aboutsummaryrefslogtreecommitdiffstats
path: root/doc/protocol.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/protocol.xml')
-rw-r--r--doc/protocol.xml200
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>