User's Manual
#############

Introduction
************

Music Player Daemon (:program:`MPD`) is a flexible, powerful, server-side application for playing music. Through plugins and libraries it can play a variety of sound files while being controlled by its network protocol.

This document is work in progress. Most of it may be incomplete yet. Please help!

Installation
************

Installing on Debian/Ubuntu
---------------------------

Install the package :file:`mpd` via :program:`apt`:

.. code-block:: none

    apt install mpd

When installed this way, :program:`MPD` by default looks for music in :file:`/var/lib/mpd/music/`; this may not be correct. Look at your :file:`/etc/mpd.conf` file... 

.. note::

   Debian and Ubuntu are infamous for shipping heavily outdated
   software.  The :program:`MPD` version in their respective stable
   releases are usually too old to be supported by this project.
   Ironically, the :program:`MPD` version in Debian "*unstable*" is
   more stable than the version in Debian "*stable*".


Installing on Android
---------------------

An experimental Android build is available on Google Play. After installing and launching it, :program:`MPD` will scan the music in your Music directory and you can control it as usual with a :program:`MPD` client.

If you need to tweak the configuration, you can create a file called :file:`mpd.conf` on the data partition (the directory which is returned by Android's :dfn:`getExternalStorageDirectory()` API function). 

ALSA is not available on Android; only the :ref:`OpenSL ES
<sles_output>` output plugin can be used for local playback.

Compiling from source
---------------------

Download the source tarball from the `MPD home page <https://musicpd.org>`_ and unpack it:

.. code-block:: none

    tar xf mpd-version.tar.xz
    cd mpd-version

In any case, you need:

* a C++14 compiler (e.g. gcc 6.0 or clang 3.9)
* `Meson 0.47.2 <http://mesonbuild.com/>`__ and `Ninja
  <https://ninja-build.org/>`__
* Boost 1.58
* pkg-config 

Each plugin usually needs a codec library, which you also need to
install. Check the :doc:`plugins` for details about required libraries

For example, the following installs a fairly complete list of build dependencies on Debian Jessie:

.. code-block:: none

    apt install g++ \
      libpcre3-dev \
      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 libtwolame-dev libshine-dev \
      libsamplerate0-dev libsoxr-dev \
      libbz2-dev libcdio-paranoia-dev libiso9660-dev libmms-dev \
      libzzip-dev \
      libcurl4-gnutls-dev libyajl-dev libexpat-dev \
      libasound2-dev libao-dev libjack-jackd2-dev libopenal-dev \
      libpulse-dev libshout3-dev \
      libsndio-dev \
      libmpdclient-dev \
      libnfs-dev libsmbclient-dev \
      libupnp-dev \
      libavahi-client-dev \
      libsqlite3-dev \
      libsystemd-dev \
      libgtest-dev \
      libboost-dev \
      libicu-dev
      

Now configure the source tree:

.. code-block:: none

 meson . output/release --buildtype=debugoptimized -Db_ndebug=true

The following command shows a list of compile-time options:

.. code-block:: none

 meson configure output/release

When everything is ready and configured, compile:

.. code-block:: none

 ninja -C output/release

And install:

.. code-block:: none

 ninja -C output/release install

Compiling for Windows
---------------------

Even though it does not "feel" like a Windows application, :program:`MPD` works well under Windows. Its build process follows the "Linux style" and may seem awkward for Windows people (who are not used to compiling their software, anyway).

Basically, there are two ways to compile :program:`MPD` for Windows:

* Build as described above: with :program:`meson` and
  :program:`ninja`.  To cross-compile from Linux, you need `a Meson
  cross file <https://mesonbuild.com/Cross-compilation.html>`__.

  The remaining difficulty is installing all the external libraries.
  And :program:`MPD` usually needs many, making this method cumbersome
  for the casual user.

* Build on Linux for Windows using :program:`MPD`'s library build script. 

This section is about the latter.

Just like with the native build, unpack the :program:`MPD` source
tarball and change into the directory.  Then, instead of
:program:`meson`, type:

.. code-block:: none

 mkdir -p output/win64
 cd output/win64
 ../../win32/build.py --64

This downloads various library sources, and then configures and builds
:program:`MPD` (for x64; to build a 32 bit binary, pass
:code:`--32`). The resulting EXE files is linked statically, i.e. it
contains all the libraries already and you do not need carry DLLs
around. It is large, but easy to use. If you wish to have a small
mpd.exe with DLLs, you need to compile manually, without the
:file:`build.py` script.

Compiling for Android
---------------------

:program:`MPD` can be compiled as an Android app. It can be installed easily with Google Play, but if you want to build it from source, follow this section.

You need:

* Android SDK
* Android NDK 

Just like with the native build, unpack the :program:`MPD` source
tarball and change into the directory.  Then, instead of
:program:`meson`, type:

.. code-block:: none

 mkdir -p output/android
 cd output/android
 ../../android/build.py SDK_PATH NDK_PATH ABI
 meson configure -Dandroid_debug_keystore=$HOME/.android/debug.keystore
 ninja android/apk/mpd-debug.apk

:envvar:`SDK_PATH` is the absolute path where you installed the
Android SDK; :envvar:`NDK_PATH` is the Android NDK installation path;
ABI is the Android ABI to be built, e.g. ":code:`arm64-v8a`".

This downloads various library sources, and then configures and builds :program:`MPD`. 

systemd socket activation
-------------------------

Using systemd, you can launch :program:`MPD` on demand when the first client attempts to connect.

:program:`MPD` comes with two systemd unit files: a "service" unit and
a "socket" unit.  These will be installed to the directory specified
with :code:`-Dsystemd_system_unit_dir=...`,
e.g. :file:`/lib/systemd/system`.

To enable socket activation, type:

.. code-block:: none

    systemctl enable mpd.socket
    systemctl start mpd.socket

In this configuration, :program:`MPD` will ignore the :ref:`listener
settings <listeners>` (``bind_to_address`` and ``port``).

systemd user unit
-----------------

You can launch :program:`MPD` as a systemd user unit.  These will be
installed to the directory specified with
:code:`-Dsystemd_user_unit_dir=...`,
e.g. :file:`/usr/lib/systemd/user` or
:file:`$HOME/.local/share/systemd/user`.

Once the user unit is installed, you can start and stop :program:`MPD` like any other service:

.. code-block:: none

    systemctl --user start mpd

To auto-start :program:`MPD` upon login, type:

.. code-block:: none

    systemctl --user enable mpd

Configuration
*************

The Configuration File
----------------------

:program:`MPD` reads its configuration from a text file. Usually, that is :file:`/etc/mpd.conf`, unless a different path is specified on the command line. If you run :program:`MPD` as a user daemon (and not as a system daemon), the configuration is read from :file:`$XDG_CONFIG_HOME/mpd/mpd.conf` (usually :file:`~/.config/mpd/mpd.conf`). On Android, :file:`mpd.conf` will be loaded from the top-level directory of the data partition.

Each line in the configuration file contains a setting name and its value, e.g.:

:code:`connection_timeout "5"`

For settings which specify a filesystem path, the tilde is expanded:

:code:`music_directory "~/Music"`

Some of the settings are grouped in blocks with curly braces, e.g. per-plugin settings:

.. code-block:: none

    audio_output {
        type "alsa"
        name "My ALSA output"
        device "iec958:CARD=Intel,DEV=0"
        mixer_control "PCM"
    }

The :code:`include` directive can be used to include settings from
another file; the given file name is relative to the current file:

.. code-block:: none

  include "other.conf"

Configuring the music directory
-------------------------------

When you play local files, you should organize them within a directory called the "music directory". This is configured in :program:`MPD` with the music_directory setting.

By default, :program:`MPD` follows symbolic links in the music directory. This behavior can be switched off: :code:`follow_outside_symlinks` controls whether :program:`MPD` follows links pointing to files outside of the music directory, and :code:`follow_inside_symlinks` lets you disable symlinks to files inside the music directory.

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 ":file:`myfileserver`" on the share called "Music",
configure the music directory ":file:`smb://myfileserver/Music`". For
a recipe, read the Satellite :program:`MPD` section :ref:`satellite`.

You can also use multiple storage plugins to assemble a virtual music directory consisting of multiple storages. 

Configuring database plugins
----------------------------

If a music directory is configured, one database plugin is used. To
configure this plugin, add a :code:`database` block to
:file:`mpd.conf`:

.. code-block:: none

    database {
        plugin "simple"
        path "/var/lib/mpd/db"
    }
    
More information can be found in the :ref:`database_plugins`
reference.

Configuring neighbor plugins
----------------------------

All neighbor plugins are disabled by default to avoid unwanted
overhead. To enable (and configure) a plugin, add a :code:`neighbor`
block to :file:`mpd.conf`:

.. code-block:: none

    neighbors {
        plugin "smbclient"
    }
      
More information can be found in the :ref:`neighbor_plugin` reference.

Configuring input plugins
-------------------------

To configure an input plugin, add an :code:`input` block to
:file:`mpd.conf`:

.. code-block:: none

    input {
        plugin "curl"
        proxy "proxy.local"
    }
      

The following table lists the input options valid for all plugins:

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Name
     - Description
   * - **plugin**
     - The name of the plugin
   * - **enabled yes|no**
     - Allows you to disable a input plugin without recompiling. By default, all plugins are enabled.

More information can be found in the :ref:`input_plugins` reference.

Configuring decoder plugins
---------------------------

Most decoder plugins do not need any special configuration. To
configure a decoder, add a :code:`decoder` block to :file:`mpd.conf`:

.. code-block:: none

    decoder {
        plugin "wildmidi"
        config_file "/etc/timidity/timidity.cfg"
    }
      
The following table lists the decoder options valid for all plugins:

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Name
     - Description
   * - **plugin**
     - The name of the plugin
   * - **enabled yes|no**
     - Allows you to disable a decoder plugin without recompiling. By default, all plugins are enabled.

More information can be found in the :ref:`decoder_plugins` reference.

Configuring encoder plugins
---------------------------

Encoders are used by some of the output plugins (such as shout). The encoder settings are included in the audio_output section.

More information can be found in the :ref:`encoder_plugins` reference.

Configuring audio outputs
-------------------------

Audio outputs are devices which actually play the audio chunks produced by :program:`MPD`. You can configure any number of audio output devices, but there must be at least one. If none is configured, :program:`MPD` attempts to auto-detect. Usually, this works quite well with ALSA, OSS and on Mac OS X.

To configure an audio output manually, add one or more
:code:`audio_output` blocks to :file:`mpd.conf`:

.. code-block:: none

    audio_output {
        type "alsa"
        name "my ALSA device"
        device "hw:0"
    }

The following table lists the audio_output options valid for all plugins:


.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Name
     - Description
   * - **type**
     - The name of the plugin
   * - **name**
     - 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.
   * - **format**
     -  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.

        Any of the three attributes may be an asterisk to specify that this attribute should not be enforced, example: 48000:16:*. *:*:* is equal to not having a format specification.

        The following values are valid for bits: 8 (signed 8 bit integer samples), 16, 24 (signed 24 bit integer samples padded to 32 bit), 32 (signed 32 bit integer samples), f (32 bit floating point, -1.0 to 1.0), "dsd" means DSD (Direct Stream Digital). For DSD, there are special cases such as "dsd64", which allows you to omit the sample rate (e.g. dsd512:2 for stereo DSD512, i.e. 22.5792 MHz).

        The sample rate is special for DSD: :program:`MPD` counts the number of bytes, not bits. Thus, a DSD "bit" rate of 22.5792 MHz (DSD512) is 2822400 from :program:`MPD`'s point of view (44100*512/8).
   * - **enabed yes|no**
     - Specifies whether this audio output is enabled when :program:`MPD` is started. By default, all audio outputs are enabled. This is just the default setting when there is no state file; with a state file, the previous state is restored.
   * - **tags yes|no**
     - If set to no, then :program:`MPD` will not send tags to this output. This is only useful for output plugins that can receive tags, for example the httpd output plugin.
   * - **always_on yes|no**
     - If set to yes, then :program:`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.
   * - **mixer_type hardware|software|null|none**
     - Specifies which mixer should be used for this audio output: the
       hardware mixer (available for ALSA :ref:`alsa_plugin`, OSS
       :ref:`oss_plugin` and PulseAudio :ref:`pulse_plugin`), the
       software mixer, the ":samp:`null`" mixer (allows setting the
       volume, but with no effect; this can be used as a trick to
       implement an external mixer :ref:`external_mixer`) or no mixer
       (:samp:`none`). By default, the hardware mixer is used for
       devices which support it, and none for the others.

Configuring filters
-------------------

Filters are plugins which modify an audio stream.

To configure a filter, add a :code:`filter` block to :file:`mpd.conf`:

.. code-block:: none

    filter {
        plugin "volume"
        name "software volume"
    }

The following table lists the filter options valid for all plugins:

.. list-table::
   :widths: 20 80
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          