soundcloud-ruby-api-wrapper 0.1.5 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. data/README.html +164 -0
  2. data/VERSION.yml +1 -1
  3. data/lib/soundcloud/models/event.rb +0 -3
  4. data/lib/soundcloud/models/playlist.rb +1 -3
  5. data/lib/soundcloud/models/track.rb +7 -11
  6. data/lib/soundcloud/models/user.rb +16 -7
  7. data/spec/soundcloud_user_spec.rb +9 -0
  8. metadata +3 -1
data/README.html ADDED
@@ -0,0 +1,164 @@
1
+ <html>
2
+ <body>
3
+ <div id="description" style="width: 600px">
4
+
5
+ <h2>Getting started</h2>
6
+ <h3>Required Gems</h3>
7
+
8
+ <ul>
9
+ <li>activeresource gem</li>
10
+ <li>activesupport gem</li>
11
+ <li>multipart gem</li>
12
+ <li>oauth gem</li>
13
+ <li><a href="http://github.com/jwagener/oauth-active-resource">jwagener-oauth-active-resource</a> gem</li>
14
+ </ul>
15
+
16
+ <h3>Installation</h3>
17
+
18
+ First install all the missing required gems. To install the jwagener-oauth-active-resource gem you can use:
19
+
20
+ <pre>$ sudo gem install jwagener-oauth-active-resource -s http://gems.github.com</pre>
21
+
22
+ Then install the soundcloud api wrapper gem:
23
+
24
+ <pre>$ sudo gem install soundcloud-ruby-api-wrapper -s http://gems.github.com</pre>
25
+
26
+ <h3>Setup OAuth things</h3>
27
+
28
+ Look at <a href="http://wiki.github.com/soundcloud/api/oauth-example">http://wiki.github.com/soundcloud/api/oauth-example</a> to find out, how you setup your OAuth things.
29
+
30
+ <h3>First steps</h3>
31
+
32
+ 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.
33
+
34
+ <pre>
35
+ require 'rubygems'
36
+ gem 'soundcloud-ruby-api-wrapper'
37
+ require 'soundcloud'
38
+
39
+ # Create an anonymous soundcloud client
40
+ # if you prefer to work with sandbox-soundcloud.com, replace this with:
41
+ # sc_client = Soundcloud.register({:site => "http://api.sandbox-soundcloud.com"})
42
+ sc_client = Soundcloud.register
43
+
44
+ # Find the 10 hottest tracks
45
+ hot_tracks = sc_client.Track.find(:all,:params => {:order => 'order', :limit => 10})
46
+
47
+ # and display their titles
48
+ p '==the 10 hottest tracks=='
49
+ hot_tracks.each do |track|
50
+ p track.title
51
+ end
52
+ </pre>
53
+
54
+ To test authentication you can use this small app, which will dispay the name of the logged in user.
55
+
56
+ <pre>
57
+ require 'rubygems'
58
+ gem 'soundcloud-ruby-api-wrapper'
59
+ require 'soundcloud'
60
+
61
+ gem 'oauth'
62
+ require 'oauth'
63
+
64
+
65
+ # Create a Soundcloud OAuth consumer token object
66
+ sc_consumer = Soundcloud.consumer('YOUR_APPLICATION_CONSUMER_TOKEN','YOUR_APPLICATION_CONSUMER_SECRET')
67
+
68
+ # Create an OAuth access token object
69
+ access_token = OAuth::AccessToken.new(sc_consumer, 'YOUR_OAUTH_ACCESS_TOKEN', 'YOUR_OAUTH_ACCESS_SECRET')
70
+
71
+ # Create an authenticated Soundcloud client, based on the access token
72
+ sc_client = Soundcloud.register({ :access_token => access_token})
73
+
74
+ # Get the logged in user
75
+ my_user = sc_client.User.find_me
76
+
77
+ # Display his full name
78
+ p "Hello, my name is #{my_user.full_name}"
79
+
80
+ </pre>
81
+
82
+ Find more examples in the "Model ..." pages.
83
+
84
+
85
+ <h2>Sub-resources</h2>
86
+
87
+ The Soundcloud API provides 3 different types of sub-resources:
88
+ <h3>Nested</h3>
89
+
90
+ These are directly embedded in the response. For example a playlist has a track array.
91
+
92
+ <pre>playlist.tracks</pre>
93
+
94
+ When saving the original resource, the nested array will be saved as well.
95
+
96
+ <pre>playlist.tracks.push some_track
97
+ playlist.save
98
+ </pre>
99
+
100
+ <h3>Separate</h3>
101
+
102
+ These are separated from the original resource.
103
+ Example:
104
+ A Track has the path "/tracks/[TRACK ID]"
105
+ This track has a collection of users, which have access to this track, called permissions.
106
+ These can be accessed via the path "/tracks/[TRACK ID]/permission".
107
+
108
+ In ruby they are accessed like nested resources:
109
+
110
+ <pre>playlist.permissions</pre>
111
+
112
+ But have to be saved explicitly:
113
+ <pre>
114
+ playlist.permissions.push some_user
115
+ playlist.permissions.save
116
+ playlist.save</pre>
117
+
118
+ A lot of these collections are partials, that means Soundcloud API will not return more than 50 items per request.
119
+ For example the user famous_dj has 120 fans/followers. famous_dj.fans will only return 50 fans.
120
+ To get all fans you have to do something like this:
121
+ <pre>
122
+ fans = []
123
+ limit = 50
124
+ begin
125
+ some_fans = famous_dj.fans({:offset => fans.count, :limit => limit})
126
+ fans += some_fans
127
+ end while some_fans.count >= limit
128
+ </pre>
129
+
130
+ The array fans now contains all fans/followers of famous_dj.
131
+
132
+
133
+ <h3>'Single changeable' separate</h3>
134
+
135
+ Some separate collections can't be saved in a bulk request. Instead each item has to be added or removed explicitly.
136
+ For now this only affects the contacts (followees) and favorites of a user.
137
+
138
+ To add a track to the logged-in users favorites:
139
+
140
+ <pre>track.add_favorite!</pre>
141
+
142
+ Remove:
143
+
144
+ <pre>track.remove_favorite!</pre>
145
+
146
+ Check:
147
+
148
+ <pre>track.is_favorite? => true or false</pre>
149
+
150
+ The same works with the contacts of the logged-in user:
151
+
152
+ <pre>another_user.add_contact!
153
+ another_user.remove_contact!
154
+ another_user.is_contact? => true or false
155
+ </pre>
156
+
157
+ You can also check if another users follows some user or has a specific favorite:
158
+
159
+ <pre>
160
+ user.has_contact?(some_user) => true of false
161
+ user.has_favorite?(some_track) => true or false</pre>
162
+
163
+
164
+ </div></body></html>
data/VERSION.yml CHANGED
@@ -1,4 +1,4 @@
1
1
  ---
