oysteikt/mpd
0
0
Fork 0
Code Issues Pull Requests Releases Activity

doc/protocol: add more markup

Browse Source
This commit is contained in:
Max Kellermann 2014-10-10 23:22:37 +02:00
parent 464767c5fd
commit 63272541eb
1 changed files with 71 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
doc/protocol.xml
View File

@ -11,11 +11,11 @@
<title>Protocol overview</title> <title>Protocol overview</title>
<para> <para>
The MPD command protocol exchanges line-based text records The <application>MPD</application> command protocol exchanges
between client and server over TCP. Once the client is line-based text records between client and server over TCP.
connected to the server, they conduct a conversation until the Once the client is connected to the server, they conduct a
client closes the connection. The conversation flow is always conversation until the client closes the connection. The
initiated by the client. conversation flow is always initiated by the client.
</para> </para>
<para> <para>
@ -210,14 +210,14 @@
<title>Queuing</title> <title>Queuing</title>
<para> <para>
Often, users run MPD with "<link Often, users run <application>MPD</application> with "<link
linkend="command_random">random</link>" enabled, but want to linkend="command_random">random</link>" enabled, but want to
be able to insert songs "before" the rest of the playlist. be able to insert songs "before" the rest of the playlist.
That is commonly called "queuing". That is commonly called "queuing".
</para> </para>
<para> <para>
MPD implements this by allowing the client to specify a <application>MPD</application> implements this by allowing the client to specify a
"priority" for each song in the playlist (commands <link "priority" for each song in the playlist (commands <link
linkend="command_prio"><command>prio</command></link> and linkend="command_prio"><command>prio</command></link> and
<link <link
@ -227,19 +227,20 @@
</para> </para>
<para> <para>
In "random" mode, MPD maintains an internal randomized In "random" mode, <application>MPD</application> maintains an
sequence of songs. In this sequence, songs with a higher internal randomized sequence of songs. In this sequence,
priority come first, and all songs with the same priority are songs with a higher priority come first, and all songs with
shuffled (by default, all songs are shuffled, because all have the same priority are shuffled (by default, all songs are
the same priority "0"). When you increase the priority of a shuffled, because all have the same priority "0"). When you
song, it is moved to the front of the sequence according to increase the priority of a song, it is moved to the front of
its new priority, but always after the current one. A song the sequence according to its new priority, but always after
that has been played already (it's "before" the current song the current one. A song that has been played already (it's
in that sequence) will only be scheduled for repeated playback "before" the current song in that sequence) will only be
if its priority has become bigger than the priority of the scheduled for repeated playback if its priority has become
current song. Decreasing the priority of a song will moved it bigger than the priority of the current song. Decreasing the
farther to the end of the sequence. Changing the priority of priority of a song will moved it farther to the end of the
the current song has no effect on the sequence. sequence. Changing the priority of the current song has no
effect on the sequence.
</para> </para>
</section> </section>
</chapter> </chapter>
@ -255,12 +256,12 @@
commands using song ids should be used instead of the commands commands using song ids should be used instead of the commands
that manipulate and control playback based on playlist that manipulate and control playback based on playlist
position. Using song ids is a safer method when multiple position. Using song ids is a safer method when multiple
clients are interacting with MPD. clients are interacting with <application>MPD</application>.
</para> </para>
</note> </note>
<section id="status_commands"> <section id="status_commands">
<title>Querying MPD's status</title> <title>Querying <application>MPD</application>'s status</title>
<variablelist> <variablelist>
<varlistentry id="command_clearerror"> <varlistentry id="command_clearerror">
@ -298,12 +299,14 @@
</term> </term>
<listitem> <listitem>
<para> <para>
<footnote id="since_0_14"><simpara>Introduced with MPD 0.14</simpara></footnote> <footnote id="since_0_14"><simpara>Introduced with
<application>MPD</application> 0.14</simpara></footnote>
Waits until there is a noteworthy change in one or more Waits until there is a noteworthy change in one or more
of MPD's subsystems. As soon as there is one, it lists of <application>MPD</application>'s subsystems. As soon
all changed systems in a line in the format as there is one, it lists all changed systems in a line
<returnvalue>changed: SUBSYSTEM</returnvalue>, where in the format <returnvalue>changed:
SUBSYSTEM is one of the following: SUBSYSTEM</returnvalue>, where SUBSYSTEM is one of the
following:
</para> </para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -385,14 +388,15 @@
to wait for events as long as mpd runs. The to wait for events as long as mpd runs. The
<command>idle</command> command can be canceled by <command>idle</command> command can be canceled by
sending the command <command>noidle</command> (no other sending the command <command>noidle</command> (no other
commands are allowed). MPD will then leave commands are allowed). <application>MPD</application>
<command>idle</command> mode and print results will then leave <command>idle</command> mode and print
immediately; might be empty at this time. results immediately; might be empty at this time.
</para> </para>
<para> <para>
If the optional <varname>SUBSYSTEMS</varname> argument is used, If the optional <varname>SUBSYSTEMS</varname> argument
MPD will only send notifications when something changed in is used, <application>MPD</application> will only send
one of the specified subsytems. notifications when something changed in one of the
specified subsytems.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -429,7 +433,7 @@
<listitem> <listitem>
<para> <para>
<varname>single</varname>: <varname>single</varname>:
<footnote id="since_0_15"><simpara>Introduced with MPD 0.15</simpara></footnote> <footnote id="since_0_15"><simpara>Introduced with <application>MPD</application> 0.15</simpara></footnote>
<returnvalue>0 or 1</returnvalue> <returnvalue>0 or 1</returnvalue>
</para> </para>
</listitem> </listitem>
@ -504,7 +508,7 @@
<listitem> <listitem>
<para> <para>
<varname>elapsed</varname>: <varname>elapsed</varname>:
<footnote id="since_0_16"><simpara>Introduced with MPD 0.16</simpara></footnote> <footnote id="since_0_16"><simpara>Introduced with <application>MPD</application> 0.16</simpara></footnote>
<returnvalue> <returnvalue>
Total time elapsed within the current song, but Total time elapsed within the current song, but
with higher resolution. with higher resolution.
@ -745,7 +749,7 @@
<parameter>album</parameter>, <parameter>album</parameter>,
<parameter>auto</parameter><footnote <parameter>auto</parameter><footnote
id="replay_gain_auto_since_0_16"> id="replay_gain_auto_since_0_16">
<simpara>added in MPD 0.16</simpara> <simpara>added in <application>MPD</application> 0.16</simpara>
</footnote>. </footnote>.
</para> </para>
<para> <para>
@ -1037,7 +1041,7 @@ OK
at <varname>START:END</varname> to <varname>TO</varname> at <varname>START:END</varname> to <varname>TO</varname>
in the playlist. in the playlist.
<footnote id="range_since_0_15"> <footnote id="range_since_0_15">
<simpara>Ranges are supported since MPD 0.15</simpara> <simpara>Ranges are supported since <application>MPD</application> 0.15</simpara>
</footnote> </footnote>
</para> </para>
</listitem> </listitem>
@ -1230,7 +1234,7 @@ OK
</term> </term>
<listitem> <listitem>
<para> <para>
<footnote id="since_0_19"><simpara>Since MPD <footnote id="since_0_19"><simpara>Since <application>MPD</application>
0.19</simpara></footnote> Specifies the portion of the 0.19</simpara></footnote> Specifies the portion of the
song that shall be played. <varname>START</varname> and song that shall be played. <varname>START</varname> and
<varname>END</varname> are offsets in seconds <varname>END</varname> are offsets in seconds
@ -1560,7 +1564,7 @@ OK
<para> <para>
Finds songs in the db that are exactly Finds songs in the db that are exactly
<varname>WHAT</varname>. <varname>TYPE</varname> can <varname>WHAT</varname>. <varname>TYPE</varname> can
be any tag supported by MPD, or one of the special be any tag supported by <application>MPD</application>, or one of the special
parameters: parameters:
</para> </para>
@ -1634,7 +1638,8 @@ OK
<listitem> <listitem>
<para> <para>
Lists unique tags values of the specified type. Lists unique tags values of the specified type.
<varname>TYPE</varname> can be any tag supported by MPD or <varname>TYPE</varname> can be any tag supported by
<application>MPD</application> or
<parameter>file</parameter>. <parameter>file</parameter>.
</para> </para>
<para> <para>
@ -1667,9 +1672,11 @@ OK
</para> </para>
<para> <para>
Do not use this command. Do not manage a client-side Do not use this command. Do not manage a client-side
copy of MPD's database. That is fragile and adds huge copy of <application>MPD</application>'s database. That
overhead. It will break with large databases. Instead, is fragile and adds huge overhead. It will break with
query MPD whenever you need something. large databases. Instead, query
<application>MPD</application> whenever you need
something.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1688,9 +1695,11 @@ OK
</para> </para>
<para> <para>
Do not use this command. Do not manage a client-side Do not use this command. Do not manage a client-side
copy of MPD's database. That is fragile and adds huge copy of <application>MPD</application>'s database. That
overhead. It will break with large databases. Instead, is fragile and adds huge overhead. It will break with
query MPD whenever you need something. large databases. Instead, query
<application>MPD</application> whenever you need
something.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1705,12 +1714,13 @@ OK
<para> <para>
Lists the contents of the directory Lists the contents of the directory
<varname>URI</varname>, including files are not <varname>URI</varname>, including files are not
recognized by MPD. <varname>URI</varname> can be a path recognized by <application>MPD</application>.
relative to the music directory or an URI understood by <varname>URI</varname> can be a path relative to the
one of the storage plugins. The response contains at music directory or an URI understood by one of the
least one line for each directory entry with the prefix storage plugins. The response contains at least one
"file: " or "directory: ", and may be followed by file line for each directory entry with the prefix "file: "
attributes such as "Last-Modified" and "size". or "directory: ", and may be followed by file attributes
such as "Last-Modified" and "size".
</para> </para>
<para> <para>
For example, "smb://SERVER" returns a list of all shares For example, "smb://SERVER" returns a list of all shares
@ -1887,17 +1897,19 @@ OK
<para> <para>
"Stickers"<footnoteref linkend="since_0_15"/> are pieces of "Stickers"<footnoteref linkend="since_0_15"/> are pieces of
information attached to existing MPD objects (e.g. song files, information attached to existing
<application>MPD</application> objects (e.g. song files,
directories, albums). Clients can create arbitrary name/value directories, albums). Clients can create arbitrary name/value
pairs. MPD itself does not assume any special meaning in pairs. <application>MPD</application> itself does not assume
them. any special meaning in them.
</para> </para>
<para> <para>
The goal is to allow clients to share additional (possibly The goal is to allow clients to share additional (possibly
dynamic) information about songs, which is neither stored on dynamic) information about songs, which is neither stored on
the client (not available to other clients), nor stored in the the client (not available to other clients), nor stored in the
song files (MPD has no write access). song files (<application>MPD</application> has no write
access).
</para> </para>
<para> <para>
@ -2014,7 +2026,8 @@ OK
</term> </term>
<listitem> <listitem>
<para> <para>
Closes the connection to MPD. MPD will try to send the Closes the connection to <application>MPD</application>.
<application>MPD</application> will try to send the
remaining output buffer before it actually closes the remaining output buffer before it actually closes the
connection, but that cannot be guaranteed. This command connection, but that cannot be guaranteed. This command
will not generate a response. will not generate a response.
@ -2029,7 +2042,7 @@ OK
</term> </term>
<listitem> <listitem>
<para> <para>
Kills MPD. Kills <application>MPD</application>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>