soundcloud-ruby-api-wrapper 0.1.6 → 0.1.8

data/README.html

@@ -29,7 +29,7 @@ Look at <a href="http://wiki.github.com/soundcloud/api/oauth-example">http://wik
 
 <h3>First steps</h3>
 
-Let's start with a simple app, which will find and display the hottest tracks. You don't need any OAuth authentication to do this.
+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.
 
 <pre>
 require 'rubygems'
@@ -42,7 +42,7 @@ require 'soundcloud'
 sc_client = Soundcloud.register
 
 # Find the 10 hottest tracks
-hot_tracks = sc_client.Track.find(:all,:params => {:order => 'order', :limit => 10})
+hot_tracks = sc_client.Track.find(:all,:params => {:order => 'hotness', :limit => 10})
 
 # and display their titles
 p '==the 10 hottest tracks=='
@@ -69,7 +69,7 @@ sc_consumer = Soundcloud.consumer('YOUR_APPLICATION_CONSUMER_TOKEN','YOUR_APPLIC
 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})
+sc_client = Soundcloud.register({:access_token => access_token})
 
 # Get the logged in user 
 my_user = sc_client.User.find_me
@@ -79,25 +79,25 @@ p "Hello, my name is #{my_user.full_name}"
 
 </pre>
 
-Find more examples in the "Model ..." pages.
+Find more examples in these pages: [[Model Events]], [[Model Users]], [[Model Tracks]], [[Model Playlists]], [[Model Comments]].
 
 
 <h2>Sub-resources</h2>
 
 The Soundcloud API provides 3 different types of sub-resources:
-<h3>Nested</h3>
+<h3>Nested sub-resources</h3>
 
-These are directly embedded in the response. For example a playlist has a track array.
+These are directly embedded in the resource. For example a playlist has a track array.
   
   <pre>playlist.tracks</pre>
   
 When saving the original resource, the nested array will be saved as well.
 
-<pre>playlist.tracks.push some_track
+<pre>playlist.tracks &lt;&lt; some_track
 playlist.save
 </pre>
   
-<h3>Separate</h3>
+<h3>Separate sub-resources</h3>
 
 These are separated from the original resource.
 Example:
@@ -111,7 +111,7 @@ In ruby they are accessed like nested resources:
   
 But have to be saved explicitly:
 <pre>
-playlist.permissions.push some_user
+playlist.permissions &lt;&lt; some_user
 playlist.permissions.save
 playlist.save</pre>
 
@@ -130,7 +130,7 @@ end while some_fans.count >= limit
 The array fans now contains all fans/followers of famous_dj.
 
 
-<h3>'Single changeable' separate</h3>
+<h3>'Single changeable' separate sub-resources</h3>
 
 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.

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 0
 :minor: 1
-:patch: 6
+:patch: 8 

data/lib/soundcloud/models/comment.rb

@@ -1,9 +1,20 @@
 module Soundcloud
-  module Models    
-    # Soundcloud Comment resource
+  module Models   
+    # 
+    # SC API Attributes (as of 26/05/09):
+    # * body
+    # * timestamp
+    # * id
+    # * track_id
+    # * user_id
+    # * uri
+    #
+    # Custom Wrapper Attributes/Methods:
+    # * user 
+    # * track
     #
     # Look up the resource attributes and filtering usage here:
-    #    
+    #         
     # http://wiki.github.com/soundcloud/api/documentation#comment
     #
     # Examples:
@@ -13,7 +24,7 @@ module Soundcloud
     #   sc_client.Comment.create({:track => some_track, :body => 'Nice Track!'})
     #  
     #   # optionally you can add a timestamp (in milliseconds)
-    #   sc_client.Comment.create({:track => some_track, :body => 'nice drums!', :timestamp => 5000})
+    #   sc_client.Comment.create({:track => some_track, :body => 'nice drums @ the 5th second!', :timestamp => 5000})
     #
     #   # display all comments of some track
     #   some_track.comments.each do |comment| 

data/lib/soundcloud/models/event.rb

@@ -1,19 +1,31 @@
 module Soundcloud
   module Models
-    # Look up the resource attributes and filtering usage here:
     #
+    # SC API Attributes (as of 26/05/09): 
+    # * type
+    # * id
+    # * created_at
+    # * resource_id
+    # * comment/track/user (embedded resource, depending on type)
+    #
+    # Look up the resource attributes and filtering usage here:
+    #    
     # http://wiki.github.com/soundcloud/api/documentation#event
     #
     # Examples:
     #
