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 server is encoded in UTF-8. (Note, that 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\n" encoded in UTF-8 is simply "OK\n". For more information on UTF=8: http://www.cl.cam.ac.uk/~mgk25/unicode.html#utf-8)
Responses A command returns "OK\n" on completion or "ACK some error\n" 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 beings 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\n" 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 id's should be used instead of the commands that manipulate and control playback based on playlist position. Using song id's is a safer method when multiple clients are interacting with MPD.
Querying MPD's status clearerror Clear the current error message in status (this is also accomplished by any command that starts playback). currentsong Displays the song info of current song (same song that is identified in status). idle 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 "repeat", "random", "crossfade" While a client waits 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. status reports current status of player, and volume level. volume 0-100 repeat 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 current song stopped on or playing, playlist song number songid current song stopped on or playing, playlist songid time elapsed:total (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 Display statistics. artists: number of artists songs: number of albums uptime: daemon uptime in seconds db_playtime: sum of all song times in db db_update: last db update in UNIX time playtime: time length of music played
Playback options crossfade SECONDS Sets crossfading between songs. random STATE Set random state to STATE, should be 0 or 1. repeat STATE Set repeat state to STATE, STATE should be 0 or 1. setvol VOL Set volume to VOL, the range of volume is 0-100. volume CHANGE Change volume by amount CHANGE. volume is deprecated, use setvol instead.
Controlling playback play SONGPOS Begin playing playlist at song number SONGPOS. playid SONGID Begin playing playlist at song SONGID. next Plays next song in playlist. previous Plays previous song in playlist. pause PAUSE Toggle pause/resume playing. PAUSE is 0 or 1. Use of pause command w/o the _pause_ argument is deprecated. 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 Stop playing.
The current playlist add URI Add 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). example: addid "foo.mp3" Id: 999 OK clear Clears the current playlist. delete SONGPOS Deletes a song from the playlist. deleteid SONGID Delete song SONGID from playlist move FROM TO Move song at FROM to TO in the playlist. moveid FROM TO Move song with FROM to TO (both song ids) 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. playlistid SONGID Displays list of songs in the playlist. SONGID is optional and specifies a single song to display info for. playlistinfo SONGPOS Displays list of songs in the playlist. SONGPOS is optional and specifies a single song to display info for. 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 Shuffles the current playlist. swap SONG1 SONG2 Swap positions of SONG1 and SONG2. swapid SONG1 SONG2 Swap positions of of songs of SONG1 and SONG2 (both song ids).
Stored playlists load NAME Loads the playlist NAME.m3u from the playlist directory. 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. 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 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 List 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 a 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 List contents of 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 contain 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.
Connection settings close Closes the connection to MPD. kill Kill MPD. password PASSWORD This is used for authentication with the server. PASSWORD is simply the plaintext password. ping Does nothing but return "OK".