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