SDK References
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.
In this section:
- Basic Use
- Authentication
- Streaming
- Recording and Uploading
- Embedding
- Methods
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="/img/spacer.gif">
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>
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: "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("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("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 resourceparams
: (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 connectedscope
: (optional) additional OAuth2 scopes (default: "non-expiring")
SC.post(path, [params], callback)
Execute a POST request.
Parameters:
path
: the path to the requested resourceparams
: (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 resourceparams
: (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 resourcecallback
: 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 thesecret_token
parameter if given.options
: (optional) options that are passed to the soundManager2 sound object. (see soundManager2 docs). Additionally it supports anontimedcomments
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 startsprogress
: 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 docscallbackOrContainer
: either a callback function that gets the oEmbed response passed or an HTML element that will be used to place the embed.