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 metadataStatus 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.

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

The objects include:


album

The album for the track.

Key Type Value
name string The name of the album. Maximum length of 76 characters.
artist artist (Optional) The artist for the album. See below for details.
imageUrl string (Optional) A URL to an image of the album, typically a JPG or PNG.
id MusicObjectId (Optional) The unique music service object id for this album; identifies the album within the music service from which the track originated. See below for details.
tags array of enums (Optional) A 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.

Key Type Value
name string The name of the artist. Maximum length of 76 characters.
imageUrl string (Optional) A URL to an image of the artist, typically a JPG or PNG.
id MusicObjectId (Optional) The unique music service object id for this artist; identifies the artist within the music service from which the track originated. See below for details.
tags array of enums (Optional) A 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.

Key Type Value
name string The name of the container.
type string (Optional) The type of source. Possible values are:

    • 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.
id MusicObjectId (Optional) The unique music service object ID for this track; identifies the track within the music service from which the track originated. See below for details.
service Service (Optional) A service object describing the music service for this music source.
imageUrl string (Optional) A 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.
tags array of enums (Optional) A 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:


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.

Key Type Value
id string (Optional) The cloud queue itemId for the track. Only present if the track is from a cloud queue. Maximum length of 128 characters.
track track The track data. See below for details.
deleted boolean (Optional) Whether the track was deleted or not; true if deleted and false if not. This should be used by the cloud queue server.
policies policies (Optional) Certain 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.

Key Type Value
serviceId string (Optional) The 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.
objectId string The unique identifier for the particular piece of content within the music service. Maximum length of 256 characters.
accountId string (Optional) The 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, joinOrCreateSession, 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:

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.

Key Type Value
itemId string The identifier of the item
positionMillis number (Optional) An offset, in milliseconds, within the item.

Here’s an example:


Service

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

Key Type Value
name string The name of the service.
id string (Optional) The 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.
imageUrl string (Optional) A 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.

Key Type Value
canCrossfade boolean (Optional) Set to false to prevent audio crossfade from involving this track regardless of the prevailing playback policy. Default is true.
canSkip boolean (Optional) Set to false to prevent skipping this track regardless of the prevailing playback policy. Default is true.
durationMillis number (Optional) The 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.
id MusicObjectId (Optional) The unique music service object ID for this track; identifies the track within the music service from which the track originated. See below for details.
imageUrl string  (Optional) A 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.
name string (Optional) The name of the track (see track type: track values below).
replayGain number (Optional) The 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.

tags array of enums (Optional) A 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.
type string (Optional) The 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.
service Service (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.

Key Type Value
mediaUrl string (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.
contentType string The 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.

Key Type Value
name string (Optional) The name of the track. Maximum length of 1024 characters.
trackNumber number (Optional) The number of the track on the album.
artist artist (Optional) The artist for the track. See the artist object type below for details.
album album (Optional) The album containing the track, as determined by the source of the track. See the album object type below for details.

Here’s an example: