Sonos Developer

Players request a window of tracks in your cloud queue by specifying the itemId of a track in the cloud queue, the number of tracks before that track (the previousWindowSize), and the number of tracks after that track (the upcomingWindowSize) to be returned. This also indicates the playback policies for individual items in the cloud queue.

Optionally, the player can use this API to obtain a new access token in the response from your cloud queue server.

See GET /version for more details about the queueVersion parameter.

Request

The request contains the access token in the authorization header and the parameters in the table below.

Parameter	Type	Description
`isExplicit`	boolean	If true, indicates that a user performed a specific action or there was a specific intent to play the track. For example, the user pressed play, skipped backwards or forwards, or selected the track in the queue. If false or omitted, indicates that the player requested the track, for example, because it was the next track in the queue. You can use this to track user actions, for example, to determine if the playback stream has been initiated from another device.
`itemId`	string	The identifier for the track that should be returned. If it is omitted or an empty string, it indicates your server should return the first item in your cloud queue.
`previousWindowSize`	number	The maximum number of tracks before the track specified by the `itemId` that should be returned by your cloud queue server. A non-negative integer.
`upcomingWindowSize`	number	The maximum number of tracks after the track specified by the `itemId` that should be returned by your cloud queue server. A non-negative integer.
`queueVersion`	string	The last cloud queue change state identifier cached by the player. This could have been from: the last `GET /itemWindow` or `GET /version` response. a `loadCloudQueue` or `skipToItem` response. This is omitted when the value is unknown, for example, if the server did not respond to a query.
`reason`	string	The reason a player is requesting a new item window. See below for a list of possible values. New in v2.2: Players can send requests with multiple `reason` values separated with a + symbol. For example, `reason=load+queueCompleted`.

reason parameter

This table describes the values for the reason parameter. See reason parameter for details.

Value	Description
`load`	Sonos starts playback because of a `loadCloudQueue` command.
`pause`	An explicit user action to pause playback.
`play`	An explicit user action to start playback.
`queueCompleted`	The player has finished fetching all of the audio for the current window. The player uses this `reason` to check for more tracks.
`refresh`	The player sends this `reason` to center the current window on the track that is currently playing.
`resume`	An explicit user action to resume a suspended session. For example, the user pressed resume in the Sonos app.
`skipNext`	An explicit user action to skip to the next item.
`skipPrev`	An explicit user action to skip to the previous item.
`skipToItem`	An explicit user action to skip to an item in the queue that is neither the next item nor the previous item.

Example

Here’s an example of a GET /itemWindow request from a player. Line breaks added for readability.

GET https://www.example.com/musicqueue/v2.0/itemWindow?reason=refresh&itemId=123456&previousWindowSize=5 &upcomingWindowSize=20&queueVersion=asdf3cbjal235jazz

Here’s an example of a GET /itemWindow request from a player that has multiple reason values. Line breaks added for readability.

GET https://www.example.com/musicqueue/v2.2/itemWindow?reason=load+queueCompleted&itemId=123ABC&previousWindowSize=10 &upcomingWindowSize=20&queueVersion=NQ143rock

Response

Parameter	Type	Description
`items`	item	The list of tracks in your cloud queue that were requested by the player. See playback objects for details. Players will ignore any data that they don’t understand. Note that: The `deleted` attribute on `items` in the response is optional. It should only be set to true for the requested track (identified by the input parameter `itemId`) and only if that track has been deleted from the cloud queue. This provides a tombstone for the requested track and allows the player to know that the requested track previously existed but has been deleted. This attribute must be set to false (or omitted completely) for all other tracks. In other words, the server must omit from the `GET /itemWindow` response all deleted tracks other than the requested track. The response may include additional metadata about the track up to and including all of the fields found in the track playback object. The cloud queue server should deliver as much track metadata as is available in the `GET /itemWindow` response. Populate the `name`, `artist`, `album`, `durationMillis`, and `imageUrl` fields to ensure that all integrations can provide a good end-user experience. For example, this enables a hardware integration to display the track name and artist for music sent by a content provider. See the track object type for a list of fields that you can return. An item should contain a `mediaUrl` or a `MusicObjectId`. If an item contains both of these objects, Sonos ignores the `mediaUrl`. This is because the `MusicObjectId` resolves to a URL using SMAPI. See `MusicObjectId` and account matching for details. You must include a `contentType` to play a track.
`includesBeginningOfQueue`	boolean	Indicates that the list of tracks returned starts at the beginning of your cloud queue. Set to `true` if the list includes the beginning of your cloud queue and `false` if it does not.
`includesEndOfQueue`	boolean	Indicates that the list of tracks returned is at the end of your cloud queue. Set to `true` if the list includes the end of your cloud queue and `false` if it does not.
`contextVersion`	string	Added in v2.0. Indicates the change state of the cloud queue context such as metadata and playback policies. The player remembers this string so that it can detect changes when calling the cloud queue later.
`queueVersion`	string	Indicates the change state of the contents in the cloud queue, such as the order of tracks. When the contents change for your cloud queue server, you should also change this string. The player remembers this string so that it can detect changes when calling the cloud queue later.

