User’s Manual

Introduction

Music Player Daemon (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 mpd via apt:

apt install mpd

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…

Note

Debian and Ubuntu are infamous for shipping heavily outdated software. The MPD version in their respective stable releases are usually too old to be supported by this project. Ironically, the 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, MPD will scan the music in your Music directory and you can control it as usual with a MPD client.

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

ALSA is not available on Android; only the OpenSL ES output plugin can be used for local playback.

Compiling from source

Download the source tarball from the MPD home page and unpack it:

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 and Ninja
  • Boost 1.58
  • pkg-config

Each plugin usually needs a codec library, which you also need to install. Check the Plugin reference for details about required libraries

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

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 libwrap0-dev \
  libgtest-dev \
  libboost-dev \
  libicu-dev

Now configure the source tree:

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

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

meson configure output/release

When everything is ready and configured, compile:

ninja -C output/release

And install:

ninja -C output/release install

Compiling for Windows

Even though it does not “feel” like a Windows application, 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 MPD for Windows:

  • Build as described above: with meson and ninja. To cross-compile from Linux, you need a Meson cross file.

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

  • Build on Linux for Windows using MPD’s library build script.

This section is about the latter.

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

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

This downloads various library sources, and then configures and builds MPD (for x64; to build a 32 bit binary, pass --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 build.py script.

Compiling for Android

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 MPD source tarball and change into the directory. Then, instead of meson, type:

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

SDK_PATH is the absolute path where you installed the Android SDK; NDK_PATH is the Android NDK installation path; ABI is the Android ABI to be built, e.g. “arm64-v8a”.

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

systemd socket activation

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

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

To enable socket activation, type:

systemctl enable mpd.socket
systemctl start mpd.socket

In this configuration, MPD will ignore the listener settings (bind_to_address and port).

systemd user unit

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

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

systemctl --user start mpd

To auto-start MPD upon login, type:

systemctl --user enable mpd

Configuration

The Configuration File

MPD reads its configuration from a text file. Usually, that is /etc/mpd.conf, unless a different path is specified on the command line. If you run MPD as a user daemon (and not as a system daemon), the configuration is read from $XDG_CONFIG_HOME/mpd/mpd.conf (usually ~/.config/mpd/mpd.conf). On Android, 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.:

connection_timeout "5"

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

music_directory "~/Music"

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

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

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

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 MPD with the music_directory setting.

By default, MPD follows symbolic links in the music directory. This behavior can be switched off: follow_outside_symlinks controls whether MPD follows links pointing to files outside of the music directory, and 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 “myfileserver” on the share called “Music”, configure the music directory “smb://myfileserver/Music”. For a recipe, read the Satellite MPD section Satellite setup.

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 database block to mpd.conf:

database {
    plugin "simple"
    path "/var/lib/mpd/db"
}

More information can be found in the 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 neighbor block to mpd.conf:

neighbors {
    plugin "smbclient"
}

More information can be found in the Neighbor plugins reference.

Configuring input plugins

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

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

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

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 Input plugins reference.

Configuring decoder plugins

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

decoder {
    plugin "wildmidi"
    config_file "/etc/timidity/timidity.cfg"
}

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

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 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 Encoder plugins reference.

Configuring audio outputs

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.

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

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

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

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: MPD counts the number of bytes, not bits. Thus, a DSD “bit” rate of 22.5792 MHz (DSD512) is 2822400 from MPD’s point of view (44100*512/8).

enabed yes|no Specifies whether this audio output is enabled when 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 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 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 alsa, OSS oss and PulseAudio pulse), the software mixer, the “null” mixer (allows setting the volume, but with no effect; this can be used as a trick to implement an external mixer External Mixer) or no mixer (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 filter block to mpd.conf:

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

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

Name Description
plugin The name of the plugin
name The name of the filter

Configuring playlist plugins

Playlist plugins are used to load remote playlists (protocol commands load, listplaylist and listplaylistinfo). This is not related to MPD’s playlist directory.

To configure a playlist plugin, add a playlist_plugin block to mpd.conf:

playlist_plugin {
    name "m3u"
    enabled "true"
}

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

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

More information can be found in the Playlist plugins reference.

Audio Format Settings

Global Audio Format

The setting audio_output_format forces MPD to use one audio format for all outputs. Doing that is usually not a good idea. The values are the same as in format in the audio_output section.

Resampler

Sometimes, music needs to be resampled before it can be played; for example, CDs use a sample rate of 44,100 Hz while many cheap audio chips can only handle 48,000 Hz. Resampling reduces the quality and consumes a lot of CPU. There are different options, some of them optimized for high quality and others for low CPU usage, but you can’t have both at the same time. Often, the resampler is the component that is responsible for most of MPD’s CPU usage. Since MPD comes with high quality defaults, it may appear that MPD consumes more CPU than other software.

Check the Resampler plugins reference for a list of resamplers and how to configure them.

Client Connections

Listeners

The setting bind_to_address specifies which addresses MPD listens on for connections from clients. It can be used multiple times to bind to more than one address. Example:

bind_to_address "192.168.1.42"
bind_to_address "127.0.0.1"

The default is “any”, which binds to all available addresses. Additionally, MPD binds to $XDG_RUNTIME_DIR/mpd/socket (if it was launched as a per-user daemon and no bind_to_address setting exists).

You can set a port that is different from the global port setting, e.g. “localhost:6602”. IPv6 addresses must be enclosed in square brackets if you want to configure a port:

bind_to_address "[::1]:6602"

To bind to a local socket (UNIX domain socket), specify an absolute path or a path starting with a tilde (~). Some clients default to connecting to /var/run/mpd/socket so this may be a good choice:

bind_to_address "/var/run/mpd/socket"

If no port is specified, the default port is 6600. This default can be changed with the port setting:

port "6601"

These settings will be ignored if systemd socket activation is used.

Permissions and Passwords

By default, all clients are unauthenticated and have a full set of permissions. This can be restricted with the settings default_permissions and password.

default_permissions controls the permissions of a new client. Its value is a comma-separated list of permissions:

Name Description
read Allows reading of the database, displaying the current playlist, and current status of MPD.
add Allows adding songs and loading playlists.
control Allows all other player and playlist manipulations.
admin Allows database updates and allows shutting down MPD.

local_permissions may be used to assign other permissions to clients connecting on a local socket.

password allows the client to send a password to gain other permissions. This option may be specified multiple times with different passwords.

Note that the password option is not secure: passwords are sent in clear-text over the connection, and the client cannot verify the server’s identity.

Example:

default_permissions "read"
password "the_password@read,add,control"
password "the_admin_password@read,add,control,admin"

Other Settings

Setting Description
metadata_to_use TAG1,TAG2,…

Use only the specified tags, and ignore the others. This setting can reduce the database size and MPD’s memory usage by omitting unused tags. By default, all tags but comment are enabled. The special value “none” disables all tags.

If the setting starts with + or -, then the following tags will be added or remoted to/from the current set of tags. This example just enables the “comment” tag without disabling all the other supported tags

metadata_to_use “+comment”

Section Tags contains a list of supported tags.

The State File

The state file is a file where MPD saves and restores its state (play queue, playback position etc.) to keep it persistent across restarts and reboots. It is an optional setting.

MPD will attempt to load the state file during startup, and will save it when shutting down the daemon. Additionally, the state file is refreshed every two minutes (after each state change).

Setting Description
state_file PATH Specify the state file location. The parent directory must be writable by the MPD user (+wx).
state_file_interval SECONDS Auto-save the state file this number of seconds after each state change. Defaults to 120 (2 minutes).

The Sticker Database

“Stickers” are pieces of information attached to songs. Some clients use them to store ratings and other volatile data. This feature requires SQLite, compile-time configure option -Dsqlite=....

Setting Description
sticker_file PATH The location of the sticker database.

Resource Limitations

These settings are various limitations to prevent MPD from using too many resources (denial of service).

Setting Description
connection_timeout SECONDS If a client does not send any new data in this time period, the connection is closed. Clients waiting in “idle” mode are excluded from this. Default is 60.
max_connections NUMBER This specifies the maximum number of clients that can be connected to MPD at the same time. Default is 5.
max_playlist_length NUMBER The maximum number of songs that can be in the playlist. Default is 16384.
max_command_list_size KBYTES The maximum size a command list. Default is 2048 (2 MiB).
max_output_buffer_size KBYTES The maximum size of the output buffer to a client (maximum response size). Default is 8192 (8 MiB).

Buffer Settings

Do not change these unless you know what you are doing.

Setting Description
audio_buffer_size KBYTES Adjust the size of the internal audio buffer. Default is 4096 (4 MiB).

Zeroconf

If Zeroconf support (Avahi or Apple’s Bonjour) was enabled at compile time with -Dzeroconf=..., MPD can announce its presence on the network. The following settings control this feature:

Setting Description
zeroconf_enabled yes|no Enables or disables this feature. Default is yes.
zeroconf_name NAME The service name to publish via Zeroconf. The default is “Music Player @ %h”. %h will be replaced with the hostname of the machine running MPD.

Advanced configuration

Satellite setup

MPD runs well on weak machines such as the Raspberry Pi. However, such hardware tends to not have storage big enough to hold a music collection. Mounting music from a file server can be very slow, especially when updating the database.

One approach for optimization is running MPD on the file server, which not only exports raw files, but also provides access to a readily scanned database. Example configuration:

music_directory "nfs://fileserver.local/srv/mp3"
#music_directory "smb://fileserver.local/mp3"

database {
    plugin "proxy"
    host "fileserver.local"
}

The music_directory setting tells MPD to read files from the given NFS server. It does this by connecting to the server from userspace. This does not actually mount the file server into the kernel’s virtual file system, and thus requires no kernel cooperation and no special privileges. It does not even require a kernel with NFS support, only the nfs storage plugin (using the libnfs userspace library). The same can be done with SMB/CIFS using the smbclient storage plugin (using libsmbclient).

The database setting tells MPD to pass all database queries on to the MPD instance running on the file server (using the proxy plugin).

Real-Time Scheduling

On Linux, MPD attempts to configure real-time scheduling for some threads that benefit from it.

This is only possible you allow MPD to do it. This privilege is controlled by RLIMIT_RTPRIO RLIMIT_RTTIME. You can configure this privilege with ulimit before launching MPD:

ulimit -HS -r 50; mpd

Or you can use the prlimit program from the util-linux package:

prlimit --rtprio=50 --rttime=unlimited mpd

The systemd service file shipped with MPD comes with this setting.

This works only if the Linux kernel was compiled with CONFIG_RT_GROUP_SCHED disabled. Use the following command to check this option for your current kernel:

zgrep ^CONFIG_RT_GROUP_SCHED /proc/config.gz

You can verify whether the real-time scheduler is active with the ps command:

# ps H -q `pidof -s mpd` -o 'pid,tid,cls,rtprio,comm'
  PID   TID CLS RTPRIO COMMAND
16257 16257  TS      - mpd
16257 16258  TS      - io
16257 16259  FF     50 rtio
16257 16260  TS      - player
16257 16261  TS      - decoder
16257 16262  FF     50 output:ALSA
16257 16263 IDL      0 update

The CLS column shows the CPU scheduler; TS is the normal scheduler; FF and RR are real-time schedulers. In this example, two threads use the real-time scheduler: the output thread and the rtio (real-time I/O) thread; these two are the important ones. The database update thread uses the idle scheduler (“IDL in ps), which only gets CPU when no other process needs it.

Note

There is a rumor that real-time scheduling improves audio quality. That is not true. All it does is reduce the probability of skipping (audio buffer xruns) when the computer is under heavy load.

Using MPD

The client

After you have installed, configured and started MPD, you choose a client to control the playback.

The most basic client is mpc, which provides a command line interface. It is useful in shell scripts. Many people bind specific mpc commands to hotkeys.

The MPD Wiki contains an extensive list of clients to choose from.

The music directory and the database

The “music directory” is where you store your music files. MPD stores all relevant meta information about all songs in its “database”. Whenever you add, modify or remove songs in the music directory, you have to update the database, for example with mpc:

mpc update

Depending on the size of your music collection and the speed of the storage, this can take a while.

To exclude a file from the update, create a file called .mpdignore in its parent directory. Each line of that file may contain a list of shell wildcards. Matching files in the current directory and all subdirectories are excluded.

Mounting other storages into the music directory

MPD has various storage plugins of which multiple instances can be “mounted” into the music directory. This way, you can use local music, file servers and USB sticks at the same time. Example:

mpc mount foo nfs://192.168.1.4/export/mp3
mpc mount usbstick udisks://by-uuid-2F2B-D136
mpc unmount usbstick

MPD’s neighbor plugins can be helpful with finding mountable storages:

mpc listneighbors

Mounting is only possible with the simple database plugin and a cache_directory, e.g.:

database {
  plugin "simple"
  path "~/.mpd/db"
  cache_directory "~/.mpd/cache"
}

This requires migrating from the old db_file setting to a database section. The cache directory must exist, and MPD will put one file per mount there, which will be reused when the same storage is used again later.

Metadata

When scanning or playing a song, MPD parses its metadata. See Tags for a list of supported tags.

The metadata_to_use setting can be used to enable or disable certain tags.

The queue

The queue (sometimes called “current playlist”) is a list of songs to be played by MPD. To play a song, add it to the queue and start playback. Most clients offer an interface to edit the queue.

Stored Playlists

Stored playlists are some kind of secondary playlists which can be created, saved, edited and deleted by the client. They are addressed by their names. Its contents can be loaded into the queue, to be played back. The playlist_directory setting specifies where those playlists are stored.

Advanced usage

Bit-perfect playback

“Bit-perfect playback” is a phrase used by audiophiles to describe a setup that plays back digital music as-is, without applying any modifications such as resampling, format conversion or software volume. Naturally, this implies a lossless codec.

By default, MPD attempts to do bit-perfect playback, unless you tell it not to. Precondition is a sound chip that supports the audio format of your music files. If the audio format is not supported, MPD attempts to fall back to the nearest supported audio format, trying to lose as little quality as possible.

To verify if MPD converts the audio format, enable verbose logging, and watch for these lines:

decoder: audio_format=44100:24:2, seekable=true
output: opened plugin=alsa name="An ALSA output"audio_format=44100:16:2
output: converting from 44100:24:2

This example shows that a 24 bit file is being played, but the sound chip cannot play 24 bit. It falls back to 16 bit, discarding 8 bit.

However, this does not yet prove bit-perfect playback; ALSA may be fooling MPD that the audio format is supported. To verify the format really being sent to the physical sound chip, try:

cat /proc/asound/card*/pcm*p/sub*/hw_params
access: RW_INTERLEAVED
format: S16_LE
subformat: STD
channels: 2
rate: 44100 (44100/1)
period_size: 4096
buffer_size: 16384

Obey the “format” row, which indicates that the current playback format is 16 bit (signed 16 bit integer, little endian).

Check list for bit-perfect playback:

  • Use the ALSA output plugin.
  • Disable sound processing inside ALSA by configuring a “hardware” device (hw:0,0 or similar).
  • Don’t use software volume (setting mixer_type).
  • Don’t force MPD to use a specific audio format (settings format, audio_output_format).
  • Verify that you are really doing bit-perfect playback using MPD’s verbose log and /proc/asound/card*/pcm*p/sub*/hw_params. Some DACs can also indicate the audio format.

Direct Stream Digital (DSD)

DSD (Direct Stream Digital) is a digital format that stores audio as a sequence of single-bit values at a very high sampling rate.

MPD understands the file formats dff and dsf. There are three ways to play back DSD:

  • Native DSD playback. Requires ALSA 1.0.27.1 or later, a sound driver/chip that supports DSD and of course a DAC that supports DSD.
  • DoP (DSD over PCM) playback. This wraps DSD inside fake 24 bit PCM according to the DoP standard. Requires a DAC that supports DSD. No support from ALSA and the sound chip required (except for bit-perfect 24 bit PCM support).
  • Convert DSD to PCM on-the-fly.

Native DSD playback is used automatically if available. DoP is only used if enabled explicitly using the dop option, because there is no way for MPD to find out whether the DAC supports it. DSD to PCM conversion is the fallback if DSD cannot be used directly.

Client Hacks

External Mixer

The setting mixer_type "null" asks MPD to pretend that there is a mixer, but not actually do something. This allows you to implement a MPD client which listens for mixer events, queries the current (fake) volume, and uses it to program an external mixer. For example, your client can forward this setting to your amplifier.

Troubleshooting

Where to start

Make sure you have the latest MPD version (via mpd --version, not mpc version). All the time, bugs are found and fixed, and your problem might be a bug that is fixed already. Do not ask for help unless you have the latest MPD version. The most common excuse is when your distribution ships an old MPD version - in that case, please ask your distribution for help, and not the MPD project.

Check the log file. Configure log_level "verbose" or pass --verbose to mpd.

Sometimes, it is helpful to run MPD in a terminal and follow what happens. This is how to do it:

mpd --stdout --no-daemon --verbose

Support

Getting Help

The MPD project runs a forum and an IRC channel (#mpd on Freenode) for requesting help. Visit the MPD help page for details on how to get help.

Common Problems

1. Database
Question: I can’t see my music in the MPD database!
  • Check your music_directory setting.
  • Does the MPD user have read permission on all music files, and read+execute permission on all music directories (and all of their parent directories)?
  • Did you update the database? (mpc update)
  • Did you enable all relevant decoder plugins at compile time? mpd --version will tell you.
Question: MPD doesn’t read ID3 tags!
  • You probably compiled MPD without libid3tag. mpd --version will tell you.
2. Playback
Question: I can’t hear music on my client!
  • That problem usually follows a misunderstanding of the nature of MPD. MPD is a remote-controlled music player, not a music distribution system. Usually, the speakers are connected to the box where MPD runs, and the MPD client only sends control commands, but the client does not actually play your music.

    MPD has output plugins which allow hearing music on a remote host (such as httpd), but that is not MPD’s primary design goal.

Question: “Device or resource busy”
  • This ALSA error means that another program uses your sound hardware exclusively. You can stop that program to allow MPD to use it.
Sometimes, this other program is PulseAudio, which can multiplex sound from several applications, to allow them to share your sound chip. In this case, it might be a good idea for MPD to use PulseAudio as well, instead of using ALSA directly.

Reporting Bugs

If you believe you found a bug in MPD, report it on the bug tracker.

Your bug report should contain:

  • the output of mpd --version
  • your configuration file (mpd.conf)
  • relevant portions of the log file (--verbose)
  • be clear about what you expect MPD to do, and what is actually happening

MPD crashes

All MPD crashes are bugs which must be fixed by a developer, and you should write a bug report. (Many crash bugs are caused by codec libraries used by MPD, and then that library must be fixed; but in any case, the MPD bug tracker is a good place to report it first if you don’t know.)

A crash bug report needs to contain a “backtrace”.

First of all, your MPD executable must not be “stripped” (i.e. debug information deleted). The executables shipped with Linux distributions are usually stripped, but some have so-called “debug” packages (package mpd-dbgsym or mpd-dbg on Debian, mpd-debug on other distributions). Make sure this package is installed.

If you built MPD from sources, please recompile with Meson option “--buildtype=debug -Db_ndebug=false”, because this will add more helpful information to the backtrace.

You can extract the backtrace from a core dump, or by running MPD in a debugger, e.g.:

gdb --args mpd --stdout --no-daemon --verbose
run

As soon as you have reproduced the crash, type “bt” on the gdb command prompt. Copy the output to your bug report.