Extension on OpenSubsonic

API Key Authentication

Mon, 01 Jan 0001 00:00:00 +0000

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:

Required: A new authentication mechanism: apiKey for query.
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).

ClientInfo

Mon, 01 Jan 0001 00:00:00 +0000

{
 "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.

CodecProfile

Mon, 01 Jan 0001 00:00:00 +0000

{
 "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.

DirectPlayProfile

Mon, 01 Jan 0001 00:00:00 +0000

{
 "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.

getLyricsBySongId

Mon, 01 Jan 0001 00:00:00 +0000

OpenSubsonic version: 1

OpenSubsonic extension name songLyrics (As returned by getOpenSubsonicExtensions)

Retrieves all structured lyrics from the server for a given song. The lyrics can come from embedded tags (SYLT/USLT), LRC file/text file, or any other external source.

http://your-server/rest/getLyricsBySongId

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes	Yes		The track ID.
`enhanced`	No	Yes	`false`	When `true`, the response includes `cueLine` arrays, cue `byteStart` / `byteEnd` offsets into `cueLine.value`, and non-main `kind` tracks (translations, pronunciations). When `false` or omitted, only `kind="main"` entries are returned with no `cueLine` data. Added in `songLyrics` version 2.

Special notes about the lang field

Ideally, the server will return lang as an ISO 639 (2/3) code. However, tagged files and external lyrics can come with any value as a potential language code, so clients should take care when displaying lang.

getPlayQueueByIndex

Mon, 01 Jan 0001 00:00:00 +0000

OpenSubsonic version: 1

OpenSubsonic extension name indexBasedQueue (As returned by getOpenSubsonicExtensions)

http://your-server/rest/getPlayQueueByIndex

Returns the state of the play queue for this user (as set by savePlayQueue or savePlayQueueByIndex). This includes the tracks in the play queue, the currently playing track index (0-based), and the position within this track. Typically used to allow a user to move between different clients/apps while retaining the same play queue (for instance when listening to an audio book).

getPodcastEpisode

Mon, 01 Jan 0001 00:00:00 +0000

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.

getPodcastEpisode

Mon, 01 Jan 0001 00:00:00 +0000

OpenSubsonic version: 1

OpenSubsonic extension name getPodcastEpisode (As returned by getOpenSubsonicExtensions) http://your-server/rest/getPodcastEpisode

Returns details for a podcast episode.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes	Yes		The podcast episode ID.

Example

http://your-server/rest/getPodcastEpisode.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

A subsonic-response element with a nested podcastEpisode element on success.

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "podcastEpisode": {
 "id": "7390",
 "parent": "7389",
 "isDir": "false",
 "title": "Jonas Gahr Støre",
 "album": "NRK – Hallo P3",
 "artist": "Podcast",
 "year": "2015",
 "coverArt": "7389",
 "size": "41808585",
 "contentType": "audio/mpeg",
 "suffix": "mp3",
 "duration": "2619",
 "bitRate": "128",
 "isVideo": "false",
 "created": "2015-09-07T20:07:31.000Z",
 "artistId": "453",
 "type": "podcast",
 "streamId": "7410",
 "channelId": "17",
 "description": "Jonas Gahr Støre fra Arbeiderpartiet er med i dagens partilederutspørring i Hallo P3!",
 "status": "completed",
 "publishDate": "2015-09-07T15:29:00.000Z"
 }
 }
}

Does not exist

Field	Type	Req.	OpenS.	Details
`podcastEspisode`	`podcastEpisode`	Yes		The podcast episode

getTranscodeDecision

Mon, 01 Jan 0001 00:00:00 +0000

http://your-server/rest/getTranscodeDecision

Returns a transcode decision for a given media file. This endpoint is used by clients to determine if a media file should be transcoded before streaming. The server will analyze the provided client information and return a decision. This endpoint must be accessed using a POST request

Parameters

Parameter	Req.	OpenS.	Default	Comment
`mediaId`	Yes			The ID of the media to be transcoded.
`mediaType`	Yes			Either song or podcast so the server knows what the mediaId is referring to.

Request Body

The request body must be a JSON object containing the client’s capabilities. See the ClientInfo documentation for more details.

getTranscodeStream

Mon, 01 Jan 0001 00:00:00 +0000

http://your-server/rest/getTranscodeStream

Returns a transcoded media stream. Note: Clients should not try to reconstruct the transcodeParams. Instead, they must use the transcodeParams provided in the response of the getTranscodeDecision endpoint.

Parameters

Parameter	Req.	Default	Comment
`mediaId`	Yes		The ID of the media to be transcoded.
`mediaType`	Yes		Either song or podcast so the server knows what the mediaId is referring to.
`offset`	No	0	The time offset in seconds from which to start transcoding.
`transcodeParams`	Yes		Server-specific transcoding parameters, obtained from the property `transcodeParams` of the result of the endpoint `getTranscodeDecision`. The value is unique and already properly escaped.

Example

http://your-server/rest/getTranscodeStream.view?mediaIdId=123&mediaType=song&offset=0&parameters=...&u=demo&p=demo&v=1.16.1&c=AwesomeClientName&f=json

Result

The raw transcoded media stream. In case of an error, a standard HTTP error code is returned with a descriptive message.

HTTP form POST

Mon, 01 Jan 0001 00:00:00 +0000

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

application/x-www-form-urlencoded: the keys and values are encoded in key-value tuples separated by ‘&’, with a ‘=’ between the key and the value. Non-alphanumeric characters in both keys and values are URL encoded.

Index based Queue

Mon, 01 Jan 0001 00:00:00 +0000

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.

Limitation

Mon, 01 Jan 0001 00:00:00 +0000

{
 "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.

Playback Report

Mon, 01 Jan 0001 00:00:00 +0000

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.

reportPlayback

Mon, 01 Jan 0001 00:00:00 +0000

OpenSubsonic version: 1

OpenSubsonic extension name playbackReport (As returned by getOpenSubsonicExtensions)

http://your-server/rest/reportPlayback

Reports playback timeline state for a song. Clients should call the endpoint at least on each state change. The end point can be called every X seconds by clients, but servers should estimate current position based on playbackRate for up to date data between calls. Servers should not assume a media is played after the calculated end of content, but needs to wait for a stopped state. 30 minutes after the planned end of the media, servers should stop listening to events and clients should use the normal scrobble endpoint after reconnection from offline.

savePlayQueueByIndex

Mon, 01 Jan 0001 00:00:00 +0000

OpenSubsonic version: 1

OpenSubsonic extension name indexBasedQueue (As returned by getOpenSubsonicExtensions)

http://your-server/rest/savePlayQueueByIndex

Saves the state of the play queue for this user. This includes the tracks in the play queue, the currently playing track, and the position within this track. Typically used to allow a user to move between different clients/apps while retaining the same play queue (for instance when listening to an audio book).

Uses an index instead, as this allows for uniquely identifying play queues which may have multiple copies of the same track.

Song Lyrics

Mon, 01 Jan 0001 00:00:00 +0000

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.

stream

Mon, 01 Jan 0001 00:00:00 +0000

http://your-server/rest/stream Since 1.0.0

Streams a given media file.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			A string which uniquely identifies the file to stream. Obtained by calls to getMusicDirectory.
`maxBitRate`	No			(Since 1.2.0) If specified, the server will attempt to limit the bitrate to this value, in kilobits per second. If set to zero, no limit is imposed.
`format`	No			(Since 1.6.0) Specifies the preferred target format (e.g., “mp3” or “flv”) in case there are multiple applicable transcodings. Starting with 1.9.0 you can use the special value “raw” to disable transcoding.
`timeOffset`	No	No / Yes		By default only applicable to video streaming. If specified, start streaming at the given offset (in seconds) into the media. The `Transcode Offset` extension enables the parameter to music too.
`size`	No			(Since 1.6.0) Only applicable to video streaming. Requested video size specified as WxH, for instance “640x480”.
`estimateContentLength`	No		false	(Since 1.8.0). If set to “true”, the Content-Length HTTP header will be set to an estimated value for transcoded or downsampled media.
`converted`	No		false	(Since 1.14.0) Only applicable to video streaming. Servers can optimize videos for streaming by converting them to MP4. If a conversion exists for the video in question, then setting this parameter to “true” will cause the converted video to be returned instead of the original.

Example

http://your-server/rest/stream.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

Returns binary data on success, or an XML document on error (in which case the HTTP content type will start with “text/xml”).

StreamDetails

Mon, 01 Jan 0001 00:00:00 +0000

{
 "protocol": "http",
 "container": "flac",
 "codec": "flac",
 "audioChannels": 6,
 "audioBitrate": 3000000,
 "audioProfile": "",
 "audioSamplerate": 96000,
 "audioBitdepth": 24
}

Field	Type	Req.	OpenS.	Details
`protocol`	string	Yes	Yes	The streaming protocol. Can be `http` or `hls`.
`container`	string	Yes	Yes	The container format.
`codec`	string	Yes	Yes	The audio codec.
`audioChannels`	integer	No	Yes	The number of audio channels.
`audioBitrate`	integer	No	Yes	The audio bitrate.
`audioProfile`	string	No	Yes	The audio profile.
`audioSamplerate`	integer	No	Yes	The audio sample rate.
`audioBitdepth`	integer	No	Yes	The audio bit depth.

Template extension

Mon, 01 Jan 0001 00:00:00 +0000

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:

tokenInfo

Mon, 01 Jan 0001 00:00:00 +0000

OpenSubsonic version: 1

OpenSubsonic extension name apiKeyAuthentication (As returned by getOpenSubsonicExtensions)

Returns data about an API key.

http://your-server/rest/tokenInfo

Parameters

None

Example

http://your-server/rest/tokenInfo.view?apiKey=1234&v=1.13.0&c=AwesomeClientName&f=json

Result

A subsonic-response element with a nested tokenInfo on success, or error 44 on invalid token.

{
"subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "tokenInfo": {
 "username": "token username"
 }
 }
}

