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

#embed, #method_missing, #respond_to?

Constructor Details

#initialize(options = {}) ⇒ Playlist

Returns a new instance of Playlist.



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
114
115
 
# File 'lib/rspotify/playlist.rb', line 78

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, market: nil) ⇒ 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)
  • market (String) (defaults to: nil) —

    Optional. An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking

Returns:



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

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

  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:



74
75
76
 
# File 'lib/rspotify/playlist.rb', line 74

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>, Array<String>) —

    Tracks to be added. Either array of Tracks or strings where each string is a valid spotify track uri. 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



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/rspotify/playlist.rb', line 134

def add_tracks!(tracks, position: nil)
  track_uris = nil
  if tracks.first.is_a? String
    track_uris = tracks.join(',')
  else
    track_uris = tracks.map(&:uri).join(',')
  end
  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:



172
173
174
175
176
177
178
179
 
# File 'lib/rspotify/playlist.rb', line 172

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..."


191
192
193
 
# File 'lib/rspotify/playlist.rb', line 191

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>) 


208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/rspotify/playlist.rb', line 208

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:



287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
 
# File 'lib/rspotify/playlist.rb', line 287

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:



328
329
330
331
332
333
334
335
336
337
338
339
340
341
 
# File 'lib/rspotify/playlist.rb', line 328

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.



354
355
356
357
358
359
360
361
362
363
 
# File 'lib/rspotify/playlist.rb', line 354

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, market: nil) ⇒ 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.

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

    Optional. An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking

Returns:



237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'lib/rspotify/playlist.rb', line 237

def tracks(limit: 100, offset: 0, market: nil)
  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}"
  url << "&market=#{market}" if market
  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