About the OpenSubsonic API on OpenSubsonic

OpenSubsonic API

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

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.

For instance, browsing through the collection using ID3 tags should use the getArtists, getArtist and getAlbum methods. To browse using file structure you would use getIndexes and getMusicDirectory.

OpenAPI OpenSubsonic Swagger UI

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

OpenAPI OpenSubsonic Redoc UI

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

API Reference

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

Parameters

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.

OpenSubsonic changes

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

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.

OpenSubsonic API versions

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

Versions

This table shows the supported extensions by OpenSubsonic versions:

OpenSubsonic version	Supported extension
1	Template extension, Sonic similarity

Note: Since extensions are optional, more extensions can be added over time to the same OpenSubsonic API version.

See: OpenSubsonic changes for the global list of OpenSubsonic changes.

Subsonic API versions

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

Versions

This table shows the REST API version implemented in different Subsonic versions:

Subsonic version	REST API version
6.1.4	1.16.1
6.1.2	1.16.0
6.1	1.15.0
6.0	1.14.0
5.3	1.13.0
5.2	1.12.0
5.1	1.11.0
4.9	1.10.2
4.8	1.9.0
4.7	1.8.0
4.6	1.7.0
4.5	1.6.0
4.4	1.5.0
4.2	1.4.0
4.1	1.3.0
4.0	1.2.0
3.9	1.1.1
3.8	1.1.0

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.

addChatMessage

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

http://your-server/rest/addChatMessage Since 1.2.0

Adds a message to the chat log.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`message`	Yes			The chat message.

Example

http://your-server/rest/addChatMessage.view?message=hello&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

An empty subsonic-response element on success.

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1"
 }
}

agent

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

{
 "id": "lead",
 "role": "main",
 "name": "Chris Martin"
}

<agent id="lead" role="main" name="Chris Martin" />

Does not exist.

Example agent list within one `structuredLyrics` entry

[
 { "id": "lead", "role": "main", "name": "Chris Martin" },
 { "id": "guest", "role": "voice", "name": "Jin" },
 { "id": "choir", "role": "group", "name": "All" },
 { "id": "backing", "role": "bg" }
]

<agent id="lead" role="main" name="Chris Martin" />
<agent id="guest" role="voice" name="Jin" />
<agent id="choir" role="group" name="All" />
<agent id="backing" role="bg" />

Does not exist.

Field	Type	Req.	OpenS.	Details
`id`	`string`	Yes	Yes	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.

AlbumID3

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

{
 "id": "ad0f112b6dcf83de5e9cae85d07f0d35",
 "name": "8-bit lagerfeuer",
 "version": "Deluxe Edition",
 "artist": "pornophonique",
 "year": 2007,
 "coverArt": "al-ad0f112b6dcf83de5e9cae85d07f0d35_640a93a8",
 "starred": "2023-03-22T01:51:06Z",
 "duration": 1954,
 "playCount": 97,
 "genre": "Hip-Hop",
 "created": "2023-03-10T02:19:35.784818075Z",
 "artistId": "91c3901ac465b9efc439e4be4270c2b6",
 "songCount": 8,
 "played": "2023-03-28T00:45:13Z",
 "userRating": 4,
 "recordLabels": [
 {
 "name": "Sony"
 }
 ],
 "musicBrainzId": "189002e7-3285-4e2e-92a3-7f6c30d407a2",
 "genres": [
 {
 "name": "Hip-Hop"
 },
 {
 "name": "East coast"
 }
 ],
 "artists": [
 {
 "id": "ar-1",
 "name": "Artist 1"
 },
 {
 "id": "ar-2",
 "name": "Artist 2"
 }
 ],
 "displayArtist": "Artist 1 feat. Artist 2",
 "releaseTypes": [
 "Album",
 "Remixes"
 ],
 "moods": [
 "slow",
 "cool"
 ],
 "sortName": "lagerfeuer (8-bit)",
 "originalReleaseDate": {
 "year": 2001,
 "month": 3,
 "day": 10
 },
 "releaseDate": {
 "year": 2001,
 "month": 3,
 "day": 10
 },
 "isCompilation": false,
 "explicitStatus": "explicit",
 "discTitles": [
 {
 "disc": 0,
 "title": "Disc 0 title"
 "coverArt": "42"
 },
 {
 "disc": 2,
 "title": "Disc 1 title"
 "coverArt": "6547"
 }
 ]
}

{
 "id": "ad0f112b6dcf83de5e9cae85d07f0d35",
 "name": "8-bit lagerfeuer",
 "artist": "pornophonique",
 "year": 2007,
 "coverArt": "al-ad0f112b6dcf83de5e9cae85d07f0d35_640a93a8",
 "starred": "2023-03-22T01:51:06Z",
 "duration": 1954,
 "playCount": 97,
 "genre": "Hip-Hop",
 "created": "2023-03-10T02:19:35.784818075Z",
 "artistId": "91c3901ac465b9efc439e4be4270c2b6",
 "songCount": 8
}

Field	Type	Req.	OpenS.	Details
`id`	`string`	Yes		The id of the album
`name`	`string`	Yes		The album name.
`version`	`string`	No	Yes	The album version name (Remastered, Anniversary Box Set, …).
`artist`	`string`	No		Artist name.
`artistId`	`string`	No		The id of the artist
`coverArt`	`string`	No		A covertArt id.
`songCount`	`int`	Yes		Number of songs
`duration`	`int`	Yes		Total duration of the album in seconds
`playCount`	`long`	No		Number of play of the album
`created`	`string`	Yes		Date the album was added. [ISO 8601]
`starred`	`string`	No		Date the album was starred. [ISO 8601]
`year`	`int`	No		The album year
`genre`	`string`	No		The album genre
`played`	`string`	No	Yes	Date the album was last played. [ISO 8601]
`userRating`	`int`	No	Yes	The user rating of the album. [1-5]
`recordLabels`	Array of `RecordLabel`	No	Yes	The labels producing the album.
`musicBrainzId`	`string`	No	Yes	The album MusicBrainzID.
`genres`	Array of `ItemGenre`	No	Yes	The list of all genres of the album.
`artists`	Array of `ArtistID3`	No	Yes	The list of all album artists of the album. (Note: Only the required `ArtistID3` fields should be returned by default)
`displayArtist`	`string`	No	Yes	The single value display artist.
`releaseTypes`	Array of `string`	No	Yes	The types of this album release. (Album, Compilation, EP, Remix, …).
`moods`	Array of `string`	No	Yes	The list of all moods of the album.
`sortName`	`string`	No	Yes	The album sort name.
`originalReleaseDate`	`ItemDate`	No	Yes	Date the album was originally released.
`releaseDate`	`ItemDate`	No	Yes	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 “”.
`discTitles`	Array of `DiscTitle`	No	Yes	The list of all disc titles of the album.

OpenSubsonic

New fields are added:

AlbumID3WithSongs

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

{
 "id": "ad0f112b6dcf83de5e9cae85d07f0d35",
 "name": "8-bit lagerfeuer",
 "version": "Deluxe Edition",
 "artist": "pornophonique",
 "year": 2007,
 "coverArt": "al-ad0f112b6dcf83de5e9cae85d07f0d35_640a93a8",
 "starred": "2023-03-22T01:51:06Z",
 "duration": 1954,
 "playCount": 97,
 "genre": "Hip-Hop",
 "created": "2023-03-10T02:19:35.784818075Z",
 "artistId": "91c3901ac465b9efc439e4be4270c2b6",
 "songCount": 8,
 "played": "2023-03-28T00:45:13Z",
 "userRating": 4,
 "recordLabels": [
 {
 "name": "Sony"
 }
 ],
 "musicBrainzId": "189002e7-3285-4e2e-92a3-7f6c30d407a2",
 "genres": [
 {
 "name": "Hip-Hop"
 },
 {
 "name": "East coast"
 }
 ],
 "artists": [
 {
 "id": "ar-1",
 "name": "Artist 1"
 },
 {
 "id": "ar-2",
 "name": "Artist 2"
 }
 ],
 "displayArtist": "Artist 1 feat. Artist 2",
 "releaseTypes": [
 "Album",
 "Remixes"
 ],
 "moods": [
 "slow",
 "cool"
 ],
 "sortName": "lagerfeuer (8-bit)",
 "originalReleaseDate": {
 "year": 2001,
 "month": 3,
 "day": 10
 },
 "releaseDate": {
 "year": 2001,
 "month": 3,
 "day": 10
 },
 "isCompilation": false,
 "explicitStatus": "explicit",
 "discTitles": [
 {
 "disc": 0,
 "title": "Disc 0 title"
 "coverArt": "100000111",
 },
 {
 "disc": 2,
 "title": "Disc 1 title"
 "coverArt": "100000117",
 }
 ],
 "song": [
 {
 "id": "300000116",
 "parent": "200000021",
 "title": "Can I Help U?",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000116",
 "duration": 103,
 "bitRate": 216,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 1,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 2811819,
 "discNumber": 1,
 "suffix": "mp3",
 "explicitStatus": "explicit",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
 },
 {
 "id": "300000121",
 "parent": "200000021",
 "title": "Planetary Picknick",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000121",
 "duration": 358,
 "bitRate": 238,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 2,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 10715592,
 "discNumber": 1,
 "suffix": "mp3",
 "explicitStatus": "clean",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/2 - Planetary Picknick.mp3"
 }
 ]
}

