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.

When the ‘id’ field is not present for an item type (e.g. Genre), use its name or some other natural identifier.

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

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

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

Field	Type	Req.	OpenS.	Details
`type`	`string`	Yes		One of: song, album, artist, playlist, genre, internetRadioStation, podcastEpisode, podcast.
`id`	`string`	Yes		ID (or name, if ‘id’ is not available) of an item.

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",
      "id": "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.