Use the skipToItem command in the playbackSession namespace to skip to the track with the specified itemId in a cloud queue and optionally seek and initiate playback. This command requires your app to have either created a new session or joined an existing session, and also loaded a cloud queue on the group with loadCloudQueue.
Use playOnCompletion to start playing the cloud queue item being loaded, so your app doesn’t have to send an extra play command.
Most of the times your app already has access to the track metadata of the cloud queue item that is being loaded. Use the optional trackMetadata parameter to provide that information so the group can start playing the track immediately after receiving the loadCloudQueue command. This optimization improves the user experience by starting playback before the player fetches tracks from the cloud queue server.
Endpoint
POST
|
1 |
/playbackSessions/{sessionId}/playbackSession/skipToItem |
Request Parameters
This command requires a sessionId to determine the target of the command. See the Control documentation for details.
See the table below for descriptions of parameters in the body.
| Parameter | Type | Value |
|---|---|---|
itemId |
string | The identifier for the track. This is required, but does not need to be a value. If it is an empty string, the group will skip to the beginning of the queue. |
playOnCompletion |
boolean | (Optional) Start playback after loading. |
positionMillis |
number or string | (Optional) Position within track in milliseconds. If you omit this parameter and send a different itemId than the one that is currently playing, the player assumes that the positionMillis is zero. If you omit this parameter and send the itemId that is currently playing, the player does not change the position, and continues playing. |
queueVersion |
string | (Optional) An opaque identifier used to indicate the change state of the contents in the cloud queue. For example, if the list of tracks in the cloud queue change, the cloud queue server would change the queueVersion. The player stores this value and can pass it back in the GET /itemWindow request. |
trackMetadata |
track | (Optional) The target track to play. Entering this value enables the player to load and start playing the track immediately. See the track playback object for the data structure of this object. |
Response
Returns an empty body with a success value of true if successful. The player generates a metadataStatus event for the new cloud queue track. If your app is subscribed to the playbackMetadata namespace, it will receive this event notification. If your app is subscribed to the playback namespace, it will also receive a playbackStatus event notification if the playback state was changed.
In the event of a failure, returns a playbackError, sessionError, or globalError.
Example
Request
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
{ "itemId": "abc", "queueVersion": "asdf3cbjal235jazz", "positionMillis": 30000, "playOnCompletion": true, "trackMetadata": { "album": { "name": "Album Name" }, "name": "Track Name", "artist": { "name": "Artist Name" }, "imageUrl": "http://example.com/path_to_image_url", "durationMillis": 319000, "contentType": "audio/mpeg", "mediaUrl": "http://example.com/path_to_track_url" } } |