Clarification on OpenSubsonic

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.

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.

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

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.

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.

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.

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.

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