diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/doxygen.conf.in (renamed from doc/doxygen.conf) | 6 | ||||
| -rw-r--r-- | doc/mpd.conf.5 | 21 | ||||
| -rw-r--r-- | doc/mpdconf.example | 6 | ||||
| -rw-r--r-- | doc/protocol.xml | 277 | ||||
| -rw-r--r-- | doc/user.xml | 414 |
5 files changed, 716 insertions, 8 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..56ff33b1e 100644 --- a/doc/protocol.xml +++ b/doc/protocol.xml @@ -59,7 +59,7 @@ <para> All data between the client and the server is encoded in UTF-8. (Note: In UTF-8 all standard ansi characters, 0-127 are - the same as a standard ansi encoding. Also, no ansi character + the same as in standard ansi encoding. Also, no ansi character appears in any multi-byte characters. So, you can use standard C functions like <function>strlen</function>, and <function>strcpy</function> just fine with UTF-8 encoded @@ -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 @@ -814,6 +878,23 @@ </para> </listitem> </varlistentry> + + <varlistentry id="command_seekcur"> + <term> + <cmdsynopsis> + <command>seekcur</command> + <arg choice="req"><replaceable>TIME</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Seeks to the position <varname>TIME</varname> within the + current song. If prefixed by '+' or '-', then the time + is relative to the current playing position. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_stop"> <term> <cmdsynopsis> @@ -1073,6 +1154,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> @@ -1191,12 +1312,14 @@ OK <cmdsynopsis> <command>load</command> <arg choice="req"><replaceable>NAME</replaceable></arg> + <arg choice="opt"><replaceable>START:END</replaceable></arg> </cmdsynopsis> </term> <listitem> <para> Loads the playlist into the current queue. Playlist - plugins are supported. + plugins are supported. A range may be specified to load + only a part of the playlist. </para> </listitem> </varlistentry> @@ -1433,6 +1556,11 @@ OK the list of stored playlists. This behavior is deprecated; use "listplaylists" instead. </para> + <para> + Clients that are connected via UNIX domain socket may + use this command to read the tags of an arbitrary local + file (URI beginning with "file:///"). + </para> </listitem> </varlistentry> <varlistentry id="command_search"> @@ -1681,6 +1809,7 @@ OK <term> <cmdsynopsis> <command>disableoutput</command> + <arg choice="req"><replaceable>ID</replaceable></arg> </cmdsynopsis> </term> <listitem> @@ -1693,6 +1822,7 @@ OK <term> <cmdsynopsis> <command>enableoutput</command> + <arg choice="req"><replaceable>ID</replaceable></arg> </cmdsynopsis> </term> <listitem> @@ -1720,6 +1850,47 @@ OK <title>Reflection</title> <variablelist> + <varlistentry id="command_config"> + <term> + <cmdsynopsis> + <command>config</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Dumps configuration values that may be interesting for + the client. This command is only permitted to "local" + clients (connected via UNIX domain socket). + </para> + <para> + The following response attributes are available: + </para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + Name + </entry> + <entry> + Description + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <varname>music_directory</varname> + </entry> + <entry> + The absolute path of the music directory. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </listitem> + </varlistentry> <varlistentry id="command_commands"> <term> <cmdsynopsis> @@ -1790,5 +1961,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> + New messages are 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..46d9c11cd 100644 --- a/doc/user.xml +++ b/doc/user.xml @@ -99,6 +99,47 @@ cd mpd-version</programlisting> <programlisting>make install</programlisting> </section> + + <section> + <title><filename>systemd</filename> socket activation</title> + + <para> + Using <filename>systemd</filename>, you can launch + <filename>mpd</filename> on demand when the first client + attempts to connect. Create two files in + <filename>/etc/systemd/system/</filename>; first + <filename>mpd.socket</filename>: + </para> + + <programlisting>[Socket] +ListenStream=/run/mpd.socket +ListenStream=6600 +[Install] +WantedBy=sockets.target</programlisting> + + <para> + Now create <filename>mpd.service</filename>: + </para> + + <programlisting>[Unit] +Description=Music Player Daemon +After=sound.target +[Service] +ExecStart=/usr/bin/mpd --stdout --no-daemon</programlisting> + + <para> + Start the socket: + </para> + + <programlisting>systemctl enable mpd.socket +systemctl start mpd.socket</programlisting> + + <para> + In this configuration, <filename>mpd</filename> will ignore + the <varname>bind_to_address</varname> and + <varname>port</varname> settings. + </para> + </section> </chapter> <chapter> @@ -236,6 +277,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 +373,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 +398,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 +673,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 and DSF 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 +841,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> @@ -764,6 +1119,23 @@ cd mpd-version</programlisting> bit, floating point, ...). </entry> </row> + <row> + <entry> + <varname>dsd_usb</varname> + <parameter>yes|no</parameter> + </entry> + <entry> + If set to <parameter>yes</parameter>, then DSD over + USB according to the <ulink + url="http://www.sonore.us/DoP_openStandard_1v1.pdf">pro + posed standard by dCS and others</ulink> is enabled. This wraps + DSD samples in fake 24 bit PCM, and is understood by + some DSD capable products, but may be harmful to + other hardware. Therefore, the default is + <parameter>no</parameter> and you can enable the + option at your own risk. + </entry> + </row> </tbody> </tgroup> </informaltable> @@ -1366,6 +1738,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> @@ -1467,6 +1848,14 @@ cd mpd-version</programlisting> </section> <section> + <title><varname>embcue</varname></title> + + <para> + Reads CUE sheets from the "CUESHEET" tag of song files. + </para> + </section> + + <section> <title><varname>m3u</varname></title> <para> @@ -1498,6 +1887,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> |