2
2
  :major: 0
3
3
  :minor: 1
4
- :patch: 5
4
+ :patch: 6
data/lib/soundcloud/models/event.rb CHANGED
@@ -1,8 +1,5 @@
1
1
  module Soundcloud
2
2
  module Models
3
-
4
- # Soundcloud Event resource
5
- #
6
3
  # Look up the resource attributes and filtering usage here:
7
4
  #
8
5
  # http://wiki.github.com/soundcloud/api/documentation#event
data/lib/soundcloud/models/playlist.rb CHANGED
@@ -1,8 +1,6 @@
1
1
  module Soundcloud
2
2
  module Models
3
- # Soundcloud Playlist resource
4
- #
5
- # Note: At the moment, you cant create or delete playlists via Soundcloud API
3
+ # Note: At the moment, you can't create or delete playlists via Soundcloud API
6
4
  #
7
5
  # Look up the resource attributes and filtering usage here:
8
6
  #
data/lib/soundcloud/models/track.rb CHANGED
@@ -1,21 +1,18 @@
1
1
  module Soundcloud
2
- module Models
3
-
4
- # Soundcloud Track resource
5
- #
2
+ module Models
6
3
  # Look up the resource attributes and filtering usage here:
7
- #
4
+ #
8
5
  # http://wiki.github.com/soundcloud/api/documentation#track
9
6
  #
10
7
  # Examples:
11
8
  #
12
- # # gets the tracks from some_user
13
- # some_user_tracks = sc_client.Track.find(:all, :from => '/users/some_user/tracks')
9
+ # # gets 50 (Soundcloud API limit) tracks from some_user
10
+ # some_user_tracks = some_user.tracks
14
11
  #
