Payloads

Payloads documentation.

1: ClientInfo
2: CodecProfile
3: collectionItemID
4: CreateCollectionRequest
5: DirectPlayProfile
6: Limitation
7: MoveRange
8: TranscodingProfile
9: UpdateCollectionRequest

1 - ClientInfo

Contains information about the client’s capabilities.

{
  "name": "Play:1",
  "platform": "Sonos",
  "maxAudioBitrate": 512000,
  "maxTranscodingAudioBitrate": 256000,
  "directPlayProfiles": [
    {
      "containers": [ "mp3" ],
      "audioCodecs": [ "mp3" ],
      "protocols": [ "http" ],
      "maxAudioChannels": 2
    },
    {
      "containers": [ "flac" ],
      "audioCodecs": [ "flac" ],
      "protocols": [],
      "maxAudioChannels": 2
    }
    ,
    {
      "containers": [ "mp4" ],
      "audioCodecs": [ "flac", "aac", "alac" ],
      "protocols": [],
      "maxAudioChannels": 2
    }
    ],
    "transcodingProfiles": [
    {
      "container": "mp3",
      "audioCodec": "mp3",
      "protocol": "http",
      "maxAudioChannels": 2
    },
    {
      "container": "flac",
      "audioCodec": "flac",
      "protocol": "hls",
      "maxAudioChannels": 2
    }
  ],
  "codecProfiles": [
    {
      "type": "AudioCodec",
      "name": "mp3",
      "limitations": [
        { "name": "audioBitrate", "comparison": "LessThanEqual", "values": [ "320000" ], "required": true }
      ]
    },
    {
      "type": "AudioCodec",
      "name": "flac",
      "limitations": [
        { "name": "audioSamplerate", "comparison": "LessThanEqual", "values":  [ "192000" ], "required": false },
        { "name": "audioChannels",  "comparison": "Equals", "values": ["1", "2" ],      "required": false }
      ]
    }
  ]
}

Field	Type	Req.	OpenS.	Details
`name`	string	Yes	Yes	The name of the client device.
`platform`	string	Yes	Yes	The platform of the client (e.g., Android, iOS).
`maxAudioBitrate`	integer	No	Yes	The maximum audio bitrate the client can handle. 0 or missing means no limitation.
`maxTranscodingAudioBitrate`	integer	No	Yes	The maximum audio bitrate for transcoded content. 0 or missing means no limitation.
`directPlayProfiles`	DirectPlayProfile[]	No	Yes	A list of profiles for direct playback.
`transcodingProfiles`	TranscodingProfile[]	No	Yes	A list of profiles for transcoding. The server should evaluate these in the order they are listed, as a priority list.
`codecProfiles`	CodecProfile[]	No	Yes	A list of codec-specific profiles.

2 - CodecProfile

Defines a codec profile with optional limitations.

{
  "type": "AudioCodec",
  "name": "mp3",
  "limitations": [
    { "name": "audioBitrate", "comparison": "LessThanEqual", "values": ["320000"], "required": true }
  ]
}

Field	Type	Req.	OpenS.	Details
`type`	string	Yes	Yes	The type of codec profile. Currently only `AudioCodec` is supported.
`name`	string	Yes	Yes	The name of the codec (e.g., mp3, flac). Only a single value is accepted.
`limitations`	Limitation[]	No	Yes	A list of limitations for this codec.

3 - collectionItemID

An identifier for a collection item to be added.

Depending on the item type, either id or name must be provided. For most types, id is the natural choice, but some types (e.g. Genre) don’t have it, so name should be used.

{
  "type": "song",
  "id": "20"
}

{
  "type": "album",
  "id": "30"
}

{
  "type": "genre",
  "name": "vaporwave"
}

Field	Type	Req.	Details
`type`	`string`	Yes	One of: song, album, artist, playlist, genre, internetRadioStation, podcastEpisode, podcast.
`id`	`string`	No	ID of the item, where applicable
`name`	`string`	No	Name of the item, where applicable

4 - CreateCollectionRequest

Request payload for creating a collection.

Should be used in the CreateCollection endpoint.