{
 "id": "200000021",
 "parent": "100000036",
 "album": "Forget and Remember",
 "title": "Forget and Remember",
 "name": "Forget and Remember",
 "isDir": true,
 "coverArt": "al-200000021",
 "songCount": 20,
 "created": "2021-07-22T02:09:31+00:00",
 "duration": 4248,
 "playCount": 0,
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "year": 2005,
 "genre": "Hip-Hop",
 "song": [
 {
 "id": "300000116",
 "parent": "200000021",
 "title": "Can I Help U?",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000116",
 "duration": 103,
 "bitRate": 216,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 1,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 2811819,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
 },
 {
 "id": "300000121",
 "parent": "200000021",
 "title": "Planetary Picknick",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000121",
 "duration": 358,
 "bitRate": 238,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 2,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 10715592,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/2 - Planetary Picknick.mp3"
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`id`	`string`	Yes		The id of the album
`name`	`string`	Yes		The album name.
`version`	`string`	No	Yes	The album version name (Remastered, Anniversary Box Set, …).
`artist`	`string`	No		Artist name.
`artistId`	`string`	No		The id of the artist
`coverArt`	`string`	No		A covertArt id.
`songCount`	`int`	Yes		Number of songs
`duration`	`int`	Yes		Total duration of the album in seconds
`playCount`	`long`	No		Number of play of the album
`created`	`string`	Yes		Date the album was added. [ISO 8601]
`starred`	`string`	No		Date the album was starred. [ISO 8601]
`year`	`int`	No		The album year
`genre`	`string`	No		The album genre
`played`	`string`	No	Yes	Date the album was last played. [ISO 8601]
`userRating`	`int`	No	Yes	The user rating of the album. [1-5]
`recordLabels`	Array of `RecordLabel`	No	Yes	The labels producing the album.
`musicBrainzId`	`string`	No	Yes	The album MusicBrainzID.
`genres`	Array of `ItemGenre`	No	Yes	The list of all genres of the album.
`artists`	Array of `ArtistID3`	No	Yes	The list of all album artists of the album.
`displayArtist`	`string`	No	Yes	The single value display artist.
`releaseTypes`	Array of `string`	No	Yes	The types of this album release. (Album, Compilation, EP, Remix, …).
`moods`	Array of `string`	No	Yes	The list of all moods of the album.
`sortName`	`string`	No	Yes	The album sort name.
`originalReleaseDate`	`ItemDate`	No	Yes	Date the album was originally released.
`releaseDate`	`ItemDate`	No	Yes	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 “”.
`discTitles`	Array of `DiscTitle`	No	Yes	The list of all disc titles of the album.
`song`	Array of `Child`	No		The list of songs

OpenSubsonic

New fields are added:

albumInfo

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

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

Field	Type	Req.	Details
`notes`	`string`	No	Album notes
`musicBrainzId`	`string`	No	Album musicBrainzId
`lastFmUrl`	`string`	No	Album lastFmUrl
`smallImageUrl`	`string`	No	Album smallImageUrl
`mediumImageUrl`	`string`	No	Album mediumImageUrl
`largeImageUrl`	`string`	No	Album largeImageUrl

albumList

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

{
 "album": [
 {
 "id": "200000021",
 "parent": "100000036",
 "album": "Forget and Remember",
 "title": "Forget and Remember",
 "name": "Forget and Remember",
 "isDir": true,
 "coverArt": "al-200000021",
 "created": "2021-07-22T02:09:31+00:00",
 "duration": 4248,
 "playCount": 0,
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "year": 2005,
 "genre": "Hip-Hop"
 },
 {
 "id": "200000012",
 "parent": "100000019",
 "album": "Buried in Nausea",
 "title": "Buried in Nausea",
 "name": "Buried in Nausea",
 "isDir": true,
 "coverArt": "al-200000012",
 "created": "2021-02-24T01:44:21+00:00",
 "duration": 1879,
 "playCount": 0,
 "artistId": "100000019",
 "artist": "Various Artists",
 "year": 2012,
 "genre": "Punk"
 }
 ]
}

{
 "album": [
 {
 "id": "200000021",
 "parent": "100000036",
 "album": "Forget and Remember",
 "title": "Forget and Remember",
 "name": "Forget and Remember",
 "isDir": true,
 "coverArt": "al-200000021",
 "created": "2021-07-22T02:09:31+00:00",
 "duration": 4248,
 "playCount": 0,
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "year": 2005,
 "genre": "Hip-Hop"
 },
 {
 "id": "200000012",
 "parent": "100000019",
 "album": "Buried in Nausea",
 "title": "Buried in Nausea",
 "name": "Buried in Nausea",
 "isDir": true,
 "coverArt": "al-200000012",
 "created": "2021-02-24T01:44:21+00:00",
 "duration": 1879,
 "playCount": 0,
 "artistId": "100000019",
 "artist": "Various Artists",
 "year": 2012,
 "genre": "Punk"
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`album`	Array of `Child`	No		Artist albums

albumList2

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

{
 "album": [
 {
 "id": "200000021",
 "album": "Forget and Remember",
 "title": "Forget and Remember",
 "name": "Forget and Remember",
 "coverArt": "al-200000021",
 "songCount": 20,
 "created": "2021-07-22T02:09:31+00:00",
 "duration": 4248,
 "playCount": 0,
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "year": 2005,
 "genre": "Hip-Hop"
 },
 {
 "id": "200000012",
 "album": "Buried in Nausea",
 "title": "Buried in Nausea",
 "name": "Buried in Nausea",
 "coverArt": "al-200000012",
 "songCount": 9,
 "created": "2021-02-24T01:44:21+00:00",
 "duration": 1879,
 "playCount": 0,
 "artistId": "100000019",
 "artist": "Various Artists",
 "year": 2012,
 "genre": "Punk"
 }
 ]
}

{
 "album": [
 {
 "id": "200000021",
 "album": "Forget and Remember",
 "title": "Forget and Remember",
 "name": "Forget and Remember",
 "coverArt": "al-200000021",
 "songCount": 20,
 "created": "2021-07-22T02:09:31+00:00",
 "duration": 4248,
 "playCount": 0,
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "year": 2005,
 "genre": "Hip-Hop"
 },
 {
 "id": "200000012",
 "album": "Buried in Nausea",
 "title": "Buried in Nausea",
 "name": "Buried in Nausea",
 "coverArt": "al-200000012",
 "songCount": 9,
 "created": "2021-02-24T01:44:21+00:00",
 "duration": 1879,
 "playCount": 0,
 "artistId": "100000019",
 "artist": "Various Artists",
 "year": 2012,
 "genre": "Punk"
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`album`	Array of `AlbumID3`	No		Artist albums

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).

artist

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

{
 "id": "100000002",
 "name": "Synthetic",
 "coverArt": "ar-100000002",
 "starred": "2021-02-22T05:54:18Z"
}

{
 "id": "100000002",
 "name": "Synthetic",
 "coverArt": "ar-100000002",
 "starred": "2021-02-22T05:54:18Z"
}

Field	Type	Req.	Details
`id`	`string`	Yes	Artist id
`name`	`string`	Yes	Artist name
`artistImageUrl`	`string`	No	Artist image url
`starred`	`string`	No	Artist starred date [ISO 8601]
`userRating`	`int`	No	Artist rating [1-5]
`averageRating`	`number`	No	Artist average rating [1.0-5.0]

ArtistID3

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

{
 "id": "37ec820ca7193e17040c98f7da7c4b51",
 "name": "2 Mello",
 "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
 "albumCount": 1,
 "userRating": 5,
 "artistImageUrl": "https://demo.org/image.jpg",
 "starred": "2017-04-11T10:42:50.842Z",
 "musicBrainzId": "189002e7-3285-4e2e-92a3-7f6c30d407a2",
 "sortName": "Mello (2)",
 "roles": [
 "artist",
 "albumartist",
 "composer"
 ]
}

{
 "id": "37ec820ca7193e17040c98f7da7c4b51",
 "name": "2 Mello",
 "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
 "albumCount": 1,
 "userRating": 5,
 "artistImageUrl": "https://demo.org/image.jpg",
 "starred": "2017-04-11T10:42:50.842Z"
}

Field	Type	Req.	OpenS.	Details
`id`	`string`	Yes		The id of the artist
`name`	`string`	Yes		The artist name.
`coverArt`	`string`	No		A covertArt id.
`artistImageUrl`	`string`	No		An url to an external image source.
`albumCount`	`int`	No		Artist album count.
`starred`	`string`	No		Date the artist was starred. [ISO 8601]
`musicBrainzId`	`string`	No	Yes	The artist MusicBrainzID.
`sortName`	`string`	No	Yes	The artist sort name.
`roles`	Array of `string`	No	Yes	The list of all roles this artist has in the library.

OpenSubsonic

New fields are added:

artistInfo

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

{
 "biography": "Empty biography",
 "musicBrainzId": "1",
 "smallImageUrl": "http://localhost:8989/play/art/f20070e8e11611cc53542a38801d60fa/artist/2/thumb34.jpg",
 "mediumImageUrl": "http://localhost:8989/play/art/2b9b6c057cd4bf21089ce7572e7792b6/artist/2/thumb64.jpg",
 "largeImageUrl": "http://localhost:8989/play/art/e18287c23a75e263b64c31b3d64c1944/artist/2/thumb174.jpg"
}

{
 "biography": "Empty biography",
 "musicBrainzId": "1",
 "smallImageUrl": "http://localhost:8989/play/art/f20070e8e11611cc53542a38801d60fa/artist/2/thumb34.jpg",
 "mediumImageUrl": "http://localhost:8989/play/art/2b9b6c057cd4bf21089ce7572e7792b6/artist/2/thumb64.jpg",
 "largeImageUrl": "http://localhost:8989/play/art/e18287c23a75e263b64c31b3d64c1944/artist/2/thumb174.jpg"
}

Field	Type	Req.	Details
`biography`	`string`	No	Artist biography
`musicBrainzId`	`string`	No	Artist musicBrainzId
`lastFmUrl`	`string`	No	Artist lastFmUrl
`smallImageUrl`	`string`	No	Artist smallImageUrl
`mediumImageUrl`	`string`	No	Artist mediumImageUrl
`largeImageUrl`	`string`	No	Artist largeImageUrl
`similarArtist`	Array of `artist`	No	Similar Artists

artistInfo2

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

{
 "biography": "Empty biography",
 "musicBrainzId": "1",
 "smallImageUrl": "http://localhost:8989/play/art/f20070e8e11611cc53542a38801d60fa/artist/2/thumb34.jpg",
 "mediumImageUrl": "http://localhost:8989/play/art/2b9b6c057cd4bf21089ce7572e7792b6/artist/2/thumb64.jpg",
 "largeImageUrl": "http://localhost:8989/play/art/e18287c23a75e263b64c31b3d64c1944/artist/2/thumb174.jpg"
}

{
 "biography": "Empty biography",
 "musicBrainzId": "1",
 "smallImageUrl": "http://localhost:8989/play/art/f20070e8e11611cc53542a38801d60fa/artist/2/thumb34.jpg",
 "mediumImageUrl": "http://localhost:8989/play/art/2b9b6c057cd4bf21089ce7572e7792b6/artist/2/thumb64.jpg",
 "largeImageUrl": "http://localhost:8989/play/art/e18287c23a75e263b64c31b3d64c1944/artist/2/thumb174.jpg"
}

Field	Type	Req.	Details
`biography`	`string`	No	Artist biography
`musicBrainzId`	`string`	No	Artist musicBrainzId
`lastFmUrl`	`string`	No	Artist lastFmUrl
`smallImageUrl`	`string`	No	Artist smallImageUrl
`mediumImageUrl`	`string`	No	Artist mediumImageUrl
`largeImageUrl`	`string`	No	Artist largeImageUrl
`similarArtist`	Array of `ArtistID3`	No	Similar Artists

ArtistsID3

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

{
 "ignoredArticles": "The An A Die Das Ein Eine Les Le La",
 "index": [
 {
 "name": "C",
 "artist": [
 {
 "id": "100000016",
 "name": "CARNÚN",
 "coverArt": "ar-100000016",
 "albumCount": 1
 },
 {
 "id": "100000027",
 "name": "Chi.Otic",
 "coverArt": "ar-100000027",
 "albumCount": 0
 }
 ]
 },
 {
 "name": "I",
 "artist": [
 {
 "id": "100000013",
 "name": "IOK-1",
 "coverArt": "ar-100000013",
 "albumCount": 1
 }
 ]
 }
 ]
}

{
 "ignoredArticles": "The An A Die Das Ein Eine Les Le La",
 "index": [
 {
 "name": "C",
 "artist": [
 {
 "id": "100000016",
 "name": "CARNÚN",
 "coverArt": "ar-100000016",
 "albumCount": 1
 },
 {
 "id": "100000027",
 "name": "Chi.Otic",
 "coverArt": "ar-100000027",
 "albumCount": 0
 }
 ]
 },
 {
 "name": "I",
 "artist": [
 {
 "id": "100000013",
 "name": "IOK-1",
 "coverArt": "ar-100000013",
 "albumCount": 1
 }
 ]
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`ignoredArticles`	`string`	Yes		List of ignored articles space separated
`index`	Array of `IndexID3`	No		Index list

ArtistWithAlbumsID3

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

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

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

Field	Type	Req.	OpenS.	Details
`id`	`string`	Yes		The id of the artist
`name`	`string`	Yes		The artist name.
`coverArt`	`string`	No		A covertArt id.
`artistImageUrl`	`string`	No		An url to an external image source.
`albumCount`	`int`	Yes		Artist album count.
`starred`	`string`	No		Date the artist was starred. [ISO 8601]
`album`	Array of `AlbumID3`	No		Artist albums
`musicBrainzId`	`string`	No	Yes	The artist MusicBrainzID.
`sortName`	`string`	No	Yes	The artist sort name.
`roles`	Array of `string`	No	Yes	The list of all roles this artist has in the library.

OpenSubsonic

New fields are added:

bookmark

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

{
 "entry": {
 "id": "113bf5989ad15ce2cf1834ba9622983f",
 "parent": "b87a936c682c49d4494c7ccb08c22d23",
 "isDir": false,
 "title": "Stay Out Here",
 "album": "Shaking The Habitual",
 "artist": "The Knife",
 "track": 11,
 "year": 2013,
 "genre": "Electronic",
 "coverArt": "al-b87a936c682c49d4494c7ccb08c22d23_0",
 "size": 21096309,
 "contentType": "audio/mp4",
 "suffix": "m4a",
 "duration": 642,
 "bitRate": 257,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "path": "The Knife/Shaking The Habitual/11 - Stay Out Here.m4a",
 "created": "2023-03-13T16:30:35Z",
 "albumId": "b87a936c682c49d4494c7ccb08c22d23",
 "artistId": "b29e9a9d780cb0e133f3add5662771b9",
 "type": "music",
 "isVideo": false,
 "bookmarkPosition": 129000
 },
 "position": 129000,
 "username": "demo",
 "comment": "",
 "created": "2023-03-13T16:30:35Z",
 "changed": "2023-03-13T16:30:35Z"
}

{
 "entry": {
 "id": "113bf5989ad15ce2cf1834ba9622983f",
 "parent": "b87a936c682c49d4494c7ccb08c22d23",
 "isDir": false,
 "title": "Stay Out Here",
 "album": "Shaking The Habitual",
 "artist": "The Knife",
 "track": 11,
 "year": 2013,
 "genre": "Electronic",
 "coverArt": "al-b87a936c682c49d4494c7ccb08c22d23_0",
 "size": 21096309,
 "contentType": "audio/mp4",
 "suffix": "m4a",
 "duration": 642,
 "bitRate": 257,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "path": "The Knife/Shaking The Habitual/11 - Stay Out Here.m4a",
 "created": "2023-03-13T16:30:35Z",
 "albumId": "b87a936c682c49d4494c7ccb08c22d23",
 "artistId": "b29e9a9d780cb0e133f3add5662771b9",
 "type": "music",
 "isVideo": false,
 "bookmarkPosition": 129000
 },
 "position": 129000,
 "username": "demo",
 "comment": "",
 "created": "2023-03-13T16:30:35Z",
 "changed": "2023-03-13T16:30:35Z"
}

Field	Type	Req.	Details
`position`	`long`	Yes	Bookmark position in milliseconds
`username`	`string`	Yes	Username
`comment`	`string`	No	Bookmark comment
`created`	`string`	Yes	Bookmark creation date [ISO 8601]
`changed`	`string`	Yes	Bookmark last updated date [ISO 8601]
`entry`	`Child`	Yes	The bookmark file

bookmarks

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

{
 "bookmark": [
 {
 "entry": {
 "id": "113bf5989ad15ce2cf1834ba9622983f",
 "parent": "b87a936c682c49d4494c7ccb08c22d23",
 "isDir": false,
 "title": "Stay Out Here",
 "album": "Shaking The Habitual",
 "artist": "The Knife",
 "track": 11,
 "year": 2013,
 "genre": "Electronic",
 "coverArt": "al-b87a936c682c49d4494c7ccb08c22d23_0",
 "size": 21096309,
 "contentType": "audio/mp4",
 "suffix": "m4a",
 "duration": 642,
 "bitRate": 257,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "path": "The Knife/Shaking The Habitual/11 - Stay Out Here.m4a",
 "created": "2023-03-13T16:30:35Z",
 "albumId": "b87a936c682c49d4494c7ccb08c22d23",
 "artistId": "b29e9a9d780cb0e133f3add5662771b9",
 "type": "music",
 "isVideo": false,
 "bookmarkPosition": 129000
 },
 "position": 129000,
 "username": "demo",
 "comment": "",
 "created": "2023-03-13T16:30:35Z",
 "changed": "2023-03-13T16:30:35Z"
 },
 {
 "entry": {
 "id": "2b42782333450d02b177823e729664af",
 "parent": "dc8d8889a6fe08d8da7698c7ee1de61c",
 "isDir": false,
 "title": "Ill with the Skills",
 "album": "First Words",
 "artist": "The Polish Ambassador",
 "track": 17,
 "year": 2014,
 "coverArt": "mf-2b42782333450d02b177823e729664af_641edeb3",
 "size": 6219581,
 "contentType": "audio/mpeg",
 "suffix": "mp3",
 "duration": 255,
 "bitRate": 194,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "path": "The Polish Ambassador/First Words/17 - Ill with the Skills.mp3",
 "playCount": 1,
 "played": "2023-03-15T15:23:37Z",
 "created": "2023-03-25T11:44:51Z",
 "albumId": "dc8d8889a6fe08d8da7698c7ee1de61c",
 "artistId": "64e1f796b283545d329cdf6a31a31dbe",
 "type": "music",
 "isVideo": false,
 "bookmarkPosition": 7000
 },
 "position": 7000,
 "username": "demo",
 "comment": "playSub bookmark",
 "created": "2023-03-25T11:44:51Z",
 "changed": "2023-03-25T11:44:51Z"
 }
 ]
}

{
 "bookmark": [
 {
 "entry": {
 "id": "113bf5989ad15ce2cf1834ba9622983f",
 "parent": "b87a936c682c49d4494c7ccb08c22d23",
 "isDir": false,
 "title": "Stay Out Here",
 "album": "Shaking The Habitual",
 "artist": "The Knife",
 "track": 11,
 "year": 2013,
 "genre": "Electronic",
 "coverArt": "al-b87a936c682c49d4494c7ccb08c22d23_0",
 "size": 21096309,
 "contentType": "audio/mp4",
 "suffix": "m4a",
 "duration": 642,
 "bitRate": 257,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "path": "The Knife/Shaking The Habitual/11 - Stay Out Here.m4a",
 "created": "2023-03-13T16:30:35Z",
 "albumId": "b87a936c682c49d4494c7ccb08c22d23",
 "artistId": "b29e9a9d780cb0e133f3add5662771b9",
 "type": "music",
 "isVideo": false,
 "bookmarkPosition": 129000
 },
 "position": 129000,
 "username": "demo",
 "comment": "",
 "created": "2023-03-13T16:30:35Z",
 "changed": "2023-03-13T16:30:35Z"
 },
 {
 "entry": {
 "id": "2b42782333450d02b177823e729664af",
 "parent": "dc8d8889a6fe08d8da7698c7ee1de61c",
 "isDir": false,
 "title": "Ill with the Skills",
 "album": "First Words",
 "artist": "The Polish Ambassador",
 "track": 17,
 "year": 2014,
 "coverArt": "mf-2b42782333450d02b177823e729664af_641edeb3",
 "size": 6219581,
 "contentType": "audio/mpeg",
 "suffix": "mp3",
 "duration": 255,
 "bitRate": 194,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "path": "The Polish Ambassador/First Words/17 - Ill with the Skills.mp3",
 "playCount": 1,
 "played": "2023-03-15T15:23:37Z",
 "created": "2023-03-25T11:44:51Z",
 "albumId": "dc8d8889a6fe08d8da7698c7ee1de61c",
 "artistId": "64e1f796b283545d329cdf6a31a31dbe",
 "type": "music",
 "isVideo": false,
 "bookmarkPosition": 7000
 },
 "position": 7000,
 "username": "demo",
 "comment": "playSub bookmark",
 "created": "2023-03-25T11:44:51Z",
 "changed": "2023-03-25T11:44:51Z"
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`bookmark`	Array of `bookmark`	No		List of bookmark

changePassword

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

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).

Example

http://your-server/rest/changePassword.view?username=demo&password=password&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

An empty subsonic-response element on success.

chatMessage

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

{
 "username": "user",
 "time": 1678935699000,
 "message": "Api Script Testing"
}

{
 "username": "user",
 "time": 1678935699000,
 "message": "Api Script Testing"
}

Field	Type	Req.	Details
`username`	`string`	Yes	Username
`time`	`long`	Yes	Time in millis since Jan 1 1970
`message`	`string`	Yes	The message

chatMessages

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

{
 "chatMessage": [
 {
 "username": "admin",
 "time": 1678935707000,
 "message": "Api Script Testing"
 },
 {
 "username": "user",
 "time": 1678935699000,
 "message": "Api Script Testing"
 }
 ]
}

{
 "chatMessage": [
 {
 "username": "admin",
 "time": 1678935707000,
 "message": "Api Script Testing"
 },
 {
 "username": "user",
 "time": 1678935699000,
 "message": "Api Script Testing"
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`chatMessage`	Array of `chatMessage`	No		List of chatMessage

Child

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

{
 "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,
 "played": "2023-03-26T22:27:46Z",
 "discNumber": 1,
 "created": "2023-03-14T17:51:22.112827504Z",
 "albumId": "e8a0685e3f3ec6f251649af2b58b8617",
 "artistId": "97e0398acf63f9fb930d7d4ce209a52b",
 "type": "music",
 "mediaType": "song",
 "isVideo": false,
 "bpm": 134,
 "comment": "This is a song comment",
 "sortName": "Polar expedition",
 "musicBrainzId": "189002e7-3285-4e2e-92a3-7f6c30d407a2",
 "isrc": [
 "USSM18300073",
 "DELV42300297",
 "DEE868300011",
 "DEE868300007"
 ],
 "genres": [
 {
 "name": "Hip-Hop"
 },
 {
 "name": "East coast"
 }
 ],
 "artists": [
 {
 "id": "ar-1",
 "name": "Artist 1"
 },
 {
 "id": "ar-2",
 "name": "Artist 2"
 }
 ],
 "displayArtist": "Artist 1 feat. Artist 2",
 "albumArtists": [
 {
 "id": "ar-6",
 "name": "Artist 6"
 },
 {
 "id": "ar-7",
 "name": "Artist 7"
 }
 ],
 "displayAlbumArtist": "Artist 6 & Artist 7",
 "contributors": [
 {
 "role": "composer",
 "artist": {
 "id": "ar-3",
 "name": "Artist 3"
 }
 },
 {
 "role": "composer",
 "artist": {
 "id": "ar-4",
 "name": "Artist 4"
 }
 },
 {
 "role": "lyricist",
 "artist": {
 "id": "ar-5",
 "name": "Artist 5"
 }
 },
 {
 "role": "performer",
 "subRole": "Bass",
 "artist": {
 "id": "ar-5",
 "name": "Artist 5"
 }
 }
 ],
 "displayComposer": "Artist 3, Artist 4",
 "moods": [
 "slow",
 "cool"
 ],
 "explicitStatus": "explicit",
 "replayGain": {
 "trackGain": 0.1,
 "albumGain": 1.1,
 "trackPeak": 9.2,
 "albumPeak": 9,
 "baseGain": 0
 },
 "works": [
 {
 "name": "Symphony No. 5 in C minor, Op. 67",
 "musicBrainzId": "d03bff61-26fc-301b-98ac-4d8e85771cbc"
 }
 ],
 "movements": [
 {
 "name": "Andante con moto",
 "number": 2,
 "count": 4
 }
 ]
}

{
 "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.
`bookmarkPosition`	`long`	No		The bookmark position in seconds
`originalWidth`	`int`	No		The video original Width
`originalHeight`	`int`	No		The video original Height
`played`	`string`	No	Yes	Date the album was last played. [ISO 8601]
`bpm`	`int`	No	Yes	The BPM of the song.
`comment`	`string`	No	Yes	The comment tag of the song.
`sortName`	`string`	No	Yes	The song sort name.
`musicBrainzId`	`string`	No	Yes	The track MusicBrainzID.
`isrc`	Array of `string`	No	Yes	The track ISRC(s).
`genres`	Array of `ItemGenre`	No	Yes	The list of all genres of the song.
`artists`	Array of `ArtistID3`	No	Yes	The list of all song artists of the song. (Note: Only the required `ArtistID3` fields should be returned by default)
`displayArtist`	`string`	No	Yes	The single value display artist.
`albumArtists`	Array of `ArtistID3`	No	Yes	The list of all album artists of the song. (Note: Only the required `ArtistID3` fields should be returned by default)
`displayAlbumArtist`	`string`	No	Yes	The single value display album artist.
`contributors`	Array of `Contributor`	No	Yes	The list of all contributor artists of the song.
`displayComposer`	`string`	No	Yes	The single value display composer.
`moods`	Array of `string`	No	Yes	The list of all moods of the song.
`replayGain`	`ReplayGain`	No	Yes	The replaygain data of the song.
`explicitStatus`	`string`	No	Yes	Returns “explicit”, “clean” or “”. (For songs extracted from tags “ITUNESADVISORY”: 1 = explicit, 2 = clean, MP4 “rtng”: 1 or 4 = explicit, 2 = clean. See `albumID3` for albums)
`works`	Array of `Work`	No	Yes	The list of works associated with the song.
`movements`	Array of `Movement`	No	Yes	The list of movements associated with the song.

OpenSubsonic

New fields are added:

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.

Contributor

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

{
 "role": "performer",
 "subRole": "Bass",
 "artist": {
 "id": "ar-1",
 "name": "Artist 1"
 }
}

Does not exist.

Field	Type	Req.	OpenS.	Details
`role`	`string`	Yes	Yes	The contributor role.
`subRole`	`string`	No	Yes	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.
`artist`	`ArtistID3`	Yes	Yes	The artist taking on the role. (Note: Only the required `ArtistID3` fields should be returned by default)

OpenSubsonic

This is a new OpenSubsonic response type.

createBookmark

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

http://your-server/rest/createBookmark Since 1.9.0

Creates or updates a bookmark (a position within a media file). Bookmarks are personal and not visible to other users.

Parameters

Parameter	Req.	Comment
`id`	Yes	ID of the media file to bookmark. If a bookmark already exists for this file it will be overwritten.
`position`	Yes	The position (in milliseconds) within the media file.
`comment`	No	A user-defined comment.

Example

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

Result

An empty subsonic-response element on success.

createInternetRadioStation

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

http://your-server/rest/createInternetRadioStation Since 1.16.0

Adds a new internet radio station. Only users with admin privileges are allowed to call this method.

Parameters

Parameter	Req.	Comment
`streamUrl`	Yes	The stream URL for the station.
`name`	Yes	The user-defined name for the station.
`homepageUrl`	No	The home page URL for the station.

Example

http://your-server/rest/createInternetRadioStation.view?streamUrl=url&name=radio&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

An empty subsonic-response element on success.

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1"
 }
}

createPlaylist

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

http://your-server/rest/createPlaylist Since 1.2.0

Creates (or updates) a playlist.

Parameters

Parameter	Req.	Comment
`playlistId`	Yes (if updating)	The playlist ID.
`name`	Yes (if creating)	The human-readable name of the playlist.
`songId`	No	ID of a song in the playlist. Use one `songId` parameter for each song in the playlist.

Example

http://your-server/rest/createPlaylist.view?name=abc&songId=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

Since 1.14.0

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "playlist": {
 "id": "800000075",
 "name": "testcreate",
 "owner": "user",
 "public": true,
 "created": "2023-03-16T03:18:41+00:00",
 "changed": "2023-03-16T03:18:41+00:00",
 "songCount": 1,
 "duration": 304,
 "entry": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "playlist": {
 "id": "800000075",
 "name": "testcreate",
 "owner": "user",
 "public": true,
 "created": "2023-03-16T03:18:41+00:00",
 "changed": "2023-03-16T03:18:41+00:00",
 "songCount": 1,
 "duration": 304,
 "entry": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`playlist`	`playlist`	Yes		The created playlist

Before 1.14.0

An empty subsonic-response element on success.

createPodcastChannel

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

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).

Parameters

Parameter	Req.	OpenS.	Default	Comment
`url`	Yes			The URL of the Podcast to add.

Example

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

Result

An empty subsonic-response element on success.

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1"
 }
}

createShare

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

http://your-server/rest/createShare Since 1.6.0

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

Example

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

Result

A subsonic-response element with a nested shares element on success. Which in turns contains a single share element for the newly created share

createUser

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

http://your-server/rest/createUser Since 1.1.0

Creates a new user on the server, using the following parameters:

Parameters

Parameter	Req.	Default	Comment
`username`	Yes		The name of the new user.
`password`	Yes		The password of the new user, either in clear text of hex-encoded (see above).
`email`	Yes		The email address of the new user.
`ldapAuthenticated`	No	false	Whether the user is authenticated in LDAP.
`adminRole`	No	false	Whether the user is administrator.
`settingsRole`	No	true	Whether the user is allowed to change personal settings and password.
`streamRole`	No	true	Whether the user is allowed to play files.
`jukeboxRole`	No	false	Whether the user is allowed to play files in jukebox mode.
`downloadRole`	No	false	Whether the user is allowed to download files.
`uploadRole`	No	false	Whether the user is allowed to upload files.
`playlistRole`	No	false	Whether the user is allowed to create and delete playlists. Since 1.8.0, changing this role has no effect.
`coverArtRole`	No	false	Whether the user is allowed to change cover art and tags.
`commentRole`	No	false	Whether the user is allowed to create and edit comments and ratings.
`podcastRole`	No	false	Whether the user is allowed to administrate Podcasts.
`shareRole`	No	false	(Since 1.8.0) 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	All folders	(Since 1.12.0) IDs of the music folders the user is allowed access to. Include the parameter once for each folder.

Example

http://your-server/rest/createUser.view?username=test&password=test&email=test@test.com&name=radio&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

An empty subsonic-response element on success.

cue

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

{
 "start": 2747,
 "end": 3018,
 "value": "눈"
}

<cue start="2747" end="3018">눈</cue>

Does not exist.

Field	Type	Req.	OpenS.	Details
`start`	`integer`	Yes	Yes	Start time in milliseconds
`end`	`integer`	No	Yes	End time in milliseconds. Within a `cueLine`, `end` must 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
`value`	`string`	Yes	Yes	The text of this word or syllable

OpenSubsonic

This is a new OpenSubsonic response type added in extension songLyrics version 2.

cueLine

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

{
 "index": 0,
 "start": 2747,
 "end": 6214,
 "value": "눈을 뜬 순간",
 "cue": [
 { "start": 2747, "end": 3018, "value": "눈" },
 { "start": 3018, "end": 3179, "value": "을" },
 { "start": 3179, "end": 3582, "value": " " },
 { "start": 3582, "end": 4100, "value": "뜬" },
 { "start": 4100, "end": 4500, "value": " " },
 { "start": 4500, "end": 5200, "value": "순" },
 { "start": 5200, "end": 6214, "value": "간" }
 ]
}

<cueLine index="0" start="2747" end="6214" value="눈을 뜬 순간">
 <cue start="2747" end="3018">눈</cue>
 <cue start="3018" end="3179">을</cue>
 <cue start="3179" end="3582"> </cue>
 <cue start="3582" end="4100">뜬</cue>
 <cue start="4100" end="4500"> </cue>
 <cue start="4500" end="5200">순</cue>
 <cue start="5200" end="6214">간</cue>
</cueLine>

Does not exist.

Example with agent attribution

{
 "index": 0,
 "start": 1000,
 "end": 4000,
 "value": "You and I",
 "agentId": "lead",
 "cue": [
 { "start": 1000, "end": 1800, "value": "You " },
 { "start": 1800, "end": 2400, "value": "and " },
 { "start": 2400, "end": 3200, "value": "I" }
 ]
}

<cueLine index="0" start="1000" end="4000" value="You and I" agentId="lead">
 <cue start="1000" end="1800">You </cue>
 <cue start="1800" end="2400">and </cue>
 <cue start="2400" end="3200">I</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`	No	Yes	Full text of the line (for validation/fallback)
`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
`cue`	Array of `cue`	Yes	Yes	Ordered list of word/syllable cues

OpenSubsonic

This is a new OpenSubsonic response type added in extension songLyrics version 2.

deleteBookmark

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

http://your-server/rest/deleteBookmark Since 1.9.0

Creates or updates a bookmark (a position within a media file). Bookmarks are personal and not visible to other users.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			ID of the media file for which to delete the bookmark. Other users’ bookmarks are not affected.

Example

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

Result

An empty subsonic-response element on success.

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1"
 }
}

deleteInternetRadioStation

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

http://your-server/rest/deleteInternetRadioStation Since 1.16.0

Deletes an existing internet radio station. Only users with admin privileges are allowed to call this method.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			The ID for the station.

Example

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

Result

An empty subsonic-response element on success.

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1"
 }
}

deletePlaylist

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

http://your-server/rest/deletePlaylist Since 1.2.0

Deletes a saved playlist.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			ID of the playlist to delete, as obtained by `getPlaylists`.

Example

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

Result

An empty subsonic-response element on success.

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1"
 }
}

deletePodcastChannel

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

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).

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			The ID of the Podcast channel to delete.

Example

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

Result

An empty subsonic-response element on success.

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

{
 "subsonic-response": {
 "status":"ok",
 "version":"1.16.1",
 }
}

deletePodcastEpisode

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

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).

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			The ID of the Podcast episode to delete.

Example

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

Result

An empty subsonic-response element on success.

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1"
 }
}

deleteShare

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

http://your-server/rest/deleteShare Since 1.6.0

Deletes an existing share.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			ID of the share to delete.

Example

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

Result

An empty subsonic-response element on success.

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1"
 }
}

deleteUser

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

http://your-server/rest/deleteUser Since 1.3.0

Deletes an existing user on the server, using the following parameters:

Parameters

Parameter	Req.	OpenS.	Default	Comment
`username`	Yes			The name of the user to delete.

Example

http://your-server/rest/deleteUser.view?username=test&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

An empty subsonic-response element on success.

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1"
 }
}

