diff options
Diffstat (limited to 'doc/protocol.xml')
| -rw-r--r-- | doc/protocol.xml | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/doc/protocol.xml b/doc/protocol.xml index 0b4f0d175..aba080a6a 100644 --- a/doc/protocol.xml +++ b/doc/protocol.xml @@ -204,6 +204,47 @@ </chapter> <chapter> + <title>Recipes</title> + + <section> + <title>Queuing</title> + + <para> + Often, users run MPD 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 + "priority" for each song in the playlist (commands <link + linkend="command_prio"><command>prio</command></link> and + <link + linkend="command_prioid"><command>prioid</command></link>). A + higher priority means that the song is going to be played + before the other songs. + </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. + </para> + </section> + </chapter> + + <chapter> <title>Command reference</title> <note> @@ -318,6 +359,25 @@ <option>crossfade</option>, replay gain </para> </listitem> + <listitem> + <para> + <returnvalue>sticker</returnvalue>: the sticker database + has been modified. + </para> + </listitem> + <listitem> + <para> + <returnvalue>subscription</returnvalue>: a client + has subscribed or unsubscribed to a channel + </para> + </listitem> + <listitem> + <para> + <returnvalue>message</returnvalue>: a message was + received on a channel this client is subscribed to; + this event is only emitted when the queue is empty + </para> + </listitem> </itemizedlist> <para> While a client is waiting for <command>idle</command> @@ -1073,6 +1133,46 @@ OK </para> </listitem> </varlistentry> + + <varlistentry id="command_prio"> + <term> + <cmdsynopsis> + <command>prio</command> + <arg choice="req"><replaceable>PRIORITY</replaceable></arg> + <arg choice="req" rep="repeat"><replaceable>START:END</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Set the priority of the specified songs. A higher + priority means that it will be played first when + "random" mode is enabled. + </para> + + <para> + A priority is an integer between 0 and 255. The default + priority of new songs is 0. + </para> + </listitem> + </varlistentry> + + <varlistentry id="command_prioid"> + <term> + <cmdsynopsis> + <command>prioid</command> + <arg choice="req"><replaceable>PRIORITY</replaceable></arg> + <arg choice="req" rep="repeat"><replaceable>ID</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Same as <link + linkend="command_prio"><command>prio</command></link>, + but address the songs with their id. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_shuffle"> <term> <cmdsynopsis> @@ -1790,5 +1890,105 @@ suffix: mpc</programlisting> </varlistentry> </variablelist> </section> + + <section> + <title>Client to client</title> + + <para> + Clients can communicate with each others over "channels". A + channel is created by a client subscribing to it. More than + one client can be subscribed to a channel at a time; all of + them will receive the messages which get sent to it. + </para> + + <para> + Each time a client subscribes or unsubscribes, the global idle + event <varname>subscription</varname> is generated. In + conjunction with the <command>channels</command> command, this + may be used to auto-detect clients providing additional + services. + </para> + + <para> + A new messages is indicated by the <varname>message</varname> + idle event. + </para> + + <variablelist> + <varlistentry id="command_subscribe"> + <term> + <cmdsynopsis> + <command>subscribe</command> + <arg choice="req"><replaceable>NAME</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Subscribe to a channel. The channel is created if it + does not exist already. The name may consist of + alphanumeric ASCII characters plus underscore, dash, dot + and colon. + </para> + </listitem> + </varlistentry> + + <varlistentry id="command_unsubscribe"> + <term> + <cmdsynopsis> + <command>unsubscribe</command> + <arg choice="req"><replaceable>NAME</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Unsubscribe from a channel. + </para> + </listitem> + </varlistentry> + + <varlistentry id="command_channels"> + <term> + <cmdsynopsis> + <command>channels</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Obtain a list of all channels. The response is a list + of "channel:" lines. + </para> + </listitem> + </varlistentry> + + <varlistentry id="command_readmessages"> + <term> + <cmdsynopsis> + <command>readmessages</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Reads messages for this client. The response is a list + of "channel:" and "message:" lines. + </para> + </listitem> + </varlistentry> + + <varlistentry id="command_sendmessage"> + <term> + <cmdsynopsis> + <command>sendmessage</command> + <arg choice="req"><replaceable>CHANNEL</replaceable></arg> + <arg choice="req"><replaceable>TEXT</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Send a message to the specified channel. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> </chapter> </book> |