Media Retrieval on OpenSubsonic

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

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

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.

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

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.

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

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