path: root/doc/MPD-Protocol.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" []>
<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 id="playlist_song_metadata">Additional Song Metadata</title>
        <para>In addition to the same <link linkend="song_info_responses">song metadata</link> returned when browsing, songs in a playlist have two additional metadata elements.  <literal>Pos</literal> is the position in the playlist of the song and <literal>Id</literal> is the playlist id for a song (each song in the playlist has a unique <literal>Id</literal>, even if there is a duplicate entry for the same <literal>file</literal>).<programlisting>file: <emphasis>directory/song</emphasis>
Artist: <emphasis>famousArtist</emphasis>
Title: <emphasis>popularSong</emphasis>
Num: <emphasis>0</emphasis>
Id: <emphasis>23</emphasis>
file: <emphasis>directory/song</emphasis>
Artist: <emphasis>famouseArtist</emphasis>
Title: <emphasis>popularSong</emphasis>
Num: <emphasis>1</emphasis>
Id: <emphasis>132</emphasis></programlisting></para>
      </sect3>
      <sect3>
        <title id="song_id_vs_positiion">Song ID&apos;s vs Playlist Position</title>
        <para>When implementing a client for MPD, the developer must keep in mind that multiple clients maybe manipulating the playlist simultaneously.  Thus, its essential to use playlist song id&apos;s instead of  the playlist position for manipulating the playlist.  This is due to the fact that another client maybe moving, deleting, etc... songs in the playlist, thus changing the order and positions of songs in the playlist.  Consequently, using song id&apos;s is a safer method for manipulating the playlist as the song id&apos;s do not depend on the order and positions of songs in the playlist.</para>
      </sect3>
      <sect3>
        <title>
          <literal>playlistinfo</literal>
        </title>
        <para><programlisting>playlistinfo
playlistinfo -1
playlistinfo <emphasis>position</emphasis></programlisting><literal>playlistinfo</literal> responds with the <link linkend="playlist_song_metadata">information about songs</link> in the playlist.  If no argument is passed to <literal>playlistinfo</literal> or an argument of <literal>-1</literal> is passed, then every song in the playlist is returned.  If a playlist <emphasis>position</emphasis> is passed to <literal>playlistinfo</literal>, then the information about the song at <emphasis>position</emphasis> is returned.  Note: It&apos;s suggest that <link linkend="playlistid">
            <literal>playlistid</literal>
          </link> be used instead of <literal>playlistinfo</literal>.</para>
      </sect3>
      <sect3 id="playlistinfo">
        <title id="playlistid">
          <literal>playlistid</literal>
        </title>
        <para><programlisting>playlistid
playlistid -1
playlistid <emphasis>id</emphasis></programlisting><literal>playlistid</literal> is the same as <literal>
            <link linkend="playlistinfo">playlistinfo</link>
          </literal> except that  using optional argument <emphasis>id</emphasis>   causes the information for the song with  the playlist song ID <emphasis>id</emphasis>to be returned.</para>
      </sect3>
      <sect3>
        <title>
          <literal>plchanges</literal>
        </title>
        <para><programlisting>plchanges <emphasis>version</emphasis></programlisting><literal>plchanges</literal> responds with the <link linkend="playlist_song_metadata">song information</link> for songs that have changed since the <link linkend="status">playlist version</link> <emphasis>version</emphasis>.  Note, to detect songs that were removed at the end of the playlist, use the  playlist length returned by <link linkend="status">status</link>.</para>
      </sect3>
      <sect3>
        <title id="deleteid">
          <literal>deleteid</literal>
        </title>
        <para><programlisting>deleteid <emphasis>id</emphasis></programlisting><literal>deleteid</literal>  removes the song with the playlist song id <emphasis>id</emphasis> from the playlist.</para>
      </sect3>
      <sect3>
        <title>
          <literal>delete</literal>
        </title>
        <para><programlisting>delete <emphasis>position</emphasis></programlisting><literal>delete</literal> removes the song at the playlist position <emphasis>position</emphasis> from the playlist.  Note: It&apos;s suggested that <link linkend="deleteid">
            <literal>deleteid</literal>
          </link> be used instead of <literal>delete</literal>.</para>
      </sect3>
      <sect3>
        <title>
          <literal>add</literal>
        </title>
        <para><programlisting>add <emphasis>file</emphasis>
add <emphasis>url</emphasis></programlisting><literal>add</literal> appends the <emphasis>file</emphasis> or <emphasis>url</emphasis> to the end of the playlist</para>
      </sect3>
      <sect3>
        <title>
          <literal>moveid</literal>
        </title>
        <para><programlisting>movid <emphasis>id</emphasis> <emphasis>position</emphasis></programlisting></para>
      </sect3>
      <sect3>
        <title>
          <literal>move</literal>
        </title>
        <para><programlisting>move <emphasis>position</emphasis> <emphasis>position</emphasis></programlisting></para>
      </sect3>
      <sect3>
        <title>
          <literal>swapid</literal>
        </title>
        <para><programlisting>swapid <emphasis>id1</emphasis> <emphasis>id2</emphasis></programlisting></para>
      </sect3>
      <sect3>
        <title>
          <literal>swap</literal>
        </title>
        <para><programlisting>swap <emphasis>position1</emphasis> <emphasis>position2</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 id="status">
          <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>