-    #   # find the last 50 (default soundcloud limit) dropbox events    
-    #   sc_client.Event.find(:all,:params => {:filter => 'drop'})
+    #   # find the last 50 (default soundcloud limit) dropbox events and display the titles of the dropped tracks
+    #   dropbox_events = sc_client.Event.find(:all,:params => {:filter => 'drop'})
+    #
+    #   dropbox_events.each do |event|
+    #     p event.track.title
+    #   end
     #    
     #   # find the last 50 (default soundcloud limit)  events    
     #   sc_client.Event.find(:all)
     #
     class Event < Base    
-      belongs_to :user, :track
+      #belongs_to :user, :track, :comment # this is not right
       cattr_accessor :element_name    
       self.element_name = 'event'
     end    

data/lib/soundcloud/models/playlist.rb

@@ -2,8 +2,28 @@ module Soundcloud
   module Models
     # Note: At the moment, you can't create or delete playlists via Soundcloud API
     #
-    # Look up the resource attributes and filtering usage here:
+    # SC API Attributes (as of 26/05/09):
+    # * created_at
+    # * description
+    # * genre
+    # * id
+    # * permalink
+    # * title
+    # * user_id
+    # * permalink_url
+    # * uri
+    # * artwork_url
+    # * duration
+    # * type
+    # * user (overwritten by wrapper)
+    # * tracks (array)
     #
+    # Custom Wrapper Attributes/Methods:
+    # * user 
+    # * permissions
+    #    
+    # Look up the resource attributes and filtering usage here:
+    #    
     # http://wiki.github.com/soundcloud/api/documentation#playlist
     # 
     # Examples:

data/lib/soundcloud/models/track.rb

@@ -1,7 +1,43 @@
 module Soundcloud
   module Models  
     # Look up the resource attributes and filtering usage here:
-    #        
+    # 
+    # SC API Attributes (as of 26/05/09):
+    # * id
+    # * user_id
+    # * permalink
+    # * description
+    # * sharing
+    # * bpm
+    # * comments_count
+    # * created_at
+    # * downloadable
+    # * downloads_count
+    # * duration
+    # * genre
+    # * streamable
+    # * uri
+    # * user (overwritten by wrapper)
+    # * permalink_url
+    # * playback_count
+    # * artwork_url
+    # * waveform_url
+    # * purchase_url
+    # * stream_url
+    # * user_playback_count
+    # * user_favorite
+    #
+    # Custom Wrapper Attributes/Methods:
+    # * user 
+    # * permissions
+    # * comments
+    # * is_favorite?
+    # * add_favorite!
+    # * remove_favorite!
+    # * asset_data (= File.new('/your file..'))
+    # 
+    # Look up the resource attributes and filtering usage here:
+    #                          
     # http://wiki.github.com/soundcloud/api/documentation#track
     #
     # Examples:
@@ -9,7 +45,7 @@ module Soundcloud
     #   # gets 50 (Soundcloud API limit) tracks from some_user
     #   some_user_tracks = some_user.tracks
     #
-    #   # gets the first song from some_user_tracks
+    #   # gets the latest song from some_user_tracks
     #   first_song = some_user_tracks.first
     #
     #   # prints 50 (Soundcloud API limit) comments of first_song with username, timestamp (can be nil) and comment body
@@ -31,11 +67,12 @@ module Soundcloud
     #   new_track = sc_client.Track.new
     #   new_track.title = 'New Track'
     #   new_track.sharing = 'private'
-    #   new_track.set_asset_data(File.new('some_sound_file.wav')
+    #   new_track.asset_data = File.new('some_sound_file.wav')
     #   new_track.save
     #   
-    #   # downloads the original soundfile. some_sound_file.wav and another_sound_file.wav should be equal
-    #   File.open('another_sound_file.wav', 'w') {|f| f.write( new_track.download ) }
+    #   # downloads the original soundfile. 
+    #   #some_sound_file.wav and downloaded_file should be the same (the open call requires the 'open-uri' gem)
+    #   downloaded_file = open new_track.download_url
     #
     #   # gives some_user permission to access the new_track    
     #   some_user = sc_client.User.find('some_user')
@@ -52,16 +89,22 @@ module Soundcloud
       can_be_a_single_changeable :favorite
             
       cattr_accessor :element_name
