diff options
| -rw-r--r-- | doc/MPD-Protocol.xml | 89 |
1 files changed, 80 insertions, 9 deletions
diff --git a/doc/MPD-Protocol.xml b/doc/MPD-Protocol.xml index 2cfaa8e9d..25975a91e 100644 --- a/doc/MPD-Protocol.xml +++ b/doc/MPD-Protocol.xml @@ -9,21 +9,21 @@ <holder>Warren Dukes</holder> </copyright> </articleinfo> - <sect1> + <sect1 id="protocol_outline"> <title>Protocol Outline</title> <para>The MPD Protocol has Three Components: Commands, Responses, and Command Lists. All communication between the client and server uses the UTF-8 character encoding.</para> - <sect2> + <sect2 id="format_of_commands"> <title>Format of Commands</title> <para>Commands in MPD are specified begginning with the name of the command. The arguments of a command are delimitted by spaces and should be surrounded by double qutotation marks. The end of a command is delimitted by a return character '<literal>\n</literal>'.<programlisting>command "arg1" "arg2"</programlisting></para> </sect2> <sect2> - <title>Format of Responses</title> + <title id="format_of_responses">Format of Responses</title> <para>The different response elements of a command are seperated by the return character '<literal>\n</literal>'. The last element of a response begin with either <literal>OK</literal> or <literal>ACK</literal>. Thus, if a command is successful, the end of the response is <literal>OK\n</literal>. If a command is unsuccessful <literal>ACK</literal> terminates the command with the following format:<programlisting>ACK {err#:cmd#} {command} some error message</programlisting><literal>err#</literal> is an integer indicating the specific error that occured and <literal>cmd#</literal> is an integer indicating which command of the command list caused the error (See section 1.3 for more info on Command Lists). <literal>command</literal> gives the name of the command the error occurred on; however, its intended more for debugging persons (for human readability). <literal>some error message</literal> is also not intended to be parsed by clients but is intended more for debugging purposes.</para> <para>The other response elements are data. The data is seperated into a name and value pare by <literal>: </literal>. Thus, a possible command response containing data would be:<programlisting>Name1: Value1 Name2: Value2 OK</programlisting></para> </sect2> - <sect2> + <sect2 id="command_lists"> <title>Command Lists</title> <para>Command lists allow for a fast, effecient, and atomic execution of multiple commands. Command lists are initiated with either <literal>command_list_begin</literal> or <literal>command_list_ok_begin</literal>and are terminated with <literal>command_list_end</literal>.<programlisting>command_list_begin command1 arg1 arg2 @@ -34,11 +34,11 @@ command_list_end</programlisting></para> <para><literal>command_list_ok_begin</literal> responds with <literal>list_OK</literal> after each command is successfully completed. <literal>command_list_begin</literal> does not return anything between each command that is executed.</para> </sect2> </sect1> - <sect1> + <sect1 id="commands"> <title>Commands</title> - <sect2> + <sect2 id="db_browsing"> <title>DB: Browsing, Searching, and Finding</title> - <sect3> + <sect3 id="browsing_responses"> <title>Browsing Responses</title> <para>Browsing Responses usually contain groups of several responses. These groups are either begin with <literal>file</literal>, <literal>directory</literal>, or <literal>playlist</literal>. Each of these response groups maybe followed by metadata, which always begin with a capital letter (A-Z). Here's an example of a complete browsing response:<programlisting>file: Directory/file.mp3 Artist: Muscian @@ -49,34 +49,61 @@ playlist: Directory/favorites OK</programlisting></para> <para><literal>directory</literal> and <literal>playlist</literal> have no metadata, however future versions of the MPD protocol may add metadata to either. Also, future versions of MPD may add othe response groups for browsing.</para> </sect3> - <sect3> + <sect3 id="song_info_responses"> <title>Song Info Responses</title> <para>For query information on songs in the db (and the playlist), there is a common response for each song. The first response element is <literal>file</literal>. The remainng elements of the song info are one of the following metadata types: <literal>Artist</literal>, <literal>Album</literal>, <literal>Title</literal>, <literal>Track</literal>, <literal>Name</literal>, or <literal>Time</literal>.</para> </sect3> - <sect3> + <sect3 id="lsinfo"> <title> <literal>lsinfo</literal> </title> + <para><programlisting>lsinfo +lsinfo <emphasis>directory</emphasis> +lsinfo <emphasis>file</emphasis></programlisting><literal>lsinfo</literal> responds with <link linkend="browsing_responses">info</link> for the directory or file specified. If <literal>lsinfo</literal> is called without any arguments then the root directory is implied as the path.</para> + </sect3> + <sect3> + <title id="listallinfo"> + <literal>listallinfo</literal> + </title> + <para><programlisting>listallinfo +listallinfo <emphasis>directory</emphasis> +listallinfo <emphasis>file</emphasis></programlisting><literal>listallinfo</literal> is a recursive form of <literal> + <link linkend="lsinfo">lsinfo</link> + </literal></para> </sect3> <sect3> <title> <literal>listall</literal> </title> + <para><programlisting>listall +listall <emphasis>directory</emphasis> +listall <emphasis>file</emphasis></programlisting><literal>listall</literal> is the same as <literal> + <link linkend="listallinfo">listallinfo</link> + </literal> except that no metadata is returned.</para> </sect3> <sect3> <title> <literal>search</literal> </title> + <para><programlisting>search filename <emphasis>pattern</emphasis> +search artist <emphasis>pattern</emphasis> +search album <emphasis>pattern</emphasis> +search title <emphasis>pattern</emphasis></programlisting><literal>search</literal> respnds with the <link linkend="song_info_responses">files</link> that match the specified pattern with the specified data (either <literal>filename</literal>, <literal>artist</literal>, <literal>album</literal>, or <literal>title</literal>).</para> </sect3> <sect3> <title> <literal>find</literal> </title> + <para><programlisting>find artist <emphasis>match</emphasis> +find album <emphasis>match</emphasis></programlisting><literal>find</literal> responds with the <link linkend="song_info_responses">files</link> whose <literal>artist</literal> or <literal>album</literal> are the same as <emphasis>match</emphasis>.</para> </sect3> <sect3> <title> <literal>list</literal> </title> + <para><programlisting>list artist +list album +list album <emphasis>someArtist</emphasis></programlisting><literal>list</literal> responds with the list of albums or artists in the db.</para> </sect3> </sect2> <sect2> @@ -91,71 +118,90 @@ OK</programlisting></para> <title> <literal>playlistinfo</literal> </title> + <para><programlisting>playlistinfo +playlistinfo -1 +playlistinfo <emphasis>position</emphasis></programlisting></para> </sect3> <sect3> <title> <literal>playlistid</literal> </title> + <para><programlisting>playlistid +playlistid -1 +playlistid <emphasis>id</emphasis></programlisting></para> </sect3> <sect3> <title> <literal>plchanges</literal> </title> + <para><programlisting>plchanges <emphasis>version</emphasis></programlisting></para> </sect3> <sect3> <title> <literal>deleteid</literal> </title> + <para><programlisting>deleteid <emphasis>id</emphasis></programlisting></para> </sect3> <sect3> <title> <literal>delete</literal> </title> + <para><programlisting>delete <emphasis>position</emphasis></programlisting></para> </sect3> <sect3> <title> <literal>add</literal> </title> + <para><programlisting>add <emphasis>file</emphasis> +add <emphasis>url</emphasis></programlisting></para> </sect3> <sect3> <title> <literal>moveid</literal> </title> + <para><programlisting>movid <emphasis>id</emphasis></programlisting></para> </sect3> <sect3> <title> <literal>move</literal> </title> + <para><programlisting>move <emphasis>position</emphasis></programlisting></para> </sect3> <sect3> <title> <literal>swapid</literal> </title> + <para><programlisting>swapid <emphasis>id</emphasis></programlisting></para> </sect3> <sect3> <title> <literal>swap</literal> </title> + <para><programlisting>swap <emphasis>position</emphasis></programlisting></para> </sect3> <sect3> <title> <literal>clear</literal> </title> + <para><programlisting>clear</programlisting></para> </sect3> <sect3> <title> <literal>save</literal> </title> + <para><programlisting>save</programlisting></para> </sect3> <sect3> <title> <literal>shuffle</literal> </title> + <para><programlisting>shuffle</programlisting></para> </sect3> <sect3> <title> <literal>rm</literal> </title> + <para><programlisting>rm</programlisting></para> </sect3> </sect2> <sect2> @@ -164,6 +210,13 @@ OK</programlisting></para> <title> <literal>status</literal> </title> + <para><programlisting>status</programlisting></para> + </sect3> + <sect3> + <title> + <literal>currentsong</literal> + </title> + <para><programlisting>currentsong</programlisting></para> </sect3> </sect2> <sect2> @@ -172,41 +225,56 @@ OK</programlisting></para> <title> <literal>playid</literal> </title> + <para><programlisting>playid +playid -1 +playid <emphasis>id</emphasis></programlisting></para> </sect3> <sect3> <title> <literal>play</literal> </title> + <para><programlisting>play +play -1 +play <emphasis>position</emphasis></programlisting></para> </sect3> <sect3> <title> <literal>pause</literal> </title> + <para><programlisting>pause 0 +pause 1</programlisting></para> </sect3> <sect3> <title> <literal>stop</literal> </title> + <para><programlisting>stop</programlisting></para> </sect3> <sect3> <title> <literal>seekid</literal> </title> + <para><programlisting>seekid <emphasis>id</emphasis> <emphasis>seconds</emphasis></programlisting></para> </sect3> <sect3> <title> <literal>seek</literal> </title> + <para><programlisting>seek <emphasis>position</emphasis> <emphasis>seconds</emphasis></programlisting></para> </sect3> <sect3> <title> <literal>repeat</literal> </title> + <para><programlisting>repeat 0 +repeat 1</programlisting></para> </sect3> <sect3> <title> <literal>random</literal> </title> + <para><programlisting>random 0 +random 1</programlisting></para> </sect3> </sect2> <sect2> @@ -215,16 +283,19 @@ OK</programlisting></para> <title> <literal>password</literal> </title> + <para><programlisting>password <emphasis>psswd</emphasis></programlisting></para> </sect3> <sect3> <title> <literal>stats</literal> </title> + <para><programlisting>stats</programlisting></para> </sect3> <sect3> <title> <literal>kill</literal> </title> + <para><programlisting>kill</programlisting></para> </sect3> </sect2> </sect1> |