SoundCloud Custom Player

This plugin creates customizable, HTML/CSS/JS-based audio players. It uses jQuery together with the official SoundCloud widget for audio streaming and the widget JS API for control.

Quick Start

Download the CSS and JS files for the sc-player:

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

Add the player CSS files in the head tag of the page source:

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

Add the script tags at the end of the body tag (skip the first script tag if jQuery is already loaded on the site):

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

To create a player, add this HTML:

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

Reload the page, and the link will be replaced with a player widget.

Note: The page must be served from a local or remote web server (e.g., http://localhost, 127.0.0.1/testpage, yoursite.com) for the Flash component to initialize correctly and for audio playback to work. Verify that the JS file paths are correct and that the track URL is valid.

By default, the player operates in "zero-config" mode, requiring no JavaScript changes to produce a working player. More advanced techniques are covered in the following sections.

Examples

Default skin examples:

To share a custom player skin, send the CSS and images (or links to examples) to be listed here.

Initialization

Basic Use

The player supports track sets:

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

User tracks:

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

User favorites:

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

Custom playlists:

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

Advanced Use

By default, players are initialized on page load once the DOM is available:

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

To adjust or disable automatic initialization, replace $.scPlayer.defaults.onDomReady with a custom method or set it to null:

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

$.scPlayer.defaults.onDomReady = null;

Players can also be initialized manually:

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

or:

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

In the latter case, ensure the DOM node contains links to SoundCloud tracks. Any original DOM node will be replaced with a new div.sc-player.

To create a player on the fly by passing URLs directly:

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

To append the player manually:

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

Options

beforeRender -- This callback updates the player DOM before rendering. It is useful for adding additional elements to the GUI. To remove default elements, hiding them with CSS is preferable. The callback receives the tracks array as an argument. See the /tracks endpoint documentation for more information.

$('div.your-container-class').scPlayer({
  links: [{url: "https://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 to style players individually. Classes from the source node are also passed to the generated player. See the "minimal" player example for a use case.

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

The same effect without JavaScript:

<a class="sc-player special" href="https://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 -- Randomize the order of tracks in sets and track lists (normally displayed in server order).

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

loadArtworks -- Number of artwork images to preload in the player. The default value is 5. Adjust according to bandwidth and load preferences.

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

apiKey -- Set a personal API key, obtainable at https://soundcloud.com/you/apps/new.

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

All default options can be overridden via the $.scPlayer.defaults object:

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

Events

The player triggers several custom events that can be used to update other DOM elements.

onPlayerInit.scPlayer -- Triggered when player data has loaded and GUI rendering is complete.

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

onPlayerPlay.scPlayer -- Triggered when the player starts playing.

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

onMediaTimeUpdate.scPlayer -- Triggered continuously during playback. Useful for displaying track progress outside 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 -- Triggered when the player stops playing.

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

onPlayerTrackSwitch.scPlayer -- Triggered when the track is switched, with the track object as an argument.

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

Additional events can be added as needed. Scripts can also listen to SoundCloud JS API events; see the event reference.

Customization

Start by examining the CSS files of the default skins, where styling parameters can be altered to match specific design requirements. Add images as backgrounds to GUI controls, change colors, adjust the player width to fit the content column, scale or reorient the layout, and change fonts.

To understand the player structure, inspect a rendered player using browser developer tools (Firebug, Chrome DevTools, Safari Web Inspector, or IE DOM inspector) to see the available styling classes and selectors.

Patches, fixes, new features, and skins can be submitted on GitHub.

SoundCloud for Developers

Discover, connect and build