Skip to content
This repository

The SoundCloud Custom Player

Table of contents

Introduction

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

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>

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>

Please avoid placing the initial link in the p tag, because IE will fail to render the player div in the block element and throw an ‘Unknown Runtime Error’. The solution would be to enclose the initial link in another div container. You can read more about this problem in the Rakesh Pai’s blog.

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 (check out the SoundCloud API for its contents http://wiki.github.com/soundcloud/api/102-resources-tracks)

$('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 href="http://soundcloud.com/sarahweis/special" class="sc-player 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
});

continuePlayback
start playing the next track after the previous has finished, The default value is true.

$('div.your-container-class').scPlayer({
  continuePlayback  :   false
});

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 (now called client ID), 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 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.

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 http://github.com/soundcloud/soundcloud-custom-player

Licensing

The project is published under an MIT license:

Copyright © 2010 SoundCloud Ltd.

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the “Software”), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

Something went wrong with that request. Please try again.