Playback objects

Playback objects are collections of data about the audio items that Sonos can play. Playback objects contain information such as the title of the track, the name of the artist, or a link to the album art. You can receive playback objects in the currentItem and nextItem parameters in the getMetadataStatus event. You can send playback objects in the trackMetadata parameter in loadCloudQueue and skipToItem. You can also send playback objects in responses to the cloud queue GET /itemWindow endpoint with a MusicObjectId or a mediaUrl.

🚧

Some of these objects are still in development. Your app should ignore any objects or keys that it can't handle.


album

The album for the track.

KeyTypeRequiredValue
namestringYesThe name of the album. Maximum length of 76 characters.
artistartistNoThe artist for the album. See below for details.
imageUrlstringNoA URL to an image of the album, typically a JPG or PNG.
idMusicObjectIdNoThe unique music service object id for this album; identifies the album within the music service from which the track originated. See below for details.
tagsarray of enumsNoA tag for the track. Currently the only value is "TAG_EXPLICIT" to indicate that the album includes explicit content. Players will not include this key and value if it is empty.

artist

The artist of the track.

KeyTypeRequiredValue
namestringYesThe name of the artist. Maximum length of 76 characters.
imageUrlstringNoA URL to an image of the artist, typically a JPG or PNG.
idMusicObjectIdNoThe unique music service object id for this artist; identifies the artist within the music service from which the track originated. See below for details.
tagsarray of enumsNoA tag for the track. Currently the only value is "TAG_EXPLICIT" to indicate that the artist includes explicit content. Players will not include this key and value if it is empty.

container

A source of music. A container represents a program on a radio station, a playlist, a line-in source, or some other source of audio.

KeyTypeRequiredValue
namestringYesThe name of the container.
typestringNoThe type of source. Possible values include:

- - album — a playable album.
- artist — an artist container.
- audiobook — a type of tracklist where each track is a chapter in a book.
- container — a non-playable container.
- episode — a playable episode, podcast or otherwise.
- item — a generic container. This is the default source if none is provided.
- linein — a stream of audio representing some sort of physical or virtual audio input to the Sonos system.
- linein.homeTheater — a stream of audio from a home theater device.
- playlist — a playlist or other collection of tracks.
- show — a playable show.
- station — a streaming radio station.
- station.broadcast — a playable live broadcast station.
- track — a single playable track.
- trackList — a list of tracks.
- trackList.program — a programmed list of tracks, such as on a programmed radio station. Programmed radio periodically updates the finite list of tracks to give the perception of an infinite list of tracks.
idMusicObjectIdNoThe unique music service object ID for this track; identifies the track within the music service from which the track originated. See below for details.
serviceServiceNoA service object describing the music service for this music source.
imageUrlstringNoA URL to an image (typically a JPG or PNG) representing the music service. This should be absolute Internet-based and require no authorization to retrieve.
tagsarray of enumsNoA tag for the container. Currently the only value is "TAG_EXPLICIT" to indicate that the contents of the container include explicit content. Players will not include this key and value if it is empty.

Here's an example of a radio station without tags:

{
  "name": "Bruce Springsteen Radio",
  "type": "trackList.program",
  "id": {
    "serviceId": "7",              // Sonos id for the service
    "objectId": "program:52981234" // unique id for the program
  },
  "service": {
    "id": "7",
    "name": "Acme Music Service"
  },
  "imageUrl": "http://images.example.com/program_art.jpg"
}

item

An item in a queue. Used for cloud queue tracks and radio stations that have track-like data for the currently playing content. For example, the currentItem and nextItem parameters in the metadataStatus event are item object types.

KeyTypeRequiredValue
idstringNoThe cloud queue itemId for the track. Only present if the track is from a cloud queue. Maximum length of 128 characters.
tracktrackYesThe track data. See below for details.
deletedbooleanNoWhether the track was deleted or not; true if deleted and false if not. This should be used by the cloud queue server.
policiespoliciesNoCertain policies can be overridden by item. See the policies object type below for details.

musicObjectId

The music object identifier for the item in a music service. This identifies the content within a music service, the music service, and the account associated with the content.

KeyTypeRequiredValue
serviceIdstringNoThe unique identifier for the music service. Maximum length of 20 characters. If you omit this, the player uses the accountId (if provided) to look up the service ID.
objectIdstringYesThe unique identifier for the particular piece of content within the music service. Maximum length of 256 characters.
accountIdstringNoThe music service account to use on Sonos for playback in the session. See account matching for details. Maximum length of 13 characters. If omitted and the household has multiple accounts for the music service, Sonos will use the accountId based on the following order of precedence (if the accountId is omitted from the first item below, it uses the next item):

1. In the item metadata from the GET /itemWindow endpoint (for example, from the id for a track).
2. In the container metadata from the GET /context endpoint.
3. In the command used to load the content or queue up the tracks (such as createSession or  loadCloudQueue).While optional, you should provide the accountId using one of these methods.

