Table of contents

• Introduction
  • Included code
  • First steps
  • Encoding audio on the iPhone
• API wrapper overview
  • API wrapper delegates
    • SCSoundCloudAPIAuthenticationDelegate
    • SCSoundCloudAPIDelegate
  • Invoking API methods
• Licensing
• Changelog

Introduction

The intention of this API wrapper is to provide an easy to use interface to the OAuth protected SoundCloud REST API for your Cocoa applications.

The code should compile on iPhone OS version 2.0 or greater (only 2.2 has been tested though) and on version 10.5 of Mac OS X.

If you’re looking for a nice way to stream audio data from SoundCloud check out the Cocoa Streaming Library.

Included code

The code includes the OAuthConsumer implementation of OAuth which is released under the MIT license.

The test applications for Mac and iPhone further employ the JSON framework (New BSD License) which is a great choice if you don’t want to write your own parser.

First steps

Check out the project from Github. The project contains two folder SoundCloudAPI and TestApps, the first being the actual API wrapper. Open the included XCode project and build either the Mac framework or the iPhone target for device and simulator. The latter does include the separate targets for the device and the simulator and combines them in a fat binary that can be linked for both cases.

The Mac framework should be copied into your application and linked to your target. Also add a build phase to your target that copies the framework to the Frameworks destination.

For the iPhone library the device&simulator target results in an folder called “Dist” containing the library file libSoundCloudAPI.a and a folder “Headers” that contains the necessary header files. Copy both to your project, link the library in your target and you should be fine.

There’s one central header (SCAPI.h) that is to be included where ever you wish to use the API. If you’re using the Mac framework you have to include it as SoundCloudAPI/SCAPI.h.

The following are the steps required to create a SoundCloud client application. Those are exemplary and may differ from your way of implementing things.

1. Include SCAPI.h in your AppDelegate and the controller which shall invoke the API calls.
2. Implement the SCSoundCloudAPIAuthenticationDelegate in your AppDelegate (see later sections)
3. Implement the SCSoundCloudAPIDelegate in your controller
4. Create an API object

   
   SCSoundCloudAPI *scAPI = [[SCSoundCloudAPI alloc]
                                              initWithAuthenticationDelegate:appDelegate];
   [scAPI setResponseFormat:SCResponseFormatJSON];
   [scAPI setDelegate:self];
   

   It’s to hold the reference to the API in your controller. But no need to keep it singleton. Rather the SCSoundCloudAPIConfiguration might be kept singleton in the AppDelegate.
5. Prepare your parameters and send your request (according to the SoundCloud API documentation)
   

   
   NSString *filePath = [[NSBundle mainBundle] pathForResource:@"myTrack" ofType:@"mp3"];
   NSURL *fileURL = [NSURL fileURLWithPath:filePath];
   NSDictionary *parameters = [NSDictionary dictionaryWithObjectsAndKeys:
              fileURL, @"track[asset_data]",
              @"public", @"track[sharing]";
              @"My favorite track", @"track[title]",
              nil];
   [scAPI performMethod:@"POST"
             onResource:@"tracks"
         withParameters:parameters
                context:@"upload"];
   

Note the context in this request is “upload”. You can use this context in your soundCloudAPI:didFinishWithData:context: implementation to react on that specific request. Also you might want to implement soundCloudAPI:didSendBytes:total:context: to give the user information about uploading progress.

Encoding audio on the iPhone

(This section is still in development)

OGG Vorbis can be used, the compression takes time (approx. twice the duration of the uncompressed file to compress) but the uploading is quick because the file is small. There are other options like FLAC, were you get a fast compression time but the compressed file size is large.

For OGG Vorbis encoding, compile libogg and libvorbis for the iPhone. Then you can hook a Vorbis compression example into your application code and link the application to the libraries. You can find an encoding example here.

In short, OGG Vorbis encoding is doable and not very difficult, but the iPhone is not so fast so the compression takes time.

API wrapper overview

There are only two classes and two delegates you have to care about when using the API. The SCSoundCloudAPI (notice the SC prefix) is used to send requests to the SoundCloud servers. The API wrapper is configured by supplying it with an instance of the SCSoundCloudAPIConfiguration class.

