SoundCloud for Developers

Discover, connect and build

HTTP API Wrappers

The SDKs will make it easier to access the SoundCloud API on your framework of choice. We officially provide and support Ruby, Python, PHP, Java, JavaScript and Cocoa. All other SDKs are supported by third-party developers.

We welcome contributions to the open source projects so imagine how happy we'd be if you submit an SDK of your own for any additional language.

JavaScript SDK

The JavaScript SDK lets you easily integrate SoundCloud into your website or webapp.

Basic Use

To start using the SDK just add this script to your HTML and initialize the client with your own client_id and optionally your redirect_uri in case you want to use authentication:

<script src="//connect.soundcloud.com/sdk.js"></script>
<script>
  SC.initialize({
    client_id: "YOUR_CLIENT_ID",
    redirect_uri: "http://example.com/callback.html",
  });
</script>

Once that's done you are all set and ready to call the SoundCloud API. For example getting the latest track of a group:

SC.get("/groups/55517/tracks", {limit: 1}, function(tracks){
  alert("Latest track: " + tracks[0].title);
});

This docs will continue with explaining each component of the SDK and it's methods. If you are looking for fully working demos have a look at here.

Authentication

To use the authentication you have to host a callback.html file on your server and set it as the redirect_uri in your app settings and when initializing the SDK. This callback.html file needs to contain just a few lines:

<!DOCTYPE html>
<html lang="en">
  <head><meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <title>Connect with SoundCloud</title>
  </head>
  <body onload="window.opener.setTimeout(window.opener.SC.connectCallback, 1)">
    <b style="width: 100%; text-align: center;">This popup should automatically close in a few seconds</b>
  </body>
</html>

The connect flow is triggered by the SC.connect method. Once authenticated and authorized your app you can use the methods SC.post, SC.put and SC.delete to do things like creating comments, favoriting a track or updating a users profile. This example will automatically create a following once a user is connected:

SC.initialize({
  client_id: "YOUR_CLIENT_ID",
  redirect_uri: "http://example.com/callback.html",
});

SC.connect(function(){
  SC.put("/me/followings/3207", function(user, error){
    if(error){
      alert("Error: " + error.message);
    }else{
      alert("You are now following " + user.username);
    }
  });
});

Relevant methods: SC.connect, SC.post, SC.put, SC.delete

Streaming

The streaming of the SDK is powered by the soundManager2 library. If soundManager2 isn't already present it will be loaded by the SDK.

SC.stream("/tracks/293", function(sound){
  sound.play();
});

The SC.stream method will prepare a soundManager2 sound object for the passed track. The soundObject object provides all soundManager2 sound properties and methods like play(), stop(), pause(), setVolume(), etc.

The options can include an ontimedcomments callback, that will be called for each timed comment group while the track is playing. For example:

SC.stream("/tracks/293", {
  autoPlay: true,
  ontimedcomments: function(comments){
    console.log(comments[0].body);
  }
});

Relevant methods: SC.stream, SC.whenStreamingReady

Recording and Uploading

The Recording component requires Adobe Flash 10 and currently does not support mobile browsers. This example will record 5 seconds and play it back right away:

SC.record({
  start: function(){
    window.setTimeout(function(){
      SC.recordPlay();
    }, 5000);
  }
});

Have a look at this demo for a full working example including a full UI and the uploading of a track.

Relevant methods: SC.record, SC.recordStop, SC.recordPlay, SC.recordUpload

Embedding

The SC.oEmbed() function is a wrapper for the SoundCloud oEmbed endpoint.

It takes the URL you want to embed as an argument, an optional options object and either a callback function or an element which content will be replaced by the embed code. All properties from the options object will be passed as parameters to the oEmbed endpoint. For example maxwidth, maxheight, auto_play and color. The options are described in detail in the oEmbed documentation.

<script>
  SC.oEmbed("http://soundcloud.com/forss/flickermood", {auto_play: true}, function(oembed){
    console.log("oEmbed response: ", oembed);
  });
</script>

Or:

<div id="putTheWidgetHere"></div>
<script type="text/JavaScript">
  SC.oEmbed("http://soundcloud.com/forss/sets/soulhack", {color: "ff0066"},  document.getElementById("putTheWidgetHere"));
</script>

Relevant methods: SC.oEmbed

Methods

SC.get(path, [params], callback)

Execute a GET request.

Parameters:

  • path: the path to the requested resource
  • params: (optional) an object of additional parameters to pass in the request.
  • callback: a function to be called when request finished. Passes response object and error object.

SC.connect(options)

Initiate the OAuth2 connect flow.

Parameters:

  • options:
    • redirect_uri: the redirect URI as defined in your app settings.
    • connect: a callback function to be called once connected
    • scope: (optional) additional OAuth2 scopes (default: "non-expiring")

SC.post(path, [params], callback)

Execute a POST request.

Parameters:

  • path: the path to the requested resource
  • params: (optional) an object of additional parameters to pass in the request.
  • callback: a function to be called when request finished. Passes response object and error object.

SC.put(path, [params], callback)

Execute a PUT request.

Parameters:

  • path: the path to the requested resource
  • params: (optional) an object of additional parameters to pass in the request.
  • callback: a function to be called when request finished. Passes response object and error object.

SC.delete(path, callback)

Execute a DELETE request.

Parameters:

  • path: the path to the requested resource
  • callback: a function to be called when request finished. Passes response object and error object.

SC.whenStreamingReady(callback)

Will call the callback as soon as the streaming componenent (soundManager2) is ready.

Parameters:

  • callback: a callback function to be called when Streaming component is ready.

SC.stream(trackPath, [options], [callback])

Prepares and returns a soundManager2 sound object.

Parameters:

  • trackPath: a path of the track to be streamed. Will pass the secret_token parameter if given.
  • options: (optional) options that are passed to the soundManager2 sound object. (see soundManager2 docs). Additionally it supports an ontimedcomments callback that will be called for each timed comment group while the track is playing.
  • callback: (optional) a function to be called when the sound object is ready. Passes the sound object as an argument.

SC.record(options)

Will show a flash permission dialog to access the microphone and start recording.

Parameters:

  • options:
  • start: a function to be called when recording actually starts
  • progress: a function to be called frequently while recording. Passes milliseconds and average Peak data as arguments.

SC.recordStop

Stops the current recording or playback.

SC.recordPlay(options)

Prepares and returns a soundManager2 sound object.

Parameters:

  • options:
  • progress: a function to be called frequently while playing. Passes milliseconds as argument.
  • finished: a function to be called when playback has finished.

SC.recordUpload(options)

Uploads the recorded track to SoundCloud.

Parameters:

  • options:
    • params: additional request parameters. For example: {track: {title: "Track Title"}}
    • success: a function to be called when uploading succeeded. Passes response object and error object.

SC.oEmbed(url, [params], callbackOrContainer)

Will lookup the embed code for the passed URL (track, group, set or user) using oEmbed, passes additional params and either calls the callback function or places the embed into the container.

Parameters:

  • url: a URL to a track, group, set or user on SoundCloud.
  • params: (optional) additional parameters for oEmbed. See oEmbed docs
  • callbackOrContainer: either a callback function that gets the oEmbed response passed or an HTML element that will be used to place the embed.