The Music Player Daemon protocol General protocol syntax
Requests If arguments contain spaces, they should be surrounded by double quotation marks. COMMAND ARG 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 a 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.
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_begin is used, list_OK is returned for each successful command executed in the command list.
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 Since 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 updated 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 , , 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. Since MPD 0.14 status Reports the current status of the player and the volume level. volume: 0-100 repeat: 0 or 1 single: 0 or 1 Since MPD 0.15 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 time: total time elapsed (of current playing/paused song) bitrate: instantaneous bitrate in kbps xfade: crossfade in seconds audio: sampleRate:bits:channels updatings_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. 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. volume CHANGE Changes volume by amount CHANGE. volume is deprecated, use setvol instead.
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. 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. POSITION is optional, a negative number means it is relative to the currently playing song in the playlist (if there is one). For example: addid "foo.mp3" Id: 999 OK clear Clears the current playlist. delete SONGPOS 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. 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 listplaylist NAME Lists the files in the playlist NAME.m3u. listplaylistinfo NAME Lists songs in the playlist NAME.m3u. 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 Loads the playlist NAME.m3u from the playlist directory. 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 should be album, artist, or title. WHAT is what to find. list TYPE ARTIST Lists all tags of the specified type. TYPE should be album or artist. 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. search TYPE WHAT Searches for any song that contains WHAT. TYPE can be title, artist, album or filename. Search is not case sensitive. update URI Updates the music database. URI is a particular directory or song/file to update. Prints "updating_db: JOBID" where JOBID is the job id requested for your update, and is displayed in status, while the requested update is happening. To update a number of paths/songs at once, use command_list, it will be much more faster/efficient. Also, if you use a command_list for updating, only one update job id will be returned per sequence of updates.
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 Turns an output off. enableoutput Turns an output on. outputs Shows information about all outputs.
Reflection 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.