Extensions

• 1: API Key Authentication
• 2: getPodcastEpisode
• 3: HTTP form POST
• 4: Index based Queue
• 5: Playback Report
• 6: Playlist Folders
• 7: Song Lyrics
• 8: Sonic similarity
• 9: Template extension
• 10: Transcode Offset
• 11: Transcoding

1 - API Key Authentication

OpenSubsonic version: 1

OpenSubsonic extension name apiKeyAuthentication (As returned by getOpenSubsonicExtensions)

Version 1

This extension requires changes to the semantics of authentication. Broadly, there are two general changes:

1. Required: A new authentication mechanism: apiKey for query.
2. Recommended: Deprecation of token/salt-based authentication.

API keys

An API key is any authentication token generated by an OpenSubsonic server that can be used to authenticate. How this API key is generated by the server is implementation-specific: the server may provide a page where the user can configure one or more API keys, the server may automatically generate a API key, or any other variety of means. The format of the API key is not specified, but it must be of reasonable length to fit into a query parameter (less than 2048 characters URL-encoded).

Servers which implement this extension must provide some mechanism for viewing active API key(s) and allow for revoking API keys. Note that these API keys do not expire; as long as they are not revoked by the user, they are assumed to be valid.

Using a API key

An API key is used as a query parameter apiKey=<api key>. When an API key is provided, the client must not provide a u parameter; passing in u must be treated as an error 43.

It is recommended that servers which provide API-key authentication no longer support salt/token-based authentication.

If multiple conflicting authentication parameters are passed in, the server must return an error 43, Multiple conflicting authentication mechanisms provided

If a server removes support for token-based authentication, it must return error 41 (Token authentication not supported for LDAP users.).

If a server removes support for any other particular authentication mechanism, it must return an error 42 (Provided authentication mechanism not supported).

In both cases, it is recommended that the server provide a meaningful url (configuration url, documentation, etc) in the helpUrl to help clients instruct their users how to obtain an API key.

New error codes

This extension introduces three new errors 42, 43 and 44, and adds a new field helpUrl. See error

2 - getPodcastEpisode

OpenSubsonic version: 1

OpenSubsonic extension name: getPodcastEpisode (As returned by getOpenSubsonicExtensions)

When a server support this extension this means that it support the getPodcastEpisode endpoint getPodCastEpisode

Version 1

You can now retrieve the metadata for an individual podcast episode without having to pull an entire channel and searching the list of episodes.

3 - HTTP form POST

OpenSubsonic version: 1

OpenSubsonic extension name formPost (As returned by getOpenSubsonicExtensions)

Version 1

This extension requires that the server support passing API arguments via POST with the arguments respecting the application/x-www-form-urlencoded format.

See: API reference

4 - Index based Queue

OpenSubsonic version: 1

OpenSubsonic extension name indexBasedQueue (As returned by getOpenSubsonicExtensions)

When a server supports this extension, it provides two new endpoints: savePlayQueueByIndex and getPlayQueueByIndex.

Version 1

You can now save a play queue using an index instead of the current song ID, allowing for duplicate items in the queue. Similarly, the queue can be retrieved with the current song index.

5 - Playback Report

OpenSubsonic version: 1

OpenSubsonic extension name playbackReport (As returned by getOpenSubsonicExtensions)

When a server supports this extension, it provides the reportPlayback endpoint and can expose timeline fields in getNowPlaying responses.

Version 1

Clients can report playback status with mediaId, mediaType, positionMs, state, playbackRate, and ignoreScrobble.

When ignoreScrobble=true, the server should only update now playing display/state fields and should not perform playcount/scrobble side effects.

6 - Playlist Folders

OpenSubsonic version: 1

OpenSubsonic extension name playlistFolders (As returned by getOpenSubsonicExtensions)

When a server supports this extension, each user can organize the playlists available to them in ordered folders of arbitrary depth, as in iTunes/Apple Music, Spotify, or Rekordbox. Existing clients remain compatible because getPlaylists continues to return every visible playlist as a flat list.

Version 1

This extension requires the following endpoints:

• createPlaylistFolder creates a folder.
• deletePlaylistFolder deletes an empty folder.
• getPlaylistFolders returns all of the selected user’s folders.
• movePlaylist places playlists in a folder or at the root and sets their position.
• updatePlaylistFolder renames, moves, or reorders a folder.

It also adds playlistFolderId and playlistFolderSortOrder to the playlist response.

Hierarchy and user scope

getPlaylistFolders returns a flat list. A folder’s optional parentId identifies its parent; no parentId means that the folder is at the root. This representation supports arbitrary nesting without recursive responses. Clients reconstruct the full tree from two requests: getPlaylistFolders for the folders and getPlaylists for the playlists, using each playlist’s playlistFolderId.

A user’s folder tree is private to that user, and folder placement is independent of playlist ownership. A user can place any playlist visible to them — including a public or shared playlist owned by another user, or a readonly one — without modifying the playlist itself. Different users can place the same playlist in different folders; within one user’s tree a playlist has at most one placement. Folder names do not have to be unique.

The selected user is the authenticated user, or the user named by the admin-only username parameter on getPlaylists and getPlaylistFolders. Servers must never expose one user’s folders or placements to another user.

Ordering

