MyFavMirrors/owntone-server
1
0
Fork 0
mirror of https://github.com/owntone/owntone-server.git synced 2025-05-04 16:56:45 -04:00
Code Issues Packages Projects Releases Wiki Activity

[docs] Fix spelling mistakes

Browse Source
This commit is contained in:
Alain Nussbaumer 2024-03-29 02:19:51 +01:00
parent eecd276aa3
commit ad2d0e0bba
1 changed files with 105 additions and 197 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

302
docs/json-api.md
View File

@ -3,12 +3,12 @@ hide:
- navigation - navigation
--- ---
# OwnTone API Endpoint Reference # API Endpoint Reference
Available API endpoints: Available API endpoints:
* [Player](#player): control playback, volume, shuffle/repeat modes * [Player](#player): control playback, volume, shuffle/repeat modes
* [Outputs / Speakers](#outputs-speakers): list available outputs and enable/disable outputs * [Outputs](#outputs): list available outputs and enable/disable outputs
* [Queue](#queue): list, add or modify the current queue * [Queue](#queue): list, add or modify the current queue
* [Library](#library): list playlists, artists, albums and tracks from your library or trigger library rescan * [Library](#library): list playlists, artists, albums and tracks from your library or trigger library rescan
* [Search](#search): search for playlists, artists, albums and tracks * [Search](#search): search for playlists, artists, albums and tracks
@ -18,10 +18,15 @@ Available API endpoints:
JSON-Object model: JSON-Object model:
* [Queue item](#queue-item-object)
* [Playlist](#playlist-object)
* [Artist](#artist-object)
* [Album](#album-object) * [Album](#album-object)
* [Artist](#artist-object)
* [Browse Info](#browse-info-object)
* [Category](#category-object)
* [Directory](#directory-object)
* [Option](#option-object)
* [Paging](#paging-object)
* [Playlist](#playlist-object)
* [Queue item](#queue-item-object)
* [Track](#track-object) * [Track](#track-object)
## Player ## Player
@ -37,8 +42,6 @@ JSON-Object model:
| PUT | [/api/player/volume](#set-volume) | Set master volume or volume for a specific output | | PUT | [/api/player/volume](#set-volume) | Set master volume or volume for a specific output |
| PUT | [/api/player/seek](#seek) | Seek to a position in the currently playing track | | PUT | [/api/player/seek](#seek) | Seek to a position in the currently playing track |
### Get player status ### Get player status
**Endpoint** **Endpoint**
@ -60,7 +63,6 @@ GET /api/player
| item_length_ms | integer | Total length in milliseconds of the current queue item | | item_length_ms | integer | Total length in milliseconds of the current queue item |
| item_progress_ms | integer | Progress into the current queue item in milliseconds | | item_progress_ms | integer | Progress into the current queue item in milliseconds |
**Example** **Example**
```shell ```shell
@ -80,7 +82,6 @@ curl -X GET "http://localhost:3689/api/player"
} }
``` ```
### Control playback ### Control playback
Start or resume, pause, stop playback. Start or resume, pause, stop playback.
@ -125,7 +126,6 @@ curl -X PUT "http://localhost:3689/api/player/stop"
curl -X PUT "http://localhost:3689/api/player/toggle" curl -X PUT "http://localhost:3689/api/player/toggle"
``` ```
### Skip tracks ### Skip tracks
Skip forward or backward Skip forward or backward
@ -154,7 +154,6 @@ curl -X PUT "http://localhost:3689/api/player/next"
curl -X PUT "http://localhost:3689/api/player/previous" curl -X PUT "http://localhost:3689/api/player/previous"
``` ```
### Set shuffle mode ### Set shuffle mode
Enable or disable shuffle mode Enable or disable shuffle mode
@ -171,7 +170,6 @@ PUT /api/player/shuffle
| --------------- | ----------------------------------------------------------- | | --------------- | ----------------------------------------------------------- |
| state | The new shuffle state, should be either `true` or `false` | | state | The new shuffle state, should be either `true` or `false` |
**Response** **Response**
On success returns the HTTP `204 No Content` success status response code. On success returns the HTTP `204 No Content` success status response code.
@ -182,7 +180,6 @@ On success returns the HTTP `204 No Content` success status response code.
curl -X PUT "http://localhost:3689/api/player/shuffle?state=true" curl -X PUT "http://localhost:3689/api/player/shuffle?state=true"
``` ```
### Set consume mode ### Set consume mode
Enable or disable consume mode Enable or disable consume mode
@ -199,7 +196,6 @@ PUT /api/player/consume
| --------------- | ----------------------------------------------------------- | | --------------- | ----------------------------------------------------------- |
| state | The new consume state, should be either `true` or `false` | | state | The new consume state, should be either `true` or `false` |
**Response** **Response**
On success returns the HTTP `204 No Content` success status response code. On success returns the HTTP `204 No Content` success status response code.
@ -210,7 +206,6 @@ On success returns the HTTP `204 No Content` success status response code.
curl -X PUT "http://localhost:3689/api/player/consume?state=true" curl -X PUT "http://localhost:3689/api/player/consume?state=true"
``` ```
### Set repeat mode ### Set repeat mode
Change repeat mode Change repeat mode
@ -227,7 +222,6 @@ PUT /api/player/repeat
| --------------- | ----------------------------------------------------------- | | --------------- | ----------------------------------------------------------- |
| state | The new repeat mode, should be either `off`, `all` or `single` | | state | The new repeat mode, should be either `off`, `all` or `single` |
**Response** **Response**
On success returns the HTTP `204 No Content` success status response code. On success returns the HTTP `204 No Content` success status response code.
@ -238,7 +232,6 @@ On success returns the HTTP `204 No Content` success status response code.
curl -X PUT "http://localhost:3689/api/player/repeat?state=all" curl -X PUT "http://localhost:3689/api/player/repeat?state=all"
``` ```
### Set volume ### Set volume
Change master volume or volume of a specific output. Change master volume or volume of a specific output.
@ -255,7 +248,7 @@ PUT /api/player/volume
| --------------- | ----------------------------------------------------------- | | --------------- | ----------------------------------------------------------- |
| volume | The new volume (0 - 100) | | volume | The new volume (0 - 100) |
| step | The increase or decrease volume by the given amount (-100 - 100) | | step | The increase or decrease volume by the given amount (-100 - 100) |
| output_id | *(Optional)* If an output id is given, only the volume of this output will be changed. If parameter is omited, the master volume will be changed. | | output_id | *(Optional)* If an output id is given, only the volume of this output will be changed. If parameter is omitted, the master volume will be changed. |
Either `volume` or `step` must be present as query parameter Either `volume` or `step` must be present as query parameter
@ -277,7 +270,6 @@ curl -X PUT "http://localhost:3689/api/player/volume?step=-5"
curl -X PUT "http://localhost:3689/api/player/volume?volume=50&output_id=0" curl -X PUT "http://localhost:3689/api/player/volume?volume=50&output_id=0"
``` ```
### Seek ### Seek
Seek to a position in the currently playing track. Seek to a position in the currently playing track.
@ -295,7 +287,6 @@ PUT /api/player/seek
| position_ms | The new position in milliseconds to seek to | | position_ms | The new position in milliseconds to seek to |
| seek_ms | A relative amount of milliseconds to seek to | | seek_ms | A relative amount of milliseconds to seek to |
**Response** **Response**
On success returns the HTTP `204 No Content` success status response code. On success returns the HTTP `204 No Content` success status response code.
@ -314,8 +305,7 @@ Relative seeking (skip 30 seconds backwards):
curl -X PUT "http://localhost:3689/api/player/seek?seek_ms=-30000" curl -X PUT "http://localhost:3689/api/player/seek?seek_ms=-30000"
``` ```
## Outputs
## Outputs / Speakers
| Method | Endpoint | Description | | Method | Endpoint | Description |
| --------- | ------------------------------------------------ | ------------------------------------ | | --------- | ------------------------------------------------ | ------------------------------------ |
@ -325,8 +315,6 @@ curl -X PUT "http://localhost:3689/api/player/seek?seek_ms=-30000"
| PUT | [/api/outputs/{id}](#change-an-output) | Change an output setting | | PUT | [/api/outputs/{id}](#change-an-output) | Change an output setting |
| PUT | [/api/outputs/{id}/toggle](#toggle-an-output) | Enable or disable an output, depending on the current state | | PUT | [/api/outputs/{id}/toggle](#toggle-an-output) | Enable or disable an output, depending on the current state |
### Get a list of available outputs ### Get a list of available outputs
**Endpoint** **Endpoint**
@ -354,7 +342,6 @@ GET /api/outputs
| needs_auth_key | boolean | `true` if output requires an authorization key (device verification) | | needs_auth_key | boolean | `true` if output requires an authorization key (device verification) |
| volume | integer | Volume in percent (0 - 100) | | volume | integer | Volume in percent (0 - 100) |
**Example** **Example**
```shell ```shell
@ -425,7 +412,6 @@ On success returns the HTTP `204 No Content` success status response code.
curl -X PUT "http://localhost:3689/api/outputs/set" --data "{\"outputs\":[\"198018693182577\",\"0\"]}" curl -X PUT "http://localhost:3689/api/outputs/set" --data "{\"outputs\":[\"198018693182577\",\"0\"]}"
``` ```
### Get an output ### Get an output
Get an output Get an output
@ -525,8 +511,6 @@ On success returns the HTTP `204 No Content` success status response code.
curl -X PUT "http://localhost:3689/api/outputs/0/toggle" curl -X PUT "http://localhost:3689/api/outputs/0/toggle"
``` ```
## Queue ## Queue
| Method | Endpoint | Description | | Method | Endpoint | Description |
@ -537,8 +521,6 @@ curl -X PUT "http://localhost:3689/api/outputs/0/toggle"
| PUT | [/api/queue/items/{id}\|now_playing](#updating-a-queue-item)| Updating a queue item in the queue | | PUT | [/api/queue/items/{id}\|now_playing](#updating-a-queue-item)| Updating a queue item in the queue |
| DELETE | [/api/queue/items/{id}](#removing-a-queue-item) | Remove a queue item from the queue | | DELETE | [/api/queue/items/{id}](#removing-a-queue-item) | Remove a queue item from the queue |
### List queue items ### List queue items
Lists the items in the current queue Lists the items in the current queue
@ -553,7 +535,7 @@ GET /api/queue
| Parameter | Value | | Parameter | Value |
| --------------- | ----------------------------------------------------------- | | --------------- | ----------------------------------------------------------- |
| id | *(Optional)* If a queue item id is given, only the item with the id will be returend. Use id=now_playing to get the currently playing item. | | id | *(Optional)* If a queue item id is given, only the item with the id will be returned. Use id=now_playing to get the currently playing item. |
| start | *(Optional)* If a `start`and an `end` position is given, only the items from `start` (included) to `end` (excluded) will be returned. If only a `start` position is given, only the item at this position will be returned. | | start | *(Optional)* If a `start`and an `end` position is given, only the items from `start` (included) to `end` (excluded) will be returned. If only a `start` position is given, only the item at this position will be returned. |
| end | *(Optional)* See `start` parameter | | end | *(Optional)* See `start` parameter |
@ -602,7 +584,6 @@ curl -X GET "http://localhost:3689/api/queue"
} }
``` ```
### Clearing the queue ### Clearing the queue
Remove all items form the current queue Remove all items form the current queue
@ -623,7 +604,6 @@ On success returns the HTTP `204 No Content` success status response code.
curl -X PUT "http://localhost:3689/api/queue/clear" curl -X PUT "http://localhost:3689/api/queue/clear"
``` ```
### Adding items to the queue ### Adding items to the queue
Add tracks, playlists artists or albums to the current queue Add tracks, playlists artists or albums to the current queue
@ -644,10 +624,10 @@ POST /api/queue/items/add
| playback | *(Optional)* If the `playback` parameter is set to `start`, playback will be started after adding the new items. | | playback | *(Optional)* If the `playback` parameter is set to `start`, playback will be started after adding the new items. |
| playback_from_position | *(Optional)* If the `playback` parameter is set to `start`, playback will be started with the queue item at the position given in `playback_from_position`. | | playback_from_position | *(Optional)* If the `playback` parameter is set to `start`, playback will be started with the queue item at the position given in `playback_from_position`. |
| clear | *(Optional)* If the `clear` parameter is set to `true`, the queue will be cleared before adding the new items. | | clear | *(Optional)* If the `clear` parameter is set to `true`, the queue will be cleared before adding the new items. |
| shuffle | *(Optional)* If the `shuffle` parameter is set to `true`, the shuffle mode is activated. If it is set to something else, the shuffle mode is deactivated. To leave the shuffle mode untouched the parameter should be ommited. | | shuffle | *(Optional)* If the `shuffle` parameter is set to `true`, the shuffle mode is activated. If it is set to something else, the shuffle mode is deactivated. To leave the shuffle mode untouched the parameter should be omitted. |
| limit | *(Optional)* Maximum number of tracks to add | | limit | *(Optional)* Maximum number of tracks to add |
Either the `uris` or the `expression` parameter must be set. If both are set the `uris` parameter takes presedence and the `expression` parameter will be ignored. Either the `uris` or the `expression` parameter must be set. If both are set the `uris` parameter takes precedence and the `expression` parameter will be ignored.
**Response** **Response**
@ -659,7 +639,6 @@ On success returns the HTTP `200 OK` success status response code.
| count | integer | Number of tracks added to the queue | | count | integer | Number of tracks added to the queue |
| items | array | Array of [`queue item`](#queue-item-object) objects added | | items | array | Array of [`queue item`](#queue-item-object) objects added |
**Example** **Example**
Add new items by uri: Add new items by uri:
@ -736,8 +715,9 @@ curl -X POST "http://localhost:3689/api/queue/items/add?expression=media_kind+is
} }
``` ```
Clear current queue, add 10 new random tracks of `genre` _Pop_ and start playback Clear current queue, add 10 new random tracks of `genre` *Pop* and start playback
```
```shell
curl -X POST "http://localhost:3689/api/queue/items/add?limit=10&clear=true&playback=start&expression=genre+is+%22Pop%22+order+by+random+desc" curl -X POST "http://localhost:3689/api/queue/items/add?limit=10&clear=true&playback=start&expression=genre+is+%22Pop%22+order+by+random+desc"
``` ```
@ -756,7 +736,9 @@ Update or move a queue item in the current queue
```http ```http
PUT /api/queue/items/{id} PUT /api/queue/items/{id}
``` ```
or or
```http ```http
PUT /api/queue/items/now_playing PUT /api/queue/items/now_playing
``` ```
@ -767,7 +749,7 @@ PUT /api/queue/items/now_playing
| --------------- | -------------------- | | --------------- | -------------------- |
| id | Queue item id | | id | Queue item id |
(or use now_playing to update the currenly playing track) (or use now_playing to update the track currently playing)
**Query parameters** **Query parameters**
@ -826,8 +808,6 @@ On success returns the HTTP `204 No Content` success status response code.
curl -X PUT "http://localhost:3689/api/queue/items/2" curl -X PUT "http://localhost:3689/api/queue/items/2"
``` ```
## Library ## Library
| Method | Endpoint | Description | | Method | Endpoint | Description |
@ -858,8 +838,6 @@ curl -X PUT "http://localhost:3689/api/queue/items/2"
| PUT | [/api/rescan](#trigger-metadata-rescan) | Trigger a library metadata rescan | | PUT | [/api/rescan](#trigger-metadata-rescan) | Trigger a library metadata rescan |
| PUT | [/api/library/backup](#backup-db) | Request library backup db | | PUT | [/api/library/backup](#backup-db) | Request library backup db |
### Library information ### Library information
List some library stats List some library stats
@ -882,7 +860,6 @@ GET /api/library
| updated_at | string | Last library update (timestamp in `ISO 8601` format) | | updated_at | string | Last library update (timestamp in `ISO 8601` format) |
| updating | boolean | `true` if library rescan is in progress | | updating | boolean | `true` if library rescan is in progress |
**Example** **Example**
```shell ```shell
@ -901,7 +878,6 @@ curl -X GET "http://localhost:3689/api/library"
} }
``` ```
### List playlists ### List playlists
Lists all playlists in your library (does not return playlist folders) Lists all playlists in your library (does not return playlist folders)
@ -928,7 +904,6 @@ GET /api/library/playlists
| offset | integer | Requested offset of the first playlist | | offset | integer | Requested offset of the first playlist |
| limit | integer | Requested maximum number of playlists | | limit | integer | Requested maximum number of playlists |
**Example** **Example**
```shell ```shell
@ -953,7 +928,6 @@ curl -X GET "http://localhost:3689/api/library/playlists"
} }
``` ```
### Get a playlist ### Get a playlist
Get a specific playlists in your library Get a specific playlists in your library
@ -974,7 +948,6 @@ GET /api/library/playlists/{id}
On success returns the HTTP `200 OK` success status response code. With the response body holding the **[`playlist`](#playlist-object) object**. On success returns the HTTP `200 OK` success status response code. With the response body holding the **[`playlist`](#playlist-object) object**.
**Example** **Example**
```shell ```shell
@ -991,7 +964,6 @@ curl -X GET "http://localhost:3689/api/library/playlists/1"
} }
``` ```
### Update a playlist ### Update a playlist
Update attributes of a specific playlists in your library Update attributes of a specific playlists in your library
@ -1014,14 +986,12 @@ PUT /api/library/playlists/{id}
| --------------- | ----------------------------------------------------------- | | --------------- | ----------------------------------------------------------- |
| query_limit | For RSS feeds, this sets how many podcasts to retrieve | | query_limit | For RSS feeds, this sets how many podcasts to retrieve |
**Example** **Example**
```shell ```shell
curl -X PUT "http://localhost:3689/api/library/playlists/25?query_limit=20" curl -X PUT "http://localhost:3689/api/library/playlists/25?query_limit=20"
``` ```
### Delete a playlist ### Delete a playlist
Delete a playlist, e.g. a RSS feed Delete a playlist, e.g. a RSS feed
@ -1044,7 +1014,6 @@ DELETE /api/library/playlists/{id}
curl -X DELETE "http://localhost:3689/api/library/playlists/25" curl -X DELETE "http://localhost:3689/api/library/playlists/25"
``` ```
### List playlist tracks ### List playlist tracks
Lists the tracks in a playlists Lists the tracks in a playlists
@ -1077,7 +1046,6 @@ GET /api/library/playlists/{id}/tracks
| offset | integer | Requested offset of the first track | | offset | integer | Requested offset of the first track |
| limit | integer | Requested maximum number of tracks | | limit | integer | Requested maximum number of tracks |
**Example** **Example**
```shell ```shell
@ -1139,7 +1107,6 @@ PUT /api/library/playlists/{id}/tracks
| --------------- | ----------------------------------------------------------- | | --------------- | ----------------------------------------------------------- |
| play_count | Either `increment`, `played` or `reset`. `increment` will increment `play_count` and update `time_played`, `played` will be like `increment` but only where `play_count` is 0, `reset` will set `play_count` and `skip_count` to zero and delete `time_played` and `time_skipped` | | play_count | Either `increment`, `played` or `reset`. `increment` will increment `play_count` and update `time_played`, `played` will be like `increment` but only where `play_count` is 0, `reset` will set `play_count` and `skip_count` to zero and delete `time_played` and `time_skipped` |
**Example** **Example**
```shell ```shell
@ -1180,7 +1147,6 @@ GET /api/library/playlists/{id}/playlists
| offset | integer | Requested offset of the first playlist | | offset | integer | Requested offset of the first playlist |
| limit | integer | Requested maximum number of playlist | | limit | integer | Requested maximum number of playlist |
**Example** **Example**
```shell ```shell
@ -1215,7 +1181,6 @@ curl -X GET "http://localhost:3689/api/library/playlists/0/tracks"
} }
``` ```
### List artists ### List artists
Lists the artists in your library Lists the artists in your library
@ -1242,7 +1207,6 @@ GET /api/library/artists
| offset | integer | Requested offset of the first artist | | offset | integer | Requested offset of the first artist |
| limit | integer | Requested maximum number of artists | | limit | integer | Requested maximum number of artists |
**Example** **Example**
```shell ```shell
@ -1269,7 +1233,6 @@ curl -X GET "http://localhost:3689/api/library/artists"
} }
``` ```
### Get an artist ### Get an artist
Get a specific artist in your library Get a specific artist in your library
@ -1290,7 +1253,6 @@ GET /api/library/artists/{id}
On success returns the HTTP `200 OK` success status response code. With the response body holding the **[`artist`](#artist-object) object**. On success returns the HTTP `200 OK` success status response code. With the response body holding the **[`artist`](#artist-object) object**.
**Example** **Example**
```shell ```shell
@ -1309,7 +1271,6 @@ curl -X GET "http://localhost:3689/api/library/artists/3815427709949443149"
} }
``` ```
### List artist albums ### List artist albums
Lists the albums of an artist Lists the albums of an artist
@ -1342,7 +1303,6 @@ GET /api/library/artists/{id}/albums
| offset | integer | Requested offset of the first album | | offset | integer | Requested offset of the first album |
| limit | integer | Requested maximum number of albums | | limit | integer | Requested maximum number of albums |
**Example** **Example**
```shell ```shell
@ -1370,7 +1330,6 @@ curl -X GET "http://localhost:3689/api/library/artists/32561671101664759/albums"
} }
``` ```
### List albums ### List albums
Lists the albums in your library Lists the albums in your library
@ -1397,7 +1356,6 @@ GET /api/library/albums
| offset | integer | Requested offset of the first albums | | offset | integer | Requested offset of the first albums |
| limit | integer | Requested maximum number of albums | | limit | integer | Requested maximum number of albums |
**Example** **Example**
```shell ```shell
@ -1425,7 +1383,6 @@ curl -X GET "http://localhost:3689/api/library/albums"
} }
``` ```
### Get an album ### Get an album
Get a specific album in your library Get a specific album in your library
@ -1446,7 +1403,6 @@ GET /api/library/albums/{id}
On success returns the HTTP `200 OK` success status response code. With the response body holding the **[`album`](#album-object) object**. On success returns the HTTP `200 OK` success status response code. With the response body holding the **[`album`](#album-object) object**.
**Example** **Example**
```shell ```shell
@ -1466,7 +1422,6 @@ curl -X GET "http://localhost:3689/api/library/albums/8009851123233197743"
} }
``` ```
### List album tracks ### List album tracks
Lists the tracks in an album Lists the tracks in an album
@ -1499,7 +1454,6 @@ GET /api/library/albums/{id}/tracks
| offset | integer | Requested offset of the first track | | offset | integer | Requested offset of the first track |
| limit | integer | Requested maximum number of tracks | | limit | integer | Requested maximum number of tracks |
**Example** **Example**
```shell ```shell
@ -1538,7 +1492,6 @@ curl -X GET "http://localhost:3689/api/library/albums/1/tracks"
} }
``` ```
### Get a track ### Get a track
Get a specific track in your library Get a specific track in your library
@ -1559,7 +1512,6 @@ GET /api/library/tracks/{id}
On success returns the HTTP `200 OK` success status response code. With the response body holding the **[`track`](#track-object) object**. On success returns the HTTP `200 OK` success status response code. With the response body holding the **[`track`](#track-object) object**.
**Example** **Example**
```shell ```shell
@ -1601,7 +1553,6 @@ curl -X GET "http://localhost:3689/api/library/tracks/1"
} }
``` ```
### List playlists for a track ### List playlists for a track
Get the list of playlists that contain a track (does not return smart playlists) Get the list of playlists that contain a track (does not return smart playlists)
@ -1658,7 +1609,6 @@ curl -X GET "http://localhost:3689/api/library/tracks/27/playlists"
} }
``` ```
### Update track properties ### Update track properties
Change properties of one or more tracks (supported properties are "rating", "play_count" and "usermark") Change properties of one or more tracks (supported properties are "rating", "play_count" and "usermark")
@ -1675,7 +1625,6 @@ PUT /api/library/tracks
| --------------- | -------- | ----------------------- | | --------------- | -------- | ----------------------- |
| tracks | array | Array of track objects | | tracks | array | Array of track objects |
**Response** **Response**
On success returns the HTTP `204 No Content` success status response code. On success returns the HTTP `204 No Content` success status response code.
@ -1706,7 +1655,6 @@ PUT /api/library/tracks/{id}
| play_count | Either `increment` or `reset`. `increment` will increment `play_count` and update `time_played`, `reset` will set `play_count` and `skip_count` to zero and delete `time_played` and `time_skipped` | | play_count | Either `increment` or `reset`. `increment` will increment `play_count` and update `time_played`, `reset` will set `play_count` and `skip_count` to zero and delete `time_played` and `time_skipped` |
| usermark | The new usermark (>= 0) | | usermark | The new usermark (>= 0) |
**Response** **Response**
On success returns the HTTP `204 No Content` success status response code. On success returns the HTTP `204 No Content` success status response code.
@ -1721,7 +1669,6 @@ curl -X PUT "http://localhost:3689/api/library/tracks/1?rating=100"
curl -X PUT "http://localhost:3689/api/library/tracks/1?play_count=increment" curl -X PUT "http://localhost:3689/api/library/tracks/1?play_count=increment"
``` ```
### List genres ### List genres
Get list of genres Get list of genres
@ -1731,6 +1678,7 @@ Get list of genres
```http ```http
GET /api/library/genres GET /api/library/genres
``` ```
**Response** **Response**
| Key | Type | Value | | Key | Type | Value |
@ -1740,7 +1688,6 @@ GET /api/library/genres
| offset | integer | Requested offset of the first genre | | offset | integer | Requested offset of the first genre |
| limit | integer | Requested maximum number of genres | | limit | integer | Requested maximum number of genres |
**Example** **Example**
```shell ```shell
@ -1770,7 +1717,6 @@ curl -X GET "http://localhost:3689/api/library/genres"
"offset": 0, "offset": 0,
"limit": -1 "limit": -1
} }
``` ```
### List albums for genre ### List albums for genre
@ -1800,7 +1746,6 @@ GET api/search?type=albums&expression=genre+is+\"{genre name}\""
| offset | integer | Requested offset of the first albums | | offset | integer | Requested offset of the first albums |
| limit | integer | Requested maximum number of albums | | limit | integer | Requested maximum number of albums |
**Example** **Example**
```shell ```shell
@ -1877,7 +1822,6 @@ GET /api/library/count
| albums | integer | Number of albums matching the expression | | albums | integer | Number of albums matching the expression |
| db_playtime | integer | Total playtime in milliseconds of all tracks matching the expression | | db_playtime | integer | Total playtime in milliseconds of all tracks matching the expression |
**Example** **Example**
```shell ```shell
@ -1893,12 +1837,10 @@ curl -X GET "http://localhost:3689/api/library/count?expression=data_kind+is+fil
} }
``` ```
### List local directories ### List local directories
List the local directories and the directory contents (tracks and playlists) List the local directories and the directory contents (tracks and playlists)
**Endpoint** **Endpoint**
```http ```http
@ -1919,7 +1861,6 @@ GET /api/library/files
| tracks | object | [`paging`](#paging-object) object containing [`track`](#track-object) objects that matches the `directory` | | tracks | object | [`paging`](#paging-object) object containing [`track`](#track-object) objects that matches the `directory` |
| playlists | object | [`paging`](#paging-object) object containing [`playlist`](#playlist-object) objects that matches the `directory` | | playlists | object | [`paging`](#paging-object) object containing [`playlist`](#playlist-object) objects that matches the `directory` |
**Example** **Example**
```shell ```shell
@ -1994,7 +1935,7 @@ curl -X GET "http://localhost:3689/api/library/files?directory=/music/srv"
### Add an item to the library ### Add an item to the library
This endpoint currently only supports addind RSS feeds. This endpoint currently only supports adding RSS feeds.
**Endpoint** **Endpoint**
@ -2052,7 +1993,7 @@ curl -X PUT "http://localhost:3689/api/update"
### Trigger metadata rescan ### Trigger metadata rescan
Trigger a library metadata rescan even if files have not been updated. Maintenence method. Trigger a library metadata rescan even if files have not been updated. Maintenance method.
**Endpoint** **Endpoint**
@ -2099,8 +2040,6 @@ curl -X PUT "http://localhost:3689/api/library/backup"
| GET | [/api/search](#search-by-search-term) | Search for playlists, artists, albums, tracks, composers by a simple search term | | GET | [/api/search](#search-by-search-term) | Search for playlists, artists, albums, tracks, composers by a simple search term |
| GET | [/api/search](#search-by-query-language) | Search by complex query expression | | GET | [/api/search](#search-by-query-language) | Search by complex query expression |
### Search by search term ### Search by search term
Search for playlists, artists, albums, tracks, composers that include the given query in their title (case insensitive matching). Search for playlists, artists, albums, tracks, composers that include the given query in their title (case insensitive matching).
@ -2131,7 +2070,6 @@ GET /api/search
| playlists | object | [`paging`](#paging-object) object containing [`playlist`](#playlist-object) objects that matches the `query` | | playlists | object | [`paging`](#paging-object) object containing [`playlist`](#playlist-object) objects that matches the `query` |
| composers | object | [`paging`](#paging-object) object containing `composers` objects that matches the `query` | | composers | object | [`paging`](#paging-object) object containing `composers` objects that matches the `query` |
**Example** **Example**
Search for all tracks, artists, albums and playlists that contain "the" in their title and return the first two results for each type: Search for all tracks, artists, albums and playlists that contain "the" in their title and return the first two results for each type:
@ -2272,7 +2210,6 @@ GET /api/search
| artists | object | [`paging`](#paging-object) object containing [`artist`](#artist-object) objects that matches the `query` | | artists | object | [`paging`](#paging-object) object containing [`artist`](#artist-object) objects that matches the `query` |
| albums | object | [`paging`](#paging-object) object containing [`album`](#album-object) objects that matches the `query` | | albums | object | [`paging`](#paging-object) object containing [`album`](#album-object) objects that matches the `query` |
**Example** **Example**
Search for music tracks ordered descending by the time added to the library and limit result to 2 items: Search for music tracks ordered descending by the time added to the library and limit result to 2 items:
@ -2281,15 +2218,12 @@ Search for music tracks ordered descending by the time added to the library and
curl -X GET "http://localhost:3689/api/search?type=tracks&expression=media_kind+is+music+order+by+time_added+desc&offset=0&limit=2" curl -X GET "http://localhost:3689/api/search?type=tracks&expression=media_kind+is+music+order+by+time_added+desc&offset=0&limit=2"
``` ```
## Server info ## Server info
| Method | Endpoint | Description | | Method | Endpoint | Description |
| --------- | ------------------------------------------------ | ------------------------------------ | | --------- | ------------------------------------------------ | ------------------------------------ |
| GET | [/api/config](#config) | Get configuration information | | GET | [/api/config](#config) | Get configuration information |
### Config ### Config
**Endpoint** **Endpoint**
@ -2306,7 +2240,6 @@ GET /api/config
| websocket_port | integer | Port number for the [websocket](#push-notifications) (or `0` if websocket is disabled) | | websocket_port | integer | Port number for the [websocket](#push-notifications) (or `0` if websocket is disabled) |
| buildoptions | array | Array of strings indicating which features are supported by the server | | buildoptions | array | Array of strings indicating which features are supported by the server |
**Example** **Example**
```shell ```shell
@ -2330,7 +2263,6 @@ curl -X GET "http://localhost:3689/api/config"
} }
``` ```
## Settings ## Settings
| Method | Endpoint | Description | | Method | Endpoint | Description |
@ -2341,8 +2273,6 @@ curl -X GET "http://localhost:3689/api/config"
| PUT | [/api/settings/{category-name}/{option-name}](#change-an-option-value) | Change the value of a setting option | | PUT | [/api/settings/{category-name}/{option-name}](#change-an-option-value) | Change the value of a setting option |
| DELETE | [/api/settings/{category-name}/{option-name}](#delete-an-option) | Reset a setting option to its default | | DELETE | [/api/settings/{category-name}/{option-name}](#delete-an-option) | Reset a setting option to its default |
### List categories ### List categories
List all settings categories with their options List all settings categories with their options
@ -2359,7 +2289,6 @@ GET /api/settings
| --------------- | -------- | ----------------------------------------- | | --------------- | -------- | ----------------------------------------- |
| categories | array | Array of settings [category](#category-object) objects | | categories | array | Array of settings [category](#category-object) objects |
**Example** **Example**
```shell ```shell
@ -2388,7 +2317,6 @@ curl -X GET "http://localhost:3689/api/settings"
} }
``` ```
### Get a category ### Get a category
Get a settings category with their options Get a settings category with their options
@ -2403,7 +2331,6 @@ GET /api/settings/{category-name}
Returns a settings [category](#category-object) object Returns a settings [category](#category-object) object
**Example** **Example**
```shell ```shell
@ -2428,7 +2355,6 @@ curl -X GET "http://localhost:3689/api/settings/webinterface"
} }
``` ```
### Get an option ### Get an option
Get a single settings option Get a single settings option
@ -2443,7 +2369,6 @@ GET /api/settings/{category-name}/{option-name}
Returns a settings [option](#option-object) object Returns a settings [option](#option-object) object
**Example** **Example**
```shell ```shell
@ -2458,7 +2383,6 @@ curl -X GET "http://localhost:3689/api/settings/webinterface/show_composer_now_p
} }
``` ```
### Change an option value ### Change an option value
Get a single settings option Get a single settings option
@ -2480,14 +2404,12 @@ PUT /api/settings/{category-name}/{option-name}
On success returns the HTTP `204 No Content` success status response code. On success returns the HTTP `204 No Content` success status response code.
**Example** **Example**
```shell ```shell
curl -X PUT "http://localhost:3689/api/settings/webinterface/show_composer_now_playing" --data "{\"name\":\"show_composer_now_playing\",\"value\":true}" curl -X PUT "http://localhost:3689/api/settings/webinterface/show_composer_now_playing" --data "{\"name\":\"show_composer_now_playing\",\"value\":true}"
``` ```
### Delete an option ### Delete an option
Delete a single settings option (thus resetting it to default) Delete a single settings option (thus resetting it to default)
@ -2502,14 +2424,12 @@ DELETE /api/settings/{category-name}/{option-name}
On success returns the HTTP `204 No Content` success status response code. On success returns the HTTP `204 No Content` success status response code.
**Example** **Example**
```shell ```shell
curl -X DELETE "http://localhost:3689/api/settings/webinterface/show_composer_now_playing" curl -X DELETE "http://localhost:3689/api/settings/webinterface/show_composer_now_playing"
``` ```
## Push notifications ## Push notifications
If the server was built with websocket support it exposes a websocket at `localhost:3688` to inform clients of changes (e. g. player state or library updates). If the server was built with websocket support it exposes a websocket at `localhost:3688` to inform clients of changes (e. g. player state or library updates).
@ -2560,9 +2480,89 @@ curl --include \
} }
``` ```
## Objects
## Object model ### `album` object
| Key | Type | Value |
| --------------- | -------- | ----------------------------------------- |
| id | string | Album id |
| name | string | Album name |
| name_sort | string | Album sort name |
| artist_id | string | Album artist id |
| artist | string | Album artist name |
| track_count | integer | Number of tracks |
| length_ms | integer | Total length of tracks in milliseconds |
| uri | string | Resource identifier |
| artwork_url | string | *(optional)* [Artwork url](#artwork-urls) |
### `artist` object
| Key | Type | Value |
| --------------- | -------- | ----------------------------------------- |
| id | string | Artist id |
| name | string | Artist name |
| name_sort | string | Artist sort name |
| album_count | integer | Number of albums |
| track_count | integer | Number of tracks |
| length_ms | integer | Total length of tracks in milliseconds |
| uri | string | Resource identifier |
| artwork_url | string | *(optional)* [Artwork url](#artwork-urls) |
### `browse-info` object
| Key | Type | Value |
| --------------- | -------- | ----------------------------------------- |
| name | string | Name (depends on the type of the query) |
| name_sort | string | Sort name |
| artist_count | integer | Number of artists |
| album_count | integer | Number of albums |
| track_count | integer | Number of tracks |
| time_played | string | Timestamp in `ISO 8601` format |
| time_added | string | Timestamp in `ISO 8601` format |
### `category` object
| Key | Type | Value |
| --------------- | -------- | ----------------------------------------- |
| name | string | Category name |
| options | array | Array of option in this category |
### `directory` object
| Key | Type | Value |
| --------------- | -------- | ----------------------------------------- |
| path | string | Directory path |
### `option` object
| Key | Type | Value |
| --------------- | -------- | ----------------------------------------- |
| name | string | Option name |
| type | integer | The type of the value for this option (`0`: integer, `1`: boolean, `2`: string) |
| value | (integer / boolean / string) | Current value for this option |
### `paging` object
| Key | Type | Value |
| --------------- | -------- | ----------------------------------------- |
| items | array | Array of result objects |
| total | integer | Total number of items |
| offset | integer | Requested offset of the first item |
| limit | integer | Requested maximum number of items |
### `playlist` object
| Key | Type | Value |
| --------------- | -------- | ----------------------------------------- |
| id | string | Playlist id |
| name | string | Playlist name |
| path | string | Path |
| parent_id | integer | Playlist id of the parent (folder) playlist |
| type | string | Type of this playlist: `special`, `folder`, `smart`, `plain` |
| smart_playlist | boolean | `true` if playlist is a smart playlist |
| folder | boolean | `true` if it is a playlist folder |
| uri | string | Resource identifier |
### `queue item` object ### `queue item` object
@ -2596,50 +2596,6 @@ curl --include \
| samplerate | string | file sample rate (ie 44100/48000/...) | | samplerate | string | file sample rate (ie 44100/48000/...) |
| channel | string | file channel (ie mono/stereo/xx ch)) | | channel | string | file channel (ie mono/stereo/xx ch)) |
### `playlist` object
| Key | Type | Value |
| --------------- | -------- | ----------------------------------------- |
| id | string | Playlist id |
| name | string | Playlist name |
| path | string | Path |
| parent_id | integer | Playlist id of the parent (folder) playlist |
| type | string | Type of this playlist: `special`, `folder`, `smart`, `plain` |
| smart_playlist | boolean | `true` if playlist is a smart playlist |
| folder | boolean | `true` if it is a playlist folder |
| uri | string | Resource identifier |
### `artist` object
| Key | Type | Value |
| --------------- | -------- | ----------------------------------------- |
| id | string | Artist id |
| name | string | Artist name |
| name_sort | string | Artist sort name |
| album_count | integer | Number of albums |
| track_count | integer | Number of tracks |
| length_ms | integer | Total length of tracks in milliseconds |
| uri | string | Resource identifier |
| artwork_url | string | *(optional)* [Artwork url](#artwork-urls) |
### `album` object
| Key | Type | Value |
| --------------- | -------- | ----------------------------------------- |
| id | string | Album id |
| name | string | Album name |
| name_sort | string | Album sort name |
| artist_id | string | Album artist id |
| artist | string | Album artist name |
| track_count | integer | Number of tracks |
| length_ms | integer | Total length of tracks in milliseconds |
| uri | string | Resource identifier |
| artwork_url | string | *(optional)* [Artwork url](#artwork-urls) |
### `track` object ### `track` object
| Key | Type | Value | | Key | Type | Value |
@ -2678,54 +2634,6 @@ curl --include \
| usermark | integer | User review marking of track (ranges from 0) | | usermark | integer | User review marking of track (ranges from 0) |
| lyrics | string | The lyrics if found either as LRC or plain text | | lyrics | string | The lyrics if found either as LRC or plain text |
### `paging` object
| Key | Type | Value |
| --------------- | -------- | ----------------------------------------- |
| items | array | Array of result objects |
| total | integer | Total number of items |
| offset | integer | Requested offset of the first item |
| limit | integer | Requested maximum number of items |
### `browse-info` object
| Key | Type | Value |
| --------------- | -------- | ----------------------------------------- |
| name | string | Name (depends on the type of the query) |
| name_sort | string | Sort name |
| artist_count | integer | Number of artists |
| album_count | integer | Number of albums |
| track_count | integer | Number of tracks |
| time_played | string | Timestamp in `ISO 8601` format |
| time_added | string | Timestamp in `ISO 8601` format |
### `directory` object
| Key | Type | Value |
| --------------- | -------- | ----------------------------------------- |
| path | string | Directory path |
### `category` object
| Key | Type | Value |
| --------------- | -------- | ----------------------------------------- |
| name | string | Category name |
| options | array | Array of option in this category |
### `option` object
| Key | Type | Value |
| --------------- | -------- | ----------------------------------------- |
| name | string | Option name |
| type | integer | The type of the value for this option (`0`: integer, `1`: boolean, `2`: string) |
| value | (integer / boolean / string) | Current value for this option |
### Artwork urls ### Artwork urls
Artwork urls in `queue item`, `artist`, `album` and `track` objects can be either relative urls or absolute urls to the artwork image. Artwork urls in `queue item`, `artist`, `album` and `track` objects can be either relative urls or absolute urls to the artwork image.