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.

artist

The artist of the track.

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.

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.

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.

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.

Here's an example:

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

service

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

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.

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.

Track type "track"

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

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"
      ]
    }
  }
}