Quick Start

Seven steps to connect your Flash application to SoundCloud

Let’s go through a minimalistic example of how to build a SoundCloud application. For real world projects you will need to add some error and event handling, this example is just to get you started.

There is also a simple AIR client available in the downloads section that uses all the code presented here (you’ll need Flex SDK 4 to run it).

1. Register your application

Sign up with SoundCloud if you haven’t already and then click the link below and register your application.
http://soundcloud.com/settings/applications/new

You need to do that in order to get a Consumer Key and Secret that allows you to connect to the API. Once you’re app is registered you can copy the Consumer Key and Consumer Secret strings and save them as constants somewhere in your code.
Note: If you also want to use the SoundCloud sandbox (recommended) be sure to register an application there as well
http://sandbox-soundcloud.com/settings/applications/new

2. Download the AS3 wrapper

If you are using Git just check out this project and include it in your project as source code or a library project. If not, you should learn git ;) If you don’t want to do that now, just download the SWC and put it in your lib folder or project root folder (e.g. for Flash).

3. Create a SoundcloudClient

var scClient:SoundcloudClient = new SoundcloudClient(consumerKey, consumerSecret);

The two parameters are the strings you obtained in Step 1, remember?

4. Authentication Step 1: Get a Request Token from SoundCloud

At this point you have to learn a little about how OAuth works. OAuth is the authentication standard that SoundCloud and many other web services are using. It’s very complicated but you don’t need to know much about how it works.

The OAuth authentication reqires three steps. The first step is to request a “Request Token” by calling

scClient.getRequestToken();

That’s it. The returned token is stored within the client object so you don’t need to handle it (of course you could add a listener to the response event. Have a look at the code of the example client to learn how to do that).

5. Authentication Step 2: Authorize the Request Token

Now the user of your app needs to allow it to access her account data by granting access on a special SoundCloud page. Open this page like this:

scClient.authorizeUser();

This will bring up the page in the browser. After you have clicked “Allow Access” on this page, you should see a “Verifier” code on the confirmation page. Copy this code because you need to submit it in the next step.

6. Authentication Step 3: Authorize the Request Token

Now that you have an authenticated request token, you can trade it for an “Access Token”:

scClient.getAccessToken(verificationCode);

Enter the code from the web page as the parameter.

The “Access Token” you will receive now allows you to make any call to the SoundCloud API without going through the authentication process again. So it’s a good idea to store it from your application, e.g. in the EncryptedLocalStorage, if you’re building an AIR application or in a Flash Cookie. The next time you start the app you can pass it to the SoundcloudClient as the 3rd parameter and start making calls against the API immediately. The Access Token is restricted to be used with your application (based on you Consumer Key and Secret) and the SoundCloud user that has authenticated it on the web in step 5. That means that every user of your app needs a different token and it doesn’t make sense to hardcode it in your application. Only the Consumer Key and Secret should be included when you publish your application.

7. Send requests

Now that you have an Acess Token you can access all resources exposed by the SoundCloud API. “me” for example let’s you obtain the user profile data of the currently logged on user:

scClient.sendRequest("me", URLRequestMethod.GET);

If a request requires parameters you can pass them wrapped in a simple AS-Object to sendRequest() as the 3rd parameter. E.g. if you want to create a new set (internally called “playlist”):

var params:Object = {};
params["playlist[title]"] = "Top 5";
params["playlist[description]"] = "My current top 5 tracks";
scClient.sendRequest("playlists", URLRequestMethod.POST, params);

See the official API documentation for a list of all available resources and their parameters:
http://soundcloud.com/api

Check out the code of the sample application from the downloads section to see how to upload tracks:
http://github.com/dasflash/Soundcloud-AS3-API/downloads

I hope this was not too hard for the start. There are many more features under the hood of this API that I want to cover in upcoming posts. If you want to be feeded with news on the AS3 SoundCloud API you can grab the RSS of my blog or follow me on Twitter .