tkell edited this page Sep 13, 2010 · 8 revisions

Table of contents


If you need even more control over the presentation and functionality of audio playback on your site than offered by the Flash-based SoundCloud Widget, you might be interested in using a javascript-based player in combination with the SoundCloud API. Here are a few examples based on our open-source javascript player. Feel free to extend and fork it in any way you like to fit your own needs!

Quick start

To try out the SoundCloud player, you will first need to check out the source and look at the files in the javascript directory. The player is based on jQuery and SoundManager 2, and is written as a standard jQuery plugin.

To set it up, first include all required javascript and CSS files in a normal webpage:

<link href="player.css" media="all" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="soundmanager2.js"></script>
<script type="text/javascript" src="jquery-1.3.2.min.js"></script>
<script type="text/javascript" src="player.js"></script>

Next, simply add a link to your page with the class soundcloud-player and the href attribute pointing to a track permalink on SoundCloud (The track needs to have the option “128kbs version is downloadable” for it to be accessible through the API), like so:

<a class="soundcloud-player" href="">Play</a>

Now you need to add a bit of initialization code:

soundManager.flashVersion = 9;
soundManager.debugMode = false;
soundManager.defaultOptions.multiShot = false;
soundManager.url = "";

$(function() {

Most of the code above has to do with the initialization of SoundManager 2. First we set flashVersion to use the Actionscript 3 version, which performs better but requires Flash 9 to be installed. Then we set debugMode and defaultOptions.multiShot to false. We are using a re-compiled version of the SoundManager 2 swf file that is more liberal for cross domain use (read more about that here), we enabled it by setting url. You can also use the one bundled with SoundManager 2, but then you need to host javascripts and the swf file on the same domain.

Finally, we use jQuery’s ready event to initialize the player as soon as the DOM has loaded completely.

If everything goes well, you should now see something like this:


You can click the player above to see how it works. Now that was easy!


The player has a very simple structure, and can easily be customized by simply changing the default CSS file, the controls.png image sprite, and by adding parameters to the plugin initialization. For now the plugin supports three, width, collapse and autoplay.

Custom width

    $("a.soundcloud-player#custom-width").scPlayer({width: 600});


Blue player with custom CSS


    div#custom-css {
      background-color: #8cbfea;
      color: #0a2f4e;

    #custom-css .progress {
      background-color: #71a0c8;

    #custom-css .loading {
      background-color: #244b6c;

    #custom-css .controls, a#custom-css {
      background-image: url(controls-blue.png);


Large pink player with custom CSS, width and height

$("a.soundcloud-player#custom-size").scPlayer({width: "100%",collapse:false});

    div#custom-size {
      background-color: #f88aff;
      height: 45px;
      font-family: Georgia, serif;
      font-size: 32px;
      color: #a02062;

    #custom-size .progress {
      background-color: #e55bee;
      height: 44px;

    #custom-size .progress-bar {
      height: 45px;

    #custom-size .loading {
      background-color: #a02062;

    #custom-size a {
      color: #a02062;

    #custom-size .metadata {
      left: 50px;

    #custom-size .controls, a#custom-size {
      background-image: url(controls-large-pink.png);
      width: 40px;
      height: 40px;

    #custom-size.playing > a {
      background-position: -40px 0;



$("a.soundcloud-player#custom-size").scPlayer({autoplay: true});

No example given for autoplay


This code is licensed under the Apache License, Version 2. The ALv2 is a free software license. It neither forces you to redistribute your code under the license itself nor does it force you to open your code in any other way. As always feel free to contact me if there are any obscurities concerning licensing.


  • 24th October, 2009 Update to use SoundCloud’s API resource resolver for future compatibility with the API
  • 29th September, 2009 Update to latest soundmanager, and auto-stop of players when having multiple players on one page
  • 5th March, 2009 Launch of first player version
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.