Sibling items — the child folders and playlists sharing one parent, or the folders and playlists at the root — share a single ordering space. sortOrder values are client-assigned integers that servers store without normalization; duplicates are allowed. Clients should sort siblings by sortOrder ascending, breaking ties by name, and place items without a value after ordered ones. This lets clients reproduce manually ordered trees from apps like iTunes and Rekordbox exactly.

Placement lifecycle and deletion

A placement exists only while its playlist is visible to the user: when a playlist is deleted or stops being visible, its placement in every affected user’s tree ceases to exist. Folder emptiness is evaluated over child folders and currently visible playlists. Folders can only be deleted when empty; servers must not implicitly delete or move a folder’s contents.

An omitted parentId on updatePlaylistFolder leaves the folder’s parent unchanged, while an explicitly empty value moves the folder to the root. The playlistFolderId parameter of movePlaylist behaves the same way. Servers must distinguish an empty parameter value from an absent parameter.

Error handling

• A folder ID (including parentId) that does not exist or belongs to another user’s tree returns error 70, indistinguishable from not-found, so that folder IDs cannot be probed across users.
• A playlistId that does not exist or is not visible to the authenticated user returns error 70.
• A move that would create a cycle, or deleting a non-empty folder, returns error 0.
• Calling updatePlaylistFolder or movePlaylist without any of their optional parameters returns error 10.

Backward compatibility

Clients that do not support this extension can keep using the existing playlist endpoints. They receive the same complete flat playlist list and can ignore the new fields.

7 - Song Lyrics

OpenSubsonic version: 1

OpenSubsonic extension name songLyrics (As returned by getOpenSubsonicExtensions)

Version 1

Line-level structured lyrics with multi-language support.

This extension requires the following endpoints:

• getLyricsBySongId: Fetch structured song lyrics by id

Version 2

Word/syllable-level timing (karaoke) and lyric layer classification (translations, pronunciations).

Adds:

• enhanced query parameter on getLyricsBySongId to opt-in to enhanced lyrics data
• kind field on structuredLyrics to classify independent lyric layers (main, translation, pronunciation)
• agent objects within an optional agents array on structuredLyrics for reusable agent attribution metadata
• cueLine array on structuredLyrics for word/syllable-level timing
• agentId field on cueLine to reference an agent in the same structuredLyrics entry
• cue objects within each cueLine for individual word/syllable timestamps, with required byteStart / byteEnd offsets into cueLine.value

When agent attribution is present, the reusable agent metadata lives once in structuredLyrics.agents, while each cueLine points at the relevant agent via agentId. Simple unattributed single-layer lyrics may omit agents entirely. Entries with multiple vocal agents/layers must emit agents, and every attributed entry that uses agents must define exactly one role: "main" agent. A single-agent attributed/default layer may also use agents with that lone agent marked as main.

Each cue includes byteStart / byteEnd, defined as 0-based inclusive offsets into the UTF-8 encoding of the final cueLine.value, with no normalization step. Accordingly, each cueLine that contains cues must also include value. When multiple agent cueLines share one parent line index, each cueLine.value is the renderable text for that agent/layer, not necessarily the parent line’s combined text.

All new fields are gated behind enhanced=true — without it, the response is identical to version 1.

Servers that support Version 2 should advertise songLyrics versions [1, 2] via getOpenSubsonicExtensions.

This extension requires the following endpoints:

• getLyricsBySongId: Fetch structured song lyrics by id (with optional enhanced parameter)

8 - Sonic similarity

OpenSubsonic version: 1

OpenSubsonic extension name: sonicSimilarity (As returned by getOpenSubsonicExtensions)

Version 1

This extension adds two new audio-similarity endpoints:

• findSonicPath
• getSonicSimilarTracks

These endpoints return a list of sonicMatch entries, each with a Child entry and a normalized similarity score.

9 - Template extension

OpenSubsonic version: 1

OpenSubsonic extension name: template (As returned by getOpenSubsonicExtensions)

This is a template extension that allows servers to do marvelous stuff and clients to use that stuff.

Version 1

You can now bake cakes and brownies via the API!

This extension requires the following endpoints:

• bakeCake To bake cakes.
• bakeBrownie To bake brownies.

Version 2

You can now bake a lot of stuff via the API!

This extension requires the following endpoints:

• bakeSomething To bake something.

10 - Transcode Offset

OpenSubsonic version: 1

OpenSubsonic extension name: transcodeOffset (As returned by getOpenSubsonicExtensions)

When a server support this extension this means that it support the timeOffset parameter of the stream endpoint for music.

Version 1

You can now start transcoding at any position in the media, allowing seeking when transcoding on the clients!

This extension requires the support of the timeOffset parameter of the stream endpoint for music.

11 - Transcoding

OpenSubsonic version: 1

OpenSubsonic extension name: transcoding (As returned by getOpenSubsonicExtensions)

Version 1

This extension provides a way for clients to obtain a server’s decision on whether a media file should be transcoded and to retrieve the transcoded stream if necessary.

This extension requires the following endpoints:

• getTranscodeDecision: Returns a transcode decision for a given media file. Standard parameters are still provided through the URL as usual. However, because client playback capabilities can be complex, they must be supplied in the request body as a JSON-encoded payload. For this reason, this endpoint uses the POST method rather than GET.
• getTranscodeStream: Returns a transcoded media stream.