792 lines
22 KiB
XML
792 lines
22 KiB
XML
<?xml version='1.0' encoding="utf-8"?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"docbook/dtd/xml/4.2/docbookx.dtd">
|
|
<book>
|
|
<title>The Music Player Daemon - User's Manual</title>
|
|
|
|
<chapter>
|
|
<title>Introduction</title>
|
|
|
|
<para>
|
|
This document is work in progress. Most of it may be incomplete
|
|
yet. Please help!
|
|
</para>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Installation</title>
|
|
|
|
<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.
|
|
</para>
|
|
|
|
<section>
|
|
<title>Installing on Debian/Ubuntu</title>
|
|
|
|
<para>
|
|
Install the package <filename>mpd</filename>:
|
|
</para>
|
|
|
|
<programlisting>apt-get install mpd</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Compiling from source</title>
|
|
|
|
<para>
|
|
Download the source tarball from <ulink
|
|
url="http://mpd.wikia.com/wiki/Server">the MPD home
|
|
page</ulink> and unpack it:
|
|
</para>
|
|
|
|
<programlisting>tar xjf mpd-0.14.2.tar.bz
|
|
cd mpd-0.14.2</programlisting>
|
|
|
|
<para>
|
|
Make sure that all the required libraries and build tools are
|
|
installed. The <filename>INSTALL</filename> file has a list.
|
|
</para>
|
|
|
|
<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>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Configuration</title>
|
|
|
|
<section>
|
|
<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
|
|
MPD 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.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<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 "lastfm"
|
|
user "foo"
|
|
password "bar"
|
|
}
|
|
</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>
|
|
</section>
|
|
|
|
<section>
|
|
<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>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Configuring audio outputs</title>
|
|
|
|
<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.
|
|
</para>
|
|
|
|
<para>
|
|
To configure an audio output manually, add an
|
|
<varname>audio_output</varname> block 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>
|
|
<entry>
|
|
<varname>format</varname>
|
|
</entry>
|
|
<entry>
|
|
Always open the audio output with the specified audio
|
|
format (samplerate:bits:channels), regardless of the
|
|
format of the input file. This is optional for most
|
|
plugins.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<varname>enabled</varname>
|
|
<parameter>yes|no</parameter>
|
|
</entry>
|
|
<entry>
|
|
Specifies whether this audio output is enabled when
|
|
MPD is started. By default, all audio outputs are
|
|
enabled.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<varname>mixer_enabled</varname>
|
|
<parameter>yes|no</parameter>
|
|
</entry>
|
|
<entry>
|
|
Specifies whether the hardware mixer of this audio
|
|
output should be used. By default, all hardware
|
|
mixers are enabled if available.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
|
|
<section>
|
|
<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>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Plugin reference</title>
|
|
|
|
<section>
|
|
<title>Input plugins</title>
|
|
|
|
<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>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>file</varname></title>
|
|
|
|
<para>
|
|
Opens local files.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>lastfm</varname></title>
|
|
|
|
<para>
|
|
Plays last.fm radio. This plugin is experimental, and will
|
|
be superseded by a better solution in MPD 0.16.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>mms</varname></title>
|
|
|
|
<para>
|
|
Plays streams with the MMS protocol.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Output plugins</title>
|
|
|
|
<section>
|
|
<title><varname>alsa</varname></title>
|
|
|
|
<para>
|
|
The "Advanced Linux Sound Architecture" 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>use_mmap</varname>
|
|
<parameter>yes|no</parameter>
|
|
</entry>
|
|
<entry>
|
|
If set to <parameter>yes</parameter>, then
|
|
<filename>libasound</filename> will try to use
|
|
memory mapped I/O.
|
|
</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 MPD.
|
|
It is recommended to let MPD resample (with
|
|
libsamplerate), 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>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>ao</varname></title>
|
|
|
|
<para>
|
|
The <varname>ao</varname> plugin uses the portable
|
|
<filename>libao</filename> library.
|
|
</para>
|
|
</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>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>jack</varname></title>
|
|
|
|
<para>
|
|
The <varname>jack</varname> plugin connects to a JACK
|
|
server.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>mvp</varname></title>
|
|
|
|
<para>
|
|
The <varname>mvp</varname> plugin uses the proprietary
|
|
Hauppauge Media MVP interface. We do not know any user of
|
|
this plugin, and we do not know if it actually works.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>httpd</varname></title>
|
|
|
|
<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.
|
|
</para>
|
|
|
|
<para>
|
|
You must configure either <varname>quality</varname> or
|
|
<varname>bitrate</varname>. 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 (on all
|
|
interfaces).
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<varname>encoder</varname>
|
|
<parameter>NAME</parameter>
|
|
</entry>
|
|
<entry>
|
|
Chooses an encoder plugin,
|
|
e.g. <parameter>vorbis</parameter>.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<varname>quality</varname>
|
|
<parameter>Q</parameter>
|
|
</entry>
|
|
<entry>
|
|
Configures the encoder quality (for VBR) in the
|
|
range -1 .. 10.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<varname>bitrate</varname>
|
|
<parameter>BR</parameter>
|
|
</entry>
|
|
<entry>
|
|
Sets a constant encoder bit rate, in kilobit per
|
|
second.
|
|
</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>
|
|
<title><varname>oss</varname></title>
|
|
|
|
<para>
|
|
The "Open Sound System" plugin is supported on most Unix
|
|
platforms.
|
|
</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 MPD will attempt to open
|
|
<filename>/dev/sound/dsp</filename> and
|
|
<filename>/dev/dsp</filename>.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>osx</varname></title>
|
|
|
|
<para>
|
|
The "Mac OS X" plugin uses Apple's CoreAudio API.
|
|
</para>
|
|
</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>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>pulse</varname></title>
|
|
|
|
<para>
|
|
The <varname>pulse</varname> plugin connects to a PulseAudio
|
|
server.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>shout</varname></title>
|
|
|
|
<para>
|
|
The <varname>shout</varname> plugin connects to a ShoutCast
|
|
or IceCast server. It forwards tags to this server.
|
|
</para>
|
|
</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>
|
|
</chapter>
|
|
</book>
|