Lists on OpenSubsonic

getAlbumList

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

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

Returns a list of random, newest, highest rated etc. albums. Similar to the album lists on the home page of the Subsonic web interface.

Parameters

Parameter	Req.	Default	Comment
`type`	Yes		The list type. Must be one of the following: `random`, `newest`, `highest`, `frequent`, `recent`. Since 1.8.0 you can also use `alphabeticalByName` or `alphabeticalByArtist` to page through all albums alphabetically, and `starred` to retrieve starred albums. Since 1.10.1 you can use `byYear` and `byGenre` to list albums in a given year range or genre.
`size`	No	10	The number of albums to return. Max 500.
`offset`	No	0	The list offset. Useful if you for example want to page through the list of newest albums.
`fromYear`	Yes (if `type` is `byYear`)		The first year in the range. If `fromYear > toYear` a reverse chronological list is returned.
`toYear`	Yes (if `type` is `byYear`)		The last year in the range.
`genre`	Yes (if `type` is `byGenre`)		The name of the genre, e.g., “Rock”.
`musicFolderId`	No		(Since 1.11.0) Only return albums in the music folder with the given ID. See `getMusicFolders`.

Example

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

Result

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

getAlbumList2

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

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

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

Parameters

Parameter	Req.	Default	Comment
`type`	Yes		The list type. Must be one of the following: `random`, `newest`, `highest`, `frequent`, `recent`. Since 1.8.0 you can also use `alphabeticalByName` or `alphabeticalByArtist` to page through all albums alphabetically, and `starred` to retrieve starred albums. Since 1.10.1 you can use `byYear` and `byGenre` to list albums in a given year range or genre.
`size`	No	10	The number of albums to return. Max 500.
`offset`	No	0	The list offset. Useful if you for example want to page through the list of newest albums.
`fromYear`	Yes (if `type` is `byYear`)		The first year in the range. If `fromYear > toYear` a reverse chronological list is returned.
`toYear`	Yes (if `type` is `byYear`)		The last year in the range.
`genre`	Yes (if `type` is `byGenre`)		The name of the genre, e.g., “Rock”.
`musicFolderId`	No		(Since 1.11.0) Only return albums in the music folder with the given ID. See `getMusicFolders`.

Example

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

Result

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

getNowPlaying

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

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

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

Parameters

Takes no extra parameters.

Example

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

Result

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

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

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

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

OpenSubsonic

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

getRandomSongs

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

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

Returns random songs matching the given criteria.

Parameters

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

Example

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

Result

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

getSongsByGenre

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

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

Returns songs in a given genre.

Parameters

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

Example

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

Result

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

getStarred

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

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

Returns starred songs, albums and artists.