{
  "name": "test collection",
  "comment": "this is a collection",
  "items": [
    {
      "type": "song",
      "id": "300000060"
    },
    {
      "type": "album",
      "id": "200000021"
    },
    {
      "type": "genre",
      "name": "vaporwave"
    }
  ]
}

Field	Type	Req.	OpenS.	Details
`name`	string	Yes	Yes	The human-readable name of the collection.
`comment`	string	No	Yes	The collection comment.
`public`	boolean	No	Yes	`true` if the collection should be visible to all users, `false` otherwise. Default `false`.
`items`	CollectionItemID[]	No	Yes	A list of items.

5 - DirectPlayProfile

Defines a direct play profile.

{
  "containers": [ "mp4" ],
  "audioCodecs": [ "aac", "alac" ],
  "protocols": [ "http" ],
  "maxAudioChannels": 2
}

Field	Type	Req.	OpenS.	Details
`containers`	Array of string	Yes	Yes	List of supported container format (e.g., mp3, flac, mp4). An empty array means any container.
`audioCodecs`	Array of string	Yes	Yes	List of supported audio codecs. An empty array means any codec.
`protocols`	Array of string	Yes	Yes	The streaming protocols. Supported values are `http`, `hls`.
`maxAudioChannels`	integer	No	Yes	The maximum number of audio channels supported.

6 - Limitation

Defines a limitation for a codec profile.

{
  "name": "audioSamplerate",
  "comparison": "Equals",
  "values": [ "44100", "48000" ],
  "required": true
}

Field	Type	Req.	Details
`name`	string	Yes	The name of the limitation. Can be `audioChannels`, `audioBitrate`, `audioProfile`, `audioSamplerate`, or `audioBitdepth`.
`comparison`	string	Yes	The comparison operator. Can be `Equals`, `NotEquals`, `LessThanEqual`, `GreaterThanEqual`.
`values`	string	Yes	The values to compare against. For `LessThanEqual` and `GreaterThanEqual`, only the first value will be used.
`required`	boolean	Yes	Whether this limitation must be met.

7 - MoveRange

Move a range of items from one position to another.

{
  "fromStart": 0,
  "fromEnd": 5,
  "to": 20
}

Field	Type	Req.	OpenS.	Details
`fromStart`	integer	Yes	Yes	Start of the original range (inclusive).
`fromEnd`	integer	Yes	Yes	End of the original range (exclusive).
`to`	integer	Yes	Yes	New index of the first item in the range.

8 - TranscodingProfile

Defines a transcoding profile.

{
  "container": "mp3",
  "audioCodec": "mp3",
  "protocol": "http",
  "maxAudioChannels": 2
}

Field	Type	Req.	OpenS.	Details
`container`	string	Yes	Yes	The container format (e.g., mp3, flac).
`audioCodec`	string	Yes	Yes	The target audio codec for transcoding.
`protocol`	string	Yes	Yes	The streaming protocol. Can be `http` or `hls`.
`maxAudioChannels`	integer	No	Yes	The maximum number of audio channels for the transcoded stream.

9 - UpdateCollectionRequest

Request payload for updating a collection.

Should be used in the UpdateCollection endpoint. Only the fields supplied in the request payload will have an effect on a collection.

{
  "collectionId": "23785995",
  "name": "new name",
  "comment": "this is a new comment"
}

{
  "collectionId": "23785995",
  "add": [
    {
      "type": "album",
      "id": "1234"
    }
  ]
}

{
  "collectionId": "23785995",
  "move": {
    "fromStart": 0,
    "fromEnd": 5,
    "to": 20
  }
}

{
  "collectionId": "23785995",
  "remove": [0, 1, 2, 6]
}

Field	Type	Req.	OpenS.	Details
`collectionId`	string	Yes	Yes	The collection ID.
`name`	string	No	Yes	The human-readable name of the collection. Cannot be an empty string.
`comment`	string	No	Yes	The collection comment.
`public`	boolean	No	Yes	`true` if the collection should be visible to all users, `false` otherwise.
`add`	CollectionItemID[]	No	Yes	Add the specified items to the collection. Items are appended to the tail of the collection.
`move`	MoveRange	No	Yes	Move items from the original position to another in the collection.
`remove`	Array of integer	No	Yes	Remove the items at the specified positions from the collection.

Only one of add, move, and remove can be non-empty in a single request.