HTTP API Guide

Using the SoundCloud API, you can build applications that take sound on the web to the next level. With this guide we explain and provide code examples for many common integration use cases like playing and uploading sounds or how to take advantage of SoundCloud's many social features. If you're looking for more in depth information, feel free to jump to our API Reference.

To help you get started quickly, SDKs are available for Python, Ruby, JavaScript. To follow along with the examples below, you'll need to have at least one SDK installed.

Now go ahead and jump to the section you're most interested in and get started.

Authentication

This section presumes you have:

Registered your App

Our API allows you to get permission from a SoundCloud user to access SoundCloud on their behalf. This means that you will have access to their account, including any private sounds or sets that they have created or have had shared with them. You can also use SoundCloud for your app's registration and sign-in process. This creates a seamless, one click experience for your users and give your app an easy way to upload sounds, make comments or otherwise act on a user's behalf.

SoundCloud authentication uses OAuth 2.0, a popular open standard used by many popular API providers. OAuth 2.0 allows users to authorize your application without disclosing their username and password.

There are different ways to authenticate with OAuth, depending on the type of application you're building. You can also simplify your login process by using the Connect with SoundCloud buttons as your apps login system.

In this section:

Sign in with SoundCloud
Client-side JavaScript Applications
Server-side Web Applications
Mobile and Desktop Applications
Getting Information about Authenticated User
Authenticating without the SoundCloud Connect Screen
Refreshing Tokens

Sign in with SoundCloud

You can simplify your registration and sign in process by using a Connect with SoundCloud button. This lets your user know that they can register for your app with one click using their SoundCloud account. It also grants your app access to their account and gives you the ability to upload tracks, create sets and otherwise act on their behalf.

Client-side JavaScript Applications

If you are writing an application that runs in the browser, you should use the JavaScript SDK SC.connect() method to authenticate your app.

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

// initiate auth popup
SC.connect().then(function() {
  return SC.get('/me');
}).then(function(me) {
  alert('Hello, ' + me.username);
});
</script>

A pop-up window will be opened allowing the user to log in to SoundCloud and approve your app's authorization request. You'll have to host the callback.html file on your server and set the redirect_uri in your app settings accordingly.

Try out the Client-side auth flow

Server-side Web Applications

To authenticate your server-side web application using one of our SDKs, create an instance of the Soundcloud class with the API credentials you obtained when you registered your app and redirect the user to the authorization URL so that they can log in and approve your request.

require 'soundcloud'

# create client object with app credentials
client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID',
                        :client_secret => 'YOUR_CLIENT_SECRET',
                        :redirect_uri => 'https://example.com/callback')

# redirect user to authorize URL
redirect_to client.authorize_url()
import soundcloud

# create client object with app credentials
client = soundcloud.Client(client_id='YOUR_CLIENT_ID',
                           client_secret='YOUR_CLIENT_SECRET',
                           redirect_uri='https://example.com/callback')

# redirect user to authorize URL
redirect client.authorize_url()
// this example is not applicable to the JavaScript SDK

The user will be redirected to a SoundCloud connect screen and asked to authorize your application. If the user is already signed into SoundCloud, they will be able to authorize your request in one click.

Users of your app will be redirected to the SoundCloud Connect screen.

If the user approves your authorization request, they will be sent to the redirect_uri you specified when registering your app. Extract the code parameter from the query string and use it to obtain an access token.

require 'soundcloud'

# create client object with app credentials
client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID',
                        :client_secret => 'YOUR_CLIENT_SECRET',
                        :redirect_uri => 'https://example.com/callback')

# exchange authorization code for access token
code = params[:code]
access_token = client.exchange_token(:code => code)
import soundcloud

# create client object with app credentials
client = soundcloud.Client(client_id='YOUR_CLIENT_ID',
                           client_secret='YOUR_CLIENT_SECRET',
                           redirect_uri='https://example.com/callback')

# exchange authorization code for access token
code = params['code']
access_token = client.exchange_token(code)
// this example is not applicable to the JavaScript SDK

You should now store the access token in a database. Associate it with the user it belongs to and use it from now on instead of sending the user through the authorization flow. The returned object will have an access_token property and a refresh_token property as well as expires_in and scope.

require 'soundcloud'

# create client object with access token
client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN')

# make an authenticated call
current_user = client.get('/me')
puts current_user.username
import soundcloud

# create client object with access token
client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN')

# make an authenticated call
current_user = client.get('/me')
print current_user.username
// this example is not applicable to the JavaScript SDK

Refreshing Tokens

