aboutsummaryrefslogtreecommitdiffstats
path: root/doc/user.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user.xml')
-rw-r--r--doc/user.xml545
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>