diff options
Diffstat (limited to 'doc/user.xml')
| -rw-r--r-- | doc/user.xml | 545 |
1 files changed, 489 insertions, 56 deletions
diff --git a/doc/user.xml b/doc/user.xml index 6357267e4..d70c9ead1 100644 --- a/doc/user.xml +++ b/doc/user.xml @@ -80,6 +80,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> @@ -106,29 +136,18 @@ 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>: + attempts to connect. </para> - <programlisting>[Socket] -ListenStream=/run/mpd.socket -ListenStream=6600 -[Install] -WantedBy=sockets.target</programlisting> - <para> - Now create <filename>mpd.service</filename>: + MPD comes with two <filename>systemd</filename> unit files: a + "service" unit and a "socket" unit. These will only be + installed when MPD 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 @@ -162,6 +181,14 @@ systemctl start mpd.socket</programlisting> 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> <section> @@ -393,7 +420,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 +444,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). @@ -609,6 +634,202 @@ 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 + MPD 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 MPD's CPU usage. + Since MPD comes with high quality defaults, it may appear + that MPD 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/">libsamplerate</ulink> + a.k.a. Secret Rabbit Code (SRC). + </para> + </listitem> + + <listitem> + <para> + <ulink + url="http://sourceforge.net/projects/soxr/">libsoxr</ulink>, + the SoX Resampler library + </para> + </listitem> + + <listitem> + <para> + internal: low CPU usage, but very poor quality. This is + the fallback if MPD was compiled without an external + resampler. + </para> + </listitem> + </itemizedlist> + + <para> + The setting <varname>samplerate_converter</varname> controls + how MPD 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 libsoxr with "Very High Quality" setting. + </entry> + </row> + + <row> + <entry> + "<parameter>soxr high</parameter>" or + "<parameter>soxr</parameter>" + </entry> + <entry> + Use libsoxr with "High Quality" setting. + </entry> + </row> + + <row> + <entry> + "<parameter>soxr medium</parameter>" + </entry> + <entry> + Use libsoxr with "Medium Quality" setting. + </entry> + </row> + + <row> + <entry> + "<parameter>soxr low</parameter>" + </entry> + <entry> + Use libsoxr with "Low Quality" setting. + </entry> + </row> + + <row> + <entry> + "<parameter>soxr quick</parameter>" + </entry> + <entry> + Use libsoxr with "Quick" setting. + </entry> + </row> + + <row> + <entry> + "<parameter>Best Sinc Interpolator</parameter>" or + "<parameter>0</parameter>" + </entry> + <entry> + libsamplerate: 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> + libsamplerate: 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> + libsamplerate: Band limited sinc interpolation, + fastest, 97dB SNR, 80% BW. + </entry> + </row> + + <row> + <entry> + "<parameter>ZOH Sinc Interpolator</parameter>" or + "<parameter>3</parameter>" + </entry> + <entry> + libsamplerate: 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> + libsamplerate: Linear interpolator, very fast, poor + quality. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + </section> </chapter> <chapter> @@ -704,6 +925,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> @@ -749,62 +982,71 @@ systemctl start mpd.socket</programlisting> </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 MPD 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 MPD 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> @@ -844,6 +1086,68 @@ systemctl start mpd.socket</programlisting> </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> + </tgroup> + </informaltable> + </section> + + <section> <title><varname>despotify</varname></title> <para> @@ -902,6 +1206,65 @@ 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 MPD 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 MPD 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 MPD 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> @@ -1173,6 +1536,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> @@ -2214,6 +2606,47 @@ 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 MPD token provided by SoundCloud. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + + </section> + </section> </chapter> </book> |