You will need to periodically refresh your access tokens when they expire:

require 'soundcloud'

# create client object with app credentials and refresh token
client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID',
                        :client_secret => 'YOUR_CLIENT_SECRET',
                        :refresh_token => 'SOME_REFRESH_TOKEN')

# the client can now be used to make authenticated API calls
puts client.get('/me').username
import soundcloud

# create client object with app credentials and refresh token
client = Soundcloud.new(client_id='YOUR_CLIENT_ID',
                        client_secret='YOUR_CLIENT_SECRET',
                        refresh_token='SOME_REFRESH_TOKEN')

# the client can now be used to make authenticated API calls
print client.get('/me').username
// this example is not applicable to the JavaScript SDK

Mobile and Desktop Applications

You authenticate Mobile and Desktop Applications the same way you do for Server-side Web Applications. To make the flow smoother, you can use a redirect_uri with a custom protocol scheme and set your app as a handler for that protocol scheme. For example, your redirect_uri could be something like my-app://soundcloud/callback.

When building apps for mobile devices, we recommend using our mobile optimized connect screen by setting display=popup in the authorization URL query string.

Mobile optimized connect screen.

Getting Information about the Authenticated User

Once the user has signed into SoundCloud and approved your app's authorization request, you will be able to access their profile and act on their behalf. We have provided a convenient endpoint for accessing information about the authenticated user.

require 'soundcloud'

# create a client object with access token
client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN')

# print out the user's username
puts client.get('/me').username

# update the user's profile description
user = client.post('/me', :description => 'I am using the SoundCloud API!')
puts user.description
import soundcloud

# create a client object with access token
client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN')

# print out the user's username
print client.get('/me').username

# update the user's profile description
user = client.post('/me', description='I am using the SoundCloud API!')
print user.description
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://example.com/callback'
});

// update user's profile description
SC.connect().then(function() {
   SC.put('/me', {
     user: { description: 'I am using the SoundCloud API!' }
   });
});
</script>

Authenticating without the SoundCloud Connect Screen

If you simply need an access token for testing, and do not want to go through the connect flow, or if you have one central account your app needs to access, you can use the OAuth User Credentials Flow. An example of this kind of app would be an artist's website where you'll only be using a single SoundCloud account for the artists sets, user information and sounds. In these cases you may exchange a set of user credentials for an access token.

Do not use this if you intend for users to access their SoundCloud accounts from your app. Because this authorization flow depends on passing a set of user credentials, it is inaccessible for anyone who has used Facebook Connect to create their SoundCloud account. It is also a bad practice to require users to give your app their user credentials. If you intend to upload sounds from different users, you must use a more appropriate authentication flow, such as the ones explained above.

Our Terms of Service specify that you must use the Connect with SoundCloud screen unless you have made a separate arrangement with us.

require 'soundcloud'

# create client object with app and user credentials
client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID',
                        :client_secret => 'YOUR_CLIENT_SECRET',
                        :username => 'YOUR_USERNAME',
                        :password => 'YOUR_PASSWORD')

# print authenticated user's username
puts client.get('/me').username
import soundcloud

# create client object with app and user credentials
client = soundcloud.Client(client_id='YOUR_CLIENT_ID',
                           client_secret='YOUR_CLIENT_SECRET',
                           username='YOUR_USERNAME',
                           password='YOUR_PASSWORD')

# print authenticated user's username
print client.get('/me').username
// this example is not supported by the JavaScript SDK

Uploading Sounds

This section presumes you have:

Sounds (in the API these are called tracks) are core to SoundCloud. Our API gives you the ability to upload, manage and share sounds on the web. Your app can take an audio file and upload it to a user's SoundCloud account. You can also manage metadata (including tags), share the sound on other social networks, or add the sound to playlists. We support the following formats: AIFF, WAVE, FLAC, OGG, MP2, MP3, AAC, AMR and WMA.

In this section:

Uploading Audio Files
Updating Metadata
Sharing Sounds to other Social Networks
Creating Sets
Adding Sounds to a Set
Accessing Sets

Uploading Audio Files

To upload a sound, send a POST request with a multipart/form-data media type to the /tracks endpoint. This is done with one of our SDKs using the post method and passing information about the track being uploaded.

Request bodies for track uploads via the API may not be larger than 500MB.

require 'soundcloud'

# create a client object with access token
client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN')

# upload an audio file
track = client.post('/tracks', :track => {
  :title => 'This is my sound',
  :asset_data => File.new('file.mp3', 'rb')
})

