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.



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/rspotify/playlist.rb', line 51

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

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

  @tracks_cache = if options['tracks'] && options['tracks']['items']
    options['tracks']['items'].map { |i| Track.new i['track'] }
  end

  super(options)
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



10
11
12
 
# File 'lib/rspotify/playlist.rb', line 10

def collaborative
  @collaborative
end

#description ⇒ String

The playlist description

Returns:

  • (String) —

    the current value of description



10
11
12
 
# File 'lib/rspotify/playlist.rb', line 10

def description
  @description
end

#followers ⇒ Hash

Information about the followers of the playlist

Returns:

  • (Hash) —

    the current value of followers



10
11
12
 
# File 'lib/rspotify/playlist.rb', line 10

def followers
  @followers
end

#images ⇒ Array<Hash>

The playlist images

Returns:

  • (Array<Hash>) —

    the current value of images



10
11
12
 
# File 'lib/rspotify/playlist.rb', line 10

def images
  @images
end

#name ⇒ String

The name of the playlist

Returns:

  • (String) —

    the current value of name



10
11
12
 
# File 'lib/rspotify/playlist.rb', line 10

def name
  @name
end

#owner ⇒ User

The user who owns the playlist

Returns:

  • (User) —

    the current value of owner



10
11
12
 
# File 'lib/rspotify/playlist.rb', line 10

def owner
  @owner
end

#public ⇒ Boolean

true if the playlist is not marked as secret

Returns:

  • (Boolean) —

    the current value of public



10
11
12
 
# File 'lib/rspotify/playlist.rb', line 10

def public
  @public
end

Class Method Details

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



22
23
24
25
26
27
28
29
30
 
# File 'lib/rspotify/playlist.rb', line 22

def self.find(user_id, id)
  url = if id == "starred"
    "users/#{user_id}/starred"
  else
    "users/#{user_id}/playlists/#{id}"
  end
  json = RSpotify.resolve_auth_request(user_id, url)
  Playlist.new json
end

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

Returns array of playlist objects matching the query

Examples:

playlists = RSpotify::Playlist.search('Soundtrack')
playlists.size        #=> 20
playlists.first.class #=> RSpotify::Playlist
playlists.first.name  #=> ""

playlists = RSpotify::Playlist.search('Soundtrack', limit: 10)
playlists.size #=> 10

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:



47
48
49
 
# File 'lib/rspotify/playlist.rb', line 47

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



87
88
89
90
91
92
93
94
95
 
# File 'lib/rspotify/playlist.rb', line 87

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

  User.oauth_post(@owner.id, url, {})
  @tracks_cache = nil
  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 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:



112
113
114
115
116
117
118
 
# File 'lib/rspotify/playlist.rb', line 112

def change_details!(**data)
  User.oauth_put(@owner.id, @href, data.to_json)
  data.each do |field, value|
    instance_variable_set("@#{field}", value)
  end
  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..."


130
131
132
 
# File 'lib/rspotify/playlist.rb', line 130

def complete!
  initialize RSpotify.resolve_auth_request(@owner.id, @href)
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 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.



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

def replace_tracks!(tracks)
  track_uris = tracks.map(&:uri).join(',')
  url = @href + "/tracks?uris=#{track_uris}"
  User.oauth_put(@owner.id, url, {})
  @tracks_cache = 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:



143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/rspotify/playlist.rb', line 143

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

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

  tracks = json['items'].map do |i|
    Track.new i['track'] unless i['track'].nil?
  end.compact

  @tracks_cache = tracks if limit == 100 && offset == 0
  tracks
end