path: root/doc/MPD-Protocol.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "docbook/xml-dtd-4.2-1.0-24/docbookx.dtd" []>
<article>
  <title>MPD Protocol</title>
  <articleinfo>
    <releaseinfo>Version 0.11.0</releaseinfo>
    <copyright>
      <year>2004</year>
      <holder>Warren Dukes</holder>
    </copyright>
  </articleinfo>
  <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 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 &apos;<literal>\n</literal>&apos;.<programlisting>command &quot;arg1&quot; &quot;arg2&quot;</programlisting></para>
    </sect2>
    <sect2>
      <title id="format_of_responses">Format of Responses</title>
      <para>The different response elements of a command are seperated by the return character &apos;<literal>\n</literal>&apos;.  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 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
command2 arg1 arg2
command3 arg1 arg2
command_list_end</programlisting></para>
      <para>The responses for command executed with command lists are the same with the exception that an<literal>OK</literal> or <literal>ACK</literal> is not returned for each command.   Instead a single <literal>OK</literal> or <literal>ACK</literal> is returned for the entire command list.  An <literal>OK</literal> indicates that all the commands in the command list were successfully executed; while an <literal>ACK</literal> error is returned on the first unsuccessful command in the command list and none of the following commands in the command     are executed.</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 id="commands">
    <title>Commands</title>
    <sect2 id="db_browsing">
      <title>DB: Browsing, Searching, and Finding</title>
      <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&apos;s an example of a complete browsing response:<programlisting>file: Directory/file.mp3
Artist: Muscian
Album: Record
Time: 23
directory: Directory/Subdirectory
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 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 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>
      <title>Playlist: Adding, Deleting, and Managment</title>
      <sect3>
        <title>Additional Song Metadata</title>
      </sect3>
      <sect3>
        <title>Song ID&apos;s vs Playlist Position</title>
      </sect3>
      <sect3>
        <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>
      <title>Status Queries</title>
      <sect3>
        <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>
      <title>Playback: Play, Pause, Stop, and Seek</title>
      <sect3>
        <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>
      <title>Miscellanous Commands</title>
      <sect3>
        <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>
  <sect1>
    <title>ACK Errors</title>
    <sect2>
      <title>Common Errors</title>
    </sect2>
    <sect2>
      <title>Command Specific</title>
    </sect2>
  </sect1>
  <sect1>
    <title>Guidelines</title>
  </sect1>
</article>