# print track link
puts track.permalink_url
import soundcloud

# create a client object with access token
client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN')

# upload audio file
track = client.post('/tracks', track={
    'title': 'This is my sound',
    'asset_data': open('file.mp3', 'rb')
})

# print track link
print track.permalink_url
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>

// When you have recorded a song with the SDK or any Web Audio application,
// you can upload it if it's in a format that is accepted
SC.upload({
  file: theBlob, // a Blob of your WAV, MP3...
  title: 'This is my sound'
});
</script>

If successful, your track will immediately be queued up for encoding. You check the state property of the track resource to check its progress. Once the state is finished it is ready to be embedded or streamed.

See also:

/tracks endpoint reference documentation.
Desktop sharing kits.
iOS sharing kit.
Android sharing kit.

Updating Metadata

In order to update a sounds metadata, you create a client and call the put method, passing in the path of the track resource and the properties you want to update.

You can update the track artwork using the artwork_data parameter. Please note that at this time it is not possible to update the actual track audio file.

For a full list of properties that can be set on a sound resource, see the /tracks endpoint reference.

require 'soundcloud'

# create a client object with access token
client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN')

# fetch a track by it's ID
track = client.get('/tracks/290')

# update the track's metadata
client.put(track.uri, :track => {
  :description => 'This track was recorded in Berlin',
  :genre => 'Electronic',
  :artwork_data => File.new('artwork.jpg', 'rb')
})
import soundcloud

# create a client object with access token
client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN')

# fetch a track by it's ID
track = client.get('/tracks/290')

# update the track's metadata
client.put(track.uri, track={
  'description': 'This track was recorded in Berlin',
  'genre': 'Electronic',
  'artwork_data': open('artwork.jpg', 'rb')
})
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://example.com/callback'
});

var getTracks = function() { return SC.get('/me/tracks'); };

// connect and update track data
SC.connect().then(getTracks).then(function(tracks){
  SC.put('/tracks' + tracks[0].id, {
    track: {
      description: 'This track was recorded in Berlin',
      genre: 'Electronic'
    }
  });
});
</script>

SoundCloud accounts can be connected to accounts on Twitter, Facebook, Foursquare and Tumblr to allow easy sharing of tracks and favorites. On every public track your app uploads, you can choose to share it to one of the connected social networks.

A list of networks that a user has connected to their account is available using the /me/connections endpoint. You can create new connections, and use existing connections to share tracks and playlists using our API.

require 'soundcloud'

# create a client object with access token
client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN')

# get a list of connected social networks
connections = client.get('/me/connections')

# print out connection details
connections.each do |connection|
  puts "Connection type: #{connection.type}"
  puts "Favorites are posted to this network" if connection.post_favorite
  puts "New tracks and playlists are shared" if connection.post_publish
end
import soundcloud

# create a client object with access token
client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN')

# get a list of connected social networks
connections = client.get('/me/connections')

# print out connection details
for connection in connections:
    print "Connection type: %s" % connection.type
    if connection.post_favorite:
        print "Favorites are posted to this network"
    if connection.post_publish:
        print "New sounds and sets are shared"
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://example.com/callback'
});

// list connected social networks
SC.connect().then(function() {
  SC.get('/me/connections').then(function(connection) {
    alert('Connection id: ' + connection.id);
  });
});
</script>

When you upload new sounds or create a new set, you can automatically share to Twitter, Facebook or any other network connected to your apps users SoundCloud account.

require 'soundcloud'

# create a client object with access token
client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN')

# get 'twitter' connection
connection = client.get('/me/connections').find { |c| c.type == 'twitter' }

# upload new track and share it on twitter
track = client.post('/tracks', :track => {
  :title        => 'This is my new sound',
  :asset_data   => File.new('audio.mp3', 'rb'),
  :shared_to    => {
    :connections => [{:id => connection.id}]
  }
})
import soundcloud

# create a client object with access token
client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN')

# get 'twitter' connection
connection = [c for c in client.get('/me/connections')
              if c.type == 'twitter'][0]

# upload new track and share it on twitter
track = client.post('/tracks', track={
    'title': 'This is my new sound',
    'asset_data': open('audio.mp3', 'rb'),
    'shared_to': [{'id': connection.id}]
})
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://example.com/callback'
});

var recorder = new SC.Recorder();
var startRecording = function () {
  recorder.start();
  setTimeout(stopRecordingAndUpload, 5000);
};

