Getting started

Required Gems

• activeresource gem
• activesupport gem
• multipart gem
• oauth gem
• jwagener-oauth-active-resource gem

Installation

First install all the missing required gems. To install the jwagener-oauth-active-resource gem you can use:

$ sudo gem install jwagener-oauth-active-resource -s http://gems.github.com

Then install the soundcloud api wrapper gem:

$ sudo gem install soundcloud-ruby-api-wrapper -s http://gems.github.com

Setup OAuth things

Look at http://wiki.github.com/soundcloud/api/oauth-example to find out, how you setup your OAuth things.

First steps

Let's start with a simple app. It will find and display the 10 hottest tracks of alltime. You don't need any OAuth authentication to do this.

require 'rubygems'
gem 'soundcloud-ruby-api-wrapper'
require 'soundcloud'

# Create an anonymous soundcloud client
# if you prefer to work with sandbox-soundcloud.com, replace this with:
# sc_client = Soundcloud.register({:site => "http://api.sandbox-soundcloud.com"})
sc_client = Soundcloud.register

# Find the 10 hottest tracks
hot_tracks = sc_client.Track.find(:all,:params => {:order => 'hotness', :limit => 10})

# and display their titles
p '==the 10 hottest tracks=='
hot_tracks.each do |track|
  p track.title
end

To test authentication you can use this small app, which will dispay the name of the logged in user.

require 'rubygems'
gem 'soundcloud-ruby-api-wrapper'
require 'soundcloud'

gem 'oauth'
require 'oauth'


# Create a Soundcloud OAuth consumer token object
sc_consumer = Soundcloud.consumer('YOUR_APPLICATION_CONSUMER_TOKEN','YOUR_APPLICATION_CONSUMER_SECRET')

# Create an OAuth access token object
access_token = OAuth::AccessToken.new(sc_consumer, 'YOUR_OAUTH_ACCESS_TOKEN', 'YOUR_OAUTH_ACCESS_SECRET')

# Create an authenticated Soundcloud client, based on the access token
sc_client = Soundcloud.register({:access_token => access_token})

# Get the logged in user 
my_user = sc_client.User.find_me

# Display his full name
p "Hello, my name is #{my_user.full_name}"

Find more examples in these pages: [[Model Events]], [[Model Users]], [[Model Tracks]], [[Model Playlists]], [[Model Comments]].

Sub-resources

The Soundcloud API provides 3 different types of sub-resources:

Nested sub-resources

These are directly embedded in the resource. For example a playlist has a track array.

playlist.tracks

When saving the original resource, the nested array will be saved as well.

playlist.tracks << some_track
playlist.save

Separate sub-resources

These are separated from the original resource. Example: A Track has the path "/tracks/[TRACK ID]" This track has a collection of users, which have access to this track, called permissions. These can be accessed via the path "/tracks/[TRACK ID]/permission". In ruby they are accessed like nested resources:

playlist.permissions

But have to be saved explicitly:

playlist.permissions << some_user
playlist.permissions.save
playlist.save

A lot of these collections are partials, that means Soundcloud API will not return more than 50 items per request. For example the user famous_dj has 120 fans/followers. famous_dj.fans will only return 50 fans. To get all fans you have to do something like this:

fans = []
limit = 50
begin 
  some_fans = famous_dj.fans({:offset => fans.count, :limit => limit})
  fans += some_fans
end while some_fans.count >= limit

The array fans now contains all fans/followers of famous_dj.

'Single changeable' separate sub-resources

Some separate collections can't be saved in a bulk request. Instead each item has to be added or removed explicitly. For now this only affects the contacts (followees) and favorites of a user. To add a track to the logged-in users favorites:

track.add_favorite!

Remove:

track.remove_favorite!

Check:

track.is_favorite? => true or false

The same works with the contacts of the logged-in user:

another_user.add_contact!
another_user.remove_contact!
another_user.is_contact? => true or false

You can also check if another users follows some user or has a specific favorite:

user.has_contact?(some_user) => true of false 
user.has_favorite?(some_track) => true or false