diff options
| -rw-r--r-- | Makefile.am | 5 | ||||
| -rw-r--r-- | doc/user.xml | 5213 |
2 files changed, 1 insertions, 5217 deletions
diff --git a/Makefile.am b/Makefile.am index e0b13df32..20f1e8858 100644 --- a/Makefile.am +++ b/Makefile.am @@ -2513,15 +2513,12 @@ endif man_MANS = doc/mpd.1 doc/mpd.conf.5 doc_DATA = AUTHORS COPYING NEWS README.md doc/mpdconf.example -DOCBOOK_FILES = doc/protocol.xml doc/user.xml +DOCBOOK_FILES = doc/protocol.xml if ENABLE_DOCUMENTATION protocoldir = $(docdir)/protocol protocol_DATA = $(wildcard doc/protocol/*.html) -userdir = $(docdir)/user -user_DATA = $(wildcard doc/user/*.html) - DOCBOOK_HTML = $(patsubst %.xml,%/index.html,$(DOCBOOK_FILES)) DOCBOOK_INCLUDES = $(wildcard $(srcdir)/doc/include/*.xml) diff --git a/doc/user.xml b/doc/user.xml deleted file mode 100644 index c7266ed59..000000000 --- a/doc/user.xml +++ /dev/null @@ -1,5213 +0,0 @@ -<?xml version='1.0' encoding="utf-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> - -<book> - <title>The Music Player Daemon - User's Manual</title> - - <chapter id="intro"> - <title>Introduction</title> - - <para> - <application>Music Player Daemon</application> - (<application>MPD</application>) is a flexible, powerful, - server-side application for playing music. Through plugins and - libraries it can play a variety of sound files while being - controlled by its network protocol. - </para> - - <para> - This document is work in progress. Most of it may be incomplete - yet. Please help! - </para> - </chapter> - - <chapter id="install"> - <title>Installation</title> - - <para> - We recommend that you use the software installation routines of - your distribution to install <application>MPD</application>. - Most operating systems have a <application>MPD</application> - package, which is very easy to install. - </para> - - <section id="install_debian"> - <title>Installing on Debian/Ubuntu</title> - - <para> - Install the package <application>MPD</application> via APT: - </para> - - <programlisting>apt-get install mpd</programlisting> - - <para> - When installed this way, <application>MPD</application> by - default looks for music in - <filename>/var/lib/mpd/music/</filename>; this may not be - correct. Look at your <filename>/etc/mpd.conf</filename> - file... - </para> - </section> - - <section id="install_android"> - <title>Installing on Android</title> - - <para> - An experimental Android build is available on <ulink - url="https://play.google.com/store/apps/details?id=org.musicpd">Google - Play</ulink>. After installing and launching it, MPD will - scan the music in your <filename>Music</filename> directory - and you can control it as usual with a MPD client. - </para> - - <para> - If you need to tweak the configuration, you can create a file - called <filename>mpd.conf</filename> on the data partition - (the directory which is returned by Android's <ulink - url="https://developer.android.com/reference/android/os/Environment.html#getExternalStorageDirectory()">getExternalStorageDirectory()</ulink> - API function). - </para> - </section> - - <section id="install_source"> - <title>Compiling from source</title> - - <para> - Download the source tarball from <ulink - url="http://www.musicpd.org/download.html">the - <application>MPD</application> home page</ulink> and unpack - it: - </para> - - <programlisting>tar xf mpd-version.tar.xz -cd mpd-version</programlisting> - - <para> - In any case, you need: - </para> - - <itemizedlist> - <listitem> - <para> - a C++14 compiler (e.g. <ulink - url="http://gcc.gnu.org/">gcc 6.0</ulink> or <ulink - url="http://clang.llvm.org/">clang 3.9</ulink>) - </para> - </listitem> - - <listitem> - <para> - <ulink url="http://www.boost.org/">Boost 1.58</ulink> - </para> - </listitem> - - <listitem> - <para> - <ulink url="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</ulink> - </para> - </listitem> - </itemizedlist> - - <para> - Each plugin usually needs a codec library, which you also need - to install. Check the plugin reference for details about - required libraries. - </para> - - <para> - For example, the following installs a fairly complete list of - build dependencies on Debian Jessie: - </para> - - <programlisting> -apt-get install g++ \ - libmad0-dev libmpg123-dev libid3tag0-dev \ - libflac-dev libvorbis-dev libopus-dev \ - libadplug-dev libaudiofile-dev libsndfile1-dev libfaad-dev \ - libfluidsynth-dev libgme-dev libmikmod2-dev libmodplug-dev \ - libmpcdec-dev libwavpack-dev libwildmidi-dev \ - libsidplay2-dev libsidutils-dev libresid-builder-dev \ - libavcodec-dev libavformat-dev \ - libmp3lame-dev libtwolame-dev libshine-dev \ - libsamplerate0-dev libsoxr-dev \ - libbz2-dev libcdio-paranoia-dev libiso9660-dev libmms-dev \ - libzzip-dev \ - libcurl4-gnutls-dev libyajl-dev libexpat-dev \ - libasound2-dev libao-dev libjack-jackd2-dev libopenal-dev \ - libpulse-dev libroar-dev libshout3-dev \ - libsndio-dev \ - libmpdclient-dev \ - libnfs-dev libsmbclient-dev \ - libupnp-dev \ - libavahi-client-dev \ - libsqlite3-dev \ - libsystemd-dev libwrap0-dev \ - libcppunit-dev xmlto \ - libboost-dev \ - libicu-dev - </programlisting> - - <para> - Now configure the source tree: - </para> - - <programlisting>./configure</programlisting> - - <para> - The <parameter>--help</parameter> argument shows a list of - compile-time options. When everything is ready and - configured, compile: - </para> - - <programlisting>make</programlisting> - - <para> - And install: - </para> - - <programlisting>make install</programlisting> - - <section id="windows_build"> - <title>Compiling for Windows</title> - - <para> - Even though it does not "feel" like a Windows application, - <application>MPD</application> works well under Windows. - Its build process follows the "Linux style", and may seem - awkward for Windows people (who are not used to compiling - their software, anyway). - </para> - - <para> - Basically, there are three ways to compile - <application>MPD</application> for Windows: - </para> - - <orderedlist> - <listitem> - <para> - Build on Windows for Windows. All you need to do is - described above already: configure and make. - </para> - - <para> - For Windows users, this is kind of unusual, because few - Windows users have a GNU toolchain and a UNIX shell - installed. - </para> - </listitem> - - <listitem> - <para> - Build on Linux for Windows. This is described above - already: configure and make. You need the <ulink - url="https://mingw-w64.org/"><application>mingw-w64</application> - cross compiler</ulink>. Pass - <parameter>--host=i686-w64-mingw32</parameter> (32 bit) - or <parameter>--host=x86_64-w64-mingw32</parameter> (64 - bit) to configure. - </para> - - <para> - This is somewhat natural for Linux users. Many - distributions have <application>mingw-w64</application> - packages. The remaining difficulty here is installing - all the external libraries. And - <application>MPD</application> usually needs many, - making this method cumbersome for the casual user. - </para> - </listitem> - - <listitem> - <para> - Build on Linux for Windows using the - <application>MPD</application>'s library build script. - </para> - </listitem> - </orderedlist> - - <para> - This section is about the latter. - </para> - - <para> - Just like with the native build, unpack the - <application>MPD</application> source tarball and change - into the directory. Then, instead of - <command>./configure</command>, type: - </para> - - <programlisting>./win32/build.py --64</programlisting> - - <para> - This downloads various library sources, and then configures - and builds <application>MPD</application> (for x64; to build - a 32 bit binary, pass <parameter>--32</parameter>). The - resulting EXE files is linked statically, i.e. it contains - all the libraries already, and you do not need carry DLLs - around. It is large, but easy to use. If you wish to have - a small <filename>mpd.exe</filename> with DLLs, you need to - compile manually, without the <filename>build.py</filename> - script. - </para> - </section> - - <section id="android_build"> - <title>Compiling for Android</title> - - <para> - MPD can be compiled as an Android app. It can be installed - easily with <link linkend="install_android">Google - Play</link>, but if you want to build it from source, follow - this section. - </para> - - <para> - You need: - </para> - - <itemizedlist> - <listitem> - <para> - Android SDK - </para> - </listitem> - - <listitem> - <para> - <ulink - url="https://developer.android.com/ndk/downloads/index.html">Android - NDK</ulink> - </para> - </listitem> - </itemizedlist> - - <para> - Just like with the native build, unpack the - <application>MPD</application> source tarball and change - into the directory. Then, instead of - <command>./configure</command>, type: - </para> - - <programlisting>./android/build.py SDK_PATH NDK_PATH ABI -make android/build/mpd-debug.apk</programlisting> - - <para> - <varname>SDK_PATH</varname> is the absolute path where you - installed the Android SDK; <varname>NDK_PATH</varname> is - the Android NDK installation path; <varname>ABI</varname> is - the Android ABI to be built, e.g. "armeabi-v7a". - </para> - - <para> - This downloads various library sources, and then configures - and builds <application>MPD</application>. - </para> - </section> - </section> - - <section id="systemd_socket"> - <title><filename>systemd</filename> socket activation</title> - - <para> - Using <filename>systemd</filename>, you can launch - <application>MPD</application> on demand when the first client - attempts to connect. - </para> - - <para> - <application>MPD</application> comes with two - <application>systemd</application> unit files: a "service" - unit and a "socket" unit. These will only be installed when - <application>MPD</application> was configured with - <parameter>--with-systemdsystemunitdir=/lib/systemd/system</parameter>. - </para> - - <para> - To enable socket activation, type: - </para> - - <programlisting>systemctl enable mpd.socket -systemctl start mpd.socket</programlisting> - - <para> - In this configuration, <application>MPD</application> will - ignore the <varname>bind_to_address</varname> and - <varname>port</varname> settings. - </para> - </section> - - <section id="systemd_user"> - <title><filename>systemd</filename> user unit</title> - - <para> - You can launch <application>MPD</application> as a - <filename>systemd</filename> user unit. The service file will - only be installed when <application>MPD</application> was - configured with - <parameter>--with-systemduserunitdir=/usr/lib/systemd/user</parameter> - or - <parameter>--with-systemduserunitdir=$HOME/.local/share/systemd/user</parameter>. - </para> - - <para> - Once the user unit is installed, you can start and stop - <application>MPD</application> like any other service: - </para> - - <programlisting>systemctl --user start mpd</programlisting> - - <para> - To auto-start <application>MPD</application> upon login, type: - </para> - - <programlisting>systemctl --user enable mpd</programlisting> - </section> - </chapter> - - <chapter id="config"> - <title>Configuration</title> - - <section id="config_file"> - <title>The Configuration File</title> - - <para> - <application>MPD</application> reads its configuration from a - text file. Usually, that is - <filename>/etc/mpd.conf</filename>, unless a different path is - specified on the command line. If you run - <application>MPD</application> as a user daemon (and not as a - system daemon), the configuration is read from - <filename>$XDG_CONFIG_HOME/mpd/mpd.conf</filename> (usually - <filename>~/.config/mpd/mpd.conf</filename>). On Android, - <filename>mpd.conf</filename> will be loaded from the - top-level directory of the data partition. - </para> - - <para> - Each line in the configuration file contains a setting name - and its value, e.g.: - </para> - - <programlisting>connection_timeout "5"</programlisting> - - <para> - For settings which specify a filesystem path, the tilde is - expanded: - </para> - - <programlisting>music_directory "~/Music"</programlisting> - - <para> - Some of the settings are grouped in blocks with curly braces, - e.g. per-plugin settings: - </para> - - <programlisting>audio_output { - type "alsa" - name "My ALSA output" - device "iec958:CARD=Intel,DEV=0" - mixer_control "PCM" -}</programlisting> - - <para> - The <varname>include</varname> directive can be used to - include settings from another file; the given file name is - relative to the current file: - </para> - - <programlisting>include "other.conf"</programlisting> - - <para> - You can use <varname>include_optional</varname> instead if you - want the included file to be optional; the directive will be - ignored if the file does not exist: - </para> - - <programlisting>include_optional "may_not_exist.conf"</programlisting> - - <para> - Both directives can have a shell pattern (with wildcards - '<filename>*</filename>' and '<filename>?</filename>') in the - last path segment, e.g.: - </para> - - <programlisting>include "conf.d/*.conf"</programlisting> - </section> - - <section id="config_music_directory"> - <title>Configuring the music directory</title> - - <para> - When you play local files, you should organize them within a - directory called the "music directory". This is configured in - <application>MPD</application> with the - <varname>music_directory</varname> setting. - </para> - - <para> - By default, <application>MPD</application> follows symbolic - links in the music directory. This behavior can be switched - off: <varname>follow_outside_symlinks</varname> controls - whether <application>MPD</application> follows links pointing - to files outside of the music directory, and - <varname>follow_inside_symlinks</varname> lets you disable - symlinks to files inside the music directory. - </para> - - <para> - Instead of using local files, you can use <link - linkend="storage_plugins">storage plugins</link> to access - files on a remote file server. For example, to use music from - the SMB/CIFS server "myfileserver" on the share called - "Music", configure the music directory - "<parameter>smb://myfileserver/Music</parameter>". For a - recipe, read the <link linkend="satellite">Satellite - MPD</link> section. - </para> - - <para> - You can also <link linkend="mount">use multiple storage - plugins to assemble a virtual music directory consisting of - multiple storages</link>. - </para> - </section> - - <section id="config_database_plugins"> - <title>Configuring database plugins</title> - - <para> - If a music directory is configured, one database plugin is - used. To configure this plugin, add a - <varname>database</varname> block to - <filename>mpd.conf</filename>: - </para> - - <programlisting>database { - plugin "simple" - path "/var/lib/mpd/db" -} - </programlisting> - - <para> - The following table lists the <varname>database</varname> - options valid for all plugins: - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry> - Name - </entry> - <entry> - Description - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>plugin</varname> - </entry> - <entry> - The name of the plugin. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para> - More information can be found in the <link - linkend="database_plugins">database plugin reference</link>. - </para> - </section> - - <section id="config_neighbor_plugins"> - <title>Configuring neighbor plugins</title> - - <para> - All neighbor plugins are disabled by default to avoid unwanted - overhead. To enable (and configure) a plugin, add a - <varname>neighbor</varname> block to - <filename>mpd.conf</filename>: - </para> - - <programlisting>neighbors { - plugin "smbclient" -} - </programlisting> - - <para> - The following table lists the <varname>neighbor</varname> - options valid for all plugins: - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry> - Name - </entry> - <entry> - Description - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>plugin</varname> - </entry> - <entry> - The name of the plugin. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para> - More information can be found in the <link - linkend="neighbor_plugins">neighbor plugin reference</link>. - </para> - </section> - - <section id="config_input_plugins"> - <title>Configuring input plugins</title> - - <para> - To configure an input plugin, add a <varname>input</varname> - block to <filename>mpd.conf</filename>: - </para> - - <programlisting>input { - plugin "curl" - proxy "proxy.local" -} - </programlisting> - - <para> - The following table lists the <varname>input</varname> options - valid for all plugins: - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry> - Name - </entry> - <entry> - Description - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>plugin</varname> - </entry> - <entry> - The name of the plugin. - </entry> - </row> - <row> - <entry> - <varname>enabled</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - Allows you to disable a input plugin without - recompiling. By default, all plugins are enabled. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para> - More information can be found in the <link - linkend="input_plugins">input plugin reference</link>. - </para> - </section> - - <section id="config_decoder_plugins"> - <title>Configuring decoder plugins</title> - - <para> - Most decoder plugins do not need any special configuration. - To configure a decoder, add a <varname>decoder</varname> block - to <filename>mpd.conf</filename>: - </para> - - <programlisting>decoder { - plugin "wildmidi" - config_file "/etc/timidity/timidity.cfg" -} - </programlisting> - - <para> - The following table lists the <varname>decoder</varname> - options valid for all plugins: - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry> - Name - </entry> - <entry> - Description - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>plugin</varname> - </entry> - <entry> - The name of the plugin. - </entry> - </row> - <row> - <entry> - <varname>enabled</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - Allows you to disable a decoder plugin without - recompiling. By default, all plugins are enabled. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para> - More information can be found in the <link - linkend="decoder_plugins">decoder plugin reference</link>. - </para> - </section> - - <section id="config_encoder_plugins"> - <title>Configuring encoder plugins</title> - - <para> - Encoders are used by some of the output plugins (such as <link - linkend="shout_output"><varname>shout</varname></link>). The - encoder settings are included in the - <varname>audio_output</varname> section. More information can - be found in the <link linkend="encoder_plugins">encoder plugin - reference</link>. - </para> - </section> - - <section id="config_audio_outputs"> - <title>Configuring audio outputs</title> - - <para> - Audio outputs are devices which actually play the audio chunks - produced by <application>MPD</application>. You can configure - any number of audio output devices, but there must be at least - one. If none is configured, <application>MPD</application> - attempts to auto-detect. Usually, this works quite well with - ALSA, OSS and on Mac OS X. - </para> - - <para> - To configure an audio output manually, add one or more - <varname>audio_output</varname> blocks to - <filename>mpd.conf</filename>: - </para> - - <programlisting>audio_output { - type "alsa" - name "my ALSA device" - device "hw:0" -} - </programlisting> - - <para> - The following table lists the <varname>audio_output</varname> - options valid for all plugins: - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry> - Name - </entry> - <entry> - Description - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>type</varname> - </entry> - <entry> - The name of the plugin. - </entry> - </row> - <row> - <entry> - <varname>name</varname> - </entry> - <entry> - The name of the audio output. It is visible to the - client. Some plugins also use it internally, e.g. as - a name registered in the PULSE server. - </entry> - </row> - <row id="ao_format"> - <entry> - <varname>format</varname> - </entry> - <entry> - <para> - Always open the audio output with the specified - audio format - (<replaceable>samplerate:bits:channels</replaceable>), - regardless of the format of the input file. This is - optional for most plugins. - </para> - <para> - Any of the three attributes may be an asterisk to - specify that this attribute should not be enforced, - example: <parameter>48000:16:*</parameter>. - <parameter>*:*:*</parameter> is equal to not having - a <varname>format</varname> specification. - </para> - <para> - The following values are valid for - <varname>bits</varname>: <varname>8</varname> - (signed 8 bit integer samples), - <varname>16</varname>, <varname>24</varname> (signed - 24 bit integer samples padded to 32 bit), - <varname>32</varname> (signed 32 bit integer - samples), <varname>f</varname> (32 bit floating - point, -1.0 to 1.0), "<varname>dsd</varname>" means - DSD (Direct Stream Digital). For DSD, there are - special cases such as "<varname>dsd64</varname>", - which allows you to omit the sample rate - (e.g. <parameter>dsd512:2</parameter> for stereo - DSD512, i.e. 22.5792 MHz). - </para> - <para> - The sample rate is special for DSD: - <application>MPD</application> counts the number of - bytes, not bits. Thus, a DSD "bit" rate of 22.5792 - MHz (DSD512) is 2822400 from - <application>MPD</application>'s point of view - (44100*512/8). - </para> - </entry> - </row> - <row> - <entry> - <varname>enabled</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - Specifies whether this audio output is enabled when - <application>MPD</application> is started. By - default, all audio outputs are enabled. This is just - the default setting when there is no state file; with - a state file, the previous state is restored. - </entry> - </row> - <row> - <entry> - <varname>tags</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - If set to <parameter>no</parameter>, then - <application>MPD</application> will not send tags to - this output. This is only useful for output plugins - that can receive tags, for example the <link - linkend="httpd_output"><varname>httpd</varname></link> - output plugin. - </entry> - </row> - <row> - <entry> - <varname>always_on</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - If set to <parameter>yes</parameter>, then - <application>MPD</application> 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 accidentally - stopped. - </entry> - </row> - <row> - <entry> - <varname>mixer_type</varname> - <parameter>hardware|software|null|none</parameter> - </entry> - <entry> - Specifies which mixer should be used for this audio - output: the hardware mixer (available for <link - linkend="alsa_output">ALSA</link>, <link - linkend="oss_output">OSS</link> and <link - linkend="pulse_output">PulseAudio</link>), the - software mixer, the "null" mixer - (<parameter>null</parameter>; allows setting the - volume, but with no effect; this can be used as a - trick to implement an <link - linkend="external_mixer">external mixer</link>) or no - mixer (<parameter>none</parameter>). By default, the - hardware mixer is used for devices which support it, - and none for the others. - </entry> - </row> - <row> - <entry> - <varname>replay_gain_handler</varname> - <parameter>software|mixer|none</parameter> - </entry> - <entry> - Specifies how replay gain is applied. The default is - <parameter>software</parameter>, which uses an - internal software volume control. - <parameter>mixer</parameter> uses the configured - (hardware) mixer control. <parameter>none</parameter> - disables replay gain on this audio output. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="config_filters"> - <title>Configuring filters</title> - - <para> - Filters are plugins which modify an audio stream. - </para> - - <para> - To configure a filter, add a <varname>filter</varname> block - to <filename>mpd.conf</filename>: - </para> - - <programlisting>filter { - plugin "volume" - name "software volume" -} - </programlisting> - - <para> - The following table lists the <varname>filter</varname> - options valid for all plugins: - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry> - Name - </entry> - <entry> - Description - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>plugin</varname> - </entry> - <entry> - The name of the plugin. - </entry> - </row> - <row> - <entry> - <varname>name</varname> - </entry> - <entry> - The name of the filter. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="config_playlist_plugins"> - <title>Configuring playlist plugins</title> - - <para> - Playlist plugins are used to load remote playlists (protocol - commands <command>load</command>, - <command>listplaylist</command> and - <command>listplaylistinfo</command>). This is not related to - <application>MPD</application>'s playlist directory. - </para> - - <para> - To configure a playlist plugin, add a - <varname>playlist_plugin</varname> block to - <filename>mpd.conf</filename>: - </para> - - <programlisting>playlist_plugin { - name "m3u" - enabled "true" -} - </programlisting> - - <para> - The following table lists the - <varname>playlist_plugin</varname> options valid for all - plugins: - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry> - Name - </entry> - <entry> - Description - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>name</varname> - </entry> - <entry> - The name of the plugin. - </entry> - </row> - <row> - <entry> - <varname>enabled</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - Allows you to disable a input plugin without - recompiling. By default, all plugins are enabled. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para> - More information can be found in the <link - linkend="playlist_plugins">playlist plugin reference</link>. - </para> - </section> - - <section id="config_audio_format"> - <title>Audio Format Settings</title> - - <section id="config_global_audio_format"> - <title>Global Audio Format</title> - - <para> - The setting <varname>audio_output_format</varname> forces - <application>MPD</application> to use one audio format for - all outputs. Doing that is usually not a good idea. The - values are the same as in <link - linkend="ao_format"><varname>format</varname> in the <link - linkend="config_audio_outputs"><varname>audio_output</varname></link> - section</link>. - </para> - </section> - - <section> - <title>Resampler</title> - - <para> - Sometimes, music needs to be resampled before it can be - played; for example, CDs use a sample rate of 44,100 Hz - while many cheap audio chips can only handle 48,000 Hz. - Resampling reduces the quality and consumes a lot of CPU. - There are different options, some of them optimized for high - quality and others for low CPU usage, but you can't have - both at the same time. Often, the resampler is the - component that is responsible for most of - <application>MPD</application>'s CPU usage. Since - <application>MPD</application> comes with high quality - defaults, it may appear that <application>MPD</application> - consumes more CPU than other software. - </para> - - <para> - Check the <link linkend="resampler_plugins">resampler plugin - reference</link> for a list of resamplers and how to - configure them. - </para> - </section> - </section> - - <section id="config_clients"> - <title>Client Connections</title> - - <section id="config_listeners"> - <title>Listeners</title> - - <para> - The setting <varname>bind_to_address</varname> specifies - which addresses <application>MPD</application> listens on - for connections from clients. The default is - "<parameter>any</parameter>", which binds to all available - addresses. - </para> - - <para> - You can set a port that is different from the global port - setting, e.g. "<parameter>localhost:6602</parameter>". IPv6 - addresses must be enclosed in square brackets if you want to - configure a port, e.g. "<parameter>[::1]:6602</parameter>". - </para> - - <para> - To bind to a local socket (UNIX domain socket), specify an - absolute path or a path starting with a tilde - (<parameter>~</parameter>). Some clients default to - connecting to <filename>/var/run/mpd/socket</filename> so - this may be a good choice. - </para> - - <para> - If no port is specified, the default port is - <parameter>6600</parameter>. This default can be changed - with the <varname>port</varname> setting. - </para> - </section> - - <section id="config_permissions"> - <title>Permissions and Passwords</title> - - <para> - By default, all clients are unauthenticated and have a full - set of permissions. This can be restricted with the - settings <varname>default_permissions</varname> and - <varname>password</varname>. - </para> - - <para> - <varname>default_permissions</varname> controls the - permissions of a new client. Its value is a comma-separated - list of permissions: - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry> - Name - </entry> - <entry> - Description - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <parameter>read</parameter> - </entry> - <entry> - Allows reading of the database, displaying the current - playlist, and current status of MPD. - </entry> - </row> - - <row> - <entry> - <parameter>read</parameter> - </entry> - <entry> - Allows reading of the database, displaying the current - playlist, and current status of MPD. - </entry> - </row> - - <row> - <entry> - <parameter>add</parameter> - </entry> - <entry> - Allows adding songs and loading playlists. - </entry> - </row> - - <row> - <entry> - <parameter>control</parameter> - </entry> - <entry> - Allows all other player and playlist manipulations. - </entry> - </row> - - <row> - <entry> - <parameter>admin</parameter> - </entry> - <entry> - Allows database updates and allows shutting down MPD. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para> - <varname>local_permissions</varname> may be used to assign - other permissions to clients connecting on a local socket. - </para> - - <para> - <varname>password</varname> allows the client to send a - password to gain other permissions. This option may be - specified multiple times with different passwords. - </para> - - <para> - Note that the <varname>password</varname> option is not - secure: passwords are sent in clear-text over the - connection, and the client cannot verify the server's - identity. - </para> - - <para> - Example: - </para> - - <programlisting>default_permissions "read" -password "the_password@read,add,control" -password "the_admin_password@read,add,control,admin"</programlisting> - </section> - </section> - - <section id="config_other"> - <title>Other Settings</title> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>metadata_to_use</varname> - <parameter>TAG1,TAG2,...</parameter> - </entry> - <entry> - Use only the specified tags, and ignore the others. - This setting can reduce the database size and - <application>MPD</application>'s memory usage by - omitting unused tags. By default, all tags but - <varname>comment</varname> are enabled. The special - value "none" disables all tags. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <section> - <title>The State File</title> - - <para> - The <emphasis>state file</emphasis> is a file where - <application>MPD</application> saves and restores its state - (play queue, playback position etc.) to keep it persistent - across restarts and reboots. It is an optional setting. - </para> - - <para> - <application>MPD</application> will attempt to load the - state file during startup, and will save it when shutting - down the daemon. Additionally, the state file is refreshed - every two minutes (after each state change). - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>state_file</varname> - <parameter>PATH</parameter> - </entry> - <entry> - Specify the state file location. The parent - directory must be writable by the - <application>MPD</application> user - (<parameter>+wx</parameter>). - </entry> - </row> - - <row> - <entry> - <varname>state_file_interval</varname> - <parameter>SECONDS</parameter> - </entry> - <entry> - Auto-save the state file this number of seconds - after each state change. Defaults to - <parameter>120</parameter> (2 minutes). - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="stickers"> - <title>The Sticker Database</title> - - <para> - "Stickers" are pieces of information attached to songs. - Some clients use them to store ratings and other volatile - data. This feature requires <ulink - url="http://www.sqlite.org/">SQLite</ulink>, compile-time - configure option <parameter>--enable-sqlite</parameter>. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>sticker_file</varname> - <parameter>PATH</parameter> - </entry> - <entry> - The location of the sticker database. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title>Resource Limitations</title> - - <para> - These settings are various limitations to prevent - <application>MPD</application> from using too many - resources (denial of service). - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - - <row> - <entry> - <varname>connection_timeout</varname> - <parameter>SECONDS</parameter> - </entry> - <entry> - If a client does not send any new data in this time - period, the connection is closed. Clients waiting - in "idle" mode are excluded from this. Default is - <parameter>60</parameter>. - </entry> - </row> - - <row> - <entry> - <varname>max_connections</varname> - <parameter>NUMBER</parameter> - </entry> - <entry> - This specifies the maximum number of clients that - can be connected to <application>MPD</application> - at the same time. Default is - <parameter>5</parameter>. - </entry> - </row> - - <row> - <entry> - <varname>max_playlist_length</varname> - <parameter>NUMBER</parameter> - </entry> - <entry> - The maximum number of songs that can be in the - playlist. Default is <parameter>16384</parameter>. - </entry> - </row> - - <row> - <entry> - <varname>max_command_list_size</varname> - <parameter>KBYTES</parameter> - </entry> - <entry> - The maximum size a command list. Default is - <parameter>2048</parameter> (2 MiB). - </entry> - </row> - - <row> - <entry> - <varname>max_output_buffer_size</varname> - <parameter>KBYTES</parameter> - </entry> - <entry> - The maximum size of the output buffer to a client - (maximum response size). Default is - <parameter>8192</parameter> (8 MiB). - </entry> - </row> - - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title>Buffer Settings</title> - - <para> - Do not change these unless you know what you are doing. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - - <row> - <entry> - <varname>audio_buffer_size</varname> - <parameter>KBYTES</parameter> - </entry> - <entry> - Adjust the size of the internal audio buffer. - Default is <parameter>4096</parameter> (4 MiB). - </entry> - </row> - - <row> - <entry> - <varname>buffer_before_play</varname> - <parameter>PERCENT</parameter> - </entry> - <entry> - Control the percentage of the buffer which is filled - before beginning to play. Increasing this reduces - the chance of audio file skipping, at the cost of - increased time prior to audio playback. Default is - <parameter>10%</parameter>. - </entry> - </row> - - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="zeroconf"> - <title>Zeroconf</title> - - <para> - If Zeroconf support (<ulink - url="http://avahi.org/">Avahi</ulink> or Apple's Bonjour) - was enabled at compile time with - <parameter>--with-zeroconf=...</parameter>, MPD can announce - its presence on the network. The following settings control - this feature: - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - - <row> - <entry> - <varname>zeroconf_enabled</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - Enables or disables this feature. Default is - <parameter>yes</parameter>. - </entry> - </row> - - <row> - <entry> - <varname>zeroconf_name</varname> - <parameter>NAME</parameter> - </entry> - <entry> - The service name to publish via Zeroconf. The - default is "<parameter>Music Player</parameter>". - </entry> - </row> - - </tbody> - </tgroup> - </informaltable> - </section> - </section> - </chapter> - - <chapter id="advanced_config"> - <title>Advanced configuration</title> - - <section id="satellite"> - <title>Satellite setup</title> - - <para> - <application>MPD</application> runs well on weak machines such - as the <ulink url="http://www.raspberrypi.org/">Raspberry - Pi</ulink>. However, such hardware tends to not have storage - big enough to hold a music collection. Mounting music from a - file server can be very slow, especially when updating the - database. - </para> - - <para> - One approach for optimization is running - <application>MPD</application> on the file server, which not - only exports raw files, but also provides access to a readily - scanned database. Example configuration: - </para> - - <programlisting>music_directory "nfs://fileserver.local/srv/mp3" -#music_directory "smb://fileserver.local/mp3" - -database { - plugin "proxy" - host "fileserver.local" -} - </programlisting> - - <para> - The <link - linkend="config_music_directory"><varname>music_directory</varname></link> - setting tells <application>MPD</application> to read files - from the given NFS server. It does this by connecting to the - server from userspace. This does not actually mount the file - server into the kernel's virtual file system, and thus - requires no kernel cooperation and no special privileges. It - does not even require a kernel with NFS support, only the - <link linkend="nfs_storage"><filename>nfs</filename></link> - storage plugin (using the <filename>libnfs</filename> - userspace library). The same can be done with SMB/CIFS using - the <link - linkend="smbclient_storage"><filename>smbclient</filename></link> - storage plugin (using <filename>libsmbclient</filename>). - </para> - - <para> - The <link - linkend="config_database_plugins"><varname>database</varname></link> - setting tells <application>MPD</application> to pass all - database queries on to the <application>MPD</application> - instance running on the file server (using the <link - linkend="proxy_database"><filename>proxy</filename></link> - plugin). - </para> - </section> - - <section id="realtime"> - <title>Real-Time Scheduling</title> - - <para> - On Linux, <application>MPD</application> attempts to configure - <ulink - url="https://en.wikipedia.org/wiki/Real-time_computing">real-time - scheduling</ulink> for some threads that benefit from it. - </para> - - <para> - This is only possible you allow <application>MPD</application> - to do it. This privilege is controlled by - <varname>RLIMIT_RTPRIO</varname> - <varname>RLIMIT_RTTIME</varname>. You can configure this - privilege with <command>ulimit</command> before launching - <application>MPD</application>: - </para> - - <programlisting>ulimit -HS -r 50; mpd</programlisting> - - <para> - Or you can use the <command>prlimit</command> program from the - <application>util-linux</application> package: - </para> - - <programlisting>prlimit --rtprio=50 --rttime=unlimited mpd</programlisting> - - <para> - The <application>systemd</application> service file shipped - with <application>MPD</application> comes with this setting. - </para> - - <para> - This works only if the Linux kernel was compiled with - <varname>CONFIG_RT_GROUP_SCHED</varname> disabled. Use the - following command to check this option for your current - kernel: - </para> - - <programlisting>zgrep ^CONFIG_RT_GROUP_SCHED /proc/config.gz</programlisting> - - <para> - You can verify whether the real-time scheduler is active with - the <command>ps</command> command: - </para> - - <programlisting># ps H -q `pidof -s mpd` -o 'pid,tid,cls,rtprio,comm' - PID TID CLS RTPRIO COMMAND -16257 16257 TS - mpd -16257 16258 TS - io -16257 16259 FF 50 rtio -16257 16260 TS - player -16257 16261 TS - decoder -16257 16262 FF 50 output:ALSA -16257 16263 IDL 0 update</programlisting> - - <para> - The <varname>CLS</varname> column shows the CPU scheduler; - <parameter>TS</parameter> is the normal scheduler; - <parameter>FF</parameter> and <parameter>RR</parameter> are - real-time schedulers. In this example, two threads use the - real-time scheduler: the <command>output</command> thread and - the <command>rtio</command> (real-time I/O) thread; these two - are the important ones. The database update thread uses the - idle scheduler ("<parameter>IDL</parameter> in - <command>ps</command>), which only gets CPU when no other - process needs it. - </para> - - <note> - <para> - There is a rumor that real-time scheduling improves audio - quality. That is not true. All it does is reduce the - probability of skipping (audio buffer xruns) when the - computer is under heavy load. - </para> - </note> - </section> - </chapter> - - <chapter id="use"> - <title>Using <application>MPD</application></title> - - <section id="client"> - <title>The client</title> - - <para> - After you have installed, configured and started - <application>MPD</application>, you choose a client to control - the playback. - </para> - - <para> - The most basic client is <filename>mpc</filename>, which - provides a command line interface. It is useful in shell - scripts. Many people bind specific <filename>mpc</filename> - commands to hotkeys. - </para> - - <para> - The <ulink - url="http://www.musicpd.org/clients/"><application>MPD</application> - Wiki</ulink> contains an extensive list of clients to choose - from. - </para> - </section> - - <section id="music_directory_and_database"> - <title>The music directory and the database</title> - - <para> - The "music directory" is where you store your music files. - <application>MPD</application> stores all relevant meta - information about all songs in its "database". Whenever you - add, modify or remove songs in the music directory, you have - to update the database, for example with - <filename>mpc</filename>: - </para> - - <programlisting>mpc update</programlisting> - - <para> - Depending on the size of your music collection and the speed - of the storage, this can take a while. - </para> - - <para> - To exclude a file from the update, create a file called - <filename>.mpdignore</filename> in its parent directory. Each - line of that file may contain a list of shell wildcards. - Matching files in the current directory and all subdirectories - are excluded. - </para> - - <section id="mount"> - <title>Mounting other storages into the music directory</title> - - <para> - <application>MPD</application> has various <link - linkend="storage_plugins">storage plugins</link> of which - multiple instances can be "mounted" into the music - directory. This way, you can use local music, file servers - and USB sticks at the same time. Example: - </para> - - <programlisting>mpc mount foo nfs://192.168.1.4/export/mp3 -mpc mount usbstick udisks://by-uuid-2F2B-D136 -mpc unmount usbstick</programlisting> - - <para> - MPD's <link - linkend="neighbor_plugins">neighbor plugins</link> can be - helpful with finding mountable storages: - </para> - - <programlisting>mpc listneighbors</programlisting> - - <para> - Mounting is only possible with the <link - linkend="simple_database"><varname>simple</varname> database - plugin</link> and a <varname>cache_directory</varname>, - e.g.: - </para> - - <programlisting> -database { - plugin "simple" - path "~/.mpd/db" - cache_directory "~/.mpd/cache" -} - </programlisting> - - <para> - This requires migrating from the old - <varname>db_file</varname> setting to a - <varname>database</varname> section. The cache directory - must exist, and MPD will put one file per mount there, which - will be reused when the same storage is used again later. - </para> - </section> - </section> - - <section id="tags"> - <title>Metadata</title> - - <para> - When scanning or playing a song, - <application>MPD</application> parses its metadata. The - following tags are supported: - </para> - - <xi:include href="include/tags.xml" - xmlns:xi="http://www.w3.org/2001/XInclude"/> - </section> - - <section id="queue"> - <title>The queue</title> - - <para> - The queue (sometimes called "current playlist") is a list of - songs to be played by <application>MPD</application>. To play - a song, add it to the queue and start playback. Most clients - offer an interface to edit the queue. - </para> - </section> - - <section id="stored_playlists"> - <title>Stored Playlists</title> - - <para> - Stored playlists are some kind of secondary playlists which - can be created, saved, edited and deleted by the client. They - are addressed by their names. Its contents can be loaded into - the queue, to be played back. The - <varname>playlist_directory</varname> setting specifies where - those playlists are stored. - </para> - </section> - </chapter> - - <chapter id="advanced_usage"> - <title>Advanced usage</title> - - <section id="bit_perfect"> - <title>Bit-perfect playback</title> - - <para> - "Bit-perfect playback" is a phrase used by audiophiles to - describe a setup that plays back digital music as-is, without - applying any modifications such as resampling, format - conversion or software volume. Naturally, this implies a - lossless codec. - </para> - - <para> - By default, <application>MPD</application> attempts to do - bit-perfect playback, unless you tell it not to. Precondition - is a sound chip that supports the audio format of your music - files. If the audio format is not supported, - <application>MPD</application> attempts to fall back to the - nearest supported audio format, trying to lose as little - quality as possible. - </para> - - <para> - To verify if <application>MPD</application> converts the audio - format, enable verbose logging, and watch for these lines: - </para> - - <programlisting>decoder: audio_format=44100:24:2, seekable=true -output: opened plugin=alsa name="An ALSA output" audio_format=44100:16:2 -output: converting from 44100:24:2</programlisting> - - <para> - This example shows that a 24 bit file is being played, but the - sond chip cannot play 24 bit. It falls back to 16 bit, - discarding 8 bit. - </para> - - <para> - However, this does not yet prove bit-perfect playback; - <application>ALSA</application> may be fooling - <application>MPD</application> that the audio format is - supported. To verify the format really being sent to the - physical sound chip, try: - </para> - - <programlisting>cat /proc/asound/card*/pcm*p/sub*/hw_params -access: RW_INTERLEAVED -format: S16_LE -subformat: STD -channels: 2 -rate: 44100 (44100/1) -period_size: 4096 -buffer_size: 16384</programlisting> - - <para> - Obey the "format" row, which indicates that the current - playback format is 16 bit (signed 16 bit integer, little - endian). - </para> - - <para> - Check list for bit-perfect playback: - </para> - - <itemizedlist> - <listitem> - <para> - Use the <link linkend="alsa_output">ALSA</link> output - plugin. - </para> - </listitem> - - <listitem> - <para> - Disable sound processing inside - <application>ALSA</application> by configuring a - "hardware" device (<parameter>hw:0,0</parameter> or - similar). - </para> - </listitem> - - <listitem> - <para> - Don't use software volume (setting <link - linkend="config_audio_outputs"><varname>mixer_type</varname></link>). - </para> - </listitem> - - <listitem> - <para> - Don't force <application>MPD</application> to use a - specific audio format (settings <link - linkend="config_audio_outputs"><varname>format</varname></link>, - <link - linkend="config_global_audio_format"><varname>audio_output_format</varname></link>). - </para> - </listitem> - - <listitem> - <para> - Verify that you are really doing bit-perfect playback - using <application>MPD</application>'s verbose log and - <filename>/proc/asound/card*/pcm*p/sub*/hw_params</filename>. - Some DACs can also indicate the audio format. - </para> - </listitem> - </itemizedlist> - </section> - - <section id="dsd"> - <title>Direct Stream Digital (DSD)</title> - - <para> - DSD (<ulink - url="https://en.wikipedia.org/wiki/Direct_Stream_Digital">Direct - Stream Digital</ulink>) is a digital format that stores audio - as a sequence of single-bit values at a very high sampling - rate. - </para> - - <para> - <application>MPD</application> understands the file formats - <link linkend="dsdiff_decoder"><filename>dff</filename></link> - and <link - linkend="dsf_decoder"><filename>dsf</filename></link>. There - are three ways to play back DSD: - </para> - - <itemizedlist> - <listitem> - <para> - Native DSD playback. Requires - <application>ALSA</application> 1.0.27.1 or later, a sound - driver/chip that supports DSD and of course a DAC that - supports DSD. - </para> - </listitem> - - <listitem> - <para> - DoP (DSD over PCM) playback. This wraps DSD inside fake - 24 bit PCM according to the <ulink - url="http://dsd-guide.com/dop-open-standard">DoP - standard</ulink>. Requires a DAC that supports DSD. No - support from ALSA and the sound chip required (except for - <link linkend="bit_perfect">bit-perfect</link> 24 bit PCM - support). - </para> - </listitem> - - <listitem> - <para> - Convert DSD to PCM on-the-fly. - </para> - </listitem> - </itemizedlist> - - <para> - Native DSD playback is used automatically if available. DoP - is only used if enabled explicitly using the <link - linkend="alsa_output"><varname>dop</varname></link> option, - because there is no way for <application>MPD</application> to - find out whether the DAC supports it. DSD to PCM conversion - is the fallback if DSD cannot be used directly. - </para> - </section> - </chapter> - - <chapter id="client_hacks"> - <title>Client Hacks</title> - - <section id="external_mixer"> - <title>External Mixer</title> - - <para> - The setting '<varname>mixer_type</varname> - "<parameter>null</parameter>"' asks - <application>MPD</application> to pretend that there is a - mixer, but not actually do something. This allows you to - implement a <application>MPD</application> client which - listens for <varname>mixer</varname> events, queries the - current (fake) volume, and uses it to program an external - mixer. For example, your client can forward this setting to - your amplifier. - </para> - </section> - </chapter> - - <chapter id="troubleshooting"> - <title>Troubleshooting</title> - - <section id="troubleshooting_start"> - <title>Where to start</title> - - <para> - Make sure you have the latest <application>MPD</application> - version (via <command>mpd --version</command>, not - <command>mpc version</command>). All the time, bugs are found - and fixed, and your problem might be a bug that is fixed - already. Do not ask for help unless you have the latest - <application>MPD</application> version. The most common - excuse is when your distribution ships an old - <application>MPD</application> version - in that case, please - ask your distribution for help, and not the - <application>MPD</application> project. - </para> - - <para> - Check the log file. Configure '<varname>log_level</varname> - "<parameter>verbose</parameter>"' or pass - <parameter>--verbose</parameter> to <filename>mpd</filename>. - </para> - - <para> - Sometimes, it is helpful to run <application>MPD</application> - in a terminal and follow what happens. This is how to do it: - </para> - - <programlisting>mpd --stdout --no-daemon --verbose</programlisting> - </section> - - <section id="support"> - <title>Support</title> - - <section id="help"> - <title>Getting Help</title> - - <para> - The <application>MPD</application> project runs <ulink - url="https://forum.musicpd.org/">a forum</ulink> and an IRC - channel (<varname>#mpd</varname> on Freenode) for requesting - help. Visit <ulink url="https://www.musicpd.org/help/">the - <application>MPD</application> help page</ulink> for details - on how to get help. - </para> - </section> - - <section id="faq"> - <title>Common Problems</title> - - <qandaset defaultlabel='qanda'> - <qandadiv> - <title>Database</title> - - <qandaentry> - <question> - <para> - I can't see my music in the - <application>MPD</application> database! - </para> - </question> - <answer> - <itemizedlist> - <listitem> - <para> - Check your <varname>music_directory</varname> - setting. - </para> - </listitem> - </itemizedlist> - <itemizedlist> - <listitem> - <para> - Does the <application>MPD</application> user - have read permission on all music files, and - read+execute permission on all music directories - (and all of their parent directories)? - </para> - </listitem> - </itemizedlist> - <itemizedlist> - <listitem> - <para> - Did you update the database? (<command>mpc - update</command>) - </para> - </listitem> - </itemizedlist> - <itemizedlist> - <listitem> - <para> - Did you enable all relevant decoder plugins at - compile time? <command>mpd --version</command> - will tell you. - </para> - </listitem> - </itemizedlist> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para> - <application>MPD</application> doesn't read ID3 - tags! - </para> - </question> - <answer> - <para> - You probably compiled <application>MPD</application> - without <filename>libid3tag</filename>. - <command>mpd --version</command> will tell you. - </para> - </answer> - </qandaentry> - </qandadiv> - - <qandadiv> - <title>Playback</title> - - <qandaentry> - <question> - <para>I can't hear music on my client!</para> - </question> - <answer> - <para> - That problem usually follows a misunderstanding of the - nature of <application>MPD</application>. - <application>MPD</application> is a remote-controlled - music player, not a music distribution system. - Usually, the speakers are connected to the box where - <application>MPD</application> runs, and the - <application>MPD</application> client only sends - control commands, but the client does not actually - play your music. - </para> - - <para> - <application>MPD</application> has output plugins - which allow hearing music on a remote host (such as - <link - linkend="httpd_output"><varname>httpd</varname></link>), - but that is not <application>MPD</application>'s - primary design goal. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para>"Device or resource busy"</para> - </question> - <answer> - <para> - This ALSA error means that another program uses your - sound hardware exclusively. You can stop that - program to allow <application>MPD</application> to - use it. - </para> - <para> - Sometimes, this other program is - <application>PulseAudio</application>, which can - multiplex sound from several applications, to allow - them to share your sound chip. In this case, it - might be a good idea for <link - linkend="pulse_output"><application>MPD</application> - to use <application>PulseAudio</application></link> - as well, instead of using ALSA directly. - </para> - </answer> - </qandaentry> - </qandadiv> - </qandaset> - </section> - </section> - - <section id="bugs"> - <title>Reporting Bugs</title> - - <para> - If you believe you found a bug in - <application>MPD</application>, report it on <ulink - url="https://github.com/MusicPlayerDaemon/MPD/issues/">the bug - tracker</ulink>. - </para> - - <para> - Your bug report should contain: - </para> - - <itemizedlist> - <listitem> - <para> - the output of <command>mpd --version</command> - </para> - </listitem> - - <listitem> - <para> - your <link linkend="config_file">configuration file</link> - (<filename>mpd.conf</filename>) - </para> - </listitem> - - <listitem> - <para> - relevant portions of the log file (--verbose) - </para> - </listitem> - - <listitem> - <para> - be clear about what you expect MPD to do, and what is - actually happening - </para> - </listitem> - </itemizedlist> - - <section id="crash"> - <title><application>MPD</application> crashes</title> - - <para> - All <application>MPD</application> crashes are bugs which - must be fixed by a developer, and you should write a bug - report. (Many crash bugs are caused by codec libraries - used by <application>MPD</application>, and then that - library must be fixed; but in any case, the - <application>MPD</application> bug tracker is a good place - to report it first if you don't know.) - </para> - - <para> - A crash bug report needs to contain a "backtrace". - </para> - - <para> - First of all, your <application>MPD</application> executable - must not be "stripped" (i.e. debug information deleted). - The executables shipped with Linux distributions are usually - stripped, but some have so-called "debug" packages (package - <filename>mpd-dbg</filename> or - <filename>mpd-dbgsym</filename> on Debian, - <filename>mpd-debug</filename> on other distributions). - Make sure this package is installed. - </para> - - <para> - You can extract the backtrace from a core dump, or by - running <application>MPD</application> in a debugger, e.g.: - </para> - - <programlisting>gdb --args mpd --stdout --no-daemon --verbose -run</programlisting> - - <para> - As soon as you have reproduced the crash, type - "<command>bt</command>" on the <filename>gdb</filename> - command prompt. Copy the output to your bug report. - </para> - </section> - </section> - </chapter> - - <chapter id="plugin_reference"> - <title>Plugin reference</title> - - <section id="database_plugins"> - <title>Database plugins</title> - - <section id="simple_database"> - <title><varname>simple</varname></title> - - <para> - The default plugin. Stores a copy of the database in - memory. A file is used for permanent storage. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>path</varname> - </entry> - <entry> - The path of the database file. - </entry> - </row> - - <row> - <entry> - <varname>cache_directory</varname> - </entry> - <entry> - The path of the cache directory for additional - storages mounted at runtime. This setting is - necessary for the <command>mount</command> protocol - command. - </entry> - </row> - - <row> - <entry> - <varname>compress</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - Compress the database file using - <filename>gzip</filename>? Enabled by default (if - built with <filename>zlib</filename>). - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="proxy_database"> - <title><varname>proxy</varname></title> - - <para> - Provides access to the database of another - <application>MPD</application> instance using - <filename>libmpdclient</filename>. This is useful when you - run mount the music directory via NFS/SMB, and the file - server already runs a <application>MPD</application> - instance. Only the file server needs to update the - database. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>host</varname> - </entry> - <entry> - The host name of the "master" - <application>MPD</application> instance. - </entry> - </row> - <row> - <entry> - <varname>port</varname> - </entry> - <entry> - The port number of the "master" - <application>MPD</application> instance. - </entry> - </row> - <row> - <entry> - <varname>password</varname> - </entry> - <entry> - The password used to log in to the "master" - <application>MPD</application> instance. - </entry> - </row> - <row> - <entry> - <varname>keepalive</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - Send TCP keepalive packets to the "master" - <application>MPD</application> instance? This option can - help avoid certain firewalls dropping inactive - connections, at the expensive of a very small amount of - additional network traffic. Disabled by default. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title><varname>upnp</varname></title> - - <para> - Provides access to UPnP media servers. - </para> - </section> - </section> - - <section id="storage_plugins"> - <title>Storage plugins</title> - - <section> - <title><varname>local</varname></title> - - <para> - The default plugin which gives - <application>MPD</application> access to local files. It is - used when <varname>music_directory</varname> refers to a - local directory. - </para> - </section> - - <section id="curl_storage"> - <title><varname>curl</varname></title> - - <para> - A WebDAV client using <filename>libcurl</filename>. It is - used when <varname>music_directory</varname> contains a - <parameter>http://</parameter> or - <parameter>https://</parameter> URI, for example - "<parameter>https://the.server/dav/</parameter>". - </para> - </section> - - <section id="smbclient_storage"> - <title><varname>smbclient</varname></title> - - <para> - Load music files from a SMB/CIFS server. It is used when - <varname>music_directory</varname> contains a - <parameter>smb://</parameter> URI, for example - "<parameter>smb://myfileserver/Music</parameter>". - </para> - </section> - - <section id="nfs_storage"> - <title><varname>nfs</varname></title> - - <para> - Load music files from a NFS server. It is used when - <varname>music_directory</varname> contains a - <parameter>nfs://</parameter> URI according to <ulink - url="http://tools.ietf.org/html/rfc2224">RFC2224</ulink>, - for example "<parameter>nfs://servername/path</parameter>". - </para> - - <para> - This plugin uses <ulink - url="https://github.com/sahlberg/libnfs"><filename>libnfs</filename></ulink>, - which supports only NFS version 3. Since - <application>MPD</application> is not allowed to bind to - "privileged ports", the NFS server needs to enable the - "insecure" setting; example - <filename>/etc/exports</filename>: - </para> - - <programlisting>/srv/mp3 192.168.1.55(ro,insecure)</programlisting> - - <para> - Don't fear: "insecure" does not mean that your NFS server is - insecure. A few decades ago, people thought the concept of - "privileged ports" would make network services "secure", - which was a fallacy. The absence of this obsolete - "security" measure means little. - </para> - </section> - - <section id="udisks_storage"> - <title><varname>udisks</varname></title> - - <para> - Mount file systems (e.g. USB sticks or other removable - media) using the <varname>udisks2</varname> daemon via - D-Bus. To obtain a valid <varname>udisks2</varname> URI, - consult the according <link - linkend="udisks_neighbor">neighbor plugin</link>. - </para> - </section> - </section> - - <section id="neighbor_plugins"> - <title>Neighbor plugins</title> - - <section id="smbclient_neighbor"> - <title><varname>smbclient</varname></title> - - <para> - Provides a list of SMB/CIFS servers on the local network. - </para> - </section> - - <section id="udisks_neighbor"> - <title><varname>udisks</varname></title> - - <para> - Queries the <varname>udisks2</varname> daemon via D-Bus and - obtain a list of file systems (e.g. USB sticks or other - removable media). - </para> - </section> - - <section id="upnp_neighbor"> - <title><varname>upnp</varname></title> - - <para> - Provides a list of UPnP servers on the local network. - </para> - </section> - </section> - - <section id="input_plugins"> - <title>Input plugins</title> - - <section> - <title><varname>alsa</varname></title> - - <para> - Allows <application>MPD</application> on Linux to play audio - directly from a soundcard using the scheme - <filename>alsa://</filename>. Audio is formatted as 44.1 kHz - 16-bit stereo (CD format). Examples: - </para> - - <para> - <filename>mpc add alsa://</filename> plays audio from device hw:0,0 - </para> - <para> - <filename>mpc add alsa://hw:1,0</filename> plays audio from device - hw:1,0 - </para> - </section> - - <section> - <title><varname>cdio_paranoia</varname></title> - - <para> - Plays audio CDs using <ulink - url="http://www.gnu.org/software/libcdio/"><filename>libcdio</filename></ulink>. - 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> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>default_byte_order</varname> - <parameter>little_endian|big_endian</parameter> - </entry> - <entry> - If the CD drive does not specify a byte order, - <application>MPD</application> assumes it is the - CPU's native byte order. This setting allows - overriding this. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title><varname>curl</varname></title> - - <para> - Opens remote files or streams over HTTP using <ulink - url="http://curl.haxx.se/"><filename>libcurl</filename></ulink>. - </para> - - <para> - Note that unless overridden by the below settings (e.g. by - setting them to a blank value), general curl configuration - from environment variables such as - <varname>http_proxy</varname> or specified in - <filename>~/.curlrc</filename> will be in effect. - </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> - <row> - <entry> - <varname>proxy_user</varname>, - <varname>proxy_password</varname> - </entry> - <entry> - Configures proxy authentication. - </entry> - </row> - - <row> - <entry> - <varname>verify_peer</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - Verify the peer's SSL certificate? <ulink - url="http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html">More - information</ulink>. - </entry> - </row> - - <row> - <entry> - <varname>verify_host</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - Verify the certificate's name against host? <ulink - url="http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html">More - information</ulink>. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="ffmpeg_input"> - <title><varname>ffmpeg</varname></title> - - <para> - Access to various network protocols implemented by the - <application>FFmpeg</application> library: - <filename>gopher://</filename>, - <filename>rtp://</filename>, - <filename>rtsp://</filename>, - <filename>rtmp://</filename>, - <filename>rtmpt://</filename>, - <filename>rtmps://</filename> - </para> - </section> - - <section> - <title><varname>file</varname></title> - - <para> - Opens local files. - </para> - </section> - - <section> - <title><varname>mms</varname></title> - - <para> - Plays streams with the MMS protocol using <ulink - url="https://launchpad.net/libmms"><filename>libmms</filename></ulink>. - </para> - </section> - - <section> - <title><varname>nfs</varname></title> - - <para> - Allows <application>MPD</application> to access files on - NFSv3 servers without actually mounting them (i.e. in - userspace, without help from the kernel's VFS layer). All - URIs with the <filename>nfs://</filename> scheme are used - according to <ulink - url="http://tools.ietf.org/html/rfc2224">RFC2224</ulink>. - Example: - </para> - - <para> - <filename>mpc add nfs://servername/path/filename.ogg</filename> - </para> - - <para> - Note that this usually requires enabling the "insecure" flag - in the server's <filename>/etc/exports</filename> file, - because <application>MPD</application> cannot bind to - so-called "privileged" ports. Don't fear: this will not - make your file server insecure; the flag was named in a time - long ago when privileged ports were thought to be meaningful - for security. By today's standards, NFSv3 is not secure at - all, and if you believe it is, you're already doomed. - </para> - </section> - - <section> - <title><varname>smbclient</varname></title> - - <para> - Allows <application>MPD</application> to access files on - SMB/CIFS servers (e.g. Samba or Microsoft Windows). All - URIs with the <filename>smb://</filename> scheme are used. - Example: - </para> - - <para> - <filename>mpc add smb://servername/sharename/filename.ogg</filename> - </para> - </section> - - <section id="qobuz_input"> - <title><varname>qobuz</varname></title> - - <para> - Play songs from the commercial streaming service <ulink - url="https://www.qobuz.com/">Qobuz</ulink>. It plays URLs in the - form <filename>qobuz://track/ID</filename>, e.g.: - </para> - - <programlisting>mpc add qobuz://track/23601296</programlisting> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>app_id</varname> - <parameter>ID</parameter> - </entry> - <entry> - The Qobuz application id. - </entry> - </row> - - <row> - <entry> - <varname>app_secret</varname> - <parameter>SECRET</parameter> - </entry> - <entry> - The Qobuz application secret. - </entry> - </row> - - <row> - <entry> - <varname>username</varname> - <parameter>USERNAME</parameter> - </entry> - <entry> - The Qobuz user name. - </entry> - </row> - - <row> - <entry> - <varname>password</varname> - <parameter>PASSWORD</parameter> - </entry> - <entry> - The Qobuz password. - </entry> - </row> - - <row> - <entry> - <varname>format_id</varname> - <parameter>N</parameter> - </entry> - <entry> - The <ulink - url="https://github.com/Qobuz/api-documentation/blob/master/endpoints/track/getFileUrl.md#parameters">Qobuz - format identifier</ulink>, i.e. a number which - chooses the format and quality to be requested from - Qobuz. The default is "5" (320 kbit/s MP3). - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="tidal_input"> - <title><varname>tidal</varname></title> - - <para> - Play songs from the commercial streaming service <ulink - url="http://tidal.com/">Tidal</ulink>. It plays URLs in the - form <filename>tidal://track/ID</filename>, e.g.: - </para> - - <programlisting>mpc add tidal://track/59727857</programlisting> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>token</varname> - <parameter>TOKEN</parameter> - </entry> - <entry> - The Tidal application token. Since Tidal is - unwilling to assign a token to MPD, this needs to be - reverse-engineered from another (approved) Tidal - client. - </entry> - </row> - - <row> - <entry> - <varname>username</varname> - <parameter>USERNAME</parameter> - </entry> - <entry> - The Tidal user name. - </entry> - </row> - - <row> - <entry> - <varname>password</varname> - <parameter>PASSWORD</parameter> - </entry> - <entry> - The Tidal password. - </entry> - </row> - - <row> - <entry> - <varname>audioquality</varname> - <parameter>Q</parameter> - </entry> - <entry> - The Tidal "audioquality" parameter. Possible - values: <parameter>HI_RES</parameter>, - <parameter>LOSSLESS</parameter>, - <parameter>HIGH</parameter>, - <parameter>LOW</parameter>. Default is - <parameter>HIGH</parameter>. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - </section> - - <section id="decoder_plugins"> - <title>Decoder plugins</title> - - <section id="adplug_decoder"> - <title><varname>adplug</varname></title> - - <para> - Decodes AdLib files using <ulink - url="http://adplug.sourceforge.net/">libadplug</ulink>. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>sample_rate</varname> - <parameter></parameter> - </entry> - <entry> - The sample rate that shall be synthesized by the - plugin. Defaults to 48000. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="audiofile_decoder"> - <title><varname>audiofile</varname></title> - - <para> - Decodes WAV and AIFF files using <ulink - url="http://audiofile.68k.org/"><filename>libaudiofile</filename></ulink>. - </para> - </section> - - <section id="faad_decoder"> - <title><varname>faad</varname></title> - - <para> - Decodes AAC files using <ulink - url="http://www.audiocoding.com/"><filename>libfaad</filename></ulink>. - </para> - </section> - - <section id="ffmpeg_decoder"> - <title><varname>ffmpeg</varname></title> - - <para> - Decodes various codecs using <ulink - url="https://ffmpeg.org/"><application>FFmpeg</application></ulink>. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>analyzeduration</varname> - <parameter>VALUE</parameter> - </entry> - <entry> - Sets the FFmpeg muxer option - <varname>analyzeduration</varname>, which specifies - how many microseconds are analyzed to probe the - input. The <ulink - url="https://ffmpeg.org/ffmpeg-formats.html">FFmpeg - formats documentation</ulink> has more information. - </entry> - </row> - - <row> - <entry> - <varname>probesize</varname> - <parameter>VALUE</parameter> - </entry> - <entry> - Sets the FFmpeg muxer option - <varname>probesize</varname>, which specifies - probing size in bytes, i.e. the size of the data to - analyze to get stream information. The <ulink - url="https://ffmpeg.org/ffmpeg-formats.html">FFmpeg - formats documentation</ulink> has more information. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="flac_decoder"> - <title><varname>flac</varname></title> - - <para> - Decodes FLAC files using - <ulink url="https://xiph.org/flac/"><application>libFLAC</application></ulink>. - </para> - </section> - - <section id="dsdiff_decoder"> - <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 - <parameter>no</parameter>. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="dsf_decoder"> - <title><varname>dsf</varname></title> - - <para> - Decodes DSF files containing DSDIFF data (e.g. SACD rips). - </para> - - </section> - - <section> - <title><varname>fluidsynth</varname></title> - - <para> - MIDI decoder based on <ulink - url="http://www.fluidsynth.org/"><application>FluidSynth</application></ulink>. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>sample_rate</varname> - </entry> - <entry> - The sample rate that shall be synthesized by the - plugin. Defaults to 48000. - </entry> - </row> - <row> - <entry> - <varname>soundfont</varname> - </entry> - <entry> - The absolute path of the soundfont file. Defaults - to - <filename>/usr/share/sounds/sf2/FluidR3_GM.sf2</filename>. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title><varname>gme</varname></title> - - <para> - Video game music file emulator based on <ulink - url="https://bitbucket.org/mpyne/game-music-emu/wiki/Home"><application>game-music-emu</application></ulink>. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>accuracy</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - Enable more accurate sound emulation. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="hybrid_dsd_decoder"> - <title><varname>hybrid_dsd</varname></title> - - <para> - <ulink - url="http://dsdmaster.blogspot.de/p/bitperfect-introduces-hybrid-dsd-file.html">Hybrid-DSD</ulink> - is a MP4 container file (<filename>*.m4a</filename>) which - contains both ALAC and DSD data. It is disabled by default, - and works only if you explicitly enable it. Without this - plugin, the ALAC parts gets handled by the <link - linkend="ffmpeg_decoder">FFmpeg decoder plugin</link>. This - plugin should be enabled only if you have a bit-perfect - playback path to a DSD-capable DAC; for everybody else, - playing back the ALAC copy of the file is better. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>gapless</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - This specifies whether to support gapless playback - of MP3s which have the necessary headers. Useful if - your MP3s have headers with incorrect information. - If you have such MP3s, it is highly recommended that - you fix them using <ulink - url="http://www.willwap.co.uk/Programs/vbrfix.php"><application>vbrfix</application></ulink> - instead of disabling gapless MP3 playback. The - default is to support gapless MP3 playback. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="mad_decoder"> - <title><varname>mad</varname></title> - - <para> - Decodes MP3 files using <ulink - url="http://www.underbit.com/products/mad/"><application>libmad</application></ulink>. - </para> - </section> - - <section> - <title><varname>mikmod</varname></title> - - <para> - Module player based on <ulink - url="http://mikmod.sourceforge.net/"><application>MikMod</application></ulink>. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>loop</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - Allow backward loops in modules. Default is - <parameter>no</parameter>. - </entry> - </row> - <row> - <entry> - <varname>sample_rate</varname> - </entry> - <entry> - Sets the sample rate generated by - <filename>libmikmod</filename>. Default is 44100. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title><varname>modplug</varname></title> - - <para> - Module player based on <application>MODPlug</application>. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>loop_count</varname> - </entry> - <entry> - Number of times to loop the module if it uses backward loops. - Default is <parameter>0</parameter> which prevents looping. - <parameter>-1</parameter> loops forever. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="mpcdec_decoder"> - <title><varname>mpcdec</varname></title> - - <para> - Decodes Musepack files using <ulink - url="http://www.musepack.net/"><application>libmpcdec</application></ulink>. - </para> - </section> - - <section id="mpg123_decoder"> - <title><varname>mpg123</varname></title> - - <para> - Decodes MP3 files using <ulink - url="http://www.mpg123.de/"><application>libmpg123</application></ulink>. - </para> - </section> - - <section id="opus_decoder"> - <title><varname>opus</varname></title> - - <para> - Decodes Opus files using <ulink - url="http://www.opus-codec.org/"><application>libopus</application></ulink>. - </para> - </section> - - <section> - <title><varname>pcm</varname></title> - - <para> - Read raw PCM samples. It understands the "audio/L16" MIME - type with parameters "rate" and "channels" according to RFC - 2586. It also understands the - <application>MPD</application>-specific MIME type - "audio/x-mpd-float". - </para> - </section> - - <section id="sidplay_decoder"> - <title><varname>sidplay</varname></title> - - <para> - C64 SID decoder based on <ulink - url="http://sidplay2.sourceforge.net/"><application>libsidplay</application></ulink>. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>songlength_database</varname> - <parameter>PATH</parameter> - </entry> - <entry> - Location of your songlengths file, as distributed - with the HVSC. The <varname>sidplay</varname> - plugin checks this for matching MD5 fingerprints. - See <ulink url="http://www.hvsc.c64.org/download/C64Music/DOCUMENTS/Songlengths.faq"/>. - </entry> - </row> - - <row> - <entry> - <varname>default_songlength</varname> - <parameter>SECONDS</parameter> - </entry> - <entry> - This is the default playing time in seconds for - songs not in the songlength database, or in case - you're not using a database. A value of 0 means - play indefinitely. - </entry> - </row> - - <row> - <entry> - <varname>filter</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - Turns the SID filter emulation on or off. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="sndfile_decoder"> - <title><varname>sndfile</varname></title> - - <para> - Decodes WAV and AIFF files using <ulink - url="http://www.mega-nerd.com/libsndfile/"><filename>libsndfile</filename></ulink>. - </para> - </section> - - <section id="vorbis_decoder"> - <title><varname>vorbis</varname></title> - - <para> - Decodes Ogg-Vorbis files using <ulink - url="http://www.xiph.org/ogg/vorbis/"><application>libvorbis</application></ulink>. - </para> - </section> - - <section id="wavpack_decoder"> - <title><varname>wavpack</varname></title> - - <para> - Decodes WavPack files using - <ulink url="http://www.wavpack.com/"><application>libwavpack</application></ulink>. - </para> - </section> - - <section> - <title><varname>wildmidi</varname></title> - - <para> - MIDI decoder based on <ulink - url="http://www.mindwerks.net/projects/wildmidi/"><application>libwildmidi</application></ulink>. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>config_file</varname> - </entry> - <entry> - The absolute path of the timidity config file. Defaults - to - <filename>/etc/timidity/timidity.cfg</filename>. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - </section> - - <section id="encoder_plugins"> - <title>Encoder plugins</title> - - <section> - <title><varname>flac</varname></title> - - <para> - Encodes into <ulink - url="https://xiph.org/flac/">FLAC</ulink> (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 <ulink - url="http://lame.sourceforge.net/"><application>LAME</application></ulink> - 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>shine</varname></title> - - <para> - Encodes into MP3 using the <ulink - url="https://github.com/savonet/shine"><application>Shine</application></ulink> - library. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>bitrate</varname> - </entry> - <entry> - Sets the bit rate in kilobit per second. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title><varname>twolame</varname></title> - - <para> - Encodes into MP2 using the <ulink - url="http://www.twolame.org/"><application>TwoLAME</application></ulink> - 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 id="opus_encoder"> - <title><varname>opus</varname></title> - - <para> - Encodes into <ulink - url="http://www.opus-codec.org/">Ogg Opus</ulink>. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>bitrate</varname> - </entry> - <entry> - Sets the data rate in bit per second. The special - value "auto" lets <application>libopus</application> - choose a rate (which is the default), and "max" uses - the maximum possible data rate. - </entry> - </row> - - <row> - <entry> - <varname>complexity</varname> - </entry> - <entry> - Sets the <ulink - url="https://wiki.xiph.org/OpusFAQ#What_is_the_complexity_of_Opus.3F">Opus - complexity</ulink>. - </entry> - </row> - - <row> - <entry> - <varname>signal</varname> - </entry> - <entry> - Sets the Opus signal type. Valid values are "auto" - (the default), "voice" and "music". - </entry> - </row> - - <row> - <entry> - <varname>opustags</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - Configures how metadata is interleaved into the stream. - If set to <parameter>yes</parameter>, then metadata - is inserted using ogg stream chaining, as specified - in <ulink url="https://tools.ietf.org/html/rfc7845.html#section-7.2">RFC - 7845</ulink>. If set to <parameter>no</parameter> - (the default), then ogg stream chaining is avoided - and other output-dependent method is used, if - available. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="vorbis_encoder"> - <title><varname>vorbis</varname></title> - - <para> - Encodes into <ulink url="http://www.vorbis.com/">Ogg - Vorbis</ulink>. - </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. Defaults to 3. 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 id="resampler_plugins"> - <title>Resampler plugins</title> - - <para> - The resampler can be configured in a block named - <varname>resampler</varname>, for example: - </para> - - <programlisting>resampler { - plugin "soxr" - quality "very high" -}</programlisting> - - <para> - The following table lists the <varname>resampler</varname> - options valid for all plugins: - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry> - Name - </entry> - <entry> - Description - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>plugin</varname> - </entry> - <entry> - The name of the plugin. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <section id="internal_resampler"> - <title><varname>internal</varname></title> - - <para> - A resampler built into <application>MPD</application>. Its - quality is very poor, but its CPU usage is low. This is the - fallback if <application>MPD</application> was compiled - without an external resampler. - </para> - </section> - - <section id="libsamplerate_resampler"> - <title><varname>libsamplerate</varname></title> - - <para> - A resampler using <ulink - url="http://www.mega-nerd.com/SRC/"><application>libsamplerate</application></ulink> - a.k.a. Secret Rabbit Code (SRC). - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry> - Name - </entry> - <entry> - Description - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>type</varname> - </entry> - <entry> - The interpolator type. See below for a list of - known types. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para> - The following converter types are provided by - <application>libsamplerate</application>: - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry> - Type - </entry> - <entry> - Description - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - "<parameter>Best Sinc Interpolator</parameter>" or - "<parameter>0</parameter>" - </entry> - <entry> - Band limited sinc interpolation, best quality, 97dB - SNR, 96% BW. - </entry> - </row> - - <row> - <entry> - "<parameter>Medium Sinc Interpolator</parameter>" or - "<parameter>1</parameter>" - </entry> - <entry> - Band limited sinc interpolation, medium quality, - 97dB SNR, 90% BW. - </entry> - </row> - - <row> - <entry> - "<parameter>Fastest Sinc Interpolator</parameter>" or - "<parameter>2</parameter>" - </entry> - <entry> - Band limited sinc interpolation, fastest, 97dB SNR, - 80% BW. - </entry> - </row> - - <row> - <entry> - "<parameter>ZOH Sinc Interpolator</parameter>" or - "<parameter>3</parameter>" - </entry> - <entry> - Zero order hold interpolator, very fast, very poor - quality with audible distortions. - </entry> - </row> - - <row> - <entry> - "<parameter>Linear Interpolator</parameter>" or - "<parameter>4</parameter>" - </entry> - <entry> - Linear interpolator, very fast, poor quality. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="soxr_resampler"> - <title><varname>soxr</varname></title> - - <para> - A resampler using <ulink - url="http://sourceforge.net/projects/soxr/"><application>libsoxr</application></ulink>, - the SoX Resampler library - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry> - Name - </entry> - <entry> - Description - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>quality</varname> - </entry> - <entry> - The <application>libsoxr</application> quality - setting. Valid values are: - - <itemizedlist> - <listitem> - <para> - "<parameter>very high</parameter>" - </para> - </listitem> - - <listitem> - <para> - "<parameter>high</parameter>" (the default) - </para> - </listitem> - - <listitem> - <para> - "<parameter>medium</parameter>" - </para> - </listitem> - - <listitem> - <para> - "<parameter>low</parameter>" - </para> - </listitem> - - <listitem> - <para> - "<parameter>quick</parameter>" - </para> - </listitem> - </itemizedlist> - </entry> - </row> - - <row> - <entry> - <varname>threads</varname> - </entry> - <entry> - The number of <application>libsoxr</application> - threads. "0" means "automatic". The default is "1" - which disables multi-threading. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - </section> - - <section id="output_plugins"> - <title>Output plugins</title> - - <section id="alsa_output"> - <title><varname>alsa</varname></title> - - <para> - The <ulink - url="http://www.alsa-project.org/"><application>Advanced - Linux Sound Architecture</application> - (<application>ALSA</application>)</ulink> plugin uses - <filename>libasound</filename>. It is recommended if you - are using Linux. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>device</varname> - <parameter>NAME</parameter> - </entry> - <entry> - Sets the device which should be used. This can be - any valid ALSA device name. The default value is - "default", which makes - <filename>libasound</filename> choose a device. It - is recommended to use a "hw" or "plughw" device, - because otherwise, <filename>libasound</filename> - automatically enables "dmix", which has major - disadvantages (fixed sample rate, poor resampler, - ...). - </entry> - </row> - <row> - <entry> - <varname>buffer_time</varname> - <parameter>US</parameter> - </entry> - <entry> - Sets the device's buffer time in microseconds. - Don't change unless you know what you're doing. - </entry> - </row> - <row> - <entry> - <varname>period_time</varname> - <parameter>US</parameter> - </entry> - <entry> - Sets the device's period time in microseconds. - Don't change unless you really know what you're - doing. - </entry> - </row> - <row> - <entry> - <varname>auto_resample</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - If set to <parameter>no</parameter>, then - <filename>libasound</filename> will not attempt to - resample, handing the responsibility over to - <application>MPD</application>. It is recommended - to let <application>MPD</application> resample (with - <application>libsamplerate</application>), because - ALSA is quite poor at doing so. - </entry> - </row> - <row> - <entry> - <varname>auto_channels</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - If set to <parameter>no</parameter>, then - <filename>libasound</filename> will not attempt to - convert between different channel numbers. - </entry> - </row> - <row> - <entry> - <varname>auto_format</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - If set to <parameter>no</parameter>, then - <filename>libasound</filename> will not attempt to - convert between different sample formats (16 bit, 24 - bit, floating point, ...). - </entry> - </row> - <row> - <entry> - <varname>dop</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - If set to <parameter>yes</parameter>, then DSD over - PCM according to the <ulink - url="http://dsd-guide.com/dop-open-standard">DoP - standard</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> - - <row> - <entry> - <varname>allowed_formats</varname> - <parameter>F1 F2 ...</parameter> - </entry> - <entry> - <para> - Specifies a list of allowed audio formats, separated - by a space. All items may contain asterisks as a - wild card, and may be followed by - "<parameter>=dop</parameter>" to enable DoP (DSD - over PCM) for this particular format. The first - matching format is used, and if none matches, MPD - chooses the best fallback of this list. - </para> - <para> - Example: "<parameter>96000:16:* 192000:24:* - dsd64:*=dop *:dsd:*</parameter>". - </para> - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para> - The according hardware mixer plugin understands the - following settings: - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>mixer_device</varname> - <parameter>DEVICE</parameter> - </entry> - <entry> - <para> - Sets the ALSA mixer device name, defaulting to - <parameter>default</parameter> which lets ALSA - pick a value. - </para> - </entry> - </row> - <row> - <entry> - <varname>mixer_control</varname> - <parameter>NAME</parameter> - </entry> - <entry> - <para> - Choose a mixer control, defaulting to - <parameter>PCM</parameter>. Type <command>amixer - scontrols</command> to get a list of available - mixer controls. - </para> - </entry> - </row> - <row> - <entry> - <varname>mixer_index</varname> - <parameter>NUMBER</parameter> - </entry> - <entry> - Choose a mixer control index. This is necessary if - there is more than one control with the same name. - Defaults to <parameter>0</parameter> (the first - one). - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para> - The following attributes can be configured at runtime using - the <command>outputset</command> command: - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>dop</varname> - <parameter>1|0</parameter> - </entry> - <entry> - <para> - Allows changing the <varname>dop</varname> - configuration setting at runtime. This takes - effect the next time the output is opened. - </para> - </entry> - </row> - - <row> - <entry> - <varname>allowed_formats</varname> - <parameter>F1 F2 ...</parameter> - </entry> - <entry> - <para> - Allows changing the - <varname>allowed_formats</varname> configuration - setting at runtime. This takes effect the next - time the output is opened. - </para> - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title><varname>ao</varname></title> - - <para> - The <varname>ao</varname> plugin uses the portable <ulink - url="https://www.xiph.org/ao/"><filename>libao</filename></ulink> - library. Use only if there is no native plugin for your - operating system. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>driver</varname> - <parameter>D</parameter> - </entry> - <entry> - The <filename>libao</filename> driver to use for - audio output. Possible values depend on what libao - drivers are available. See <ulink - url="http://www.xiph.org/ao/doc/drivers.html">http://www.xiph.org/ao/doc/drivers.html</ulink> - for information on some commonly used drivers. - Typical values for Linux include "oss" and "alsa09". - The default is "default", which causes libao to - select an appropriate plugin. - </entry> - </row> - - <row> - <entry> - <varname>options</varname> - <parameter>O</parameter> - </entry> - <entry> - Options to pass to the selected - <filename>libao</filename> driver. - </entry> - </row> - - <row> - <entry> - <varname>write_size</varname> - <parameter>O</parameter> - </entry> - <entry> - This specifies how many bytes to write to the audio - device at once. This parameter is to work around a - bug in older versions of libao on sound cards with - very small buffers. The default is 1024. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title><varname>sndio</varname></title> - - <para> - The <varname>sndio</varname> plugin uses the <ulink - url="http://www.sndio.org/">sndio</ulink> library. It should normally be used - on OpenBSD. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>device</varname> - <parameter>NAME</parameter> - </entry> - <entry> - The audio output device <filename>libsndio</filename> - will attempt to use. The default is "default" which - causes libsndio to select the first output device. - </entry> - </row> - - <row> - <entry> - <varname>buffer_time</varname> - <parameter>MS</parameter> - </entry> - <entry> - Set the application buffer time in milliseconds. - </entry> - </row> - - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title><varname>fifo</varname></title> - - <para> - The <varname>fifo</varname> plugin writes raw PCM data to a - FIFO (First In, First Out) file. The data can be read by - another program. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>path</varname> - <parameter>P</parameter> - </entry> - <entry> - This specifies the path of the FIFO to write to. - Must be an absolute path. If the path does not - exist, it will be created when - <application>MPD</application> is started, and - removed when <application>MPD</application> is - stopped. The FIFO will be created with the same - user and group as <application>MPD</application> is - running as. Default permissions can be modified by - using the builtin shell command - <filename>umask</filename>. If a FIFO already - exists at the specified path it will be reused, and - will not be removed when - <application>MPD</application> is stopped. You can - use the "mkfifo" command to create this, and then - you may modify the permissions to your liking. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="jack_output"> - <title><varname>jack</varname></title> - - <para> - The <varname>jack</varname> plugin connects to a <ulink - url="http://jackaudio.org/"><application>JACK</application></ulink> - server. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>client_name</varname> - <parameter>NAME</parameter> - </entry> - <entry> - The name of the <application>JACK</application> - client. Defaults to "Music Player Daemon". - </entry> - </row> - <row> - <entry> - <varname>server_name</varname> - <parameter>NAME</parameter> - </entry> - <entry> - Optional name of the <application>JACK</application> - server. - </entry> - </row> - <row> - <entry> - <varname>autostart</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - If set to <parameter>yes</parameter>, then - <filename>libjack</filename> will automatically - launch the <application>JACK</application> daemon. - Disabled by default. - </entry> - </row> - <row> - <entry> - <varname>source_ports</varname> - <parameter>A,B</parameter> - </entry> - <entry> - The names of the <application>JACK</application> - source ports to be created. By default, the ports - "left" and "right" are created. To use more ports, - you have to tweak this option. - </entry> - </row> - <row> - <entry> - <varname>destination_ports</varname> - <parameter>A,B</parameter> - </entry> - <entry> - The names of the <application>JACK</application> - destination ports to connect to. - </entry> - </row> - <row> - <entry> - <varname>ringbuffer_size</varname> - <parameter>NBYTES</parameter> - </entry> - <entry> - Sets the size of the ring buffer for each channel. - Do not configure this value unless you know what - you're doing. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="httpd_output"> - <title><varname>httpd</varname></title> - - <para> - The <varname>httpd</varname> plugin creates a HTTP server, - similar to <ulink - url="http://www.shoutcast.com/"><application>ShoutCast</application></ulink> - / <ulink - url="http://icecast.org/"><application>IceCast</application></ulink>. - HTTP streaming clients like - <application>mplayer</application>, <application>VLC</application>, - and <application>mpv</application> can connect to it. - </para> - - <para> - It is highly recommended to configure a fixed - <varname>format</varname>, because a stream cannot switch - its audio format on-the-fly when the song changes. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>port</varname> - <parameter>P</parameter> - </entry> - <entry> - Binds the HTTP server to the specified port. - </entry> - </row> - <row> - <entry> - <varname>bind_to_address</varname> - <parameter>ADDR</parameter> - </entry> - <entry> - Binds the HTTP server to the specified address (IPv4 or - IPv6). Multiple addresses in parallel are not supported. - </entry> - </row> - <row> - <entry> - <varname>encoder</varname> - <parameter>NAME</parameter> - </entry> - <entry> - Chooses an encoder plugin. A list of encoder - plugins can be found in the <link - linkend="encoder_plugins">encoder plugin - reference</link>. - </entry> - </row> - <row> - <entry> - <varname>max_clients</varname> - <parameter>MC</parameter> - </entry> - <entry> - Sets a limit, number of concurrent clients. When set - to 0 no limit will apply. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title><varname>null</varname></title> - - <para> - The <varname>null</varname> plugin does nothing. It - discards everything sent to it. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>sync</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - If set to <parameter>no</parameter>, then the timer - is disabled - the device will accept PCM chunks at - arbitrary rate (useful for benchmarking). The - default behaviour is to play in real time. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="oss_output"> - <title><varname>oss</varname></title> - - <para> - The "Open Sound System" plugin is supported on most Unix - platforms. - </para> - - <para> - On Linux, <application>OSS</application> has been superseded - by <application>ALSA</application>. Use the <link - linkend="alsa_output"><application>ALSA</application> output - plugin</link> instead of this one on Linux. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>device</varname> - <parameter>PATH</parameter> - </entry> - <entry> - Sets the path of the PCM device. If not specified, - then <application>MPD</application> will attempt to - open <filename>/dev/sound/dsp</filename> and - <filename>/dev/dsp</filename>. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - - <para> - The according hardware mixer plugin understands the - following settings: - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>mixer_device</varname> - <parameter>DEVICE</parameter> - </entry> - <entry> - <para> - Sets the OSS mixer device path, defaulting to - <filename>/dev/mixer</filename>. - </para> - </entry> - </row> - <row> - <entry> - <varname>mixer_control</varname> - <parameter>NAME</parameter> - </entry> - <entry> - <para> - Choose a mixer control, defaulting to - <parameter>PCM</parameter>. - </para> - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="openal_output"> - <title><varname>openal</varname></title> - - <para> - The "OpenAL" plugin uses <ulink - url="http://kcat.strangesoft.net/openal.html"><filename>libopenal</filename></ulink>. - It is supported on many platforms. Use only if there is no - native plugin for your operating system. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>device</varname> - <parameter>NAME</parameter> - </entry> - <entry> - Sets the device which should be used. This can be - any valid OpenAL device name. If not specified, then - <filename>libopenal</filename> will choose a default device. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title><varname>osx</varname></title> - - <para> - The "Mac OS X" plugin uses Apple's CoreAudio API. - </para> - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>device</varname> - <parameter>NAME</parameter> - </entry> - <entry> - Sets the device which should be used. Uses device names as listed in the - "Audio Devices" window of "Audio MIDI Setup". - </entry> - </row> - <row> - <entry> - <varname>hog_device</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - Hog the device. This means that it takes exclusive control of the audio - output device it is playing through, and no other program can access it. - </entry> - </row> - <row> - <entry> - <varname>dop</varname> - <parameter>yes|no</parameter> - </entry> - <entry> - If set to <parameter>yes</parameter>, then DSD over - PCM according to the <ulink - url="http://dsd-guide.com/dop-open-standard">DoP - standard</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. Under macOS you must - make sure to select a physical mode on the output - device which supports at least 24 bits per channel - as the Mac OS X plugin only changes the sample rate. - </entry> - </row> - <row> - <entry> - <varname>channel_map</varname> - <parameter>SOURCE,SOURCE,...</parameter> - </entry> - <entry><para> - Specifies a channel map. If your audio device has more than two - outputs this allows you to route audio to auxillary outputs. For - predictable results you should also specify a "format" with a fixed - number of channels, e.g. "*:*:2". The number of items in the channel - map must match the number of output channels of your output device. - Each list entry specifies the source for that output channel; use "-1" - to silence an output. For example, if you have a four-channel output - device and you wish to send stereo sound (format "*:*:2") to outputs 3 - and 4 while leaving outputs 1 and 2 silent then set the channel map to - "-1,-1,0,1". In this example '0' and '1' denote the left and right - channel respectively. - </para> - <para> - The channel map may not refer to outputs that do not exist according - to the format. If the format is "*:*:1" (mono) and you have a - four-channel sound card then "-1,-1,0,0" (dual mono output on the - second pair of sound card outputs) is a valid channel map but - "-1,-1,0,1" is not because the second channel ('1') does not exist - when the output is mono. - </para></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title><varname>pipe</varname></title> - - <para> - The <varname>pipe</varname> plugin starts a program and - writes raw PCM data into its standard input. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>command</varname> - <parameter>CMD</parameter> - </entry> - <entry> - This command is invoked with the shell. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="pulse_output"> - <title><varname>pulse</varname></title> - - <para> - The <varname>pulse</varname> plugin connects to a <ulink - url="http://www.freedesktop.org/wiki/Software/PulseAudio/"><application>PulseAudio</application></ulink> - server. Requires <filename>libpulse</filename>. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>server</varname> - <parameter>HOSTNAME</parameter> - </entry> - <entry> - Sets the host name of the - <application>PulseAudio</application> server. By - default, <application>MPD</application> connects to - the local <application>PulseAudio</application> - server. - </entry> - </row> - <row> - <entry> - <varname>sink</varname> - <parameter>NAME</parameter> - </entry> - <entry> - Specifies the name of the - <application>PulseAudio</application> sink - <application>MPD</application> should play on. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title><varname>roar</varname></title> - - <para> - The <varname>roar</varname> plugin connects to a <ulink - url="http://roaraudio.keep-cool.org/">RoarAudio</ulink> - server. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>server</varname> - <parameter>HOSTNAME</parameter> - </entry> - <entry> - The host name of the RoarAudio server. If not - specified, then <application>MPD</application> will - connect to the default locations. - </entry> - </row> - - <row> - <entry> - <varname>role</varname> - <parameter>ROLE</parameter> - </entry> - <entry> - The "role" that <application>MPD</application> - registers itself as in the RoarAudio server. The - default is "music". - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title><varname>recorder</varname></title> - - <para> - The <varname>recorder</varname> plugin writes the audio - played by <application>MPD</application> to a file. This - may be useful for recording radio streams. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>path</varname> - <parameter>P</parameter> - </entry> - <entry> - Write to this file. - </entry> - </row> - - <row> - <entry> - <varname>format_path</varname> - <parameter>P</parameter> - </entry> - <entry> - <para> - An alternative to <varname>path</varname> which - provides a format string referring to tag values. - - The special tag <varname>iso8601</varname> emits - the current date and time in <ulink - url="https://en.wikipedia.org/wiki/ISO_8601">ISO8601</ulink> - format (UTC). - Every time a new song starts or a new tag gets - received from a radio station, a new file is - opened. If the format does not render a file - name, nothing is recorded. - </para> - - <para> - A tag name enclosed in percent signs ('%') is - replaced with the tag value. Example: - <parameter>~/.mpd/recorder/%artist% - - %title%.ogg</parameter> - </para> - - <para> - Square brackets can be used to group a substring. - If none of the tags referred in the group can be - found, the whole group is omitted. Example: - <parameter>[~/.mpd/recorder/[%artist% - - ]%title%.ogg]</parameter> (this omits the dash - when no artist tag exists; if title also doesn't - exist, no file is written) - </para> - - <para> - The operators "|" (logical "or") and "&" - (logical "and") can be used to select portions of - the format string depending on the existing tag - values. Example: - <parameter>~/.mpd/recorder/[%title%|%name%].ogg</parameter> - (use the "name" tag if no title exists) - </para> - </entry> - </row> - - <row> - <entry> - <varname>encoder</varname> - <parameter>NAME</parameter> - </entry> - <entry> - Chooses an encoder plugin. A list of encoder - plugins can be found in the <link - linkend="encoder_plugins">encoder plugin - reference</link>. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section id="shout_output"> - <title><varname>shout</varname></title> - - <para> - The <varname>shout</varname> plugin connects to a <ulink - url="http://www.shoutcast.com/"><application>ShoutCast</application></ulink> - or <ulink - url="http://icecast.org/"><application>IceCast</application></ulink> - server using <filename>libshout</filename>. It forwards - tags to this server. - </para> - - <para> - You must set a <varname>format</varname>. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>host</varname> - <parameter>HOSTNAME</parameter> - </entry> - <entry> - Sets the host name of the <ulink - url="http://www.shoutcast.com/"><application>ShoutCast</application></ulink> - / <ulink - url="http://icecast.org/"><application>IceCast</application></ulink> - server. - </entry> - </row> - <row> - <entry> - <varname>port</varname> - <parameter>PORTNUMBER</parameter> - </entry> - <entry> - Connect to this port number on the specified host. - </entry> - </row> - <row> - <entry> - <varname>timeout</varname> - <parameter>SECONDS</parameter> - </entry> - <entry> - Set the timeout for the shout connection in seconds. - Defaults to 2 seconds. - </entry> - </row> - <row> - <entry> - <varname>protocol</varname> - <parameter>icecast2|icecast1|shoutcast</parameter> - </entry> - <entry> - Specifies the protocol that wil be used to connect - to the server. The default is - "<parameter>icecast2</parameter>". - - </entry> - </row> - <row> - <entry> - <varname>mount</varname> - <parameter>URI</parameter> - </entry> - <entry> - Mounts the <application>MPD</application> stream in - the specified URI. - </entry> - </row> - <row> - <entry> - <varname>user</varname> - <parameter>USERNAME</parameter> - </entry> - <entry> - Sets the user name for submitting the stream to the - server. Default is "source". - </entry> - </row> - <row> - <entry> - <varname>password</varname> - <parameter>PWD</parameter> - </entry> - <entry> - Sets the password for submitting the stream to the - server. - </entry> - </row> - <row> - <entry> - <varname>name</varname> - <parameter>NAME</parameter> - </entry> - <entry> - Sets the name of the stream. - </entry> - </row> - <row> - <entry> - <varname>genre</varname> - <parameter>GENRE</parameter> - </entry> - <entry> - Sets the genre of the stream (optional). - </entry> - </row> - <row> - <entry> - <varname>description</varname> - <parameter>DESCRIPTION</parameter> - </entry> - <entry> - Sets a short description of the stream (optional). - </entry> - </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> - <entry> - Specifies whether the stream should be "public". - Default is <parameter>no</parameter>. - </entry> - </row> - <row> - <entry> - <varname>encoder</varname> - <parameter>PLUGIN</parameter> - </entry> - <entry> - Chooses an encoder plugin. Default is <link - linkend="vorbis_encoder"><parameter>vorbis</parameter></link>. - A list of encoder plugins can be found in the <link - linkend="encoder_plugins">encoder plugin - reference</link>. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title><varname>solaris</varname></title> - - <para> - The "Solaris" plugin runs only on SUN Solaris, and plays via - <filename>/dev/audio</filename>. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>device</varname> - <parameter>PATH</parameter> - </entry> - <entry> - Sets the path of the audio device, defaults to - <filename>/dev/audio</filename>. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - </section> - - <section id="playlist_plugins"> - <title>Playlist plugins</title> - - <section> - <title><varname>asx</varname></title> - - <para> - Reads <filename>.asx</filename> playlist files. - </para> - </section> - - <section> - <title><varname>cue</varname></title> - - <para> - Reads <filename>.cue</filename> files. - </para> - </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> - Reads <filename>.m3u</filename> playlist files. - </para> - </section> - - <section> - <title><varname>extm3u</varname></title> - - <para> - Reads extended <filename>.m3u</filename> playlist files. - </para> - </section> - - <section> - <title><varname>flac</varname></title> - - <para> - Reads the <varname>cuesheet</varname> metablock from a FLAC - file. - </para> - </section> - - <section> - <title><varname>pls</varname></title> - - <para> - Reads <filename>.pls</filename> playlist files. - </para> - </section> - - <section> - <title><varname>rss</varname></title> - - <para> - Reads music links from <filename>.rss</filename> files. - </para> - </section> - - <section> - <title><varname>soundcloud</varname></title> - - <para> - Download playlist from SoundCloud. It accepts URIs starting - with <filename>soundcloud://</filename>. - </para> - - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>apikey</varname> - <parameter>KEY</parameter> - </entry> - <entry> - An API key to access the SoundCloud servers. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </section> - - <section> - <title><varname>xspf</varname></title> - - <para> - Reads <ulink url="http://www.xspf.org/">XSPF</ulink> - playlist files. - </para> - </section> - </section> - </chapter> -</book> |