aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/doxygen.conf.in (renamed from doc/doxygen.conf)6
-rw-r--r--doc/mpd.conf.521
-rw-r--r--doc/mpdconf.example6
-rw-r--r--doc/protocol.xml208
-rw-r--r--doc/user.xml348
5 files changed, 583 insertions, 6 deletions
diff --git a/doc/doxygen.conf b/doc/doxygen.conf.in
index ddece77e8..95dca9a3c 100644
--- a/doc/doxygen.conf
+++ b/doc/doxygen.conf.in
@@ -31,7 +31,7 @@ PROJECT_NAME = MPD
# This could be handy for archiving the generated documentation or
# if some version control system is used.
-PROJECT_NUMBER =
+PROJECT_NUMBER = @VERSION@
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
# base path where the generated documentation will be put.
@@ -481,7 +481,7 @@ FILE_VERSION_FILTER =
# The QUIET tag can be used to turn on/off the messages that are generated
# by doxygen. Possible values are YES and NO. If left blank NO is used.
-QUIET = NO
+QUIET = YES
# The WARNINGS tag can be used to turn on/off the warning messages that are
# generated by doxygen. Possible values are YES and NO. If left blank
@@ -534,7 +534,7 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
-INPUT = src/
+INPUT = @abs_top_srcdir@/src/
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
diff --git a/doc/mpd.conf.5 b/doc/mpd.conf.5
index 4cddd7ba9..bd890228b 100644
--- a/doc/mpd.conf.5
+++ b/doc/mpd.conf.5
@@ -69,6 +69,9 @@ mpd will be saved to this file when mpd is terminated by a TERM signal or by
the "kill" command. When mpd is restarted, it will read the state file and
restore the state of mpd (including the playlist).
.TP
+.B restore_paused <yes or no>
+Put MPD into pause mode instead of starting playback after startup.
+.TP
.B user <username>
This specifies the user that MPD will run as, if set. MPD should
never run as root, and you may use this option to make MPD change its
@@ -80,6 +83,10 @@ This specifies which address mpd binds to and listens on. Multiple
bind_to_address parameters may be specified. The default is "any", which binds
to all available addresses.
+You can set a port that is different from the global port setting,
+e.g. "localhost:6602". IPv6 addresses must be enclosed in square
+brackets if you want to configure a port, e.g. "[::1]:6602".
+
To bind to a Unix domain socket, specify an absolute path. For a
system-wide MPD, we suggest the path "\fB/var/run/mpd/socket\fP".
.TP
@@ -259,6 +266,17 @@ of database.
.B auto_update_depth <N>
Limit the depth of the directories being watched, 0 means only watch
the music directory itself. There is no limit by default.
+.TP
+.B despotify_user <name>
+This specifies the user to use when logging in to Spotify using the despotify plugins.
+.TP
+.B despotify_password <name>
+This specifies the password to use when logging in to Spotify using the despotify plugins.
+.TP
+.B despotify_high_bitrate <yes or no>
+This specifies if the requested bitrate for Spotify should be high or not. Higher sounds
+better but requires more processing and higher bandwidth. Default is yes.
+.TP
.SH REQUIRED AUDIO OUTPUT PARAMETERS
.TP
.B type <type>
@@ -464,6 +482,9 @@ connect to the icecast server. The default is 2 seconds.
.B description <description>
This specifies a description of the stream.
.TP
+.B url <url>
+This specifies a URL associated with the stream.
+.TP
.B genre <genre>
This specifies the genre(s) of the stream.
.SH FILES
diff --git a/doc/mpdconf.example b/doc/mpdconf.example
index b14337c76..1aa9cf1dc 100644
--- a/doc/mpdconf.example
+++ b/doc/mpdconf.example
@@ -103,6 +103,11 @@
#
#gapless_mp3_playback "yes"
#
+# Setting "restore_paused" to "yes" puts MPD into pause mode instead
+# of starting playback after startup.
+#
+#restore_paused "no"
+#
# This setting enables MPD to create playlists in a format usable by other
# music players.
#
@@ -235,6 +240,7 @@ input {
## protocol "icecast2" # optional
## user "source" # optional
## description "My Stream Description" # optional
+## url "http://example.com" # optional
## genre "jazz" # optional
## public "no" # optional
## timeout "2" # optional
diff --git a/doc/protocol.xml b/doc/protocol.xml
index 0b4f0d175..d99a00b24 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>
@@ -677,7 +737,11 @@
Sets the replay gain mode. One of
<parameter>off</parameter>,
<parameter>track</parameter>,
- <parameter>album</parameter>.
+ <parameter>album</parameter>,
+ <parameter>auto</parameter><footnote
+ id="replay_gain_auto_since_0_16">
+ <simpara>added in MPD 0.16</simpara>
+ </footnote>.
</para>
<para>
Changing the mode during playback may take several
@@ -1073,6 +1137,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>
@@ -1681,6 +1785,7 @@ OK
<term>
<cmdsynopsis>
<command>disableoutput</command>
+ <arg choice="req"><replaceable>ID</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
@@ -1693,6 +1798,7 @@ OK
<term>
<cmdsynopsis>
<command>enableoutput</command>
+ <arg choice="req"><replaceable>ID</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>
@@ -1790,5 +1896,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>
diff --git a/doc/user.xml b/doc/user.xml
index 6a9871007..4bd849f96 100644
--- a/doc/user.xml
+++ b/doc/user.xml
@@ -236,6 +236,16 @@ cd mpd-version</programlisting>
</section>
<section>
+ <title>Configuring encoder plugins</title>
+
+ <para>
+ Encoders are used by some of the output plugins (such as
+ <varname>shout</varname>). The encoder settings are included
+ in the <varname>audio_output</varname> section.
+ </para>
+ </section>
+
+ <section>
<title>Configuring audio outputs</title>
<para>
@@ -322,7 +332,8 @@ cd mpd-version</programlisting>
<varname>24_3</varname> (signed 24 bit integer
samples, no padding, 3 bytes per sample),
<varname>32</varname> (signed 32 bit integer
- samples).
+ samples), <varname>f</varname> (32 bit floating
+ point, -1.0 to 1.0).
</para>
</entry>
</row>
@@ -346,7 +357,7 @@ cd mpd-version</programlisting>
If set to "yes", then MPD attempts to keep this audio
output always open. This may be useful for streaming
servers, when you don't want to disconnect all
- listeners even when playback is accidently stopped.
+ listeners even when playback is accidentally stopped.
</entry>
</row>
<row>
@@ -621,12 +632,143 @@ cd mpd-version</programlisting>
Plays streams with the MMS protocol.
</para>
</section>
+
+ <section>
+ <title><varname>cdio_paranoia</varname></title>
+
+ <para>
+ Plays audio CDs. The URI has the form:
+ "<filename>cdda://[DEVICE][/TRACK]</filename>". The
+ simplest form <filename>cdda://</filename> plays the whole
+ disc in the default drive.
+ </para>
+ </section>
+
+ <section>
+ <title><varname>despotify</varname></title>
+
+ <para>
+ Plays <ulink url="http://www.spotify.com">Spotify</ulink> tracks using the despotify
+ library. The despotify plugin uses a <filename>spt://</filename> URI and a Spotify
+ URL. So for example, you can add a song with:
+ </para>
+
+ <para>
+ <filename>mpc add spt://spotify:track:5qENVY0YEdZ7fiuOax70x1</filename>
+ </para>
+
+ <para>
+ You need a Spotify premium account to use this plugin, and you need
+ to setup username and password in the configuration file. The
+ configuration settings are global since the despotify playlist plugin
+ use the same settings.
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Setting</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <varname>despotify_user</varname>
+ </entry>
+ <entry>
+ Sets up the Spotify username (required)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <varname>despotify_password</varname>
+ </entry>
+ <entry>
+ Sets up the Spotify password (required)
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <varname>despotify_high_bitrate</varname>
+ </entry>
+ <entry>
+ Set up if high bitrate should be used for Spotify tunes.
+ High bitrate sounds better but slow systems can have problems
+ with playback (default yes).
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section>
+ <title><varname>soup</varname></title>
+
+ <para>
+ Opens remote files or streams over HTTP.
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Setting</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <varname>proxy</varname>
+ </entry>
+ <entry>
+ Sets the address of the HTTP proxy server.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
</section>
<section>
<title>Decoder plugins</title>
<section>
+ <title><varname>dsdiff</varname></title>
+
+ <para>
+ Decodes DFF files containing DSDIFF data (e.g. SACD rips).
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Setting</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <varname>lsbitfirst</varname>
+ <parameter>yes|no</parameter>
+ </entry>
+ <entry>
+ Decode the least significant bit first. Default is
+ "no".
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section>
<title><varname>mikmod</varname></title>
<para>
@@ -658,6 +800,178 @@ cd mpd-version</programlisting>
</section>
<section>
+ <title>Encoder plugins</title>
+
+ <section>
+ <title><varname>flac</varname></title>
+
+ <para>
+ Encodes into FLAC (lossless).
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Setting</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <varname>compression</varname>
+ </entry>
+ <entry>
+ Sets the <filename>libFLAC</filename> compression
+ level. The levels range from 0 (fastest, least
+ compression) to 8 (slowest, most compression).
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section>
+ <title><varname>lame</varname></title>
+
+ <para>
+ Encodes into MP3 using the LAME library.
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Setting</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <varname>quality</varname>
+ </entry>
+ <entry>
+ Sets the quality for VBR. 0 is the highest quality,
+ 9 is the lowest quality. Cannot be used with
+ <varname>bitrate</varname>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <varname>bitrate</varname>
+ </entry>
+ <entry>
+ Sets the bit rate in kilobit per second. Cannot be
+ used with <varname>quality</varname>.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section>
+ <title><varname>null</varname></title>
+
+ <para>
+ Does not encode anything, passes the input PCM data as-is.
+ </para>
+ </section>
+
+ <section>
+ <title><varname>twolame</varname></title>
+
+ <para>
+ Encodes into MP2 using the <filename>twolame</filename>
+ library.
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Setting</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <varname>quality</varname>
+ </entry>
+ <entry>
+ Sets the quality for VBR. 0 is the highest quality,
+ 9 is the lowest quality. Cannot be used with
+ <varname>bitrate</varname>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <varname>bitrate</varname>
+ </entry>
+ <entry>
+ Sets the bit rate in kilobit per second. Cannot be
+ used with <varname>quality</varname>.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section>
+ <title><varname>vorbis</varname></title>
+
+ <para>
+ Encodes into Ogg Vorbis.
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Setting</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <varname>quality</varname>
+ </entry>
+ <entry>
+ Sets the quality for VBR. -1 is the lowest quality,
+ 10 is the highest quality. Cannot be used with
+ <varname>bitrate</varname>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <varname>bitrate</varname>
+ </entry>
+ <entry>
+ Sets the bit rate in kilobit per second. Cannot be
+ used with <varname>quality</varname>.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section>
+ <title><varname>wave</varname></title>
+
+ <para>
+ Encodes into WAV (lossless).
+ </para>
+ </section>
+ </section>
+
+ <section>
<title>Output plugins</title>
<section>
@@ -1366,6 +1680,15 @@ cd mpd-version</programlisting>
</row>
<row>
<entry>
+ <varname>url</varname>
+ <parameter>URL</parameter>
+ </entry>
+ <entry>
+ Sets a URL associated with the stream (optional).
+ </entry>
+ </row>
+ <row>
+ <entry>
<varname>public</varname>
<parameter>yes|no</parameter>
</entry>
@@ -1498,6 +1821,27 @@ cd mpd-version</programlisting>
playlist files.
</para>
</section>
+
+ <section>
+ <title><varname>despotify</varname></title>
+
+ <para>
+ Adds <ulink url="http://www.spotify.com/">Spotify</ulink>
+ playlists. Spotify playlists use the <filename>spt://</filename> URI,
+ and a Spotify playlist URL. So for example, you can load a playlist
+ with
+ </para>
+
+ <para>
+ <filename>mpc load spt://spotify:user:simon.kagstrom:playlist:3SUwkOe5VbVHysZcidEZtH</filename>
+ </para>
+
+ <para>
+ See the despotify input plugin for configuration options (username
+ and password needs to be setup)
+ </para>
+ </section>
+
</section>
</chapter>
</book>