Playlists on OpenSubsonic

createPlaylist

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

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

Creates (or updates) a playlist.

Parameters

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

Example

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

Result

Since 1.14.0

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

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

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

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

Before 1.14.0

An empty subsonic-response element on success.

createPlaylistFolder

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

OpenSubsonic version: 1

OpenSubsonic extension name playlistFolders (As returned by getOpenSubsonicExtensions)

http://your-server/rest/createPlaylistFolder

Creates a playlist folder in the authenticated user’s playlist organization.

Parameters

Parameter	Req.	OpenS.	Comment
`name`	Yes	Yes	The human-readable name of the playlist folder.
`parentId`	No	Yes	ID of the parent playlist folder. Omit to create a root-level folder.
`sortOrder`	No	Yes	Position among siblings, as a client-assigned integer. If omitted, the server assigns a position after the existing siblings.

A parentId that does not exist or belongs to another user’s tree returns error 70, so that a user cannot probe for folder IDs in other users’ trees. See the extension description for ordering semantics and error handling.

deletePlaylist

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

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

Deletes a saved playlist.

Parameters

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

Example

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

Result

An empty subsonic-response element on success.

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

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

deletePlaylistFolder

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

OpenSubsonic version: 1

OpenSubsonic extension name playlistFolders (As returned by getOpenSubsonicExtensions)

http://your-server/rest/deletePlaylistFolder

Deletes an empty folder from the authenticated user’s playlist organization.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`playlistFolderId`	Yes	Yes		ID of the playlist folder to delete.

The folder must contain no child folders and no playlists currently visible to the user. A server must return error 0 when the folder is not empty and must not implicitly delete or move its contents. A playlistFolderId that does not exist or belongs to another user’s tree returns error 70. See the extension description for the placement lifecycle and error handling.

getPlaylist

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

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

Returns a listing of files in a saved playlist.

Parameters

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

Example

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

Result

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

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

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

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

getPlaylistFolders

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

OpenSubsonic version: 1

OpenSubsonic extension name playlistFolders (As returned by getOpenSubsonicExtensions)

http://your-server/rest/getPlaylistFolders

Returns all folders in a user’s playlist organization as a flat list. Clients build the hierarchy by matching each folder’s parentId to another folder’s id, and place playlists using the playlistFolderId returned by getPlaylists.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`username`	No	Yes		If specified, return folders 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/getPlaylistFolders.view?u=demo&p=demo&v=1.16.1&c=AwesomeClientName&f=json

Result

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

getPlaylists

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

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

Returns all playlists a user is allowed to play.

Parameters

Parameter	Req.	OpenS.	Default	Comment
`username`	no			(Since 1.8.0) If specified, return playlists for this user rather than for the authenticated user. The authenticated user must have admin role if this parameter is used.

Example

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

Result

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

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

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

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

movePlaylist

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

OpenSubsonic version: 1

OpenSubsonic extension name playlistFolders (As returned by getOpenSubsonicExtensions)

http://your-server/rest/movePlaylist

Places playlists in the authenticated user’s playlist organization. This endpoint moves playlists into a folder or to the root and sets their position among siblings. It never modifies the playlists themselves, so it works on any playlist visible to the user, including shared, public, and readonly playlists owned by others.

Parameters

Parameter	Req.	OpenS.	Comment
`playlistId`	Yes	Yes	ID of the playlist to place. Multiple parameters allowed; playlists are placed in the order given.
`playlistFolderId`	No	Yes	ID of the destination folder. An empty value moves the playlists to the root. Omit to keep each playlist in its current location and only change its position.
`sortOrder`	No	Yes	Position among siblings, as a client-assigned integer. Multiple parameters allowed, paired in order with `playlistId` (as `time` pairs with `id` on `scrobble`). When omitted, moved playlists are placed after the existing contents of the destination.

At least one of playlistFolderId or sortOrder must be supplied; otherwise the server returns error 10. When sortOrder parameters are supplied, their count must match the number of playlistId parameters; otherwise the server returns error 10. See the extension description for ordering semantics and error handling.

updatePlaylist

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

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

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

Parameters

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

Example

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

Result

An empty subsonic-response element on success.

updatePlaylistFolder

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

OpenSubsonic version: 1

OpenSubsonic extension name playlistFolders (As returned by getOpenSubsonicExtensions)

http://your-server/rest/updatePlaylistFolder

Updates a folder in the authenticated user’s playlist organization: rename it, move it under another folder or to the root, or change its position among its siblings. Playlists are moved into and out of folders with movePlaylist.

Parameters

Parameter	Req.	OpenS.	Comment
`playlistFolderId`	Yes	Yes	ID of the playlist folder to update.
`name`	No	Yes	The new human-readable name.
`parentId`	No	Yes	ID of the new parent folder. An empty value moves the folder to the root. Omit to leave the parent unchanged.
`sortOrder`	No	Yes	New position among siblings, as a client-assigned integer.

At least one optional parameter must be supplied; otherwise the server returns error 10. A parentId that does not exist or belongs to another user’s tree returns error 70; a move that would create a cycle returns error 0. See the extension description for ordering semantics and error handling.