Field	Type	Req.	Details
`id`	`string`	Yes	The id
`parent`	`string`	No	Parent item
`name`	`string`	Yes	The directory name
`starred`	`string`	No	Starred date [ISO 8601]
`userRating`	`int`	No	The user rating [1-5]
`averageRating`	`number`	No	The average rating [1.0-5.0]
`playCount`	`long`	No	The play count
`child`	Array of `Child`	No	The directory content

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.

DiscTitle

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

{
 "disc": 0,
 "title": "The disc title"
 "coverArt": "65135"
}

Does not exist.

Field	Type	Req.	OpenS.	Details
`disc`	`int`	Yes	Yes	The disc number.
`title`	`string`	Yes	Yes	The name of the disc.
`coverArt`	`string`	No	Yes	The cover art ID of the disc.

OpenSubsonic

This is a new OpenSubsonic response type.

download

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

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

Downloads a given media file. Similar to stream, but this method returns the original media data without transcoding or downsampling.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			A string which uniquely identifies the file to stream. Obtained by calls to getMusicDirectory.

Example

http://your-server/rest/download.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”).

downloadPodcastEpisode

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

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).

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			The ID of the Podcast episode to download.

Example

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

Result

An empty subsonic-response element on success.

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1"
 }
}

error

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

{
 "code": 42,
 "message": "Authentication mechanism not supported. Use API keys",
 "helpUrl": "https://example.org/users/apiKey"
}

{
 "code": 40,
 "message": "Wrong username or password"
}

Field	Type	Req.	OpenS.	Details
`code`	`int`	Yes		The error code
`message`	`string`	No		The optional error message
`helpUrl`	`string`	No	Yes	A URL (documentation, configuration, etc) which may provide additional context for the error)

The following error codes are defined:

findSonicPath

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

http://your-server/rest/findSonicPath

Finds a path of songs connecting a start song to an end song, navigating through audio similarity space.

Parameters

Parameter	Req.	Default	Comment
`startSongId`	Yes		The ID of the starting song.
`endSongId`	Yes		The ID of the ending/target song.
`count`	No	25	Maximum number of songs in the path.

Example

http://your-server/rest/findSonicPath.view?startSongId=100&endSongId=200&count=5&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

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.

findSonicPathResult

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

{
 "sonicMatch": [
 {
 "entry": {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP/04-Synthetic_-_BrownSmoke.wma"
 },
 "similarity": 1.0
 },
 {
 "entry": {
 "id": "300000055",
 "parent": "200000002",
 "title": "Red&GreenSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000055",
 "duration": 400,
 "bitRate": 64,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 5,
 "year": 2007,
 "genre": "Electronic",
 "size": 3209886,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP/05-Synthetic_-_RedGreenSmoke.mp3"
 },
 "similarity": 0.55
 }
 ]
}

Does not exist.

Field	Type	Req.	OpenS.	Details
`sonicMatch`	Array of `sonicMatch`	Yes		An ordered list of songs forming the path, each with its similarity score from the starting song.

genre

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

{
 "songCount": 6,
 "albumCount": 1,
 "value": "Noise"
}

{
 "songCount": 6,
 "albumCount": 1,
 "value": "Noise"
}

Field	Type	Req.	Details
`value`	`string`	Yes	Genre name
`songCount`	`int`	Yes	Genre song count
`albumCount`	`int`	Yes	Genre album count

genres

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

{
 "genre": [
 {
 "songCount": 1,
 "albumCount": 1,
 "value": "Punk"
 },
 {
 "songCount": 4,
 "albumCount": 1,
 "value": "Dark Ambient"
 },
 {
 "songCount": 6,
 "albumCount": 1,
 "value": "Noise"
 },
 {
 "songCount": 11,
 "albumCount": 1,
 "value": "Electronica"
 },
 {
 "songCount": 11,
 "albumCount": 1,
 "value": "Dance"
 },
 {
 "songCount": 12,
 "albumCount": 1,
 "value": "Electronic"
 },
 {
 "songCount": 20,
 "albumCount": 1,
 "value": "Hip-Hop"
 }
 ]
}