+      attr_accessor :asset_data
       self.element_name = 'track'
      
-      def download
+      def download_url
         raise Exception.new('Track is not downloadable') if not downloadable
-        begin
-          response = connection.handle_response( self.class.oauth_connection.get(download_url) )
-        rescue ActiveResource::Redirection => redirection          
-          response = Net::HTTP.get(URI.parse(redirection.response['Location']))
+        original_download_url = super       
+        if sharing == "private" 
+          begin
+            response = connection.handle_response( self.class.oauth_connection.get( original_download_url ) )
+            return original_download_url
+          rescue ActiveResource::Redirection => redirection          
+            return redirection.response['Location']
+          end
+        else
+          return original_download_url
         end
-        return response
       end
       
       # multipart stuff, to upload a soundfile 

data/lib/soundcloud/models/user.rb

@@ -1,10 +1,46 @@
 module Soundcloud
   module Models
+    # SC API Attributes (as of 26/05/09):
+    # * id
+    # * username
+    # * full_name
+    # * description
+    # * city
+    # * country
+    # * discogs_name
+    # * myspace_name
+    # * website
+    # * website_title
+    # * online
+    # * avatar_url
+    # * permalink_url
+    # * uri
+    # * track_count
+    #
+    # Custom Wrapper Attributes/Methods:
+    # * tracks
+    # * contacts
+    # * comments
+    # * favorites
+    # * playlists
+    # * fans
+    # * is_contact?
+    # * add_contact!
+    # * remove_contact!
+    # * has_favorite?(track/track_id)
+    # * has_contact?(user/user_id)
+    #    
     # Look up the resource attributes and filtering usage here:
     #        
     # http://wiki.github.com/soundcloud/api/documentation#user
     #
+    # Custom Wrapper Class Methods
+    # * find_me 
+    #
     # Examples:
+    #   # gets the logged-in user
+    #   me = client.User.find_me
+    #    
     #   # gets the user with username userABC
     #   user = sc_client.User.find('userABC')
     #  
@@ -14,8 +50,6 @@ module Soundcloud
     #     p user.username
     #   end
     #   
-    #   # gets the logged-in user
-    #   me = client.User.find_me
     #
     #   # checks if the first user named joe is following the second user named joe
     #   joe1 = joes.first

data/spec/soundcloud_event_spec.rb

@@ -11,4 +11,9 @@ describe 'Soundcloud::Models::Event' do
   it 'should get the last events' do
     events = @sc.Event.find(:all)
   end
+  
+  it 'should get a fan event and should provide the user resource' do
+    fan_events = @sc.Event.find(:all,:params => {:type => 'Fan'})
+    fan_events.first.user.username.should_not be nil
+  end
 end

data/spec/soundcloud_track_spec.rb

@@ -31,7 +31,8 @@ describe "Soundcloud::Models::Track" do
     track = @sc.Track.new
     track.title = 'API Test 1'
     track.sharing = 'private'
-    track.set_asset_data(test_track_file)    
+#    track.set_asset_data(test_track_file)    
+    track.asset_data = test_track_file
     track.save
 
     track.destroy
@@ -63,16 +64,15 @@ describe "Soundcloud::Models::Track" do
     @test_track_1.is_favorite?.should be false
   end  
   
-  it 'should be able to download a track' do
-    track = @sc.Track.find(:one, :from => '/users/api-test-2/tracks/track1-2')
-    track.download
+  it 'should be able to download a private track' do
+    track = @sc.Track.find(:one, :from => '/users/api-test-2/tracks/track3-1')
+    track.download_url
   end
   
-  it 'should be able to download a track (unauthenticated)' do 
+  it 'should be able to download a public track (unauthenticated)' do 
     usc = Soundcloud.register({:site => soundcloud_site})
     track = usc.Track.find(:one, :from => '/users/api-test-2/tracks/track1-2')
-    #    File.open('/tmp/sc-track', 'w') {|f| f.write( track.download ) }
-    track.download
+    track.download_url
   end
   
   it 'should find tracks with a bpm <= 90' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: soundcloud-ruby-api-wrapper
 version: !ruby/object:Gem::Version 
-  version: 0.1.6
+  version: 0.1.8
 platform: ruby
 authors: 
 - Johannes Wagener
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-05-25 00:00:00 -07:00
+date: 2009-05-27 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency