mirror of https://github.com/owntone/owntone-server.git synced 2024-12-26 07:05:57 -05:00

chme 694e1874ae [README] Update JSON API documentation (new endpoint for tracks, fix for

player/previous)

2019-01-31 09:42:53 +01:00

60 KiB

Raw Blame History

forked-daapd API Endpoint Reference

Available API endpoints:

Player: control playback, volume, shuffle/repeat modes
Outputs / Speakers: list available outputs and enable/disable outputs
Queue: list, add or modify the current queue
Library: list playlists, artists, albums and tracks from your library or trigger library rescan
Search: search for playlists, artists, albums and tracks
Server info: get server information
Push notifications: receive push notifications

JSON-Object model:

Queue item
Playlist
Artist
Album
Track

Player

Method	Endpoint	Description
GET	/api/player	Get player status
PUT	/api/player/play, /api/player/pause, /api/player/stop, /api/player/toggle	Start, pause or stop playback
PUT	/api/player/next, /api/player/previous	Skip forward or backward
PUT	/api/player/shuffle	Set shuffle mode
PUT	/api/player/consume	Set consume mode
PUT	/api/player/repeat	Set repeat mode
PUT	/api/player/volume	Set master volume or volume for a specific output
PUT	/api/player/seek	Seek to a position in the currently playing track

Get player status

Endpoint

GET /api/player

Response

Key	Type	Value
state	string	`play`, `pause` or `stop`
repeat	string	`off`, `all` or `single`
consume	boolean	`true` if consume mode is enabled
shuffle	boolean	`true` if shuffle mode is enabled
volume	integer	Master volume in percent (0 - 100)
item_id	integer	The current playing queue item `id`
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

Example

curl -X GET "http://localhost:3689/api/player"

{
  "state": "pause",
  "repeat": "off",
  "consume": false,
  "shuffle": false,
  "volume": 50,
  "item_id": 269,
  "item_length_ms": 278093,
  "item_progress_ms": 3674
}

Control playback

Start or resume, pause, stop playback.

Endpoint

PUT /api/player/play

PUT /api/player/pause

PUT /api/player/stop

PUT /api/player/toggle

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/play"

curl -X PUT "http://localhost:3689/api/player/pause"

curl -X PUT "http://localhost:3689/api/player/stop"

curl -X PUT "http://localhost:3689/api/player/toggle"

Skip tracks

Skip forward or backward

Endpoint

PUT /api/player/next

PUT /api/player/previous

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/next"

curl -X PUT "http://localhost:3689/api/player/previous"

Set shuffle mode

Enable or disable shuffle mode

Endpoint

PUT /api/player/shuffle

Query parameters

Parameter	Value
state	The new shuffle state, should be either `true` or `false`

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/shuffle?state=true"

Set consume mode

Enable or disable consume mode

Endpoint

PUT /api/player/consume

Query parameters

Parameter	Value
state	The new consume state, should be either `true` or `false`

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/consume?state=true"

Set repeat mode

Change repeat mode

Endpoint

PUT /api/player/repeat

Query parameters

Parameter	Value
state	The new repeat mode, should be either `off`, `all` or `single`

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/repeat?state=all"

Set volume

Change master volume or volume of a specific output.

Endpoint

PUT /api/player/volume

Query parameters

