Configuration

## Before configuring

Music Player Daemon will look for configuration files in two default places. The system-wide configuration file can be found at `/etc/mpd.conf`. For local users, mpd will find it at `~/.mpdconf`. You can specify a configuration file with launching mpd by issuing `mpd /PATH/TO/FILE/my_config_file`. When launching a second command with a different configuration file, you can have multiple instances of mpd running. Make sure you have installed mpd. The default configuration file should be of great help.

If you would have any problems in starting mpd after configuration, this is most likely due to permission problems. Music Player Daemon will also perfectly run without any audio output set up.

The Manual maintained by the developers can be found here.

## Initial Configuration

After installation, MPD won't work until you tell it where the media files are. You do that by changing the `~/.mpdconf file` (for individual users) or `/etc/mpd.conf` for system-wide MPD. You may want to start with this:

```
port                    "6600"
music_directory         "~/music"
playlist_directory      "~/.mpd/playlists"
db_file                 "~/.mpd/mpd.db"
log_file                "~/.mpd/mpd.log"
```

You will need to create the directories if they do not already exist, e.g.:

```
mkdir -p ~/.mpd/playlists
```

For those using linux, if you have a samba server with all your music, say that its share name is `ALBUMS`, and you mount it locally as `/mnt/albums`. Then have your `db_file` option to point at such place, i.e. `/mnt/albums`. This way, when you don't have the `ALBUMS` share mounted on your computer you will have your mpddb file with `LOCAL` files (note that the mount destination should be `~/music` as well), whereas when you have it mounted you will have your mpddb file with all your music. Note that this will not require creating mpddb files each and every time (just need to run `/etc/init.d/mpd restart`)

#### Additional options

The default config file, which is distributed with mpd, should guide you through some additional options. You can adjust what someone connected through a client can do, the amount of messages put in the log file, et cetera.

#### Audio Outputs

mpd serves a wide variety to get the audio to multiple places in a multitude of ways. You can enable multiple outputs at the same time, for example in a multiple zone setup, or to stream the same output both to your amplifier, to some kinda service on your computer, and a stream to the internet. By default, every audio output you configured is enabled after you start, but inserting `enabled = "no"` leaves it off by default. You can later enable this output with a client.

Later versions of mpd may support Generic Decoders to decode files and streams.

### Local Playback

Linux comes with multiple, partially overlapping ways of dealing with audio. Most (all?) of these possibilities of outputting audio are supported by mpd. To get an overview of the several services and options there are, please read Linux Audio Explained.

#### Alsa

With Alsa you can send the audio output directly to your sound card. By default, this will be the device `hw:0,0`, which corresponds to one audio output on your sound card. A typical configuration is:

```
audio_output {
       type                    "alsa"
       name                    "My ALSA Device"
       device                  "hw:0,0"     # optional
       format                  "44100:16:2" # optional
}

```

If you want to plug your amplifier in another hole in your sound card, you will have to figure out how to address a specific physical connection on your sound card, or if you want to make use of the digital output, please see the specialized Alsa HOWTO.

#### PulseAudio

PulseAudio seems to become the default sound server in more and more linux distributions. It has some advantages over Alsa, such as the capability to stream the output to a server over the network, or volume control over the sources of the audio, and the ability to flexibly put an audio stream to another sink.

To make use of PulseAudio with mpd, you just need to add a new `audio_output` section with the type set to "pulse". You can also specify a server and sink parameter. A typical audio\_output section looks like this:

```
audio_output {
      type    "pulse"
      name    "My MPD PulseAudio Output"
      #server  "localhost"   # optional
      #sink    "alsa_output" # optional
}

```

For Distributions like Ubuntu 10.4, network access must be enabled; This can be done in the "System / Preferences / PulseAudio Preferences" menu after installing the paprefs package. See the PulseAudio HOWTO for more options and how to escape some errors.

#### JACK

##### libao / JACK

