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/COMMANDS | 325 ----------------- doc/protocol.xml | 1064 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1064 insertions(+), 325 deletions(-) delete mode 100644 doc/COMMANDS create mode 100644 doc/protocol.xml diff --git a/doc/COMMANDS b/doc/COMMANDS deleted file mode 100644 index 35373a4d..00000000 --- a/doc/COMMANDS +++ /dev/null @@ -1,325 +0,0 @@ - Music Player Daemon - Commands - - WARNING - This document has not been updated to reflect recent changes in - the MPD protocol. It does not contain all supported commands, - and some commands may now take additional arguments. However, - clients conforming to this specification should still be - compatible with the latest release of MPD. For more up to date - documentation, please see the protocol reference on the wiki at - . - -This document is intended for client developers, not end users. - -Format: -------- - -If arguments contain spaces, they should be surrounded by double quotation -marks, ". - -command ... - explanation: w/ arg1 and arg2 - -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 ) - -Command Completion: -------------------- - -A command returns "OK\n" on completion or "ACK some error\n" on failure. -These denote the end of command execution. - -NOTE: ------ - -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. - -Commands: ---------- - -add - add the file _path_ to the playlist (directories add recursively) - _path_ can also be a single file - increments playlist version by for each song added - -addid - _path_ 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) - adds a song to the playlist (non-recursive) and returns the song id; - example: - - addid "foo.mp3" - Id: 999 - OK - -clear - clears the current playlist - increments playlist version by 1 - -clearerror - clear the current error message in status - (this is also accomplished by any command that starts playback) - -close - close the connection with the MPD - -crossfade - sets crossfading between songs - -currentsong - displays the song info of current song (same song that is identified - in status) - -delete - delete _song_ from playlist - increments playlist version by 1 - -deleteid - delete song with _songid_ from playlist - increments playlist version by 1 - -find - finds songs in the db that are exactly _what_ - _type_ should be "album", "artist", or "title" - _what_ is what to find - -kill - kill MPD - -list - list all tags of _type_ - _type_ should be "album" or "artist" - _arg1_ is an optional parameter when type is album, this specifies - to list albums by a artist, where artist is specified with - arg1 - -listall - lists all songs and directories in _path_ (recursively) - _path_ is optional and maybe a directory or path - -listallinfo - same as listall command, except it also returns metadata info - in the same format as lsinfo - -load - loads the playlist _name_.m3u from the playlist directory - increments playlist version by the number of songs added - -lsinfo - list contents of _directory_, from the db. _directory_ is optional - - When listing the root directory, this currently returns the - list of stored playlists. This behavior is deprecated; use - "listplaylists" instead. - -move - move song at _from_ to _to_ in the playlist - increments playlist version by 1 - -moveid - move song with _songid_ to _to_ in the playlist - increments playlist version by 1 - if _to_ is negative, it is relative to the current song in - the playlist (if there is one). - -next - plays next song in playlist - -pause - toggle pause/resume playing - _pause_ is required and should be 0 or 1 - NOTE: use of pause command w/o the _pause_ argument is deprecated - -password - this is used for authentication with the server. - _password_ is simply the plaintext password - -ping - does nothing but return "OK" - -play - begin playing playlist at song number _song_, _song_ is optional - -playid - begin playing playlist at song with _songid_, _songid_ is optional - -playlist - displays the current playlist - NOTE: do not use this, instead use 'playlistinfo' - -playlistinfo - displays list of songs in the playlist - _song_ is optional and specifies a single song to display info for - -playlistid - displays list of songs in the playlist - _songid_ is optional and specifies a single song to display info for - -plchanges - displays changed songs currently in the playlist since - _playlist version_ - NOTE: to detect songs that were deleted at the end of the playlist, - use playlistlength returned by status command. - -plchangesposid - displays changed songs currently in the playlist since - _playlist version_ - This function only returns the position and the id of the changed song, not the complete metadata. This is more bandwidth efficient. - NOTE: to detect songs that were deleted at the end of the playlist, - use playlistlength returned by status command. - -previous - plays previous song in playlist - -random - set random state to _state_, _state_ should be 0 or 1 - -repeat - set repeat state to _state_, _state_ should be 0 or 1 - -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 - removes the playlist .m3u from the playlist directory - -save - saves the current playlist to _name_.m3u in the playlist directory - -search - searches for any song that contain _what_ - _type_ can be "title","artist","album", or "filename" - search is not case sensitive - -seek - seeks to the position _time_ (in seconds) of entry _song_ in the - playlist - -seekid - seeks to the position _time_ (in seconds) of song with _songid_ - -setvol - set volume to _vol_ - _vol_ the range of volume is 0-100 - -shuffle - shuffles the current playlist - increments playlist version by 1 - -stats - display stats - artists: number of artists - albums: number of albums - songs: number of songs - 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 - -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: :