Endpoints
Generic endpoint
POST /api/v1/mpd
Content-Type: application/json
{ "command": "some mpd command" }
This is the endpoint that hands a command as is to MPD. The return is tha answer of MPD converted to JSON. For a list of commands, see mpds protocol specification.
For convenience, there are special endpoints for some commands (see below).
Responses from MPD are encoded in JSON wrapped in an outer object. Here is an example for an idle answer:
{
"success": true,
"type": "IdleAnswer",
"result": {
"changes": [
"player"
]
}
}
The outer object contains a field success
which indicates whether
the response was an OK from MPD. If MPD responded with an ACK this
is false. If it is true
, then there is a result
field containing
the payload of the MPD response. If it is false
, there is an ack
field that contains the JSON representation of MPD’s ACK response. An
additional type
field indicates which kind of response it is.
Websocket
Using the endpoint /api/v1/mpd
with a GET request allows to create a
websocket connection. This can be used to get notified about MPD
events and also to send commands (same json as above) to MPD using the
same connection. The websocket connection is directly connected to
MPD; the http server also uses only one connection to MPD for the
websocket.
When the websocket is opened, it responds with IdleAnswer
events or
with answers as results to sending some commands through the
websocket. A json decoder can (for example) check the type
field to
distinguish answer types.
Special Endpoints
These are just convenient endpoints to execute mpd commands. Each one corresponds to a single mpd command.
GET /api/v1/mpdspecial/search?tag=value&tag=value&range=0:2
This allows to use thesearch
andfind
command directly with an http GET request. You can specify multiple tag/value pairs to search for and a window range.GET /api/v1/mpdspecial/list?listtype=value&genre=Classical&track=2
Executes MPD’slist
command. Here thelisttype
is literal and means the tag to list values for. Optionally multiple tag/value pairs can be specified for filtering.GET /api/v1/mpdspecial/count?tag=value
Executes MPD’scount
command. There must be exactly one tag/value pair.GET /api/v1/mpdspecial/currentsong
Executes thecurrentsong
command.GET /api/v1/mpdspecial/status
Executes thestatus
command.GET /api/v1/mpdspecial/playlistinfo?pos=2&range=1:3
Returns the current playlist or only a part of it ifpos
orrange
are specified. If both are given, thenpos
wins.GET /api/v1/mpdspecial/listplaylists
Lists all stored playlists.
Cover and Booklet files
There are endpoints that deliver cover art or booklet files for an
album. One takes a song file and tries to find the corresponding cover
image. The other takes an album name and looks up a file using MDP
find
command and uses it to look up the cover or booklet file.
GET /api/v1/cover/album?name=<albumName>[&size=<sz>]
GET /api/v1/cover/file/<file-uri.flac>[?size=<sz>]
GET /api/v1/booklet/album?name=<albumName>
GET /api/v1/booklet/file/<file-uri.flac>
The cover or booklet is expected to be a file next to the songs in a
directory. Some names are tried (which can be
configured), while cover.jpg
(and
booklet.pdf
, respectively) is the default (it is tried first). For
this to work, you need to configure the same music directory as in
your MPD config file. The cover images and booklet files are delivered
directly from the file system and are not requested from MPD.
For cover art, a size
parameter can be specified. If this is
present, the cover art is resized (if it exceeds size
) and a squared
thumbnail of the given size is returned. The thumbnail is created on
the fly and stored on the file system, so it might take a while when
requesting for the first time. Keep in mind that this slows down the
library page a lot on first access. But once all the thumbnails are
created, they are then served from the file system and everything goes
pretty fast. If you don’t like this feature, you can turn it off
“globally” in the configuration file; the size
parameter is then ignored and all clients receive the original cover
art file. If an error occurs during resizing, it is logged and the
original file is returned. Please see the config
file for how to configure this feature. Also note
that the directory of thumbnails is not cleaned up automatically.
If you have your cover art only inside each song, then currently that is not supported. You could simply export all of them into its own file; for example for flac files:
find /music/dir -name "*.flac" -printf "%h\n" | uniq | while read f;
do
cover="$f/cover.jpg"
flac=$(ls -1 $f/*.flac | head -n1)
if ! [ -r "$cover" ]; then
echo "$f"
metaflac --export-picture-to="$cover" "$flac"
fi
done
Note that this script assumes that every song in a folder belongs to the same album and shares the same cover art!
Missing Covers
A missing cover is replaced by a generated image from robohash using the album name as input. This way you get unique images per album.
Cache
When looking for cover art for an album, one song of that album is requested from mpd and then its directory is searched for a cover file. Since this always requires a call to mpd, the final paths to a cover file are cached in memory. The assumption is, that these files don’t change (often). If they do, there is an endpoint to clear the cache:
POST /api/v1/cover/clearcache
So after startup the first load of all album covers takes a while; but this should then speed up significantly.
Cover images are by default resized. This is faster when there are high qualitiy cover art, since all resized images are cached once they are created.
Booklets and covers share the same cache. So while there is the same
route for booklets (/api/v1/booklet/clearcache
), they have an
identical effect.
Multiple MPD connections
If multiple mpd connections are configured, they are available using
its id after the usual endpoint ends. For example, /api/v1/mpd
would
be /api/v1/mpd/myid
, or /api/v1/mpdspecial/currentsong
would be
/api/v1/mpdspecial/myid/currentsong
. The connection with id
default
(which is mandatory) is always reachable at the “default”
endpoints; additionally to its concrete form. For example, both
endpoints:
/api/v1/mpd
and/api/v1/mpd/default
are the same.
Custom data
If you like to serve some static content, it is possible by
configuring a custom endpoint. Simply specify a directory and
everything below that is served at the /custom/
endpoint.