From Gentoo Wiki
Jump to:navigation Jump to: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 a network protocol.


USE flags

USE flags for media-sound/mpd The Music Player Daemon (mpd)

alsa Add support for media-libs/alsa-lib (Advanced Linux Sound Architecture)
ao Use libao audio output library for sound playback
audiofile Add support for libaudiofile where applicable
bzip2 Enable bzip2 compression support
cdio Use libcdio for ISO9660 parsing support
chromaprint Enable ChromaPrint / AcoustID support
cue Enable CUE sheet support
curl Support for web stream listening
dbus Enable dbus support for anything that needs it (gpsd, gnomemeeting, etc)
doc Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
eventfd Use the eventfd function in MPD's event loop
expat Enable the use of dev-libs/expat for XML parsing
faad Use external faad library for AAC decoding
ffmpeg Enable ffmpeg/libav-based audio/video codec support
fifo Support writing audio to a FIFO
flac Add support for FLAC: Free Lossless Audio Codec
fluidsynth Enables Fluidsynth MIDI software synthesis (discouraged)
gme Enables support for media-libs/game-music-emu for playing various video game music formats.
icu Enable ICU (Internationalization Components for Unicode) support, using dev-libs/icu
id3tag Support for ID3 tags
inotify Use the Linux kernel inotify subsystem to notice changes to mpd music library
jack Add support for the JACK Audio Connection Kit
lame Support for MP3 streaming via Icecast2
libmpdclient Enable support for remote mpd databases
libsamplerate Build with support for converting sample rates using libsamplerate
libsoxr Enable the libsoxr resampler
mad Add support for mad (high-quality mp3 decoder library and cli frontend)
mikmod Add libmikmod support to allow playing of SoundTracker-style music files
mms Support for Microsoft Media Server (MMS) streams
modplug Add libmodplug support for playing SoundTracker-style music files
mpg123 Enable support for mp3 decoding over media-sound/mpg123
musepack Enable support for the musepack audio codec
network Enables network streaming support
nfs Enable support for the Network File System
openal Add support for the Open Audio Library
openmpt OpenMPT decoder plugin
opus Enable Opus audio codec support
oss Add support for OSS (Open Sound System)
pipe Support writing audio to a pipe
pipewire PipeWire support
pulseaudio Add sound server support via media-libs/libpulse (may be PulseAudio or PipeWire)
qobuz Build plugin to access qobuz
recorder Enables output plugin for recording radio streams
samba Add support for SAMBA (Windows File and Printer sharing)
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
sid Enable SID (Commodore 64 audio) file support
signalfd Use the signalfd function in MPD's event loop
snapcast Snapcast audio plugin
sndfile Add support for libsndfile
sndio Enable support for the media-sound/sndio backend
soundcloud Build plugin to access soundcloud
sqlite Add support for sqlite - embedded sql database
systemd Enable support for systemd socket activation
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
twolame Support twolame MPEG-2 encoding
udisks Enable storage management support (automounting, volume monitoring, etc)
upnp Enable UPnP port mapping support
vorbis Add support for the OggVorbis audio codec
wavpack Add support for wavpack audio compression tools
webdav Enable using music from a WebDAV share
wildmidi Enable MIDI support via wildmidi
zeroconf Support for DNS Service Discovery (DNS-SD)
zip Enable support for ZIP archives
zlib Add support for zlib compression

A number of these flags are set by the desktop profile.


root #emerge --ask media-sound/mpd


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

A list of supported plugins/features of your MPD can be obtained by issuing:

user $mpd --version

MPD can be configured in a system-wide or per-user fashion. The configuration style choice depends on the intended usage.

System-wide 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"

audio_output {
        type            "alsa"
        name            "default"
        mixer_type      "software"

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.

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"
If running pipewire with libpulse, this option will allow a system level MPD daemon to access the user level pipewire server if one of the tcp options is enabled in /etc/pipewire/pipewire-pulse.conf. See "Adding multi user support" in the Pipewire page.
It may be a good practice to run both PulseAudio and MPD under X11 user instead.

Pipewire (optional)

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

FILE /etc/mpd.conf
audio_output {
        type            "pipewire"
        name            "Pipewire Output"
Pipewire will not let an MPD system daemon access a user level pipewire socket, so this option should only be used if running MPD as a user level daemon.

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 e.g. 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:

Bluetooth headset (optional)

Setup a Bluetooth headset first, according to the Bluetooth headset article.

ALSA (non-PulseAudio) setup with BlueZ 5

Put a user level ~/.asoundrc file in MPD's $HOME directory, which is /var/lib/mpd by default. MPD will be able to control the volume of the headset.

FILE /var/lib/mpd/.asoundrc
# Specify the parameters of the Bluetooth connection
defaults.bluealsa {
     interface "hci0"            # host Bluetooth adapter
     device "XX:XX:XX:XX:XX:XX"  # Bluetooth headset MAC address
     profile "a2dp"

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          "bluealsa"
        mixer_type    "software"

MPD might crash when switching output _while_ playing (if so, pause before switching).

If you experience some issues while trying to play AAC or other files, like:

user $mpd --no-daemon --stderr
alsa_output: Failed to open "My ALSA Device" [alsa]: Error opening ALSA device "bluealsa" (snd_pcm_hw_params): Invalid argument

Then add this line to your audio_output:

FILE /etc/mpd.conf
format          "44100:16:2"

FIFO (optional)

The FIFO output setup for the visualiser plugin which in the media-sound/ncmpcpp client. Following additional settings enable the FIFO functionality:

FILE /etc/mpd.conf
audio_output {
        type  "fifo"
        name  "mpdFIFO"
        path  "/tmp/mpd.fifo"
        enabled  "yes"
        format  "44100:16:2"

The name and path variables values can be set to reflect own needs.



To start MPD:

root #rc-service mpd start

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

root #rc-update add mpd default

To start MPD immediately:

root #systemctl start mpd

To start MPD at boot time:

root #systemctl enable mpd

Per-user configuration

It may be handy to run MPD configured for a specific user.

Basic configuration

Start with copying /etc/mpd.conf to $XDG_CONFIG_HOME/mpd/mpd.conf. Then you need to adjust the configuration to your needs.

Sample configuration using PulseAudio output:

FILE $XDG_CONFIG_HOME/mpd/mpd.conf
# Recommended location for database
db_file                 "~/.mpd/database"

# Input
input {
        plugin          "curl"

# PulseAudio output
audio_output {
        type            "pulse"
        name            "Pulse Audio"

Now it should be possible to start MPD simply issuing:

user $mpd


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

It is possible to leverage systemd user services to control MPD in a per-user way.

To activate the MPD, start the systemd socket:

user $systemctl --user enable --now mpd.socket



Graphical (GTK)

Graphical (Qt)

Graphical (other)


  • ympd — MPD Web GUI - written in C, utilizing Websockets and Bootstrap/JS


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


For general troubleshooting refer to the MPD user manual troubleshooting section

See also

  • Upmpdcli — a free and open source UPnP media renderer front-end for Music Player Daemon (MPD).

External resources