If the access token is set to expire soon, an updated one is included in the X-Updated-Authorization header of the response. See Play audio for details.

Example

See playback objects for details about the item objects.

{
  "includesBeginningOfQueue": true,
  "includesEndOfQueue": false,
  "contextVersion": "context_version_string",
  "queueVersion": "asdf3cbjal235jazz",
  "items": [
  {
    "id": "this_is_the_cloud_queue_item_id",
    "deleted": false,
    "policies": {
      "canSkip": true,
      "canCrossfade": true
    },
    // track example using the mediaUrl
    "track": {
      "mediaUrl": "http://acme.example.com/path/12345.mp3",
      "contentType": "audio/mp3",
      "name": "Billie Jean",
      "imageUrl": "http://images.example.com/art1",
      "durationMillis": 293000,
      "trackNumber": 4,
      "artist": {
        "name": "Michael Jackson",
        "id": {
          "serviceId": "ACME Music Service",
          "objectId": "art987"
        }
      },
      "album": {
        "name": "Thriller",
        "id": {
          "serviceId": "ACME Music Service",
          "objectId": "alb6254"
        },
        "artist": {
          "name": "Michael Jackson"
        }
      }
    }
  },
  { // metadata example for a non-skippable ad
    "id": "this_is_the_cloud_queue_item_id2",
    "deleted": false,
    "policies": {
      "canSkip": false,
      "canCrossfade": false,
      "isVisible": false
    },
    // track example using a MusicObjectId
    "track": {
      "id": {
        "serviceId": "ACME Music Service",
        "objectId": "ab12345",
        "accountId": "acct1234"
      },
      "name": "This is a song",
      "imageUrl": "http://images.example.com/art78956",
      "durationMillis": 30000,
    }
  },
  { additional items... }
  ]
}

{

"includesBeginningOfQueue": true,

"includesEndOfQueue": false,

"contextVersion": "context_version_string",

"queueVersion": "asdf3cbjal235jazz",

"items": [

{

"id": "this_is_the_cloud_queue_item_id",

"deleted": false,

"policies": {

"canSkip": true,

"canCrossfade": true

// track example using the mediaUrl

"track": {

"mediaUrl": "http://acme.example.com/path/12345.mp3",

"contentType": "audio/mp3",

"name": "Billie Jean",

"imageUrl": "http://images.example.com/art1",

"durationMillis": 293000,

"trackNumber": 4,

"artist": {

"name": "Michael Jackson",

"id": {

"serviceId": "ACME Music Service",

"objectId": "art987"

}

"album": {

"name": "Thriller",

"id": {

"serviceId": "ACME Music Service",

"objectId": "alb6254"

"artist": {

"name": "Michael Jackson"

}

{ // metadata example for a non-skippable ad

"id": "this_is_the_cloud_queue_item_id2",

"deleted": false,

"policies": {

"canSkip": false,

"canCrossfade": false,

"isVisible": false

// track example using a MusicObjectId

"track": {

"id": {

"serviceId": "ACME Music Service",

"objectId": "ab12345",

"accountId": "acct1234"

"name": "This is a song",

"imageUrl": "http://images.example.com/art78956",

"durationMillis": 30000,

}

{ additional items... }

]

}

Error Handling

If the player sends an itemId that does not exist in the cloud queue, you should send a 404 (“Not Found”) error. The player stops playback, enters PLAYBACK_STATE_IDLE, clears the queue, and waits until the user loads more content and selects a new item for playback.

The reason can be returned in the X-Rejected-Reason HTTP header for your cloud queue server, for logging purposes. For example, you could return “ANOTHER_STREAM_BEING_PLAYED” or “STREAM_RATE_LIMIT_REACHED”.

See Error Handling for how to handle errors as well as a list of client and server errors.