diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/user.xml | 1113 |
1 files changed, 947 insertions, 166 deletions
diff --git a/doc/user.xml b/doc/user.xml index 6357267e4..e5b11927d 100644 --- a/doc/user.xml +++ b/doc/user.xml @@ -13,10 +13,10 @@ </para> <para> - MPD (Music Player Daemon) is, as the name suggests, a server - software allowing you to remotely play your music, handle - playlists, deliver music (HTTP STREAMS with various - sub-protocols) and organizze playlists. + <application>MPD</application> (Music Player Daemon) is, as the + name suggests, a server software allowing you to remotely play + your music, handle playlists, deliver music (HTTP streams with + various sub-protocols) and organizze playlists. </para> <para> @@ -26,8 +26,8 @@ </para> <para> - MPD supports also Gapless playback, buffered audio output, and - crossfading! + <application>MPD</application> supports also gapless playback, + buffered audio output, and crossfading! </para> <para> @@ -42,23 +42,26 @@ <para> We recommend that you use the software installation routines of - your distribution to install MPD. Most operating systems have a - MPD package, which is very easy to install. + your distribution to install <application>MPD</application>. + Most operating systems have a <application>MPD</application> + package, which is very easy to install. </para> <section> <title>Installing on Debian/Ubuntu</title> <para> - Install the package <filename>mpd</filename> via APT: + Install the package <application>MPD</application> via APT: </para> <programlisting>apt-get install mpd</programlisting> <para> - When installed this way, MPD by default looks for music in - /var/lib/mpd/music/; this may not be correct. Look at your - /etc/mpd.conf file... + 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> @@ -67,8 +70,9 @@ <para> Download the source tarball from <ulink - url="http://www.musicpd.org/download.html">the MPD home - page</ulink> and unpack it: + 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 @@ -80,6 +84,36 @@ cd mpd-version</programlisting> </para> <para> + For example, the following installs a fairly complete list of + build dependencies on Debian Wheezy: + </para> + + <programlisting> +apt-get install g++ automake autoconf \ + 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 \ + libsamplerate0-dev \ + libbz2-dev libcdio-paranoia-dev libiso9660-dev libmms-dev \ + libzzip-dev \ + libcurl4-gnutls-dev libyajl-dev \ + libasound2-dev libao-dev libjack-jackd2-dev libopenal-dev \ + libpulse-dev libroar-dev libshout3-dev \ + libmpdclient-dev \ + libavahi-client-dev \ + libsqlite3-dev \ + libsystemd-daemon-dev libwrap0-dev \ + libcppunit-dev xmlto \ + libboost-dev \ + libglib2.0-dev + </programlisting> + + <para> Now configure the source tree: </para> @@ -105,38 +139,28 @@ cd mpd-version</programlisting> <para> Using <filename>systemd</filename>, you can launch - <filename>mpd</filename> on demand when the first client - attempts to connect. Create two files in - <filename>/etc/systemd/system/</filename>; first - <filename>mpd.socket</filename>: + <application>MPD</application> on demand when the first client + attempts to connect. </para> - <programlisting>[Socket] -ListenStream=/run/mpd.socket -ListenStream=6600 -[Install] -WantedBy=sockets.target</programlisting> - <para> - Now create <filename>mpd.service</filename>: + <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</parameter>. </para> - <programlisting>[Unit] -Description=Music Player Daemon -After=sound.target -[Service] -ExecStart=/usr/bin/mpd --stdout --no-daemon</programlisting> - <para> - Start the socket: + To enable socket activation, type: </para> <programlisting>systemctl enable mpd.socket systemctl start mpd.socket</programlisting> <para> - In this configuration, <filename>mpd</filename> will ignore - the <varname>bind_to_address</varname> and + In this configuration, <application>MPD</application> will + ignore the <varname>bind_to_address</varname> and <varname>port</varname> settings. </para> </section> @@ -151,16 +175,26 @@ systemctl start mpd.socket</programlisting> <para> When you play local files, you should organize them within a directory called the "music directory". This is configured in - MPD with the <varname>music_directory</varname> setting. + <application>MPD</application> with the + <varname>music_directory</varname> setting. </para> <para> - By default, MPD follows symbolic links in the music directory. - This behavior can be switched off: - <varname>follow_outside_symlinks</varname> controls whether - MPD 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. + 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 storage plugins 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>". </para> </section> @@ -338,10 +372,11 @@ systemctl start mpd.socket</programlisting> <para> Audio outputs are devices which actually play the audio chunks - produced by MPD. You can configure any number of audio output - devices, but there must be at least one. If none is - configured, MPD attempts to auto-detect. Usually, this works - quite well with ALSA, OSS and on Mac OS X. + 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> @@ -393,7 +428,7 @@ systemctl start mpd.socket</programlisting> a name registered in the PULSE server. </entry> </row> - <row> + <row id="ao_format"> <entry> <varname>format</varname> </entry> @@ -417,8 +452,6 @@ systemctl start mpd.socket</programlisting> (signed 8 bit integer samples), <varname>16</varname>, <varname>24</varname> (signed 24 bit integer samples padded to 32 bit), - <varname>24_3</varname> (signed 24 bit integer - samples, no padding, 3 bytes per sample), <varname>32</varname> (signed 32 bit integer samples), <varname>f</varname> (32 bit floating point, -1.0 to 1.0). @@ -432,8 +465,8 @@ systemctl start mpd.socket</programlisting> </entry> <entry> Specifies whether this audio output is enabled when - MPD is started. By default, all audio outputs are - enabled. + <application>MPD</application> is started. By + default, all audio outputs are enabled. </entry> </row> <row> @@ -442,10 +475,10 @@ systemctl start mpd.socket</programlisting> <parameter>yes|no</parameter> </entry> <entry> - If set to "no", then MPD will not send tags to this - output. This is only useful for output plugins that - can receive tags, for example the - <varname>httpd</varname> output plugin. + 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 <varname>httpd</varname> output plugin. </entry> </row> <row> @@ -454,10 +487,12 @@ systemctl start mpd.socket</programlisting> <parameter>yes|no</parameter> </entry> <entry> - If set to "yes", then MPD attempts to keep this audio - output always open. This may be useful for streaming - servers, when you don't want to disconnect all - listeners even when playback is accidentally stopped. + 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> @@ -469,8 +504,9 @@ systemctl start mpd.socket</programlisting> Specifies which mixer should be used for this audio output: the hardware mixer (available for ALSA, OSS and PulseAudio), the software mixer or no mixer - ("none"). By default, the hardware mixer is used for - devices which support it, and none for the others. + (<parameter>none</parameter>). By default, the + hardware mixer is used for devices which support it, + and none for the others. </entry> </row> <row> @@ -480,10 +516,11 @@ systemctl start mpd.socket</programlisting> </entry> <entry> Specifies how replay gain is applied. The default is - "software", which uses an internal software volume - control. "mixer" uses the configured (hardware) mixer - control. "none" disables replay gain on this audio - output. + <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> @@ -553,7 +590,8 @@ systemctl start mpd.socket</programlisting> <para> Playlist plugins are used to load remote playlists. This is - not related to MPD's playlist directory. + not related to <application>MPD</application>'s playlist + directory. </para> <para> @@ -609,17 +647,417 @@ systemctl start mpd.socket</programlisting> </tgroup> </informaltable> </section> + + <section> + <title>Audio Format Settings</title> + + <section> + <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 + <varname>audio_output</varname> 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> + The following resamplers are available (if enabled at + compile time): + </para> + + <itemizedlist> + <listitem> + <para> + <ulink + url="http://www.mega-nerd.com/SRC/"><application>libsamplerate</application></ulink> + a.k.a. Secret Rabbit Code (SRC). + </para> + </listitem> + + <listitem> + <para> + <ulink + url="http://sourceforge.net/projects/soxr/"><application>libsoxr</application></ulink>, + the SoX Resampler library + </para> + </listitem> + + <listitem> + <para> + internal: low CPU usage, but very poor quality. This is + the fallback if <application>MPD</application> was + compiled without an external resampler. + </para> + </listitem> + </itemizedlist> + + <para> + The setting <varname>samplerate_converter</varname> controls + how <application>MPD</application> shall resample music. + Possible values: + </para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + Value + </entry> + <entry> + Description + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + "<parameter>internal</parameter>" + </entry> + <entry> + The internal resampler. Low CPU usage, but very + poor quality. + </entry> + </row> + + <row> + <entry> + "<parameter>soxr very high</parameter>" + </entry> + <entry> + Use <application>libsoxr</application> with "Very + High Quality" setting. + </entry> + </row> + + <row> + <entry> + "<parameter>soxr high</parameter>" or + "<parameter>soxr</parameter>" + </entry> + <entry> + Use <application>libsoxr</application> with "High + Quality" setting. + </entry> + </row> + + <row> + <entry> + "<parameter>soxr medium</parameter>" + </entry> + <entry> + Use <application>libsoxr</application> with "Medium + Quality" setting. + </entry> + </row> + + <row> + <entry> + "<parameter>soxr low</parameter>" + </entry> + <entry> + Use <application>libsoxr</application> with "Low + Quality" setting. + </entry> + </row> + + <row> + <entry> + "<parameter>soxr quick</parameter>" + </entry> + <entry> + Use <application>libsoxr</application> with "Quick" + setting. + </entry> + </row> + + <row> + <entry> + "<parameter>Best Sinc Interpolator</parameter>" or + "<parameter>0</parameter>" + </entry> + <entry> + <application>libsamplerate</application>: 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> + <application>libsamplerate</application>: 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> + <application>libsamplerate</application>: Band + limited sinc interpolation, fastest, 97dB SNR, 80% + BW. + </entry> + </row> + + <row> + <entry> + "<parameter>ZOH Sinc Interpolator</parameter>" or + "<parameter>3</parameter>" + </entry> + <entry> + <application>libsamplerate</application>: 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> + <application>libsamplerate</application>: Linear + interpolator, very fast, poor quality. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + </section> + + <section> + <title>Other Settings</title> + + <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> + <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> </chapter> <chapter> - <title>Using MPD</title> + <title>Using <application>MPD</application></title> <section> <title>The client</title> <para> - After you have installed, configured and started MPD, you - choose a client to control the playback. + After you have installed, configured and started + <application>MPD</application>, you choose a client to control + the playback. </para> <para> @@ -630,7 +1068,8 @@ systemctl start mpd.socket</programlisting> </para> <para> - The <ulink url="http://www.musicpd.org/clients/">MPD + The <ulink + url="http://www.musicpd.org/clients/"><application>MPD</application> Wiki</ulink> contains an extensive list of clients to choose from. </para> @@ -641,10 +1080,11 @@ systemctl start mpd.socket</programlisting> <para> The "music directory" is where you store your music files. - MPD 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>: + <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> @@ -666,9 +1106,9 @@ systemctl start mpd.socket</programlisting> <para> The queue (sometimes called "current playlist") is a list of - songs to be played by MPD. To play a song, add it to the - queue and start playback. Most clients offer an interface to - edit the queue. + 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> </chapter> @@ -704,6 +1144,18 @@ systemctl start mpd.socket</programlisting> The path of the database file. </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> @@ -713,11 +1165,13 @@ systemctl start mpd.socket</programlisting> <title><varname>proxy</varname></title> <para> - Provides access to the database of another MPD 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 MPD instance. Only the file - server needs to update the database. + 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> @@ -734,7 +1188,8 @@ systemctl start mpd.socket</programlisting> <varname>host</varname> </entry> <entry> - The host name of the "master" MPD instance. + The host name of the "master" + <application>MPD</application> instance. </entry> </row> <row> @@ -742,69 +1197,81 @@ systemctl start mpd.socket</programlisting> <varname>port</varname> </entry> <entry> - The port number of the "master" MPD instance. + The port number of the "master" + <application>MPD</application> instance. </entry> </row> </tbody> </tgroup> </informaltable> </section> + + <section> + <title><varname>upnp</varname></title> + + <para> + Provides access to UPnP media servers. + </para> + </section> </section> <section> - <title>Input plugins</title> + <title>Storage plugins</title> <section> - <title><varname>curl</varname></title> + <title><varname>local</varname></title> <para> - Opens remote files or streams over HTTP. + 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> - <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> - </tbody> - </tgroup> - </informaltable> + <section> + <title><varname>smbclient</varname></title> + + <para> + Load music files from a SMB/CIFS server. It used used when + <varname>music_directory</varname> contains a + <parameter>smb://</parameter> URI, for example + "<parameter>smb://myfileserver/Music</parameter>". + </para> </section> <section> - <title><varname>file</varname></title> + <title><varname>nfs</varname></title> <para> - Opens local files. + Load music files from a NFS server. It used 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> </section> + </section> + + <section> + <title>Input plugins</title> <section> - <title><varname>mms</varname></title> + <title><varname>alsa</varname></title> <para> - Plays streams with the MMS protocol. + 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> @@ -833,9 +1300,72 @@ systemctl start mpd.socket</programlisting> <parameter>little_endian|big_endian</parameter> </entry> <entry> - If the CD drive does not specify a byte order, MPD - assumes it is the CPU's native byte order. This - setting allows overriding this. + 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. + </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> @@ -902,6 +1432,66 @@ systemctl start mpd.socket</programlisting> </tgroup> </informaltable> </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. + </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> <section> @@ -930,7 +1520,7 @@ systemctl start mpd.socket</programlisting> </entry> <entry> Decode the least significant bit first. Default is - "no". + <parameter>no</parameter>. </entry> </row> </tbody> @@ -1173,6 +1763,35 @@ systemctl start mpd.socket</programlisting> </section> <section> + <title><varname>shine</varname></title> + + <para> + Encodes into MP3 using the shine 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> @@ -1265,7 +1884,7 @@ systemctl start mpd.socket</programlisting> <section> <title>Output plugins</title> - <section> + <section id="alsa_output"> <title><varname>alsa</varname></title> <para> @@ -1340,10 +1959,11 @@ systemctl start mpd.socket</programlisting> <entry> If set to <parameter>no</parameter>, then <filename>libasound</filename> will not attempt to - resample, handing the responsibility over to MPD. - It is recommended to let MPD resample (with - libsamplerate), because ALSA is quite poor at doing - so. + 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> @@ -1389,6 +2009,63 @@ systemctl start mpd.socket</programlisting> </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> </section> <section> @@ -1396,7 +2073,8 @@ systemctl start mpd.socket</programlisting> <para> The <varname>ao</varname> plugin uses the portable - <filename>libao</filename> library. + <filename>libao</filename> library. Use only if there is no + native plugin for your operating system. </para> <informaltable> @@ -1479,15 +2157,19 @@ systemctl start mpd.socket</programlisting> <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 MPD is started, and - removed when MPD is stopped. The FIFO will be - created with the same user and group as MPD is + 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 "umask". If a FIFO - already exists at the specified path it will be - reused, and will not be removed when MPD is stopped. - You can use the "mkfifo" command to create this, and - then you may modify the permissions to your liking. + 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> @@ -1499,8 +2181,8 @@ systemctl start mpd.socket</programlisting> <title><varname>jack</varname></title> <para> - The <varname>jack</varname> plugin connects to a JACK - server. + The <varname>jack</varname> plugin connects to a + <application>JACK</application> server. </para> <informaltable> @@ -1518,8 +2200,8 @@ systemctl start mpd.socket</programlisting> <parameter>NAME</parameter> </entry> <entry> - The name of the JACK client. Defaults to "Music - Player Daemon". + The name of the <application>JACK</application> + client. Defaults to "Music Player Daemon". </entry> </row> <row> @@ -1528,7 +2210,8 @@ systemctl start mpd.socket</programlisting> <parameter>NAME</parameter> </entry> <entry> - Optional name of the JACK server. + Optional name of the <application>JACK</application> + server. </entry> </row> <row> @@ -1539,7 +2222,8 @@ systemctl start mpd.socket</programlisting> <entry> If set to <parameter>yes</parameter>, then <filename>libjack</filename> will automatically - launch the JACK daemon. Disabled by default. + launch the <application>JACK</application> daemon. + Disabled by default. </entry> </row> <row> @@ -1548,10 +2232,10 @@ systemctl start mpd.socket</programlisting> <parameter>A,B</parameter> </entry> <entry> - The names of the JACK source ports to be created. - By default, the ports "left" and "right" are - created. To use more ports, you have to tweak this - option. + 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> @@ -1560,7 +2244,8 @@ systemctl start mpd.socket</programlisting> <parameter>A,B</parameter> </entry> <entry> - The names of the JACK destination ports to connect to. + The names of the <application>JACK</application> + destination ports to connect to. </entry> </row> <row> @@ -1584,8 +2269,9 @@ systemctl start mpd.socket</programlisting> <para> The <varname>httpd</varname> plugin creates a HTTP server, - similar to ShoutCast / IceCast. HTTP streaming clients like - <filename>mplayer</filename> can connect to it. + similar to <application>ShoutCast</application> / + <application>IceCast</application>. HTTP streaming clients + like <application>mplayer</application> can connect to it. </para> <para> @@ -1711,6 +2397,13 @@ systemctl start mpd.socket</programlisting> 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> @@ -1727,22 +2420,65 @@ systemctl start mpd.socket</programlisting> </entry> <entry> Sets the path of the PCM device. If not specified, - then MPD will attempt to open - <filename>/dev/sound/dsp</filename> and + 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> <title><varname>openal</varname></title> <para> - The "OpenAL" plugin uses <filename>libopenal</filename>. - It is supported on many platforms. + The "OpenAL" plugin uses <filename>libopenal</filename>. It + is supported on many platforms. Use only if there is no + native plugin for your operating system. </para> <informaltable> @@ -1833,8 +2569,8 @@ systemctl start mpd.socket</programlisting> </entry> <entry> Sets the host name of the PulseAudio server. By - default, MPD connects to the local PulseAudio - server. + default, <application>MPD</application> connects to + the local PulseAudio server. </entry> </row> <row> @@ -1843,8 +2579,8 @@ systemctl start mpd.socket</programlisting> <parameter>NAME</parameter> </entry> <entry> - Specifies the name of the PulseAudio sink MPD should - play on. + Specifies the name of the PulseAudio sink + <application>MPD</application> should play on. </entry> </row> </tbody> @@ -1877,8 +2613,8 @@ systemctl start mpd.socket</programlisting> </entry> <entry> The host name of the RoarAudio server. If not - specified, then MPD will connect to the default - locations. + specified, then <application>MPD</application> will + connect to the default locations. </entry> </row> @@ -1888,8 +2624,9 @@ systemctl start mpd.socket</programlisting> <parameter>ROLE</parameter> </entry> <entry> - The "role" that MPD registers itself as in the - RoarAudio server. The default is "music". + The "role" that <application>MPD</application> + registers itself as in the RoarAudio server. The + default is "music". </entry> </row> </tbody> @@ -1902,8 +2639,8 @@ systemctl start mpd.socket</programlisting> <para> The <varname>recorder</varname> plugin writes the audio - played by MPD to a file. This may be useful for recording - radio streams. + played by <application>MPD</application> to a file. This + may be useful for recording radio streams. </para> <para> @@ -2031,7 +2768,8 @@ systemctl start mpd.socket</programlisting> <parameter>URI</parameter> </entry> <entry> - Mounts the MPD stream in the specified URI. + Mounts the <application>MPD</application> stream in + the specified URI. </entry> </row> <row> @@ -2097,7 +2835,7 @@ systemctl start mpd.socket</programlisting> </entry> <entry> Specifies whether the stream should be "public". - Default is "no". + Default is <parameter>no</parameter>. </entry> </row> <row> @@ -2214,6 +2952,49 @@ systemctl start mpd.socket</programlisting> </para> </section> + <section> + <title><varname>soundcloud</varname></title> + + <para> + Adds <ulink url="https://www.soundcloud.com/">Soundcloud</ulink> + playlists. SoundCloud playlists use the <filename>soundcloud://</filename> URI, + and with a number of arguments, you may load different playlists with + </para> + + <programlisting> +mpc load soundcloud://track/TRACK_ID +mpc load soundcloud://playlist/PLAYLIST_ID +mpc load soundcloud://user/USERNAME +mpc load soundcloud://search/SEARCH_QUERY +mpc load soundcloud://url/https://soundcloud.com/ARTIST/TRACK-NAME + </programlisting> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Setting</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <varname>apikey</varname> + <parameter>client_id</parameter> + </entry> + <entry> + User apikey/client_id can override the + <application>MPD</application> token provided by + SoundCloud. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + + </section> + </section> </chapter> </book> |