diff options
| -rw-r--r-- | doc/COMMANDS | 325 | ||||
| -rw-r--r-- | doc/protocol.xml | 1064 |
2 files changed, 1064 insertions, 325 deletions
diff --git a/doc/COMMANDS b/doc/COMMANDS deleted file mode 100644 index 35373a4d5..000000000 --- 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 - <http://mpd.wikia.com/wiki/Protocol_Reference>. - -This document is intended for client developers, not end users. - -Format: -------- - -If arguments contain spaces, they should be surrounded by double quotation -marks, ". - -command <type arg1> <type arg2> ... - 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 <string path> - 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 <string path> <int position> - _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 <int seconds> - sets crossfading between songs - -currentsong - displays the song info of current song (same song that is identified - in status) - -delete <int song> - delete _song_ from playlist - increments playlist version by 1 - -deleteid <int songid> - delete song with _songid_ from playlist - increments playlist version by 1 - -find <string type> <string what> - 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 <string type> <string arg1> - 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 <string path> - lists all songs and directories in _path_ (recursively) - _path_ is optional and maybe a directory or path - -listallinfo <string path> - same as listall command, except it also returns metadata info - in the same format as lsinfo - -load <string name> - loads the playlist _name_.m3u from the playlist directory - increments playlist version by the number of songs added - -lsinfo <string directory> - 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 <int from> <int to> - move song at _from_ to _to_ in the playlist - increments playlist version by 1 - -moveid <int songid> <int to> - 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 <bool 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 <string password> - this is used for authentication with the server. - _password_ is simply the plaintext password - -ping - does nothing but return "OK" - -play <int song> - begin playing playlist at song number _song_, _song_ is optional - -playid <int songid> - begin playing playlist at song with _songid_, _songid_ is optional - -playlist - displays the current playlist - NOTE: do not use this, instead use 'playlistinfo' - -playlistinfo <int song> - displays list of songs in the playlist - _song_ is optional and specifies a single song to display info for - -playlistid <int songid> - displays list of songs in the playlist - _songid_ is optional and specifies a single song to display info for - -plchanges <playlist version> - 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 <playlist version> - 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 <int state> - set random state to _state_, _state_ should be 0 or 1 - -repeat <int state> - 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 <string name> - removes the playlist <name>.m3u from the playlist directory - -save <string name> - saves the current playlist to _name_.m3u in the playlist directory - -search <string type> <string what> - searches for any song that contain _what_ - _type_ can be "title","artist","album", or "filename" - search is not case sensitive - -seek <int song> <int time> - seeks to the position _time_ (in seconds) of entry _song_ in the - playlist - -seekid <int songid> <int time> - seeks to the position _time_ (in seconds) of song with _songid_ - -setvol <int vol> - 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: <int elapsed>:<time total> (of current playing/paused song) - bitrate: <int bitrate> (instantaneous bitrate in kbps) - xfade: <int seconds> (crossfade in seconds) - audio: <int sampleRate>:<int bits>:<int channels> - updatings_db: <int job id> - error: if there is an error, returns message here - -stop - stop playing - -swap <int song1> <int song2> - swap positions of _song1_ and _song2_ - increments playlist version by 1 - -swapid <int songid1> <int songid2> - swap positions of of songs with song id's of _songid1_ and _songid2_ - increments playlist version by 1 - -update <string path> - searches mp3 directory for new music and removes old music from the db - _path_ is an optional argument that maybe a particular directory or - song/file to update. - returned: - updating_db: <int job id> - where job id, is the job id requested for your update, and is displayed - in status, while the requested update is happening - increments playlist version by 1 - NOTE: 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_db job id will be returned - per sequence of updates. - -volume <int change> - change volume by amount _change_ - NOTE: volume command is deprecated, use setvol instead - -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. - - -COMMAND LIST ------------- - -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. 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 @@ +<?xml version='1.0' encoding="utf-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "docbook/dtd/xml/4.2/docbookx.dtd"> +<book> + <title>The Music Player Daemon protocol</title> + + <chapter> + <title>General protocol syntax</title> + + <section> + <title>Requests</title> + + <para> + If arguments contain spaces, they should be surrounded by double quotation + marks. + </para> + + <cmdsynopsis> + <command>COMMAND</command> + <arg rep="Repeat"><replaceable>ARG</replaceable></arg> + </cmdsynopsis> + + <para> + 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) + </para> + </section> + + <section> + <title>Responses</title> + + <para> + A command returns "OK\n" on completion or "ACK some error\n" on failure. + These denote the end of command execution. + </para> + </section> + + <section> + <title>Command lists</title> + + <para> + 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>command_list_begin</command> or + <command>command_list_ok_begin</command> and ends with + <command>command_list_end</command>. + </para> + + <para> + 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. + </para> + </section> + </chapter> + + <chapter> + <title>Command reference</title> + + <note> + <para> + 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. + </para> + </note> + + <section> + <title>Querying MPD's status</title> + + <variablelist> + <varlistentry id="command_clearerror"> + <term> + <cmdsynopsis> + <command>clearerror</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Clear the current error message in status (this is also + accomplished by any command that starts playback). + </para> + </listitem> + </varlistentry> + <varlistentry id="command_currentsong"> + <term> + <cmdsynopsis> + <command>currentsong</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Displays the song info of current song (same song that + is identified in status). + </para> + </listitem> + </varlistentry> + <varlistentry id="command_idle"> + <term> + <cmdsynopsis> + <command>idle</command> + </cmdsynopsis> + </term> + <listitem> + <para> + 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: + </para> + <itemizedlist> + <listitem> + <para> + <returnvalue>database</returnvalue>: the song database + has been updated + </para> + </listitem> + <listitem> + <para> + <returnvalue>stored_playlist</returnvalue>: a stored + playlist has been modified, renamed, created or + deleted + </para> + </listitem> + <listitem> + <para> + <returnvalue>playlist</returnvalue>: the current + playlist has been modified + </para> + </listitem> + <listitem> + <para> + <returnvalue>player</returnvalue>: the player has been + started, stopped or seeked + </para> + </listitem> + <listitem> + <para> + <returnvalue>mixer</returnvalue>: the volume has been + changed + </para> + </listitem> + <listitem> + <para> + <returnvalue>output</returnvalue>: an audio output has + been enabled or disabled + </para> + </listitem> + <listitem> + <para> + <returnvalue>options</returnvalue>: options like + "repeat", "random", "crossfade" + </para> + </listitem> + </itemizedlist> + <para> + While a client waits for <command>idle</command> + results, the server disables timeouts, allowing a client + to wait for events as long as mpd runs. The + <command>idle</command> command can be canceled by + sending the command <command>noidle</command> (no other + commands are allowed). MPD will then leave + <command>idle</command> mode and print results + immediately; might be empty at this time. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_status"> + <term> + <cmdsynopsis> + <command>status</command> + </cmdsynopsis> + </term> + <listitem> + <para> + reports current status of player, and volume level. + </para> + <variablelist> + <varlistentry> + <term>volume</term> + <listitem> + <para>0-100</para> + </listitem> + </varlistentry> + <varlistentry> + <term>repeat</term> + <listitem> + <para>0 or 1</para> + </listitem> + </varlistentry> + <varlistentry> + <term>playlist</term> + <listitem> + <para> + 31-bit unsigned integer, the playlist version + number + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>playlistlength</term> + <listitem> + <para> + integer, the length of the playlist + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>state</term> + <listitem> + <para> + "play", "stop", or "pause" + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>song</term> + <listitem> + <para> + current song stopped on or playing, playlist song + number + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>songid</term> + <listitem> + <para> + current song stopped on or playing, playlist + songid + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>time</term> + <listitem> + <para> + elapsed:total (of current playing/paused song) + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>bitrate</term> + <listitem> + <para> + instantaneous bitrate in kbps + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>xfade</term> + <listitem> + <para> + crossfade in seconds + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>audio</term> + <listitem> + <para> + sampleRate:bits:channels + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>updatings_db</term> + <listitem> + <para> + job id + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>error</term> + <listitem> + <para> + if there is an error, returns message here + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + <varlistentry id="command_stats"> + <term> + <cmdsynopsis> + <command>stats</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Display statistics. + </para> + <itemizedlist> + <listitem> + <para> + <varname>artists</varname>: number of artists + </para> + </listitem> + <listitem> + <para> + <varname>songs</varname>: number of albums + </para> + </listitem> + <listitem> + <para> + <varname>uptime</varname>: daemon uptime in seconds + </para> + </listitem> + <listitem> + <para> + <varname>db_playtime</varname>: sum of all song + times in db + </para> + </listitem> + <listitem> + <para> + <varname>db_update</varname>: last db update in UNIX + time + </para> + </listitem> + <listitem> + <para> + <varname>playtime</varname>: time length of music played + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>Playback options</title> + + <variablelist> + <varlistentry id="command_crossfade"> + <term> + <cmdsynopsis> + <command>crossfade</command> + <arg choice="req"><replaceable>SECONDS</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Sets crossfading between songs. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_random"> + <term> + <cmdsynopsis> + <command>random</command> + <arg choice="req"><replaceable>STATE</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Set random state to <varname>STATE</varname>, should + be 0 or 1. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_repeat"> + <term> + <cmdsynopsis> + <command>repeat</command> + <arg choice="req"><replaceable>STATE</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Set repeat state to <varname>STATE</varname>, + <varname>STATE</varname> should be 0 or 1. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_setvol"> + <term> + <cmdsynopsis> + <command>setvol</command> + <arg choice="req"><replaceable>VOL</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Set volume to <varname>VOL</varname>, the range of + volume is 0-100. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_volume"> + <term> + <cmdsynopsis> + <command>volume</command> + <arg choice="req"><replaceable>CHANGE</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Change volume by amount <varname>CHANGE</varname>. + </para> + <note> + <para> + <command>volume</command> is deprecated, use + <command>setvol</command> instead. + </para> + </note> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>Controlling playback</title> + + <variablelist> + <varlistentry id="command_play"> + <term> + <cmdsynopsis> + <command>play</command> + <arg><replaceable>SONGPOS</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Begin playing playlist at song number + <varname>SONGPOS</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_playid"> + <term> + <cmdsynopsis> + <command>playid</command> + <arg><replaceable>SONGID</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Begin playing playlist at song + <varname>SONGID</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_next"> + <term> + <cmdsynopsis> + <command>next</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Plays next song in playlist. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_previous"> + <term> + <cmdsynopsis> + <command>previous</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Plays previous song in playlist. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_pause"> + <term> + <cmdsynopsis> + <command>pause</command> + <arg choice="req"><replaceable>PAUSE</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Toggle pause/resume playing. <varname>PAUSE</varname> is 0 or 1. + </para> + <note> + <para> + Use of pause command w/o the _pause_ argument is + deprecated. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry id="command_seek"> + <term> + <cmdsynopsis> + <command>seek</command> + <arg choice="req"><replaceable>SONGPOS</replaceable></arg> + <arg choice="req"><replaceable>TIME</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Seeks to the position <varname>TIME</varname> (in + seconds) of entry <varname>SONGPOS</varname> in the + playlist. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_seekid"> + <term> + <cmdsynopsis> + <command>seekid</command> + <arg choice="req"><replaceable>SONGID</replaceable></arg> + <arg choice="req"><replaceable>TIME</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Seeks to the position <varname>TIME</varname> (in + seconds) of song <varname>SONGID</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_stop"> + <term> + <cmdsynopsis> + <command>stop</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Stop playing. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>The current playlist</title> + + <variablelist> + <varlistentry id="command_add"> + <term> + <cmdsynopsis> + <command>add</command> + <arg choice="req"><replaceable>URI</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Add the file <varname>URI</varname> to the playlist + (directories add recursively). + <varname>URI</varname> can also be a single file. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_addid"> + <term> + <cmdsynopsis> + <command>addid</command> + <arg choice="req"><replaceable>URI</replaceable></arg> + <arg><replaceable>POSITION</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Adds a song to the playlist (non-recursive) and returns the song id. + </para> + <para> + <varname>URI</varname> is always a single file or + URL. <varname>POSITION</varname> is optional, a + negative number means it is relative to the currently + playing song in the playlist (if there is one). + example: + </para> + <screen> +addid "foo.mp3" +Id: 999 +OK + </screen> + </listitem> + </varlistentry> + <varlistentry id="command_clear"> + <term> + <cmdsynopsis> + <command>clear</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Clears the current playlist. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_delete"> + <term> + <cmdsynopsis> + <command>delete</command> + <arg choice="req"><replaceable>SONGPOS</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Deletes a song from the playlist. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_deleteid"> + <term> + <cmdsynopsis> + <command>deleteid</command> + <arg choice="req"><replaceable>SONGID</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Delete song <varname>SONGID</varname> from playlist + </para> + </listitem> + </varlistentry> + <varlistentry id="command_move"> + <term> + <cmdsynopsis> + <command>move</command> + <arg choice="req"><replaceable>FROM</replaceable></arg> + <arg choice="req"><replaceable>TO</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Move song at <varname>FROM</varname> to + <varname>TO</varname> in the playlist. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_moveid"> + <term> + <cmdsynopsis> + <command>moveid</command> + <arg choice="req"><replaceable>FROM</replaceable></arg> + <arg choice="req"><replaceable>TO</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Move song with <varname>FROM</varname> to + <varname>TO</varname> (both song ids) in the + playlist. If <varname>TO</varname> is negative, it + is relative to the current song in the playlist (if + there is one). + </para> + </listitem> + </varlistentry> + <varlistentry id="command_playlist"> + <term> + <cmdsynopsis> + <command>playlist</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Displays the current playlist. + </para> + <note> + <para> + Do not use this, instead use <command>playlistinfo</command>. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry id="command_playlistid"> + <term> + <cmdsynopsis> + <command>playlistid</command> + <arg choice="req"><replaceable>SONGID</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Displays list of songs in the playlist. + <varname>SONGID</varname> is optional and specifies a + single song to display info for. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_playlistinfo"> + <term> + <cmdsynopsis> + <command>playlistinfo</command> + <arg><replaceable>SONGPOS</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Displays list of songs in the playlist. + <varname>SONGPOS</varname> is optional and specifies + a single song to display info for. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_plchanges"> + <term> + <cmdsynopsis> + <command>plchanges</command> + <arg choice="req"><replaceable>VERSION</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Displays changed songs currently in the playlist since + <varname>VERSION</varname>. + </para> + <para> + To detect songs that were deleted at the end of the + playlist, use playlistlength returned by status command. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_plchangesposid"> + <term> + <cmdsynopsis> + <command>plchangesposid</command> + <arg choice="req"><replaceable>VERSION</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Displays changed songs currently in the playlist since + <varname>VERSION</varname>. This function only + returns the position and the id of the changed song, not + the complete metadata. This is more bandwidth efficient. + </para> + <para> + To detect songs that were deleted at the end of the + playlist, use playlistlength returned by status command. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_shuffle"> + <term> + <cmdsynopsis> + <command>shuffle</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Shuffles the current playlist. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_swap"> + <term> + <cmdsynopsis> + <command>swap</command> + <arg choice="req"><replaceable>SONG1</replaceable></arg> + <arg choice="req"><replaceable>SONG2</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Swap positions of <varname>SONG1</varname> and + <varname>SONG2</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_swapid"> + <term> + <cmdsynopsis> + <command>swapid</command> + <arg choice="req"><replaceable>SONG1</replaceable></arg> + <arg choice="req"><replaceable>SONG2</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Swap positions of of songs of + <varname>SONG1</varname> and + <varname>SONG2</varname> (both song ids). + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>Stored playlists</title> + + <variablelist> + <varlistentry id="command_load"> + <term> + <cmdsynopsis> + <command>load</command> + <arg choice="req"><replaceable>NAME</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Loads the playlist <filename>NAME.m3u</filename> from + the playlist directory. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_listplaylists"> + <term> + <cmdsynopsis> + <command>listplaylists</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Prints a list of the playlist directory. + </para> + <para> + 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. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_rm"> + <term> + <cmdsynopsis> + <command>rm</command> + <arg choice="req"><replaceable>NAME</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Removes the playlist <filename>NAME.m3u</filename> from + the playlist directory. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_save"> + <term> + <cmdsynopsis> + <command>save</command> + <arg choice="req"><replaceable>NAME</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Saves the current playlist to + <filename>NAME.m3u</filename> in the playlist directory. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>The music database</title> + + <variablelist> + <varlistentry id="command_find"> + <term> + <cmdsynopsis> + <command>find</command> + <arg choice="req"><replaceable>TYPE</replaceable></arg> + <arg choice="req"><replaceable>WHAT</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + finds songs in the db that are exactly + <varname>WHAT</varname>. <varname>TYPE</varname> should + be <parameter>album</parameter>, + <parameter>artist</parameter>, or + <parameter>title</parameter>. <varname>WHAT</varname> + is what to find. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_list"> + <term> + <cmdsynopsis> + <command>list</command> + <arg choice="req"><replaceable>TYPE</replaceable></arg> + <arg><replaceable>ARTIST</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + List all tags of the specified type. + <varname>TYPE</varname> should be "album" or "artist". + </para> + <para> + <varname>ARTIST</varname> is an optional parameter + when type is album, this specifies to list albums by a + artist. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_listall"> + <term> + <cmdsynopsis> + <command>listall</command> + <arg><replaceable>URI</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Lists all songs and directories in + <varname>URI</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_listallinfo"> + <term> + <cmdsynopsis> + <command>listallinfo</command> + <arg><replaceable>URI</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Same as <command>listall</command>, except it also + returns metadata info in the same format as + <command>lsinfo</command>. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_lsinfo"> + <term> + <cmdsynopsis> + <command>lsinfo</command> + <arg><replaceable>URI</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + List contents of directory <varname>URI</varname>. + </para> + <para> + When listing the root directory, this currently returns + the list of stored playlists. This behavior is + deprecated; use "listplaylists" instead. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_search"> + <term> + <cmdsynopsis> + <command>search</command> + <arg choice="req"><replaceable>TYPE</replaceable></arg> + <arg choice="req"><replaceable>WHAT</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Searches for any song that contain + <varname>WHAT</varname>. <varname>TYPE</varname> can be + <parameter>title</parameter>, + <parameter>artist</parameter>, + <parameter>album</parameter> or + <parameter>filename</parameter>. Search is not case + sensitive. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_update"> + <term> + <cmdsynopsis> + <command>update</command> + <arg><replaceable>URI</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Updates the music database. + </para> + <para> + <varname>URI</varname> is a particular directory or + song/file to update. + </para> + <para> + Prints "updating_db: JOBID" where + <varname>JOBID</varname> is the job id requested for + your update, and is displayed in status, while the + requested update is happening. + </para> + <para> + 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 + <command>update</command> job id will be returned per + sequence of updates. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>Connection settings</title> + + <variablelist> + <varlistentry id="command_close"> + <term> + <cmdsynopsis> + <command>close</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Closes the connection to MPD. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_kill"> + <term> + <cmdsynopsis> + <command>kill</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Kill MPD. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_password"> + <term> + <cmdsynopsis> + <command>password</command> + <arg choice="req"><replaceable>PASSWORD</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + This is used for authentication with the server. + <varname>PASSWORD</varname> is simply the plaintext + password. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_ping"> + <term> + <cmdsynopsis> + <command>ping</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Does nothing but return "OK". + </para> + </listitem> + </varlistentry> + </variablelist> + </section> + </chapter> +</book> |