-
Notifications
You must be signed in to change notification settings - Fork 18
Playlist API Methods
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.
Echowrap.playlist_basic(:artist => 'Vampire Weekend', :results => 3) =>
[<Echowrap::Song:0x007f8fb2270a08 @attrs={:artist_id=>"AR2ZPMX1187FB4E4B6",
:id=>"SOMWTWK12AB01860CD", :artist_name=>"Vampire Weekend", :title=>"White Sky"}>,
<Echowrap::Song:0x007f8fb22709e0 @attrs={:artist_id=>"AR5AEGG1187FB4AFD2",
:id=>"SOPECCK13DC4E02E07", :artist_name=>"The Virgins", :title=>"Impressions of You"}>,
<Echowrap::Song:0x007f8fb22709b8 @attrs={:artist_id=>"ARL93GT1187B9A1057",
:id=>"SODTAZA13B0D1D86BE", :artist_name=>"Metric", :title=>"Artificial Nocturne"}>]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
- 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.
Echowrap.playlist_static(:artist => 'Empire of the Sun', :results => 3) =>
[<Echowrap::Song:0x007ff780b01448 @attrs={:artist_id=>"ARD063K11C8A422ED7",
:id=>"SOOIOAZ12AF72A4A9F", :artist_name=>"Empire of the Sun", :title=>"Without You (New Version)"}>,
<Echowrap::Song:0x007ff780b01420 @attrs={:artist_id=>"ARD063K11C8A422ED7",
:id=>"SOGJNIF12AF72A7D68", :artist_name=>"Empire of the Sun", :title=>"Suo Gan"}>,
<Echowrap::Song:0x007ff780b013f8 @attrs={:artist_id=>"ARD063K11C8A422ED7",
:id=>"SOACYKQ13F4A044137", :artist_name=>"Empire of the Sun", :title=>"Lux"}>]Creates a new dynamic playlist session. A dynamic playlist is created with an initial set of parameters that define rules for generating the playlist. A session identifier is returned that can be used with other dynamic methods to get new songs, provide feedback or to steer the playlist. Songs in the playlist can be fetched, one at a time, using the dynamic/next method. The playlist is dynamic in that it is adapted dynamically based on the listener's feedback and steering.
The dynamic playlist will adapt the playlist session based upon a number of factors:
- Played songs
- Skipped songs
- Rated songs/artists
- Favorited songs/artists
- Banned songs/artists
- Playlist steering The dynamic/create method accepts the same set of parameters as the playlist/static method with the exception of the results parameter.
A dynamic playlist session will persist as long as there is activity on the session. However, after a period of inactivity (typically 24 hours), a playlist session may be automatically expired and deleted. To retain information associated with a session (such as favorited and banned songs and artists), use a session_catalog to capture and persist the user's activity.
Echowrap.playlist_dynamic_create(:artist => 'Daft Punk') =>
<Echowrap::Playlist:0x007ff2e2ba0f18
@attrs={:status=>{:version=>"4.2", :code=>0, :message=>"Success"},
:session_id=>"8dd625f20b134c189b277c84324b392e"}Restarts a playlist session. Given the session ID and a new set of playlist parameters, this method restarts the playlist session based upon the new parameters. The session history is maintained. Everything else is reset. This method takes all the same parameters as dynamic/create, plus the session ID. Returns the given session ID.
Echowrap.playlist_dynamic_restart(:artist => 'MGMT', :session_id => '8dd625f20b134c189b277c84324b392e') =>
<Echowrap::Playlist:0x007f8824350be8
@attrs={:status=>{:version=>"4.2", :code=>0, :message=>"Success"},
:session_id=>"8dd625f20b134c189b277c84324b392e"}>Returns the next songs in the playlist. Results includes two lists of songs - one list (called next) contains the next songs to play, the other (called lookahead) contains the lookahead songs (controlled via the lookahead parameter). The next songs returned by this method will be considered to be played starting at the time the call returns. Use the dynamic/feedback method to indicate that the song was skipped or not played.
Echowrap.playlist_dynamic_next(:session_id => '8dd625f20b134c189b277c84324b392e') =>
<Echowrap::Playlist:0x007f97a228fc80
@attrs={:status=>{:version=>"4.2", :code=>0, :message=>"Success"}, :lookahead=>[],
:songs=>[{:artist_id=>"ARI3Y821187FB3649C", :id=>"SOUSJRM13779D18866", :artist_name=>"MGMT",
:title=>"4th Dimensional Transition"}]}>Give feedback on the given items (artists or songs) or the last played song. This method allows you to give user feedback such as rating, favoriting, banning of a song or artist. Feedback is applied to the item specified by the given song_id or track_id. If no song_id or track_id is specified, then the feedback is applied to the most recent song returned by dynamic/next. Multiple feedbacks can be given at any time. Specified songs need not be in the session history. This allows the pre-seeding of a session with played tracks, skipped tracks, favorites, ratings and bans.
Echowrap.playlist_dynamic_feedback(:session_id => '8dd625f20b134c189b277c84324b392e',
:favorite_song => 'SOACYKQ13F4A044137') =>
trueSteers the playlist based upon the given constraints. Steerings are additive and can be reset with the reset parameter.
Echowrap.playlist_dynamic_steer(:session_id => '8dd625f20b134c189b277c84324b392e',
:min_danceability => 0.5) =>
trueReturns information about a dynamic playlist session
Echowrap.playlist_dynamic_steer(:session_id => '8dd625f20b134c189b277c84324b392e',
:min_danceability => 0.5) =>
<Echowrap::Playlist:0x007ff062a9fa88
@attrs={:status=>{:version=>"4.2", :code=>0, :message=>"Success"}, :category_map=>{:electric=>"any", :live=>"any", :studio=>"any", :acoustic=>"any", :christmas=>"false", :childrens=>"any"},
:skipped_songs=>[], :invalid_songs=>[], :rules_run=>0, :banned_song_ids=>[],
:id=>"8dd625f20b134c189b277c84324b392e", :constraints=>{:danceability=>{:max=>nil,
:target=>nil, :name=>"danceability", :min=>0.5}}, :banned_artist_ids=>[],
:actual_history_length=>1, :seeds=>{:artist_ids=>["ARI3Y821187FB3649C"],
:genres=>[], :station_catalogs=>[], :track_ids=>[], :song_ids=>[], :descriptions=>[],
:session_catalogs=>[], :seed_catalogs=>[]}, :rules_runtime=>0,
:api_key=>"FIM8YZ2YSRNEFFP00",
:rules=>[{:rule=>"Don't put two copies of the same song in a playlist."},
{:rule=>"Prefer songs similar to: "}], :favorited_artist_ids=>[],
:restart_request_ids=>[], :call_list=>[{:action=>"create", :time=>1375642475},
{:action=>"restart", :parameters=>{:session_id=>"8dd625f20b134c189b277c84324b392e"},
:time=>1375643552}, {:action=>"next", :parameters=>{:num_lookahead=>0, :actual_lookahead=>0,
:num_results=>1, :actual_results=>1}, :time=>1375643799}, {:action=>"favorite",
:parameters=>{:song_id=>["SOACYKQ13F4A044137"], :remove=>false}, :time=>1375644608},
{:action=>"steer_value", :parameters=>{:steer_parameter=>"danceability",
:new_min=>0.5, :new_target=>nil, :new_max=>nil}, :time=>1375644785}],
:favorites_map=>{}, :song_scores=>{}, :favorited_song_ids=>["SOACYKQ13F4A044137"],
:ratings_map=>{}, :options=>{:rank_type=>"relevance", :sort=>nil, :song_types=>[], :artist_pick=>"song_hotttnesss-desc", :dmca=>false, :variety=>0.5, :buckets=>[],
:append_scores=>false, :adventurousness=>0.2, :limit=>"false", :playlist_type=>"artist",
:distribution=>"focused"}, :rules_retries=>0, :playlist_score=>0,
:invalid_artist_ids=>[], :history=>[{:title=>"4th Dimensional Transition",
:artist_name=>"MGMT", :source=>"next", :artist_id=>"ARI3Y821187FB3649C",
:id=>"SOUSJRM13779D18866", :served_time=>1375643799}]}>Deletes a previously created session. A non-commercial API can have, at most 1,000 active playlist sessions. Note that sessions that have been inactive for a period of time (at least 24 hours) may be expired and deleted automatically.
Echowrap.playlist_dynamic_delete(:session_id => '8dd625f20b134c189b277c84324b392e') =>
true