var stopRecordingAndUpload = function () {
  recorder.stop();
  recorder.getWAV().then(function(wav){
    SC.upload({
      file: wav,
      title: 'track' + Date.now(),
      connections: [ { id: 123 } ] // the desired connection to share to
    });
  });
};

SC.connect().then(startRecording);
</script>

You can also share an existing track or playlist.

require 'soundcloud'

# create a client object with access token
client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN')

# get 'twitter' connection
connection = client.get('/me/connections').find { |c| c.type == 'twitter' }

# share sound on twitter
client.post("/tracks/#{track.id}/shared-to/connections",
  :connections => [{:id => connection.id}],
  :sharing-note => 'Check out my new sound'
)
import soundcloud

# create a client object with access token
client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN')

# get 'twitter' connection
connection = [c for c in client.get('/me/connections')
              if c.type == 'twitter'][0]

# share sound on twitter
client.post("/tracks/#{track.id}/shared-to/connections",
  connections=[{'id': connection.id}],
  sharing-note='Check out my new sound'
)
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://example.com/callback'
});

var getConnections = function () { return SC.get('/me/connections'); };

SC.connect().then(getConnections).then(function(connections){
  SC.post('/tracks/THE_TRACK_ID/shared-to/connections', {
    connections: [ { id: connections[0].id } ],
    sharing-note: 'Check out my new sound'
  });
});
</script>

See also:

/tracks endpoint reference documentation
/me/connections endpoint reference documentation
Desktop sharing kits
iOS sharing kit
Android sharing kit

Creating Sets

Sets (in the API these are called playlists) allow you to organize sounds into groups that can be shared together. For example, songs in an album or a specific collection of sounds can be grouped together using a set and then shared to the world. You can only add sounds that you own to a set and a sound can belong to multiple sets.

You create sets using our API by creating a client and calling the post method with the /playlists endpoint and information about the set, including a list of track ids.

require 'soundcloud'

# create a client object with access token
client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN')

# create an array of track ids
tracks = [290, 291, 292].map { |id| {:id => id} }

# create the playlist
client.post('/playlists', :playlist => {
  :title => 'My new album',
  :sharing => 'public',
  :tracks => tracks
})
import soundcloud

# create a client object with access token
client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN')

# create an array of track ids
tracks = map(lambda id: dict(id=id), [290, 291, 292])

# create the playlist
client.post('/playlists', playlist={
    'title': 'My new album',
    'sharing': 'public',
    'tracks': tracks
})
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://example.com/callback'
});

var tracks = [{id: 290}, {id: 291}, {id: 292}];

SC.connect().then(function() {
  SC.post('/playlists', {
    playlist: { title: 'My Playlist', tracks: tracks }
  });
});
</script>

Adding Sounds to a Set

Once a set has been created, you can continue to add sounds to it by updating the tracks property.

require 'soundcloud'

# create a client object with access token
client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN')

# create an array of track ids
tracks = [290, 291, 292].map { |id| {:id => id} }

# get playlist
playlist = client.get('/me/playlists').first

# add tracks to playlist
client.put(playlist.uri, :playlist => {
  :tracks => tracks
})
import soundcloud

# create a client object with access token
client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN')

# create an array of track ids
tracks = map(lambda id: dict(id=id), [290, 291, 292])

# get playlist
playlist = client.get('/me/playlists')[0]

# add tracks to playlist
client.put(playlist.uri, playlist={
    'tracks': tracks
})
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://example.com/callback'
});

var tracks = [{id: 290}, {id: 291}, {id: 292}];

var getFirstPlaylist = function() {
  return SC.get('/me/playlists', { limit: 1 });
};
var addTracks = function(playlists) {
  return SC.put('/playlists/' + playlists[0].id, {
    playlist: { tracks: tracks }
  });
};

SC.connect().then(getFirstPlaylist).then(addTracks);
</script>

Accessing Sets

To get a list of tracks in a set, send a GET request to the /playlists endpoint with the set id.

require 'soundcloud'

# create a client object with access token
client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN')

# get playlist
playlist = client.get('/playlists/2050462')

# list tracks in playlist
playlist.tracks.each do |track|
  puts track.title
end
import soundcloud

# create a client object with access token
client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN')

# get playlist
playlist = client.get('/playlists/2050462')

# list tracks in playlist
for track in playlist.tracks:
    print track['title']
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID'
});

SC.get('/playlists/2050462').then(function(playlist) {
  playlist.tracks.forEach(function(track) {
    console.log(track.title);
  });
});
</script>

See also:

/playlists endpoint reference documentation.

Playing Sounds

This section presumes you have:

Registered your App