Parameters

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

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "starred": {
 "artist": [
 {
 "id": "100000002",
 "name": "Synthetic",
 "coverArt": "ar-100000002",
 "starred": "2021-02-22T05:54:18Z"
 }
 ],
 "album": [
 {
 "id": "200000021",
 "parent": "100000036",
 "album": "Forget and Remember",
 "title": "Forget and Remember",
 "name": "Forget and Remember",
 "isDir": true,
 "coverArt": "al-200000021",
 "songCount": 20,
 "created": "2021-07-22T02:09:31+00:00",
 "duration": 4248,
 "playCount": 0,
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "year": 2005,
 "genre": "Hip-Hop"
 }
 ],
 "song": [
 {
 "id": "082f435a363c32c57d5edb6a678a28d4",
 "parent": "e8a0685e3f3ec6f251649af2b58b8617",
 "isDir": false,
 "title": "\"polar expedition\"",
 "album": "Live at The Casbah - 2005-04-29",
 "artist": "The New Deal",
 "track": 4,
 "year": 2005,
 "coverArt": "mf-082f435a363c32c57d5edb6a678a28d4_6410b3ce",
 "size": 19866778,
 "contentType": "audio/flac",
 "suffix": "flac",
 "starred": "2023-03-27T09:45:27Z",
 "duration": 178,
 "bitRate": 880,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "path": "The New Deal/Live at The Casbah - 2005-04-29/04 - \"polar expedition\".flac",
 "playCount": 8,
 "discNumber": 1,
 "created": "2023-03-14T17:51:22.112827504Z",
 "albumId": "e8a0685e3f3ec6f251649af2b58b8617",
 "artistId": "97e0398acf63f9fb930d7d4ce209a52b",
 "type": "music",
 "isVideo": false
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "starred": {
 "artist": [
 {
 "id": "100000002",
 "name": "Synthetic",
 "coverArt": "ar-100000002",
 "starred": "2021-02-22T05:54:18Z"
 }
 ],
 "album": [
 {
 "id": "200000021",
 "parent": "100000036",
 "album": "Forget and Remember",
 "title": "Forget and Remember",
 "name": "Forget and Remember",
 "isDir": true,
 "coverArt": "al-200000021",
 "songCount": 20,
 "created": "2021-07-22T02:09:31+00:00",
 "duration": 4248,
 "playCount": 0,
 "artistId": "100000036",
 "artist": "Comfort Fit",
 "year": 2005,
 "genre": "Hip-Hop"
 }
 ],
 "song": [
 {
 "id": "082f435a363c32c57d5edb6a678a28d4",
 "parent": "e8a0685e3f3ec6f251649af2b58b8617",
 "isDir": false,
 "title": "\"polar expedition\"",
 "album": "Live at The Casbah - 2005-04-29",
 "artist": "The New Deal",
 "track": 4,
 "year": 2005,
 "coverArt": "mf-082f435a363c32c57d5edb6a678a28d4_6410b3ce",
 "size": 19866778,
 "contentType": "audio/flac",
 "suffix": "flac",
 "starred": "2023-03-27T09:45:27Z",
 "duration": 178,
 "bitRate": 880,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "path": "The New Deal/Live at The Casbah - 2005-04-29/04 - \"polar expedition\".flac",
 "playCount": 8,
 "discNumber": 1,
 "created": "2023-03-14T17:51:22.112827504Z",
 "albumId": "e8a0685e3f3ec6f251649af2b58b8617",
 "artistId": "97e0398acf63f9fb930d7d4ce209a52b",
 "type": "music",
 "isVideo": false
 }
 ]
 }
 }
}

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

getStarred2

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

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

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

Parameters

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

Example

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

Result

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

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "type": "AwesomeServerName",
 "serverVersion": "0.1.3 (tag)",
 "openSubsonic": true,
 "starred2": {
 "artist": [
 {
 "id": "37ec820ca7193e17040c98f7da7c4b51",
 "name": "2 Mello",
 "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
 "albumCount": 1,
 "userRating": 5,
 "artistImageUrl": "https://demo.org/image.jpg",
 "starred": "2017-04-11T10:42:50.842Z"
 }
 ],
 "album": [
 {
 "id": "ad0f112b6dcf83de5e9cae85d07f0d35",
 "name": "8-bit lagerfeuer",
 "artist": "pornophonique",
 "year": 2007,
 "coverArt": "al-ad0f112b6dcf83de5e9cae85d07f0d35_640a93a8",
 "starred": "2023-03-22T01:51:06Z",
 "duration": 1954,
 "playCount": 97,
 "genre": "Hip-Hop",
 "created": "2023-03-10T02:19:35.784818075Z",
 "artistId": "91c3901ac465b9efc439e4be4270c2b6",
 "songCount": 8
 }
 ],
 "song": [
 {
 "id": "082f435a363c32c57d5edb6a678a28d4",
 "parent": "e8a0685e3f3ec6f251649af2b58b8617",
 "isDir": false,
 "title": "\"polar expedition\"",
 "album": "Live at The Casbah - 2005-04-29",
 "artist": "The New Deal",
 "track": 4,
 "year": 2005,
 "coverArt": "mf-082f435a363c32c57d5edb6a678a28d4_6410b3ce",
 "size": 19866778,
 "contentType": "audio/flac",
 "suffix": "flac",
 "starred": "2023-03-27T09:45:27Z",
 "duration": 178,
 "bitRate": 880,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "path": "The New Deal/Live at The Casbah - 2005-04-29/04 - \"polar expedition\".flac",
 "playCount": 8,
 "discNumber": 1,
 "created": "2023-03-14T17:51:22.112827504Z",
 "albumId": "e8a0685e3f3ec6f251649af2b58b8617",
 "artistId": "97e0398acf63f9fb930d7d4ce209a52b",
 "type": "music",
 "isVideo": false
 }
 ]
 }
 }
}

{
 "subsonic-response": {
 "status": "ok",
 "version": "1.16.1",
 "starred2": {
 "artist": [
 {
 "id": "37ec820ca7193e17040c98f7da7c4b51",
 "name": "2 Mello",
 "coverArt": "ar-37ec820ca7193e17040c98f7da7c4b51_0",
 "albumCount": 1,
 "userRating": 5,
 "artistImageUrl": "https://demo.org/image.jpg",
 "starred": "2017-04-11T10:42:50.842Z"
 }
 ],
 "album": [
 {
 "id": "ad0f112b6dcf83de5e9cae85d07f0d35",
 "name": "8-bit lagerfeuer",
 "artist": "pornophonique",
 "year": 2007,
 "coverArt": "al-ad0f112b6dcf83de5e9cae85d07f0d35_640a93a8",
 "starred": "2023-03-22T01:51:06Z",
 "duration": 1954,
 "playCount": 97,
 "genre": "Hip-Hop",
 "created": "2023-03-10T02:19:35.784818075Z",
 "artistId": "91c3901ac465b9efc439e4be4270c2b6",
 "songCount": 8
 }
 ],
 "song": [
 {
 "id": "082f435a363c32c57d5edb6a678a28d4",
 "parent": "e8a0685e3f3ec6f251649af2b58b8617",
 "isDir": false,
 "title": "\"polar expedition\"",
 "album": "Live at The Casbah - 2005-04-29",
 "artist": "The New Deal",
 "track": 4,
 "year": 2005,
 "coverArt": "mf-082f435a363c32c57d5edb6a678a28d4_6410b3ce",
 "size": 19866778,
 "contentType": "audio/flac",
 "suffix": "flac",
 "starred": "2023-03-27T09:45:27Z",
 "duration": 178,
 "bitRate": 880,
 "bitDepth": 16,
 "samplingRate": 44100,
 "channelCount": 2,
 "path": "The New Deal/Live at The Casbah - 2005-04-29/04 - \"polar expedition\".flac",
 "playCount": 8,
 "discNumber": 1,
 "created": "2023-03-14T17:51:22.112827504Z",
 "albumId": "e8a0685e3f3ec6f251649af2b58b8617",
 "artistId": "97e0398acf63f9fb930d7d4ce209a52b",
 "type": "music",
 "isVideo": false
 }
 ]
 }
 }
}

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