The Music Player Daemon protocolGeneral protocol syntaxProtocol overview
The MPD command protocol exchanges line-based text records
between client and server over TCP. Once the client is
connected to the server, they conduct a conversation until the
client closes the connection. The conversation flow is always
initiated by the client.
The client transmits a command sequence, terminated by the
newline character \n. The server will
respond with one or more lines, the last of which will be a
completion code.
When the client connects to the server, the server will answer
with the following line:
OK MPD version
where version is a version identifier such as
0.12.2. This version identifier is the version of the protocol
spoken, not the real version of the daemon. (There is no way to
retrieve this real version identifier from the connection.)
RequestsCOMMANDARG
If arguments contain spaces, they should be surrounded by double
quotation marks.
Argument strings are separated from the command and any other
arguments by linear white-space (' ' or '\t').
All data between the client and the server is encoded in
UTF-8. (Note: In UTF-8 all standard ansi characters, 0-127 are
the same as in standard ansi encoding. Also, no ansi character
appears in any multi-byte characters. So, you can use
standard C functions like strlen, and
strcpy just fine with UTF-8 encoded
strings. For example: OK encoded in
UTF-8 is simply OK. For more
information on UTF=8:
http://www.cl.cam.ac.uk/~mgk25/unicode.html#utf-8)
Responses
A command returns OK on completion or
ACK some error on failure. These
denote the end of command execution.
Failure responses
The nature of the error can be gleaned from the information
that follows the ACK.
ACK lines are of the form:
ACK [error@command_listNum] {current_command} message_text\n
These responses are generated by a call to
commandError. They contain four separate
terms. Let's look at each of them:
error: numeric value of one
of the ACK_ERROR constants defined
in ack.h.
command_listNum:
offset of the command that caused the error in a Command List.
An error will always cause a command list to terminate
at the command that causes the error.
current_command:
name of the command, in a Command List,
that was executing when the error occurred.
message_text:
some (hopefully) informative text that describes the
nature of the error.
foo
An example might help. Consider the following sequence
sent from the client to the server.
command_list_begin
volume 86
play 10240
status
command_list_end
The server responds with:
ACK [50@1] {play} song doesn't exist: "10240"
This tells us that the play command, which was the
second in the list (the first or only command is
numbered 0), failed with error 50. The number 50
translates to ACK_ERROR_NO_EXIST--the
song doesn't exist. This is reiterated by the message text
which also tells us which song doesn't exist.
Command lists
To facilitate faster adding of files etc. you can pass a list
of commands all at once using a command list. The command
list begins with command_list_begin or
command_list_ok_begin and ends with
command_list_end.
It does not execute any commands until the list has ended.
The return value is whatever the return for a list of commands
is. On success for all commands,
OK is returned. If a command
fails, no more commands are executed and the appropriate
ACK error is returned. If
command_list_ok_begin is used,
list_OK is returned for each
successful command executed in the command list.
Ranges
Some commands (e.g. delete)
allow specifying a range in the form
START:END (the END
item is not included in the range, similar to ranges in the
Python programming language). If END is
omitted, then the maximum possible value is assumed.
RecipesQueuing
Often, users run MPD with "random" enabled, but want to
be able to insert songs "before" the rest of the playlist.
That is commonly called "queuing".
MPD implements this by allowing the client to specify a
"priority" for each song in the playlist (commands prio and
prioid). A
higher priority means that the song is going to be played
before the other songs.
In "random" mode, MPD maintains an internal randomized
sequence of songs. In this sequence, songs with a higher
priority come first, and all songs with the same priority are
shuffled (by default, all songs are shuffled, because all have
the same priority "0"). When you increase the priority of a
song, it is moved to the front of the sequence according to
its new priority, but always after the current one. A song
that has been played already (it's "before" the current song
in that sequence) will only be scheduled for repeated playback
if its priority has become bigger than the priority of the
current song. Decreasing the priority of a song will moved it
farther to the end of the sequence. Changing the priority of
the current song has no effect on the sequence.
Command reference
For manipulating playlists and playing, there are two sets of
commands. One set uses the song id of a song in the playlist,
while another set uses the playlist position of the song. The
commands using song ids should be used instead of the commands
that manipulate and control playback based on playlist
position. Using song ids is a safer method when multiple
clients are interacting with MPD.
Querying MPD's statusclearerror
Clears the current error message in status (this is also
accomplished by any command that starts playback).
currentsong
Displays the song info of the current song (same song that
is identified in status).
idleSUBSYSTEMSIntroduced with MPD 0.14
Waits until there is a noteworthy change in one or more
of MPD's subsystems. As soon as there is one, it lists
all changed systems in a line in the format
changed: SUBSYSTEM, where
SUBSYSTEM is one of the following:
database: the song database
has been modified after update.
update: a database update
has started or finished. If the database was
modified during the update, the
database event is also
emitted.
stored_playlist: a stored
playlist has been modified, renamed, created or
deleted
playlist: the current
playlist has been modified
player: the player has been
started, stopped or seeked
mixer: the volume has been
changed
output: an audio output has
been enabled or disabled
options: options like
, ,
, replay gain
sticker: the sticker database
has been modified.
subscription: a client
has subscribed or unsubscribed to a channel
message: a message was
received on a channel this client is subscribed to;
this event is only emitted when the queue is empty
While a client is waiting for idle
results, the server disables timeouts, allowing a client
to wait for events as long as mpd runs. The
idle command can be canceled by
sending the command noidle (no other
commands are allowed). MPD will then leave
idle mode and print results
immediately; might be empty at this time.
If the optional SUBSYSTEMS argument is used,
MPD will only send notifications when something changed in
one of the specified subsytems.
status
Reports the current status of the player and the volume
level.
volume:
0-100repeat:
0 or 1random:
0 or 1single:
Introduced with MPD 0.150 or 1consume:
0 or 1playlist:
31-bit unsigned integer, the playlist
version numberplaylistlength:
integer, the length of the
playliststate:
play, stop, or pausesong:
playlist song number of the current
song stopped on or playing
songid:
playlist songid of the current song
stopped on or playing
nextsong:
playlist song number of the next
song to be played
nextsongid:
playlist songid of the next song
to be played
time:
total time elapsed (of current
playing/paused song)elapsed:
Introduced with MPD 0.16
Total time elapsed within the current song, but
with higher resolution.
bitrate:
instantaneous bitrate in
kbpsxfade:
crossfade in secondsmixrampdb:
mixramp threshold in dBmixrampdelay:
mixrampdelay in secondsaudio:
sampleRate:bits:channelsupdatings_db:
job iderror:
if there is an error, returns message
herestats
Displays statistics.
artists: number of artists
songs: number of albums
uptime: daemon uptime in seconds
db_playtime: sum of all song
times in the db
db_update: last db update in UNIX
time
playtime: time length of music played
Playback optionsconsumeSTATE
Sets consume state to STATE,
STATE should be 0 or 1.
When consume is activated, each song played is removed from playlist.
crossfadeSECONDS
Sets crossfading between songs.
mixrampdbdeciBels
Sets the threshold at which songs will be overlapped. Like crossfading but doesn't fade the track volume, just overlaps. The songs need to have MixRamp tags added by an external tool. 0dB is the normalized maximum volume so use negative values, I prefer -17dB. In the absence of mixramp tags crossfading will be used. See http://sourceforge.net/projects/mixramp
mixrampdelaySECONDS
Additional time subtracted from the overlap calculated by mixrampdb. A value of "nan" disables MixRamp overlapping and falls back to crossfading.
randomSTATE
Sets random state to STATE,
STATE should be 0 or 1.
repeatSTATE
Sets repeat state to STATE,
STATE should be 0 or 1.
setvolVOL
Sets volume to VOL, the range of
volume is 0-100.
singleSTATE
Sets single state to STATE,
STATE should be 0 or 1.
When single is activated, playback is stopped after current song, or
song is repeated if the 'repeat' mode is enabled.
replay_gain_modeMODE
Sets the replay gain mode. One of
off,
track,
album,
autoadded in MPD 0.16.
Changing the mode during playback may take several
seconds, because the new settings does not affect the
buffered data.
This command triggers the
options idle event.
replay_gain_status
Prints replay gain options. Currently, only the
variable replay_gain_mode is
returned.
Controlling playbacknext
Plays next song in the playlist.
pausePAUSE
Toggles pause/resumes playing, PAUSE is 0 or 1.
The use of pause command w/o the PAUSE argument is
deprecated.
playSONGPOS
Begins playing the playlist at song number
SONGPOS.
playidSONGID
Begins playing the playlist at song
SONGID.
previous
Plays previous song in the playlist.
seekSONGPOSTIME
Seeks to the position TIME (in
seconds) of entry SONGPOS in the
playlist.
seekidSONGIDTIME
Seeks to the position TIME (in
seconds) of song SONGID.
seekcurTIME
Seeks to the position TIME within the
current song. If prefixed by '+' or '-', then the time
is relative to the current playing position.
stop
Stops playing.
The current playlistaddURI
Adds the file URI to the playlist
(directories add recursively). URI
can also be a single file.
addidURIPOSITION
Adds a song to the playlist (non-recursive) and returns the song id.
URI is always a single file or
URL. For example:
addid "foo.mp3"
Id: 999
OK
clear
Clears the current playlist.
deletePOSSTART:END
Deletes a song from the playlist.
deleteidSONGID
Deletes the song SONGID from the
playlist
moveFROMSTART:ENDTO
Moves the song at FROM or range of songs
at START:END to TO
in the playlist.
Ranges are supported since MPD 0.15moveidFROMTO
Moves the song with FROM (songid) to
TO (playlist index) in the
playlist. If TO is negative, it
is relative to the current song in the playlist (if
there is one).
playlist
Displays the current playlist.
Do not use this, instead use playlistinfo.
playlistfindTAGNEEDLE
Finds songs in the current playlist with strict
matching.
playlistidSONGID
Displays a list of songs in the playlist.
SONGID is optional and specifies a
single song to display info for.
playlistinfoSONGPOSSTART:END
Displays a list of all songs in the playlist, or if the optional
argument is given, displays information only for the song
SONGPOS or the range of songs
START:ENDplaylistsearchTAGNEEDLE
Searches case-sensitively for partial matches in the
current playlist.
plchangesVERSION
Displays changed songs currently in the playlist since
VERSION.
To detect songs that were deleted at the end of the
playlist, use playlistlength returned by status command.
plchangesposidVERSION
Displays changed songs currently in the playlist since
VERSION. This function only
returns the position and the id of the changed song, not
the complete metadata. This is more bandwidth efficient.
To detect songs that were deleted at the end of the
playlist, use playlistlength returned by status command.
prioPRIORITYSTART:END
Set the priority of the specified songs. A higher
priority means that it will be played first when
"random" mode is enabled.
A priority is an integer between 0 and 255. The default
priority of new songs is 0.
prioidPRIORITYID
Same as prio,
but address the songs with their id.
shuffleSTART:END
Shuffles the current playlist.
START:END is optional and specifies
a range of songs.
swapSONG1SONG2
Swaps the positions of SONG1 and
SONG2.
swapidSONG1SONG2
Swaps the positions of SONG1 and
SONG2 (both song ids).
Stored playlists
Playlists are stored inside the configured playlist directory.
They are addressed with their file name (without the directory
and without the .m3u suffix).
Some of the commands described in this section can be used to
run playlist plugins instead of the hard-coded simple
m3u parser. They can access playlists in
the music directory (relative path including the suffix) or
remote playlists (absolute URI with a supported scheme).
listplaylistNAME
Lists the songs in the playlist. Playlist plugins are
supported.
listplaylistinfoNAME
Lists the songs with metadata in the playlist. Playlist
plugins are supported.
listplaylists
Prints a list of the playlist directory.
After each playlist name the server sends its last
modification time as attribute "Last-Modified" in ISO
8601 format. To avoid problems due to clock differences
between clients and the server, clients should not
compare this value with their local clock.
loadNAMESTART:END
Loads the playlist into the current queue. Playlist
plugins are supported. A range may be specified to load
only a part of the playlist.
playlistaddNAMEURI
Adds URI to the playlist
NAME.m3u.
NAME.m3u will be created if it does
not exist.
playlistclearNAME
Clears the playlist NAME.m3u.
playlistdeleteNAMESONGPOS
Deletes SONGPOS from the
playlist NAME.m3u.
playlistmoveNAMESONGIDSONGPOS
Moves SONGID in the playlist
NAME.m3u to the position
SONGPOS.
renameNAMENEW_NAME
Renames the playlist NAME.m3u to NEW_NAME.m3u.
rmNAME
Removes the playlist NAME.m3u from
the playlist directory.
saveNAME
Saves the current playlist to
NAME.m3u in the playlist directory.
The music databasecountTAGNEEDLE
Counts the number of songs and their total playtime in
the db matching TAG exactly.
findTYPEWHAT...
Finds songs in the db that are exactly
WHAT. TYPE can
be any tag supported by MPD, or one of the two special
parameters — file to search by
full path (relative to database root), and
any to match against all
available tags. WHAT is what to find.
findaddTYPEWHAT...
Finds songs in the db that are exactly
WHAT and adds them to current playlist.
Parameters have the same meaning as for find.
listTYPEARTIST
Lists all tags of the specified type.
TYPE can be any tag supported by MPD or
file.
ARTIST is an optional parameter when
type is album, this specifies to list albums by an
artist.
listallURI
Lists all songs and directories in
URI.
listallinfoURI
Same as listall, except it also
returns metadata info in the same format as
lsinfo.
lsinfoURI
Lists the contents of the directory
URI.
When listing the root directory, this currently returns
the list of stored playlists. This behavior is
deprecated; use "listplaylists" instead.
Clients that are connected via UNIX domain socket may
use this command to read the tags of an arbitrary local
file (URI beginning with "file:///").
searchTYPEWHAT...
Searches for any song that contains
WHAT. Parameters have the same meaning
as for find, except that search is not
case sensitive.
searchaddTYPEWHAT...
Searches for any song that contains WHAT
in tag TYPE and adds them to current playlist.
Parameters have the same meaning as for find,
except that search is not case sensitive.
searchaddplNAMETYPEWHAT...
Searches for any song that contains WHAT
in tag TYPE and adds them to the playlist
named NAME.
If a playlist by that name doesn't exist it is created.
Parameters have the same meaning as for find,
except that search is not case sensitive.
updateURI
Updates the music database: find new files, remove
deleted files, update modified files.
URI is a particular directory or
song/file to update. If you do not specify it,
everything is updated.
Prints "updating_db: JOBID" where
JOBID is a positive number
identifying the update job. You can read the current
job id in the status response.
rescanURI
Same as update, but also rescans
unmodified files.
Stickers
"Stickers" are pieces of
information attached to existing MPD objects (e.g. song files,
directories, albums). Clients can create arbitrary name/value
pairs. MPD itself does not assume any special meaning in
them.
The goal is to allow clients to share additional (possibly
dynamic) information about songs, which is neither stored on
the client (not available to other clients), nor stored in the
song files (MPD has no write access).
Client developers should create a standard for common sticker
names, to ensure interoperability.
Objects which may have stickers are addressed by their object
type ("song" for song objects) and their URI (the path within
the database for songs).
stickergetTYPEURINAME
Reads a sticker value for the specified object.
stickersetTYPEURINAMEVALUE
Adds a sticker value to the specified object. If a
sticker item with that name already exists, it is
replaced.
stickerdeleteTYPEURINAME
Deletes a sticker value from the specified object. If
you do not specify a sticker name, all sticker values
are deleted.
stickerlistTYPEURI
Lists the stickers for the specified object.
stickerfindTYPEURINAME
Searches the sticker database for stickers with the
specified name, below the specified directory (URI).
For each matching song, it prints the URI and that one
sticker's value.
Connection settingsclose
Closes the connection to MPD.
kill
Kills MPD.
passwordPASSWORD
This is used for authentication with the server.
PASSWORD is simply the plaintext
password.
ping
Does nothing but return "OK".
Audio output devicesdisableoutputID
Turns an output off.
enableoutputID
Turns an output on.
outputs
Shows information about all outputs.
Reflectionconfig
Dumps configuration values that may be interesting for
the client. This command is only permitted to "local"
clients (connected via UNIX domain socket).
The following response attributes are available:
Name
Description
music_directory
The absolute path of the music directory.
commands
Shows which commands the current user has access to.
notcommands
Shows which commands the current user does not have
access to.
tagtypes
Shows a list of available song metadata.
urlhandlers
Gets a list of available URL handlers.
decoders
Print a list of decoder plugins, followed by their
supported suffixes and MIME types. Example response:
plugin: mad
suffix: mp3
suffix: mp2
mime_type: audio/mpeg
plugin: mpcdec
suffix: mpcClient to client
Clients can communicate with each others over "channels". A
channel is created by a client subscribing to it. More than
one client can be subscribed to a channel at a time; all of
them will receive the messages which get sent to it.
Each time a client subscribes or unsubscribes, the global idle
event subscription is generated. In
conjunction with the channels command, this
may be used to auto-detect clients providing additional
services.
New messages are indicated by the message
idle event.
subscribeNAME
Subscribe to a channel. The channel is created if it
does not exist already. The name may consist of
alphanumeric ASCII characters plus underscore, dash, dot
and colon.
unsubscribeNAME
Unsubscribe from a channel.
channels
Obtain a list of all channels. The response is a list
of "channel:" lines.
readmessages
Reads messages for this client. The response is a list
of "channel:" and "message:" lines.
sendmessageCHANNELTEXT
Send a message to the specified channel.