One way to play audio on Sonos is by using a cloud queue, a list of tracks that you host on a server that the player can access. See Play audio for details. Use the loadCloudQueue command in the playbackSession namespace to load, and optionally start playback of, an item in a cloud queue.
This command requires that your app has an open playback session with a cloud queue, created or joined using the createSession, joinSession, or joinOrCreateSession command.
If you want to immediately start playing the track, set the playOnCompletion parameter to true. This bypasses the need to send a play command after the player loads the track. You should also send playback objects with information about the track in the trackMetadata parameter. This optimization improves the user experience by starting playback for the first track before the player fetches tracks from the cloud queue server.
After receiving the loadCloudQueue command, the player will fetch a window of tracks from the cloud queue server centered around the item with the itemId that your app provided. If the track was deleted, the group will play the next track in the queue. For more details, see the Cloud Queue API /itemWindow endpoint.
All commands in the playback and playbackMetadata namespace also apply to the cloud queue playback. For example, you can send the play or pause command in the playback namespace to play or pause a cloud queue track on a player.
Endpoint
POST
|
1 |
/playbackSessions/{sessionId}/playbackSession/loadCloudQueue |
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 |
|---|---|---|
httpAuthorization |
string | (Optional) The string value for the HTTP Authorization header, provided to the cloud queue server on all requests. The maximum value is 5120 bytes. See the Authorization for media and the cloud queue section in Play audio for details. If you don’t include this value and the player matches the session to a SMAPI user account, the Authorization header will contain the SMAPI account OAuth token. |
itemId |
string | (Optional) The identifier for the track to load. If this is an empty string (“”) or omitted, the player skips to the beginning of the cloud queue by requesting an item window with an empty string as the itemId. If you provide trackMetadata, you must also provide itemId, even if it is “”. |
playOnCompletion |
Boolean | (Optional) If true, start playback after loading the cloud queue. If you provided the trackMetadata, the player begins playback immediately. If you provided the itemId, the player starts playing once the cloud queue window returns the metadata.
If not provided, the default value is false. If false, the player loads the cloud queue, but requires the |
positionMillis |
number or string | (Optional) Position within the track in milliseconds. Default value is 0. If not provided and itemId matches the current item, the player does not interrupt playback or change the current position. The player still respects the playOnCompletion parameter, if provided. This value can be formatted as a JSON string or number. |
queueBaseUrl |
string | The base URL for the cloud queue. The player uses this to form the REST URLs used to access the cloud queue. This URL is required to end in a recognized version specification indicating the version of the Cloud Queue API supported by the server. See the Cloud queue base URL and API version section in Play audio for details.
You can pass RESTful segments within the base URL to identify the user. See the Communicate user identity in the base URL section in Play audio for details. |
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 changes, the cloud queue server would change the queueVersion. The player stores this value and can pass it back in the GET /itemWindow request. This enables your cloud-based client to keep its app and data model in sync across calls to the player. |
trackMetadata |
track | (Optional) The metadata for the first track. If provided, the player starts playing the item immediately, with the default playback policies, before the player retrieves the item window. See the track playback object type for the data structure of this object. |
useHttpAuthorizationForMedia |
Boolean | (Optional) If true, the player passes the httpAuthorization token to HTTPS media requests associated with the cloud queue. The player never sends the token to insecure (HTTP) requests. This parameter has no bearing when cloud queue items reference SMAPI objects, in which case, the player sends normal SMAPI headers. The default value is false. |
Response
Returns an empty body with a success value of true if successful.
The player generates a metadataStatus event for the loaded cloud queue track. If your app is subscribed to the playbackMetadata namespace, it will receive this notification.
The player also generates a playbackStatus event if the playback state was changed. If your app is subscribed to the playback namespace, it will receive this notification as well.
In the event of a failure, returns a sessionError, playbackError, or a globalError.
For example, the player delivers an ERROR_PLAYBACK_NO_CONTENT playbackError if your app calls loadCloudQueue with an empty queue and a playOnCompletion value of true.
Example
Request
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
{ "queueBaseUrl": "https://www.example.com/musicqueue/1243328192349892/v2.0/", "httpAuthorization": "Bearer 1tg1343f-xyz9-300t-5380-8y4545y2p400", "itemId": "abc", "queueVersion": "asdf3cbjal235jazz", "positionMillis": 30000, "playOnCompletion": false, "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" } } |