SoundCloud for Developers

Discover, connect and build

SoundCloud Player Widget

The SoundCloud Player is customizable through URL parameters and scriptable through a JavaScript API. You'll find the JavaScript Wrapper on GitHub.

Customize Parameters

color hex code Color play button and other controls. e.g. “0066CC”
theme_color hex code Color player background etc.
text_buy_track String e.g. “Tweet” and it points to your “buy” link
text_buy_set String e.g. “Tweet” and it points to your “buy” link
text_download_track String e.g. “Get it” and it points to your “download” link
buying true/false Show/Hide buy buttons
sharing true/false Show/Hide share buttons
download true/false Show/Hide download buttons
show_bpm true/false Show/Hide bpm display in player
show_playcount true/false Show/Hide number of track plays
start_track Number A number from 0 to the playlist length. preselects a track in a playlist
default_width Number A number e.g. 400. Overrides the player’s autoscale, useful when embedding in other flash movies
default_height Number A number e.g. 500. Overrides the player’s autoscale, useful when embedding in other flash movies
font String A string e.g. “Arial”. Overrides the default font with system font
enable_api true/false Enable the JavaScript API callbacks
single_active true/false if set to false the multiple players on the page won’t toggle each other off when playing
show_user true/false Show or hide the uploader name, useful e.g. in tiny players to save space)
auto_play true/false
show_artwork true/false
show_playcount true/false
show_bpm true/false
show_comments true/false

These parameters can be added to the player URL in the embed code. Please note that the player URL is twice in the embed code and both need to be modified:

<object height="81" width="100%">
  <param name="movie"
    value="http://player.soundcloud.com/player.swf?{ ADD YOUR PARAMETERS HERE }&url=http%3A%2F%2Fapi.soundcloud.com%2Ftracks%2F293"></param>
  <param name="allowscriptaccess" value="always"></param>
  <embed
    src="http://player.soundcloud.com/player.swf?{ ADD YOUR PARAMETERS HERE }&url=http%3A%2F%2Fapi.soundcloud.com%2Ftracks%2F293"
    allowscriptaccess="always" height="81"  type="application/x-shockwave-flash" width="100%">
  </embed>
</object>

Quick start

To try out the SoundCloud Widget API, please download or check out the soundcloud.player.api.js file and put it into your scripts folder. Put the following code into your HTML head:

<script type="text/javascript" src="scripts/soundcloud.player.api.js"></script>
<script type="text/javascript">
   soundcloud.addEventListener('onPlayerReady', function(player, data) {
     player.api_play();
   });
</script>

Put the following code into your HTML body:

<object height="81" width="100%" id="yourPlayerId" classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000">
  <param name="movie" value="http://player.soundcloud.com/player.swf?url=http%3A%2F%2Fsoundcloud.com%2Fmatas%2Fhobnotropic&enable_api=true&object_id=yourPlayerId"></param>
  <param name="allowscriptaccess" value="always"></param>
  <embed allowscriptaccess="always" height="81" src="http://player.soundcloud.com/player.swf?url=http%3A%2F%2Fsoundcloud.com%2Fmatas%2Fhobnotropic&enable_api=true&object_id=yourPlayerId" type="application/x-shockwave-flash" width="100%" name="yourPlayerId"></embed>
</object>

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.

  • set the object tag id attribute to myPlayer
  • set the embed tag name attribute to myPlayer
  • add a query parameter object_id=myPlayer to a widget url
  • activate widget event callbacks by adding a query parameter enable_api=true
  • add a classid parameter to the object tag for the Internet Explorer classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
<object height="81" width="100%" id="myPlayer" classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000">
  <param name="movie" value="http://player.soundcloud.com/player.swf?url=http%3A%2F%2Fsoundcloud.com%2Fmatas%2Fhobnotropic&enable_api=true&object_id=myPlayer"></param>
  <param name="allowscriptaccess" value="always"></param>
  <embed allowscriptaccess="always" height="81" src="http://player.soundcloud.com/player.swf?url=http%3A%2F%2Fsoundcloud.com%2Fmatas%2Fhobnotropic&enable_api=true&object_id=myPlayer" type="application/x-shockwave-flash" width="100%" name="myPlayer"></embed>
</object>

Please make sure that the id and name attributes of the object and embed tags do not include the following characters: . - + * / \. read the ExternalInterface documentation

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.

var flashvars = {
  enable_api: true,
  object_id: "myPlayer",
  url: "http://soundcloud.com/forss/flickermood"
};
var params = {
  allowscriptaccess: "always"
};
var attributes = {
  id: "myPlayer",
  name: "myPlayer"
};
swfobject.embedSWF("http://player.soundcloud.com/player.swf", "myContent", "81", "100%", "9.0.0","expressInstall.swf", flashvars, params, attributes);

Also note, that allowscriptaccess attribute is set to always.

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.addEventListener('onPlayerReady', myEventHandlerFunction);

soundcloud.removeEventListener(eventName, function) Requires 2 arguments - event type and listener function.

soundcloud.removeEventListener('onPlayerReady', myEventHandlerFunction);

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_getTrackDuration() Returns current track duration in seconds.

api_getTrackPosition() Returns current track position in seconds.

api_getTracks() Returns the list of the track objects in the player

api_getCurrentTrack() Returns the current track object

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: player DOM 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. data Object 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.
soundcloud.addEventListener('onPlayerReady', function(player, data) {
  console.log('player ready');
});

onMediaStart Fired when the widget starts playing current track (fired only once per track).
soundcloud.addEventListener('onMediaStart', function(player, data) {
  console.log('track started id:' + data.mediaId);
});
onMediaPlay Fired when the widget plays current track.
soundcloud.addEventListener('onMediaPlay', function(player, data) {
  console.log('track is playing id:' + data.mediaId);
});
onMediaPause Fired when the widget stops playing current track (fired on every play, seek, toggle from pause)
soundcloud.addEventListener('onMediaPause', function(player, data) {
   console.log('track stopped at:' + player.api_getTrackPosition());
});
onMediaBuffering Fired when the widget is still buffering. data (second argument) contains property percent. It also means you can't seek in the track fully yet
soundcloud.addEventListener('onMediaBuffering', function(player, data) {
  console.log('track loading:' + data.percent + '%');
});
onMediaDoneBuffering Fired when the widget is done buffering. data (second argument) contains property percent. It also means now you can seek in the track.
soundcloud.addEventListener('onMediaDoneBuffering', function(player, data) {
  console.log('track loaded!');
  player.api_seekTo(35);
});
onMediaEnd Fired when the track finished playing.
soundcloud.addEventListener('onMediaEnd', function(player, data) {
  console.log('track finished!');
});
onMediaSeek Fired when the user seeks in the current track
soundcloud.addEventListener('onMediaSeek', function(player, data) {
  console.log('seeking in the track!');
});
onPlayerError Fired when the widget can't get the requested data from the server (the resource is removed, hidden, etc.). The widget initialization failed.
soundcloud.addEventListener('onPlayerError', function(player, data) {
  console.error('track couldn't be loaded!');
});

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'.

jQuery integration

$(document).bind('soundcloud:onPlayerReady', function(event, data) {
  var mediaUri = data.mediaUri,
    mediaId   = data.mediaId,
    flashNode = event.target;
});

Prototype integration

$(document).observe('soundcloud:onMediaPlay', function(event) {
  var mediaUri = event.memo.mediaUri,
    mediaId   = event.memo.mediaId,
    flashNode = event.target;
});

Please note the difference in the listener parameters. The event is triggered off the widget DOM node so the flash object can be accessed as event.target in listener function.