Class: RSpotify::Playlist

Inherits:
Base
  • Object
show all
Defined in:
lib/rspotify/playlist.rb

Instance Attribute Summary collapse

Attributes inherited from Base

#external_urls, #href, #id, #type, #uri

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

#method_missing, #respond_to?

Constructor Details

#initialize(options = {}) ⇒ Playlist

Returns a new instance of Playlist.



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/rspotify/playlist.rb', line 76

def initialize(options = {})
  @collaborative = options['collaborative']
  @description   = options['description']
  @followers     = options['followers']
  @images        = options['images']
  @name          = options['name']
  @public        = options['public']
  @snapshot_id   = options['snapshot_id']
  @total         = options['tracks']['total']

  @owner = if options['owner']
    User.new options['owner']
  end

  tracks = options['tracks']['items'] if options['tracks']
  tracks.select! { |t| t['track'] } if tracks

  @tracks_cache = if tracks
    tracks.map { |t| Track.new t['track'] }
  end

  @tracks_added_at = hash_for(tracks, 'added_at') do |added_at|
    Time.parse added_at
  end

  @tracks_added_by = hash_for(tracks, 'added_by') do |added_by|
    User.new added_by
  end

  @tracks_is_local = hash_for(tracks, 'is_local') do |is_local|
    is_local
  end

  super(options)

  @path = "users/#{@owner.instance_variable_get('@id')}/"
  @path << (@href =~ /\/starred$/ ? 'starred' : "playlists/#{@id}")
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class RSpotify::Base

Instance Attribute Details

#collaborative ⇒ Boolean

true if the owner allows other users to modify the playlist

Returns:

  • (Boolean) —

    the current value of collaborative



15
16
17
 
# File 'lib/rspotify/playlist.rb', line 15

def collaborative
  @collaborative
end

#description ⇒ String

The playlist description

Returns:

  • (String) —

    the current value of description



15
16
17
 
# File 'lib/rspotify/playlist.rb', line 15

def description
  @description
end

#followers ⇒ Hash

Information about the followers of the playlist

Returns:

  • (Hash) —

    the current value of followers



15
16
17
 
# File 'lib/rspotify/playlist.rb', line 15

def followers
  @followers
end

#images ⇒ Array<Hash>

Images for the playlist. The array may be empty or contain up to three images. The images are returned by size in descending order. If returned, the source URL for the image is temporary and will expire in less than one day.

Returns:

  • (Array<Hash>) —

    the current value of images



15
16
17
 
# File 'lib/rspotify/playlist.rb', line 15

def images
  @images
end

#name ⇒ String

The name of the playlist

Returns:

  • (String) —

    the current value of name



15
16
17
 
# File 'lib/rspotify/playlist.rb', line 15

def name
  @name
end

#owner ⇒ User

The user who owns the playlist

Returns:

  • (User) —

    the current value of owner



15
16
17
 
# File 'lib/rspotify/playlist.rb', line 15

def owner
  @owner
end

#public ⇒ Boolean

true if the playlist is not marked as secret

Returns:

  • (Boolean) —

    the current value of public



15
16
17
 
# File 'lib/rspotify/playlist.rb', line 15

def public
  @public
end

#snapshot_id ⇒ String

The version identifier for the current playlist. This attribute gets updated every time the playlist changes and can be supplied in other requests to target a specific playlist version

Returns:

  • (String) —

    the current value of snapshot_id



15
16
17
 
# File 'lib/rspotify/playlist.rb', line 15

def snapshot_id
  @snapshot_id
end

#total ⇒ Integer

The total number of tracks in the playlist

Returns:

  • (Integer) —

    the current value of total



15
16
17
 
# File 'lib/rspotify/playlist.rb', line 15

def total
  @total
end

#tracks_added_at ⇒ Hash

A hash containing the date and time each track was added to the playlist. Note: the hash is updated only when #tracks is used.

Returns:

  • (Hash) —

    the current value of tracks_added_at



15
16
17
 
# File 'lib/rspotify/playlist.rb', line 15

def tracks_added_at
  @tracks_added_at
end

#tracks_added_by ⇒ Hash

A hash containing the user that added each track to the playlist. Note: the hash is updated only when #tracks is used.

Returns:

  • (Hash) —

    the current value of tracks_added_by



15
16
17
 
# File 'lib/rspotify/playlist.rb', line 15

def tracks_added_by
  @tracks_added_by
end

#tracks_is_local ⇒ Hash

A hash showing whether each track is local or not. Note: the hash is updated only when #tracks is used.

Returns:

  • (Hash) —

    the current value of tracks_is_local



15
16
17
 
# File 'lib/rspotify/playlist.rb', line 15

def tracks_is_local
  @tracks_is_local
