When you open this page, the SoundCloud widget will load and start playing immediately.
Also, while you test drive, it's highly recommended to temporarily enable debugging by prepending the script with soundcloud.debug = true; and opening that page in Firefox with the Firebug extension enabled. This way you'll get a better idea how and when the events get fired, if the embed code is correct etc.

Important: Because of the Flash local sandbox restrictions, the API will work only on a web server. This means, you'll either need to put the following example in the folder that's accessible through a local web server (e.g. http://127.0.0.1/, http://localhost/ etc.) or upload it to a remote server.

Embed code

To be able to use the Widget API, you'll have to modify the standard embed code accordingly. First, choose a name you'll refer to the player, for example myPlayer.

These settings are mandatory. If you're using SWFObject or similar Flash HTML generators, set id to the widget identifier, and also add enable_api:true, object_id:"yourPlayerId" to the flashvars object. You shouldn't need to add a classid parameter, the generator will create it by itself in Internet Explorer.

Properties

soundcloud.version
returns a current wrapper version as a string in format major.minor, e.g. '0.1'. Minor version will keep the same API, major version changes may change the API.
soundcloud.debug
Enable event tracing to window.console by setting this property to true. The default setting is false.

Methods

The Widget API wrapper will create a global variable soundcloud.

Wrapper methods

soundcloud.addEventListener(eventName, function)
Requires 2 arguments - event type and listener function.
Add an event listener to a player, gets notified about the changes. The listener function will receive 2 arguments - widget DOM node and the data object. Please refer to the Events documentation to find out more about the data sent with particular events.

soundcloud.getPlayer(playerID)
Requires 1 argument - flash element ID. Normally it's the id attribute of the object tag and name attribute of the embed tag in HTML.
Returns a DOM object of the player, the widget methods are available. In case the embed code wasn't set up correctly, this method will throw an error indicating the reason.

var player = soundcloud.getPlayer('myPlayerId');

Widget methods

When you'll get the widget DOM object with the help of the soundcloud.getPlayer method, you'll have access to the following public methods:

api_play()
Player starts playing either from 0 or from the last paused track position. In the case the widget contains multiple tracks it will start playing the first track.

api_pause()
Player stops playing, current track position is saved.

api_stop()
Player stops playing, current track position is reset to 0.

api_toggle()
Player starts or stops playing, depending on it's current state. The current track position is saved.

api_prev()
In the case the widget contains multiple tracks it will skip to the previous track.

api_next()
In the case the widget contains multiple tracks it will skip to the next track.

api_skip(trackIndex)
In the case the widget contains multiple tracks it will jump to the trackIndex, where the track list goes 0,1,2. e.g. myPlayer.api_skip(2) will load the third track in a playlist. You can check the current trackIndex by calling myPlayer.api_getCurrentTrackIndex().

api_load(url)
Player stops playing, resets and loads a new resource from the given url. This way one widget could be used as an audio engine for the multiple SoundCloud resources. Note: after calling this method, please wait again for the onPlayerReady event! The player will not be operational until it is triggered.

api_seekTo(seconds)
Jump to a certain position in a track. Before seeking, please make sure that the track is fully buffered. The widget will trigger a onMediaDoneBuffering event when it's fully available.

api_setVolume(0..100)
Set the widget volume to a certain value.

api_getVolume()
Returns current volume, as a number between 0 and 100.

api_getCurrentTrackIndex()
Returns the index of the current track in the playlist (0 based). If the first track is playing it'll return 0, the second 1, and so on.

api_getFlashId()
Returns the id/name of the widget node in the DOM.

Did you know, that you can't use play or stop when registering callbacks through ExternalInterface.addCallback() in Flash? The Internet Explorer would throw an error on line 48 "object does not support this property". Read about it here or here

Widget events

If the player's enable_api parameter is set to true (see Embed code) the widget will trigger certain events. You can listen to these events using the soundcloud.addEventListener method. If you have access to JavaScript frameworks jQuery or Prototype in your web application, you can use the respective listener methods.

Listener arguments

The registered listener functions should expect 2 arguments:
playerDOM node
the widget DOM node that triggered this event, should be used to reference the widget especially when you have a few of them on the page.
dataObject
this object will always contain the following properties:

mediaUri String: the uri of media in Widget API that triggered the event, like 'http://api.soundcloud.com/tracks/49931'

mediaId String: the id of the media item, e.g. '49931' etc. The load events onMediaBuffering and onMediaDoneBuffering have an additional property in data:

percent Number: a percent of the current track audio stream in local buffer, from 0 to 100

These properties should help you reference the items in SoundCloud API. Let's say on onPlayerReady you get a data.mediaUri http://api.soundcloud.com/tracks/49931, then you could call it for more info etc. Check out the jQuery example in examples folder for working example code.

Event types:

onPlayerReady
Fired when the widget has loaded its data and is ready to accept external calls. Triggered only once per widget instance.

JavaScript Frameworks

The widget wrapper will automatically re-trigger every widget event into the DOM as a jQuery or Prototype event. The events are name spaced in the format 'soundcloud:eventName', e.g. 'soundcloud:onPlayerReady'.