OpenSubsonic API

Version 2 introduces a structured way to handle multiple lyric layers and precise timing.

Agent Attribution Rules

When multiple vocal agents or layers are present, the response must include an agents array.

• Every attributed entry using agents must define exactly one agent with role: "main".
• To avoid redundancy, reusable agent metadata is stored once in structuredLyrics.agents, and individual cueLine objects reference them using agentId.

Timing and Cues

Timing is handled via cueLine objects and cue objects:

• cueLine.value: The renderable text for that specific agent/layer. If multiple agent cueLines share a parent line index, each value represents only that layer's text, not the combined text of the parent line.
• cue.byteStart / cue.byteEnd: 0-based inclusive offsets into the UTF-8 encoding of the cueLine.value.
• Important: There is no normalization step for these offsets. Each cueLine containing cues must include the value field.

The AlbumID3WithSongs response is an extension of the standard AlbumID3 object that includes an array of song entries (of type Child). This format allows a client to retrieve full album metadata along with the complete list of tracks contained within that album in a single response.

There are two primary variations of this response structure:

1. OpenSubsonic: Includes extended metadata fields (like version, userRating, musicBrainzId, etc.) and uses the song key to provide the tracklist.
2. Subsonic (Legacy): A more limited version used for backward compatibility, primarily focusing on core album and song identity.

When consuming this data, note that OpenSubsonic servers may provide additional optional fields that are not present in standard Subsonic responses.

{
  "id": "ad0f112b6dcf83de5e9cae85d07f0d35",
  "name": "8-bit lagerfeuer",
  "song": [
    {
      "id": "300000116",
      "title": "Can I Help U?",
      "duration": 103
    }
  ]
}

The transcodeDecision object is the response returned by the getTranscodeDecision endpoint. It informs the client whether a media file can be played directly or if the server must transcode it to a different format to satisfy the client's capabilities.

Key logic for clients:

• If canDirectPlay is true, the client can request the source stream directly.
• If canDirectPlay is false and canTranscode is true, the client must use the transcodeParams provided to call the getTranscodeStream endpoint.
• transcodeParams is an internal server value that must be properly escaped when used as a URL parameter.

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true,
    "transcodeDecision": {
      "canDirectPlay": false,
      "canTranscode": true,
      "transcodeReason": ["AudioCodecNotSupported"],
      "errorReason": "",
      "transcodeParams": "0001-0005-004",
      "sourceStream": {
        "protocol": "http",
        "container": "flac",
        "codec": "flac",
        "audioChannels": 6,
        "audioBitrate": 3000000,
        "audioProfile": "",
        "audioSamplerate": 96000,
        "audioBitdepth": 24
      },
      "transcodeStream": {
        "protocol": "hls",
        "container": "mp4",
        "codec": "aac",
        "audioChannels": 2,
        "audioBitrate": 256000,
        "audioProfile": "xHE-AAC",
        "audioSamplerate": 48000,
        "audioBitdepth": 16
      }
    }
  }
}

The ClientInfo payload is an extension used to communicate a client device's capabilities to the server. This allows the server to make informed decisions regarding direct playback, transcoding, and codec selection.

Key capabilities communicated include:

• Bitrate limits: maxAudioBitrate (for direct play) and maxTranscodingAudioBitrate (for transcoded streams).
• Direct Play Profiles: A list of directPlayProfiles defining supported containers, codecs, protocols, and channel limits.
• Transcoding Profiles: A prioritized list of transcodingProfiles that the server should evaluate in order to determine the best transcoding strategy.
• Codec Profiles: Detailed codecProfiles that specify specific limitations (e.g., bitrate or samplerate constraints) for individual codecs.

{
  "name": "Play:1",
  "platform": "Sonos",
  "maxAudioBitrate": 512000,
  "maxTranscodingAudioBitrate": 256000,
  "directPlayProfiles": [
    {
      "containers": [ "mp3" ],
      "audioCodecs": [ "mp3" ],
      "protocols": [ "http" ],
      "maxAudioChannels": 2
    }
  ],
  "transcodingProfiles": [
    {
      "container": "mp3",
      "audioCodec": "mp3",
      "protocol": "http",
      "maxAudioChannels": 2
    }
  ],
  "codecProfiles": [
    {
      "type": "AudioCodec",
      "name": "mp3",
      "limitations": [
        { "name": "audioBitrate", "comparison": "LessThanEqual", "values": [ "320000" ], "required": true }
      ]
    }
  ]
}

The ArtistWithAlbumsID3 response is an extension of the ArtistID3 format that includes an array of AlbumID3 objects. This format is used to provide detailed information about an artist along with their associated albums.

OpenSubsonic vs. Subsonic Differences

When implementing or consuming this response, note that OpenSubsonic adds several specific fields. If a server supports these fields, it must return them (even with empty or default values) so clients can detect support. These additional fields are optional from a schema perspective but required for feature detection.

OpenSubsonic specific fields:

• musicBrainzId: The artist's MusicBrainzID.
• sortName: The artist's sort name.
• roles: A list of all roles this artist has in the library (e.g., artist, albumartist, composer).

{
  "id": "37ec820ca7193e17040c98f7da7c4b51",
  "name": "2 Mello",
  "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
  "albumCount": 1,
  "userRating": 5,
  "artistImageUrl": "https://demo.org/image.jpg",
  "starred": "2017-04-11T10:42:50.842Z",
  "musicBrainzId": "189002e7-3285-4e2e-92a3-7f6c30d407a2",
  "sortName": "Mello (2)",
  "roles": [
    "artist",
    "albumartist",
    "composer"
  ],
  "album": [
    {
      "id": "200000002",
      "parent": "100000002",
      "album": "Colorsmoke EP",
      "title": "Colorsmoke EP",
      "name": "Colorsmoke EP",
      "isDir": true,
      "coverArt": "al-200000002",
      "songCount": 12,
      "created": "2021-02-23T04:24:48+00:00",
      "duration": 4568,
      "playCount": 1,
      "artistId": "100000002",
      "artist": "Synthetic",
      "year": 2007,
      "genre": "Electronic",
      "userRating": 5,
      "averageRating": 3,
      "starred": "2021-02-22T05:51:53Z"
    }
  ]
}