From a3fd74d0dcb3c51bf5fce949c1c6d5b0a22b3d6d Mon Sep 17 00:00:00 2001 From: Max Kellermann Date: Wed, 19 Nov 2008 21:16:19 +0100 Subject: doc: converted doc/COMMANDS to DocBook The goal is to have one structured document which is the authoritative protocol specification. The documentation which currently resides in the wiki will be merged. --- doc/protocol.xml | 1064 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1064 insertions(+) create mode 100644 doc/protocol.xml (limited to 'doc/protocol.xml') diff --git a/doc/protocol.xml b/doc/protocol.xml new file mode 100644 index 000000000..cec521506 --- /dev/null +++ b/doc/protocol.xml @@ -0,0 +1,1064 @@ + + + + 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". + + + + +
+ + -- cgit v1.2.3