The configuration needs to be passed the consumer key and the consumer secret of your application (get them at the application registration page). Further you need to supply a callback URL which is used to return to your application after it has been authorized by the user (see the example applications for Mac and iPhone on how to bind you application to a custom URL scheme. Also see the Apple documentation for iPhone and Mac).

On creating an SCSoundCloudAPI instance you must supply a SCSoundCloudAPIAuthenticationDelegate which is described in detail, later.

API wrapper delegates

The Cocoa SoundCloud API wrapper describes two delegates.

SCSoundCloudAPIAuthenticationDelegate

It is recommended to implement this delegate as a singelton (probably in your AppDelegate). It implements three methods:

• configurationForSoundCloudAPI:
  Is to return the SCSoundCloudAPIConfiguration object
  
  
  
• soundCloudAPI:requestedAuthenticationWithURL:
  Is called when a web browser needs to be opened to authorise the request token. Inform the user and open the browser.
  
  
  
• soundCloudAPI:didChangeAuthenticationStatus:
  Is called when the authentication status of the API changes. You can interact on the different autentication statuses and inform the user. Further you can trigger the next step in the authentication procedure. See the example applications for reference implementation.
  
  

SCSoundCloudAPIDelegate

This delegate is used to be invoked as a result during the API calls. For an explanation on the context see the next section. The methods are:

• soundCloudAPI:didFinishWithData:context:
  Is called when the response is completed. It is called with the data (NSData) of the response body.
  
  
  
• soundCloudAPI:didFailWithError:context:
  Is called if the request failed. It is called with the error (NSError) containing information why the request failed.
  
  
  
• soundCloudAPI:didReceiveData:context:
  Is called during the API receives data from the server. The data (NSData) is received progressively as blocks. After the whole response has been received soundCloudAPI:didFinishWithData:context: is invoked.
  
  
  
• soundCloudAPI:didReceiveBytes:total:context:
  Is called during the API receives data from the server. Contains the amount (UInt32) of bytes already received and the total amount of bytes.
  
  
  
• soundCloudAPI:didSendBytes:total:context:
  Is called during the API sends data to the server in a POST request. Contains the amount (UInt32) of bytes already sent and the total amount of bytes to be sent.

Invoking API methods

SCSoundCloudAPI provides a method performMethod:onResource:withParameters:context:. The four method parameters are the following:

• Method:
  The HTTP method. GET, POST, PUT or DELETE as NSString.
  
  
  
• Resource:
  The resource on the RESTful API side. See the API documentation for a list of resource types.
  
  
  
• Parameters:
  A dictionary (NSDictionary) of parameter names and values. The values are either of the type NSString or if you want to send POST data you can also supply a NSURL pointing to a file or an NSData object (remember the memory limits on the iPhone when directly passing NSData).
  
  
  
• Context:
  The context is an object (id) which can be used to relate method invocation to delegate invocation.

Licensing

We decided to widen the license and switched from the GNU Lesser General Public License to the Apache License, Version 2. Instead of the LGPL which is a copyleft license the ALv2 is a free software license. It neither forces you to redistribute your code under the license itself nor does it force you to open your code in any other way. As always feel free to contact us if there are any obscurities concerning licensing.

Changelog

• 20th nov, 2009 Added a reference to the Cocoa Streaming Library in the introduction
• 30th may, 2009 Added pre compiler statement to let the wrapper compile on iPhone OS 3.0 simulator (set base sdk of the device & simulator targets)
• 30th may, 2009 Added additional error hook to the authDelegate + pulled authentication workflow inside the framework (removed it from the sample applications)
• 25th march, 2009 Added Increased timeout of HTTPRequest + fixed a bug on which the post stream wasn’t closed by the NSURLConnection
• 14th march, 2009 Added SCInputStreamWrapper as a possibility to pass in stream data as a
  parameter to the request
• 11th march, 2009 Removed SHA1 and HMAC algorithms from the OAuth stack and replaced them internal functions (no longer exporting cryptography algorithms)
• 26th feb, 2009 Added a section on encoding audio for the iPhone
• 19th feb, 2009 Switched to Apache License version 2
• 18th feb, 2009 Integrated library targets for the wrapper (no more copying the whole code)
• 17th feb, 2009 Launch of version 1.0