mpd/doc/user.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>

    <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.
    </para>

    <para>
      It has been written with minimal resource usage and stability in
      mind!  Infact, it runs fine on a Pentium 75, allowing you to use
      your cheap old PC to create a stereo system!
    </para>

    <para>
      MPD supports also Gapless playback, buffered audio output, and
      crossfading!
    </para>

    <para>
      The separate client and server design allows users to choose a
      user interface that best suites their tastes independently of
      the underlying daemon, which actually plays music!
    </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> 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...
      </para>
    </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-version.tar.bz
cd mpd-version</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_type</varname>
                <parameter>hardware|software|none</parameter>
              </entry>
              <entry>
                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.
              </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>

        <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>
        <title><varname>pulse</varname></title>

        <para>
          The <varname>pulse</varname> plugin connects to a PulseAudio
          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>
                  Sets the host name of the PulseAudio server.  By
                  default, MPD connects to the local PulseAudio
                  server.
                </entry>
              </row>
              <row>
                <entry>
                  <varname>sink</varname>
                  <parameter>NAME</parameter>
                </entry>
                <entry>
                  Specifies the name of the PulseAudio sink MPD should
                  play on.
                </entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </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>

        <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 Shoutcast/Icecast 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>mount</varname>
                  <parameter>URI</parameter>
                </entry>
                <entry>
                  Mounts the MPD 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>public</varname>
                  <parameter>yes|no</parameter>
                </entry>
                <entry>
                  Specifies whether the stream should be "public".
                  Default is "no".
                </entry>
              </row>
              <row>
                <entry>
                  <varname>encoder</varname>
                  <parameter>PLUGIN</parameter>
                </entry>
                <entry>
                  Sets the name of the encoder plugin.  Default is
                  "vorbis".  "vorbis" and "lame" are valid encoder
                  plugins (provided that you enabled them at compile
                  time).
                </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>
  </chapter>
</book>