Yep, you can also play sounds from your application. Depending on your needs, you can embed a player widget, use the JavaScript SDK to stream audio content in the browser, or feed a stream url into your own audio player. You can also use our Widget API to control the player and handle events.

In this section:

Embedding the SoundCloud Widget
Streaming Sounds

Embedding a SoundCloud Widget

If you have the URL of a sound or set, you can get the embed code and paste it into your website. You can also do this in your application using the oEmbed endpoint. Given a sound or set URL, you can retrieve all of the information you need to embed a player.

The JavaScript SDK has a shortcut for embedding a player widget. In order to embed a player widget using the JavaScript SDK, you can call the SC.oEmbed() function, passing in the track or playlist URL and any options for the player. For full details, see our oEmbed reference.

require 'soundcloud'

# create a client object with your app credentials
client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID')

# get a tracks oembed data
track_url = 'https://soundcloud.com/forss/flickermood'
embed_info = client.get('/oembed', :url => track_url)

# print the html for the player widget
puts embed_info['html']
import soundcloud

# create a client object with your app credentials
client = soundcloud.Client(client_id='YOUR_CLIENT_ID')

# get a tracks oembed data
track_url = 'https://soundcloud.com/forss/flickermood'
embed_info = client.get('/oembed', url=track_url)

# print the html for the player widget
print embed_info['html']
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID'
});

var track_url = 'https://soundcloud.com/forss/flickermood';
SC.oEmbed(track_url, { auto_play: true }).then(function(oEmbed) {
  console.log('oEmbed response: ', oEmbed);
});
</script>

Example SoundCloud Widget

Streaming Sounds

Note if you are going to stream from our API you need to attribute properly. Make sure you've read our Terms and Attribution Guidelines to make sure you treat our creators content correctly. When using a custom player you must:

Credit the uploader as the creator of the sound
Credit SoundCloud as the source by including one of the logos found here
Link to the SoundCloud URL containing the work
If the sound is private link to the profile of the creator

If you don't want to use the SoundCloud widget, our API gives you the ability to access a sound's stream URL and use your own player to play sounds from SoundCloud. In order to get a URL for streaming a sound, you can request the appropriate resource and make note of the stream_url property. Send a GET request to that URL and you will get a 302 - Found redirect, which you can intercept by passing allow_redirects=False to the get method.

Note that as long as the sound is public, you'll only need to provide a client_id when creating a client. If you would like to access the stream URL for a private sound, you'll need to authenticate your app.

require 'soundcloud'

# create a client object with your app credentials
client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID')

# fetch track to stream
track = client.get('/tracks/293')

# get the tracks streaming URL
stream_url = client.get(track.stream_url, :allow_redirects => true)

# print the tracks stream URL
puts stream_url.location
import soundcloud

# create a client object with your app credentials
client = soundcloud.Client(client_id='YOUR_CLIENT_ID')

# fetch track to stream
track = client.get('/tracks/293')

# get the tracks streaming URL
stream_url = client.get(track.stream_url, allow_redirects=False)

# print the tracks stream URL
print stream_url.location
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID'
});

// stream track id 293
SC.stream('/tracks/293').then(function(player){
  player.play().then(function(){
    console.log('Playback started!');
  }).catch(function(e){
    console.error('Playback rejected. Try calling play() from a user interaction.', e);
  });
});
</script>

See also:

/oembed endpoint reference documentation.
HTML5 Widget API.
JavaScript SDK Streaming.
/tracks endpoint reference documentation.

Comments

This section presumes you have:

SoundCloud has many social features that make it easier to collaborate, share and get feedback. The primary way that SoundCloud users interact is by leaving comments on each other's sounds.

Our API allows you to leave comments on sounds by calling the post method with the /tracks/{TRACK_ID}/comments path and information about the comment. Include the timestamp to make it a timed comment.

Note that you cannot leave comments on sounds if the creator has disabled comments.

require 'soundcloud'

# create a client object with access token
client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN')

# get the latest track from authenticated user
track = client.get('/me/tracks', :limit => 1).first

# create a new timed comment
comment = client.post("/tracks/#{track.id}/comments", :comment => {
  :body => 'This is a timed comment',
  :timestamp => 1500
})
import soundcloud

# create a client object with access token
client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN')

# get the latest track from authenticated user
track = client.get('/me/tracks', limit=1)[0]

# create a new timed comment
comment = client.post('/tracks/%d/comments' % track.id, comment={
    'body': 'This is a timed comment',
    'timestamp': 1500
})
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://example.com/callback'
});