policies

You can provide track-level playback policies in the policies object. Here's an example:

{
  "policies": {
      "canSkip": false,
      "canSkipToItem": false,
      "canCrossfade": false,
      "isVisible": false
  }
}

See Playback policy list for a list of track-level playback policies and descriptions. See Set playback policies for details about how to use playback policies.


positionInformation

The position of the playback head. A Sonos player uses this Control API object to skip to a specific location in the play list. This is similar to the SMAPI positionInformation object.

KeyTypeRequiredValue
itemIdstringYesThe identifier of the item
positionMillisnumberNoAn offset, in milliseconds, within the item.

Here's an example:

{
    "itemId": "abc123",
    "positionMillis": 33123
}

service

The music service identifier or a pseudo-service identifier in the case of local library.

KeyTypeRequiredValue
namestringYesThe name of the service.
idstringNoThe unique identifier for the music service. This can be the same as the serviceId value in the MusicObjectId. A value of "locallibrary" represents the content available from the local library.
imageUrlstringNoA URL to an image (typically a JPG or PNG) representing the music service. This should be absolute Internet-based and require no authorization to retrieve.

track

A single music track or audio file. Tracks are identified by type, which determines the key values for the object types included. The following fields are shared by all types of tracks.

KeyTypeRequiredValue
canCrossfadebooleanNoSet to false to prevent audio crossfade from involving this track regardless of the prevailing playback policy. Default is true.
canSkipbooleanNoSet to false to prevent skipping this track regardless of the prevailing playback policy. Default is true.
durationMillisnumberNoThe duration of the track, in milliseconds, for example, 210000 for a 3 and a half minute song. Use a value of 0 to hide the progress bar. The Sonos app will not display the time played or the time left and the user will not be able to seek.
idMusicObjectIdNoThe unique music service object ID for this track; identifies the track within the music service from which the track originated. See below for details.
imageUrlstringNoA URL to an image for the track, for example, an album cover. Typically a JPG or PNG. Maximum length of 1024 characters. Where possible, this URL should be absolute Internet-based (as opposed to local LAN) and not require authorization to retrieve.
namestringNoThe name of the track (see track type: track values below).
replayGainnumberNoThe track gain. This field allows for floating value points.

The player applies this normalization to track audio, overriding any value found in the actual media. Your service should pass the best dB value that you have. Players will interpret this as needed and clamp any values outside of this range. Currently, this range is from -13 dB to +13 dB. For example, the player treats a value of 14 as if it were 13. This range is subject to change at our discretion. The default replayGain value is zero, which results in no change to the audio volume.
tagsarray of enumsNoA tag for the track. Currently the only value is "TAG_EXPLICIT" to indicate that the track includes explicit content. Players will not include this key and value if it is empty.
typestringNoThe type of track. Maximum length of 15 characters. Currently the only value for this parameter is track, which is also the default. Use track to describe a normal audio or music track with a name, album, and artist. See below for details.
serviceServiceYes(Output only) The name and id of the music service where the track originated. This field is only present in events such as the metadataStatus event.

Cloud queue inputs

These fields are included only on input to playbackSession commands such as loadCloudQueue and skipToItem. They are not included in metadataStatus events, so that the URL for your media can't be discovered.

KeyTypeRequiredValue
mediaUrlstringNo(Optional if MusicObjectId provided) The URL for the media. Maximum length of 1024 characters. This is not necessary if your app provides the MusicObjectId in the track object. If your app does provide the MusicObjectId, the player will not use the mediaUrl key.
contentTypestringYesThe type of content, such as "audio/mpeg". This is also known as the MIME or media type. Maximum length of 255 characters. This is required. If you don't send the correct content type, the player won't play the track.

Track type "track"

If the track type is track, the following fields can be included.

KeyTypeRequiredValue
namestringNoThe name of the track. Maximum length of 1024 characters.
trackNumbernumberNoThe number of the track on the album.
artistartistNoThe artist for the track. See the artist object type below for details.
albumalbumNoThe album containing the track, as determined by the source of the track. See the album object type below for details.

Here's an example:

{
  "track": {
    "type": "track",
    "canSkip": true,
    "canCrossfade": true,
    "id": {
      "serviceId": "example.com",
      "objectId": "tr12345",
      "accountId": "acct1234"
    },
    "name": "Billie Jean",
    "imageUrl": "http://images.example.com/art1",
    "durationMillis": 293000,
    "trackNumber": 4,
    "replayGain": -2.96,
    "artist": {
      "name": "Michael Jackson",
      "id": {
        "serviceId": "example.com",
        "objectId": "art987"
      }
    },
    "album": {
      "name": "Thriller",
      "id": {
        "serviceId": "example.com",
        "objectId": "alb6254"
      },
      "artist": {
        "name": "Michael Jackson"
      },
      "tags": [
        "TAG_EXPLICIT"
      ]
    }
  }
}