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
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
All commands in the
playbackMetadata namespace also apply to the cloud queue playback. For example, you can send the
pause command in the
playback namespace to play or pause a cloud queue track on a player.
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.
||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.|
||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
||Boolean||(Optional) If true, start playback after loading the cloud queue. If you provided the
If not provided, the default value is false. If false, the player loads the cloud queue, but requires the
||number or string||(Optional) Position within the track in milliseconds. Default value is 0. If not provided and
||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.
||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
||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.|
||Boolean||(Optional) If true, the player passes the
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
playbackError, or a
For example, the player delivers an
playbackError if your app calls
loadCloudQueue with an empty queue and a
playOnCompletion value of true.
"httpAuthorization": "Bearer 1tg1343f-xyz9-300t-5380-8y4545y2p400",
"name": "Album Name"
"name": "Track Name",
"name": "Artist Name"