The OpenSubsonic API allows anyone to build their own programs using a compatible server, whether they’re on the web, the desktop, or on mobile devices. All the OpenSubsonic-compatible apps (clients and servers) are built using the OpenSubsonic API.
The OpenSubsonic API allows you to call methods that respond in REST style XML or JSON. Since most clients now only rely on JSON, this documentation only shows the JSON answers in the documentation.
This project is built upon the original Subsonic API.
Issues for some of the issues this project tries to solve over the original API.
Participants
OpenSubsonic is built with servers and clients trying to improve the global media center ecosystem by providing a common expandable API that can fit most of the needs of modern music apps.
Any server or client can join the organization and make proposals for OpenSubsonic. The only condition is that if (as a client) you request an API extension that is accepted, you engage yourself in implementing it in your client in a timely manner.
The OpenSubsonic API has several goals, which include:
Being an open, collaboratively maintained specification.
Ensuring security across all extensions.
The API aims for consistent results across all servers, ensuring that every request produces the same outcome. The API definition must be clear and precise, eliminating any ambiguity about the expected results.
Maintaining complete backwards compatibility with the existing Subsonic API.
Offering piecewise optional implementation for servers and clients.
Addressing Issues with the Subsonic API
Some of the issues the OpenSubsonic API aims to address include:
Outdated and insecure authentication methods.
Suboptimal versioning schema.
Insufficient methods for expressing server functionality.
Lack of an open and collaborative way to evolve the API.
By extending the existing Subsonic API, the OpenSubsonic API hopes to create a more secure, flexible, and collaborative environment for the Subsonic ecosystem.
Join us
Feel free to join the OpenSubsonic forum for discussions, suggestions, and questions.
1 - OpenSubsonic API
API details and methods.
See API Reference for the basic API documentation. (Mandatory parameters, authentication, error handling, …)
Be sure to read OpenSubsonic changes to easily identify the changes brought by OpenSubsonic.
File structure vs ID3 tags
Starting with version 1.8.0, the API provides methods for accessing the media collection organized according to ID3 tags, rather than file structure.
Please note that all methods take the following parameters:
Parameter
Req.
OpenS.
Default
Comment
u
Yes**
The username.
p
Yes*
The password, either in clear text or hex-encoded with a “enc:” prefix. Since 1.13.0 this should only be used for testing purposes.
t
Yes*
(Since 1.13.0) The authentication token computed as md5(password + salt). See below for details.
s
Yes*
(Since 1.13.0) A random string (“salt”) used as input for computing the password hash. See below for details.
apiKey
Yes**
Yes
[OS] An API key used for authentication
v
Yes
The protocol version implemented by the client, i.e., the version of the subsonic-rest-api.xsd schema used (see below).
c
Yes
A unique string identifying the client application.
f
No
xml
Request data to be returned in this format. Supported values are “xml”, “json” (since 1.4.0) and “jsonp” (since 1.6.0). If using jsonp, specify name of javascript callback function using a callback parameter.
*) Either p or both t and s must be specified.
**) If apiKey is specified, then none of p, t, s, nor u can be specified.
Remember to URL encode the request parameters. All methods (except those that return binary data) returns XML documents conforming to the subsonic-rest-api.xsd schema. The XML documents are encoded with UTF-8.
POST support
OpenSubsonic add official support for application/x-www-form-urlencoded POST to pass the argument.
Check that the server support the HTTP form POST extension before using it.
The arguments can then be passed in the POST body (Do not forget to URL encode both the keys and values), this allows to overcome the URL size limits when passing many parameters for playlists for example.
curl -v -X POST -H 'Content-Type: application/x-www-form-urlencoded' 'http://your-server/rest/ping.view' --data 'c=AwesomeClientName&v=1.12.0&f=json&u=joe&p=sesame'
Authentication
If you are targeting API version 1.12.0 or earlier, authentication is performed by sending the password as clear text or hex-encoded. Examples:
Starting with API version 1.13.0, the recommended authentication scheme is to send an authentication token, calculated as a one-way salted hash of the password.
This involves two steps:
For each REST call, generate a random string called the salt. Send this as parameter s.
Use a salt length of at least six characters.
Calculate the authentication token as follows: token = md5(password + salt). The md5() function takes a string and returns the 32-byte ASCII hexadecimal representation of the MD5 hash, using lower case characters for the hex values. The ‘+’ operator represents concatenation of the two strings. Treat the strings as UTF-8 encoded when calculating the hash. Send the result as parameter t.
For example: if the password is sesame and the random salt is c19b2d, then token = md5(“sesamec19b2d”) = 26719a1196d2a940705a59634eb18eab. The corresponding request URL then becomes:
For servers that implement API Key authentication, the recommended authentication is to use an API key.
This is a token generated from the Subsonic server.
It must be passed in in as apiKey=<API key>, and the u parameter must not be provided.
Note that u/p may still be used by servers which are backed by LDAP/PAM/other authentication.
All API endpoint unless noted otherwise returns a subsonic-response that indicate the result of the command and give some information about the server.
If a method fails it will return an error code and message in an error element. In addition, the status attribute of the subsonic-response root element will be set to failed instead of ok. For example:
The trial period for the Subsonic server is over. Please upgrade to Subsonic Premium. Visit subsonic.org for details.
70
The requested data was not found.
OpenSubsonic
Servers must return error 41 if they do not support token-based authentication, 42 if they do not support any other authentication mechanism (password-based and/or API key-based), and 43 if multiple conflicting authentication parameters are passed in at the same time.
Note that even though the error text for 41 is Token authentication not supported for LDAP users., it actually implies that Token authentication is not supported for any reason.
To indicate differences between cases (where LDAP is used, versus no LDAP), servers may use the new helpUrl field.
New fields are added, see error
3 - OpenSubsonic changes
API changes in OpenSubsonic API vs the original Subsonic API.
Documentation
In the documentation all changes from the original Subsonic API will be emphasized with the following warning:
OpenSubsonic
Changes (Required or optional) related to OpenSubsonic.
All endpoints or responses modified by the OpenSubsonic API will have [OS] indicator in the navigation menu.
Most servers and clients have dedicated pages to show what parts of OpenSubsonic they support. See Overview
OpenSubsonic expand the original API via 3 different ways:
Clarifications: Documentation improvement to ensure consistency in server answers or actions where doubt was possible.
Extensions: Non breaking changes to the API to improve clients life. Like new returned field, or new parameters to existing functions.
Additions: New endpoints added to provide functions that could not be provided via non breaking extensions.
Required changes
OpenSubsonic is built to be mostly optional to ease the burden on the servers who can’t support some features, while still allowing clients to precisely know what the servers support without having to guess.
To achieve this servers supporting OpenSubsonic have to support a very minimal subset of things.
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).
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 umust 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
4.2 - Artist role filter
Add support for filtering artist lists by artist role.
When a server supports this extension it means that it supports filtering the returned artists by role: the role parameter of the getArtists endpoint and the artistRole parameter of the search3 endpoint. (The parameter is named artistRole on search3 to disambiguate it from that endpoint’s album and song results.)
Version 1
You can now filter the artists returned by getArtists and search3 by role, letting clients choose whether they want album artists, track artists, or every artist regardless of role.
Historically these endpoints return only album artists. Some clients want the full set of artists (composers, track artists, etc.) - for example to mirror the whole library - while legacy clients rely on the album-artist-only behavior. This extension lets the client, rather than the server, decide.
The parameter may be repeated to request several roles, using the values found in the ArtistID3roles field (e.g. albumartist, artist, composer). An artist is returned if it has any of the requested roles. The special value all returns every artist regardless of role.
When the parameter is omitted the server returns what it does today, so the extension is purely additive and existing clients are unaffected. On search3, the parameter only affects the returned artists; albums and songs are unaffected.
This extension requires the support of the role parameter of getArtists and the artistRole parameter of search3.
4.3 - getPodcastEpisode
Add support for retrieving individual podcast episode metadata.
This extension requires that the server support passing API arguments via POST with the arguments respecting the application/x-www-form-urlencoded format.
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.
4.5 - Index based Queue
Add’s support for specifying and querying the play queue with index.
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.
4.6 - Playback Report
Add support for client playback timeline reporting.
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 agentsmust 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)
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.
Changes the password of an existing user on the server.
http://your-server/rest/changePassword Since 1.1.0
Changes the password of an existing user on the server, using the following parameters. You can only change your own password unless you have admin privileges.
Parameters
Parameter
Req.
OpenS.
Default
Comment
username
Yes
The name of the user which should change its password.
password
Yes
The new password of the new user, either in clear text of hex-encoded (see above).
http://your-server/rest/createPodcastChannel Since 1.9.0
Adds a new Podcast channel. Note: The user must be authorized for Podcast administration (see Settings > Users > User is allowed to administrate Podcasts).
Creates a public URL that can be used by anyone to stream music or video from the server. The URL is short and suitable for posting on Facebook, Twitter etc. Note: The user must be authorized to share (see Settings > Users > User is allowed to share files with anyone).
Parameters
Parameter
Req.
OpenS.
Default
Comment
id
Yes
ID of a song, album or video to share. Use one id parameter for each entry to share.
description
No
A user-defined description that will be displayed to people visiting the shared media.
expires
No
The time at which the share expires. Given as milliseconds since 1970.
http://your-server/rest/deletePodcastChannel Since 1.9.0
Deletes a Podcast channel. Note: The user must be authorized for Podcast administration (see Settings > Users > User is allowed to administrate Podcasts).
http://your-server/rest/deletePodcastEpisode Since 1.9.0
Deletes a Podcast episode. Note: The user must be authorized for Podcast administration (see Settings > Users > User is allowed to administrate Podcasts).
Returns binary data on success, or an XML document on error (in which case the HTTP content type will start with βtext/xmlβ).
5.17 - downloadPodcastEpisode
Request the server to start downloading a given Podcast episode.
http://your-server/rest/downloadPodcastEpisode Since 1.9.0
Request the server to start downloading a given Podcast episode. Note: The user must be authorized for Podcast administration (see Settings > Users > User is allowed to administrate Podcasts).
A subsonic-response element with a top-level sonicMatch array on success. The returned path MUST contain the start song as the first entry and the end song as the last entry.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true,
"albumInfo": {
"notes": "Download the full release here (creative commons). These cripsy beats are ripe with thumping funk and techno influences, sample wizardry and daring shuffles. Composed with the help of unique sound plugins which were especially programmed to measure Comfort Fitβs needs and wishes, we think the chances arenβt bad that youβll fall for the unique sound signature, bounce and elegance of this unusual Hip Hop production. Ltj bukem / Good looking Rec., UK: \"Really love this music.\" Velanche / XLR8R, UK: \"Awesome job he's done... overall production is dope.\" Kwesi / BBE Music, UK: \"Wooooooowwwww... WHAT THE FUCK! THIS IS WHAT",
"musicBrainzId": "6e1d48f7-717c-416e-af35-5d2454a13af2",
"smallImageUrl": "http://localhost:8989/play/art/0f8c3cbd6b0b22c3b5402141351ac812/album/21/thumb34.jpg",
"mediumImageUrl": "http://localhost:8989/play/art/41b16680dc1b3aaf5dfba24ddb6a1712/album/21/thumb64.jpg",
"largeImageUrl": "http://localhost:8989/play/art/e6fd8d4e0d35c4436e56991892bfb27b/album/21/thumb174.jpg" }
}
}
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"albumInfo": {
"notes": "Download the full release here (creative commons). These cripsy beats are ripe with thumping funk and techno influences, sample wizardry and daring shuffles. Composed with the help of unique sound plugins which were especially programmed to measure Comfort Fitβs needs and wishes, we think the chances arenβt bad that youβll fall for the unique sound signature, bounce and elegance of this unusual Hip Hop production. Ltj bukem / Good looking Rec., UK: \"Really love this music.\" Velanche / XLR8R, UK: \"Awesome job he's done... overall production is dope.\" Kwesi / BBE Music, UK: \"Wooooooowwwww... WHAT THE FUCK! THIS IS WHAT",
"musicBrainzId": "6e1d48f7-717c-416e-af35-5d2454a13af2",
"smallImageUrl": "http://localhost:8989/play/art/0f8c3cbd6b0b22c3b5402141351ac812/album/21/thumb34.jpg",
"mediumImageUrl": "http://localhost:8989/play/art/41b16680dc1b3aaf5dfba24ddb6a1712/album/21/thumb64.jpg",
"largeImageUrl": "http://localhost:8989/play/art/e6fd8d4e0d35c4436e56991892bfb27b/album/21/thumb174.jpg" }
}
}
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true,
"albumInfo": {
"notes": "Download the full release here (creative commons). These cripsy beats are ripe with thumping funk and techno influences, sample wizardry and daring shuffles. Composed with the help of unique sound plugins which were especially programmed to measure Comfort Fitβs needs and wishes, we think the chances arenβt bad that youβll fall for the unique sound signature, bounce and elegance of this unusual Hip Hop production. Ltj bukem / Good looking Rec., UK: \"Really love this music.\" Velanche / XLR8R, UK: \"Awesome job he's done... overall production is dope.\" Kwesi / BBE Music, UK: \"Wooooooowwwww... WHAT THE FUCK! THIS IS WHAT",
"musicBrainzId": "6e1d48f7-717c-416e-af35-5d2454a13af2",
"smallImageUrl": "http://localhost:8989/play/art/0f8c3cbd6b0b22c3b5402141351ac812/album/21/thumb34.jpg",
"mediumImageUrl": "http://localhost:8989/play/art/41b16680dc1b3aaf5dfba24ddb6a1712/album/21/thumb64.jpg",
"largeImageUrl": "http://localhost:8989/play/art/e6fd8d4e0d35c4436e56991892bfb27b/album/21/thumb174.jpg" }
}
}
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"albumInfo": {
"notes": "Download the full release here (creative commons). These cripsy beats are ripe with thumping funk and techno influences, sample wizardry and daring shuffles. Composed with the help of unique sound plugins which were especially programmed to measure Comfort Fitβs needs and wishes, we think the chances arenβt bad that youβll fall for the unique sound signature, bounce and elegance of this unusual Hip Hop production. Ltj bukem / Good looking Rec., UK: \"Really love this music.\" Velanche / XLR8R, UK: \"Awesome job he's done... overall production is dope.\" Kwesi / BBE Music, UK: \"Wooooooowwwww... WHAT THE FUCK! THIS IS WHAT",
"musicBrainzId": "6e1d48f7-717c-416e-af35-5d2454a13af2",
"smallImageUrl": "http://localhost:8989/play/art/0f8c3cbd6b0b22c3b5402141351ac812/album/21/thumb34.jpg",
"mediumImageUrl": "http://localhost:8989/play/art/41b16680dc1b3aaf5dfba24ddb6a1712/album/21/thumb64.jpg",
"largeImageUrl": "http://localhost:8989/play/art/e6fd8d4e0d35c4436e56991892bfb27b/album/21/thumb174.jpg" }
}
}
Returns a list of random, newest, highest rated etc. albums. Similar to the album lists on the home page of the Subsonic web interface.
Parameters
Parameter
Req.
OpenS.
Default
Comment
type
Yes
The list type. Must be one of the following: random, newest, highest, frequent, recent. Since 1.8.0 you can also use alphabeticalByName or alphabeticalByArtist to page through all albums alphabetically, and starred to retrieve starred albums. Since 1.10.1 you can use byYear and byGenre to list albums in a given year range or genre.
size
No
10
The number of albums to return. Max 500.
offset
No
0
The list offset. Useful if you for example want to page through the list of newest albums.
fromYear
Yes (if type is byYear)
The first year in the range. If fromYear > toYear a reverse chronological list is returned.
toYear
Yes (if type is byYear)
The last year in the range.
genre
Yes (if type is byGenre)
The name of the genre, e.g., “Rock”.
musicFolderId
No
(Since 1.11.0) Only return albums in the music folder with the given ID. See getMusicFolders.
Similar to getAlbumList, but organizes music according to ID3 tags.
Parameters
Parameter
Req.
OpenS.
Default
Comment
type
Yes
The list type. Must be one of the following: random, newest, highest, frequent, recent. Since 1.8.0 you can also use alphabeticalByName or alphabeticalByArtist to page through all albums alphabetically, and starred to retrieve starred albums. Since 1.10.1 you can use byYear and byGenre to list albums in a given year range or genre.
size
No
10
The number of albums to return. Max 500.
offset
No
0
The list offset. Useful if you for example want to page through the list of newest albums.
fromYear
Yes (if type is byYear)
The first year in the range. If fromYear > toYear a reverse chronological list is returned.
toYear
Yes (if type is byYear)
The last year in the range.
genre
Yes (if type is byGenre)
The name of the genre, e.g., “Rock”.
musicFolderId
No
(Since 1.11.0) Only return albums in the music folder with the given ID. See getMusicFolders.
Similar to getIndexes, but organizes music according to ID3 tags.
Parameters
Parameter
Req.
OpenS.
Default
Comment
musicFolderId
No
If specified, only return artists in the music folder with the given ID. See getMusicFolders.
role
No
Yes
Repeat this parameter to filter the returned artists by one or more roles. Requires the Artist role filter extension.
OpenSubsonic
If the server supports the Artist role filter extension, it must accept the role parameter and filter the returned artists accordingly.
role may be repeated to request several roles, using the values found in the ArtistID3roles field (e.g. albumartist, artist, composer). An artist is returned if it has any of the requested roles. The special value all returns every artist regardless of role.
When role is omitted the server returns what it does today, so the extension is purely additive and existing clients are unaffected.
<subsonic-responsestatus="ok"version="1.16.1"type="AwesomeServerName"serverVersion="0.1.3 (tag)"openSubsonic="true"><indexeslastModified="237462836472342"ignoredArticles="The El La Los Las Le Les"><shortcutid="11"name="Audio books"/><shortcutid="10"name="Podcasts"/><indexname="A"><artistid="1"name="ABBA"/><artistid="2"name="Alanis Morisette"/><artistid="3"name="Alphaville"starred="2013-11-02T12:30:00"/></index><indexname="B"><artistname="Bob Dylan"id="4"/></index><childid="111"parent="11"title="Dancing Queen"isDir="false"album="Arrival"artist="ABBA"track="7"year="1978"genre="Pop"coverArt="24"size="8421341"contentType="audio/mpeg"suffix="mp3"duration="146"bitRate="128"path="ABBA/Arrival/Dancing Queen.mp3"/><childid="112"parent="11"title="Money, Money, Money"isDir="false"album="Arrival"artist="ABBA"track="7"year="1978"genre="Pop"coverArt="25"size="4910028"contentType="audio/flac"suffix="flac"transcodedContentType="audio/mpeg"transcodedSuffix="mp3"duration="208"bitRate="128"path="ABBA/Arrival/Money, Money, Money.mp3"/></indexes></subsonic-response>
<subsonic-responsestatus="ok"version="1.16.1"type="AwesomeServerName"><indexeslastModified="237462836472342"ignoredArticles="The El La Los Las Le Les"><shortcutid="11"name="Audio books"/><shortcutid="10"name="Podcasts"/><indexname="A"><artistid="1"name="ABBA"/><artistid="2"name="Alanis Morisette"/><artistid="3"name="Alphaville"starred="2013-11-02T12:30:00"/></index><indexname="B"><artistname="Bob Dylan"id="4"/></index><childid="111"parent="11"title="Dancing Queen"isDir="false"album="Arrival"artist="ABBA"track="7"year="1978"genre="Pop"coverArt="24"size="8421341"contentType="audio/mpeg"suffix="mp3"duration="146"bitRate="128"path="ABBA/Arrival/Dancing Queen.mp3"/><childid="112"parent="11"title="Money, Money, Money"isDir="false"album="Arrival"artist="ABBA"track="7"year="1978"genre="Pop"coverArt="25"size="4910028"contentType="audio/flac"suffix="flac"transcodedContentType="audio/mpeg"transcodedSuffix="mp3"duration="208"bitRate="128"path="ABBA/Arrival/Money, Money, Money.mp3"/></indexes></subsonic-response>
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true,
"lyrics": {
"artist": "Metallica",
"title": "Blitzkrieg",
"value": "Let us have peace, let us have life\n\nLet us escape the cruel night\n\nLet us have time, let the sun shine\n\nLet us beware the deadly sign\n\n\n\nThe day is coming\n\nArmageddon's near\n\nInferno's coming\n\nCan we survive the blitzkrieg?\n\nThe blitzkrieg\n\nThe blitzkrieg\n\n\n\nSave us from fate, save us from hate\n\nSave ourselves before it's too late\n\nCome to our need, hear our plea\n\nSave ourselves before the earth bleeds\n\n\n\nThe day is dawning\n\nThe time is near\n\nAliens calling\n\nCan we survive the blitzkrieg?" }
}
}
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"lyrics": {
"artist": "Metallica",
"title": "Blitzkrieg",
"value": "Let us have peace, let us have life\n\nLet us escape the cruel night\n\nLet us have time, let the sun shine\n\nLet us beware the deadly sign\n\n\n\nThe day is coming\n\nArmageddon's near\n\nInferno's coming\n\nCan we survive the blitzkrieg?\n\nThe blitzkrieg\n\nThe blitzkrieg\n\n\n\nSave us from fate, save us from hate\n\nSave ourselves before it's too late\n\nCome to our need, hear our plea\n\nSave ourselves before the earth bleeds\n\n\n\nThe day is dawning\n\nThe time is near\n\nAliens calling\n\nCan we survive the blitzkrieg?" }
}
}
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.
Furthermore, there is special behavior for the value xxx.
While not an ISO code, it is commonly used by taggers and other parsing software.
Clients should treat xxx as not having a specified language (equivalent to the und code).
<subsonic-responsestatus="ok"version="1.16.1"type="AwesomeServerName"serverVersion="0.1.3 (tag)"openSubsonic="true"><lyricsList><structuredLyricsdisplayArtist="Muse"displayTitle="Hysteria"lang="en"offset="-100"synced="true"><linestart="0">It's bugging me</line><linestart="2000">Grating me</line><linestart="3001">And twisting me around...</line></structuredLyrics><structuredLyricsdisplayArtist="Muse"displayTitle="Hysteria"lang="en"offset="100"synced="false"><line>It's bugging me</line><line>Grating me</line><line>And twisting me around...</line></structuredLyrics></lyricsList></subsonic-response>
Does not exist.
Version 2 (enhanced=true)
When enhanced=true is passed, the response includes kind to classify lyric tracks, cueLine arrays with word/syllable-level timing, cue byteStart / byteEnd offsets into cueLine.value, optional per-entry agents metadata for agent attribution, and additional tracks such as translations and pronunciations.
<subsonic-responsestatus="ok"version="1.16.1"type="AwesomeServerName"serverVersion="0.1.3 (tag)"openSubsonic="true"><lyricsList><structuredLyricskind="main"lang="ko"synced="true"><linestart="2747">λμ λ¬ μκ°</line><linestart="6214">λͺ¨λ κ² λ¬λΌμ‘μ΄</line><cueLineindex="0"start="2747"end="6214"value="λμ λ¬ μκ°"><cuestart="2747"end="3018"byteStart="0"byteEnd="2">λ</cue><cuestart="3018"end="3179"byteStart="3"byteEnd="5">μ</cue><cuestart="3179"end="3582"byteStart="6"byteEnd="6"></cue><cuestart="3582"end="4100"byteStart="7"byteEnd="9">λ¬</cue><cuestart="4100"end="4500"byteStart="10"byteEnd="10"></cue><cuestart="4500"end="5200"byteStart="11"byteEnd="13">μ</cue><cuestart="5200"end="6214"byteStart="14"byteEnd="16">κ°</cue></cueLine><cueLineindex="1"start="6214"end="9000"value="λͺ¨λ κ² λ¬λΌμ‘μ΄"><cuestart="6214"end="6800"byteStart="0"byteEnd="2">λͺ¨</cue><cuestart="6800"end="7200"byteStart="3"byteEnd="5">λ </cue><cuestart="7200"end="7600"byteStart="6"byteEnd="6"></cue><cuestart="7600"end="8000"byteStart="7"byteEnd="9">κ²</cue><cuestart="8000"end="8400"byteStart="10"byteEnd="10"></cue><cuestart="8400"end="9000"byteStart="11"byteEnd="22">λ¬λΌμ‘μ΄</cue></cueLine></structuredLyrics><structuredLyricskind="translation"lang="eng"synced="true"><linestart="2747">The moment I opened my eyes</line><linestart="6214">Everything had changed</line></structuredLyrics><structuredLyricskind="pronunciation"lang="ko-Latn"synced="true"><linestart="2747">nuneul tteun sungan</line><linestart="6214">modeun ge dallajyeosseo</line><cueLineindex="0"start="2747"end="6214"value="nuneul tteun sungan"><cuestart="2747"end="3179"byteStart="0"byteEnd="5">nuneul</cue><cuestart="3582"end="4100"byteStart="7"byteEnd="11">tteun</cue><cuestart="4500"end="6214"byteStart="13"byteEnd="18">sungan</cue></cueLine><cueLineindex="1"start="6214"end="9000"value="modeun ge dallajyeosseo"><cuestart="6214"end="7200"byteStart="0"byteEnd="5">modeun</cue><cuestart="7600"end="8000"byteStart="7"byteEnd="8">ge</cue><cuestart="8400"end="9000"byteStart="10"byteEnd="22">dallajyeosseo</cue></cueLine></structuredLyrics></lyricsList></subsonic-response>
Does not exist.
Example with background vocals (agents + agentId)
When a source distinguishes both a lead/default vocal layer and background vocals within the same lyric line, the server emits a shared agents array on that structuredLyrics entry and splits the lyric into separate cueLines with the same index. Each cueLine references one agent via agentId, contains that agent/layer’s renderable text in value, and the cueLine whose referenced agent has role: "main" comes first. The parent line remains the combined fallback line:
Example with multiple agents (TTML-style attribution)
When a source has multiple named singers (e.g. a duet from TTML with ttm:agent and ttm:name), the server stores those identities once in agents and each cueLine references the relevant singer or group via agentId:
<cueLineindex="0"start="0"end="2400"value="Oh love love me tonight"><cuestart="0"end="300"byteStart="0"byteEnd="1">Oh</cue><cuestart="900"end="1300"byteStart="8"byteEnd="11">love</cue><cuestart="1300"end="1600"byteStart="13"byteEnd="14">me</cue><cuestart="1600"end="2400"byteStart="16"byteEnd="22">tonight</cue></cueLine>
Without enhanced=true, the response is identical to version 1:
Only kind="main" entries are returned (the kind field itself is omitted)
No cueLine arrays are included
The existing line array is always present and unchanged
cueLine is a parallel structure, not a replacement for line
Servers that don’t support TTML or word-level timing simply never include these fields. Clients that don’t support karaoke display simply ignore them.
cueLine behavior
cueLine data is only meaningful when synced=true. Servers must not emit cueLine arrays for unsynced lyrics.
Within a cueLine, cue.endmust be either present on all cues or none (all-or-nothing). When the source provides partial end times, servers must fill missing values. When no cues have end times, end is omitted from all cues. This is a documented contract rule; the OpenAPI schema does not encode the all-or-none shape structurally.
agents are scoped to a single structuredLyrics entry. When present, agentsmust contain at least one entry, and each agents[].idmust be unique within that entry. agents are optional for simple unattributed single-layer lyrics. When a structuredLyrics entry represents multiple vocal agents/layers, it must include agents; a single-agent attributed/default entry may also include agents, and if it does, exactly one agent must use role: "main". agents should not be emitted without cueLine data.
When multiple cueLines share the same index, the cueLine whose referenced agent has role: "main"must come first. Clients should not assume every source can distinguish or emit multiple agents.
When multiple agent cueLines share the same index, each cueLine.valuemust be independently renderable for that agent/layer. Clients should use structuredLyrics.line[index].value as the combined fallback line, not as the per-agent cueLine text.
If agents is present, every cueLine in that entry must include agentId, and each agentIdmust match exactly one agents[].id in that entry. If agents is absent, cueLines must not include agentId.
Every cue must include byteStart / byteEnd, and every cueLinemust include value. The offsets are 0-based inclusive positions into the final UTF-8 encoding of that cueLine.value, with no normalization step, and byteStartmust be β€ byteEnd. The OpenAPI schema enforces the presence of these fields, but not the cross-field ordering constraint structurally.
Cues within a cueLinemust not overlap (i.e. cue[n].endmust be β€ cue[n+1].start). Servers must normalize any source overlaps so that clients can iterate cues sequentially without overlap-resolution logic. Overlapping timing across different cueLines (different agentId values) is expected, since those represent parallel vocal layers.
Cues where start == end (zero-duration) may occur. Clients should treat these as instantaneous markers.
structuredLyrics entries are independent across kind tracks, including main. Clients should not assume 1:1 correspondence of line arrays or cueLine arrays between tracks.
Cue counts may differ across kind tracks for the same lyric passage. Clients should not assume 1:1 cue correspondence between tracks.
For right-to-left scripts (Arabic, Hebrew), cues are in logical reading order. Clients are responsible for bidi rendering.
5.39 - getMusicDirectory
Returns a listing of all files in a music directory.
http://your-server/rest/getMusicDirectory Since 1.0.0
Returns a listing of all files in a music directory. Typically used to get list of albums for an artist, or list of songs for an album.
Parameters
Parameter
Req.
OpenS.
Default
Comment
id
Yes
A string which uniquely identifies the music folder. Obtained by calls to getIndexes or getMusicDirectory.
(Since 1.8.0) If specified, return playlists for this user rather than for the authenticated user. The authenticated user must have admin role if this parameter is used.
Returns the state of the play queue for this user (as set by savePlayQueue). 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).
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).
Returns all Podcast channels the server subscribes to, and (optionally) their episodes. This method can also be used to return details for only one channel - refer to the id parameter. A typical use case for this method would be to first retrieve all channels without episodes, and then retrieve all episodes for the single channel the user selects.
Parameters
Parameter
Req.
OpenS.
Default
Comment
includeEpisodes
No
true
(Since 1.9.0) Whether to include Podcast episodes in the returned result.
id
No
(Since 1.9.0) If specified, only return the Podcast channel with this ID.
Returns a random collection of songs from the given artist and similar artists.
http://your-server/rest/getSimilarSongs Since 1.11.0
Returns a random collection of songs from the given artist and similar artists, using data from last.fm. Typically used for artist radio features.
Parameters
Parameter
Req.
OpenS.
Default
Comment
id
Yes
The artist, album or song ID.
count
No
50
Max number of songs to return.
OpenSubsonic
In the original Subsonic, the specification for getSimilarSongs2 implies that it should be used instead of this endpoint if the client and/or server organizes by ID3 tags.
For OpenSubsonic servers, getSimilarSongs may be used instead of getSimilarSongs2 when organizing by ID3 tags, and there are no differences in results returned when using artist IDs.
Returns similar tracks based on sonic (audio) analysis.
http://your-server/rest/getSonicSimilarTracks
Returns tracks that are sonically similar to a given track, based on audio analysis. Results are ordered from most similar to least similar. Each result includes a normalized similarity score to the query track. Higher values indicate greater similarity, with 1.0 meaning it is the exact same song and 0.0 meaning the most different.
Returns a transcode decision for a given media file.
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.
This endpoint must be accessed using a POST request
5.62 - getTranscodeStream
Returns a transcoded media stream.
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.
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.
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.
Get details about a given user, including which authorization roles and folder access it has. Can be used to enable/disable certain features in the client, such as jukebox control.
Parameters
Parameter
Req.
OpenS.
Default
Comment
username
Yes
The name of the user to retrieve. You can only retrieve your own user unless you have admin privileges.
Get details about all users, including which authorization roles and folder access they have. Only users with admin privileges are allowed to call this method.
Creates an HLS (HTTP Live Streaming) playlist used for streaming video or audio. HLS is a streaming protocol implemented by Apple and works by breaking the overall stream into a sequence of small HTTP-based file downloads. It’s supported by iOS and newer versions of Android. This method also supports adaptive bitrate streaming, see the bitRate parameter.
Parameters
Parameter
Req.
OpenS.
Default
Comment
id
Yes
A string which uniquely identifies the media file to stream.
bitRate
No
If specified, the server will attempt to limit the bitrate to this value, in kilobits per second. If this parameter is specified more than once, the server will create a variant playlist, suitable for adaptive bitrate streaming. The playlist will support streaming at all the specified bitrates. The server will automatically choose video dimensions that are suitable for the given bitrates. Since 1.9.0 you may explicitly request a certain width (480) and height (360) like so: bitRate=1000@480x360
audioTrack
No
The ID of the audio track to use. SeegetVideoInfo for how to get the list of available audio tracks for a video.
Returns an M3U8 playlist on success (content type “application/vnd.apple.mpegurl”), or an XML document on error (in which case the HTTP content type will start with “text/xml”).
5.68 - jukeboxControl
Controls the jukebox, i.e., playback directly on the server’s audio hardware.
http://your-server/rest/jukeboxControl Since 1.2.0
Controls the jukebox, i.e., playback directly on the server’s audio hardware. Note: The user must be authorized to control the jukebox (see Settings > Users > User is allowed to play files in jukebox mode).
Parameters
Parameter
Req.
OpenS.
Default
Comment
action
Yes
The operation to perform. Must be one of: get, status (since 1.7.0), set (since 1.7.0), start, stop, skip, add, clear, remove, shuffle, setGain
index
No
Used by skip and remove. Zero-based index of the song to skip to or remove.
offset
No
(Since 1.7.0) Used by skip. Start playing this many seconds into the track.
id
No
Used by add and set. ID of song to add to the jukebox playlist. Use multiple id parameters to add many songs in the same request. (set is similar to a clear followed by a add, but will not change the currently playing track.)
gain
No
Used by setGain to control the playback volume. A float value between 0.0 and 1.0.
Requests the server to check for new Podcast episodes.
http://your-server/rest/refreshPodcasts Since 1.9.0
Requests the server to check for new Podcast episodes. Note: The user must be authorized for Podcast administration (see Settings > Users > User is allowed to administrate Podcasts).
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.
The starting state is an indicator that the player is starting (or restarting) the media, if the server support scrobble this is the indicator to start monitoring for this playback session even if it’s the same song.
The server should only start moving it’s internal clock after the state changes to playing to take in account possible long buffering.
Parameters
Parameter
Req.
OpenS.
Default
Comment
mediaId
Yes
Yes
The ID of the media being reported.
mediaType
Yes
Yes
Either song or podcast so the server knows what the mediaId is referring to.
positionMs
Yes
Yes
The playback position in milliseconds.
state
Yes
Yes
Playback state: starting, playing, paused, or stopped.
playbackRate
No
Yes
1.0
Playback speed multiplier.
ignoreScrobble
No
Yes
false
If true, server should only update now-playing display/state and should not trigger scrobble/playcount side effects.
http://your-server/rest/savePlayQueue Since 1.12.0
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).
Parameters
Parameter
Req.
OpenS.
Default
Comment
id
No
ID of a song in the play queue. Use one id parameter for each song in the play queue.
current
Yes (subsonic) / No (OpenSubsonic)*
The ID of the current playing song.
position
No
The position in milliseconds within the currently playing song.
Errata/OpenSubsonic
* In the original Subsonic, despite the claims that current is optional, it was required and must be in the list of id.
Note: For OpenSubsonic servers, id is optional. Send a call without any parameters to clear the currently saved queue.
For OpenSubsonic servers only, current is required unlessid is empty.
If position is empty, servers should treat the position as 0.
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.
Parameters
Parameter
Req.
OpenS.
Default
Comment
id
No
ID of a song in the play queue. Use one id parameter for each song in the play queue.
currentIndex
Yes, unless no id is provided
The 0-based index of the current playing track. This must be between 0 and length of the queue - 1 (inclusive).
position
No
The position in milliseconds within the currently playing song.
Noteid is optional. Send a call without any parameters to clear the currently saved queue.
In this case, currentIndexmust not be set.
If currentIndex is not between 0 and length of the queue - 1 (inclusive), the server must respond with error code 10.
currentIndex is required unless no id is provided.
If position is empty, servers should treat the position as 0.
5.74 - scrobble
Registers the local playback of one or more media files.
Registers the local playback of one or more media files. Typically used when playing media that is cached on the client. This operation includes the following:
“Scrobbles” the media files on last.fm if the user has configured his/her last.fm credentials on the server.
Updates the play count and last played timestamp for the media files. (Since 1.11.0)
Makes the media files appear in the “Now playing” page in the web app, and appear in the list of songs returned by getNowPlaying (Since 1.11.0)
Since 1.8.0 you may specify multiple id (and optionally time) parameters to scrobble multiple files.
Parameters
Parameter
Req.
OpenS.
Default
Comment
id
Yes
A string which uniquely identifies the file to scrobble.
time
No
(Since 1.8.0) The time (in milliseconds since 1 Jan 1970) at which the song was listened to.
submission
No
True
Whether this is a “submission” or a “now playing” notification.
Returns albums, artists and songs matching the given search criteria. Supports paging through the result.
Music is organized according to ID3 tags.
Parameters
Parameter
Requ.
OpenS.
Default
Comment
query
Yes
See below*
Search query.
artistCount
No
20
Maximum number of artists to return.
artistOffset
No
0
Search result offset for artists. Used for paging.
albumCount
No
20
Maximum number of albums to return.
albumOffset
No
0
Search result offset for albums. Used for paging.
songCount
No
20
Maximum number of songs to return.
songOffset
No
0
Search result offset for songs. Used for paging.
musicFolderId
No
(Since 1.12.0) Only return results from music folder with the given ID. See getMusicFolders.
artistRole
No
Yes
Repeat this parameter to filter the returned artists by one or more roles. Requires the Artist role filter extension.
OpenSubsonic
Servers must support an empty query and return all the data to allow clients to properly access all the media information for offline sync.
If the server supports the Artist role filter extension, it must accept the artistRole parameter and filter the returned artists accordingly (albums and songs are unaffected).
artistRole may be repeated to request several roles, using the values found in the ArtistID3roles field (e.g. albumartist, artist, composer). An artist is returned if it has any of the requested roles. The special value all returns every artist regardless of role. When artistRole is omitted the server returns what it does today, so the extension is purely additive and existing clients are unaffected.
The ID of the file (song) or folder (album/artist) to star. Multiple parameters allowed.
albumId
No
The ID of an album to star. Use this rather than id if the client accesses the media collection according to ID3 tags rather than file structure. Multiple parameters allowed.
artistId
No
The ID of an artist to star. Use this rather than id if the client accesses the media collection according to ID3 tags rather than file structure. Multiple parameters allowed.
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.
Returns binary data on success, or an XML document on error (in which case the HTTP content type will start with “text/xml”).
OpenSubsonic
OpenSubsonic servers must not count access to this endpoint as a play and increase playcount. Clients can use the Scrobble endpoint to indicate that a media is played ensuring proper data in all cases.
If the server support the Transcode Offset extension, then it must accept the timeOffset parameter for music too.
The ID of the file (song) or folder (album/artist) to unstar. Multiple parameters allowed.
albumId
No
The ID of an album to unstar. Use this rather than id if the client accesses the media collection according to ID3 tags rather than file structure. Multiple parameters allowed.
artistId
No
The ID of an artist to unstar. Use this rather than id if the client accesses the media collection according to ID3 tags rather than file structure. Multiple parameters allowed.
The password of the user, either in clear text of hex-encoded (see above).
email
No
The email address of the user.
ldapAuthenticated
No
Whether the user is authenticated in LDAP.
adminRole
No
Whether the user is administrator.
settingsRole
No
Whether the user is allowed to change personal settings and password.
streamRole
No
Whether the user is allowed to play files.
jukeboxRole
No
Whether the user is allowed to play files in jukebox mode.
downloadRole
No
Whether the user is allowed to download files.
uploadRole
No
Whether the user is allowed to upload files.
coverArtRole
No
Whether the user is allowed to change cover art and tags.
commentRole
No
Whether the user is allowed to create and edit comments and ratings.
podcastRole
No
Whether the user is allowed to administrate Podcasts.
shareRole
No
Whether the user is allowed to share files with anyone.
videoConversionRole
No
false
(Since 1.15.0) Whether the user is allowed to start video conversions.
musicFolderId
No
(Since 1.12.0) IDs of the music folders the user is allowed access to. Include the parameter once for each folder.
maxBitRate
No
(Since 1.13.0) The maximum bit rate (in Kbps) for the user. Audio streams of higher bit rates are automatically downsampled to this bit rate. Legal values: 0 (no limit), 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320.
Opaque identifier for this agent. The value is only meaningful within the parent structuredLyrics entry and must be unique within that entry
role
string
Yes
Yes
Semantic vocal-layer classification for cueLines that reference this agent. One of: main (lead/default vocal layer), voice (additional explicit individual voice part), bg (background vocals), group (group/chorus vocals). When a structuredLyrics entry uses agents for cue-attributed lyrics, it must define exactly one main agent
name
string
No
Yes
Optional human-readable label for this agent, such as a singer or character name from the source metadata
OpenSubsonic
This is a new OpenSubsonic response type added in extension songLyrics version 2.
Date the specific edition of the album was released. Note: for files using ID3 tags, releaseDate should generally be read from the TDRL tag. Servers that use a different source for this field should document the behavior.
isCompilation
boolean
No
Yes
True if the album is a compilation.
explicitStatus
string
No
Yes
Returns “explicit” if at least one song is explicit, “clean” if no song is explicit and at least one is “clean” else “”.
Note: All OpenSubsonic added fields are optionals. But if a server support a field it must return it with an empty / default value when not present in it’s database so that clients knows what the server supports.
Note: Even if some added fields may looks duplicated, it’s important to still return the legacy data for compatibility reasons.
Date the specific edition of the album was released. Note: for files using ID3 tags, releaseDate should generally be read from the TDRL tag. Servers that use a different source for this field should document the behavior.
isCompilation
boolean
No
Yes
True if the album is a compilation.
explicitStatus
string
No
Yes
Returns “explicit” if at least one song is explicit, “clean” if no song is explicit and at least one is “clean” else “”.
Note: All OpenSubsonic added fields are optionals. But if a server support a field it must return it with an empty / default value when not present in it’s database so that clients knows what the server supports.
Note: Even if some added fields may looks duplicated, it’s important to still return the legacy data for compatibility reasons.
7.4 - albumInfo
Album info.
{
"notes": "Download the full release here (creative commons). These cripsy beats are ripe with thumping funk and techno influences, sample wizardry and daring shuffles. Composed with the help of unique sound plugins which were especially programmed to measure Comfort Fitβs needs and wishes, we think the chances arenβt bad that youβll fall for the unique sound signature, bounce and elegance of this unusual Hip Hop production. Ltj bukem / Good looking Rec., UK: \"Really love this music.\" Velanche / XLR8R, UK: \"Awesome job he's done... overall production is dope.\" Kwesi / BBE Music, UK: \"Wooooooowwwww... WHAT THE FUCK! THIS IS WHAT",
"musicBrainzId": "6e1d48f7-717c-416e-af35-5d2454a13af2",
"smallImageUrl": "http://localhost:8989/play/art/0f8c3cbd6b0b22c3b5402141351ac812/album/21/thumb34.jpg",
"mediumImageUrl": "http://localhost:8989/play/art/41b16680dc1b3aaf5dfba24ddb6a1712/album/21/thumb64.jpg",
"largeImageUrl": "http://localhost:8989/play/art/e6fd8d4e0d35c4436e56991892bfb27b/album/21/thumb174.jpg"}
{
"notes": "Download the full release here (creative commons). These cripsy beats are ripe with thumping funk and techno influences, sample wizardry and daring shuffles. Composed with the help of unique sound plugins which were especially programmed to measure Comfort Fitβs needs and wishes, we think the chances arenβt bad that youβll fall for the unique sound signature, bounce and elegance of this unusual Hip Hop production. Ltj bukem / Good looking Rec., UK: \"Really love this music.\" Velanche / XLR8R, UK: \"Awesome job he's done... overall production is dope.\" Kwesi / BBE Music, UK: \"Wooooooowwwww... WHAT THE FUCK! THIS IS WHAT",
"musicBrainzId": "6e1d48f7-717c-416e-af35-5d2454a13af2",
"smallImageUrl": "http://localhost:8989/play/art/0f8c3cbd6b0b22c3b5402141351ac812/album/21/thumb34.jpg",
"mediumImageUrl": "http://localhost:8989/play/art/41b16680dc1b3aaf5dfba24ddb6a1712/album/21/thumb64.jpg",
"largeImageUrl": "http://localhost:8989/play/art/e6fd8d4e0d35c4436e56991892bfb27b/album/21/thumb174.jpg"}
The list of all roles this artist has in the library.
OpenSubsonic
New fields are added:
musicBrainzId
sortName
roles
Note: All OpenSubsonic added fields are optionals. But if a server support a field it must return it with an empty / default value when not present in it’s database so that clients knows what the server supports.
Note: Even if some added fields may looks duplicated, it’s important to still return the legacy data for compatibility reasons.
The list of all roles this artist has in the library.
OpenSubsonic
New fields are added:
musicBrainzId
sortName
roles
Note: All OpenSubsonic added fields are optionals. But if a server support a field it must return it with an empty / default value when not present in it’s database so that clients knows what the server supports.
Note: Even if some added fields may looks duplicated, it’s important to still return the legacy data for compatibility reasons.
{
"id": "082f435a363c32c57d5edb6a678a28d4",
"parent": "e8a0685e3f3ec6f251649af2b58b8617",
"isDir": false,
"title": "\"polar expedition\"",
"album": "Live at The Casbah - 2005-04-29",
"artist": "The New Deal",
"track": 4,
"year": 2005,
"coverArt": "mf-082f435a363c32c57d5edb6a678a28d4_6410b3ce",
"size": 19866778,
"contentType": "audio/flac",
"suffix": "flac",
"starred": "2023-03-27T09:45:27Z",
"duration": 178,
"bitRate": 880,
"bitDepth": 16,
"samplingRate": 44100,
"channelCount": 2,
"path": "The New Deal/Live at The Casbah - 2005-04-29/04 - \"polar expedition\".flac",
"playCount": 8,
"discNumber": 1,
"created": "2023-03-14T17:51:22.112827504Z",
"albumId": "e8a0685e3f3ec6f251649af2b58b8617",
"artistId": "97e0398acf63f9fb930d7d4ce209a52b",
"type": "music",
"isVideo": false}
Field
Type
Req.
OpenS.
Details
id
string
Yes
The id of the media
parent
string
No
The id of the parent (folder/album)
isDir
boolean
Yes
The media is a directory
title
string
Yes
The media name.
album
string
No
The album name.
artist
string
No
The artist name.
track
int
No
The track number.
year
int
No
The media year.
genre
string
No
The media genre
coverArt
string
No
A covertArt id.
size
long
No
A file size of the media.
contentType
string
No
The mimeType of the media.
suffix
string
No
The file suffix of the media.
transcodedContentType
string
No
The transcoded mediaType if transcoding should happen.
transcodedSuffix
string
No
The file suffix of the transcoded media.
duration
int
No
The duration of the media in seconds.
bitRate
int
No
The bitrate of the media.
bitDepth
int
No
Yes
The bit depth of the media.
samplingRate
int
No
Yes
The sampling rate of the media.
channelCount
int
No
Yes
The number of channels of the media.
path
string
No
The full path of the media.
isVideo
boolean
No
Media is a video
userRating
int
No
The user rating of the media [1-5]
averageRating
number
No
The average rating of the media [1.0-5.0]
playCount
long
No
The play count.
discNumber
int
No
The disc number.
created
string
No
Date the media was created. [ISO 8601]
starred
string
No
Date the media was starred. [ISO 8601]
albumId
string
No
The corresponding album id
artistId
string
No
The corresponding artist id
type
string
No
The generic type of media [music/podcast/audiobook/video]
mediaType
string
No
Yes
The actual media type [song/album/artist] Note: If you support musicBrainzId you must support this field to ensure clients knows what the ID refers to.
Note: All OpenSubsonic added fields are optionals. But if a server support a field it must return it with an empty / default value when not present in it’s database so that clients knows what the server supports.
Note: Even if some added fields may looks duplicated, it’s important to still return the legacy data for compatibility reasons.
The subRole for roles that may require it. Ex: The instrument for the performer role (TMCL/performer tags). Note: For consistency between different tag formats, the TIPL sub roles should be directly exposed in the role field.
When untimed text appears between timed cues, byteStart and byteEnd disambiguate repeated tokens by pointing at the exact substring within the parent cueLine.value. For example, within cueLine.value = "Oh love love me tonight", the timed second love uses byteStart = 8 and byteEnd = 11:
End time in milliseconds. Within a cueLine, endmust be either present on all cues or none. When the source provides partial end times, servers must fill missing values (e.g., using the next cue’s start, or the cueLine’s end for the final cue). When no cues have end times (e.g., Enhanced LRC with start-only timing), end is omitted from all cues. This is a documented contract rule; the OpenAPI schema does not enforce the all-or-none shape structurally
byteStart
integer
Yes
Yes
Zero-based inclusive UTF-8 byte offset into the parent cueLine.value where this cue begins
byteEnd
integer
Yes
Yes
Zero-based inclusive UTF-8 byte offset into the parent cueLine.value where this cue ends
value
string
Yes
Yes
The text of this word or syllable
byteStart / byteEnd behavior
Every cue must include byteStart and byteEnd. The parent cueLinemust include value, the offsets are calculated against the final UTF-8 encoding of that cueLine.value with no normalization step, and byteStartmust be less than or equal to byteEnd. The OpenAPI schema enforces the presence of the fields, but not the cross-field ordering constraint structurally.
OpenSubsonic
This is a new OpenSubsonic response type added in extension songLyrics version 2.
7.20 - cueLine
Word/syllable-level timing data for a lyrics line or agent layer.
<cueLineindex="0"start="1000"end="4000"value="You and I"agentId="lead"><cuestart="1000"end="1800"byteStart="0"byteEnd="3">You </cue><cuestart="1800"end="2400"byteStart="4"byteEnd="7">and </cue><cuestart="2400"end="3200"byteStart="8"byteEnd="8">I</cue></cueLine>
Does not exist.
Example with ambiguous repeated text
When untimed text appears between timed cues, cueLine.value plus cue byteStart / byteEnd offsets identifies the exact occurrence of a repeated token:
<cueLineindex="0"start="0"end="2400"value="Oh love love me tonight"><cuestart="0"end="300"byteStart="0"byteEnd="1">Oh</cue><cuestart="900"end="1300"byteStart="8"byteEnd="11">love</cue><cuestart="1300"end="1600"byteStart="13"byteEnd="14">me</cue><cuestart="1600"end="2400"byteStart="16"byteEnd="22">tonight</cue></cueLine>
Does not exist.
Field
Type
Req.
OpenS.
Details
index
integer
Yes
Yes
Zero-based index into the parent line array this cueLine corresponds to
start
integer
No
Yes
Start time in milliseconds (may differ from the parent line if cues are more precise)
end
integer
No
Yes
End time in milliseconds
value
string
Yes
Yes
Full text for this cueLine. When agent attribution splits one parent line into multiple cueLines, this is the text for that cueLine’s agent/layer, not necessarily the parent line’s combined text. Required because every nested cue defines byteStart / byteEnd against this exact final UTF-8 string
agentId
string
No
Yes
Opaque identifier referencing an agent in the same structuredLyrics entry. If the parent structuredLyrics entry includes agents, every cueLine in that entry must include agentId, and the value must match exactly one agents[].id in that entry. If the parent entry does not include agents, cueLines must not include agentId. When multiple cueLines share the same index, the cueLine whose referenced agent has role: "main"must come first
<indexeslastModified="237462836472342"ignoredArticles="The El La Los Las Le Les"><shortcutid="11"name="Audio books"/><shortcutid="10"name="Podcasts"/><indexname="A"><artistid="1"name="ABBA"/><artistid="2"name="Alanis Morisette"/><artistid="3"name="Alphaville"starred="2013-11-02T12:30:00"/></index><indexname="B"><artistname="Bob Dylan"id="4"/></index><childid="111"parent="11"title="Dancing Queen"isDir="false"album="Arrival"artist="ABBA"track="7"year="1978"genre="Pop"coverArt="24"size="8421341"contentType="audio/mpeg"suffix="mp3"duration="146"bitRate="128"path="ABBA/Arrival/Dancing Queen.mp3"/><childid="112"parent="11"title="Money, Money, Money"isDir="false"album="Arrival"artist="ABBA"track="7"year="1978"genre="Pop"coverArt="25"size="4910028"contentType="audio/flac"suffix="flac"transcodedContentType="audio/mpeg"transcodedSuffix="mp3"duration="208"bitRate="128"path="ABBA/Arrival/Money, Money, Money.mp3"/></indexes>
<indexeslastModified="237462836472342"ignoredArticles="The El La Los Las Le Les"><shortcutid="11"name="Audio books"/><shortcutid="10"name="Podcasts"/><indexname="A"><artistid="1"name="ABBA"/><artistid="2"name="Alanis Morisette"/><artistid="3"name="Alphaville"starred="2013-11-02T12:30:00"/></index><indexname="B"><artistname="Bob Dylan"id="4"/></index><childid="111"parent="11"title="Dancing Queen"isDir="false"album="Arrival"artist="ABBA"track="7"year="1978"genre="Pop"coverArt="24"size="8421341"contentType="audio/mpeg"suffix="mp3"duration="146"bitRate="128"path="ABBA/Arrival/Dancing Queen.mp3"/><childid="112"parent="11"title="Money, Money, Money"isDir="false"album="Arrival"artist="ABBA"track="7"year="1978"genre="Pop"coverArt="25"size="4910028"contentType="audio/flac"suffix="flac"transcodedContentType="audio/mpeg"transcodedSuffix="mp3"duration="208"bitRate="128"path="ABBA/Arrival/Money, Money, Money.mp3"/></indexes>
Field
Type
Req.
OpenS.
Details
ignoredArticles
string
Yes
The ignored articles
lastModified
long
Yes
Last time the index was modified in milliseconds after January 1, 1970 UTC
The start time of the lyrics, relative to the start time of the track, in milliseconds. If this is not part of synced lyrics, start must be omitted
OpenSubsonic
This is a new OpenSubsonic response type.
7.37 - lyrics
Lyrics.
{
"artist": "Metallica",
"title": "Blitzkrieg",
"value": "Let us have peace, let us have life\n\nLet us escape the cruel night\n\nLet us have time, let the sun shine\n\nLet us beware the deadly sign\n\n\n\nThe day is coming\n\nArmageddon's near\n\nInferno's coming\n\nCan we survive the blitzkrieg?\n\nThe blitzkrieg\n\nThe blitzkrieg\n\n\n\nSave us from fate, save us from hate\n\nSave ourselves before it's too late\n\nCome to our need, hear our plea\n\nSave ourselves before the earth bleeds\n\n\n\nThe day is dawning\n\nThe time is near\n\nAliens calling\n\nCan we survive the blitzkrieg?"}
{
"artist": "Metallica",
"title": "Blitzkrieg",
"value": "Let us have peace, let us have life\n\nLet us escape the cruel night\n\nLet us have time, let the sun shine\n\nLet us beware the deadly sign\n\n\n\nThe day is coming\n\nArmageddon's near\n\nInferno's coming\n\nCan we survive the blitzkrieg?\n\nThe blitzkrieg\n\nThe blitzkrieg\n\n\n\nSave us from fate, save us from hate\n\nSave ourselves before it's too late\n\nCome to our need, hear our plea\n\nSave ourselves before the earth bleeds\n\n\n\nThe day is dawning\n\nThe time is near\n\nAliens calling\n\nCan we survive the blitzkrieg?"}
If true the playlist cannot be edited by the current user
validUntil
string
No
Yes
Date the playlist contents are considered valid until [ISO 8601]
OpenSubsonic
New fields are added:
readonly
validUntil
Note: All OpenSubsonic added fields are optional. But if a server supports a field it must return it with an empty / default value when not present in its database so that clients know what the server supports.
When readonly is true, clients should hide or disable UI actions that modify the playlist. This is useful for server-generated playlists like smart playlists, recommendations, or curated system lists. The value should reflect the current authenticated user’s access level. When omitted, clients should assume the playlist is editable (false).
The validUntil field indicates how long the playlist contents can be treated as fresh, inspired by HTTP caching semantics. Clients may use this to determine when to refresh the playlist data. An empty or absent value indicates no caching guarantee; clients should refresh the playlist data on each access.
Note: All OpenSubsonic added fields are optional. But if a server supports a field it must return it with an empty / default value when not present in its database so that clients know what the server supports.
When readonly is true, clients should hide or disable UI actions that modify the playlist. This is useful for server-generated playlists like smart playlists, recommendations, or curated system lists. The value should reflect the current authenticated user’s access level. When omitted, clients should assume the playlist is editable (false).
The validUntil field indicates how long the playlist contents can be treated as fresh, inspired by HTTP caching semantics. Clients may use this to determine when to refresh the playlist data. An empty or absent value indicates no caching guarantee; clients should refresh the playlist data on each access.
Errata: In the original spec, current is required to be an int.
However, as child ids are strings, this is updated to note that the id should be a string to be consistent.
Field
Type
Req.
OpenS.
Details
current
string
No*
ID of currently playing track
position
long
No
Position in milliseconds of currently playing track
* If entry exists and is non-empty, OpenSubsonic servers must ensure that currentIndex exists and is a valid index (between 0 and length of the queue - 1, inclusive).
If position is omitted, clients should treat the position as 0.
7.51 - PodcastChannel
A Podcast channel.
{
"channel": {
"id": "1",
"url": "http://downloads.bbc.co.uk/podcasts/fivelive/drkarl/rss.xml",
"title": "Dr Karl and the Naked Scientist",
"description": "Dr Chris Smith aka The Naked Scientist with the latest news from the world of science and Dr Karl answers listeners' science questions.",
"coverArt": "pod-1",
"originalImageUrl": "http://downloads.bbc.co.uk/podcasts/fivelive/drkarl/drkarl.jpg",
"status": "completed",
"episode": [
{
"id": "34",
"streamId": "523",
"channelId": "1",
"title": "Scorpions have re-evolved eyes",
"description": "This week Dr Chris fills us in on the UK's largest free science festival, plus all this week's big scientific discoveries.",
"publishDate": "2011-02-03T14:46:43",
"status": "completed",
"parent": "11",
"isDir": "false",
"year": "2011",
"genre": "Podcast",
"coverArt": "24",
"size": "78421341",
"contentType": "audio/mpeg",
"suffix": "mp3",
"duration": "3146",
"bitRate": "128",
"path": "Podcast/drkarl/20110203.mp3" }
]
}
}
{
"channel": {
"id": "1",
"url": "http://downloads.bbc.co.uk/podcasts/fivelive/drkarl/rss.xml",
"title": "Dr Karl and the Naked Scientist",
"description": "Dr Chris Smith aka The Naked Scientist with the latest news from the world of science and Dr Karl answers listeners' science questions.",
"coverArt": "pod-1",
"originalImageUrl": "http://downloads.bbc.co.uk/podcasts/fivelive/drkarl/drkarl.jpg",
"status": "completed",
"episode": [
{
"id": "34",
"streamId": "523",
"channelId": "1",
"title": "Scorpions have re-evolved eyes",
"description": "This week Dr Chris fills us in on the UK's largest free science festival, plus all this week's big scientific discoveries.",
"publishDate": "2011-02-03T14:46:43",
"status": "completed",
"parent": "11",
"isDir": "false",
"year": "2011",
"genre": "Podcast",
"coverArt": "24",
"size": "78421341",
"contentType": "audio/mpeg",
"suffix": "mp3",
"duration": "3146",
"bitRate": "128",
"path": "Podcast/drkarl/20110203.mp3" }
]
}
}
The base gain value. (In Db) (Ogg Opus Output Gain for example)
fallbackGain
number
No
Yes
An optional fallback gain that clients should apply when the corresponding gain value is missing. (Can be computed from the tracks or exposed as an user setting.)
Note: If the data is not present the field must be omitted in the answer. (But the replayGain field on Child must always be present)
The child metadata object (id, parent, title, etc.).
similarity
number
Yes
The normalized similarity score (1.0 = same exact song, 0.0 = most different). For getSonicSimilarTracks, relative to the query song. For findSonicPath, relative to the starting song. Returns -1 when similarity is not supported by the server.
<structuredLyricsdisplayArtist="Muse"displayTitle="Hysteria"lang="xxx"offset="-100"synced="true"><linestart="0">It's bugging me</line><linestart="2000">Grating me</line><linestart="3001">And twisting me around...</line></structuredLyrics>
Does not exist.
Version 2 (enhanced β word/syllable-level with kind)
When enhanced=true is passed to getLyricsBySongId, the response includes additional fields: kind to classify lyric tracks, cueLine arrays with word/syllable-level timing, cue byteStart / byteEnd offsets into cueLine.value, and optional agents arrays for reusable agent attribution.
Each structuredLyrics entry is self-contained. Clients should treat tracks with different kind values, including main, as independent layers rather than assuming 1:1 line or cue alignment between them. Agent identity is also scoped to a single structuredLyrics entry; agents[].id values have no meaning outside that entry. When a cue uses byteStart / byteEnd, those offsets are always relative to the final cueLine.value string in the same entry.
When a source distinguishes one or more explicit vocal agents within the same structuredLyrics entry, the entry carries a shared agents array and each cueLine references one via agentId. A single attributed/default agent uses role: "main"; entries with multiple agents still define exactly one main agent and any additional voice, bg, or group agents around it:
<structuredLyricskind="main"lang="eng"synced="true"><linestart="1000">You and I</line><linestart="4000">Under this sky</line><linestart="7000">Together tonight</line><agentid="lead"role="main"name="Chris Martin"/><agentid="guest"role="voice"name="Jin"/><agentid="choir"role="group"name="All"/><cueLineindex="0"agentId="lead"start="1000"end="4000"value="You and I"><cuestart="1000"end="1800"byteStart="0"byteEnd="3">You </cue><cuestart="1800"end="2400"byteStart="4"byteEnd="7">and </cue><cuestart="2400"end="3200"byteStart="8"byteEnd="8">I</cue></cueLine><cueLineindex="1"agentId="guest"start="4000"end="7000"value="Under this sky"><cuestart="4000"end="4800"byteStart="0"byteEnd="1">Un</cue><cuestart="4800"end="5400"byteStart="2"byteEnd="5">der </cue><cuestart="5400"end="5900"byteStart="6"byteEnd="10">this </cue><cuestart="5900"end="7000"byteStart="11"byteEnd="13">sky</cue></cueLine><cueLineindex="2"agentId="choir"start="7000"end="10000"value="Together tonight"><cuestart="7000"end="8000"byteStart="0"byteEnd="1">To</cue><cuestart="8000"end="8800"byteStart="2"byteEnd="3">ge</cue><cuestart="8800"end="9200"byteStart="4"byteEnd="8">ther </cue><cuestart="9200"end="10000"byteStart="9"byteEnd="15">tonight</cue></cueLine></structuredLyrics>
Does not exist.
The same song with kind: "pronunciation" β note how cue counts differ from the main track (3 romanized words vs. 7 Korean syllables):
<structuredLyricskind="pronunciation"lang="ko-Latn"synced="true"><linestart="2747">nuneul tteun sungan</line><linestart="6214">modeun ge dallajyeosseo</line><cueLineindex="0"start="2747"end="6214"value="nuneul tteun sungan"><cuestart="2747"end="3179"byteStart="0"byteEnd="5">nuneul</cue><cuestart="3582"end="4100"byteStart="7"byteEnd="11">tteun</cue><cuestart="4500"end="6214"byteStart="13"byteEnd="18">sungan</cue></cueLine><cueLineindex="1"start="6214"end="9000"value="modeun ge dallajyeosseo"><cuestart="6214"end="7200"byteStart="0"byteEnd="5">modeun</cue><cuestart="7600"end="8000"byteStart="7"byteEnd="8">ge</cue><cuestart="8400"end="9000"byteStart="10"byteEnd="22">dallajyeosseo</cue></cueLine></structuredLyrics>
Does not exist.
Fields
Field
Type
Req.
OpenS.
Details
lang
string
Yes
Yes
The lyrics language (ideally ISO 639). If the language is unknown (e.g. lrc file), the server must return und (ISO standard) or xxx (common value for taggers)
The actual lyrics. Ordered by start time (synced) or appearance order (unsynced)
displayArtist
string
No
Yes
The artist name to display. This could be the localized name, or any other value
displayTitle
string
No
Yes
The title to display. This could be the song title (localized), or any other value
offset
number
No
Yes
The offset to apply to all lyrics, in milliseconds. Positive means lyrics appear sooner, negative means later. If not included, the offset must be assumed to be 0
kind
string
No
Yes
The primary lyric-layer classification for this structuredLyrics entry. One of: main (primary vocals for this entry, default if omitted), translation (a translation of another lyric layer into another language), pronunciation (a phonetic/romanized rendering, e.g. romaji for Japanese, pinyin for Chinese). Tracks are independent across kind values; clients should not assume 1:1 line or cue alignment between entries. Only returned when enhanced=true. Added in songLyrics version 2
Reusable per-track attribution metadata for cueLine entries. When present, must contain at least one entry, and each agents[].idmust be unique within this structuredLyrics entry. agents are optional for simple unattributed single-layer lyrics. When a structuredLyrics entry represents multiple vocal agents/layers, it must include agents; a single-agent attributed/default entry may also include agents, and if it does, exactly one agent must use role: "main". agents should not be emitted without cueLine data
Word/syllable-level timing data. Each cueLine corresponds to a line by its index field. Every cueLine must include value, and every nested cue must include byteStart / byteEnd offsets into that exact string. If agents is present, every cueLine in the entry must include agentId; if agents is absent, cueLines must not include agentId. Only returned when enhanced=true and synced is true. Added in songLyrics version 2
If agents is present, each cueLine.agentIdmust resolve to exactly one agents[].id in the same structuredLyrics entry.
type containing the server type/name (Ex: Navidrome or gonic). Mandatory to help clients adapt to actual Subsonic API support.
serverVersion containing the server version (Ex: 1.2.3) this is different from the version field that expose the Subsonic API version. Mandatory for clients to be able to detect servers updates and check again supported OpenSubsonic extensions.
openSubsonic must return true if the server support OpenSubsonic API v1
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.
Note that a Subsonic-compatible server is backward compatible with a REST client if and only if the major version is the same, and the minor version of the client is less than or equal to the server’s. For example, if the server has REST API version 2.2, it supports client versions 2.0, 2.1 and 2.2, but not versions 1.x, 2.3+ or 3.x. The third part of the version number is not used to determine compatibility.
OpenSubsonic
OpenSubsonic servers should support at least 1.14.0. It is not required to support version 1.16.1, but this is still highly recommended.
10 - OpenAPI schema
OpenAPI schema documentation and development guidelines.
Can be found here Only relevant to OpenSubsonic servers.
WIP
This work is still ongoing, there are some inconsistencies between the docs and the schema. Users should still check the actual docs and servers results until work on it is completely finished.
List of known differences compared to official documentation
Some undocumented typo fixes
Added minimum: 0 to integer types where it’s implied (count, offset, unix timestamp, position)
Requires the use of format=json parameter. xml response formats are not supported as of the time of writing this document.
All extensions are added to the schema and tagged as “Extension”,
and have an additional 404 return type as well that described as “Not
Implemented”
Excluded examples. They need to be carefully added incrementally to see how they are merged in Swagger/Redoc docs.
Parameters only existing via Extensions are always added and marked in their description field
HTTP form POST extensions have an additional response “405 - Method
Not Allowed” as an additional way to indicate when they are not
supported.
- HTTP form POST extension support might be stricter than what’s
allowed (global params - auth and format params - only allowed as query
params, endpoint specific params are the only ones allowed in request
body)
Building
By default the schema is in parts to for easier maintainability. You can build it with the command below.
npm run build:openapi
This will output the schema to content/en/docs/Openapi/openapi.json and also validate the output for correctness. The end result can be used as-is.
Preservation of previous versions
When a version change happens in the spec, the previous versions’ built openapi.json should be placed into content/en/docs/Openapi/openapi-x.x.x.json for archiving purposes.
Usage
Ideally this should be used as a reference and for automatic client/server code generation.
Client Code Generation
Python
openapi-python-client β - Auth params need to be passed in at client initialization
When the documentation is changed the OpenAPI schema MUST BE updated in openapi folder and vice-versa.
Folder Structure
endpoints - matches paths section in openapi.json, files inside should be added to said section.
endpoints/{endpoint}.json/{endpoint}/ - supporting schemas for en endpoint, should be added to components/schemas section in openapi.json
responses - matches components/responses section in openapi.json and files inside should be added to said section.
schemas - matches components/schemas section in openapi.json and files inside should be added to said section.
Schema validation during development
The fragmented files are not validated in dev environments, so one of 2 ways are recommended when editing.
Edit/add files. Keep building the output to static/openapi.json and keep it open to catch errors.
Add new endpoints/schemas to openapi/openapi.json directly. Move them to different files when you are done with them.
In the future $schema tag could be added to each of them to make in-editor validation work but that requires the relevant parts of OpenAPI schema to be served from somewhere in a broken up form - you can add "$schema": "https://schemas.sourcemeta.com/openapi/v3.0/schema.json" but you can’t add "$schema": "https://schemas.sourcemeta.com/openapi/v3.0/schema.json#definitions/Schema"