<subsonic-response status="ok" version="1.16.1" type="AwesomeServerName" serverVersion="0.1.3 (tag)" openSubsonic="true">
 <tokenInfo username="token username"></tokenInfo>
</subsonic-response>

Does not exist.

Field	Type	Req.	OpenS.	Details
`tokenInfo`	`tokenInfo`	Yes	Yes	Information about the token

Transcode Offset

Mon, 01 Jan 0001 00:00:00 +0000

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.

transcodeDecision

Mon, 01 Jan 0001 00:00:00 +0000

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

Field	Type	Req.	OpenS.	Details
`canDirectPlay`	boolean	Yes	Yes	Whether the media can be played directly by the client.
`canTranscode`	boolean	Yes	Yes	Whether the media can be transcoded by the server.
`transcodeReason`	string[]	No	Yes	An array of reasons why transcoding is necessary. The strings are server specific made for logging purpose, the server should return 1 string per direct play profile.
`errorReason`	string	No	Yes	A description of an error that occurred.
`transcodeParams`	string	No	Yes	An server internal value to be passed to the transcode endpoint, the value needs to be properly escaped to be reused as is in url parameter. See `getTranscodeStream`. The client may not use the value instantly and should be kept valid by the server for a reasonable duration if stored in memory.
`sourceStream`	StreamDetails	No	Yes	Details about the source media stream.
`transcodeStream`	StreamDetails	No	Yes	Details about the target transcoded stream if `canTranscode` is true.

Transcoding

Mon, 01 Jan 0001 00:00:00 +0000

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.

TranscodingProfile

Mon, 01 Jan 0001 00:00:00 +0000

{
 "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.