Module: Echowrap::API::Playlist

Includes:: Utils

Included in:: Client

Defined in:: lib/echowrap/api/playlist.rb

Constant Summary

Constants included from Utils

Utils::API_KEY_CANNOT_CALL_THIS_METHOD, Utils::INVALID_PARAMETER, Utils::MISSING_OR_INVALID_KEY, Utils::MISSING_PARAMETER, Utils::RATE_LIMIT_EXCEEDED, Utils::SUCCESS

Instance Method Summary collapse

Instance Method Details

#playlist_basic(options = {}) ⇒ `Array`, `Array<Echowrap::Song>`

Returns a basic playlist. A basic playlist is generated once from an initial set of parameters, and returned as an ordered list of songs. Basic playlist functionality is supported, see the static and dynamic playlist APIs for advanced contextual and personalized playlisting. Some properties of a basic playlist:

Songs are never repeated
Artists may be repeated

A number of different algorithms can be used to select songs for the playlist. These are specified with the type parameter.

Examples:

Return an array of songs with artist ‘Daft Punk’

Echowrap.playlist_basic(:artist => "Daft Punk")

Parameters:

options (Hash) (defaults to: {}) —

A customizable set of options.

Options Hash (options):

:type (String) —

The type of the playlist to be generated. Not required, must be one of [‘artist-radio’, ‘song-radio’, ‘genre-radio’]
:artist_id (String) —

ID(s) of seed artist(s) for the playlist. Echo Nest or Rosetta IDs. Not required, may use multiple, no more than 5 total artist_id, artist, track_id, and song_id parameters. Example: ‘ARH6W4X1187B99274F’ or ‘7digital-US:artist:304’.
:artist (String) —

Name(s) of seed artist(s) for the playlist. Not required, may use multiple, no more than 5 total artist_id, artist, track_id, and song_id parameters. Example: ‘Weezer, the+beatles’.
:song_id (String) —

ID(s) of seed song(s) for the playlist. Echo Nest or Rosetta IDs. Not required, may use multiple, no more than 5 total artist_id, artist, track_id, and song_id parameters. Example: ‘SOCZMFK12AC468668F’.
:genre (String) —

A musical genre such as rock, jazz, or dance pop. See the artist method list_genres for details on what genres are currently available, only allowed for genre-radio playlist types and required for genre-radio playlist types. Example: ‘jazz, metal’.
:track_id (String) —

ID(s) of seed track(s) for the playlist. Echo Nest or Rosetta IDs. Not required, may use multiple, no more than 5 total artist_id, artist, track_id, and song_id parameters. Example: ‘TRTLKZV12E5AC92E11’.
:results (Integer) —

The desired number of songs in the playlist, the valid range is 0 to 100, with 15 as the default
:bucket (String) —

Specifies which extra information should be returned in the playlist. Not require, may use multiple, must be one of [‘id:catalog-name’, ‘tracks’]. When specifying idspace buckets (those starting with “id:”) the results will be returned in a “foreign_ids” key/element. See Project Rosetta Stone for more information on ID spaces. Example: “tracks”.
:limit (String) —

If ‘true’, limit the results to any of the given rosetta id space. Must be on of [‘true’, ‘false’] with ‘false’ as the default. If limit is set to anything but false, at least one idspace must also be provided in the bucket parameter.
:dmca (String) —

If true or ‘styleb’ the playlist delivered will meet the DMCA rules. When the DMCA parameter is set to true, the playlist will conform to the following rules: No more than 2 songs in a row from the same album, no more than 3 songs from an album in a 3 hour period, no more than 3 different songs in a row by the same artist, no more than 4 songs by the same artist in a 3 hour period. Skipped songs are not considered to have been played for DMCA conformance purposes. If dmca is set to ‘styleb’, skipped songs are considered to have been played for DMCA purposes.

Returns:

(Array) —

Array of songs.
(Array<Echowrap::Song>)

Raises:

(Echowrap::Error::Unauthorized) —

Error raised when supplied api key is not valid.

#playlist_dynamic_create(options = {}) ⇒ `Object`



122
123
124

# File 'lib/echowrap/api/playlist.rb', line 122

def playlist_dynamic_create(options={})
  object_from_response(Echowrap::Playlist, :get, '/api/v4/playlist/dynamic/create', nil, options)
end

#playlist_dynamic_delete(options = {}) ⇒ `Object`



243
244
245

# File 'lib/echowrap/api/playlist.rb', line 243

def playlist_dynamic_delete(options={})
  boolean_from_response(:get, '/api/v4/playlist/dynamic/delete', options)
end

#playlist_dynamic_feedback(options = {}) ⇒ `Object`



182
183
184

# File 'lib/echowrap/api/playlist.rb', line 182

def playlist_dynamic_feedback(options={})
  boolean_from_response(:get, '/api/v4/playlist/dynamic/feedback', options)
end

#playlist_dynamic_info(options = {}) ⇒ `Object`



227
228
229

# File 'lib/echowrap/api/playlist.rb', line 227

def playlist_dynamic_info(options={})
  object_from_response(Echowrap::Playlist, :get, '/api/v4/playlist/dynamic/info', nil, options)
end

#playlist_dynamic_next(options = {}) ⇒ `Object`



156
157
158

# File 'lib/echowrap/api/playlist.rb', line 156

def playlist_dynamic_next(options={})
  object_from_response(Echowrap::Playlist, :get, '/api/v4/playlist/dynamic/next', nil, options)
end

#playlist_dynamic_restart(options = {}) ⇒ `Object`



138
139
140

# File 'lib/echowrap/api/playlist.rb', line 138

def playlist_dynamic_restart(options={})
  object_from_response(Echowrap::Playlist, :get, '/api/v4/playlist/dynamic/restart', nil, options)
end

#playlist_dynamic_steer(options = {}) ⇒ `Object`



211
212
213

# File 'lib/echowrap/api/playlist.rb', line 211

def playlist_dynamic_steer(options={})
  boolean_from_response(:get, '/api/v4/playlist/dynamic/steer', options)
end

#playlist_static(options = {}) ⇒ `Array`, `Array<Echowrap::Song>`

Returns a static playlist. A static playlist is generated once from an initial set of parameters, and returned as an ordered list of songs. Some properties of a static playlist:

Songs are never repeated
Artist may be repeated