end

Class Method Details

Get a list of Spotify featured playlists (shown, for example, on a Spotify player’s “Browse” tab).

Examples:

playlists = RSpotify::Playlist.browse_featured
playlists = RSpotify::Playlist.browse_featured(locale: 'es_MX', limit: 10)
playlists = RSpotify::Playlist.browse_featured(country: 'US', timestamp: '2014-10-23T09:00:00')

Parameters:

  • limit (Integer) (defaults to: 20) —

    Maximum number of playlists to return. Maximum: 50. Default: 20.

  • offset (Integer) (defaults to: 0) —

    The index of the first playlist to return. Use with limit to get the next set of playlists. Default: 0.

  • country (String) —

    Optional. A country: an ISO 3166-1 alpha-2 country code. Provide this parameter if you want the list of returned playlists to be relevant to a particular country. If omitted, the returned playlists will be relevant to all countries.

  • locale (String) —

    Optional. The desired language, consisting of a lowercase ISO 639 language code and an uppercase ISO 3166-1 alpha-2 country code, joined by an underscore. For details access / here and look for the locale parameter description.

  • timestamp (String) —

    Optional. A timestamp in ISO 8601 format: yyyy-MM-ddTHH:mm:ss. Use this parameter to specify the user’s local time to get results tailored for that specific date and time in the day. If not provided, the response defaults to the current UTC time. Example: “2014-10-23T09:00:00” for a user whose local time is 9AM.

Returns:



30
31
32
33
34
35
36
37
38
39
 
# File 'lib/rspotify/playlist.rb', line 30

def self.browse_featured(limit: 20, offset: 0, **options)
  url = "browse/featured-playlists?limit=#{limit}&offset=#{offset}"
  options.each do |option, value|
    url << "&#{option}=#{value}"
  end

  response = RSpotify.get(url)
  return response if RSpotify.raw_response
  response['playlists']['items'].map { |i| Playlist.new i }
end

.find(user_id, id) ⇒ Playlist

Returns Playlist object with user_id and id provided. If id is “starred”, returns starred playlist from user.

Examples:

playlist = RSpotify::Playlist.find('wizzler', '00wHcTN0zQiun4xri9pmvX')
playlist.class #=> RSpotify::Playlist
playlist.name  #=> "Movie Soundtrack Masterpieces"

Parameters:

  • user_id (String)
  • id (String)

Returns:



51
52
53
54
55
56
57
58
 
# File 'lib/rspotify/playlist.rb', line 51

def self.find(user_id, id)
  url = "users/#{user_id}/"
  url << (id == 'starred' ? id : "playlists/#{id}")

  response = RSpotify.resolve_auth_request(user_id, url)
  return response if RSpotify.raw_response
  Playlist.new response
end

.search(query, limit: 20, offset: 0) ⇒ Array<Playlist>

Returns array of Playlist objects matching the query. It’s also possible to find the total number of search results for the query

Examples:

playlists = RSpotify::Playlist.search('Indie')
playlists = RSpotify::Playlist.search('Indie', limit: 10)

RSpotify::Playlist.search('Indie').total #=> 14653

Parameters:

  • query (String) —

    The search query’s keywords. See the q description in here for details.

  • limit (Integer) (defaults to: 20) —

    Maximum number of playlists to return. Maximum: 50. Default: 20.

  • offset (Integer) (defaults to: 0) —

    The index of the first playlist to return. Use with limit to get the next set of playlists. Default: 0.

Returns:



72
73
74
 
# File 'lib/rspotify/playlist.rb', line 72

def self.search(query, limit: 20, offset: 0)
  super(query, 'playlist', limit: limit, offset: offset)
end

Instance Method Details

#add_tracks!(tracks, position: nil) ⇒ Array<Track>

Adds one or more tracks to a playlist in user’s Spotify account. This method is only available when the current user has granted access to the playlist-modify-public and playlist-modify-private scopes.

Examples:

tracks = RSpotify::Track.search('Know', 30)
playlist = user.create_playlist!('my-awesome-playlist')

playlist.add_tracks!(tracks)
playlist.tracks.size       #=> 30
playlist.tracks.first.name #=> "Somebody That I Used To Know"

playlist.add_tracks!(tracks, position: 20)
playlist.tracks[20].name #=> "Somebody That I Used To Know"

Parameters:

  • tracks (Array<Track>) —

    Tracks to be added. Maximum: 100 per request

  • position (Integer, NilClass) (defaults to: nil) —

    The position to insert the tracks, a zero-based index. Default: tracks are appended to the playlist

Returns:

  • (Array<Track>) —

    The tracks added



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/rspotify/playlist.rb', line 132

