WithSoundCloud API you can build applications that takemusic to the next level. With this guide we explain andprovide code examples for a lot of common integration use cases likeplaying and uploading tracks, liking a playlist or discovering new music.If you're looking for more in depth information,feel free to jump to our API Explorer.
In order to integrate with Soundcloud you need to authorize your application.SoundCloud authentication uses the OAuth 2.1 draft,a popular open standard used by many API providers. OAuth 2.1allows users to authorize the application without disclosing their usernameand password.
You can simplify your registration and sign in process by using aConnect with SoundCloud button. This lets your user know that theycan register for your app with one click using their SoundCloudaccount. It also grants your app access to their account and givesyou the ability to upload tracks, create playlists and otherwise act ontheir behalf.
Your application should construct the authorization URL with the necessaryparameters and then redirect the user's browser to this URL.This step must be performed on the front-end of your application,as it involves user interaction.
YOUR_CLIENT_ID: The client ID you obtained during application registration.
YOUR_REDIRECT_URI: The URI you provided during application registration. After authentication,the user will be redirected to this URI.Your application should be prepared to receive and process the authorization code at this URI.
CODE_CHALLENGE: A PKCE code challenge. You can read about ithere and use this PKCE generator sandbox to understand how it works.
STATE: A random string to protect against CSRF attacks.
A pop-up window will be opened allowing the user to log in toSoundCloud and approve your app's authorization request.If the user is already signed into SoundCloud, they will be able to authorize your request in one click.
If the user approves your authorization request, they will be sentto the redirect_uri you specified when registering your app. Your applicationshould extract the code parameter from the query string and use it to obtain an access token.
YOUR_CLIENT_ID, YOUR_CLIENT_SECRET: obtained during application registration.
YOUR_PKCE_GENERATED_CODE_VERIFIER: generated by your application during step 1.
YOUR_REDIRECT_URI: the same redirect URI you used in the authorization request. This must match exactly to ensure security.
YOUR_CODE: the authorization code your application received from the authorization server.
The returned object has an access_token property and a refresh_tokenproperty as well as expires_in and scope.You should now store the object in a database or a data storage of your choice. Associate itwith the user it belongs to and use the access_token from now on instead ofsending the user through the authorization flow on each API interaction.Use the refresh_token returned in the body to automatically renew the expired token via the refresh token flow.
With applications, such as CLIs, or pure back-end services, you would authenticate the application itselfrather than a user. For instance, you might want to build an artist's website where you only need an accessto their tracks, playlists, or user information. There is no need to go through the connect flow, asSoundCloud API provides the Client Credentials Flow for these purposes. You pass along theclient_id and client_secret you have acquired at registrationto authenticate and get a token.
*** Developers migrating to new endpoints should note that for the client_credential grant type, ONLY basic header client authentication is supported. Client credentials as request content has been dropped.
Similarly to the Authorization Code flow, you receive an object that has an access_token,refresh_token properties as well as expires_in and scope.Store the object in a database or a data storage of your choice. Associate it with the user it belongs toand use the access_token for requesting data from our API. Use the refresh_token to automatically renew the expiredtoken.
Please be aware there is rate limiting on the amount of tokens you can request through the Client Credentials Flow:50 tokens in 12h per app, and 30 tokens in 1h per IP address. In order to not hit the limit we highlyrecommend reusing one token between instances of your service and implementing the Refresh Token flow to renew tokens.
As the access tokens expire you will need to periodically refresh them. Currently a token lives around 1 hour.You can set an automatic process that checks the expiration time of a current token and updates it usingthe provided refresh_token. Each refresh token can only be used once.
You authenticate mobile and desktop applications the same way youdo for web applications. To make the flow smoother, youcan use a redirect_uri with a custom protocol scheme and set yourapp as a handler for that protocol scheme. For example, yourredirect_uri could be something like my-app://soundcloud/callback.
All Soundcloud resources (tracks, playlists, users) can only be accessed byan authenticated applications. That said, every request to our API requires anAuthorization header in the following format:
Once the user has signed into SoundCloud and approved your app'sauthorization request, you will be able to access their profile andact on their behalf. We have provided a convenient endpoint foraccessing information about the authenticated user.
Tracks are core to SoundCloud.Our API gives you the ability to upload, manage andshare tracks. Your app can take an audio file and uploadit to a user's SoundCloud account. You can also manage metadata(including tags) or add the track to playlists.We support the following formats: AIFF, WAVE, FLAC, OGG, MP2, MP3, AAC, AMR and WMA.
Playlists allow you to organize tracks into groups that can be shared together. For example, tracksin an album or in a specific collection can be grouped together using a playlist and then shared to the world.You can add any tracks to a playlist and a track can belong to multiple playlists.Playlists can be either private or public.
Yep, you can also play tracks and playlists from your application. Depending onyour needs, you can embed a player widget, or feed a stream url into yourown audio player. You can also use our Widget API to control theplayer and handle events.
If you have the URL of a track or a playlist, you canget the embed code and paste it into your website. You can also do this inyour application using the oEmbed endpoint. Given a track or playlistURL, you can retrieve all of the information you need to embed a player.
Note if you are going to stream from our API you need to attribute properly.Make sure you've read our Terms andAttribution Guidelines to make sureyou treat our creators content correctly. When using a custom player you must:
If you don't want to use the SoundCloud widget, our API gives youthe ability to access a track's stream URL and use your own playerto play tracks from SoundCloud. In order to get a URL for streaming,you can request the appropriate resource and make note ofthe stream_url property. Send a GET request to that URL andyou will get a set of links with available transcodings which you can choose from.
Note that as long as the track is public, you can access it with no user associated.If you would like to access the stream URL for a private track, you'll need tohave an authorized user session and a secret_token provided.
Not every track is allowed for streaming off platform. A user might restrict a playback, ora track might be behind a paywall, geo-blocked and so on. In that case a track in response wont have astream_url available and a field access will have blocked. If youtry to call /tracks/:id/streams endpoint you will get an error.
Your application can take advantage of SoundCloud's social featuresby allowing users to follow other users and like tracks or playlists. Followingand liking allows SoundCloud users to customize their experience. Trackscreated and reposted by people your user follows will be available in theiractivity feed.
Resources such as tracks, users, playlists can be searchedusing our API. Most endpoints will accept a q param which you canuse to specify a keyword to search for in fields like title,username, description, etc. depending on the resource type.
Most results from our API are returned as a collection. The numberof items in the collection returned is limited to 50 bydefault with a maximum value of 200. Most endpoints support alinked_partitioning parameter that allows you to pagethrough collections. When this parameter is passed, the response willcontain a next_href property if there are additional results.To fetch the next page of results, simply follow that URI. If the responsedoes not contain a next_href property, you have reached theend of the results.
Our API supports CORS for making cross domain requests. This meansyou can access SoundCloud API endpoints from JavaScript running inthe browser. By requesting results formatted as JSON, you will beable to parse and use the response immediately.
The response from SoundCloud will have an HTTP status code thatwill help you determine the cause of the error. Our API tries to usethe appropriate HTTP status code to indicate the type of problemencountered.
Our public endpoints will work with an access token acquired through the Client Credentials flow.Acting on behalf of another user is different. The Authenticationsection gives a detailed explanation of how this works.
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.
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.
Is it possible to have soundcloud only play once but not replay again if the user goes to another page and comes back? It may have someone to do with cookies so i enabled third party just to test but nope, as soon as I go away from that page and come back it starts up again. I don't want users to have that kind of experience. This may be out of the realm of SS so I totally understand if there is no answer on this one
3a8082e126