7/16/2019 Docs - Custom Player - SoundCloud Developers

http://slidepdf.com/reader/full/docs-custom-player-soundcloud-developers 1/3

26/05/13 Docs - Custom Player - SoundCloud Developers

developers.soundcloud.com/docs/custom-player# 1/3

Developers

Documentation

Blog

Support

Your Apps

Custom Player

Quick start

Examples

Initialization

Options

Events

Customization

SoundCloud Custom Player

This plugin allows you to create easily customizable, HTML/CSS/JS based audio players. It uses jQuery together with the official SoundCloud Flash widget for the audio

streaming and widget JS API for its control.

Quick start

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

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.

Initialization

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>

7/16/2019 Docs - Custom Player - SoundCloud Developers

http://slidepdf.com/reader/full/docs-custom-player-soundcloud-developers 2/3

26/05/13 Docs - Custom Player - SoundCloud Developers

developers.soundcloud.com/docs/custom-player# 2/3

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();

};

or 

$.scPlayer.defaults.onDomReady = null;

Also, you can initialize your players manually:

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

or:

$('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'));

Options

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:

<a class="sc-player special" href="http://soundcloud.com/sarahweis/special">Special player</a>

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

7/16/2019 Docs - Custom Player - SoundCloud Developers

http://slidepdf.com/reader/full/docs-custom-player-soundcloud-developers 3/3

26/05/13 Docs - Custom Player - SoundCloud Developers

developers.soundcloud.com/docs/custom-player# 3/3

});

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

http://soundcloud.com/you/apps/new.

$('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;

Events

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

});

onPlayerPause.scPlayer gets triggered when the player stops playing

$(document).bind('onPlayerPause.scPlayer', function(event){

console.log(event.target, 'it stopped!');

});

onPlayerTrackSwitch.scPlayergets 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.

Customization

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.

Help us improve our developer resources: I always wanted...  Send Feedback 

HTTP/1.1 200 OK. Thank you for your feedback! Got more?

API Terms of Use

Status

App Gallery

SoundCloudAPI