From Gentoo Wiki
Jump to: navigation, search

MPD (Music Player Daemon) is a flexible, 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. For more information, read about what mpd is and is not.


Install media-sound/mpd. Following minimal USE flags set is needed to be able to play most known audio file formats, and to listen to audio streams. For more features review the USE flags.

USE flag (what is that?) Default Recommended Description
adplug No Enable the AdPlug decoder plugin
alsa Yes Add support for media-libs/alsa-lib (Advanced Linux Sound Architecture)
ao No Use libao audio output library for sound playback
audiofile No Add support for libaudiofile where applicable
bzip2 Yes Use the bzlib compression library
cdio No Use libcdio for ISO9660 parsing support
curl Yes Yes Support for web stream listening
debug No Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see Backtraces
expat No Enable the use of dev-libs/expat for XML parsing
faad No Use external faad library for AAC decoding
ffmpeg Yes Enable ffmpeg/libav-based audio/video codec support
fifo Yes Support writing audio to a FIFO
flac No Yes Add support for FLAC: Free Lossless Audio Codec
fluidsynth No Enables Fluidsynth MIDI software synthesis
glib No Enable GLib usage
gme No Enables support for media-libs/game-music-emu for playing various video game music formats.
icu No Enable ICU (Internationalization Components for Unicode) support, using dev-libs/icu
id3tag Yes Yes Support for ID3 tags
inotify Yes Use the Linux kernel inotify subsystem to notice changes to mpd music library
jack No Add support for the JACK Audio Connection Kit
lame No Support for MP3 streaming via Icecast2
libav No Prefer libav over ffmpeg whenever both are supported
libmpdclient No Enable support for remote mpd databases
libsamplerate No Build with support for converting sample rates using libsamplerate
libsoxr No Enable the libsoxr resampler
mad Yes Yes Add support for mad (high-quality mp3 decoder library and cli frontend)
mikmod No Add libmikmod support to allow playing of SoundTracker-style music files
mms No Support for Microsoft Media Server (MMS) streams
modplug No Add libmodplug support for playing SoundTracker-style music files

USE flag (what is that?) Default Recommended Description
mpg123 No Enable support for mp3 decoding over media-sound/mpg123
musepack No Enable support for the musepack audio codec
network No Enables network streaming support
nfs No Enable support for the Network File System
ogg No Yes Add support for the Ogg container format (commonly used by Vorbis, Theora and flac)
openal No Add support for the Open Audio Library
opus No Enable Opus codec support
oss No Add support for OSS (Open Sound System)
pipe No Support writing audio to a pipe
pulseaudio No Add support for PulseAudio sound server
recorder No Enables output plugin for recording radio streams
samba No Add support for SAMBA (Windows File and Printer sharing)
sid No Build with SID (Commodore 64 Audio) support
sndfile No Add support for libsndfile
soundcloud No Build plugin to access soundcloud
sqlite No Add support for sqlite - embedded sql database
systemd No Enable support for systemd socket activation
tcpd No Add support for TCP wrappers
twolame No Support twolame MPEG-2 encoding
unicode Yes Add support for Unicode
upnp No Enable UPnP port mapping support
vorbis No Yes Add support for the OggVorbis audio codec
wavpack No Yes Add support for wavpack audio compression tools
wildmidi No Enable MIDI support via wildmidi
zeroconf No Support for DNS Service Discovery (DNS-SD)
zip No Support for ZIP files

Note that a number of these flags are added by the desktop profile.

root #emerge --ask mpd


After finished installation MPD should be working with the Gentoo shipped default configuration.

Basic configuration

Below an example of a simple configuration:

FILE /etc/mpd.conf
music_directory      "/var/lib/mpd/music"
playlist_directory   "/var/lib/mpd/playlists"
db_file              "/var/lib/mpd/database"
log_file             "/var/lib/mpd/log"
state_file           "/var/lib/mpd/state"
user                 "mpd"
bind_to_address      "localhost"
bind_to_address      "/var/lib/mpd/socket"
input {
        plugin "curl"

At this point MPD should be able to run as a system daemon with its own user called mpd, which is the default setting of MPD.


You can now start MPD:

root #rc-service mpd start

To start MPD at boot time, add it your default runlevel:

root #rc-update add mpd default

PulseAudio (optional)

If MPD was build with PulseAudio support (pulseaudio USE flag), add a dedicated audio_output section to your /etc/mpd.conf:

FILE /etc/mpd.conf
audio_output {
        type            "pulse"
        name            "Pulse Output"
        mixer_control   "Master"
It may be a good practice to run both PulseAudio and MPD under X11 user instead.

Built-in HTTP streaming server (optional)

If MPD was build with network USE flag, add a dedicated audio_output section to your /etc/mpd.conf:

FILE /etc/mpd.conf
audio_output {    
        type            "httpd"
        name            "HTTP Stream"
        encoder         "vorbis"                # optional, vorbis(OGG) or lame(MP3)
        port            "8000"
        bitrate         "192"                   # do not define if quality is defined      
        format          "44100:16:1"
bind_to_address ""

Replace localhost with or a specific interface IP. Bind to address means here: stream on all local found IP interfaces. You could change it to a specific interface IP address like f.e. then the streaming server is bound to that interface IP only.

Some players require to specify the file format in the URL to be able to connect to the stream. Example:

Running as a specific user (optional)

Sometimes it may be handy to run MPD as a specific user.

Start with copying /etc/mpd.conf to ~/.mpdconf. There are some changes that you will have to change in order to run MPD as a user, most importantly user and group, also make sure the various path settings are correct:

FILE ~/.mpdconfuser definition
user    "YOUR_USER"
group   "YOUR_USER"

Make sure your user has read access to the directory you specify in music_directory.

If your cron program supports @reboot you can create a cronjob that has /usr/bin/mpd start at boot in place of the init script.

Bluetooth Headset (optional)

This ALSA (non-PulseAudio) setup currently only works with BlueZ 4.

Setup your Bluetooth headset first, according to this wiki. Put a user level ~/.asoundrc file in MPD's $HOME directory, which is /var/lib/mpd by default. The following example creates an extra "Bluetooth" slider in any mixer application, and enables MPD to control the volume of the headset:

FILE /var/lib/mpd/.asoundrc
# Change device to the MAC address of your headset
pcm.btheadset {
   type plug
   slave {
      pcm {
         type bluetooth
         device "XX:XX:XX:XX:XX:XX"
         profile "auto"
   hint {
      show on
      description "Bluetooth Headset"
ctl.btheadset {
   type bluetooth
pcm.btheadset_softvol {
   type softvol
   slave.pcm "btheadset" "Bluetooth"
   control.card 0
# Using bluetooth as default:
#pcm.!default {
#   type plug
#   slave.pcm "btheadset_softvol"

To be able to switch between the Bluetooth headset and the default sound card, add these lines to the audio_output section in /etc/mpd.conf:

FILE /etc/mpd.conf
audio_output {
        type            "alsa"
        name            "My ALSA Device"
audio_output {
        type            "alsa"
        name            "ALSA Bluetooth Headset"
        device          "btheadset_softvol"
        mixer_type      "software"

MPD might go crazy when switching output _while_ playing, and fill its log (if so, pause before switching).



Graphical (GTK+)

Graphical (Qt)


Scrobblers are clients that submit to Audioscrobbler-compatible services (eg. or


For general troubleshooting refer to the excellent MPD troubleshooting section.

External resources