This is the multi-page printable view of this section.
Click here to print.
Return to the regular view of this page.
Overview
Complete API documentation and reference.
What is OpenSubsonic API?
The OpenSubsonic API allows anyone to build their own programs using a compatible server, whether they’re on the web, the desktop, or on mobile devices. All the OpenSubsonic-compatible apps (clients and servers) are built using the OpenSubsonic API.
The OpenSubsonic API allows you to call methods that respond in REST style XML or JSON. Since most clients now only rely on JSON, this documentation only shows the JSON answers in the documentation.
This project is built upon the original Subsonic API.
See:
- OpenSubsonic API for the API documentation.
- Goals for some of the goals of this project.
- Issues for some of the issues this project tries to solve over the original API.
Participants
OpenSubsonic is built with servers and clients trying to improve the global media center ecosystem by providing a common expandable API that can fit most of the needs of modern music apps.
Any server or client can join the organization and make proposals for OpenSubsonic. The only condition is that if (as a client) you request an API extension that is accepted, you engage yourself in implementing it in your client in a timely manner.
Servers
Clients
Goals
The OpenSubsonic API has several goals, which include:
- Being an open, collaboratively maintained specification.
- Ensuring security across all extensions.
- The API aims for consistent results across all servers, ensuring that every request produces the same outcome. The API definition must be clear and precise, eliminating any ambiguity about the expected results.
- Maintaining complete backwards compatibility with the existing Subsonic API.
- Offering piecewise optional implementation for servers and clients.
Addressing Issues with the Subsonic API
Some of the issues the OpenSubsonic API aims to address include:
- Outdated and insecure authentication methods.
- Suboptimal versioning schema.
- Insufficient methods for expressing server functionality.
- Lack of an open and collaborative way to evolve the API.
By extending the existing Subsonic API, the OpenSubsonic API hopes to create a more secure, flexible, and collaborative environment for the Subsonic ecosystem.
Join us
Feel free to join the OpenSubsonic forum for discussions, suggestions, and questions.
1 - OpenSubsonic API
API details and methods.
See API Reference for the basic API documentation. (Mandatory parameters, authentication, error handling, …)
Be sure to read OpenSubsonic changes to easily identify the changes brought by OpenSubsonic.
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.
Correspondingly, there are two sets of methods for searching, starring and album lists. Refer to the method documentation for details.
API methods
2 - API Reference
Common API documentation.
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.
**) If apiKey is specified, then none of p, t, s, nor u can be specified.
Remember to URL encode the request parameters. All methods (except those that return binary data) returns XML documents conforming to the subsonic-rest-api.xsd schema. The XML documents are encoded with UTF-8.
POST support
OpenSubsonic add official support for application/x-www-form-urlencoded POST to pass the argument.
Check that the server support the HTTP form POST extension before using it.
The arguments can then be passed in the POST body (Do not forget to URL encode both the keys and values), this allows to overcome the URL size limits when passing many parameters for playlists for example.
curl -v -X POST -H 'Content-Type: application/x-www-form-urlencoded' 'http://your-server/rest/ping.view' --data 'c=AwesomeClientName&v=1.12.0&f=json&u=joe&p=sesame'
Authentication
If you are targeting API version 1.12.0 or earlier, authentication is performed by sending the password as clear text or hex-encoded. Examples:
http://your-server/rest/ping.view?u=joe&p=sesame&v=1.12.0&c=AwesomeClientName&f=json
http://your-server/rest/ping.view?u=joe&p=enc:736573616d65&v=1.12.0&c=AwesomeClientName&f=json
Starting with API version 1.13.0, the recommended authentication scheme is to send an authentication token, calculated as a one-way salted hash of the password.
This involves two steps:
- For each REST call, generate a random string called the salt. Send this as parameter
s.
Use a salt length of at least six characters.
- Calculate the authentication token as follows: token = md5(password + salt). The md5() function takes a string and returns the 32-byte ASCII hexadecimal representation of the MD5 hash, using lower case characters for the hex values. The ‘+’ operator represents concatenation of the two strings. Treat the strings as UTF-8 encoded when calculating the hash. Send the result as parameter
t.
For example: if the password is sesame and the random salt is c19b2d, then token = md5(“sesamec19b2d”) = 26719a1196d2a940705a59634eb18eab. The corresponding request URL then becomes:
http://your-server/rest/ping.view?u=joe&t=26719a1196d2a940705a59634eb18eab&s=c19b2d&v=1.13.0&c=AwesomeClientName&f=json
For servers that implement API Key authentication, the recommended authentication is to use an API key.
This is a token generated from the Subsonic server.
It must be passed in in as apiKey=<API key>, and the u parameter must not be provided.
Note that u/p may still be used by servers which are backed by LDAP/PAM/other authentication.
http://your-server/rest/ping.view?u=joe&apiKey=43504ab81e2bfae1a7691fe3fc738fdf55ada2757e36f14bcf13d&v=1.16.1&c=AwesomeClientName&f=json
Subsonic-response
All API endpoint unless noted otherwise returns a subsonic-response that indicate the result of the command and give some information about the server.
{
"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"
}
}
See: subsonic-response for the field details.
Error handling
If a method fails it will return an error code and message in an error element. In addition, the status attribute of the subsonic-response root element will be set to failed instead of ok. For example:
{
"subsonic-response": {
"status": "failed",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true,
"error": {
"code": 40,
"message": "Wrong username or password"
}
}
}
{
"subsonic-response": {
"status": "failed",
"version": "1.16.1",
"error": {
"code": 40,
"message": "Wrong username or password"
}
}
}
| Field |
Type |
Req. |
OpenS. |
Details |
error |
error |
Yes |
|
The error details. |
code |
int |
Yes |
|
The error code. |
message |
string |
No |
|
A human readable error message. |
The following error codes are defined:
| Code |
Description |
| 0 |
A generic error. |
| 10 |
Required parameter is missing. |
| 20 |
Incompatible Subsonic REST protocol version. Client must upgrade. |
| 30 |
Incompatible Subsonic REST protocol version. Server must upgrade. |
| 40 |
Wrong username or password. |
| 41 |
Token authentication not supported for LDAP users. |
| 42 |
Provided authentication mechanism not supported. |
| 43 |
Multiple conflicting authentication mechanisms provided. |
| 44 |
Invalid API key. |
| 50 |
User is not authorized for the given operation. |
| 60 |
The trial period for the Subsonic server is over. Please upgrade to Subsonic Premium. Visit subsonic.org for details. |
| 70 |
The requested data was not found. |
OpenSubsonic
Servers must return error 41 if they do not support token-based authentication, 42 if they do not support any other authentication mechanism (password-based and/or API key-based), and 43 if multiple conflicting authentication parameters are passed in at the same time.
Note that even though the error text for 41 is Token authentication not supported for LDAP users., it actually implies that Token authentication is not supported for any reason.
To indicate differences between cases (where LDAP is used, versus no LDAP), servers may use the new helpUrl field.
New fields are added, see error
3 - OpenSubsonic changes
API changes in OpenSubsonic API vs the original Subsonic API.
Documentation
In the documentation all changes from the original Subsonic API will be emphasized with the following warning:
OpenSubsonic
Changes (Required or optional) related to OpenSubsonic.
All endpoints or responses modified by the OpenSubsonic API will have [OS] indicator in the navigation menu.
Most servers and clients have dedicated pages to show what parts of OpenSubsonic they support. See Overview
OpenSubsonic expand the original API via 3 different ways:
- Clarifications: Documentation improvement to ensure consistency in server answers or actions where doubt was possible.
- Extensions: Non breaking changes to the API to improve clients life. Like new returned field, or new parameters to existing functions.
- Additions: New endpoints added to provide functions that could not be provided via non breaking extensions.
Required changes
OpenSubsonic is built to be mostly optional to ease the burden on the servers who can’t support some features, while still allowing clients to precisely know what the servers support without having to guess.
To achieve this servers supporting OpenSubsonic have to support a very minimal subset of things.
- Expand the
subsonic-response with the new mandatory fields.
- Implement the
getOpenSubsonicExtensions endpoint. This must be accessible without any authentication parameters
- Return error 41 (
API Reference) if they do not support Subsonic 1.13.0 new authentification system while advertising a version > 1.13.0
List of changes
Clarifications
List of clarifications
Non breaking changes
List of non breaking changes
Additions
List of additions
Extensions
List of extension
4 - Extensions
OpenSubsonic extensions documentation.
4.1 - API Key Authentication
Add a new authentication mechanism involving only an API key, and no
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).
Servers which implement this extension must provide some mechanism for viewing active API key(s) and allow for revoking API keys.
Note that these API keys do not expire; as long as they are not revoked by the user, they are assumed to be valid.
Using a API key
An API key is used as a query parameter apiKey=<api key>.
When an API key is provided, the client must not provide a u parameter; passing in u must be treated as an error 43.
It is recommended that servers which provide API-key authentication no longer support salt/token-based authentication.
If multiple conflicting authentication parameters are passed in, the server must return an error 43, Multiple conflicting authentication mechanisms provided
If a server removes support for token-based authentication, it must return error 41 (Token authentication not supported for LDAP users.).
If a server removes support for any other particular authentication mechanism, it must return an error 42 (Provided authentication mechanism not supported).
In both cases, it is recommended that the server provide a meaningful url (configuration url, documentation, etc) in the helpUrl to help clients instruct their users how to obtain an API key.
New error codes
This extension introduces three new errors 42, 43 and 44, and adds a new field helpUrl. See error
4.2 - HTTP form POST
Add support for POST request to the API (application/x-www-form-urlencoded)
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.
4.3 - Song Lyrics
Add support for synchronized lyrics, multiple languages, and retrieval by song ID
OpenSubsonic version: 1
OpenSubsonic extension name songLyrics (As returned by getOpenSubsonicExtensions)
Version 1
This extension requires the following endpoints:
4.4 - Template extension
A template extension.
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:
Version 2
You can now bake a lot of stuff via the API!
This extension requires the following endpoints:
4.5 - Transcode Offset
Add support for start offset for transcoding.
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.
5 - Endpoints
Low level endpoints documentation.
5.1 - addChatMessage
Adds a message to the chat log.
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"
}
}
5.2 - changePassword
Changes the password of an existing user on the server.
http://your-server/rest/changePassword Since 1.1.0
Changes the password of an existing user on the server, using the following parameters. You can only change your own password unless you have admin privileges.
Parameters
| Parameter |
Req. |
OpenS. |
Default |
Comment |
username |
Yes |
|
|
The name of the user which should change its password. |
password |
Yes |
|
|
The new password of the new user, either in clear text of hex-encoded (see above). |
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.
{
"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"
}
}
5.3 - createBookmark
Creates or updates a bookmark.
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. |
OpenS. |
Default |
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.
{
"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"
}
}
5.4 - createInternetRadioStation
Adds a new internet radio station.
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. |
OpenS. |
Default |
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"
}
}
5.5 - createPlaylist
Creates (or updates) a playlist.
http://your-server/rest/createPlaylist Since 1.2.0
Creates (or updates) a playlist.
Parameters
| Parameter |
Req. |
OpenS. |
Default |
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
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 |
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"
}
}
5.6 - createPodcastChannel
Adds a new Podcast channel.
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"
}
}
5.7 - createShare
Creates a public URL that can be used by anyone to stream music or video from the server.
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. |
OpenS. |
Default |
Comment |
id |
Yes |
|
|
ID of a song, album or video to share. Use one id parameter for each entry to share. |
description |
No |
|
|
A user-defined description that will be displayed to people visiting the shared media. |
expires |
No |
|
|
The time at which the share expires. Given as milliseconds since 1970. |
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
{
"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 created share |
5.8 - createUser
Creates a new user on the server.
http://your-server/rest/createUser Since 1.1.0
Creates a new user on the server, using the following parameters:
Parameters
| Parameter |
Req. |
OpenS. |
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 authenicated 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.
{
"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"
}
}
5.9 - deleteBookmark
Creates or updates a bookmark.
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"
}
}
5.10 - deleteInternetRadioStation
Deletes an existing internet radio station.
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"
}
}
5.11 - deletePlaylist
Deletes a saved playlist.
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"
}
}
5.12 - deletePodcastChannel
Deletes a Podcast channel.
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",
}
}
5.13 - deletePodcastEpisode
Deletes a Podcast episode.
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"
}
}
5.14 - deleteShare
Deletes an existing share.
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"
}
}
5.15 - deleteUser
Deletes an existing user on the server.
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"
}
}
5.16 - download
Downloads a given media file.
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”).
5.17 - downloadPodcastEpisode
Request the server to start downloading a given Podcast episode.
http://your-server/rest/downloadPodcastEpisode Since 1.9.0
Request the server to start downloading a given Podcast episode. Note: The user must be authorized for Podcast administration (see Settings > Users > User is allowed to administrate Podcasts).
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"
}
}
5.18 - getAlbum
Returns details for an album.
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 album 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 |
album |
Yes |
|
The album |
5.19 - getAlbumInfo
Returns album info.
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 |
5.20 - getAlbumInfo2
Returns album info.
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 |
5.21 - getAlbumList
Returns a list of random, newest, highest rated etc. albums.
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. |
OpenS. |
Default |
Comment |
type |
Yes |
|
|
The list type. Must be one of the following: random, newest, highest, frequent, recent. Since 1.8.0 you can also use alphabeticalByName or alphabeticalByArtist to page through all albums alphabetically, and starred to retrieve starred albums. Since 1.10.1 you can use byYear and byGenre to list albums in a given year range or genre. |
size |
No |
|
10 |
The number of albums to return. Max 500. |
offset |
No |
|
0 |
The list offset. Useful if you for example want to page through the list of newest albums. |
fromYear |
Yes (if type is byYear) |
|
|
The first year in the range. If fromYear > toYear a reverse chronological list is returned. |
toYear |
Yes (if type is byYear) |
|
|
The last year in the range. |
genre |
Yes (if type is byGenre) |
|
|
The name of the genre, e.g., “Rock”. |
musicFolderId |
No |
|
|
(Since 1.11.0) Only return albums in the music folder with the given ID. See getMusicFolders. |
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.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"albumList": {
"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"
},
{
"id": "200000012",
"parent": "100000019",
"album": "Buried in Nausea",
"title": "Buried in Nausea",
"name": "Buried in Nausea",
"isDir": true,
"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"
}
]
}
}
}
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"albumList": {
"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 |
albumList |
albumList |
Yes |
|
The album list |
5.22 - getAlbumList2
Returns a list of random, newest, highest rated etc. albums.
http://your-server/rest/getAlbumList2 Since 1.8.0
Similar to getAlbumList, but organizes music according to ID3 tags.
Parameters
| Parameter |
Req. |
OpenS. |
Default |
Comment |
type |
Yes |
|
|
The list type. Must be one of the following: random, newest, highest, frequent, recent. Since 1.8.0 you can also use alphabeticalByName or alphabeticalByArtist to page through all albums alphabetically, and starred to retrieve starred albums. Since 1.10.1 you can use byYear and byGenre to list albums in a given year range or genre. |
size |
No |
|
10 |
The number of albums to return. Max 500. |
offset |
No |
|
0 |
The list offset. Useful if you for example want to page through the list of newest albums. |
fromYear |
Yes (if type is byYear) |
|
|
The first year in the range. If fromYear > toYear a reverse chronological list is returned. |
toYear |
Yes (if type is byYear) |
|
|
The last year in the range. |
genre |
Yes (if type is byGenre) |
|
|
The name of the genre, e.g., “Rock”. |
musicFolderId |
No |
|
|
(Since 1.11.0) Only return albums in the music folder with the given ID. See getMusicFolders. |
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.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"albumList2": {
"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"
}
]
}
}
}
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"albumList2": {
"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 |
albumList2 |
albumList2 |
Yes |
|
The album list |
5.23 - getArtist
Returns details for an artist.
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": "100000002",
"name": "Synthetic",
"coverArt": "ar-100000002",
"albumCount": 1,
"starred": "2021-02-22T05:54:18Z",
"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": "100000002",
"name": "Synthetic",
"coverArt": "ar-100000002",
"albumCount": 1,
"starred": "2021-02-22T05:54:18Z",
"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 |
5.24 - getArtistInfo
Returns artist info.
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. |
OpenS. |
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.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"artistInfo": {
"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",
"artistInfo": {
"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 |
artistInfo |
artistInfo |
Yes |
|
The album info |
5.25 - getArtistInfo2
Returns artist info.
http://your-server/rest/getArtistInfo2 Since 1.11.0
Similar to getArtistInfo, but organizes music according to ID3 tags.
Parameters
| Parameter |
Req. |
OpenS. |
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": {},
"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": {},
"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 |
5.26 - getArtists
Returns all artists.
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 |
5.27 - getAvatar
Returns the avatar (personal image) for a user.
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”).
5.28 - getBookmarks
Returns all bookmarks for this user.
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 |
5.29 - getCaptions
Returns captions (subtitles) for a video.
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.
5.30 - getChatMessages
Returns the current visible (non-expired) chat messages.
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 |
5.31 - getCoverArt
Returns a cover art image.
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. |
|
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”).
5.32 - getGenres
Returns all genres.
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 |
5.33 - getIndexes
Returns an indexed structure of all artists.
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.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true,
"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"
}
}
}
<subsonic-response status="ok" version="1.16.1" type="AwesomeServerName" serverVersion="0.1.3 (tag)" openSubsonic="true">
<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>
</subsonic-response>
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"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"
}
}
}
<subsonic-response status="ok" version="1.16.1" type="AwesomeServerName">
<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>
</subsonic-response>
| Field |
Type |
Req. |
OpenS. |
Details |
indexes |
indexes |
Yes |
|
The indexed artist list |
5.34 - getInternetRadioStations
Returns all internet radio stations.
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/"
},
{
"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"
}
]
}
}
}
{
"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"
}
]
}
}
}
5.35 - getLicense
Get details about the software license.
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 |
5.36 - getLyrics
Searches for and returns lyrics for a given song.
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 |
5.37 - getLyricsBySongId
Add support for synchronized lyrics, multiple languages, and retrieval by song ID
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. |
Special notes about the lang field
Ideally, the server will return lang as an ISO 639 (2/3) code.
However, tagged files and external lyrics can come with any value as a potential language code, so clients should take care when displaying lang.
Furthermore, there is special behavior for the value xxx.
While not an ISO code, it is commonly used by taggers and other parsing software.
Clients should treat xxx as not having a specified language (equivalent to the und code).
Example
http://your-server/rest/getLyricsBySongId.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested lyricsList
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true,
"lyricsList": {
"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": "und",
"offset": 100,
"synced": false,
"line": [
{
"value": "It's bugging me"
},
{
"value": "Grating me"
},
{
"value": "And twisting me around..."
}
]
}
]
}
}
}
<subsonic-response status="ok" version="1.16.1" type="AwesomeServerName" serverVersion="0.1.3 (tag)" openSubsonic="true">
<lyricsList>
<structuredLyrics displayArtist="Muse" displayTitle="Hysteria" lang="en" 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="en" offset="100" synced="false">
<line>It's bugging me</line>
<line>Grating me</line>
<line>And twisting me around...</line>
</structuredLyrics>
</lyricsList>
</subsonic-response>
| Field |
Type |
Req. |
OpenS. |
Details |
lyricsList |
lyricsList |
Yes |
Yes |
List of structured lyrics |
5.38 - getMusicDirectory
Returns a listing of all files in a music directory.
http://your-server/rest/getMusicDirectory Since 1.0.0
Returns a listing of all files in a music directory. Typically used to get list of albums for an artist, or list of songs for an album.
Parameters
| Parameter |
Req. |
OpenS. |
Default |
Comment |
id |
Yes |
|
|
A string which uniquely identifies the music folder. Obtained by calls to getIndexes or getMusicDirectory. |
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 |
5.39 - getMusicFolders
Returns all configured top-level music folders.
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 |
5.40 - getNewestPodcasts
Returns the most recently published Podcast episodes.
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.
| Field |
Type |
Req. |
OpenS. |
Details |
newestPodcasts |
newestPodcasts |
Yes |
|
The podacsts |
5.41 - getNowPlaying
Returns what is currently being played by all users.
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
}
]
}
}
}
{
"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 |
5.42 - getOpenSubsonicExtensions
List the OpenSubsonic extensions supported by this server.
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
]
}
]
}
}
| Field |
Type |
Req. |
OpenS. |
Details |
openSubsonicExtensions |
An array of openSubsonicExtension |
Yes |
|
The list of supported extensions |
OpenSubsonic
This is a new endpoint.
5.43 - getPlaylist
Returns a listing of files in a saved playlist.
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 |
5.44 - getPlaylists
Returns all playlists a user is allowed to play.
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",
"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 |
5.45 - getPlayQueue
Returns the state of the play queue for this user.
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.
| Field |
Type |
Req. |
OpenS. |
Details |
playQueue |
playQueue |
Yes |
|
The play queue |
5.46 - getPodcasts
Returns all Podcast channels the server subscribes to, and (optionally) their episodes.
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.
| Field |
Type |
Req. |
OpenS. |
Details |
podcasts |
podcasts |
Yes |
|
The podacsts |
5.47 - getRandomSongs
Returns random songs matching the given criteria.
http://your-server/rest/getRandomSongs Since 1.2.0
Returns random songs matching the given criteria.
Parameters
| Parameter |
Req. |
OpenS. |
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.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"randomSongs": {
"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",
"randomSongs": {
"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 |
randomSongs |
randomSongs |
Yes |
|
The random songs list |
5.48 - getScanStatus
Returns the current status for media library scanning.
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 |
5.49 - getShares
Returns information about shared media this user is allowed to manage.
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 |
5.50 - getSimilarSongs
Returns a random collection of songs from the given artist and similar artists.
http://your-server/rest/getSimilarSongs Since 1.11.0
Returns a random collection of songs from the given artist and similar artists, using data from last.fm. Typically used for artist radio features.
Parameters
| Parameter |
Req. |
OpenS. |
Default |
Comment |
id |
Yes |
|
|
The artist, album or song ID. |
count |
No |
|
50 |
Max number of songs to return. |
Example
http://your-server/rest/getSimilarSongs.view?id=123&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested similarSongs element on success.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"similarSongs": {
"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",
"similarSongs": {
"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 |
similarSongs |
similarSongs |
Yes |
|
The similar songs list |
5.51 - getSimilarSongs2
Returns a random collection of songs from the given artist and similar artists.
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 |
5.52 - getSong
Returns details for a song.
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.
| Field |
Type |
Req. |
OpenS. |
Details |
song |
song |
Yes |
|
The song |
5.53 - getSongsByGenre
Returns songs in a given genre.
http://your-server/rest/getSongsByGenre Since 1.9.0
Returns songs in a given genre.
Parameters
| Parameter |
Req. |
OpenS. |
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=Rock&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
Result
A subsonic-response element with a nested songsByGenre element on success.
| Field |
Type |
Req. |
OpenS. |
Details |
songsByGenre |
songsByGenre |
Yes |
|
The song |
5.54 - getStarred
Returns starred songs, albums and artists.
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.
| Field |
Type |
Req. |
OpenS. |
Details |
starred |
starred |
Yes |
|
The song |
5.55 - getStarred2
Returns starred songs, albums and artists.
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.
| Field |
Type |
Req. |
OpenS. |
Details |
starred2 |
starred2 |
Yes |
|
The song |
5.56 - getTopSongs
Returns top songs for the given artist.
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 |
5.57 - getUser
Get details about a given user, including which authorization roles and folder access it has.
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.
| Field |
Type |
Req. |
OpenS. |
Details |
user |
user |
Yes |
|
The user |
5.58 - getUsers
Get details about all users, including which authorization roles and folder access they have
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.
| Field |
Type |
Req. |
OpenS. |
Details |
users |
users |
Yes |
|
The users |
5.59 - getVideoInfo
Returns details for a video.
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.
| Field |
Type |
Req. |
OpenS. |
Details |
videoInfo |
videoInfo |
Yes |
|
The song |
5.60 - getVideos
Returns all video files.
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.
| Field |
Type |
Req. |
OpenS. |
Details |
videos |
videos |
Yes |
|
The videos |
5.61 - hls
Downloads a given media file.
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. |
OpenS. |
Default |
Comment |
id |
Yes |
|
|
A string which uniquely identifies the media file to stream. |
bitRate |
No |
|
|
If specified, the server will attempt to limit the bitrate to this value, in kilobits per second. If this parameter is specified more than once, the server will create a variant playlist, suitable for adaptive bitrate streaming. The playlist will support streaming at all the specified bitrates. The server will automatically choose video dimensions that are suitable for the given bitrates. Since 1.9.0 you may explicitly request a certain width (480) and height (360) like so: bitRate=1000@480x360 |
audioTrack |
No |
|
|
The ID of the audio track to use. SeegetVideoInfo for how to get the list of available audio tracks for a video. |
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”).
5.62 - jukeboxControl
Controls the jukebox, i.e., playback directly on the server’s audio hardware.
http://your-server/rest/jukeboxControl Since 1.2.0
Controls the jukebox, i.e., playback directly on the server’s audio hardware. Note: The user must be authorized to control the jukebox (see Settings > Users > User is allowed to play files in jukebox mode).
Parameters
| Parameter |
Req. |
OpenS. |
Default |
Comment |
action |
Yes |
|
|
The operation to perform. Must be one of: get, status (since 1.7.0), set (since 1.7.0), start, stop, skip, add, clear, remove, shuffle, setGain |
index |
No |
|
|
Used by skip and remove. Zero-based index of the song to skip to or remove. |
offset |
No |
|
|
(Since 1.7.0) Used by skip. Start playing this many seconds into the track. |
id |
No |
|
|
Used by add and set. ID of song to add to the jukebox playlist. Use multiple id parameters to add many songs in the same request. (set is similar to a clear followed by a add, but will not change the currently playing track.) |
gain |
No |
|
|
Used by setGain to control the playback volume. A float value between 0.0 and 1.0. |
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 :
5.63 - ping
Used to test connectivity with the server.
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"
}
}
5.64 - refreshPodcasts
Requests the server to check for new Podcast episodes.
http://your-server/rest/refreshPodcasts Since 1.9.0
Requests the server to check for new Podcast episodes. Note: The user must be authorized for Podcast administration (see Settings > Users > User is allowed to administrate Podcasts).
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"
}
}
5.65 - savePlayQueue
Saves the state of the play queue for this user.
http://your-server/rest/savePlayQueue Since 1.12.0
Saves the state of the play queue for this user. This includes the tracks in the play queue, the currently playing track, and the position within this track. Typically used to allow a user to move between different clients/apps while retaining the same play queue (for instance when listening to an audio book).
Parameters
| Parameter |
Req. |
OpenS. |
Default |
Comment |
id |
No |
|
|
ID of a song in the play queue. Use one id parameter for each song in the play queue. |
current |
No |
|
|
The ID of the current playing song. |
position |
No |
|
|
The position in milliseconds within the currently playing song. |
Example
http://your-server/rest/savePlayQueue.view?id=123¤t=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"
}
}
OpenSubsonic
Note id is optional. Send a call without any parameters to clear the currently saved queue.
5.66 - scrobble
Registers the local playback of one or more media files.
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.
Parameters
| Parameter |
Req. |
OpenS. |
Default |
Comment |
id |
Yes |
|
|
A string which uniquely identifies the file to scrobble. |
time |
No |
|
|
(Since 1.8.0) The time (in milliseconds since 1 Jan 1970) at which the song was listened to. |
submission |
No |
|
True |
Whether this is a “submission” or a “now playing” notification. |
Example
http://your-server/rest/scrobble.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"
}
}
5.67 - search
Returns a listing of files matching the given search criteria. Supports paging through the result.
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. |
OpenS. |
Default |
Comment |
artist |
No |
|
|
Artist to search for. |
album |
No |
|
|
Album to searh 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.
| Field |
Type |
Req. |
OpenS. |
Details |
searchResult |
searchResult |
Yes |
|
The result |
5.68 - search2
Returns a listing of files matching the given search criteria. Supports paging through the result.
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. |
OpenS. |
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.
| Field |
Type |
Req. |
OpenS. |
Details |
searchResult2 |
searchResult2 |
Yes |
|
The result |
5.69 - search3
Returns albums, artists and songs matching the given search criteria. Supports paging through the result.
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.
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"type": "AwesomeServerName",
"serverVersion": "0.1.3 (tag)",
"openSubsonic": true
"searchResult3": {
"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
}
]
}
}
}
{
"subsonic-response": {
"status": "ok",
"version": "1.16.1",
"searchResult3": {
"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
}
]
}
}
}
| Field |
Type |
Req. |
OpenS. |
Details |
searchResult3 |
searchResult3 |
Yes |
|
The result of the search |
5.70 - setRating
Sets the rating for a music file.
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"
}
}
5.71 - star
Attaches a star to a song, album or artist.
http://your-server/rest/star Since 1.8.0
Attaches a star to a song, album or artist.
Parameters
| Parameter |
Req. |
OpenS. |
Default |
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.
{
"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"
}
}
5.72 - startScan
Initiates a rescan of the media libraries.
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 |
5.73 - stream
Streams a given media file.
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 Offet 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”).
OpenSubsonic
OpenSubsonic servers must not count access to this endpoint as a play and increase playcount. Clients can use the Scrobble endpoint to indicate that a media is played ensuring proper data in all cases.
If the server support the Transcode Offet extension, then it must accept the timeOffset parameter for music too.
5.74 - tokenInfo
Returns information about an API key
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>
| Field |
Type |
Req. |
OpenS. |
Details |
tokenInfo |
tokenInfo |
Yes |
Yes |
Information about the token |
5.75 - unstar
Attaches a star to a song, album or artist.
http://your-server/rest/unstar Since 1.8.0
Removes a star to a song, album or artist.
Parameters
| Parameter |
Req. |
OpenS. |
Default |
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.
{
"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"
}
}
5.76 - updateInternetRadioStation
Updates an existing internet radio station.
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. |
OpenS. |
Default |
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.
{
"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"
}
}
5.77 - updatePlaylist
Updates a playlist. Only the owner of a playlist is allowed to update it.
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. |
OpenS. |
Default |
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.
{
"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"
}
}
5.78 - updateShare
Updates the description and/or expiration date for an existing share.
http://your-server/rest/updateShare Since 1.6.0
Updates the description and/or expiration date for an existing share.
Parameters
| Parameter |
Req. |
OpenS. |
Default |
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.
{
"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"
}
}
5.79 - updateUser
Modifies an existing user on the server.
http://your-server/rest/updateUser Since 1.10.1
Modifies an existing user on the server.
Parameters
| Parameter |
Req. |
OpenS. |
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 authenicated 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.
{
"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"
}
}
6 - Responses
Endpoints responses documentation.
6.1 - AlbumID3
An album from ID3 tags.
{
"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,
"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,
"discTitles": [
{
"disc": 0,
"title": "Disc 0 title"
},
{
"disc": 2,
"title": "Disc 1 title"
}
]
}
{
"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. |
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. |
discTitles |
Array of DiscTitle |
No |
Yes |
The list of all disc titles of the album. |
OpenSubsonic
New fields are added:
playeduserRatingrecordLabelsmusicBrainzIdgenresartistsdisplayArtistreleaseTypemoodssortNameoriginalReleaseDateisCompilationdiscTitles
Note: All OpenSubsonic added fields are optionals. But if a server support a field it must return it with an empty / default value when not present in it’s database so that clients knows what the server supports.
Note: Even if some added fields may looks duplicated, it’s important to still return the legacy data for compatibility reasons.
6.2 - AlbumID3WithSongs
Album with songs.
{
"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,
"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,
"discTitles": [
{
"disc": 0,
"title": "Disc 0 title"
},
{
"disc": 2,
"title": "Disc 1 title"
}
],
"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"
}
]
}
{
"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. |
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. |
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:
playeduserRatingrecordLabelsmusicBrainzIdgenresartistsdisplayArtistreleaseTypemoodssortNameoriginalReleaseDateisCompilationdiscTitles
Note: All OpenSubsonic added fields are optionals. But if a server support a field it must return it with an empty / default value when not present in it’s database so that clients knows what the server supports.
Note: Even if some added fields may looks duplicated, it’s important to still return the legacy data for compatibility reasons.
6.3 - albumInfo
Album info.
{
"notes": "Download the full release here (creative commons). These cripsy beats are ripe with thumping funk and techno influences, sample wizardry and daring shuffles. Composed with the help of unique sound plugins which were especially programmed to measure Comfort Fit’s needs and wishes, we think the chances aren’t bad that you’ll fall for the unique sound signature, bounce and elegance of this unusual Hip Hop production. Ltj bukem / Good looking Rec., UK: \"Really love this music.\" Velanche / XLR8R, UK: \"Awesome job he's done... overall production is dope.\" Kwesi / BBE Music, UK: \"Wooooooowwwww... WHAT THE FUCK! THIS IS WHAT",
"musicBrainzId": "6e1d48f7-717c-416e-af35-5d2454a13af2",
"smallImageUrl": "http://localhost:8989/play/art/0f8c3cbd6b0b22c3b5402141351ac812/album/21/thumb34.jpg",
"mediumImageUrl": "http://localhost:8989/play/art/41b16680dc1b3aaf5dfba24ddb6a1712/album/21/thumb64.jpg",
"largeImageUrl": "http://localhost:8989/play/art/e6fd8d4e0d35c4436e56991892bfb27b/album/21/thumb174.jpg"
}
{
"notes": "Download the full release here (creative commons). These cripsy beats are ripe with thumping funk and techno influences, sample wizardry and daring shuffles. Composed with the help of unique sound plugins which were especially programmed to measure Comfort Fit’s needs and wishes, we think the chances aren’t bad that you’ll fall for the unique sound signature, bounce and elegance of this unusual Hip Hop production. Ltj bukem / Good looking Rec., UK: \"Really love this music.\" Velanche / XLR8R, UK: \"Awesome job he's done... overall production is dope.\" Kwesi / BBE Music, UK: \"Wooooooowwwww... WHAT THE FUCK! THIS IS WHAT",
"musicBrainzId": "6e1d48f7-717c-416e-af35-5d2454a13af2",
"smallImageUrl": "http://localhost:8989/play/art/0f8c3cbd6b0b22c3b5402141351ac812/album/21/thumb34.jpg",
"mediumImageUrl": "http://localhost:8989/play/art/41b16680dc1b3aaf5dfba24ddb6a1712/album/21/thumb64.jpg",
"largeImageUrl": "http://localhost:8989/play/art/e6fd8d4e0d35c4436e56991892bfb27b/album/21/thumb174.jpg"
}
| Field |
Type |
Req. |
OpenS. |
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 |
6.4 - albumList
Album list.
{
"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 |
6.5 - albumList2
Album list.
{
"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 |
6.6 - artist
Artist details.
{
"id": "100000002",
"name": "Synthetic",
"coverArt": "ar-100000002",
"albumCount": 1,
"starred": "2021-02-22T05:54:18Z"
}
{
"id": "100000002",
"name": "Synthetic",
"coverArt": "ar-100000002",
"albumCount": 1,
"starred": "2021-02-22T05:54:18Z"
}
| Field |
Type |
Req. |
OpenS. |
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] |
album |
Array of AlbumID3 |
No |
|
Artist albums |
6.7 - ArtistID3
An artist from ID3 tags.
{
"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 arist |
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 have in the library. |
OpenSubsonic
New fields are added:
musicBrainzIdsortNameroles
Note: All OpenSubsonic added fields are optionals. But if a server support a field it must return it with an empty / default value when not present in it’s database so that clients knows what the server supports.
Note: Even if some added fields may looks duplicated, it’s important to still return the legacy data for compatibility reasons.
6.8 - artistInfo
Artist info.
{
"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": {},
"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 |
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 |
6.9 - artistInfo2
Artist info.
{
"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": {},
"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 |
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 |
6.10 - ArtistsID3
A list of indexed 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
}
]
}
]
}
{
"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 |
Yes |
|
Index list |
6.11 - bookmark
A 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": "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. |
OpenS. |
Details |
position |
long |
Yes |
|
Bookmark position in seconds |
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 |
6.12 - bookmarks
Bookmarks list.
{
"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 |
6.13 - chatMessage
A chatMessage.
{
"username": "user",
"time": 1678935699000,
"message": "Api Script Testing"
}
{
"username": "user",
"time": 1678935699000,
"message": "Api Script Testing"
}
| Field |
Type |
Req. |
OpenS. |
Details |
username |
string |
Yes |
|
Username |
time |
long |
Yes |
|
Time in millis since Jan 1 1970 |
message |
string |
Yes |
|
The message |
6.14 - chatMessages
Chat messages list.
{
"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 |
6.15 - Child
A media.
{
"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
}
}
{
"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. |
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. |
OpenSubsonic
New fields are added:
playedbpmcommentsortNamemusicBrainzIdgenresartistsdisplayArtistalbumArtistsdisplayAlbumArtistcontributorsdisplayComposermoodsreplayGain
Note: All OpenSubsonic added fields are optionals. But if a server support a field it must return it with an empty / default value when not present in it’s database so that clients knows what the server supports.
Note: Even if some added fields may looks duplicated, it’s important to still return the legacy data for compatibility reasons.
6.16 - Contributor
A contributor artist for a song or an album
{
"role": "performer",
"subRole": "Bass",
"artist": {
"id": "ar-1",
"name": "Artist 1"
}
}
| 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.
6.17 - directory
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"
}
]
}
{
"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 |
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 |
6.18 - DiscTitle
A disc title for an album
{
"disc": 0,
"title": "The disc title"
}
| Field |
Type |
Req. |
OpenS. |
Details |
disc |
int |
Yes |
Yes |
The disc numer. |
title |
string |
Yes |
Yes |
The name of the disc. |
OpenSubsonic
This is a new OpenSubsonic response type.
6.19 - error
Error.
{
"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:
| Code |
Description |
| 0 |
A generic error. |
| 10 |
Required parameter is missing. |
| 20 |
Incompatible Subsonic REST protocol version. Client must upgrade. |
| 30 |
Incompatible Subsonic REST protocol version. Server must upgrade. |
| 40 |
Wrong username or password. |
| 41 |
Token authentication not supported for LDAP users. |
| 42 |
Provided authentication mechanism not supported. |
| 43 |
Multiple conflicting authentication mechanisms provided. |
| 44 |
Invalid API key. |
| 50 |
User is not authorized for the given operation. |
| 60 |
The trial period for the Subsonic server is over. Please upgrade to Subsonic Premium. Visit subsonic.org for details. |
| 70 |
The requested data was not found. |
6.20 - genre
A genre.
{
"songCount": 6,
"albumCount": 1,
"value": "Noise"
}
{
"songCount": 6,
"albumCount": 1,
"value": "Noise"
}
| Field |
Type |
Req. |
OpenS. |
Details |
value |
string |
Yes |
|
Genre name |
songCount |
int |
Yes |
|
Genre song count |
albumCount |
int |
Yes |
|
Genre album count |
6.21 - genres
Genres list.
{
"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 |
6.22 - Index
An indexed artist list.
{
"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 |
Yes |
|
Artist list |
6.23 - indexes
Artist list.
{
"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. |
OpenS. |
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 |
6.24 - IndexID3
An indexed artist list by ID3 tags.
{
"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 |
Yes |
|
Artist list |
6.25 - internetRadioStation
An internetRadioStation.
{
"id": "2",
"name": "HBR1.com - I.D.M. Tranceponder",
"streamUrl": "http://ubuntu.hbr1.com:19800/trance.ogg",
"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/"
}
| Field |
Type |
Req. |
OpenS. |
Details |
id |
string |
Yes |
|
The Id |
name |
string |
Yes |
|
The name |
streamUrl |
string |
Yes |
|
The radio url |
homePageUrl |
string |
No |
|
Genre name |
6.26 - internetRadioStations
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"
}
]
}
{
"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 |
Yes |
|
A list of internetRadioStation |
6.27 - ItemDate
A date for a media item that may be just a year, or year-month, or full date.
{
"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"/>
| 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.
6.28 - ItemGenre
A genre returned in list of genres for an item.
| Field |
Type |
Req. |
OpenS. |
Details |
name |
string |
Yes |
Yes |
Genre name |
OpenSubsonic
This is a new OpenSubsonic response type.
6.29 - jukeboxPlaylist
jukeboxPlaylist.
| Field |
Type |
Req. |
OpenS. |
Details |
6.30 - jukeboxStatus
jukeboxStatus.
| Field |
Type |
Req. |
OpenS. |
Details |
6.31 - license
getLicense result.
{
"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. |
OpenS. |
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] |
6.32 - line
One line of a song lyric
{
"start": 0,
"value": "It's bugging me"
}
<line start="0">It's bugging me</line>
| 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.
6.33 - lyrics
Lyrics.
{
"artist": "Metallica",
"title": "Blitzkrieg",
"value": "Let us have peace, let us have life\n\nLet us escape the cruel night\n\nLet us have time, let the sun shine\n\nLet us beware the deadly sign\n\n\n\nThe day is coming\n\nArmageddon's near\n\nInferno's coming\n\nCan we survive the blitzkrieg?\n\nThe blitzkrieg\n\nThe blitzkrieg\n\n\n\nSave us from fate, save us from hate\n\nSave ourselves before it's too late\n\nCome to our need, hear our plea\n\nSave ourselves before the earth bleeds\n\n\n\nThe day is dawning\n\nThe time is near\n\nAliens calling\n\nCan we survive the blitzkrieg?"
}
{
"artist": "Metallica",
"title": "Blitzkrieg",
"value": "Let us have peace, let us have life\n\nLet us escape the cruel night\n\nLet us have time, let the sun shine\n\nLet us beware the deadly sign\n\n\n\nThe day is coming\n\nArmageddon's near\n\nInferno's coming\n\nCan we survive the blitzkrieg?\n\nThe blitzkrieg\n\nThe blitzkrieg\n\n\n\nSave us from fate, save us from hate\n\nSave ourselves before it's too late\n\nCome to our need, hear our plea\n\nSave ourselves before the earth bleeds\n\n\n\nThe day is dawning\n\nThe time is near\n\nAliens calling\n\nCan we survive the blitzkrieg?"
}
| Field |
Type |
Req. |
OpenS. |
Details |
value |
string |
Yes |
|
The lyrics |
artist |
string |
No |
|
The artist name |
title |
string |
No |
|
The song title |
6.34 - lyricsList
List of structured lyrics
{
"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>
| 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.
6.35 - musicFolder
MusicFolder.
{
"id": "4",
"name": "upload"
}
{
"id": "4",
"name": "upload"
}
| Field |
Type |
Req. |
OpenS. |
Details |
id |
string |
Yes |
|
The id |
name |
string |
No |
|
The folder name |
6.36 - musicFolders
MusicFolders.
{
"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 |
Yes |
|
The folders |
6.37 - newestPodcasts
NewestPodcasts.
| Field |
Type |
Req. |
OpenS. |
Details |
6.38 - nowPlaying
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
}
]
}
{
"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 |
6.39 - NowPlayingEntry
NowPlayingEntry.
{
"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
}
{
"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 |
string |
Int |
|
Last update |
playerId |
boolean |
Int |
|
Player Id |
playerName |
string |
No |
|
Player name |
6.40 - OpenSubsonicExtension
A supported OpenSubsonic API extension.
{
"name": "template",
"versions": [
1,
2
]
}
| 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.
6.41 - playlist
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
}
{
"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 |
6.42 - playlists
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
}
]
}
{
"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 |
Yes |
|
A list of playlist |
6.43 - playlistWithSongs
Playlist with songs.
{
"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"
}
]
}
{
"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 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 |
entry |
Array of Child |
No |
|
The list of songs |
6.44 - PlayQueue
NowPlayingEntry.
| Field |
Type |
Req. |
OpenS. |
Details |
6.45 - podcasts
Podcasts.
| Field |
Type |
Req. |
OpenS. |
Details |
6.46 - randomSongs
RandomSongs list.
{
"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 |
6.47 - RecordLabel
A record label for an album.
| Field |
Type |
Req. |
OpenS. |
Details |
name |
string |
Yes |
Yes |
The record label name. |
OpenSubsonic
This is a new OpenSubsonic response type.
6.48 - ReplayGain
The replay gain data of a song.
{
"trackGain": 0.1,
"albumGain": 1.1,
"trackPeak": 9.2,
"albumPeak": 0,
"baseGain": 0,
"fallbackGain": -8.1
}
| 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 ommited in the answer. (But the replayGain field on Child must always be present)
OpenSubsonic
This is a new OpenSubsonic response type.
6.49 - scanStatus
Scan status information.
{
"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 |
6.50 - searchResult
searchResult.
| Field |
Type |
Req. |
OpenS. |
Details |
6.51 - searchResult2
searchResult2.
| Field |
Type |
Req. |
OpenS. |
Details |
6.52 - searchResult3
search3 result.
{
"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. |
OpenS. |
Details |
artist |
Array of ArtistID3 |
No |
|
Matching artists |
album |
Array of AlbumID3 |
No |
|
Matching albums |
song |
Array of Child |
No |
|
Matching songs |
6.53 - share
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"
}
]
}
{
"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 |
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 |
Yes |
|
A list of share |
6.54 - shares
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"
}
]
}
]
}
{
"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 |
Yes |
|
A list of share |
6.55 - similarSongs
SimilarSongs list.
{
"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 |
6.56 - similarSongs2
SimilarSongs2 list.
{
"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 |
6.57 - song
song.
| Field |
Type |
Req. |
OpenS. |
Details |
6.58 - songsByGenre
songsByGenre.
| Field |
Type |
Req. |
OpenS. |
Details |
6.59 - starred
starred.
| Field |
Type |
Req. |
OpenS. |
Details |
6.60 - starred2
starred2.
| Field |
Type |
Req. |
OpenS. |
Details |
6.61 - structuredLyrics
Structured lyrics
{
"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>
| Field |
Type |
Req. |
OpenS. |
Details |
lang |
string |
Yes |
Yes |
The lyrics language (ideally ISO 639). If the language is unknown (e.g. lrc file), the server must return und (ISO standard) or xxx (common value for taggers) |
synced |
boolean |
Yes |
Yes |
True if the lyrics are synced, false otherwise |
line |
Array of line |
Yes |
Yes |
The actual lyrics. Ordered by start time (synced) or appearance order (unsynced) |
displayArtist |
string |
No |
Yes |
The artist name to display. This could be the localized name, or any other value |
displayTitle |
string |
No |
Yes |
The title to display. This could be the song title (localized), or any other value |
offset |
number |
No |
Yes |
The offset to apply to all lyrics, in milliseconds. Positive means lyrics appear sooner, negative means later. If not included, the offset must be assumed to be 0 |
OpenSubsonic
This is a new OpenSubsonic response type.
6.62 - subsonic-response
Common answer wrapper.
{
"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:
type containing the server type/name (Ex: Navidrome or gonic). Mandatory to help clients adapt to actual Subsonic API support.serverVersion containing the server version (Ex: 1.2.3) this is different from the version field that expose the Subsonic API version. Mandatory for clients to be able to detect servers updates and check again supported OpenSubsonic extensions.openSubsonic must return true if the server support OpenSubsonic API v1
6.63 - tokenInfo
Information about an API key
{
"tokenInfo": {
"username": "token username"
}
}
<tokenInfo username="token username"></tokenInfo>
| Field |
Type |
Req. |
OpenS. |
Details |
username |
string |
Yes |
Yes |
Username associated with token |
6.64 - topSongs
TopSongs list.
{
"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 |
6.65 - user
user.
| Field |
Type |
Req. |
OpenS. |
Details |
6.66 - users
users.
| Field |
Type |
Req. |
OpenS. |
Details |
6.67 - videoInfo
videoInfo.
| Field |
Type |
Req. |
OpenS. |
Details |
6.68 - videos
videos.
| Field |
Type |
Req. |
OpenS. |
Details |
7 - OpenSubsonic API versions
OpenSubsonic API versions.
Versions
This table shows the supported extensions by OpenSubsonic versions:
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.
8 - Subsonic API versions
Subsonic API versions.
Versions
This table shows the REST API version implemented in different Subsonic versions:
Note that a Subsonic-compatible server is backward compatible with a REST client if and only if the major version is the same, and the minor version of the client is less than or equal to the server’s. For example, if the server has REST API version 2.2, it supports client versions 2.0, 2.1 and 2.2, but not versions 1.x, 2.3+ or 3.x. The third part of the version number is not used to determine compatibility.
OpenSubsonic
OpenSubsonic servers should support at least 1.14.0. It is not required to support version 1.16.1, but this is still highly recommended.