-
Notifications
You must be signed in to change notification settings - Fork 11
Quick Start
Let’s go through a minimalistic example of how to build a SoundCloud application. This example serves just to get you started. For real world projects you will need to add additional error and event handling.
There is also a simple Flash and Flex example application available in the downloads section that uses all the code presented here.
Sign up with SoundCloud if you haven’t already and then click the link below and register your application.
http://soundcloud.com/you/apps/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 your application there as well
http://sandbox-soundcloud.com/you/apps/new
If you are using Git just fetch this project from github and place it in your Flash Builder workspace as a library project. If not, you should learn git ;) If you don’t want to do that now, just download the pre-compiled SWC file from the bin folder and put it in the lib folder of your project.
In case you want to create your project with Flash CS3 or 4 you have to download the compiled SWC file as well (and only this file!). Then open your .fla file and select File / Publish Settings… / Flash / Settings… / Library path. Click on the plus-button and add the folder where you have placed the SWC file to the list. You can also check out the example Flash CS4 project from the downloads section. It includes the SWC and has evereything set up already.
var scClient:SoundcloudClient = new SoundcloudClient(consumerKey, consumerSecret);
The two parameters are the strings you obtained in Step 1, remember?
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 anything about how it works internally.
The OAuth authentication requires 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).
Now the user of your app needs to allow it to access her account data by granting access on a special SoundCloud page. Open the page with this command:
scClient.authorizeUser();
That 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.
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, 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.
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);
sendRequest() return a delegate object that dispatches an event when the request has completed (and different one if it fails). The event object contains the response data. You can catch the events like this:
var delegate:SoundcloudDelegate = scClient.sendRequest("me", URLRequestMethod.GET);
delegate.addEventListener(SoundcloudEvent.REQUEST_COMPLETE, getMeCompleteHandler);
The event handler would look like this:
protected function getMeCompleteHandler(event:SoundcloudEvent):void
{
trace("my user name is: "+event.data.username);
}
The data that is included in the REQUEST_COMPLETE event is a XML object by default. The SoundCloud API is also able to transmit data in JSON format. You can switch the format in the SoundcloudClient. See the comments in the code for details or check the test client in the download section which is using JSON for said “me” request.
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/dorianroy/Soundcloud-AS3-API/downloads
You can find the complete ASDoc documentation files here
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 .