var commentOnTrack = function(tracks) {
  SC.post('/tracks/' + tracks[0].id + '/comments', {
    comment: { body: 'This is a timed comment', timestamp: 1500 }
  });
};

SC.connect().then(function() {
  SC.get('/me/tracks', { limit: 1 }).then(commentOnTrack);
});
</script>

Note that the timestamp value is in milliseconds and represents the amount of time from the beginning of the sound. If you omit the timestamp, the comment will be a non-timed comment.

You can also get a list of comments for a specified sound.

require 'soundcloud'

# create a client object with access token
client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN')

# get the latest track from authenticated user
track = client.get('/me/tracks', :limit => 1).first

# get a list of comments for the track
comments = client.get("/tracks/#{track.id}/comments")

# print out each comment
comments.each { |comment| puts comment.body }
import soundcloud

# create a client object with access token
client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN')

# get the latest track from authenticated user
track = client.get('/me/tracks', limit=1)[0]

# get a list of comments for the track
comments = client.get('/tracks/%d/comments' % track.id)

# print out each comment
for comment in comments:
    print comment.body
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://example.com/callback'
});

var getTracks = function () {
  return SC.get('/me/tracks', { limit: 1 });
};

var getComments = function (tracks) {
  return SC.get('/tracks/' + tracks[0].id + '/comments');
};

var listComments = function (comments) {
  comments.forEach(function(comment){
    console.log(comment.body)
  })
};

SC.connect().then(getTracks).then(getComments).then(listComments);
</script>

See also:

/tracks endpoint reference documentation.

Follow & Like

This section presumes you have:

Your application can take advantage of SoundCloud's social features by allowing users to follow other users and like sounds or sets. Following and liking allows SoundCloud users to customize their experience. Sounds created and reposted by people your user follows will be available in their activity feed.

You can follow a user using the /me/followings endpoint.

require 'soundcloud'

# create a client object with access token
client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN')

# Follow user with ID 3207
client.put('/me/followings/3207')

# Unfollow the same user
client.delete('/me/followings/3207')

# check the status of the relationship
begin
  client.get('/me/followings/3207')
rescue Soundcloud::ResponseError => e
  if e.response.status == '404'
    puts 'You are not following user 3207'
  end
end
import soundcloud

# create a client object with access token
client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN')

# Follow user with ID 3207
client.put('/me/followings/3207')

# Unfollow the same user
client.delete('/me/followings/3207')

# check the status of the relationship
try:
    client.get('/me/followings/3207')
except Exception, e:
    if e.response.status == '404':
        print 'You are not following user 3207'
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://example.com/callback'
});

SC.connect().then(function() {
  // Follow user with ID 3207
  SC.put('/me/followings/3207').then(function(){
    // Unfollow the same user
    SC.delete('/me/followings/3207');
  });
});
</script>

Liking a sound or set is done using the /me/favorites endpoint.

require 'soundcloud'

# create a client object with access token
client = Soundcloud.new(:access_token => 'YOUR_ACCESS_TOKEN')

# Fetch a track by it's ID
track = client.get('/tracks/290')

# Like the track
client.put("/me/favorites/#{track.id}")
import soundcloud

# create a client object with access token
client = soundcloud.Client(access_token='YOUR_ACCESS_TOKEN')

# Fetch a track by it's ID
track = client.get('/tracks/290')

# Like the track
client.put('/me/favorites/%d' % track.id)
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://example.com/callback'
});

SC.connect().then(function() {
  // favorite the track with id 290
  SC.put('/me/favorites/290');
});
</script>

See also:

/me endpoint reference documentation.

Search

This section presumes you have:

Registered your App

Resources such as sounds, users, sets can be searched using our API. Most endpoints will accept a q param which you can use to specify a keyword to search for in fields like title, username, description, etc. depending on the resource type.

Some resource types, such as sounds, can be filtered by fields like license, duration or tag_list.

require 'soundcloud'

# create a client object with your app credentials
client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID')

# find all sounds of buskers licensed under 'creative commons share alike'
tracks = client.get('/tracks', :q => 'buskers', :licence => 'cc-by-sa')
import soundcloud

# create a client object with your app credentials
client = soundcloud.Client(client_id='YOUR_CLIENT_ID')

# find all sounds of buskers licensed under 'creative commons share alike'
tracks = client.get('/tracks', q='buskers', license='cc-by-sa')
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID'
});

// find all sounds of buskers licensed under 'creative commons share alike'
SC.get('/tracks', {
  q: 'buskers', license: 'cc-by-sa'
}).then(function(tracks) {
  console.log(tracks);
});
</script>

