aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorWarren Dukes <warren.dukes@gmail.com>2004-06-13 03:24:15 +0000
committerWarren Dukes <warren.dukes@gmail.com>2004-06-13 03:24:15 +0000
commit8c445d3f1b15cb51d55db05a8ad5e84ecd59d4d9 (patch)
treef6b160650690ffb2f6b5bf52a5c84faffa0bf072 /doc
parentb7e0d34b9e16c04839bf047e978d75b255a388f6 (diff)
downloadmpd-8c445d3f1b15cb51d55db05a8ad5e84ecd59d4d9.tar.gz
mpd-8c445d3f1b15cb51d55db05a8ad5e84ecd59d4d9.tar.xz
mpd-8c445d3f1b15cb51d55db05a8ad5e84ecd59d4d9.zip
docbook MPD Protocol documentation beginnings
git-svn-id: https://svn.musicpd.org/mpd/trunk@1454 09075e82-0dd4-0310-85a5-a0d7c8717e4f
Diffstat (limited to 'doc')
-rw-r--r--doc/MPD-Protocol.xml244
1 files changed, 244 insertions, 0 deletions
diff --git a/doc/MPD-Protocol.xml b/doc/MPD-Protocol.xml
new file mode 100644
index 000000000..2cfaa8e9d
--- /dev/null
+++ b/doc/MPD-Protocol.xml
@@ -0,0 +1,244 @@
+<?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>
+ <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>
+ <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>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>
+ <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>
+ <title>Commands</title>
+ <sect2>
+ <title>DB: Browsing, Searching, and Finding</title>
+ <sect3>
+ <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>
+ <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>
+ <title>
+ <literal>lsinfo</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>listall</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>search</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>find</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>list</literal>
+ </title>
+ </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>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>playlistid</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>plchanges</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>deleteid</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>delete</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>add</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>moveid</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>move</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>swapid</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>swap</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>clear</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>save</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>shuffle</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>rm</literal>
+ </title>
+ </sect3>
+ </sect2>
+ <sect2>
+ <title>Status Queries</title>
+ <sect3>
+ <title>
+ <literal>status</literal>
+ </title>
+ </sect3>
+ </sect2>
+ <sect2>
+ <title>Playback: Play, Pause, Stop, and Seek</title>
+ <sect3>
+ <title>
+ <literal>playid</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>play</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>pause</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>stop</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>seekid</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>seek</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>repeat</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>random</literal>
+ </title>
+ </sect3>
+ </sect2>
+ <sect2>
+ <title>Miscellanous Commands</title>
+ <sect3>
+ <title>
+ <literal>password</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>stats</literal>
+ </title>
+ </sect3>
+ <sect3>
+ <title>
+ <literal>kill</literal>
+ </title>
+ </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>
+