15
12
  # # gets the first song from some_user_tracks
16
13
  # first_song = some_user_tracks.first
17
14
  #
18
- # # prints all comments of first_song with username, timestamp (can be nil) and comment body
15
+ # # prints 50 (Soundcloud API limit) comments of first_song with username, timestamp (can be nil) and comment body
19
16
  # first_song.comments.each do |comment|
20
17
  # if comment.timestamp.nil?
21
18
  # timestamp = ""
@@ -26,9 +23,10 @@ module Soundcloud
26
23
  # end
27
24
  #
28
25
  #
29
- # # gets tracks with a BPM <= 100
26
+ # # gets 50 (Soundcloud API limit) tracks with a BPM <= 100
30
27
  # slow_tracks = sc_client.Track.find(:all, :params => { "bpm[to]" => "100"} )
31
28
  #
29
+ #
32
30
  # # create a new Track on Soundcloud with some_sound_file.mp3 as asset data
33
31
  # new_track = sc_client.Track.new
34
32
  # new_track.title = 'New Track'
@@ -55,8 +53,6 @@ module Soundcloud
55
53
 
56
54
  cattr_accessor :element_name
57
55
  self.element_name = 'track'
58
-
59
-
60
56
 
61
57
  def download
62
58
  raise Exception.new('Track is not downloadable') if not downloadable
data/lib/soundcloud/models/user.rb CHANGED
@@ -1,10 +1,7 @@
1
1
  module Soundcloud
2
2
  module Models
3
-
4
- # Soundcloud User resource
5
- #
6
3
  # Look up the resource attributes and filtering usage here:
7
- #
4
+ #
8
5
  # http://wiki.github.com/soundcloud/api/documentation#user
9
6
  #
10
7
  # Examples:
@@ -29,15 +26,24 @@ module Soundcloud
29
26
  # joe2.add_contact!
30
27
  #
31
28
  #
32
- # # Display all tracks of a user
29
+ # # Display 50 (Soundcloud API limit) tracks of a user
33
30
  # user = sc_client.User.find('some-user')
34
31
  # user.tracks.each do |track|
35
32
  # p track.title
36
33
  # end
37
-
34
+ #
35
+ # # Get all fans of a user
36
+ # fans = []
37
+ # limit = 50
38
+ # begin
39
+ # some_fans = famous_dj.fans({:offset => fans.count, :limit => limit})
40
+ # fans += some_fans
41
+ # end while some_fans.count >= limit
42
+ #
43
+ #
38
44
 
39
45
  class User < Base
40
- has_many :tracks, :contacts, :comments, :favorites, :playlists
46
+ has_many :tracks, :contacts, :comments, :favorites, :playlists, :fans
41
47
  has_many_single_changeable :contacts, :favorites
42
48
  can_be_a_single_changeable :contact
43
49
 
@@ -55,6 +61,9 @@ module Soundcloud
55
61
 
56
62
  class Contact < User #:nodoc:
57
63
  end
64
+
65
+ class Fan < User #:nodoc:
66
+ end
58
67
  end
59
68
  end
60
69
 
data/spec/soundcloud_user_spec.rb CHANGED
@@ -53,6 +53,15 @@ describe "Soundcloud::Models::User" do
53
53
  my_user = @sc.User.find_me
54
54
  my_user.username.should_not be nil
55
55
  end
56
+
57
+ it 'should find some fans of a user' do
58
+ @api_test_2.fans.count.should be >= 1
59
+ end
60
+
61
+ it 'should find exactly one fan / two fans' do
62
+ @api_test_2.fans({:limit => 1}).count.should be == 1
63
+ @api_test_2.fans({:limit => 2}).count.should be == 2
64
+ end
56
65
 
57
66
  end
58
67
 
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: soundcloud-ruby-api-wrapper
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.5
4
+ version: 0.1.6
5
5
  platform: ruby
6
6
  authors:
7
7
  - Johannes Wagener
@@ -40,9 +40,11 @@ extensions: []
40
40
 
41
41
  extra_rdoc_files:
42
42
  - LICENSE
43
+ - README.html
43
44
  - README.rdoc
44
45
  files:
45
46
  - LICENSE
47
+ - README.html
46
48
  - README.rdoc
47
49
  - Rakefile
48
50
  - VERSION.yml