You can also specify ranges for bpm, duration, and more.

require 'soundcloud'

# create a client object with your app credentials
client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID')

# find all tracks with the genre 'punk' that have a tempo greater than 120 bpm.
tracks = client.get('/tracks', :genres => 'punk', :bpm => {
  :from => 120
})
import soundcloud

# create a client object with your app credentials
client = soundcloud.Client(client_id='YOUR_CLIENT_ID')

# find all tracks with the genre 'punk' that have a tempo greater than 120 bpm.
tracks = client.get('/tracks', genres='punk', bpm={
    'from': 120
})
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID'
});

// find all tracks with the genre 'punk' that have a tempo greater than 120 bpm.
SC.get('/tracks', {
  genres: 'punk', bpm: { from: 120 }
}).then(function(tracks) {
  console.log(tracks);
});
</script>

For a complete list of search fields and filters, please see the API Reference for the resource type you'd like to search.

Pagination

This section presumes you have:

Registered your App

Most results from our API are returned as a collection. The number of items in the collection returned is limited to 50 by default with a maximum value of 200. Most endpoints support a linked_partitioning parameter that will allow you to page through collections. When this parameter is passed, the response will contain a next_href property if there are additional results. To fetch the next page of results, simply follow that URI. If the response does not contain a next_href property, you have reached the end of the results.

require 'soundcloud'

# create a client object with your app credentials
client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID')

page_size = 100

# get first 100 tracks
tracks = client.get('/tracks', :order => 'created_at', :limit => page_size)
tracks.each { |t| puts t.title }

# start paging through results, 100 at a time
tracks = client.get('/tracks', :order => 'created_at', :limit => page_size,
                    :linked_partitioning => 1)
tracks.each { |t| puts t.title }
import soundcloud

# create a client object with your app credentials
client = soundcloud.Client(client_id='YOUR_CLIENT_ID')

page_size = 100

# get first 100 tracks
tracks = client.get('/tracks', order='created_at', limit=page_size)
for track in tracks:
    print track.title

# start paging through results, 100 at a time
tracks = client.get('/tracks', order='created_at', limit=page_size,
                    linked_partitioning=1)
for track in tracks:
    print track.title
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID'
});

var page_size = 100;
SC.get('/tracks', { limit: page_size }).then(function(tracks) {
  // first 100 tracks
});

SC.get('/tracks', {
  limit: page_size, linked_partitioning: 1
}).then(function(tracks) {
  // page through results, 100 at a time
});
</script>

SoundCloud URLs

This section presumes you have:

Registered your App

If you have a permalink URL to a particular resource, but need more information such as an ID or other property. In these cases, you can use the /resolve endpoint to extract a full representation of the resource.

require 'soundcloud'

# create client with your app's credentials
client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID')

# a permalink to a track
track_url = 'https://soundcloud.com/forss/voca-nomen-tuum'

# resolve track URL into track resource
track = client.get('/resolve', :url => track_url)

# now that we have the track id, we can get a list of comments, for example
client.get("/tracks/#{track.id}/comments").each do |comment|
  puts "Someone said: #{comment.body} at #{comment.timestamp}"
end
import soundcloud

# create client with access token
client = soundcloud.Client(client_id='YOUR_CLIENT_ID')

# a permalink to a track
track_url = 'https://soundcloud.com/forss/voca-nomen-tuum'

# resolve track URL into track resource
track = client.get('/resolve', url=track_url)

# now that we have the track id, we can get a list of comments, for example
for track in client.get('/tracks/%d/comments' % track.id):
    print 'Someone said: %s at %d' % (comment.body, comment.timestamp)
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID'
});

// permalink to a track
var track_url = 'https://soundcloud.com/forss/voca-nomen-tuum';

var getComments = function (track) {
  return SC.get('/tracks/' + track.id + '/comments');
};

var listComments = function (comments) {
  comments.forEach(function(comment){
    console.log(comment.body);
  });
};

SC.resolve(track_url).then(getComments).then(listComments);
</script>

See also:

/resolve endpoint reference documentation.

Cross Domain Requests

This section presumes you have:

Registered your App

Our API supports CORS for making cross domain requests. This means you can access SoundCloud API endpoints from JavaScript running in the browser. By requesting results formatted as JSON, you will be able to parse and use the response immediately.