Parameter	Value
volume	The new volume (0 - 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.

Either volume or step must be present as query parameter

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/volume?volume=50"

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"

Seek

Seek to a position in the currently playing track.

Endpoint

PUT /api/player/seek

Query parameters

Parameter	Value
position_ms	The new position in milliseconds to seek to

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/player/seek?position_ms=2000"

Outputs / Speakers

Method	Endpoint	Description
GET	/api/outputs	Get a list of available outputs
PUT	/api/outputs/set	Set enabled outputs
GET	/api/outputs/{id}	Get an output
PUT	/api/outputs/{id}	Change an output (enable/disable or volume)

Get a list of available outputs

Endpoint

GET /api/outputs

Response

Key	Type	Value
outputs	array	Array of `output` objects

output object

Key	Type	Value
id	string	Output id
name	string	Output name
type	string	Type of the output: `AirPlay`, `Chromecast`, `ALSA`, `Pulseaudio`, `fifo`
selected	boolean	`true` if output is enabled
has_password	boolean	`true` if output is password protected
requires_auth	boolean	`true` if output requires authentication
needs_auth_key	boolean	`true` if output requires an authorization key (device verification)
volume	integer	Volume in percent (0 - 100)

Example

curl -X GET "http://localhost:3689/api/outputs"

{
  "outputs": [
    {
      "id": "123456789012345",
      "name": "kitchen",
      "type": "AirPlay",
      "selected": true,
      "has_password": false,
      "requires_auth": false,
      "needs_auth_key": false,
      "volume": 0
    },
    {
      "id": "0",
      "name": "Computer",
      "type": "ALSA",
      "selected": true,
      "has_password": false,
      "requires_auth": false,
      "needs_auth_key": false,
      "volume": 19
    },
    {
      "id": "100",
      "name": "daapd-fifo",
      "type": "fifo",
      "selected": false,
      "has_password": false,
      "requires_auth": false,
      "needs_auth_key": false,
      "volume": 0
    }
  ]
}

Set enabled outputs

Set the enabled outputs by passing an array of output ids. forked-daapd enables all outputs with the given ids and disables the remaining outputs.

Endpoint

PUT /api/outputs/set

Body parameters

Parameter	Type	Value
outputs	array	Array of output ids

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/outputs/set" --data "{\"outputs\":[\"198018693182577\",\"0\"]}"

Get an output

Endpoint

GET /api/outputs/{id}

Path parameters

Parameter	Value
id	Output id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the output object.

Example

curl -X GET "http://localhost:3689/api/outputs/0"

{
  "id": "0",
  "name": "Computer",
  "type": "ALSA",
  "selected": true,
  "has_password": false,
  "requires_auth": false,
  "needs_auth_key": false,
  "volume": 3
}

Change an output

Enable or disable an output and change its volume.

Endpoint

PUT /api/outputs/{id}

Path parameters

Parameter	Value
id	Output id

Body parameters

Parameter	Type	Value
selected	boolean	(Optional) `true` to enable and `false` to disable the output
volume	integer	(Optional) Volume in percent (0 - 100)

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/outputs/0" --data "{\"selected\":true, \"volume\": 50}"

Queue

Method	Endpoint	Description
GET	/api/queue	Get a list of queue items
PUT	/api/queue/clear	Remove all items from the queue
POST	/api/queue/items/add	Add items to the queue
PUT	/api/queue/items/{id}	Move a queue item in the queue
DELETE	/api/queue/items/{id}	Remove a queue item form the queue

List queue items

Lists the items in the current queue

Endpoint

GET /api/queue

Query parameters

Parameter	Value
id	(Optional) If a queue item id is given, only the item with the id will be returend.
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

Response

Key	Type	Value
version	integer	Version number of the current queue
count	integer	Number of items in the current queue
items	array	Array of `queue item` objects

Example

curl -X GET "http://localhost:3689/api/queue"

{
  "version": 833,
  "count": 20,
  "items": [
    {
      "id": 12122,
      "position": 0,
      "track_id": 10749,
      "title": "Angels",
      "artist": "The xx",
      "artist_sort": "xx, The",
      "album": "Coexist",
      "album_sort": "Coexist",
      "albumartist": "The xx",
      "albumartist_sort": "xx, The",
      "genre": "Indie Rock",
      "year": 2012,
      "track_number": 1,
      "disc_number": 1,
      "length_ms": 171735,
      "media_kind": "music",
      "data_kind": "file",
      "path": "/music/srv/The xx/Coexist/01 Angels.mp3",
      "uri": "library:track:10749"
    },
    ...
  ]
}

Clearing the queue

Remove all items form the current queue

Endpoint

PUT /api/queue/clear

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/queue/clear"

Adding items to the queue

Add tracks, playlists artists or albums to the current queue

Endpoint

POST /api/queue/items/add

Query parameters

Parameter	Value
uris	Comma seperated list of resource identifiers (`track`, `playlist`, `artist` or `album` object `uri`)
expression	A smart playlist query expression identifying the tracks that will be added to the queue.
position	(Optional) If a position is given, new items are inserted starting from this position into the queue.
playback	(Optional) If the `playback` parameter is set to `start`, playback will be started after 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.

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.

Response

On success returns the HTTP 200 OK success status response code.

Key	Type	Value
count	integer	number of tracks added to the queue

Example

Add new items by uri:

curl -X POST "http://localhost:3689/api/queue/items/add?uris=library:playlist:68,library:artist:2932599850102967727"

{
  "count": 42
}

Add new items by query language:

curl -X POST "http://localhost:3689/api/queue/items/add?expression=media_kind+is+music"

{
  "count": 42
}

Moving a queue item

Move a queue item in the current queue

Endpoint

PUT /api/queue/items/{id}

Path parameters

Parameter	Value
id	Queue item id

Query parameters

Parameter	Value
new_position	The new position for the queue item in the current queue.

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/queue/items/3?new_position=0"

Removing a queue item

Remove a queue item from the current queue

Endpoint

DELETE /api/queue/items/{id}

Path parameters

Parameter	Value
id	Queue item id

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X PUT "http://localhost:3689/api/queue/items/2"

Library

Method	Endpoint	Description
GET	/api/library	Get library information
GET	/api/library/playlists	Get a list of playlists
GET	/api/library/playlists/{id}	Get a playlist
GET	/api/library/playlists/{id}/tracks	Get list of tracks for a playlist
GET	/api/library/artists	Get a list of artists
GET	/api/library/artists/{id}	Get an artist
GET	/api/library/artists/{id}/albums	Get list of albums for an artist
GET	/api/library/albums	Get a list of albums
GET	/api/library/albums/{id}	Get an album
GET	/api/library/albums/{id}/tracks	Get list of tracks for an album
GET	/api/library/tracks/{id}	Get a track
PUT	/api/library/tracks/{id}	Update a tracks properties (rating, play_count)
GET	/api/library/genres	Get list of genres
GET	/api/library/count	Get count of tracks, artists and albums
GET	/api/library/files	Get list of directories in the local library
GET	/api/update	Trigger a library rescan

Library information

List some library stats

Endpoint

GET /api/library

Response

Key	Type	Value
songs	integer	Array of `playlist` objects
db_playtime	integer	Total playtime of all songs in the library
artists	integer	Number of album artists in the library
albums	integer	Number of albums in the library
started_at	string	Server startup time (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

Example

curl -X GET "http://localhost:3689/api/library"

{
  "songs": 217,
  "db_playtime": 66811,
  "artists": 9,
  "albums": 19,
  "started_at": "2018-11-19T19:06:08Z",
  "updated_at": "2018-11-19T19:06:16Z",
  "updating": false
}

List playlists

Lists the playlists in your library

Endpoint

GET /api/library/playlists

Query parameters

Parameter	Value
offset	(Optional) Offset of the first playlist to return
limit	(Optional) Maximum number of playlists to return

Response

Key	Type	Value
items	array	Array of `playlist` objects
total	integer	Total number of playlists in the library
offset	integer	Requested offset of the first playlist
limit	integer	Requested maximum number of playlists

Example

curl -X GET "http://localhost:3689/api/library/playlists"

{
  "items": [
    {
      "id": 1,
      "name": "radio",
      "path": "/music/srv/radio.m3u",
      "smart_playlist": false,
      "uri": "library:playlist:1"
    },
    ...
  ],
  "total": 20,
  "offset": 0,
  "limit": -1
}

Get a playlist

Get a specific playlists in your library

Endpoint

GET /api/library/playlists/{id}

Path parameters

Parameter	Value
id	Playlist id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the playlist object.

Example

curl -X GET "http://localhost:3689/api/library/playlists/1"

{
  "id": 1,
  "name": "radio",
  "path": "/music/srv/radio.m3u",
  "smart_playlist": false,
  "uri": "library:playlist:1"
}

List playlist tracks

Lists the tracks in a playlists

Endpoint

GET /api/library/playlists/{id}/tracks

Path parameters

Parameter	Value
id	Playlist id

Query parameters

Parameter	Value
offset	(Optional) Offset of the first track to return
limit	(Optional) Maximum number of tracks to return

Response

Key	Type	Value
items	array	Array of `track` objects
total	integer	Total number of tracks in the playlist
offset	integer	Requested offset of the first track
limit	integer	Requested maximum number of tracks

Example

curl -X GET "http://localhost:3689/api/library/playlists/1/tracks"

{
  "items": [
    {
      "id": 10766,
      "title": "Solange wir tanzen",
      "artist": "Heinrich",
      "artist_sort": "Heinrich",
      "album": "Solange wir tanzen",
      "album_sort": "Solange wir tanzen",
      "albumartist": "Heinrich",
      "albumartist_sort": "Heinrich",
      "genre": "Electronica",
      "year": 2014,
      "track_number": 1,
      "disc_number": 1,
      "length_ms": 223085,
      "play_count": 2,
      "skip_count": 1,
      "time_played": "2018-02-23T10:31:20Z",
      "media_kind": "music",
      "data_kind": "file",
      "path": "/music/srv/Heinrich/Solange wir tanzen/01 Solange wir tanzen.mp3",
      "uri": "library:track:10766"
    },
    ...
  ],
  "total": 20,
  "offset": 0,
  "limit": -1
}

List artists

Lists the artists in your library

Endpoint

GET /api/library/artists

Query parameters

Parameter	Value
offset	(Optional) Offset of the first artist to return
limit	(Optional) Maximum number of artists to return

Response

Key	Type	Value
items	array	Array of `artist` objects
total	integer	Total number of artists in the library
offset	integer	Requested offset of the first artist
limit	integer	Requested maximum number of artists

Example

curl -X GET "http://localhost:3689/api/library/artists"

{
  "items": [
    {
      "id": "3815427709949443149",
      "name": "ABAY",
      "name_sort": "ABAY",
      "album_count": 1,
      "track_count": 10,
      "length_ms": 2951554,
      "uri": "library:artist:3815427709949443149"
    },
    ...
  ],
  "total": 20,
  "offset": 0,
  "limit": -1
}

Get an artist

Get a specific artist in your library

Endpoint

GET /api/library/artists/{id}

Path parameters

Parameter	Value
id	Artist id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the artist object.

Example

curl -X GET "http://localhost:3689/api/library/artists/3815427709949443149"

{
  "id": "3815427709949443149",
  "name": "ABAY",
  "name_sort": "ABAY",
  "album_count": 1,
  "track_count": 10,
  "length_ms": 2951554,
  "uri": "library:artist:3815427709949443149"
}

List artist albums

Lists the albums of an artist

Endpoint

GET /api/library/artists/{id}/albums

Path parameters

Parameter	Value
id	Artist id

Query parameters

Parameter	Value
offset	(Optional) Offset of the first album to return
limit	(Optional) Maximum number of albums to return

Response

Key	Type	Value
items	array	Array of `album` objects
total	integer	Total number of albums of this artist
offset	integer	Requested offset of the first album
limit	integer	Requested maximum number of albums

Example

curl -X GET "http://localhost:3689/api/library/artists/32561671101664759/albums"

{
  "items": [
    {
      "id": "8009851123233197743",
      "name": "Add Violence",
      "name_sort": "Add Violence",
      "artist": "Nine Inch Nails",
      "artist_id": "32561671101664759",
      "track_count": 5,
      "length_ms": 1634961,
      "uri": "library:album:8009851123233197743"
    },
    ...
  ],
  "total": 20,
  "offset": 0,
  "limit": -1
}

List albums

Lists the albums in your library

Endpoint

GET /api/library/albums

Query parameters

Parameter	Value
offset	(Optional) Offset of the first album to return
limit	(Optional) Maximum number of albums to return

Response

Key	Type	Value
items	array	Array of `album` objects
total	integer	Total number of albums in the library
offset	integer	Requested offset of the first albums
limit	integer	Requested maximum number of albums

Example

curl -X GET "http://localhost:3689/api/library/albums"

{
  "items": [
    {
      "id": "8009851123233197743",
      "name": "Add Violence",
      "name_sort": "Add Violence",
      "artist": "Nine Inch Nails",
      "artist_id": "32561671101664759",
      "track_count": 5,
      "length_ms": 1634961,
      "uri": "library:album:8009851123233197743"
    },
    ...
  ],
  "total": 20,
  "offset": 0,
  "limit": -1
}

Get an album

Get a specific album in your library

Endpoint

GET /api/library/albums/{id}

Path parameters

Parameter	Value
id	Album id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the album object.

Example

curl -X GET "http://localhost:3689/api/library/albums/8009851123233197743"

{
  "id": "8009851123233197743",
  "name": "Add Violence",
  "name_sort": "Add Violence",
  "artist": "Nine Inch Nails",
  "artist_id": "32561671101664759",
  "track_count": 5,
  "length_ms": 1634961,
  "uri": "library:album:8009851123233197743"
}

List album tracks

Lists the tracks in an album

Endpoint

GET /api/library/albums/{id}/tracks

Path parameters

Parameter	Value
id	Album id

Query parameters

Parameter	Value
offset	(Optional) Offset of the first track to return
limit	(Optional) Maximum number of tracks to return

Response

Key	Type	Value
items	array	Array of `track` objects
total	integer	Total number of tracks
offset	integer	Requested offset of the first track
limit	integer	Requested maximum number of tracks

Example

curl -X GET "http://localhost:3689/api/library/albums/1/tracks"

{
  "items": [
    {
      "id": 10766,
      "title": "Solange wir tanzen",
      "artist": "Heinrich",
      "artist_sort": "Heinrich",
      "album": "Solange wir tanzen",
      "album_sort": "Solange wir tanzen",
      "albumartist": "Heinrich",
      "albumartist_sort": "Heinrich",
      "genre": "Electronica",
      "year": 2014,
      "track_number": 1,
      "disc_number": 1,
      "length_ms": 223085,
      "play_count": 2,
      "last_time_played": "2018-02-23T10:31:20Z",
      "media_kind": "music",
      "data_kind": "file",
      "path": "/music/srv/Heinrich/Solange wir tanzen/01 Solange wir tanzen.mp3",
      "uri": "library:track:10766"
    },
    ...
  ],
  "total": 20,
  "offset": 0,
  "limit": -1
}

Get a track

Get a specific track in your library

Endpoint

GET /api/library/tracks/{id}

Path parameters

Parameter	Value
id	Track id

Response

On success returns the HTTP 200 OK success status response code. With the response body holding the track object.

Example

curl -X GET "http://localhost:3689/api/library/track/1"

{
  "id": 1,
  "title": "Pardon Me",
  "title_sort": "Pardon Me",
  "artist": "Incubus",
  "artist_sort": "Incubus",
  "album": "Make Yourself",
  "album_sort": "Make Yourself",
  "album_id": "6683985628074308431",
  "album_artist": "Incubus",
  "album_artist_sort": "Incubus",
  "album_artist_id": "4833612337650426236",
  "composer": "Alex Katunich/Brandon Boyd/Chris Kilmore/Jose Antonio Pasillas II/Mike Einziger",
  "genre": "Alternative Rock",
  "year": 2001,
  "track_number": 12,
  "disc_number": 1,
  "length_ms": 223170,
  "rating": 0,
  "play_count": 0,
  "skip_count": 0,
  "time_added": "2019-01-20T11:58:29Z",
  "date_released": "2001-05-27",
  "seek_ms": 0,
  "media_kind": "music",
  "data_kind": "file",
  "path": "/music/srv/Incubus/Make Yourself/12 Pardon Me.mp3",
  "uri": "library:track:1",
  "artwork_url": "/artwork/item/1"
}

Update track properties

Change properties of a specific track (supported properties are "rating" and "play_count")

Endpoint

PUT /api/library/tracks/{id}

Path parameters

Parameter	Value
id	Track id

Query parameters

Parameter	Value
rating	The new rating (0 - 100)
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`

Response

On success returns the HTTP 204 No Content success status response code.

Example

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"

List genres

Get list of genres

Endpoint

GET /api/library/genres

Response

Key	Type	Value
items	array	Array of `genre` objects
total	integer	Total number of genres in the library
offset	integer	Requested offset of the first genre
limit	integer	Requested maximum number of genres

Example

curl -X GET "http://localhost:3689/api/library/genres"

{
  "items": [
    {
      "name": "Classical"
    },
    {
      "name": "Drum & Bass"
    },
    {
      "name": "Pop"
    },
    {
      "name": "Rock/Pop"
    },
    {
      "name": "'90s Alternative"
    }
  ],
  "total": 5,
  "offset": 0,
  "limit": -1
}

List albums for genre

Lists the albums in a genre

Endpoint

GET api/search?type=albums&expression=genre+is+\"{genre name}\""

Query parameters

Parameter	Value
genre	genre name (uri encoded and html esc seq for chars: '/&)
offset	(Optional) Offset of the first album to return
limit	(Optional) Maximum number of albums to return

Response

Key	Type	Value
items	array	Array of `album` objects
total	integer	Total number of albums in the library
offset	integer	Requested offset of the first albums
limit	integer	Requested maximum number of albums

Example

curl -X GET "http://localhost:3689/api/search?type=albums&expression=genre+is+\"Pop\""
curl -X GET "http://localhost:3689/api/search?type=albums&expression=genre+is+\"Rock%2FPop\""            # Rock/Pop
curl -X GET "http://localhost:3689/api/search?type=albums&expression=genre+is+\"Drum%20%26%20Bass\""     # Drum & Bass
curl -X GET "http://localhost:3689/api/search?type=albums&expression=genre+is+\"%2790s%20Alternative\""  # '90 Alternative

{
  "albums": {
    "items": [
      {
        "id": "320189328729146437",
        "name": "Best Ever",
        "name_sort": "Best Ever",
        "artist": "ABC",
        "artist_id": "8760559201889050080",
        "track_count": 1,
        "length_ms": 3631,
        "uri": "library:album:320189328729146437"
      },
      {
        "id": "7964595866631625723",
        "name": "Greatest Hits",
        "name_sort": "Greatest Hits",
        "artist": "Marvin Gaye",
        "artist_id": "5261930703203735930",
        "track_count": 2,
        "length_ms": 7262,
        "uri": "library:album:7964595866631625723"
      },
      {
        "id": "3844610748145176456",
        "name": "The Very Best of Etta",
        "name_sort": "Very Best of Etta",
        "artist": "Etta James",
        "artist_id": "2627182178555864595",
        "track_count": 1,
        "length_ms": 177926,
        "uri": "library:album:3844610748145176456"
      }
    ],
    "total": 3,
    "offset": 0,
    "limit": -1
  }
}

Get count of tracks, artists and albums

Get information about the number of tracks, artists and albums and the total playtime

Endpoint

GET /api/library/count

Query parameters

Parameter	Value
expression	(Optional) The smart playlist query expression, if this parameter is omitted returns the information for the whole library

Response

Key	Type	Value
tracks	integer	Number of tracks matching the expression
artists	integer	Number of artists matching the expression
albums	integer	Number of albums matching the expression
db_playtime	integer	Total playtime in milliseconds of all tracks matching the expression

Example

curl -X GET "http://localhost:3689/api/library/count?expression=data_kind+is+file"

{
  "tracks": 6811,
  "artists": 355,
  "albums": 646,
  "db_playtime": 1590767
}

List local directories

List the local directories and the directory contents (tracks and playlists)

Endpoint

GET /api/library/files

Query parameters

Parameter	Value
directory	(Optional) A path to a directory in your local library.

Response

Key	Type	Value
directories	array	Array of `directory` objects containing the sub directories
tracks	object	`paging` object containing `track` objects that matches the `directory`
playlists	object	`paging` object containing `playlist` objects that matches the `directory`

Example

curl -X GET "http://localhost:3689/api/library/files?directory=/music/srv"

{
  "directories": [
    {
      "path": "/music/srv/Audiobooks"
    },
    {
      "path": "/music/srv/Music"
    },
    {
      "path": "/music/srv/Playlists"
    },
    {
      "path": "/music/srv/Podcasts"
    }
  ],
  "tracks": {
    "items": [
      {
        "id": 1,
        "title": "input.pipe",
        "artist": "Unknown artist",
        "artist_sort": "Unknown artist",
        "album": "Unknown album",
        "album_sort": "Unknown album",
        "album_id": "4201163758598356043",
        "album_artist": "Unknown artist",
        "album_artist_sort": "Unknown artist",
        "album_artist_id": "4187901437947843388",
        "genre": "Unknown genre",
        "year": 0,
        "track_number": 0,
        "disc_number": 0,
        "length_ms": 0,
        "play_count": 0,
        "skip_count": 0,
        "time_added": "2018-11-24T08:41:35Z",
        "seek_ms": 0,
        "media_kind": "music",
        "data_kind": "pipe",
        "path": "/music/srv/input.pipe",
        "uri": "library:track:1",
        "artwork_url": "/artwork/item/1"
      }
    ],
    "total": 1,
    "offset": 0,
    "limit": -1
  },
  "playlists": {
    "items": [
      {
        "id": 8,
        "name": "radio",
        "path": "/music/srv/radio.m3u",
        "smart_playlist": true,
        "uri": "library:playlist:8"
      }
    ],
    "total": 1,
    "offset": 0,
    "limit": -1
  }
}

Trigger rescan

Trigger a library rescan

Endpoint

GET /api/update

Response

On success returns the HTTP 204 No Content success status response code.

Example

curl -X GET "http://localhost:3689/api/update"

{
  "songs": 217,
  "db_playtime": 66811,
  "artists": 9,
  "albums": 19,
  "started_at": "2018-11-19T19:06:08Z",
  "updated_at": "2018-11-19T19:06:16Z",
  "updating": false
}

Search

Method	Endpoint	Description
GET	/api/search	Search for playlists, artists, albums, tracks,genres by a simple search term
GET	/api/search	Search by complex query expression

Search by search term

Search for playlists, artists, albums, tracks, genres that include the given query in their title (case insensitive matching).

Endpoint

GET /api/search

Query parameters

Parameter	Value
query	The search keyword
type	Comma separated list of the result types (`playlist`, `artist`, `album`, `track`, `genre`)
media_kind	(Optional) Filter results by media kind (`music`, `movie`, `podcast`, `audiobook`, `musicvideo`, `tvshow`). Filter only applies to artist, album and track result types.
offset	(Optional) Offset of the first item to return for each type
limit	(Optional) Maximum number of items to return for each type

Response

Key	Type	Value
tracks	object	`paging` object containing `track` objects that matches the `query`
artists	object	`paging` object containing `artist` objects that matches the `query`
albums	object	`paging` object containing `album` objects that matches the `query`
playlists	object	`paging` object containing `playlist` objects that matches the `query`

Example

Search for all tracks, artists, albums and playlists that contain "the" in their title and return the first two results for each type:

curl -X GET "http://localhost:3689/api/search?type=tracks,artists,albums,playlists&query=the&offset=0&limit=2"

{
  "tracks": {
    "items": [
      {
        "id": 35,
        "title": "Another Love",
        "artist": "Tom Odell",
        "artist_sort": "Tom Odell",
        "album": "Es is was es is",
        "album_sort": "Es is was es is",
        "album_id": "6494853621007413058",
        "album_artist": "Various artists",
        "album_artist_sort": "Various artists",
        "album_artist_id": "8395563705718003786",
        "genre": "Singer/Songwriter",
        "year": 2013,
        "track_number": 7,
        "disc_number": 1,
        "length_ms": 251030,
        "play_count": 0,
        "media_kind": "music",
        "data_kind": "file",
        "path": "/music/srv/Compilations/Es is was es is/07 Another Love.m4a",
        "uri": "library:track:35"
      },
      {
        "id": 215,
        "title": "Away From the Sun",
        "artist": "3 Doors Down",
        "artist_sort": "3 Doors Down",
        "album": "Away From the Sun",
        "album_sort": "Away From the Sun",
        "album_id": "8264078270267374619",
        "album_artist": "3 Doors Down",
        "album_artist_sort": "3 Doors Down",
        "album_artist_id": "5030128490104968038",
        "genre": "Rock",
        "year": 2002,
        "track_number": 2,
        "disc_number": 1,
        "length_ms": 233278,
        "play_count": 0,
        "media_kind": "music",
        "data_kind": "file",
        "path": "/music/srv/Away From the Sun/02 Away From the Sun.mp3",
        "uri": "library:track:215"
      }
    ],
    "total": 14,
    "offset": 0,
    "limit": 2
  },
  "artists": {
    "items": [
      {
        "id": "8737690491750445895",
        "name": "The xx",
        "name_sort": "xx, The",
        "album_count": 2,
        "track_count": 25,
        "length_ms": 5229196,
        "uri": "library:artist:8737690491750445895"
      }
    ],
    "total": 1,
    "offset": 0,
    "limit": 2
  },
  "albums": {
    "items": [
      {
        "id": "8264078270267374619",
        "name": "Away From the Sun",
        "name_sort": "Away From the Sun",
        "artist": "3 Doors Down",
        "artist_id": "5030128490104968038",
        "track_count": 12,
        "length_ms": 2818174,
        "uri": "library:album:8264078270267374619"
      },
      {
        "id": "6835720495312674468",
        "name": "The Better Life",
        "name_sort": "Better Life",
        "artist": "3 Doors Down",
        "artist_id": "5030128490104968038",
        "track_count": 11,
        "length_ms": 2393332,
        "uri": "library:album:6835720495312674468"
      }
    ],
    "total": 3,
    "offset": 0,
    "limit": 2
  },
  "playlists": {
    "items": [],
    "total": 0,
    "offset": 0,
    "limit": 2
  }
}

Search by query language

Search for artists, albums, tracks by a smart playlist query expression (see README_SMARTPL.md for the expression syntax).

Endpoint

GET /api/search

Query parameters

Parameter	Value
expression	The smart playlist query expression
type	Comma separated list of the result types (`artist`, `album`, `track`
offset	(Optional) Offset of the first item to return for each type
limit	(Optional) Maximum number of items to return for each type

Response

Key	Type	Value
tracks	object	`paging` object containing `track` objects that matches the `query`
artists	object	`paging` object containing `artist` objects that matches the `query`
albums	object	`paging` object containing `album` objects that matches the `query`

Example

Search for music tracks ordered descending by the time added to the library and limit result to 2 items:

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

Method	Endpoint	Description
GET	/api/config	Get configuration information

Config

Endpoint

GET /api/config

Response

Key	Type	Value
version	string	forked-daapd server version
websocket_port	integer	Port number for the websocket (or `0` if websocket is disabled)
buildoptions	array	Array of strings indicating which features are supported by the forked-daapd server

Example

curl -X GET "http://localhost:3689/api/config"

{
  "websocket_port": 3688,
  "version": "25.0",
  "buildoptions": [
    "ffmpeg",
    "iTunes XML",
    "Spotify",
    "LastFM",
    "MPD",
    "Device verification",
    "Websockets",
    "ALSA"
  ]
}

Push notifications

If forked-daapd was built with websocket support, forked-daapd exposes a websocket at localhost:3688 to inform clients of changes (e. g. player state or library updates). The port depends on the forked-daapd configuration and can be read using the /api/config endpoint.

After connecting to the websocket, the client should send a message containing the event types it is interested in. After that forked-daapd will send a message each time one of the events occurred.

Message

Key	Type	Value
notify	array	Array of event types

Event types

Type	Description
update	Library update started or finished
database	Library database changed (new/modified/deleted tracks)
outputs	An output was enabled or disabled
player	Player state changes
options	Playback option changes (shuffle, repeat, consume mode)
volume	Volume changes
queue	Queue changes

Example

curl --include \
     --no-buffer \
     --header "Connection: Upgrade" \
     --header "Upgrade: websocket" \
     --header "Host: localhost:3688" \
     --header "Origin: http://localhost:3688" \
     --header "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
     --header "Sec-WebSocket-Version: 13" \
     --header "Sec-WebSocket-Protocol: notify" \
     http://localhost:3688/ \
     --data "{ \"notify\": [ \"player\" ] }"

{ 
  "notify": [
    "player"
  ]
}

Object model

`queue item` object

Key	Type	Value
id	string	Item id
position	integer	Position in the queue (starting with zero)
track_id	string	Track id
title	string	Title
artist	string	Track artist name
artist_sort	string	Track artist sort name
album	string	Album name
album_sort	string	Album sort name
album_artist	string	Album artist name
album_artist_sort	string	Album artist sort name
composer	string	Composer (optional)
genre	string	Genre
year	integer	Release year
track_number	integer	Track number
disc_number	integer	Disc number
length_ms	integer	Track length in milliseconds
media_kind	string	Media type of this track: `music`, `movie`, `podcast`, `audiobook`, `musicvideo`, `tvshow`
data_kind	string	Data type of this track: `file`, `url`, `spotify`, `pipe`
path	string	Path
uri	string	Resource identifier
artwork_url	string	(optional) Artwork url

`playlist` object

Key	Type	Value
id	string	Playlist id
name	string	Playlist name
path	string	Path
smart_playlist	boolean	`true` if playlist is a smart playlist
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

`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

`track` object

Key	Type	Value
id	string	Track id
title	string	Title
title_sort	string	Sort title
artist	string	Track artist name
artist_sort	string	Track artist sort name
album	string	Album name
album_sort	string	Album sort name
album_id	string	Album id
album_artist	string	Album artist name
album_artist_sort	string	Album artist sort name
album_artist_id	string	Album artist id
composer	string	Track composer
genre	string	Genre
year	integer	Release year
track_number	integer	Track number
disc_number	integer	Disc number
length_ms	integer	Track length in milliseconds
rating	integer	Track rating (ranges from 0 to 100)
play_count	integer	How many times the track was played
skip_count	integer	How many times the track was skipped
time_played	string	Timestamp in `ISO 8601` format
time_skipped	string	Timestamp in `ISO 8601` format
time_added	string	Timestamp in `ISO 8601` format
date_released	string	Date in the format `yyyy-mm-dd`
seek_ms	integer	Resume point in milliseconds (available only for podcasts and audiobooks)
media_kind	string	Media type of this track: `music`, `movie`, `podcast`, `audiobook`, `musicvideo`, `tvshow`
data_kind	string	Data type of this track: `file`, `stream`, `spotify`, `pipe`
path	string	Path
uri	string	Resource identifier
artwork_url	string	(optional) Artwork url

`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

`genre` object

Key	Type	Value
name	string	Name of genre

`directory` object

Key	Type	Value
path	string	Directory path

Artwork urls

Artwork urls in queue item, artist, album and track objects can be either relative urls or absolute urls to the artwork image. Absolute artwork urls are pointing to external artwork images (e. g. for radio streams that provide artwork metadata), while relative artwork urls are served from forked-daapd.

It is possible to add the query parameters maxwidth and/or maxheight to relative artwork urls, in order to get a smaller image (forked-daapd only scales down never up).

Note that even if a relative artwork url attribute is present, it is not guaranteed to exist.

60 KiB Raw Blame History

forked-daapd API Endpoint Reference

Player

Get player status

Control playback

Skip tracks

Set shuffle mode

Set consume mode

Set repeat mode

Set volume

Seek

Outputs / Speakers

Get a list of available outputs

Set enabled outputs

Get an output

Change an output

Queue

List queue items

Clearing the queue

Adding items to the queue

Moving a queue item

Removing a queue item

Library

Library information

List playlists

Get a playlist

List playlist tracks

List artists

Get an artist

List artist albums

List albums

Get an album

List album tracks

Get a track

Update track properties

List genres

List albums for genre

Get count of tracks, artists and albums

List local directories

Trigger rescan

Search

Search by search term

Search by query language

Server info

Config

Push notifications

Object model

queue item object

playlist object

artist object

album object

track object

paging object

genre object

directory object

Artwork urls

60 KiB

Raw Blame History

`queue item` object

`playlist` object

`artist` object

`album` object

`track` object

`paging` object

`genre` object

`directory` object