SoundCloud Custom Player

The player setup is relatively easy: Download the CSS and JS files for the sc-player here:

http://github.com/soundcloud/soundcloud-custom-player/archives/master

First, add the player css files in the 'head' tag of your page source:

<link rel="stylesheet" href="../css/sc-player-standard.css" type="text/css">

Then add the script tags at the end of your 'body' tag (in case you're already using jQuery on your site, skip the first script tag):

<script type="text/javascript" src="http://code.jquery.com/jquery.js"></script>
<script type="text/javascript" src="../js/soundcloud.player.api.js"></script>
<script type="text/javascript" src="../js/sc-player.js"></script>

And now let's create a player! Put this into you HTML code:

<a href="http://soundcloud.com/matas/hobnotropic" class="sc-player">My new dub track</a>

Now reload your page, and instead of the link you should see a cool new widget.

Note: when you're doing the test, please make sure you're running it on the local or remote web-server (http://localhost, 127.0.0.1/testpage, yoursite.com, etc.) Only then can you be sure that the Flash component will be initialized correctly and the track will actually play. If you're still experiencing problems, verify that the links to JS files are correct. Also make sure you're using an url of an existing track :)

Per default the player works in 'zero-config' mode. It means, you don't need to change or write any JavaScript to get a working player on your site. More advanced techniques are shown in the following chapters.

Examples of the default skins:

• Standard skin
• Artwork skin
• Minimal skin
• Red skin

If you've created your own player skin you want to share with the others, send us the css and images (or links to the examples), and we'll list it here.

Basic use

Of course, the player supports track sets:

<a href="http://soundcloud.com/forss/sets/soulhack" class="sc-player">Soulhack</a>

And user's tracks:

<a href="http://soundcloud.com/matas" class="sc-player">My latest tracks</a>

And groups:

<a href="http://soundcloud.com/groups/field-recordings" class="sc-player">Field recordings from around the world</a>

And even user's favorites:

<a href="http://soundcloud.com/hannes/favorites" class="sc-player">Hannes favorites</a>

Or you can even build your own playlist:

<div class="sc-player">
  <a href="http://soundcloud.com/matas/hobnotropic">My dub track</a>
  <a href="http://soundcloud.com/van-rivers/lykke-li-im-good-im-gone-van-rivers-the-subliminal-kid-remix">Lykke Li remix</a>
  <a href="http://soundcloud.com/forss/forss-vs-borg-deadline-live-in-milan-2004">Forss live</a>
  <a href="http://soundcloud.com/max-richter/wwb-the-haunted-ocean-1">Max Richter: The Haunted Ocean 1</a>
</div>

Advanced use

By default the players will be initialized on page load once the DOM is available with the following method:

$('a.sc-player, div.sc-player').scPlayer();

You could adjust it or disable it completely if you plan to render the player e.g. only after certain user interaction: To do that, you should replace the default method $.scPlayer.defaults.onDomReady with your own method, or just set it to null.

$.scPlayer.defaults.onDomReady = function(){
  $('a.your-link-class').scPlayer();
};

$.scPlayer.defaults.onDomReady = null;

Also, you can initialize your players manually:

$('a.your-link-class').scPlayer();

$('div.your-container-class').scPlayer();

in the latter case, please make sure the DOM node contains links to the SoundCloud tracks. Please keep in mind that any original DOM node will be replaced with the new div.sc-player

You can pass the urls directly, if you'd rather create player on the fly:

$('div.your-container-class').scPlayer({
  links: [{url: "http://soundcloud.com/matas/hobnotropic", title: "http://soundcloud.com/matas/hobnotropic"}]
});

or if you want to append it yourself:

var $myPlayer  = $.scPlayer({
  links: [{url: "http://soundcloud.com/matas/hobnotropic", title: "http://soundcloud.com/matas/hobnotropic"}]
});
$myPlayer.appendTo($('#somewhere-deep-in-the-dom'));

beforeRender this callback allows you to update the player DOM right before it's get's rendered. Useful, if you want to add a few additional elements to the GUI. If you'd rather remove some of the defaults, hiding them with CSS is a better option probably. It provides the tracks array as an argument. See the /tracks endpoint documentation for more information.

$('div.your-container-class').scPlayer({
  links: [{url: "http://soundcloud.com/matas/hobnotropic", title: "My new dub track"}],
  beforeRender  :   function(tracksData) {
    var $player = $(this);
    $player.addClass('super-player-class');
  }
});

customClass pass a custom class, if you plan to style the players individually, also the classes of the source node get passed onto generated player. Check out the 'minimal' player example for the use case.

$('div.your-special-container-class').scPlayer({
  customClass  :  'special'
});

or the same effect without JavaScript:

Special player

autoPlay start playing the first track once the player is ready, The default value is false.

$('div.your-container-class').scPlayer({
  autoPlay  :   true
});

randomize normally, the tracks in the sets and track lists will be shown in the same order as on the server, but you might want to randomize it:

$('div.your-container-class').scPlayer({
  randomize: true
});

loadArtworks how many artwork images should be preloaded in the player. The default value is 5. Adjust it according to your bandwidth/load convenience preference.

$('div.your-container-class').scPlayer({
  loadArtworks: 1
});

apiKey you might want to add your personal API key, you can get one here:

$('div.your-container-class').scPlayer({
  apiKey: 'yourApiKey'
});

Also you can override all the default options in the $.scPlayer.defaults object, for example:

$.scPlayer.defaults.apiKey = 'yourApiKey';
$.scPlayer.defaults.autoPlay = true;
$.scPlayer.defaults.randomize = true;

There are some custom events, that get triggered by the player. You could use them to update other DOM elements as well. onPlayerInit.scPlayer gets triggered when the player data was laoded and GUI finished rendering

$(document).bind('onPlayerInit.scPlayer', function(event){
  console.log(event.target, 'is ready!');
});

onPlayerPlay.scPlayer gets triggered when the player starts playing

$(document).bind('onPlayerPlay.scPlayer', function(event){
  console.log(event.target, 'it's playing!');
});

onMediaTimeUpdate.scPlayer gets triggered constantly when the player is playing, could be used to display track progress outside of the player node

$(document).bind('onMediaTimeUpdate.scPlayer', function(event){
  console.log(event.target, 'the track is at ' + event.position + ' out of ' + event.duration + ' which is ' + event.relative + ' of the total');
});

onPlayerPause.scPlayer gets triggered when the player stops playing

$(document).bind('onPlayerPause.scPlayer', function(event){
  console.log(event.target, 'it stopped!');
});

onPlayerTrackSwitch.scPlayer gets triggered when the track was switched in the player, has a track object as an argument.

$(document).bind('onPlayerTrackSwitch.scPlayer', function(event, track){
  console.log(event.target, 'it jumped to this track:', track);
});

Please let us know if there are any additional events that should be added, this list can grow for sure. Additionally, your scripts can listen to the SoundCloud JS API events, please read the event reference here.

A good starting point is take a look at the CSS files of the default skins, where you can alter the styling parameters according to your design needs. Add images as backgrounds to the GUI controls, change the colors, update the player width so that it fits into you content column, scale it so changes its orientation to vertical, change the fonts etc. To get an overview of the player's structure, please check a rendered player in Firebug (or Chrome, Safari, IE DOM inspectors) You'll see how it's build, what kind of styling classes and selectors can be used to alter the GUI. Also we encourage you to submit patches, fixes, new features or skins on Github.