Check out the instructions at the alsa-project.org website on how to set up an ALSA device that forwards to JACK, then simply set this device as your output device in mpd.conf. Actually it seems to work only for the "ao" output type using the "alsa09" driver:

```
audio_output {
   type        "ao"
   driver      "alsa09"
   options     "dev=devicename" # replace devicename with that of your .asoundrc without the leading 'pcm.'
                                # (i.e. "dev=jackplug", when you set up pcm.jackplug in your .asoundrc)
   name        "Jack Output"
}

```

##### native / JACK

Here is how to use jack in more recent versions of mpd:

```
audio_output {
      type    "jack"
      name    "my jack device"
}

```

#### Enlightened Sound Daemon / EsounD / ESD

The Enlightened Sound Daemon, or ESD, intercepts and mixes digital
audio streams before passing them to `/dev/dsp`, thereby letting
multiple sound sources have simultaneous access to the sound hardware.
MPD relies on libao, the cross-platform audio library, and, happily for
ESD users, libao supports ESD.

Configuration to let libao, ESD, and MPD work together can be done
in either of two ways. The libao configuration file,
`/etc/libao.conf`, sets the default libao sound driver, using the syntax
`default_driver=x`, where x is an available driver. As of version 0.8.5,
the drivers are oss, esd, arts, alsa, alsa09, nas, irix, and
sun. Setting a system-wide libao default with default\_driver=esd should
do the trick. Alternatively, the MPD configuration file `/etc/mpd.conf`
can also specify the libao ESD driver as follows:
driver "esd". This overrides the libao default and works equally
well.

