doc/COMMANDS

   1                          Music Player Daemon - Commands
   2
   3                                     WARNING
   4         This document has not been updated to reflect recent changes in
   5         the MPD protocol.  It does not contain all supported commands,
   6         and some commands may now take additional arguments.  However,
   7         clients conforming to this specification should still be
   8         compatible with the latest release of MPD.  For more up to date
   9         documentation, please see the protocol reference on the wiki at
  10         <http://mpd.wikia.com/wiki/Protocol_Reference>.
  11
  12 This document is intended for client developers, not end users.
  13
  14 Format:
  15 -------
  16
  17 If arguments contain spaces, they should be surrounded by double quotation
  18 marks, ".
  19
  20 command <type arg1> <type arg2> ...
  21         explanation: w/ arg1 and arg2
  22
  23 All data between the client and server is encoded in UTF-8. (Note,
  24 that in UTF-8 all standard ansi characters, 0-127, are the same as a standard
  25 ansi encoding. Also, no ansi character appears in any multi-byte
  26 characters.  So, you can use standard C functions like strlen, and strcpy
  27 just fine with UTF-8 encoded strings. For example: "OK\n" encoded in UTF-8 is
  28 simply "OK\n".  For more information on UTF=8:
  29 http://www.cl.cam.ac.uk/~mgk25/unicode.html#utf-8 )
  30
  31 Command Completion:
  32 -------------------
  33
  34 A command returns "OK\n" on completion or "ACK some error\n" on failure.
  35 These denote the end of command execution.
  36
  37 NOTE:
  38 -----
  39
  40 For manipulating playlists and playing, there are two sets of commands.  One
  41 set uses the song id of a song in the playlist, while another set uses the
  42 playlist position of the song.  The commands using song id's should be used
  43 instead of the commands that manipulate and control playback based on playlist
  44 position.  Using song id's is a safer method when multiple clients are
  45 interacting with MPD.
  46
  47 Commands:
  48 ---------
  49
  50 add <string path>
  51         add the file _path_ to the playlist (directories add recursively)
  52         _path_ can also be a single file
  53         increments playlist version by for each song added
  54
  55 clear
  56         clears the current playlist
  57         increments playlist version by 1
  58
  59 clearerror
  60         clear the current error message in status
  61         (this is also accomplished by any command that starts playback)
  62
  63 close
  64         close the connection with the MPD
  65
  66 crossfade <int seconds>
  67         sets crossfading between songs
  68
  69 currentsong
  70         displays the song info of current song (same song that is identified
  71         in status)
  72
  73 delete <int song>
  74         delete _song_ from playlist
  75         increments playlist version by 1
  76
  77 deleteid <int songid>
  78         delete song with _songid_ from playlist
  79         increments playlist version by 1
  80
  81 find <string type> <string what>
  82         finds songs in the db that are exactly _what_
  83         _type_ should be "album", "artist", or "title"
  84         _what_ is what to find
  85
  86 kill
  87         kill MPD
  88
  89 list <string type> <string arg1>
  90         list all tags of _type_
  91         _type_ should be "album" or "artist"
  92         _arg1_ is an optional parameter when type is album, this specifies
  93                 to list albums by a artist, where artist is specified with
  94                 arg1
  95
  96 listall <string path>
  97         lists all songs and directories in _path_ (recursively)
  98         _path_ is optional and maybe a directory or path
  99
 100 listallinfo <string path>
 101         same as listall command, except it also returns metadata info
 102         in the same format as lsinfo
 103
 104 load <string name>
 105         loads the playlist _name_.m3u from the playlist directory
 106         increments playlist version by the number of songs added
 107
 108 lsinfo <string directory>
 109         list contents of _directory_, from the db.  _directory_ is optional
 110
 111 move <int from> <int to>
 112         move song at _from_ to _to_ in the playlist
 113         increments playlist version by 1
 114
 115 moveid <int songid> <int to>
 116         move song with _songid_ to  _to_ in the playlist
 117         increments playlist version by 1
 118
 119 next
 120         plays next song in playlist
 121
 122 pause   <bool pause>
 123         toggle pause/resume playing
 124         _pause_ is required and should be 0 or 1
 125         NOTE: use of pause command w/o the _pause_ argument is deprecated
 126
 127 password <string password>
 128         this is used for authentication with the server.
 129         _password_ is simply the plaintext password
 130
 131 ping
 132         does nothing but return "OK"
 133
 134 play <int song>
 135         begin playing playlist at song number _song_, _song_ is optional
 136
 137 playid <int songid>
 138         begin playing playlist at song with _songid_, _songid_ is optional
 139
 140 playlist
 141         displays the current playlist
 142         NOTE: do not use this, instead use 'playlistinfo'
 143
 144 playlistinfo <int song>
 145         displays list of songs in the playlist
 146         _song_ is optional and specifies a single song to display info for
 147
 148 playlistid <int songid>
 149         displays list of songs in the playlist
 150         _songid_ is optional and specifies a single song to display info for
 151
 152 plchanges <playlist version>
 153         displays changed songs currently in the playlist since
 154         _playlist version_
 155         NOTE: to detect songs that were deleted at the end of the playlist,
 156         use playlistlength returned by status command.
 157
 158 plchangesposid <playlist version>
 159         displays changed songs currently in the playlist since
 160         _playlist version_
 161         This function only returns the position and the id of the changed song, not the complete metadata. This is more bandwidth efficient.
 162         NOTE: to detect songs that were deleted at the end of the playlist,
 163         use playlistlength returned by status command.
 164
 165 previous
 166         plays previous song in playlist
 167
 168 random <int state>
 169         set random state to _state_, _state_ should be 0 or 1
 170
 171 repeat <int state>
 172         set repeat state to _state_, _state_ should be 0 or 1
 173
 174 rm <string name>
 175         removes the playlist <name>.m3u from the playlist directory
 176
 177 save <string name>
 178         saves the current playlist to _name_.m3u in the playlist directory
 179
 180 search <string type> <string what>
 181         searches for any song that contain _what_
 182         _type_ can be "title","artist","album", or "filename"
 183         search is not case sensitive
 184
 185 seek <int song> <int time>
 186         seeks to the position _time_ (in seconds) of entry _song_ in the
 187         playlist
 188
 189 seekid <int songid> <int time>
 190         seeks to the position _time_ (in seconds) of song with _songid_
 191
 192 setvol <int vol>
 193         set volume to _vol_
 194         _vol_ the range of volume is 0-100
 195
 196 shuffle
 197         shuffles the current playlist
 198         increments playlist version by 1
 199
 200 stats
 201         display stats
 202         artists: number of artists
 203         albums: number of albums
 204         songs: number of songs
 205         uptime: daemon uptime in seconds
 206         db_playtime: sum of all song times in db
 207         db_update: last db update in UNIX time
 208         playtime: time length of music played
 209
 210 status
 211         reports current status of player, and volume level.
 212         volume: (0-100).
 213         repeat: (0 or 1)
 214         playlist: (31-bit unsigned integer, the playlist version number)
 215         playlistlength: (integer, the length of the playlist)
 216         state: ("play", "stop", or "pause")
 217         song: (current song stopped on or playing, playlist song number)
 218         songid: (current song stopped on or playing, playlist songid)
 219         time: <int elapsed>:<time total> (of current playing/paused song)
 220         bitrate: <int bitrate> (instantaneous bitrate in kbps)
 221         xfade: <int seconds> (crossfade in seconds)
 222         audio: <int sampleRate>:<int bits>:<int channels>
 223         updatings_db: <int job id>
 224         error: if there is an error, returns message here
 225
 226 stop
 227         stop playing
 228
 229 swap <int song1> <int song2>
 230         swap positions of _song1_ and _song2_
 231         increments playlist version by 1
 232
 233 swapid <int songid1> <int songid2>
 234         swap positions of of songs with song id's of _songid1_ and _songid2_
 235         increments playlist version by 1
 236
 237 update <string path>
 238         searches mp3 directory for new music and removes old music from the db
 239         _path_ is an optional argument that maybe a particular directory or
 240                 song/file to update.
 241         returned:
 242                 updating_db: <int job id>
 243         where job id, is the job id requested for your update, and is displayed
 244         in status, while the requested update is happening
 245         increments playlist version by 1
 246         NOTE: To update a number of paths/songs at once, use command_list,
 247         it will be much more faster/efficient.  Also, if you use a
 248         command_list for updating, only one update_db job id will be returned
 249         per sequence of updates.
 250
 251 volume <int change>
 252         change volume by amount _change_
 253         NOTE: volume command is deprecated, use setvol instead
 254
 255 COMMAND LIST
 256 ------------
 257
 258 To facilitate faster adding of files, etc, you can pass a list of commands all
 259 at once using a command list.  The command list beings with:
 260
 261 command_list_begin
 262
 263 or:
 264
 265 command_list_ok_begin
 266
 267 And ends with:
 268
 269 command_list_end
 270
 271 It does not execute any commands until the list has ended.  The return
 272 value is whatever the return for a list of commands is.  On success
 273 for all commands, OK is returned.  If a command fails, no more commands
 274 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
 275 in the command list.