# The Music Player Daemon protocol

## General protocol syntax

### Protocol 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.)

### Requests

            COMMAND
            ARG

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.

## Recipes

### Queuing

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 status

                  clearerror

  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).

                  idle
                  SUBSYSTEMS

  Introduced 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 `repeat`, `random`, `crossfade`, 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-100

  - `repeat`: 0 or 1

  - `random`: 0 or 1

  - `single`: Introduced with MPD 0.15 0 or 1

  - `consume`: 0 or 1

  - `playlist`: 31-bit unsigned integer, the playlist version number

  - `playlistlength`: integer, the length of the playlist

  - `state`: play, stop, or pause

  - `song`: 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 kbps

  - `xfade`: crossfade in seconds

  - `mixrampdb`: mixramp threshold in dB

  - `mixrampdelay`: mixrampdelay in seconds

  - `audio`: sampleRate:bits:channels

  - `updating_db`: job id

  - `error`: if there is an error, returns message here

                  stats

  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 options

                  consume
                  STATE

  Sets consume state to `STATE`, `STATE` should be 0 or 1. When consume is activated, each song played is removed from playlist.

                  crossfade
                  SECONDS

  Sets crossfading between songs.

                  mixrampdb
                  deciBels

  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

                  mixrampdelay
                  SECONDS

  Additional time subtracted from the overlap calculated by mixrampdb. A value of "nan" disables MixRamp overlapping and falls back to crossfading.

                  random
                  STATE

  Sets random state to `STATE`, `STATE` should be 0 or 1.

                  repeat
                  STATE

  Sets repeat state to `STATE`, `STATE` should be 0 or 1.

                  setvol
                  VOL

  Sets volume to `VOL`, the range of volume is 0-100.

                  single
                  STATE

  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_mode
                  MODE

  Sets the replay gain mode. One of `off`, `track`, `album`, `auto` added 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 playback

                  next

  Plays next song in the playlist.

                  pause
                  PAUSE

  Toggles pause/resumes playing, `PAUSE` is 0 or 1.

  The use of pause command w/o the PAUSE argument is deprecated.

                  play
                  SONGPOS

  Begins playing the playlist at song number `SONGPOS`.

                  playid
                  SONGID

  Begins playing the playlist at song `SONGID`.

                  previous

  Plays previous song in the playlist.

                  seek
                  SONGPOS
                  TIME

  Seeks to the position `TIME` (in seconds) of entry `SONGPOS` in the playlist.

                  seekid
                  SONGID
                  TIME

  Seeks to the position `TIME` (in seconds) of song `SONGID`.

                  seekcur
                  TIME

  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 playlist

                  add
                  URI

  Adds the file `URI` to the playlist (directories add recursively). `URI` can also be a single file.

                  addid
                  URI
                  POSITION

  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.

                  delete

                    POS
                    START:END

  Deletes a song from the playlist.

                  deleteid
                  SONGID

  Deletes the song `SONGID` from the playlist

                  move

                      FROM
                      START:END

                  TO

  Moves the song at `FROM` or range of songs at `START:END` to `TO` in the playlist. Ranges are supported since MPD 0.15

                  moveid
                  FROM
                  TO

  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`.

                  playlistfind
                  TAG
                  NEEDLE

  Finds songs in the current playlist with strict matching.

                  playlistid
                  SONGID

  Displays a list of songs in the playlist. `SONGID` is optional and specifies a single song to display info for.

                  playlistinfo

                      SONGPOS
                      START: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:END`

                  playlistsearch
                  TAG
                  NEEDLE

  Searches case-sensitively for partial matches in the current playlist.

                  plchanges
                  VERSION

  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.

                  plchangesposid
                  VERSION

  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.

                  prio
                  PRIORITY
                  START: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.

                  prioid
                  PRIORITY
                  ID

  Same as `prio`, but address the songs with their id.

                  shuffle
                  START:END

  Shuffles the current playlist. `START:END` is optional and specifies a range of songs.

                  swap
                  SONG1
                  SONG2

  Swaps the positions of `SONG1` and `SONG2`.

                  swapid
                  SONG1
                  SONG2

  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).

                  listplaylist
                  NAME

  Lists the songs in the playlist. Playlist plugins are supported.

                  listplaylistinfo
                  NAME

  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.

                  load
                  NAME
                  START: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.

                  playlistadd
                  NAME
                  URI

  Adds `URI` to the playlist `NAME.m3u`.

  `NAME.m3u` will be created if it does not exist.

                  playlistclear
                  NAME

  Clears the playlist `NAME.m3u`.

                  playlistdelete
                  NAME
                  SONGPOS

  Deletes `SONGPOS` from the playlist `NAME.m3u`.

                  playlistmove
                  NAME
                  SONGID
                  SONGPOS

  Moves `SONGID` in the playlist `NAME.m3u` to the position `SONGPOS`.

                  rename
                  NAME
                  NEW_NAME

  Renames the playlist `NAME.m3u` to `NEW_NAME.m3u`.

                  rm
                  NAME

  Removes the playlist `NAME.m3u` from the playlist directory.

                  save
                  NAME

  Saves the current playlist to `NAME.m3u` in the playlist directory.

### The music database

                  count
                  TAG
                  NEEDLE

  Counts the number of songs and their total playtime in the db matching `TAG` exactly.

                  find
                  TYPE
                  WHAT
                  ...

  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.

                  findadd
                  TYPE
                  WHAT
                  ...

  Finds songs in the db that are exactly `WHAT` and adds them to current playlist. Parameters have the same meaning as for `find`.

                  list
                  TYPE
                  ARTIST

  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.

                  listall
                  URI

  Lists all songs and directories in `URI`.

                  listallinfo
                  URI

  Same as `listall`, except it also returns metadata info in the same format as `lsinfo`.

                  lsinfo
                  URI

  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:///").

                  search
                  TYPE
                  WHAT
                  ...

  Searches for any song that contains `WHAT`. Parameters have the same meaning as for `find`, except that search is not case sensitive.

                  searchadd
                  TYPE
                  WHAT
                  ...

  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.

                  searchaddpl
                  NAME
                  TYPE
                  WHAT
                  ...

  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.

                  update
                  URI

  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.

                  rescan
                  URI

  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).

                  sticker
                  get
                  TYPE
                  URI
                  NAME

  Reads a sticker value for the specified object.

                  sticker
                  set
                  TYPE
                  URI
                  NAME
                  VALUE

  Adds a sticker value to the specified object. If a sticker item with that name already exists, it is replaced.

                  sticker
                  delete
                  TYPE
                  URI
                  NAME

  Deletes a sticker value from the specified object. If you do not specify a sticker name, all sticker values are deleted.

                  sticker
                  list
                  TYPE
                  URI

  Lists the stickers for the specified object.

                  sticker
                  find
                  TYPE
                  URI
                  NAME

  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 settings

                  close

  Closes the connection to MPD.

                  kill

  Kills MPD.

                  password
                  PASSWORD

  This is used for authentication with the server. `PASSWORD` is simply the plaintext password.

                  ping

  Does nothing but return "OK".

### Audio output devices

                  disableoutput
                  ID

  Turns an output off.

                  enableoutput
                  ID

  Turns an output on.

                  outputs

  Shows information about all outputs.

### Reflection

                  config

  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: mpc

### Client 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.

                  subscribe
                  NAME

  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.

                  unsubscribe
                  NAME

  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.

                  sendmessage
                  CHANNEL
                  TEXT

  Send a message to the specified channel.