If you want to play your music on another host (perhaps becuase the computer with the speakers doesn't have enough hard drive space for your music), this seems to work:

```
audio_output {
      type      "ao"
      driver    "esd"
      options   "host=jurp5-desktop:16001"
      name      "esd"
}

```

###### ESD not working in Ubuntu

If the ESD output doesn't work in Ubuntu, you might try setting the following lines in /etc/esound/esd.conf:

```
auto_spawn=1
spawn_options=-noterminate -nobeeps -as 5
```

#### OSS

MPD includes support for OSSv3. OSS4 will work, except for the mixer.

```
audio_output {
      type      "ao"
      name      "My OSS Device"
      driver    "oss"
#        mixer_control  "mix" # optional, does not work with OSS4
}

```

##### FIFO Output

The fifo plugin writes raw PCM data to a FIFO (First In, First Out) file.  The data can be read by another program. Available from mpd 0.14. Example config:

```
audio_output {
      type                    "fifo"
      name                    "My FIFO"
      path                    "/tmp/mpd.fifo"
}

```

##### MacOS

To enable the audio output in MacOS, you need to define the type of the "audio\_output" as "osx". Example config:

```
audio_output {
      type            "osx"
      name            "My Mac Device"
      mixer_type      "software"
}

```

##### Windows

To enable the audio output in Windows, you need to define the type of the "audio\_output" as "winmm". Example config:

```
audio_output {
      type            "winmm"
      name            "My Windows Device"
}

```

In order to have multiple outputs you specify the 'device' option and use multiple audio\_output stanzas with unique names:

```
audio_output {
      type            "winmm"
      name            "Speakers"
      device          "Speakers (Realtek High Definition Audio)"
}

audio_output {
      type            "winmm"
      name            "SPDIF"
      device          "Realtek Digital Output (Realtek High Definition Audio)"
}

```

The properly formatted device name can be discovered in Windows 7 by opening the volume mixer and activating the 'device' drop-down. That list of devices contains exactly what needs to be specified in 'device'.

### Remote Playback

#### IceCast

MPD can stream to an IceCast (or other ShoutCast compatible) server. The following instructions assume that you have your IceCast server working and setup correctly. First grab the latest version of MPD from svn. (**Note:** version 0.11.5 and earlier, does not support streaming to a ShoutCast server! Check your install by running **`/usr/bin/mpd --version`** to see if **shout** is listed as an output format).

*Sidenote:* Since MPD 0.15 there is a built-in alternative to using IceCast. See below for more information.

##### Installation

You install it by using:

```
./autogen.sh --prefix=/path/to/dir
make
make install (this command may need root privileges depending on the prefix chosen)
```

Once you have mpd installed from svn, you just have to edit your MPD config file (the default is at /etc/mpd.conf), or in the prefix that you chose during installation. Make sure that you have something like the following section in your config file:

```
################# SHOUT STREAMING ########################
#
# (i.e. mpd is a icecast2 source)
#
audio_output {
      type              "shout"
      name              "my cool stream"
      host              "localhost"
      port              "8000"
      mount             "/mpd.ogg"
      password          "IceCast_mpd"
      quality           "5.0"

# end of audio_output
##########################################################
```

The lines above that start with a "#" are comment lines. The other lines have the following meaning:

* `type "shout"` indicates that this output is to be streamed to a ShoutCast server.
* `name "my cool stream"` sets the title of the stream, that your listeners will see.
* `host "localhost"` is the hostname of the Shoutcast server. If the server does not run on the same machine as MPD, change this accordingly.
* `port "8000"` is the port number on the server that MPD should connect to.
* `mount "/mpd.ogg"` is the path from the server root where your stream will be broadcast. In this example, the URL of the stream will be `http://localhost:8000/mpd.ogg`.
* `password "IceCast_mpd"` is the password used to broadcast on the server. Change this to the password required by your IceCast server.
* `quality "5.0"` **OR** `bitrate "64"` set the quality of your stream. You can (and must) only set one of them. `quality` is for variable bitrate Ogg/Vorbis, and `bitrate` for constant bitrate. Quality 3 is the default for oggenc and sounds little better than a mp3 at 128 kbits.
* `format "44100:16:1"` is the audio format of the stream. The first number is the sample rate in Hertz (Hz); 44100 Hz is equal to cd quality. The second number is the number of bits per sample; again 16 bits is the quality used on cd's. The third number is the number of channels; 1 channel is mono, 2 channels is stereo. So x:x:1 will mix a stereo channel down to a mono channel.
* `user "source"`, `description "here's my long description"` and `genre "jazz"` set some metadata that will be added to the headers of your stream and can be viewed by listeners.
* Add protocol parameter to change streaming protocol from icecast2 to "shoutcast" or "icecast1"

##### Supported Output Formats

Currently only OggVorbis is supported in mainline; MP3 is supported from version 0.14, with the optional parameter "encoding".

##### See also

Wikipage on Icecast2 configuration

Jonathan Fors' guide on MPD/Icecast streaming

FreeBSD MPD/Icecast setup

#### Built-in HTTP streaming

Since version 0.15 there is a built-in HTTP streaming deamon/server that comes with MPD. To activate this server simply set it as output device in `mpd.conf`:

```
audio_output {
    type           "httpd"
    name           "My HTTP Stream"
    encoder        "vorbis"        # optional, vorbis or lame
    port           "8000"
#    quality        "5.0"            # do not define if bitrate is defined
    bitrate        "128"            # do not define if quality is defined
    format         "44100:16:1"
}
```

Then to listen to this stream simply open the URL of your mpd server (along with the specified port) in your favorite music player. *Note:* You may have to specify the file format of the stream using an appropriate file extension in the URL. For example in my case, using Winamp 5.5, I had to use `http://192.168.178.5:8000/mpd.ogg` rather than `http://192.168.178.5:8000/`.

*Sidenote:* In my (subjective) experience it seems that the CPU usage is much lower when using the built-in http streaming server than when using IceCast. And since I use MPD 24/7 this actually makes a difference.

**Use mpd to connect to the stream**
You can also connect to this stream with mpd from another computer. See for a howto and some tricks here.

*Another sidenote:* After updating to MPD 0.16, my httpd output was broken until I added the following :
`bind_to_address "0.0.0.0"`