def add_tracks!(tracks, position: nil)
  track_uris = tracks.map(&:uri).join(',')
  url = "#{@path}/tracks?uris=#{track_uris}"
  url << "&position=#{position}" if position

  response = User.oauth_post(@owner.id, url, {})
  @total += tracks.size
  @tracks_cache = nil

  if RSpotify::raw_response
    @snapshot_id = JSON.parse(response)['snapshot_id']
    return response
  end

  @snapshot_id = response['snapshot_id']
  tracks
end

#change_details!(**data) ⇒ Playlist

Change name and public/private state of playlist in user’s Spotify account. Changing a public playlist requires the playlist-modify-public scope; changing a private playlist requires the playlist-modify-private scope.

Examples:

playlist.name   #=> "Movie Soundtrack Masterpieces"
playlist.public #=> true

playlist.change_details!(name: 'Movie Tracks', public: false)

playlist.name   #=> "Movie Tracks"
playlist.public #=> false

Parameters:

  • name (String) —

    Optional. The new name for the playlist.

  • public (Boolean) —

    Optional. If true the playlist will be public, if false it will be private.

Returns:



165
166
167
168
169
170
171
172
 
# File 'lib/rspotify/playlist.rb', line 165

def change_details!(**data)
  User.oauth_put(@owner.id, @path, data.to_json)
  data.each do |field, value|
    instance_variable_set("@#{field}", value)
  end
  @snapshot_id = nil
  self
end

#complete! ⇒ Object

Note:

It is seldom necessary to use this method explicitly, since RSpotify takes care of it automatically when needed (see Base#method_missing)

When an object is obtained undirectly, Spotify usually returns a simplified version of it. This method updates it into a full object, with all attributes filled.

Examples:

playlist = user.playlists.first
playlist.instance_variable_get("@description") #=> nil
playlist.complete!
playlist.instance_variable_get("@description") #=> "Iconic soundtracks..."


184
185
186
 
# File 'lib/rspotify/playlist.rb', line 184

def complete!
  initialize RSpotify.resolve_auth_request(@owner.id, @path)
end

#is_followed_by?(users) ⇒ Array<Boolean>

Check if one or more Spotify users are following a specified playlist. Checking if the user is privately following a playlist is only possible if he/she has granted access to the playlist-read-private scope.

Examples:

user1 = RSpotify::User.find('<some-id>')
user2 = RSpotify::User.find('<some-other-id>')
playlist.is_followed_by?([user1, user2]) #=> [true, true] (Users publicly following playlist)

oauth-user = RSpotify::User.new(request.env['omniauth.auth']) # (See OAuth section in readme)
playlist.is_followed_by?([oauth-user]) #=> [true] (User publicly or privately following playlist)

Parameters:

  • users (Array<User>) —

    The users to check. Maximum: 5.

Returns:

  • (Array<Boolean>) 


201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/rspotify/playlist.rb', line 201

def is_followed_by?(users)
  user_ids = users.map(&:id).join(',')
  url = "#{@path}/followers/contains?ids=#{user_ids}"

  users_credentials = if User.class_variable_defined?('@@users_credentials')
    User.class_variable_get('@@users_credentials')
  end

  auth_users = users.select do |user|
    users_credentials[user.id]
  end if users_credentials

  if auth_users && auth_users.any?
    User.oauth_get(auth_users.first.id, url)
  else
    RSpotify.get(url)
  end
end

#remove_tracks!(tracks, snapshot_id: nil) ⇒ Playlist

Remove one or more tracks from a user’s playlist. Removing from a public playlist requires the playlist-modify-public scope; removing from a private playlist requires the playlist-modify-private scope.

Examples:

# Remove all occurrences of one or more tracks
love_tracks = RSpotify::Track.search('Love')
playlist.remove_tracks!(love_tracks)

# Remove specific occurrences of one or more tracks
track = RSpotify::Track.find('tR3oH...')
playlist.remove_tracks!([{track: track, positions: [0,3]}, other_track])

# Remove tracks based only on their positions (requires snapshot id)
positions = [0,3,8]
playlist.remove_tracks!(positions, snapshot_id: '0ZvtH...')

Parameters:

  • tracks (Array<Track,Hash>, Array<Integer>) —

    Tracks to be removed. Maximum: 100 per request

  • snapshot_id (String) (defaults to: nil) —

    Optional. The playlist’s snapshot ID against which you want to make the changes.

Returns:



278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/rspotify/playlist.rb', line 278

def remove_tracks!(tracks, snapshot_id: nil)
  positions = tracks if tracks.first.is_a? Fixnum

  tracks = tracks.map do |track|
    next { uri: track.uri } if track.is_a? Track
    {
      uri: track[:track].uri,
      positions: track[:positions]
    }
  end unless positions

  params = {
    method: :delete,
    url: URI::encode(RSpotify::API_URI + @path + '/tracks'),
    headers: User.send(:oauth_header, @owner.id),
    payload: positions ? { positions: positions } : { tracks: tracks }
  }

  params[:payload][:snapshot_id] = snapshot_id if snapshot_id
  params[:payload] = params[:payload].to_json
  response = RestClient::Request.execute(params)

  @snapshot_id = JSON.parse(response)['snapshot_id']
  @tracks_cache = nil
  self
end

#reorder_tracks!(range_start, insert_before, **options) ⇒ Playlist

Reorder a track or a group of tracks in a playlist. Changing a public playlist requires the playlist-modify-public scope; changing a private playlist requires the playlist-modify-private scope.

Examples:

range_start = 10
insert_before = 0
# Move the tracks at index 10-14 to the start of the playlist
playlist.reorder_tracks!(range_start, insert_before, range_length: 5)

Parameters:

  • range_start (Integer) —

    The position of the first track to be reordered.

  • insert_before (Integer) —

    The position where the tracks should be inserted. To reorder the tracks to the end of the playlist, simply set insert_before to the position after the last track.

  • range_length (Integer) —

    Optional. The amount of tracks to be reordered. Default: 1.

  • snapshot_id (String) —

    Optional. The playlist’s snapshot ID against which you want to make the changes.

Returns:



319
320
321
322
323
324
325
326
327
328
329
330
331
332
 
# File 'lib/rspotify/playlist.rb', line 319

def reorder_tracks!(range_start, insert_before, **options)
  url = "#{@path}/tracks"
  data = {
    range_start: range_start,
    insert_before: insert_before
  }.merge options

  response = User.oauth_put(@owner.id, url, data.to_json)
  json = RSpotify.raw_response ? JSON.parse(response) : response

  @snapshot_id = json['snapshot_id']
  @tracks_cache = nil
  self
end

#replace_tracks!(tracks) ⇒ Array<Track>

Replace all the tracks in a playlist, overwriting its existing tracks. Changing a public playlist requires the playlist-modify-public scope; changing a private playlist requires the playlist-modify-private scope.

Examples:

playlist.tracks.map(&:name) #=> ["All of Me", "Wasted Love", "Love Runs Out"]
tracks = RSpotify::Track.search('Know', limit: 2)
playlist.replace_tracks!(tracks)
playlist.tracks.map(&:name) #=> ["Somebody That I Used To Know", "Do I Wanna Know?"]

Parameters:

  • tracks (Array<Track>) —

    The tracks that will replace the existing ones. Maximum: 100 per request

Returns:

  • (Array<Track>) —

    The tracks that were added.



345
346
347
348
349
350
351
352
353
354
 
# File 'lib/rspotify/playlist.rb', line 345

def replace_tracks!(tracks)
  track_uris = tracks.map(&:uri).join(',')
  url = "#{@path}/tracks?uris=#{track_uris}"
  User.oauth_put(@owner.id, url, {})

  @total = tracks.size
  @tracks_cache = nil
  @snapshot_id = nil
  tracks
end

#tracks(limit: 100, offset: 0) ⇒ Array<Track>

Returns array of tracks from the playlist

Examples:

playlist = RSpotify::Playlist.find('wizzler', '00wHcTN0zQiun4xri9pmvX')
playlist.tracks.first.name #=> "Main Theme from Star Wars - Instrumental"

Parameters:

  • limit (Integer) (defaults to: 100) —

    Maximum number of tracks to return. Maximum: 100. Default: 100.

  • offset (Integer) (defaults to: 0) —

    The index of the first track to return. Use with limit to get the next set of objects. Default: 0.

Returns:



229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/rspotify/playlist.rb', line 229

def tracks(limit: 100, offset: 0)
  last_track = offset + limit - 1
  if @tracks_cache && last_track < 100 && !RSpotify.raw_response
    return @tracks_cache[offset..last_track]
  end

  url = "#{@path}/tracks?limit=#{limit}&offset=#{offset}"
  response = RSpotify.resolve_auth_request(@owner.id, url)

  json = RSpotify.raw_response ? JSON.parse(response) : response
  tracks = json['items'].select { |i| i['track'] }

  @tracks_added_at = hash_for(tracks, 'added_at') do |added_at|
    Time.parse added_at
  end

  @tracks_added_by = hash_for(tracks, 'added_by') do |added_by|
    User.new added_by
  end

  @tracks_is_local = hash_for(tracks, 'is_local') do |is_local|
    is_local
  end

  tracks.map! { |t| Track.new t['track'] }
  @tracks_cache = tracks if limit == 100 && offset == 0
  return response if RSpotify.raw_response
  tracks
end