<script src="http://code.jquery.com/jquery-1.7.2.js"></script>
<script>
var url = 'https://api.soundcloud.com/tracks?client_id=YOUR_CLIENT_ID';
$.getJSON(url, function(tracks) {
  $(tracks).each(function(track) {
    console.log(track.title);
  }
});
</script>

We also support JSONP, which can be used by passing a callback parameter in the query string of the URL you are requesting.

<script>
var processTracks = function(tracks) {
  for (var i = 0; i < tracks.length; i++) {
    console.log(track.title);
  }
};
</script>
<script src="https://api.soundcloud.com/tracks?client_id=YOUR_CLIENT_ID&callback=processTracks"></script>

Errors

This section presumes you have:

Registered your App

When an error occurs, our API will return an appropriate HTTP status code and an error message description. Our SDKs will wrap this in an exception that you can catch and choose how to handle.

In this section:

HTTP Status Codes

require 'soundcloud'

# create a client object with your app credentials
client = Soundcloud.new(:client_id => 'YOUR_CLIENT_ID')

# try to get a track
begin
  track = client.get('/tracks/1')
rescue Soundcloud::ResponseError => e
  puts "Error: #{e.message}, Status Code: #{e.response.code}"
end
import soundcloud

# create a client object with your app credentials
client = soundcloud.Client(client_id='YOUR_CLIENT_ID')

# try to get a track
try:
    track = client.get('/tracks/1')
except Exception, e:
    print 'Error: %s, Status Code: %d' % (e.message, e.response.status_code)
<script src="https://connect.soundcloud.com/sdk/sdk-3.3.2.js"></script>
<script>
SC.initialize({
  client_id: 'YOUR_CLIENT_ID'
});

// all SDK methods return promises that pass errors to catch listeners
SC.get('/tracks/1').catch(function(error) {
  alert('Error: ' + error.message);
});
</script>

HTTP Status Codes

The response from SoundCloud will have an HTTP status code that will help you determine the cause of the error. Our API tries to use the appropriate HTTP status code to indicate the type of problem encountered.

Below is an overview of what those codes mean, along with some suggestions that might help you fix things.

400 Bad Request

This is likely to be caused by a programming error on your part. Check the requirements of the endpoint you're calling in the HTTP API Reference.

401 Unauthorized

This means that we were not able to authenticate you based on the information provided in the request. Make sure you're sending a client_id or an access_token.

Our public endpoints will work by just providing a client_id. Acting on behalf of another user is different. The Authentication section gives a detailed explanation of how this works.

If you're connecting using OAuth, don't forget that tokens can expire. These will need to be refreshed. Not doing so can also result in getting a 401 error.

If you need to check your application's details, use the Your Applications page. This will include the client_id for your application.

403 Forbidden

You don't have access to whatever it is you're asking for.

404 Not Found

You're asking for something that doesn't exist. Check the URL that you're requesting.

406 Not Accessible

This means it wasn't possible to respond with the format you requested. Check the Accept header that you're sending.

422 Unprocessable Entity

The request was valid, but one or more of the parameters looks a little screwy. It's possible that you sent data in the wrong format. One example would be providing an array when we expected a string.

429 Too Many Requests

To keep the amount of spam on SoundCloud as low as possible, our API limits the rate at which you can perform certain actions. Read the Rate Limits page to find out more.

500 Internal Server Error

Uh-oh. Something went wrong on our side. We're sorry. We keep track of these, and we'll try to fix it!

503 Service Unavailable

This means that we're having some trouble, and our servers are too busy to handle your request. You'll want to check for these and give your user a chance to retry the request. We keep track of these and try to make sure they don't happen.

504 Gateway Timeout

This means the request is taking too long. However, it doesn't always mean that we didn't receive your request. We could still be chugging away on the changes you made, and this means that you may want to check before retrying.

SoundCloud for Developers

Discover, connect and build

HTTP API Guide

Authentication

Sign in with SoundCloud

Client-side JavaScript Applications

Server-side Web Applications

Refreshing Tokens

Mobile and Desktop Applications

Getting Information about the Authenticated User

Authenticating without the SoundCloud Connect Screen

Uploading Sounds

Uploading Audio Files

Updating Metadata

Sharing Sounds to other Social Networks

Creating Sets

Adding Sounds to a Set

Accessing Sets

Playing Sounds

Embedding a SoundCloud Widget

Example SoundCloud Widget

Streaming Sounds

Comments

Follow & Like

Search

Pagination

SoundCloud URLs

Cross Domain Requests

Errors

HTTP Status Codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

406 Not Accessible

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

503 Service Unavailable

504 Gateway Timeout