{
 "genre": [
 {
 "songCount": 1,
 "albumCount": 1,
 "value": "Punk"
 },
 {
 "songCount": 4,
 "albumCount": 1,
 "value": "Dark Ambient"
 },
 {
 "songCount": 6,
 "albumCount": 1,
 "value": "Noise"
 },
 {
 "songCount": 11,
 "albumCount": 1,
 "value": "Electronica"
 },
 {
 "songCount": 11,
 "albumCount": 1,
 "value": "Dance"
 },
 {
 "songCount": 12,
 "albumCount": 1,
 "value": "Electronic"
 },
 {
 "songCount": 20,
 "albumCount": 1,
 "value": "Hip-Hop"
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`genre`	Array of `genre`	No		List of genre

getAlbum

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

http://your-server/rest/getAlbum Since 1.8.0

Returns details for an album, including a list of songs. This method organizes music according to ID3 tags.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			The album ID.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "album": {
 "id": "200000021",
 "parent": "100000036",
 "album": "Forget and Remember",
 "title": "Forget and Remember",
 "name": "Forget and Remember",
 "isDir": true,
 "coverArt": "al-200000021",
 "songCount": 20,
 "created": "2021-07-22T02:09:31+00:00",
 "duration": 4248,
 "playCount": 0,
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "year": 2005,
 "genre": "Hip-Hop",
 "song": [
 {
 "id": "300000116",
 "parent": "200000021",
 "title": "Can I Help U?",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000116",
 "duration": 103,
 "bitRate": 216,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 1,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 2811819,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
 },
 {
 "id": "300000121",
 "parent": "200000021",
 "title": "Planetary Picknick",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000121",
 "duration": 358,
 "bitRate": 238,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 2,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 10715592,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/2 - Planetary Picknick.mp3"
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "album": {
 "id": "200000021",
 "parent": "100000036",
 "album": "Forget and Remember",
 "title": "Forget and Remember",
 "name": "Forget and Remember",
 "isDir": true,
 "coverArt": "al-200000021",
 "songCount": 20,
 "created": "2021-07-22T02:09:31+00:00",
 "duration": 4248,
 "playCount": 0,
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "year": 2005,
 "genre": "Hip-Hop",
 "song": [
 {
 "id": "300000116",
 "parent": "200000021",
 "title": "Can I Help U?",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000116",
 "duration": 103,
 "bitRate": 216,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 1,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 2811819,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
 },
 {
 "id": "300000121",
 "parent": "200000021",
 "title": "Planetary Picknick",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000121",
 "duration": 358,
 "bitRate": 238,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 2,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 10715592,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/2 - Planetary Picknick.mp3"
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`album`	`AlbumID3WithSongs`	Yes		The album

getAlbumInfo

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

http://your-server/rest/getAlbumInfo Since 1.14.0

Returns album notes, image URLs etc, using data from last.fm.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			The album ID or song ID.

Example

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

Result

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

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

Field	Type	Req.	OpenS.	Details
`albumInfo`	`albumInfo`	Yes		The album info

getAlbumInfo2

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

http://your-server/rest/getAlbumInfo2 Since 1.14.0

Similar to getAlbumInfo, but organizes music according to ID3 tags.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			The album ID or song ID.

Example

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

Result

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

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

Field	Type	Req.	OpenS.	Details
`albumInfo`	`albumInfo`	Yes		The album info

getAlbumList

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

http://your-server/rest/getAlbumList Since 1.2.0

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.	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`.

Example

http://your-server/rest/getAlbumList.view?type=random&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

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

getAlbumList2

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

http://your-server/rest/getAlbumList2 Since 1.8.0

Similar to getAlbumList, but organizes music according to ID3 tags.

Parameters

Parameter	Req.	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`.

Example

http://your-server/rest/getAlbumList2.view?type=random&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

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

getArtist

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

http://your-server/rest/getArtist Since 1.8.0

Returns details for an artist, including a list of albums. This method organizes music according to ID3 tags.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			The artist ID.

Example

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

Result

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

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "artist": {
 "id": "37ec820ca7193e17040c98f7da7c4b51",
 "name": "2 Mello",
 "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
 "albumCount": 1,
 "userRating": 5,
 "artistImageUrl": "https://demo.org/image.jpg",
 "starred": "2017-04-11T10:42:50.842Z",
 "album": [
 {
 "id": "200000002",
 "parent": "100000002",
 "album": "Colorsmoke EP",
 "title": "Colorsmoke EP",
 "name": "Colorsmoke EP",
 "isDir": true,
 "coverArt": "al-200000002",
 "songCount": 12,
 "created": "2021-02-23T04:24:48+00:00",
 "duration": 4568,
 "playCount": 1,
 "artistId": "100000002",
 "artist": "Synthetic",
 "year": 2007,
 "genre": "Electronic",
 "userRating": 5,
 "averageRating": 3,
 "starred": "2021-02-22T05:51:53Z"
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`artist`	`artist`	Yes		The artist

getArtistInfo

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

http://your-server/rest/getArtistInfo Since 1.11.0

Returns artist info with biography, image URLs and similar artists, using data from last.fm.

Parameters

Parameter	Req.	Default	Comment
`id`	Yes		The artist, album or song ID.
`count`	No	20	Max number of similar artists to return.
`includeNotPresent`	No	false	Whether to return artists that are not present in the media library.

Example

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

Result

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

getArtistInfo2

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

http://your-server/rest/getArtistInfo2 Since 1.11.0

Similar to getArtistInfo, but organizes music according to ID3 tags.

Parameters

Parameter	Req.	Default	Comment
`id`	Yes		The artist, album or song ID.
`count`	No	20	Max number of similar artists to return.
`includeNotPresent`	No	false	Whether to return artists that are not present in the media library.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "artistInfo2": {
 "biography": "Empty biography",
 "musicBrainzId": "1",
 "smallImageUrl": "http://localhost:8989/play/art/f20070e8e11611cc53542a38801d60fa/artist/2/thumb34.jpg",
 "mediumImageUrl": "http://localhost:8989/play/art/2b9b6c057cd4bf21089ce7572e7792b6/artist/2/thumb64.jpg",
 "largeImageUrl": "http://localhost:8989/play/art/e18287c23a75e263b64c31b3d64c1944/artist/2/thumb174.jpg"
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "artistInfo2": {
 "biography": "Empty biography",
 "musicBrainzId": "1",
 "smallImageUrl": "http://localhost:8989/play/art/f20070e8e11611cc53542a38801d60fa/artist/2/thumb34.jpg",
 "mediumImageUrl": "http://localhost:8989/play/art/2b9b6c057cd4bf21089ce7572e7792b6/artist/2/thumb64.jpg",
 "largeImageUrl": "http://localhost:8989/play/art/e18287c23a75e263b64c31b3d64c1944/artist/2/thumb174.jpg"
 }
 }
}

Field	Type	Req.	OpenS.	Details
`artistInfo2`	`artistInfo2`	Yes		The album info

getArtists

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

http://your-server/rest/getArtists Since 1.8.0

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`.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "artists": {
 "ignoredArticles": "The An A Die Das Ein Eine Les Le La",
 "index": [
 {
 "name": "C",
 "artist": [
 {
 "id": "100000016",
 "name": "CARNÚN",
 "coverArt": "ar-100000016",
 "albumCount": 1
 },
 {
 "id": "100000027",
 "name": "Chi.Otic",
 "coverArt": "ar-100000027",
 "albumCount": 0
 }
 ]
 },
 {
 "name": "I",
 "artist": [
 {
 "id": "100000013",
 "name": "IOK-1",
 "coverArt": "ar-100000013",
 "albumCount": 1
 }
 ]
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "artists": {
 "ignoredArticles": "The An A Die Das Ein Eine Les Le La",
 "index": [
 {
 "name": "C",
 "artist": [
 {
 "id": "100000016",
 "name": "CARNÚN",
 "coverArt": "ar-100000016",
 "albumCount": 1
 },
 {
 "id": "100000027",
 "name": "Chi.Otic",
 "coverArt": "ar-100000027",
 "albumCount": 0
 }
 ]
 },
 {
 "name": "I",
 "artist": [
 {
 "id": "100000013",
 "name": "IOK-1",
 "coverArt": "ar-100000013",
 "albumCount": 1
 }
 ]
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`artists`	`artists`	Yes		The artist list

getAvatar

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

http://your-server/rest/getAvatar Since 1.8.0

Returns the avatar (personal image) for a user.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`username`	Yes		The user in question..

Example

http://your-server/rest/getAvatar.view?username=test&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

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

getBookmarks

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

http://your-server/rest/getBookmarks Since 1.9.0

Returns all bookmarks for this user. A bookmark is a position within a certain media file.

Parameters

Takes no extra parameters.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "bookmarks": {
 "bookmark": [
 {
 "entry": {
 "id": "113bf5989ad15ce2cf1834ba9622983f",
 "parent": "b87a936c682c49d4494c7ccb08c22d23",
 "isDir": false,
 "title": "Stay Out Here",
 "album": "Shaking The Habitual",
 "artist": "The Knife",
 "track": 11,
 "year": 2013,
 "genre": "Electronic",
 "coverArt": "al-b87a936c682c49d4494c7ccb08c22d23_0",
 "size": 21096309,
 "contentType": "audio/mp4",
 "suffix": "m4a",
 "duration": 642,
 "bitRate": 257,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "path": "The Knife/Shaking The Habitual/11 - Stay Out Here.m4a",
 "created": "2023-03-13T16:30:35Z",
 "albumId": "b87a936c682c49d4494c7ccb08c22d23",
 "artistId": "b29e9a9d780cb0e133f3add5662771b9",
 "type": "music",
 "isVideo": false,
 "bookmarkPosition": 129000
 },
 "position": 129000,
 "username": "demo",
 "comment": "",
 "created": "2023-03-13T16:30:35Z",
 "changed": "2023-03-13T16:30:35Z"
 },
 {
 "entry": {
 "id": "2b42782333450d02b177823e729664af",
 "parent": "dc8d8889a6fe08d8da7698c7ee1de61c",
 "isDir": false,
 "title": "Ill with the Skills",
 "album": "First Words",
 "artist": "The Polish Ambassador",
 "track": 17,
 "year": 2014,
 "coverArt": "mf-2b42782333450d02b177823e729664af_641edeb3",
 "size": 6219581,
 "contentType": "audio/mpeg",
 "suffix": "mp3",
 "duration": 255,
 "bitRate": 194,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "path": "The Polish Ambassador/First Words/17 - Ill with the Skills.mp3",
 "playCount": 1,
 "played": "2023-03-15T15:23:37Z",
 "created": "2023-03-25T11:44:51Z",
 "albumId": "dc8d8889a6fe08d8da7698c7ee1de61c",
 "artistId": "64e1f796b283545d329cdf6a31a31dbe",
 "type": "music",
 "isVideo": false,
 "bookmarkPosition": 7000
 },
 "position": 7000,
 "username": "demo",
 "comment": "playSub bookmark",
 "created": "2023-03-25T11:44:51Z",
 "changed": "2023-03-25T11:44:51Z"
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "bookmarks": {
 "bookmark": [
 {
 "entry": {
 "id": "113bf5989ad15ce2cf1834ba9622983f",
 "parent": "b87a936c682c49d4494c7ccb08c22d23",
 "isDir": false,
 "title": "Stay Out Here",
 "album": "Shaking The Habitual",
 "artist": "The Knife",
 "track": 11,
 "year": 2013,
 "genre": "Electronic",
 "coverArt": "al-b87a936c682c49d4494c7ccb08c22d23_0",
 "size": 21096309,
 "contentType": "audio/mp4",
 "suffix": "m4a",
 "duration": 642,
 "bitRate": 257,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "path": "The Knife/Shaking The Habitual/11 - Stay Out Here.m4a",
 "created": "2023-03-13T16:30:35Z",
 "albumId": "b87a936c682c49d4494c7ccb08c22d23",
 "artistId": "b29e9a9d780cb0e133f3add5662771b9",
 "type": "music",
 "isVideo": false,
 "bookmarkPosition": 129000
 },
 "position": 129000,
 "username": "demo",
 "comment": "",
 "created": "2023-03-13T16:30:35Z",
 "changed": "2023-03-13T16:30:35Z"
 },
 {
 "entry": {
 "id": "2b42782333450d02b177823e729664af",
 "parent": "dc8d8889a6fe08d8da7698c7ee1de61c",
 "isDir": false,
 "title": "Ill with the Skills",
 "album": "First Words",
 "artist": "The Polish Ambassador",
 "track": 17,
 "year": 2014,
 "coverArt": "mf-2b42782333450d02b177823e729664af_641edeb3",
 "size": 6219581,
 "contentType": "audio/mpeg",
 "suffix": "mp3",
 "duration": 255,
 "bitRate": 194,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "path": "The Polish Ambassador/First Words/17 - Ill with the Skills.mp3",
 "playCount": 1,
 "played": "2023-03-15T15:23:37Z",
 "created": "2023-03-25T11:44:51Z",
 "albumId": "dc8d8889a6fe08d8da7698c7ee1de61c",
 "artistId": "64e1f796b283545d329cdf6a31a31dbe",
 "type": "music",
 "isVideo": false,
 "bookmarkPosition": 7000
 },
 "position": 7000,
 "username": "demo",
 "comment": "playSub bookmark",
 "created": "2023-03-25T11:44:51Z",
 "changed": "2023-03-25T11:44:51Z"
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`bookmarks`	`bookmarks`	Yes		The bookmarks

getCaptions

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

http://your-server/rest/getCaptions Since 1.14.0

Returns captions (subtitles) for a video. Use getVideoInfo to get a list of available captions.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			The ID of the video.
`format`	No			Preferred captions format (“srt” or “vtt”).

Example

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

Result

Returns the raw video captions.

getChatMessages

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

http://your-server/rest/getChatMessages Since 1.2.0

Returns the current visible (non-expired) chat messages.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`since`	No			Only return messages newer than this time (in millis since Jan 1 1970).

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "chatMessages": {
 "chatMessage": [
 {
 "username": "admin",
 "time": 1678935707000,
 "message": "Api Script Testing"
 },
 {
 "username": "user",
 "time": 1678935699000,
 "message": "Api Script Testing"
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "chatMessages": {
 "chatMessage": [
 {
 "username": "admin",
 "time": 1678935707000,
 "message": "Api Script Testing"
 },
 {
 "username": "user",
 "time": 1678935699000,
 "message": "Api Script Testing"
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`chatMessages`	`chatMessages`	Yes		The message list

getCoverArt

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

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

Returns a cover art image.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes		The coverArt ID. Returned by most entities likes `Child` or `AlbumID3`
`size`	No		If specified, scale image to this size.

OpenSubsonic

In the original Subsonic, the id could refer to several entities: song, album or artist.

For OpenSubsonic servers, id refers to coverArt ID only.

Example

http://your-server/rest/getCoverArt.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”).

getGenres

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

http://your-server/rest/getGenres Since 1.9.0

Returns all genres.

Parameters

Takes no extra parameters.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "genres": {
 "genre": [
 {
 "songCount": 1,
 "albumCount": 1,
 "value": "Punk"
 },
 {
 "songCount": 4,
 "albumCount": 1,
 "value": "Dark Ambient"
 },
 {
 "songCount": 6,
 "albumCount": 1,
 "value": "Noise"
 },
 {
 "songCount": 11,
 "albumCount": 1,
 "value": "Electronica"
 },
 {
 "songCount": 11,
 "albumCount": 1,
 "value": "Dance"
 },
 {
 "songCount": 12,
 "albumCount": 1,
 "value": "Electronic"
 },
 {
 "songCount": 20,
 "albumCount": 1,
 "value": "Hip-Hop"
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "genres": {
 "genre": [
 {
 "songCount": 1,
 "albumCount": 1,
 "value": "Punk"
 },
 {
 "songCount": 4,
 "albumCount": 1,
 "value": "Dark Ambient"
 },
 {
 "songCount": 6,
 "albumCount": 1,
 "value": "Noise"
 },
 {
 "songCount": 11,
 "albumCount": 1,
 "value": "Electronica"
 },
 {
 "songCount": 11,
 "albumCount": 1,
 "value": "Dance"
 },
 {
 "songCount": 12,
 "albumCount": 1,
 "value": "Electronic"
 },
 {
 "songCount": 20,
 "albumCount": 1,
 "value": "Hip-Hop"
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`genres`	`genres`	Yes		The genre list

getIndexes

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

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

Returns an indexed structure of all artists.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`musicFolderId`	No			If specified, only return artists in the music folder with the given ID. See `getMusicFolders`.
`ifModifiedSince`	No			If specified, only return a result if the artist collection has changed since the given time (in milliseconds since 1 Jan 1970).

Example

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

Result

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

getInternetRadioStations

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

http://your-server/rest/getInternetRadioStations Since 1.9.0

Returns all internet radio stations. Takes no extra parameters.

Parameters

Takes no extra parameters.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "internetRadioStations": {
 "internetRadioStation": [
 {
 "id": "1",
 "name": "HBR1.com - Dream Factory",
 "streamUrl": "http://ubuntu.hbr1.com:19800/ambient.aac",
 "homePageUrl": "http://www.hbr1.com/",
 "coverArt": "ir-1"
 },
 {
 "id": "2",
 "name": "HBR1.com - I.D.M. Tranceponder",
 "streamUrl": "http://ubuntu.hbr1.com:19800/trance.ogg",
 "homePageUrl": "http://www.hbr1.com/",
 "coverArt": "ir-2"
 },
 {
 "id": "3",
 "name": "4ZZZ Community Radio",
 "streamUrl": "https://stream.4zzz.org.au:9200/4zzz",
 "homePageUrl": "https://4zzzfm.org.au",
 "coverArt": "ir-3"
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "internetRadioStations": {
 "internetRadioStation": [
 {
 "id": "1",
 "name": "HBR1.com - Dream Factory",
 "streamUrl": "http://ubuntu.hbr1.com:19800/ambient.aac",
 "homePageUrl": "http://www.hbr1.com/"
 },
 {
 "id": "2",
 "name": "HBR1.com - I.D.M. Tranceponder",
 "streamUrl": "http://ubuntu.hbr1.com:19800/trance.ogg",
 "homePageUrl": "http://www.hbr1.com/"
 },
 {
 "id": "3",
 "name": "4ZZZ Community Radio",
 "streamUrl": "https://stream.4zzz.org.au:9200/4zzz",
 "homePageUrl": "https://4zzzfm.org.au"
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`internetRadioStations`	`internetRadioStations`	Yes		The radio stations

getLicense

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

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

Get details about the software license.

Parameters

Takes no extra parameters.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "license": {
 "valid": true,
 "email": "demo@demo.org",
 "licenseExpires": "2017-04-11T10:42:50.842Z",
 "trialExpires": "2017-04-11T10:42:50.842Z"
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "license": {
 "valid": true,
 "email": "demo@demo.org",
 "licenseExpires": "2017-04-11T10:42:50.842Z",
 "trialExpires": "2017-04-11T10:42:50.842Z"
 }
 }
}

Field	Type	Req.	OpenS.	Details
`license`	`license`	Yes		The status of the license

getLyrics

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

http://your-server/rest/getLyrics Since 1.2.0

Searches for and returns lyrics for a given song.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`artist`	No			The artist name.
`title`	No			The song title.

Example

http://your-server/rest/getLyrics.view?artist=toto&title=tata&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

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

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

Field	Type	Req.	OpenS.	Details
`lyrics`	`lyrics`	Yes		The lyrics

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

getMusicDirectory

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

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.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "directory": {
 "id": "1",
 "name": "music",
 "child": [
 {
 "id": "100000016",
 "parent": "1",
 "isDir": true,
 "title": "CARNÚN",
 "artist": "CARNÚN",
 "coverArt": "ar-100000016"
 },
 {
 "id": "100000027",
 "parent": "1",
 "isDir": true,
 "title": "Chi.Otic",
 "artist": "Chi.Otic",
 "coverArt": "ar-100000027"
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "directory": {
 "id": "1",
 "name": "music",
 "child": [
 {
 "id": "100000016",
 "parent": "1",
 "isDir": true,
 "title": "CARNÚN",
 "artist": "CARNÚN",
 "coverArt": "ar-100000016"
 },
 {
 "id": "100000027",
 "parent": "1",
 "isDir": true,
 "title": "Chi.Otic",
 "artist": "Chi.Otic",
 "coverArt": "ar-100000027"
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`directory`	`directory`	Yes		The directory content

getMusicFolders

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

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

Returns all configured top-level music folders. Takes no extra parameters.

Parameters

Takes no extra parameters.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "musicFolders": {
 "musicFolder": [
 {
 "id": 1,
 "name": "music"
 },
 {
 "id": 4,
 "name": "upload"
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "musicFolders": {
 "musicFolder": [
 {
 "id": 1,
 "name": "music"
 },
 {
 "id": 4,
 "name": "upload"
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`musicFolders`	`musicFolders`	Yes		The directory content

getNewestPodcasts

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

http://your-server/rest/getNewestPodcasts Since 1.13.0

Returns the most recently published Podcast episodes.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`count`	No		20	The maximum number of episodes to return.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "newestPodcasts": {
 "episode": [
 {
 "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"
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "newestPodcasts": {
 "episode": [
 {
 "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"
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`newestPodcasts`	`NewestPodcasts`	Yes		The podcasts

getNowPlaying

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

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

Returns what is currently being played by all users. Takes no extra parameters.

Parameters

Takes no extra parameters.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "nowPlaying": {
 "entry": [
 {
 "id": "300115266",
 "parent": "200147046",
 "title": "Take the Home",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200147046",
 "album": "How I Learned to Love Our Robot Overlords",
 "artistId": "100002619",
 "artist": "Raggedy Angry",
 "coverArt": "300115266",
 "duration": 227,
 "bitRate": 222,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 3,
 "track": 7,
 "year": 2010,
 "genre": "Industrial",
 "size": 6341039,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Raggedy Angry/(2010) How I Learned to Love Our Robot Overlords/1-07 - Take the Home.mp3",
 "username": "user",
 "minutesAgo": 0,
 "playerId": 0,
 "state": "playing",
 "positionMs": 120000,
 "playbackRate": 1.0,
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "nowPlaying": {
 "entry": [
 {
 "id": "300115266",
 "parent": "200147046",
 "title": "Take the Home",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200147046",
 "album": "How I Learned to Love Our Robot Overlords",
 "artistId": "100002619",
 "artist": "Raggedy Angry",
 "coverArt": "300115266",
 "duration": 227,
 "bitRate": 222,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 3,
 "track": 7,
 "year": 2010,
 "genre": "Industrial",
 "size": 6341039,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Raggedy Angry/(2010) How I Learned to Love Our Robot Overlords/1-07 - Take the Home.mp3",
 "username": "user",
 "minutesAgo": 0,
 "playerId": 0
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`nowPlaying`	`nowPlaying`	Yes		The now playing content

OpenSubsonic

When the server supports extension playbackReport, entries can include state, positionMs, and playbackRate.

getOpenSubsonicExtensions

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

http://your-server/rest/getOpenSubsonicExtensions OpenSubsonic version 1

List the OpenSubsonic extensions supported by this server.

Parameters

Takes no extra parameters.

Note: Unlike all other APIs getOpenSubsonicExtensions must be publicly accessible.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "openSubsonicExtensions": [
 {
 "name": "template",
 "versions": [
 1,
 2
 ]
 },
 {
 "name": "transcodeOffset",
 "versions": [
 1
 ]
 },
 {
 "name": "sonicSimilarity",
 "versions": [
 1
 ]
 }
 ]
 }
}

Does not exist.

Field	Type	Req.	OpenS.	Details
`openSubsonicExtensions`	An array of `openSubsonicExtension`	Yes		The list of supported extensions

OpenSubsonic

This is a new endpoint.

getPlaylist

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

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

Returns a listing of files in a saved playlist.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	yes			ID of the playlist to return, as obtained by `getPlaylists`.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "playlist": {
 "id": "800000075",
 "name": "testcreate",
 "owner": "user",
 "public": true,
 "created": "2023-03-16T03:18:41+00:00",
 "changed": "2023-03-16T03:18:41+00:00",
 "songCount": 1,
 "duration": 304,
 "entry": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "playlist": {
 "id": "800000075",
 "name": "testcreate",
 "owner": "user",
 "public": true,
 "created": "2023-03-16T03:18:41+00:00",
 "changed": "2023-03-16T03:18:41+00:00",
 "songCount": 1,
 "duration": 304,
 "entry": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`playlist`	`playlist`	Yes		The created playlist

getPlaylists

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

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

Returns all playlists a user is allowed to play.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`username`	no			(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.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "playlists": {
 "playlist": [
 {
 "id": "800000003",
 "name": "random - admin - private (admin)",
 "owner": "admin",
 "public": false,
 "created": "2021-02-23T04:35:38+00:00",
 "changed": "2021-02-23T04:35:38+00:00",
 "songCount": 43,
 "duration": 17875
 },
 {
 "id": "800000002",
 "name": "random - admin - public (admin)",
 "owner": "admin",
 "public": true,
 "created": "2021-02-23T04:34:56+00:00",
 "changed": "2021-02-23T04:34:56+00:00",
 "songCount": 43,
 "duration": 17786
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "playlists": {
 "playlist": [
 {
 "id": "800000003",
 "name": "random - admin - private (admin)",
 "owner": "admin",
 "public": false,
 "created": "2021-02-23T04:35:38+00:00",
 "changed": "2021-02-23T04:35:38+00:00",
 "songCount": 43,
 "duration": 17875
 },
 {
 "id": "800000002",
 "name": "random - admin - public (admin)",
 "owner": "admin",
 "public": true,
 "created": "2021-02-23T04:34:56+00:00",
 "changed": "2021-02-23T04:34:56+00:00",
 "songCount": 43,
 "duration": 17786
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`playlists`	`playlists`	Yes		The playlists

getPlayQueue

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

http://your-server/rest/getPlayQueue Since 1.12.0

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).

Parameters

Takes no extra parameters.

Example

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

Result

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

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

getPodcasts

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

http://your-server/rest/getPodcasts Since 1.6.0

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.

Example

http://your-server/rest/getPodcasts.view?title=tata&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

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

getRandomSongs

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

http://your-server/rest/getRandomSongs Since 1.2.0

Returns random songs matching the given criteria.

Parameters

Parameter	Req.	Default	Comment
`size`	No	10	The maximum number of songs to return. Max 500.
`genre`	No		Only returns songs belonging to this genre.
`fromYear`	No		Only return songs published after or in this year.
`toYear`	No		Only return songs published before or in this year.
`musicFolderId`	No		Only return songs in the music folder with the given ID. See `getMusicFolders`.

Example

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

Result

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

getScanStatus

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

http://your-server/rest/getScanStatus Since 1.15.0

Returns the current status for media library scanning. Takes no extra parameters.

Parameters

Takes no extra parameters.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "scanStatus": {
 "scanning": true,
 "count": 1
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "scanStatus": {
 "scanning": true,
 "count": 0
 }
 }
}

Field	Type	Req.	OpenS.	Details
`scanStatus`	`scanStatus`	Yes		The status of the scan

getShares

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

http://your-server/rest/getShares Since 1.6.0

Returns information about shared media this user is allowed to manage. Takes no extra parameters.

Parameters

Takes no extra parameters.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "shares": {
 "share": [
 {
 "id": "12",
 "url": "http://localhost:8989/share.php?id=12&secret=fXlKyEv3",
 "description": "Forget and Remember (Comfort Fit)",
 "username": "user",
 "created": "2023-03-16T04:13:09+00:00",
 "visitCount": 0,
 "entry": [
 {
 "id": "300000116",
 "parent": "200000021",
 "title": "Can I Help U?",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000116",
 "duration": 103,
 "bitRate": 216,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 1,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 2811819,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
 },
 {
 "id": "300000121",
 "parent": "200000021",
 "title": "Planetary Picknick",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000121",
 "duration": 358,
 "bitRate": 238,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 2,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 10715592,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/2 - Planetary Picknick.mp3"
 }
 ]
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "shares": {
 "share": [
 {
 "id": "12",
 "url": "http://localhost:8989/share.php?id=12&secret=fXlKyEv3",
 "description": "Forget and Remember (Comfort Fit)",
 "username": "user",
 "created": "2023-03-16T04:13:09+00:00",
 "visitCount": 0,
 "entry": [
 {
 "id": "300000116",
 "parent": "200000021",
 "title": "Can I Help U?",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000116",
 "duration": 103,
 "bitRate": 216,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 1,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 2811819,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
 },
 {
 "id": "300000121",
 "parent": "200000021",
 "title": "Planetary Picknick",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000121",
 "duration": 358,
 "bitRate": 238,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 2,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 10715592,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/2 - Planetary Picknick.mp3"
 }
 ]
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`shares`	`shares`	Yes		The shares

getSimilarSongs

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

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.

getSimilarSongs2

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

http://your-server/rest/getSimilarSongs2 Since 1.11.0

Similar to getSimilarSongs, but organizes music according to ID3 tags.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			The artist ID.
`count`	No		50	Max number of songs to return.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "similarSongs2": {
 "song": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 },
 {
 "id": "300000055",
 "parent": "200000002",
 "title": "Red&GreenSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000055",
 "duration": 400,
 "bitRate": 64,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 5,
 "year": 2007,
 "genre": "Electronic",
 "size": 3209886,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "similarSongs2": {
 "song": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 },
 {
 "id": "300000055",
 "parent": "200000002",
 "title": "Red&GreenSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000055",
 "duration": 400,
 "bitRate": 64,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 5,
 "year": 2007,
 "genre": "Electronic",
 "size": 3209886,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`similarSongs2`	`similarSongs2`	Yes		The similar songs list

getSong

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

http://your-server/rest/getSong Since 1.8.0

Returns details for a song.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			The song ID.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "song": {
 "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,
 "played": "2023-03-26T22:27:46Z",
 "discNumber": 1,
 "created": "2023-03-14T17:51:22.112827504Z",
 "albumId": "e8a0685e3f3ec6f251649af2b58b8617",
 "artistId": "97e0398acf63f9fb930d7d4ce209a52b",
 "type": "music",
 "mediaType": "song",
 "isVideo": false,
 "bpm": 134,
 "comment": "This is a song comment",
 "sortName": "Polar expedition",
 "musicBrainzId": "189002e7-3285-4e2e-92a3-7f6c30d407a2",
 "genres": [
 {
 "name": "Hip-Hop"
 },
 {
 "name": "East coast"
 }
 ],
 "artists": [
 {
 "id": "ar-1",
 "name": "Artist 1"
 },
 {
 "id": "ar-2",
 "name": "Artist 2"
 }
 ],
 "displayArtist": "Artist 1 feat. Artist 2",
 "albumArtists": [
 {
 "id": "ar-6",
 "name": "Artist 6"
 },
 {
 "id": "ar-7",
 "name": "Artist 7"
 }
 ],
 "displayAlbumArtist": "Artist 6 & Artist 7",
 "contributors": [
 {
 "role": "composer",
 "artist": {
 "id": "ar-3",
 "name": "Artist 3"
 }
 },
 {
 "role": "composer",
 "artist": {
 "id": "ar-4",
 "name": "Artist 4"
 }
 },
 {
 "role": "lyricist",
 "artist": {
 "id": "ar-5",
 "name": "Artist 5"
 }
 },
 {
 "role": "performer",
 "subRole": "Bass",
 "artist": {
 "id": "ar-5",
 "name": "Artist 5"
 }
 }
 ],
 "displayComposer": "Artist 3, Artist 4",
 "moods": [
 "slow",
 "cool"
 ],
 "replayGain": {
 "trackGain": 0.1,
 "albumGain": 1.1,
 "trackPeak": 9.2,
 "albumPeak": 9,
 "baseGain": 0
 }
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "song": {
 "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
`song`	`Child`	Yes		The song

getSongsByGenre

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

http://your-server/rest/getSongsByGenre Since 1.9.0

Returns songs in a given genre.

Parameters

Parameter	Req.	Default	Comment
`genre`	Yes		The genre, as returned by `getGenres`.
`count`	No	10	The maximum number of songs to return. Max 500.
`offset`	No	0	The offset. Useful if you want to page through the songs in a genre.
`musicFolderId`	No		(Since 1.12.0) Only return albums in the music folder with the given ID. See `getMusicFolders`.

Example

http://your-server/rest/getSongsByGenre.view?genre=Electronic&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

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

getSonicSimilarTracks

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

http://your-server/rest/getSonicSimilarTracks

Returns tracks that are sonically similar to a given track, based on audio analysis. Each result includes its normalized distance from the query track.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			The ID of the song.
`count`	No		10	Max number of similar tracks to return.

Example

http://your-server/rest/getSonicSimilarTracks.view?id=100&count=5&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

A subsonic-response element with a top-level sonicMatch array on success.

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "sonicMatch": [
 {
 "entry": {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP/04-Synthetic_-_BrownSmoke.wma"
 },
 "similarity": 0.05
 },
 {
 "entry": {
 "id": "300000055",
 "parent": "200000002",
 "title": "Red&GreenSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000055",
 "duration": 400,
 "bitRate": 64,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 5,
 "year": 2007,
 "genre": "Electronic",
 "size": 3209886,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP/05-Synthetic_-_RedGreenSmoke.mp3"
 },
 "similarity": 0.12
 }
 ]
 }
 }
}

Does not exist.

Field	Type	Req.	OpenS.	Details
`sonicMatch`	Array of `sonicMatch`	Yes		The similar tracks with per-track similarity

getStarred

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

http://your-server/rest/getStarred Since 1.8.0

Returns starred songs, albums and artists.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`musicFolderId`	No			(Since 1.12.0) Only return results from the music folder with the given ID. See `getMusicFolders`.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "starred": {
 "artist": [
 {
 "id": "100000002",
 "name": "Synthetic",
 "coverArt": "ar-100000002",
 "starred": "2021-02-22T05:54:18Z"
 }
 ],
 "album": [
 {
 "id": "200000021",
 "parent": "100000036",
 "album": "Forget and Remember",
 "title": "Forget and Remember",
 "name": "Forget and Remember",
 "isDir": true,
 "coverArt": "al-200000021",
 "songCount": 20,
 "created": "2021-07-22T02:09:31+00:00",
 "duration": 4248,
 "playCount": 0,
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "year": 2005,
 "genre": "Hip-Hop"
 }
 ],
 "song": [
 {
 "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
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "starred": {
 "artist": [
 {
 "id": "100000002",
 "name": "Synthetic",
 "coverArt": "ar-100000002",
 "starred": "2021-02-22T05:54:18Z"
 }
 ],
 "album": [
 {
 "id": "200000021",
 "parent": "100000036",
 "album": "Forget and Remember",
 "title": "Forget and Remember",
 "name": "Forget and Remember",
 "isDir": true,
 "coverArt": "al-200000021",
 "songCount": 20,
 "created": "2021-07-22T02:09:31+00:00",
 "duration": 4248,
 "playCount": 0,
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "year": 2005,
 "genre": "Hip-Hop"
 }
 ],
 "song": [
 {
 "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
`starred`	`starred`	Yes		The song

getStarred2

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

http://your-server/rest/getStarred2 Since 1.8.0

Similar to getStarred, but organizes music according to ID3 tags.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`musicFolderId`	No			(Since 1.12.0) Only return results from the music folder with the given ID. See `getMusicFolders`.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "starred2": {
 "artist": [
 {
 "id": "37ec820ca7193e17040c98f7da7c4b51",
 "name": "2 Mello",
 "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
 "albumCount": 1,
 "userRating": 5,
 "artistImageUrl": "https://demo.org/image.jpg",
 "starred": "2017-04-11T10:42:50.842Z"
 }
 ],
 "album": [
 {
 "id": "ad0f112b6dcf83de5e9cae85d07f0d35",
 "name": "8-bit lagerfeuer",
 "artist": "pornophonique",
 "year": 2007,
 "coverArt": "al-ad0f112b6dcf83de5e9cae85d07f0d35_640a93a8",
 "starred": "2023-03-22T01:51:06Z",
 "duration": 1954,
 "playCount": 97,
 "genre": "Hip-Hop",
 "created": "2023-03-10T02:19:35.784818075Z",
 "artistId": "91c3901ac465b9efc439e4be4270c2b6",
 "songCount": 8
 }
 ],
 "song": [
 {
 "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
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "starred2": {
 "artist": [
 {
 "id": "37ec820ca7193e17040c98f7da7c4b51",
 "name": "2 Mello",
 "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
 "albumCount": 1,
 "userRating": 5,
 "artistImageUrl": "https://demo.org/image.jpg",
 "starred": "2017-04-11T10:42:50.842Z"
 }
 ],
 "album": [
 {
 "id": "ad0f112b6dcf83de5e9cae85d07f0d35",
 "name": "8-bit lagerfeuer",
 "artist": "pornophonique",
 "year": 2007,
 "coverArt": "al-ad0f112b6dcf83de5e9cae85d07f0d35_640a93a8",
 "starred": "2023-03-22T01:51:06Z",
 "duration": 1954,
 "playCount": 97,
 "genre": "Hip-Hop",
 "created": "2023-03-10T02:19:35.784818075Z",
 "artistId": "91c3901ac465b9efc439e4be4270c2b6",
 "songCount": 8
 }
 ],
 "song": [
 {
 "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
`starred2`	`starred2`	Yes		The song

getTopSongs

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

http://your-server/rest/getTopSongs Since 1.13.0

Returns top songs for the given artist, using data from last.fm.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`artist`	Yes			The artist name.
`count`	No		50	Max number of songs to return.

Example

http://your-server/rest/getTopSongs.view?artist=toto&u=demo&p=demo&v=1.13.0&c=AwesomeServerName&f=json

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "topSongs": {
 "song": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 },
 {
 "id": "300000055",
 "parent": "200000002",
 "title": "Red&GreenSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000055",
 "duration": 400,
 "bitRate": 64,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 5,
 "year": 2007,
 "genre": "Electronic",
 "size": 3209886,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "topSongs": {
 "song": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 },
 {
 "id": "300000055",
 "parent": "200000002",
 "title": "Red&GreenSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000055",
 "duration": 400,
 "bitRate": 64,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 5,
 "year": 2007,
 "genre": "Electronic",
 "size": 3209886,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`topSongs`	`topSongs`	Yes		The top songs list

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.

getUser

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

http://your-server/rest/getUser Since 1.3.0

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.

Example

http://your-server/rest/getUser.view?username=tata&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

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

getUsers

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

http://your-server/rest/getUsers Since 1.8.0

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.

Parameters

Takes no extra parameters.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "users": {
 "user": [
 {
 "folder": [
 1,
 3
 ],
 "username": "sindre",
 "email": "sindre@activeobjects.no",
 "scrobblingEnabled": "true",
 "adminRole": "false",
 "settingsRole": "true",
 "downloadRole": "true",
 "uploadRole": "false",
 "playlistRole": "true",
 "coverArtRole": "true",
 "commentRole": "true",
 "podcastRole": "true",
 "streamRole": "true",
 "jukeboxRole": "true",
 "shareRole": "false"
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "users": {
 "user": [
 {
 "folder": [
 1,
 3
 ],
 "username": "sindre",
 "email": "sindre@activeobjects.no",
 "scrobblingEnabled": "true",
 "adminRole": "false",
 "settingsRole": "true",
 "downloadRole": "true",
 "uploadRole": "false",
 "playlistRole": "true",
 "coverArtRole": "true",
 "commentRole": "true",
 "podcastRole": "true",
 "streamRole": "true",
 "jukeboxRole": "true",
 "shareRole": "false"
 }
 ]
 }
 }
}

Field	Type	Req.	OpenS.	Details
`users`	`users`	Yes		The users

getVideoInfo

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

http://your-server/rest/getVideoInfo Since 1.14.0

Returns details for a video, including information about available audio tracks, subtitles (captions) and conversions.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			The video ID.

Example

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

Result

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

// TODO

// TODO

Field	Type	Req.	OpenS.	Details
`videoInfo`	`videoInfo`	Yes		The song

getVideos

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

http://your-server/rest/getVideos Since 1.8.0

Returns all video files.

Parameters

Takes no extra parameters.

Example

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

Result

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

// TODO

// TODO

Field	Type	Req.	OpenS.	Details
`videos`	`videos`	Yes		The videos

hls

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

http://your-server/rest/hls.m3u8 Since 1.8.0

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.	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. See`getVideoInfo` for how to get the list of available audio tracks for a video.

Example

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

Result

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”).

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

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

{
 "name": "C",
 "artist": [
 {
 "id": "100000016",
 "name": "CARNÚN",
 "coverArt": "ar-100000016",
 "albumCount": 1
 },
 {
 "id": "100000027",
 "name": "Chi.Otic",
 "coverArt": "ar-100000027",
 "albumCount": 0
 }
 ]
}

{
 "name": "C",
 "artist": [
 {
 "id": "100000016",
 "name": "CARNÚN",
 "coverArt": "ar-100000016",
 "albumCount": 1
 },
 {
 "id": "100000027",
 "name": "Chi.Otic",
 "coverArt": "ar-100000027",
 "albumCount": 0
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`name`	`string`	Yes		Index name
`artist`	Array of `Artist`	No		Artist list

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.

indexes

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

{
 "shortcut": [
 {
 "id": "11",
 "name": "Audio books"
 },
 {
 "id": "10",
 "name": "Podcasts"
 }
 ],
 "index": [
 {
 "artist": [
 {
 "id": "1",
 "name": "ABBA"
 },
 {
 "id": "2",
 "name": "Alanis Morisette"
 },
 {
 "id": "3",
 "name": "Alphaville",
 "starred": "2013-11-02T12:30:00"
 }
 ],
 "name": "A"
 },
 {
 "artist": {
 "name": "Bob Dylan",
 "id": "4"
 },
 "name": "B"
 }
 ],
 "child": [
 {
 "id": "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"
 },
 {
 "id": "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"
 }
 ],
 "lastModified": "237462836472342",
 "ignoredArticles": "The El La Los Las Le Les"
}

<indexes lastModified="237462836472342" ignoredArticles="The El La Los Las Le Les">
 <shortcut id="11" name="Audio books"/>
 <shortcut id="10" name="Podcasts"/>
 <index name="A">
 <artist id="1" name="ABBA"/>
 <artist id="2" name="Alanis Morisette"/>
 <artist id="3" name="Alphaville" starred="2013-11-02T12:30:00"/>
 </index>
 <index name="B">
 <artist name="Bob Dylan" id="4"/>
 </index>
 <child id="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"/>
 <child id="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>

{
 "shortcut": [
 {
 "id": "11",
 "name": "Audio books"
 },
 {
 "id": "10",
 "name": "Podcasts"
 }
 ],
 "index": [
 {
 "artist": [
 {
 "id": "1",
 "name": "ABBA"
 },
 {
 "id": "2",
 "name": "Alanis Morisette"
 },
 {
 "id": "3",
 "name": "Alphaville",
 "starred": "2013-11-02T12:30:00"
 }
 ],
 "name": "A"
 },
 {
 "artist": {
 "name": "Bob Dylan",
 "id": "4"
 },
 "name": "B"
 }
 ],
 "child": [
 {
 "id": "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"
 },
 {
 "id": "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"
 }
 ],
 "lastModified": "237462836472342",
 "ignoredArticles": "The El La Los Las Le Les"
}

<indexes lastModified="237462836472342" ignoredArticles="The El La Los Las Le Les">
 <shortcut id="11" name="Audio books"/>
 <shortcut id="10" name="Podcasts"/>
 <index name="A">
 <artist id="1" name="ABBA"/>
 <artist id="2" name="Alanis Morisette"/>
 <artist id="3" name="Alphaville" starred="2013-11-02T12:30:00"/>
 </index>
 <index name="B">
 <artist name="Bob Dylan" id="4"/>
 </index>
 <child id="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"/>
 <child id="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.	Details
`ignoredArticles`	`string`	Yes	The ignored articles
`lastModified`	`long`	Yes	Last time the index was modified in milliseconds after January 1, 1970 UTC
`shortcut`	Array of `Artist`	No	Shortcut
`child`	Array of `Child`	No	Array of children
`index`	Array of `Index`	No	Indexed artists

IndexID3

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

{
 "name": "C",
 "artist": [
 {
 "id": "100000016",
 "name": "CARNÚN",
 "coverArt": "ar-100000016",
 "albumCount": 1
 },
 {
 "id": "100000027",
 "name": "Chi.Otic",
 "coverArt": "ar-100000027",
 "albumCount": 0
 }
 ]
}

{
 "name": "C",
 "artist": [
 {
 "id": "100000016",
 "name": "CARNÚN",
 "coverArt": "ar-100000016",
 "albumCount": 1
 },
 {
 "id": "100000027",
 "name": "Chi.Otic",
 "coverArt": "ar-100000027",
 "albumCount": 0
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`name`	`string`	Yes		Index name
`artist`	Array of `Artist`	No		Artist list

internetRadioStation

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

{
 "id": "2",
 "name": "HBR1.com - I.D.M. Tranceponder",
 "streamUrl": "http://ubuntu.hbr1.com:19800/trance.ogg",
 "homePageUrl": "http://www.hbr1.com/",
 "coverArt": "ir-2"
}

{
 "id": "2",
 "name": "HBR1.com - I.D.M. Tranceponder",
 "streamUrl": "http://ubuntu.hbr1.com:19800/trance.ogg",
 "homePageUrl": "http://www.hbr1.com/"
}

Field	Type	Req.	OpenS.	Details
`id`	`string`	Yes		The Id
`name`	`string`	Yes		The name
`streamUrl`	`string`	Yes		The radio url
`homePageUrl`	`string`	No		The home page URL for the station.
`coverArt`	`string`	No	Yes	The cover art id.

internetRadioStations

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

{
 "internetRadioStation": [
 {
 "id": "1",
 "name": "HBR1.com - Dream Factory",
 "streamUrl": "http://ubuntu.hbr1.com:19800/ambient.aac",
 "homePageUrl": "http://www.hbr1.com/",
 "coverArt": "ir-1"
 },
 {
 "id": "2",
 "name": "HBR1.com - I.D.M. Tranceponder",
 "streamUrl": "http://ubuntu.hbr1.com:19800/trance.ogg",
 "homePageUrl": "http://www.hbr1.com/",
 "coverArt": "ir-2"
 },
 {
 "id": "3",
 "name": "4ZZZ Community Radio",
 "streamUrl": "https://stream.4zzz.org.au:9200/4zzz",
 "homePageUrl": "https://4zzzfm.org.au",
 "coverArt": "ir-3"
 }
 ]
}

{
 "internetRadioStation": [
 {
 "id": "1",
 "name": "HBR1.com - Dream Factory",
 "streamUrl": "http://ubuntu.hbr1.com:19800/ambient.aac",
 "homePageUrl": "http://www.hbr1.com/"
 },
 {
 "id": "2",
 "name": "HBR1.com - I.D.M. Tranceponder",
 "streamUrl": "http://ubuntu.hbr1.com:19800/trance.ogg",
 "homePageUrl": "http://www.hbr1.com/"
 },
 {
 "id": "3",
 "name": "4ZZZ Community Radio",
 "streamUrl": "https://stream.4zzz.org.au:9200/4zzz",
 "homePageUrl": "https://4zzzfm.org.au"
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`internetRadioStation`	Array of `internetRadioStation`	No		A list of internetRadioStation

ItemDate

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

{
 "year": 2020,
 "month": 1,
 "day": 1
}

 <!-- XML name is the name of the property on the parent object-->
 <originalReleaseDate year="2020" month="1" day="1"/>

Does not exist.

Field	Type	Req.	OpenS.	Details
`year`	`integer`	No	Yes	The year
`month`	`integer`	No	Yes	The month (1-12)
`day`	`integer`	No	Yes	The day (1-31)

OpenSubsonic

This is a new OpenSubsonic response type.

ItemGenre

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

{
 "name": "Noise"
}

Does not exist.

Field	Type	Req.	OpenS.	Details
`name`	`string`	Yes	Yes	Genre name

OpenSubsonic

This is a new OpenSubsonic response type.

jukeboxControl

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

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

Example

http://your-server/rest/jukeboxControl.view?action=get&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

A subsonic-response element with a nested :

jukeboxPlaylist

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

{
 "currentIndex": 7,
 "playing": true,
 "gain": 0.9,
 "position": 67,
 "entry": [
 {
 "id": "300000116",
 "parent": "200000021",
 "title": "Can I Help U?",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000116",
 "duration": 103,
 "bitRate": 216,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 1,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 2811819,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
 }
 ]
}

{
 "currentIndex": 7,
 "playing": true,
 "gain": 0.9,
 "position": 67,
 "entry": [
 {
 "id": "300000116",
 "parent": "200000021",
 "title": "Can I Help U?",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000116",
 "duration": 103,
 "bitRate": 216,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 1,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 2811819,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
 }
 ]
}

Field	Type	Req.	Details
`currentIndex`	`int`	Yes	The current index of the song being played
`playing`	`boolean`	Yes	Whether the queue is currently playing
`gain`	`float`	Yes	Volume, in a range of [0.0, 1.0]
`position`	`int`	No	The current position of the track in seconds
`entry`	Array of `Child`	No	The songs currently enqueued in the jukebox

jukeboxStatus

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

{
 "currentIndex": 7,
 "playing": true,
 "gain": 0.9,
 "position": 67
}

{
 "currentIndex": 7,
 "playing": true,
 "gain": 0.9,
 "position": 67
}

Field	Type	Req.	Details
`currentIndex`	`int`	Yes	The current index of the song being played
`playing`	`boolean`	Yes	Whether the queue is currently playing
`gain`	`float`	Yes	Volume, in a range of [0.0, 1.0]
`position`	`int`	No	The current position of the track in seconds

license

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

{
 "valid": true,
 "email": "demo@demo.org",
 "licenseExpires": "2017-04-11T10:42:50.842Z",
 "trialExpires": "2017-04-11T10:42:50.842Z"
}

{
 "valid": true,
 "email": "demo@demo.org",
 "licenseExpires": "2017-04-11T10:42:50.842Z",
 "trialExpires": "2017-04-11T10:42:50.842Z"
}

Field	Type	Req.	Details
`valid`	`boolean`	Yes	The status of the license
`email`	`string`	No	User email
`licenseExpires`	`string`	No	End of license date. [ISO 8601]
`trialExpires`	`string`	No	End of trial date. [ISO 8601]

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.

line

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

{
 "start": 0,
 "value": "It's bugging me"
}

<line start="0">It's bugging me</line>

Does not exist.

Field	Type	Req.	OpenS.	Details
`value`	`string`	Yes	Yes	The actual text of this line
`start`	`number`	No	Yes	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.

lyrics

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

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

Field	Type	Req.	Details
`value`	`string`	Yes	The lyrics
`artist`	`string`	No	The artist name
`title`	`string`	No	The song title

lyricsList

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

{
 "structuredLyrics": [
 {
 "displayArtist": "Muse",
 "displayTitle": "Hysteria",
 "lang": "eng",
 "offset": -100,
 "synced": true,
 "line": [
 {
 "start": 0,
 "value": "It's bugging me"
 },
 {
 "start": 2000,
 "value": "Grating me"
 },
 {
 "start": 3001,
 "value": "And twisting me around..."
 }
 ]
 },
 {
 "displayArtist": "Muse",
 "displayTitle": "Hysteria",
 "lang": "xxx",
 "offset": 100,
 "synced": false,
 "line": [
 {
 "value": "It's bugging me"
 },
 {
 "value": "Grating me"
 },
 {
 "value": "And twisting me around..."
 }
 ]
 }
 ]
}

<lyricsList>
 <structuredLyrics displayArtist="Muse" displayTitle="Hysteria" lang="eng" offset="-100" synced="true">
 <line start="0">It's bugging me</line>
 <line start="2000">Grating me</line>
 <line start="3001">And twisting me around...</line>
 </structuredLyrics>
 <structuredLyrics displayArtist="Muse" displayTitle="Hysteria" lang="xxx" offset="100" synced="false">
 <line>It's bugging me</line>
 <line>Grating me</line>
 <line>And twisting me around...</line>
 </structuredLyrics>
</lyricsList>

Does not exist.

Field	Type	Req.	OpenS.	Details
`structuredLyrics`	Array of `structuredLyrics`	No	Yes	Structured lyrics. There can be multiple lyrics of the same type with the same language

OpenSubsonic

This is a new OpenSubsonic response type.

Movement

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

{
 "name": "Andante con moto",
 "number": 2,
 "count": 4
}

Does not exist.

Field	Type	Req.	OpenS.	Details
`name`	`string`	Yes	Yes	The movement name.
`number`	`int`	No	Yes	The movement number.
`count`	`int`	No	Yes	The total number of movements.

OpenSubsonic

This is a new OpenSubsonic response type.

musicFolder

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

{
 "id": 4,
 "name": "upload"
}

{
 "id": 4,
 "name": "upload"
}

Field	Type	Req.	OpenS.	Details
`id`	`int`	Yes		The id
`name`	`string`	No		The folder name

musicFolders

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

{
 "musicFolder": [
 {
 "id": 1,
 "name": "music"
 },
 {
 "id": 4,
 "name": "upload"
 }
 ]
}

{
 "musicFolder": [
 {
 "id": 1,
 "name": "music"
 },
 {
 "id": 4,
 "name": "upload"
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`musicFolder`	Array of `musicFolder`	No		The folders

NewestPodcasts

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

{
 "episode": [
 {
 "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"
 }
 ]
}

{
 "episode": [
 {
 "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"
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`episode`	An array of `PodcastEpisode`	No

nowPlaying

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

{
 "entry": [
 {
 "id": "300115266",
 "parent": "200147046",
 "title": "Take the Home",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200147046",
 "album": "How I Learned to Love Our Robot Overlords",
 "artistId": "100002619",
 "artist": "Raggedy Angry",
 "coverArt": "300115266",
 "duration": 227,
 "bitRate": 222,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 3,
 "track": 7,
 "year": 2010,
 "genre": "Industrial",
 "size": 6341039,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Raggedy Angry/(2010) How I Learned to Love Our Robot Overlords/1-07 - Take the Home.mp3",
 "username": "user",
 "minutesAgo": 0,
 "playerId": 0,
 "state": "playing",
 "positionMs": 120000,
 "playbackRate": 1.0,
 }
 ]
}

{
 "entry": [
 {
 "id": "300115266",
 "parent": "200147046",
 "title": "Take the Home",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200147046",
 "album": "How I Learned to Love Our Robot Overlords",
 "artistId": "100002619",
 "artist": "Raggedy Angry",
 "coverArt": "300115266",
 "duration": 227,
 "bitRate": 222,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 3,
 "track": 7,
 "year": 2010,
 "genre": "Industrial",
 "size": 6341039,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Raggedy Angry/(2010) How I Learned to Love Our Robot Overlords/1-07 - Take the Home.mp3",
 "username": "user",
 "minutesAgo": 0,
 "playerId": 0
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`entry`	Array of `NowPlayingEntry`	Yes		A list of NowPlayingEntry

OpenSubsonic

When the server supports extension playbackReport, each entry can include timeline fields (state, positionMs, playbackRate).

NowPlayingEntry

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

{
 "id": "300115266",
 "parent": "200147046",
 "title": "Take the Home",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200147046",
 "album": "How I Learned to Love Our Robot Overlords",
 "artistId": "100002619",
 "artist": "Raggedy Angry",
 "coverArt": "300115266",
 "duration": 227,
 "bitRate": 222,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 3,
 "track": 7,
 "year": 2010,
 "genre": "Industrial",
 "size": 6341039,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Raggedy Angry/(2010) How I Learned to Love Our Robot Overlords/1-07 - Take the Home.mp3",
 "username": "user",
 "minutesAgo": 0,
 "playerId": 0,
 "state": "playing",
 "positionMs": 120000,
 "playbackRate": 1.0,
}

{
 "id": "300115266",
 "parent": "200147046",
 "title": "Take the Home",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200147046",
 "album": "How I Learned to Love Our Robot Overlords",
 "artistId": "100002619",
 "artist": "Raggedy Angry",
 "coverArt": "300115266",
 "duration": 227,
 "bitRate": 222,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 3,
 "track": 7,
 "year": 2010,
 "genre": "Industrial",
 "size": 6341039,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Raggedy Angry/(2010) How I Learned to Love Our Robot Overlords/1-07 - Take the Home.mp3",
 "username": "user",
 "minutesAgo": 0,
 "playerId": 0
}

OpenSubsonic

NowPlayingEntry extends Child (See Child documentation for the corresponding fields)

Field	Type	Req.	OpenS.	Details
`username`	`string`	Yes		The username
`minutesAgo`	`integer`	Yes		Last update
`playerId`	`integer`	Yes		Player Id
`playerName`	`string`	No		Player name
`state`	`string`	No	Yes	Playback state: `starting`, `playing`, `paused`, or `stopped`
`positionMs`	`integer`	No	Yes	Current playback position in milliseconds (Calculated by the server from the last playbackReport call received)
`playbackRate`	`number`	No	Yes	Playback speed multiplier

OpenSubsonic

When the server supports extension playbackReport, these fields can be returned:

OpenSubsonicExtension

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

{
 "name": "template",
 "versions": [
 1,
 2
 ]
}

Does not exist.

Field	Type	Req.	OpenS.	Details
`name`	`String`	Yes	Yes	The name of the extension.
`versions`	Array of `int`	Yes	Yes	The list of supported versions of the this extension.

OpenSubsonic

This is a new response type.

ping

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

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

Test connectivity with the server.

Parameters

Takes no extra parameters.

Example

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

Result

An empty subsonic-response element on success.

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1"
 }
}

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.

playlist

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

{
 "id": "800000075",
 "name": "testcreate",
 "owner": "user",
 "public": true,
 "created": "2023-03-16T03:18:41+00:00",
 "changed": "2023-03-16T03:18:41+00:00",
 "songCount": 1,
 "duration": 304,
 "readonly": true,
 "validUntil": "2023-03-23T03:18:41+00:00"
}

{
 "id": "800000075",
 "name": "testcreate",
 "owner": "user",
 "public": true,
 "created": "2023-03-16T03:18:41+00:00",
 "changed": "2023-03-16T03:18:41+00:00",
 "songCount": 1,
 "duration": 304
}

Field	Type	Req.	OpenS.	Details
`id`	`string`	Yes		Id of the playlist
`name`	`string`	Yes		Name of the playlist
`comment`	`string`	No		A commnet
`owner`	`string`	No		Owner of the playlist
`public`	`boolean`	No		Is the playlist public
`songCount`	`int`	Yes		number of songs
`duration`	`int`	Yes		Playlist duration in seconds
`created`	`string`	Yes		Creation date [ISO 8601]
`changed`	`string`	Yes		Last changed date [ISO 8601]
`coverArt`	`string`	No		A cover Art Id
`allowedUser`	Array of `string`	No		A list of allowed usernames
`readonly`	`boolean`	No	Yes	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:

playlists

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

{
 "playlist": [
 {
 "id": "800000003",
 "name": "random - admin - private (admin)",
 "owner": "admin",
 "public": false,
 "created": "2021-02-23T04:35:38+00:00",
 "changed": "2021-02-23T04:35:38+00:00",
 "songCount": 43,
 "duration": 17875
 },
 {
 "id": "800000002",
 "name": "random - admin - public (admin)",
 "owner": "admin",
 "public": true,
 "created": "2021-02-23T04:34:56+00:00",
 "changed": "2021-02-23T04:34:56+00:00",
 "songCount": 43,
 "duration": 17786
 }
 ]
}

{
 "playlist": [
 {
 "id": "800000003",
 "name": "random - admin - private (admin)",
 "owner": "admin",
 "public": false,
 "created": "2021-02-23T04:35:38+00:00",
 "changed": "2021-02-23T04:35:38+00:00",
 "songCount": 43,
 "duration": 17875
 },
 {
 "id": "800000002",
 "name": "random - admin - public (admin)",
 "owner": "admin",
 "public": true,
 "created": "2021-02-23T04:34:56+00:00",
 "changed": "2021-02-23T04:34:56+00:00",
 "songCount": 43,
 "duration": 17786
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`playlist`	Array of `playlist`	No		A list of playlist

playlistWithSongs

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

{
 "id": "800000075",
 "name": "testcreate",
 "owner": "user",
 "public": true,
 "created": "2023-03-16T03:18:41+00:00",
 "changed": "2023-03-16T03:18:41+00:00",
 "songCount": 1,
 "duration": 304,
 "readonly": true,
 "validUntil": "2023-03-23T03:18:41+00:00",
 "entry": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 }
 ]
}

{
 "id": "800000075",
 "name": "testcreate",
 "owner": "user",
 "public": true,
 "created": "2023-03-16T03:18:41+00:00",
 "changed": "2023-03-16T03:18:41+00:00",
 "songCount": 1,
 "duration": 304,
 "entry": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`id`	`string`	Yes		Id of the playlist
`name`	`string`	Yes		Name of the playlist
`comment`	`string`	No		A comment
`owner`	`string`	No		Owner of the playlist
`public`	`boolean`	No		Is the playlist public
`songCount`	`int`	Yes		number of songs
`duration`	`int`	Yes		Playlist duration in seconds
`created`	`string`	Yes		Creation date [ISO 8601]
`changed`	`string`	Yes		Last changed date [ISO 8601]
`coverArt`	`string`	No		A cover Art Id
`allowedUser`	Array of `string`	No		A list of allowed usernames
`readonly`	`boolean`	No	Yes	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]
`entry`	Array of `Child`	No		The list of songs

OpenSubsonic

New fields are added:

PlayQueue

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

{
 "current": "1234",
 "position": 1000,
 "username": "user",
 "changed": "2023-03-10T02:19:35.784818075Z",
 "changedBy": "example client",
 "entry": [
 {
 "id": "1234",
 "parent": "200000021",
 "title": "Can I Help U?",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "1234",
 "duration": 103,
 "bitRate": 216,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 1,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 2811819,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
 }
 ]
}

{
 "current": "1234",
 "position": 1000,
 "username": "user",
 "changed": "2023-03-10T02:19:35.784818075Z",
 "changedBy": "example client",
 "entry": [
 {
 "id": "1234",
 "parent": "200000021",
 "title": "Can I Help U?",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "1234",
 "duration": 103,
 "bitRate": 216,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 1,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 2811819,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
 }
 ]
}

OpenSubsonic

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.	Details
`current`	`string`	No*	ID of currently playing track
`position`	`long`	No	Position in milliseconds of currently playing track
`username`	`string`	Yes	The user this queue belongs to
`changed`	`string`	Yes	Date modified [ISO 8601]
`changedBy`	`string`	Yes	Name of client app
`entry`	Array of `Child`	No	The list of songs in the queue

OpenSubsonic

* If entry exists and is non-empty, OpenSubsonic servers must ensure that current exists and is a valid id in the list of songs.

PlayQueueByIndex

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

{
 "currentIndex": 0,
 "position": 1000,
 "username": "user",
 "changed": "2023-03-10T02:19:35.784818075Z",
 "changedBy": "example client",
 "entry": [
 {
 "id": "1234",
 "parent": "200000021",
 "title": "Can I Help U?",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "1234",
 "duration": 103,
 "bitRate": 216,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 1,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 2811819,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
 }
 ]
}

Does not exist.

Field	Type	Req.	Details
`currentIndex`	`long`	No*	The 0-based index of the current playing track
`position`	`long`	No	Position in milliseconds of currently playing track
`username`	`string`	Yes	The user this queue belongs to
`changed`	`string`	Yes	Date modified [ISO 8601]
`changedBy`	`string`	Yes	Name of client app
`entry`	Array of `Child`	No	The list of songs in the queue

OpenSubsonic

This is a new OpenSubsonic response type.

PodcastChannel

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

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

Field	Type	Req.	Details
`id`	`string`	Yes	The channel ID
`url`	`string`	Yes	Podcast channel URL
`title`	`string`	No	The channel title
`description`	`string`	No	The channel description
`coverArt`	`string`	No	ID used for retrieving cover art
`originalImageUrl`	`string`	No	URL for original image of podcast channel
`status`	PodcastStatus	Yes	Channel status
`errorMessage`	`string`	No	An error message
`episode`	An array of PodcastEpisode	No	Podcast episodes with this channel

PodcastEpisode

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

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

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

OpenSubsonic

PodcastEntry extends Child (See Child documentation for the corresponding fields)

Field	Type	Req.	Details
`streamId`	`string`	No	ID used for streaming podcast
`channelId`	`string`	Yes	ID of the podcast channel
`description`	`string`	No	Episode description
`status`	PodcastStatus	Yes	Podcast status
`publishDate`	`string`	No	Date the episode was published [ISO 8601]

podcasts

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

{
 "channel": [
 {
 "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"
 },
 {
 "id": "3",
 "url": "https://example.com/404",
 "status": "error",
 "errorMessage": "Not Found"
 }
 ]
}

{
 "channel": [
 {
 "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"
 },
 {
 "id": "3",
 "url": "https://example.com/404",
 "status": "error",
 "errorMessage": "notFound"
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`channel`	An array of PodcastChannel	No		Podcast channel(s)

PodcastStatus

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

A podcast status is a string type taking one of the following values:

new
downloading
completed
error
deleted
skipped

RecordLabel

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

{
 "name": "Sony"
}

Does not exist.

Field	Type	Req.	OpenS.	Details
`name`	`string`	Yes	Yes	The record label name.

OpenSubsonic

This is a new OpenSubsonic response type.

refreshPodcasts

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

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).

Parameters

Takes no extra parameters.

Example

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

Result

An empty subsonic-response element on success.

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1"
 }
}

ReplayGain

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

{
 "trackGain": 0.1,
 "albumGain": 1.1,
 "trackPeak": 9.2,
 "albumPeak": 0,
 "baseGain": 0,
 "fallbackGain": -8.1
}

Does not exist.

Field	Type	Req.	OpenS.	Details
`trackGain`	`number`	No	Yes	The track replay gain value. (In Db)
`albumGain`	`number`	No	Yes	The album replay gain value. (In Db)
`trackPeak`	`number`	No	Yes	The track peak value. (Must be positive)
`albumPeak`	`number`	No	Yes	The album peak value. (Must be positive)
`baseGain`	`number`	No	Yes	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)

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.

savePlayQueue

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

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

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

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

scanStatus

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

{
 "scanning": false,
 "count": 0
}

{
 "scanning": false,
 "count": 0
}

Field	Type	Req.	OpenS.	Details
`scanning`	`boolean`	Yes		The status of the scan
`count`	`int`	No		Scanned item count

scrobble

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

http://your-server/rest/scrobble Since 1.5.0

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.

search

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

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

Deprecated since 1.4.0, use search2 instead.

Returns a listing of files matching the given search criteria. Supports paging through the result.

Parameters

Parameter	Req.	Default	Comment
`artist`	No		Artist to search for.
`album`	No		Album to search for.
`title`	No		Song title to search for.
`any`	No		Searches all fields.
`count`	No	20	Maximum number of results to return.
`offset`	No	0	Search result offset. Used for paging.
`newerThan`	No		Only return matches that are newer than this. Given as milliseconds since 1970.

Example

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

Result

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

Search Results

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

search2

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

http://your-server/rest/search2 Since 1.4.0

Returns albums, artists and songs matching the given search criteria. Supports paging through the result.

Parameters

Parameter	Req.	Default	Comment
`query`	Yes		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 the music folder with the given ID. See `getMusicFolders`.

Example

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

Result

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

search3

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

http://your-server/rest/search3 Since 1.8.0

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`.

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.

Example

http://your-server/rest/search3.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json&query=""&artistCount=1&albumCount=1&songCount=1

Result

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

searchResult

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

// TODO

// TODO

Field	Type	Req.	OpenS.	Details

searchResult2

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

{
 "artist": [
 {
 "id": "100000002",
 "name": "Synthetic",
 "coverArt": "ar-100000002",
 "starred": "2021-02-22T05:54:18Z"
 }
 ],
 "album": [
 {
 "id": "200000021",
 "parent": "100000036",
 "album": "Forget and Remember",
 "title": "Forget and Remember",
 "name": "Forget and Remember",
 "isDir": true,
 "coverArt": "al-200000021",
 "songCount": 20,
 "created": "2021-07-22T02:09:31+00:00",
 "duration": 4248,
 "playCount": 0,
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "year": 2005,
 "genre": "Hip-Hop"
 }
 ],
 "song": [
 {
 "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
 }
 ]
}

{
 "artist": [
 {
 "id": "100000002",
 "name": "Synthetic",
 "coverArt": "ar-100000002",
 "starred": "2021-02-22T05:54:18Z"
 }
 ],
 "album": [
 {
 "id": "200000021",
 "parent": "100000036",
 "album": "Forget and Remember",
 "title": "Forget and Remember",
 "name": "Forget and Remember",
 "isDir": true,
 "coverArt": "al-200000021",
 "songCount": 20,
 "created": "2021-07-22T02:09:31+00:00",
 "duration": 4248,
 "playCount": 0,
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "year": 2005,
 "genre": "Hip-Hop"
 }
 ],
 "song": [
 {
 "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.	Details
`artist`	Array of `Artist`	No	Starred artists
`album`	Array of `Child`	No	Starred albums
`song`	Array of `Child`	No	Starred songs

searchResult3

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

{
 "artist": [
 {
 "id": "37ec820ca7193e17040c98f7da7c4b51",
 "name": "2 Mello",
 "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
 "albumCount": 1,
 "userRating": 5,
 "artistImageUrl": "https://demo.org/image.jpg"
 }
 ],
 "album": [
 {
 "id": "ad0f112b6dcf83de5e9cae85d07f0d35",
 "name": "8-bit lagerfeuer",
 "artist": "pornophonique",
 "year": 2007,
 "coverArt": "al-ad0f112b6dcf83de5e9cae85d07f0d35_640a93a8",
 "starred": "2023-03-22T01:51:06Z",
 "duration": 1954,
 "playCount": 97,
 "played": "2023-03-28T00:45:13Z",
 "created": "2023-03-10T02:19:35.784818075Z",
 "artistId": "91c3901ac465b9efc439e4be4270c2b6",
 "userRating": 4,
 "songCount": 8,
 }
 ],
 "song": [
 {
 "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,
 "played": "2023-03-26T22:27:46Z",
 "discNumber": 1,
 "created": "2023-03-14T17:51:22.112827504Z",
 "albumId": "e8a0685e3f3ec6f251649af2b58b8617",
 "artistId": "97e0398acf63f9fb930d7d4ce209a52b",
 "type": "music",
 "isVideo": false
 }
 ]
}

{
 "artist": [
 {
 "id": "37ec820ca7193e17040c98f7da7c4b51",
 "name": "2 Mello",
 "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
 "albumCount": 1,
 "userRating": 5,
 "artistImageUrl": "https://demo.org/image.jpg"
 }
 ],
 "album": [
 {
 "id": "ad0f112b6dcf83de5e9cae85d07f0d35",
 "name": "8-bit lagerfeuer",
 "artist": "pornophonique",
 "year": 2007,
 "coverArt": "al-ad0f112b6dcf83de5e9cae85d07f0d35_640a93a8",
 "starred": "2023-03-22T01:51:06Z",
 "duration": 1954,
 "playCount": 97,
 "created": "2023-03-10T02:19:35.784818075Z",
 "artistId": "91c3901ac465b9efc439e4be4270c2b6",
 "songCount": 8,
 }
 ],
 "song": [
 {
 "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,
 "played": "2023-03-26T22:27:46Z",
 "discNumber": 1,
 "created": "2023-03-14T17:51:22.112827504Z",
 "albumId": "e8a0685e3f3ec6f251649af2b58b8617",
 "artistId": "97e0398acf63f9fb930d7d4ce209a52b",
 "type": "music",
 "isVideo": false
 }
 ]
}

Field	Type	Req.	Details
`artist`	Array of `ArtistID3`	No	Matching artists
`album`	Array of `AlbumID3`	No	Matching albums
`song`	Array of `Child`	No	Matching songs

setRating

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

http://your-server/rest/setRating Since 1.6.0

Sets the rating for a music file.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`id`	Yes			A string which uniquely identifies the file (song) or folder (album/artist) to rate.
`rating`	Yes			The rating between 1 and 5 (inclusive), or 0 to remove the rating.

Example

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

Result

An empty subsonic-response element on success.

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1"
 }
}

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

{
 "id": "12",
 "url": "http://localhost:8989/share.php?id=12&secret=fXlKyEv3",
 "description": "Forget and Remember (Comfort Fit)",
 "username": "user",
 "created": "2023-03-16T04:13:09+00:00",
 "visitCount": 0,
 "entry": [
 {
 "id": "300000116",
 "parent": "200000021",
 "title": "Can I Help U?",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000116",
 "duration": 103,
 "bitRate": 216,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 1,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 2811819,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
 },
 {
 "id": "300000121",
 "parent": "200000021",
 "title": "Planetary Picknick",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000121",
 "duration": 358,
 "bitRate": 238,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 2,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 10715592,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/2 - Planetary Picknick.mp3"
 }
 ]
}

{
 "id": "12",
 "url": "http://localhost:8989/share.php?id=12&secret=fXlKyEv3",
 "description": "Forget and Remember (Comfort Fit)",
 "username": "user",
 "created": "2023-03-16T04:13:09+00:00",
 "visitCount": 0,
 "entry": [
 {
 "id": "300000116",
 "parent": "200000021",
 "title": "Can I Help U?",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000116",
 "duration": 103,
 "bitRate": 216,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 1,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 2811819,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
 },
 {
 "id": "300000121",
 "parent": "200000021",
 "title": "Planetary Picknick",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000121",
 "duration": 358,
 "bitRate": 238,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 2,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 10715592,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/2 - Planetary Picknick.mp3"
 }
 ]
}

Field	Type	Req.	Details
`id`	`string`	Yes	The share Id
`url`	`string`	Yes	The share url
`description`	`string`	No	A description
`username`	`string`	Yes	The username
`created`	`string`	Yes	Creation date [ISO 8601]
`expires`	`string`	No	Share expiration [ISO 8601]
`lastVisited`	`string`	No	Last visit [ISO 8601]
`visitCount`	`int`	Yes	Visit count
`entry`	Array of `Child`	No	A list of share

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

{
 "share": [
 {
 "id": "12",
 "url": "http://localhost:8989/share.php?id=12&secret=fXlKyEv3",
 "description": "Forget and Remember (Comfort Fit)",
 "username": "user",
 "created": "2023-03-16T04:13:09+00:00",
 "visitCount": 0,
 "entry": [
 {
 "id": "300000116",
 "parent": "200000021",
 "title": "Can I Help U?",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000116",
 "duration": 103,
 "bitRate": 216,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 1,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 2811819,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
 },
 {
 "id": "300000121",
 "parent": "200000021",
 "title": "Planetary Picknick",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000121",
 "duration": 358,
 "bitRate": 238,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 2,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 10715592,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/2 - Planetary Picknick.mp3"
 }
 ]
 }
 ]
}

{
 "share": [
 {
 "id": "12",
 "url": "http://localhost:8989/share.php?id=12&secret=fXlKyEv3",
 "description": "Forget and Remember (Comfort Fit)",
 "username": "user",
 "created": "2023-03-16T04:13:09+00:00",
 "visitCount": 0,
 "entry": [
 {
 "id": "300000116",
 "parent": "200000021",
 "title": "Can I Help U?",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000116",
 "duration": 103,
 "bitRate": 216,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 1,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 2811819,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/1 - Can I Help U?.mp3"
 },
 {
 "id": "300000121",
 "parent": "200000021",
 "title": "Planetary Picknick",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000021",
 "album": "Forget and Remember",
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "coverArt": "300000121",
 "duration": 358,
 "bitRate": 238,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 2,
 "year": 2005,
 "genre": "Hip-Hop",
 "size": 10715592,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "user/Comfort Fit/Forget And Remember/2 - Planetary Picknick.mp3"
 }
 ]
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`share`	Array of `share`	No		A list of share

similarSongs

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

{
 "song": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 },
 {
 "id": "300000055",
 "parent": "200000002",
 "title": "Red&GreenSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000055",
 "duration": 400,
 "bitRate": 64,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 5,
 "year": 2007,
 "genre": "Electronic",
 "size": 3209886,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
 }
 ]
}

{
 "song": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 },
 {
 "id": "300000055",
 "parent": "200000002",
 "title": "Red&GreenSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000055",
 "duration": 400,
 "bitRate": 64,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 5,
 "year": 2007,
 "genre": "Electronic",
 "size": 3209886,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`song`	Array of `Child`	No		List of songs

similarSongs2

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

{
 "song": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 },
 {
 "id": "300000055",
 "parent": "200000002",
 "title": "Red&GreenSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000055",
 "duration": 400,
 "bitRate": 64,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 5,
 "year": 2007,
 "genre": "Electronic",
 "size": 3209886,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
 }
 ]
}

{
 "song": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 },
 {
 "id": "300000055",
 "parent": "200000002",
 "title": "Red&GreenSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000055",
 "duration": 400,
 "bitRate": 64,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 5,
 "year": 2007,
 "genre": "Electronic",
 "size": 3209886,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`song`	Array of `Child`	No		List of songs

song

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

// TODO

// TODO

Field	Type	Req.	OpenS.	Details

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

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.

songs

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

{
 "song": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 },
 {
 "id": "300000055",
 "parent": "200000002",
 "title": "Red&GreenSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000055",
 "duration": 400,
 "bitRate": 64,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 5,
 "year": 2007,
 "genre": "Electronic",
 "size": 3209886,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
 }
 ]
}

{
 "song": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 },
 {
 "id": "300000055",
 "parent": "200000002",
 "title": "Red&GreenSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000055",
 "duration": 400,
 "bitRate": 64,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 5,
 "year": 2007,
 "genre": "Electronic",
 "size": 3209886,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`song`	Array of `Child`	No		List of songs

Sonic similarity

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

OpenSubsonic version: 1

OpenSubsonic extension name: sonicSimilarity (As returned by getOpenSubsonicExtensions)

Version 1

This extension adds two new audio-similarity endpoints:

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

sonicMatch

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

A sonicMatch is a wrapper object with:

entry as a Child object
similarity (normalized similarity value)

{
 "entry": {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP/04-Synthetic_-_BrownSmoke.wma"
 },
 "similarity": 1.0
}

Does not exist.

Field	Type	Req.	OpenS.	Details
`entry`	`Child`	Yes		The child metadata object (id, parent, title, etc.).
`similarity`	`number`	Yes		The normalized similarity score (1.0 = most similar, 0.0 = least similar). For `getSonicSimilarTracks`, relative to the query song. For `findSonicPath`, relative to the starting song. Returns -1 when similarity is not supported by the server.

sonicSimilarTracksResult

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

{
 "sonicMatch": [
 {
 "entry": {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP/04-Synthetic_-_BrownSmoke.wma"
 },
 "similarity": 1.0
 },
 {
 "entry": {
 "id": "300000055",
 "parent": "200000002",
 "title": "Red&GreenSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000055",
 "duration": 400,
 "bitRate": 64,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 5,
 "year": 2007,
 "genre": "Electronic",
 "size": 3209886,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP/05-Synthetic_-_RedGreenSmoke.mp3"
 },
 "similarity": 0.88
 }
 ]
}

Does not exist.

Field	Type	Req.	OpenS.	Details
`sonicMatch`	Array of `sonicMatch`	No		A list of similar songs ordered by similarity.

star

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

http://your-server/rest/star Since 1.8.0

Attaches a star to a song, album or artist.

Parameters

Parameter	Req.	Comment
`id`	No	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.

Example

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

Result

An empty subsonic-response element on success.

starred

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

{
 "artist": [
 {
 "id": "100000002",
 "name": "Synthetic",
 "coverArt": "ar-100000002",
 "starred": "2021-02-22T05:54:18Z"
 }
 ],
 "album": [
 {
 "id": "200000021",
 "parent": "100000036",
 "album": "Forget and Remember",
 "title": "Forget and Remember",
 "name": "Forget and Remember",
 "isDir": true,
 "coverArt": "al-200000021",
 "songCount": 20,
 "created": "2021-07-22T02:09:31+00:00",
 "duration": 4248,
 "playCount": 0,
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "year": 2005,
 "genre": "Hip-Hop"
 }
 ],
 "song": [
 {
 "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
 }
 ]
}

{
 "artist": [
 {
 "id": "100000002",
 "name": "Synthetic",
 "coverArt": "ar-100000002",
 "starred": "2021-02-22T05:54:18Z"
 }
 ],
 "album": [
 {
 "id": "200000021",
 "parent": "100000036",
 "album": "Forget and Remember",
 "title": "Forget and Remember",
 "name": "Forget and Remember",
 "isDir": true,
 "coverArt": "al-200000021",
 "songCount": 20,
 "created": "2021-07-22T02:09:31+00:00",
 "duration": 4248,
 "playCount": 0,
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "year": 2005,
 "genre": "Hip-Hop"
 }
 ],
 "song": [
 {
 "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.	Details
`artist`	Array of `Artist`	No	Starred artists
`album`	Array of `Child`	No	Starred albums
`song`	Array of `Child`	No	Starred songs

starred2

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

{
 "artist": [
 {
 "id": "37ec820ca7193e17040c98f7da7c4b51",
 "name": "2 Mello",
 "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
 "albumCount": 1,
 "userRating": 5,
 "artistImageUrl": "https://demo.org/image.jpg",
 "starred": "2017-04-11T10:42:50.842Z"
 }
 ],
 "album": [
 {
 "id": "ad0f112b6dcf83de5e9cae85d07f0d35",
 "name": "8-bit lagerfeuer",
 "artist": "pornophonique",
 "year": 2007,
 "coverArt": "al-ad0f112b6dcf83de5e9cae85d07f0d35_640a93a8",
 "starred": "2023-03-22T01:51:06Z",
 "duration": 1954,
 "playCount": 97,
 "genre": "Hip-Hop",
 "created": "2023-03-10T02:19:35.784818075Z",
 "artistId": "91c3901ac465b9efc439e4be4270c2b6",
 "songCount": 8
 }
 ],
 "song": [
 {
 "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
 }
 ]
}

{
 "artist": [
 {
 "id": "37ec820ca7193e17040c98f7da7c4b51",
 "name": "2 Mello",
 "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
 "albumCount": 1,
 "userRating": 5,
 "artistImageUrl": "https://demo.org/image.jpg",
 "starred": "2017-04-11T10:42:50.842Z"
 }
 ],
 "album": [
 {
 "id": "ad0f112b6dcf83de5e9cae85d07f0d35",
 "name": "8-bit lagerfeuer",
 "artist": "pornophonique",
 "year": 2007,
 "coverArt": "al-ad0f112b6dcf83de5e9cae85d07f0d35_640a93a8",
 "starred": "2023-03-22T01:51:06Z",
 "duration": 1954,
 "playCount": 97,
 "genre": "Hip-Hop",
 "created": "2023-03-10T02:19:35.784818075Z",
 "artistId": "91c3901ac465b9efc439e4be4270c2b6",
 "songCount": 8
 }
 ],
 "song": [
 {
 "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.	Details
`artist`	Array of `artist`	No	Starred artists
`album`	Array of `Child`	No	Starred albums
`song`	Array of `Child`	No	Starred songs

startScan

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

http://your-server/rest/startScan Since 1.15.0

Initiates a rescan of the media libraries. Takes no extra parameters.

Parameters

Takes no extra parameters.

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true
 "scanStatus": {
 "scanning": true,
 "count": 1
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "scanStatus": {
 "scanning": true,
 "count": 0
 }
 }
}

Field	Type	Req.	OpenS.	Details
`scanStatus`	`scanStatus`	Yes		The status of the scan

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.

structuredLyrics

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

Version 1 (line-level)

{
 "displayArtist": "Muse",
 "displayTitle": "Hysteria",
 "lang": "xxx",
 "offset": -100,
 "synced": true,
 "line": [
 {
 "start": 0,
 "value": "It's bugging me"
 },
 {
 "start": 2000,
 "value": "Grating me"
 },
 {
 "start": 3001,
 "value": "And twisting me around..."
 }
 ]
}

<structuredLyrics displayArtist="Muse" displayTitle="Hysteria" lang="xxx" offset="-100" synced="true">
 <line start="0">It's bugging me</line>
 <line start="2000">Grating me</line>
 <line start="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, and optional agents arrays for reusable agent attribution.

subsonic-response

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1"
 }
}

Field	Type	Req.	OpenS.	Details
`status`	`string`	Yes		The command result. `ok` or `failed`
`version`	`string`	Yes		The server supported Subsonic API version.
`type`	`string`	Yes	Yes	The server actual name. [Ex: `Navidrome` or `gonic`]
`serverVersion`	`string`	Yes	Yes	The server actual version. [Ex: `1.2.3 (beta)`]
`openSubsonic`	`boolean`	Yes	Yes	Must return true if the server support OpenSubsonic API v1
`error`	`error`	No		The error details when `status` is `failed`

OpenSubsonic

New fields are added:

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

tokenInfo

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

{
 "tokenInfo": {
 "username": "token username"
 }
}

<tokenInfo username="token username"></tokenInfo>

Does not exist.

Field	Type	Req.	OpenS.	Details
`username`	string	Yes	Yes	Username associated with token

topSongs

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

{
 "song": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 },
 {
 "id": "300000055",
 "parent": "200000002",
 "title": "Red&GreenSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000055",
 "duration": 400,
 "bitRate": 64,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 5,
 "year": 2007,
 "genre": "Electronic",
 "size": 3209886,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
 }
 ]
}

{
 "song": [
 {
 "id": "300000060",
 "parent": "200000002",
 "title": "BrownSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000060",
 "duration": 304,
 "bitRate": 20,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "userRating": 5,
 "averageRating": 5,
 "track": 4,
 "year": 2007,
 "genre": "Electronic",
 "size": 792375,
 "discNumber": 1,
 "suffix": "wma",
 "contentType": "audio/x-ms-wma",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007/04-Synthetic_-_BrownSmokeYSBM20k22khS.wma"
 },
 {
 "id": "300000055",
 "parent": "200000002",
 "title": "Red&GreenSmoke",
 "isDir": false,
 "isVideo": false,
 "type": "music",
 "albumId": "200000002",
 "album": "Colorsmoke EP",
 "artistId": "100000002",
 "artist": "Synthetic",
 "coverArt": "300000055",
 "duration": 400,
 "bitRate": 64,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "track": 5,
 "year": 2007,
 "genre": "Electronic",
 "size": 3209886,
 "discNumber": 1,
 "suffix": "mp3",
 "contentType": "audio/mpeg",
 "path": "Synthetic/Synthetic_-_Colorsmoke_EP-20k217-2007(1)/05-Synthetic_-_RedGreenSmokePM20k22khS_64kb.mp3"
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`song`	Array of `Child`	No		List of songs

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.

unstar

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

http://your-server/rest/unstar Since 1.8.0

Removes a star to a song, album or artist.

Parameters

Parameter	Req.	Comment
`id`	No	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.

Example

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

Result

An empty subsonic-response element on success.

updateInternetRadioStation

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

http://your-server/rest/updateInternetRadioStation Since 1.16.0

Updates an existing internet radio station. Only users with admin privileges are allowed to call this method.

Parameters

Parameter	Req.	Comment
`id`	Yes	The ID of the station.
`streamUrl`	Yes	The stream URL for the station.
`name`	Yes	The user-defined name for the station.
`homepageUrl`	No	The home page URL for the station.

Example

http://your-server/rest/updateInternetRadioStation.view?id=123&streamUrl=url&name=test&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

An empty subsonic-response element on success.

updatePlaylist

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

http://your-server/rest/updatePlaylist Since 1.8.0

Updates a playlist. Only the owner of a playlist is allowed to update it.

Parameters

Parameter	Req.	Comment
`playlistId`	Yes	The playlist ID.
`name`	No	The human-readable name of the playlist.
`comment`	No	The playlist comment.
`public`	No	`true` if the playlist should be visible to all users, `false` otherwise.
`songIdToAdd`	No	Add this song with this ID to the playlist. Multiple parameters allowed.
`songIndexToRemove`	No	Remove the song at this position in the playlist. Multiple parameters allowed.

Example

http://your-server/rest/updatePlaylist.view?playlistId=123&name=test&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

An empty subsonic-response element on success.

updateShare

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

http://your-server/rest/updateShare Since 1.6.0

Updates the description and/or expiration date for an existing share.

Parameters

Parameter	Req.	Comment
`id`	Yes	ID of the share to update.
`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, or zero to remove the expiration.

Example

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

Result

An empty subsonic-response element on success.

updateUser

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

http://your-server/rest/updateUser Since 1.10.1

Modifies an existing user on the server.

Parameters

Parameter	Req.	Default	Comment
`username`	Yes		The name of the user.
`password`	No		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.

Example

http://your-server/rest/updateUser.view?username=test&password=test&email=test@test.com&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

Result

An empty subsonic-response element on success.

user

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

{
 "folder": [
 "1",
 "3"
 ],
 "username": "sindre",
 "email": "sindre@activeobjects.no",
 "scrobblingEnabled": "true",
 "adminRole": "false",
 "settingsRole": "true",
 "downloadRole": "true",
 "uploadRole": "false",
 "playlistRole": "true",
 "coverArtRole": "true",
 "commentRole": "true",
 "podcastRole": "true",
 "streamRole": "true",
 "jukeboxRole": "true",
 "shareRole": "false"
}

{
 "folder": [
 "1",
 "3"
 ],
 "username": "sindre",
 "email": "sindre@activeobjects.no",
 "scrobblingEnabled": "true",
 "adminRole": "false",
 "settingsRole": "true",
 "downloadRole": "true",
 "uploadRole": "false",
 "playlistRole": "true",
 "coverArtRole": "true",
 "commentRole": "true",
 "podcastRole": "true",
 "streamRole": "true",
 "jukeboxRole": "true",
 "shareRole": "false"
}

Field	Type	Req.	Details
`username`	`string`	Yes	Username
`scrobblingEnabled`	`boolean`	Yes	Whether scrobling is enabled for the user
`maxBitRate`	`int`	No
`adminRole`	`boolean`	Yes	Whether the user is an admin
`settingsRole`	`boolean`	Yes	Whether the user is can edit settings
`downloadRole`	`boolean`	Yes	Whether the user can download
`uploadRole`	`boolean`	Yes	Whether the user can upload
`playlistRole`	`boolean`	Yes	Whether the user can create playlists
`coverArtRole`	`boolean`	Yes	Whether the user can get cover art
`commentRole`	`boolean`	Yes	Whether the user can create comments
`podcastRole`	`boolean`	Yes	Whether the user can create/refresh podcasts
`streamRole`	`boolean`	Yes	Whether the user can stream
`jukeboxRole`	`boolean`	Yes	Whether the user can control the jukebox
`shareRole`	`boolean`	Yes	Whether the user can create a stream
`videoConversionRole`	`boolean`	Yes	Whether the user can convert videos
`avatarLastChanged`	`string`	No	Last time the avatar was changed [ISO 8601]
`folder`	Array of `int`	No	Folder ID(s)

users

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

{
 "user": [
 {
 "folder": [
 "1",
 "3"
 ],
 "username": "sindre",
 "email": "sindre@activeobjects.no",
 "scrobblingEnabled": "true",
 "adminRole": "false",
 "settingsRole": "true",
 "downloadRole": "true",
 "uploadRole": "false",
 "playlistRole": "true",
 "coverArtRole": "true",
 "commentRole": "true",
 "podcastRole": "true",
 "streamRole": "true",
 "jukeboxRole": "true",
 "shareRole": "false"
 }
 ]
}

{
 "user": [
 {
 "folder": [
 "1",
 "3"
 ],
 "username": "sindre",
 "email": "sindre@activeobjects.no",
 "scrobblingEnabled": "true",
 "adminRole": "false",
 "settingsRole": "true",
 "downloadRole": "true",
 "uploadRole": "false",
 "playlistRole": "true",
 "coverArtRole": "true",
 "commentRole": "true",
 "podcastRole": "true",
 "streamRole": "true",
 "jukeboxRole": "true",
 "shareRole": "false"
 }
 ]
}

Field	Type	Req.	OpenS.	Details
`user`	Array of `user`	No		Array of users

videoInfo

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

// TODO

// TODO

Field	Type	Req.	OpenS.	Details

videos

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

// TODO

// TODO

Field	Type	Req.	OpenS.	Details

Work

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

{
 "name": "Symphony No. 5 in C minor, Op. 67",
 "musicBrainzId": "d03bff61-26fc-301b-98ac-4d8e85771cbc"
}

Does not exist.

Field	Type	Req.	OpenS.	Details
`name`	`string`	Yes	Yes	The work name.
`musicBrainzId`	`string`	No	Yes	The MusicBrainz Work ID.

OpenSubsonic

This is a new OpenSubsonic response type.

About the OpenSubsonic API on OpenSubsonic

OpenSubsonic API

File structure vs ID3 tags

OpenAPI OpenSubsonic Swagger UI

OpenAPI OpenSubsonic Redoc UI

API Reference

Parameters

OpenSubsonic changes

Documentation

OpenSubsonic

Required changes

OpenSubsonic API versions

Versions

Subsonic API versions

Versions

addChatMessage

Parameters

Example

Result

agent

Example agent list within one structuredLyrics entry

OpenSubsonic

AlbumID3

OpenSubsonic

AlbumID3WithSongs

OpenSubsonic

albumInfo

albumList

albumList2

API Key Authentication

Version 1

API keys

artist

ArtistID3

OpenSubsonic

artistInfo

artistInfo2

ArtistsID3

ArtistWithAlbumsID3

OpenSubsonic

bookmark

bookmarks

changePassword

Parameters

Example

Result

chatMessage

chatMessages

Child

OpenSubsonic

ClientInfo

CodecProfile

Contributor

OpenSubsonic

createBookmark

Parameters

Example

Result

createInternetRadioStation

Parameters

Example

Result

createPlaylist

Parameters

Example

Result

Since 1.14.0

Before 1.14.0

createPodcastChannel

Parameters

Example

Result

createShare

Parameters

Example

Result

createUser

Parameters

Example

Result

Example agent list within one `structuredLyrics` entry