Music Player Daemon¶
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 in MPD’s data directory on the external storage
(usually Android/data/org.musicpd/files/mpd.conf).
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 and unpack it (or clone the git repository):
tar xf mpd-version.tar.xz
cd mpd-version
In any case, you need:
a C++17 compiler (e.g. GCC 8 or clang 7)
Meson 0.56.0 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 Bullseye:
apt install meson g++ \
libfmt-dev \
libpcre2-dev \
libmad0-dev libmpg123-dev libid3tag0-dev \
libflac-dev libvorbis-dev libopus-dev libogg-dev \
libadplug-dev libaudiofile-dev libsndfile1-dev libfaad-dev \
libfluidsynth-dev libgme-dev libmikmod-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 \
libupnp-dev \
libavahi-client-dev \
libsqlite3-dev \
libsystemd-dev \
libgtest-dev \
libboost-dev \
libicu-dev \
libchromaprint-dev \
libgcrypt20-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
NB: Check the sysconfdir setting to determine where mpd will look for mpd.conf; if you expect mpd to look for /etc/mpd.conf the sysconfdir must be ‘/etc’ (i.e., not ‘etc’ which will result in mpd looking for /usr/local/etc/mpd.conf):
meson configure output/release |grep sysconfdir
If this is not /etc (or another path you wish to specify):
$ meson configure output/release -Dsysconfdir='/etc' ; meson configure output/release |grep syscon
sysconfdir /etc Sysconf data directory
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.
You need:
Meson 0.56.0 and Ninja
cmake
pkg-config
quilt
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 \
--buildtype=debugoptimized -Db_ndebug=true \
-Dwrap_mode=forcefallback
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.
The option -Dwrap_mode=forcefallback tells Meson to download and
cross-compile several libraries used by MPD instead of looking for
them on your computer.
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
Meson 0.56.0 and Ninja
cmake
pkg-config
quilt
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 \
--buildtype=debugoptimized -Db_ndebug=true \
-Dwrap_mode=forcefallback \
-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.
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"
You can use include_optional instead if you want the included file
to be optional; the directive will be ignored if the file does not exist:
include_optional "may_not_exist.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 neighbors
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 the Input Cache¶
The input cache prefetches queued song files before they are going to be played. This has several advantages:
risk of buffer underruns during playback is reduced because this decouples playback from disk (or network) I/O
bulk transfers may be faster and more energy efficient than loading small chunks on-the-fly
by prefetching several songs at a time, the hard disk can spin down for longer periods of time
This comes at a cost:
memory usage
bulk transfers may reduce the performance of other applications which also want to access the disk (if the kernel’s I/O scheduler isn’t doing its job properly)
To enable the input cache, add an input_cache block to the
configuration file:
input_cache {
size "1 GB"
}
This allocates a cache of 1 GB. If the cache grows larger than that, older files will be evicted.
You can flush the cache at any time by sending SIGHUP to the
MPD process, see Signals.
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, see Configuring audio outputs.
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 samplerate:bits:channels |
Always open the audio output with the specified audio format, regardless of the format of the input file. This is optional for most plugins. See Global Audio Format for a detailed description of the value. |
enabled 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 “ |
replay_gain_handler software|mixer|none |
Specifies how Replay Gain is applied. The default is
|
filters “name,…” |
The specified configured filters are instantiated in the given
order. Each filter name refers to a |
More information can be found in the Output plugins reference.
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"
}
Configured filters may then be added to the filters setting of an
audio_output section, see Configuring audio outputs.
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 |
More information can be found in the Filter plugins reference.
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 |
|---|---|
name |
The name of the plugin |
enabled yes|no |
Allows you to disable a playlist plugin without recompiling. By default, all plugins are enabled. |
as_directory yes|no |
With this option, a playlist file of this type is parsed during database update and converted to a virtual directory, allowing MPD clients to access individual entries. By default, this is only enabled for the cue plugin. |
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 value is specified as samplerate:bits:channels.
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).
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.
Volume Normalization Settings¶
Replay Gain¶
The setting replaygain specifies whether MPD shall adjust the
volume of songs played using ReplayGain tags.
Setting this to album will adjust volume using the album’s
ReplayGain tags, while setting it to track will adjust it using
the “track” ReplayGain tags. auto uses the track ReplayGain tags
if random play is activated otherwise the album ReplayGain
tags.
If ReplayGain is enabled, then the setting replaygain_preamp is
set to a value (in dB) between -15 and 15. This is the gain
applied to songs with ReplayGain tags.
On songs without ReplayGain tags, the setting
replaygain_missing_preamp is used instead. If this setting is not
configured, then no ReplayGain is applied to such songs, and they will
appear too loud.
ReplayGain is usually implemented with a software volume filter (which
prevents Bit-perfect playback). To use a hardware mixer, set
replay_gain_handler to mixer in the audio_output section
(see Configuring audio outputs for details).
Simple Volume Normalization¶
MPD implements a very simple volume normalization method which can be
enabled by setting volume_normalization to yes. It supports
16 bit PCM only.
Cross-Fading¶
If crossfade is set to a positive number, then adjacent songs are
cross-faded by this number of seconds. This is a run-time setting
which can be controlled by clients,
e.g. with mpc:
mpc crossfade 10
mpc crossfade 0
Zero means cross-fading is disabled.
Cross-fading is only possible if both songs have the same audio format. At the cost of quality loss and higher CPU usage, you can make sure this is always given by configuring Global Audio Format.
MixRamp¶
MixRamp tags describe the loudness levels at start and end of a song and can be used by MPD to find the best time to begin cross-fading. MPD enables MixRamp if:
Cross-fade is enabled
mixrampdelay is set to a positive value, e.g.:
mpc mixrampdelay 1
mixrampdb is set to a reasonable value, e.g.:
mpc mixrampdb -17
both songs have MixRamp tags
both songs have the same audio format (or Global Audio Format is configured)
The MixRamp tool can be used to add MixRamp tags to your song files.
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"
On Linux, local sockets can be bound to a name without a socket inode
on the filesystem; MPD implements this by prepending @ to the
address:
bind_to_address "@mpd"
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. |
player |
Allows any player and queue manipulation (start/pause/stop playback etc.). |
control |
Allows all other player and playlist manipulations. |
admin |
Allows manipulating outputs, stickers and partitions, mounting/unmounting storage and shutting down MPD. |
local_permissions may be used to assign other permissions to clients connecting on a local socket.
host_permissions may be used to assign permissions to clients
with a certain IP address.
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"
host_permissions "192.168.0.100 read,add,control,admin"
host_permissions "2003:1234:4567::1 read,add,control,admin"
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
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). |
restore_paused yes|no |
If set to |
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 100. |
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 SIZE |
Adjust the size of the internal audio buffer. Default is
|
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 if 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 40; mpd
Or you can use the prlimit program from the util-linux package:
prlimit --rtprio=40 --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 40 rtio
16257 16260 TS - player
16257 16261 TS - decoder
16257 16262 FF 40 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¶
Starting and Stopping MPD¶
The simplest (but not the best) way to start MPD is to simply type:
mpd
This will start MPD as a daemon process (which means it
detaches from your terminal and continues to run in background). To
stop it, send SIGTERM to the process; if you have configured a
pid_file, you can use the --kill option:
mpd --kill
The best way to manage MPD processes is to use a service manager such as systemd.
systemd¶
MPD ships with systemd service units.
If you have installed MPD with your operating system’s package manager, these are probably preinstalled, so you can start and stop MPD this way (like any other service):
systemctl start mpd
systemctl stop 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
Signals¶
MPD understands the following UNIX signals:
SIGTERM,SIGINT: shut down MPDSIGHUP: reopen log files (send this after log rotation) and flush caches (see Configuring the Input Cache)
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 (or
directories) in the current directory and all subdirectories are
excluded. Example:
*.opus
99*
Subject to pattern matching is the file/directory name. It is (not
yet) possible to match nested path names, e.g. something like
foo/*.flac is not possible.
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.
Note that MPD may not necessarily read metadata itself, instead relying on data reported by the decoder that was used to read a file. For example, this is the case for the FFmpeg decoder: both MPD and FFmpeg need to support a given metadata format in order for metadata to be picked up correctly.
Only if a decoder does not have metadata support will MPD attempt to parse a song’s metadata itself.
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,0or similar).Don’t use software volume (setting
mixer_type).Don’t use Replay Gain.
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. It is the sample format used on Super Audio CDs.
MPD understands the file formats DSDIFF 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.
ICY-MetaData¶
Some MP3 streams send information about the current song with a
protocol named “ICY-MetaData”.
MPD makes its StreamTitle value available as Title
tag.
By default, MPD assumes this tag is UTF-8-encoded. To tell
MPD to assume a different character set, specify it in the
charset URL fragment parameter, e.g.:
mpc add 'http://radio.example.com/stream#charset=cp1251'
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 --stderr --no-daemon --verbose
Support¶
Getting Help¶
The MPD project runs a forum and an IRC channel (#mpd on Libera.Chat) for requesting help. Visit the MPD help page for details on how to get help.
Common Problems¶
Startup¶
Error “could not get realtime scheduling”¶
See Real-Time Scheduling. You can safely ignore this, but you won’t benefit from real-time scheduling. This only makes a difference if your computer runs programs other than MPD.
Error “Failed to initialize io_uring”¶
Linux specific: the io_uring subsystem could not be initialized. This is not a critical error - MPD will fall back to “classic” blocking disk I/O. You can safely ignore this error, but you won’t benefit from io_uring’s advantages.
“Cannot allocate memory” usually means that your memlock limit (
ulimit -lin bash orLimitMEMLOCKin systemd) is too low. 64 MB is a reasonable value for this limit.Your Linux kernel might be too old and does not support io_uring.
Error “bind to ‘0.0.0.0:6600’ failed (continuing anyway, because binding to ‘[::]:6600’ succeeded)”¶
This happens on Linux when /proc/sys/net/ipv6/bindv6only is
disabled. MPD first binds to IPv6, and this automatically binds to
IPv4 as well; after that, MPD binds to IPv4, but that fails. You can
safely ignore this, because MPD works on both IPv4 and IPv6.
Database¶
I can’t see my music in the MPD database¶
Check your
music_directorysetting.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.
Playback¶
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.
Error “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
Too Much CPU Usage¶
If you believe MPD consumes too much CPU, write a bug report with a profiling information.
On Linux, this can be obtained with perf (on Debian,
installed the package linux-perf), for example:
perf record -p `pidof mpd`
Run this command while MPD consumes much CPU, let it run for a minute
or so, and stop it by pressing Ctrl-C. Then type:
perf report >mpd_perf.txt
Upload the output file to the bug report.
Note
This requires having debug symbols for MPD and all relevant libraries. See MPD crashes for details.
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 --stderr --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.
Plugin reference¶
Database plugins¶
simple¶
The default plugin. Stores a copy of the database in memory. A file is used for permanent storage.
Setting |
Description |
|---|---|
path |
The path of the database file. |
cache_directory |
The path of the cache directory for additional storages mounted at runtime. This setting is necessary for the mount protocol command. |
compress yes|no |
Compress the database file using gzip? Enabled by default (if built with zlib). |
hide_playlist_targets yes|no |
Hide songs which are referenced by playlists? Thas is,
playlist files which are represented in the database as virtual
directories (playlist plugin setting |
proxy¶
Provides access to the database of another MPD instance using libmpdclient. This is useful when you mount the music directory via NFS/SMB, and the file server already runs a MPD (0.20 or newer) instance. Only the file server needs to update the database.
Setting |
Description |
|---|---|
host |
The host name of the “master” MPD instance. |
port |
The port number of the “master” MPD instance. |
password |
The password used to log in to the “master” MPD instance. |
keepalive yes|no |
Send TCP keepalive packets to the “master” MPD instance? This option can help avoid certain firewalls dropping inactive connections, at the expense of a very small amount of additional network traffic. Disabled by default. |
upnp¶
Provides access to UPnP media servers.
Setting |
Description |
|---|---|
interface |
Interface used to discover media servers. Decided by upnp if left unconfigured. |
Storage plugins¶
local¶
The default plugin which gives MPD access to local files. It is used when music_directory refers to a local directory.
curl¶
A WebDAV client using libcurl. It is used when music_directory
contains a http:// or https:// URI, for example
https://the.server/dav/.
smbclient¶
Load music files from a SMB/CIFS server. It is used when
music_directory contains a smb:// URI, for example
smb://myfileserver/Music.
Note that libsmbclient has a serious bug which causes MPD to
crash, and therefore this plugin is disabled by default and should not
be used until the bug is fixed:
https://bugzilla.samba.org/show_bug.cgi?id=11413
nfs¶
Load music files from a NFS server. It is used when
music_directory contains a nfs:// URI according to
RFC2224, for example nfs://servername/path.
See nfs for more information.
udisks¶
Mount file systems (e.g. USB sticks or other removable media) using the udisks2 daemon via D-Bus. To obtain a valid udisks2 URI, consult the according neighbor plugin.
It might be necessary to grant MPD privileges to control
udisks2 through policykit. To do this, create a
file called /usr/share/polkit-1/rules.d/mpd-udisks.rules with
the following text:
polkit.addRule(function(action, subject) {
if ((action.id == "org.freedesktop.udisks2.filesystem-mount" ||
action.id == "org.freedesktop.udisks2.filesystem-mount-other-seat") &&
subject.user == "mpd") {
return polkit.Result.YES;
}
});
If you run MPD as a different user, change mpd to the name of your
MPD user.
Neighbor plugins¶
smbclient¶
Provides a list of SMB/CIFS servers on the local network.
udisks¶
Queries the udisks2 daemon via D-Bus and obtains a list of file systems (e.g. USB sticks or other removable media).
upnp¶
Provides a list of UPnP servers on the local network.
Input plugins¶
alsa¶
Allows MPD on Linux to play audio directly from a soundcard using the scheme alsa://. Audio is by default formatted as 48 kHz 16-bit stereo, but this default can be overidden by a config file setting or by the URI. Examples:
mpc add alsa:// plays audio from device default
mpc add alsa://hw:1,0 plays audio from device hw:1,0
mpc add alsa://hw:1,0?format=44100:16:2 plays audio from device hw:1,0 sampling 16-bit stereo at 44.1kHz.
Setting |
Description |
|---|---|
default_device NAME |
The alsa device id to use when none is specified in the URI. |
default_format F |
The sampling rate, size and channels to use. Wildcards are not allowed. Example - “44100:16:2” |
auto_resample yes|no |
If set to no, then libasound will not attempt to resample. In this case, the user is responsible for ensuring that the requested sample rate can be produced natively by the device, otherwise an error will occur. |
auto_channels yes|no |
If set to no, then libasound will not attempt to convert between different channel numbers. The user must ensure that the device supports the requested channels when sampling. |
auto_format yes|no |
If set to no, then libasound will not attempt to convert between different sample formats (16 bit, 24 bit, floating point, …). Again the user must ensure that the requested format is available natively from the device. |
cdio_paranoia¶
Plays audio CDs using libcdio. The URI has the form: “cdda://[DEVICE][/TRACK]”. The simplest form cdda:// plays the whole disc in the default drive.
Setting |
Description |
|---|---|
default_byte_order little_endian|big_endian |
If the CD drive does not specify a byte order, MPD assumes it is the CPU’s native byte order. This setting allows overriding this. |
speed N |
Request CDParanoia cap the extraction speed to Nx normal CD audio rotation speed, keeping the drive quiet. |
mode disable|overlap|full |
Set the paranoia mode; |
skip yes|no |
If set to |
curl¶
Opens remote files or streams over HTTP using libcurl.
Note that unless overridden by the below settings (e.g. by setting
them to a blank value), general curl configuration from environment
variables such as http_proxy will be in effect.
User name and password are read from an optional ~/.netrc, ~/.curlrc is not read.
Setting |
Description |
|---|---|
proxy |
Sets the address of the HTTP proxy server. |
proxy_user, proxy_password |
Configures proxy authentication. |
verify_peer yes|no |
Verify the peer’s SSL certificate? More information. |
verify_host yes|no |
Verify the certificate’s name against host? More information. |
cacert |
Set path to Certificate Authority (CA) bundle More information. |
ffmpeg¶
Access to various network protocols implemented by the FFmpeg library:
gopher://, rtp://, rtsp://, rtmp://, rtmpt://,
rtmps://
file¶
Opens local files
mms¶
Plays streams with the MMS protocol using libmms.
nfs¶
Allows MPD to access files on NFS servers without actually
mounting them (i.e. with libnfs in userspace, without help
from the kernel’s VFS layer). All URIs with the nfs:// scheme are
used according to RFC2224. Example:
mpc add nfs://servername/path/filename.ogg
This plugin uses libnfs, which supports only NFS version 3.
Since MPD is not allowed to bind to so-called “privileged
ports”, the NFS server needs to enable the insecure setting;
example /etc/exports:
/srv/mp3 192.168.1.55(ro,insecure)
Don’t fear: this will not make your file server insecure; the flag was named a time long ago when privileged ports were thought to be meaningful for security. By today’s standards, NFSv3 is not secure at all, and if you believe it is, you’re already doomed.
smbclient¶
Allows MPD to access files on SMB/CIFS servers (e.g. Samba
or Microsoft Windows). All URIs with the smb:// scheme are
used. Example:
mpc add smb://servername/sharename/filename.ogg
mpc add smb://username:password@servername/sharename/filename.ogg
qobuz¶
Play songs from the commercial streaming service Qobuz. It plays URLs
in the form qobuz://track/ID, e.g.:
mpc add qobuz://track/23601296
Setting |
Description |
|---|---|
app_id ID |
The Qobuz application id. |
app_secret SECRET |
The Qobuz application secret. |
username USERNAME |
The Qobuz user name. |
password PASSWORD |
The Qobuz password. |
format_id N |
The Qobuz format identifier, i.e. a number which chooses the format and quality to be requested from Qobuz. The default is “5” (320 kbit/s MP3). |
Decoder plugins¶
adplug¶
Decodes AdLib files using libadplug.
Setting |
Description |
|---|---|
sample_rate |
The sample rate that shall be synthesized by the plugin. Defaults to 48000. |
audiofile¶
Decodes WAV and AIFF files using libaudiofile.
faad¶
Decodes AAC files using libfaad.
ffmpeg¶
Decodes various codecs using FFmpeg.
Setting |
Description |
|---|---|
analyzeduration VALUE |
Sets the FFmpeg muxer option analyzeduration, which specifies how many microseconds are analyzed to probe the input. The FFmpeg formats documentation has more information. |
probesize VALUE |
Sets the FFmpeg muxer option probesize, which specifies probing size in bytes, i.e. the size of the data to analyze to get stream information. The FFmpeg formats documentation has more information. |
flac¶
Decodes FLAC files using libFLAC.
dsdiff¶
Decodes DSDIFF (Direct Stream Digital Interchange File Format) files
(*.dff). These contain DSD instead of PCM.
Setting |
Description |
|---|---|
lsbitfirst yes|no |
Decode the least significant bit first. Default is no. |
dsf¶
Decodes DSF
(<https://dsd-guide.com/sites/default/files/white-papers/DSFFileFormatSpec_E.pdf>)
files (*.dsf). These contain DSD instead of PCM.
fluidsynth¶
MIDI decoder based on FluidSynth.
Setting |
Description |
|---|---|
sample_rate |
The sample rate that shall be synthesized by the plugin. Defaults to 48000. |
soundfont |
The absolute path of the soundfont file. Defaults to |
gme¶
Video game music file emulator based on game-music-emu.
Setting |
Description |
|---|---|
accuracy yes|no |
Enable more accurate sound emulation. |
default_fade |
The default fade-out time, in seconds. Used by songs that don’t specify their own fade-out time. |
hybrid_dsd¶
Hybrid-DSD
is an MP4 container file (*.m4a) which contains both ALAC and
DSD data. It is disabled by default, and works only if you explicitly
enable it. Without this plugin, the ALAC parts gets handled by the
FFmpeg decoder plugin. This
plugin should be enabled only if you have a bit-perfect playback path
to a DSD-capable DAC; for everybody else, playing back the ALAC copy
of the file is better.
mad¶
Decodes MP3 files using libmad.
mikmod¶
Module player based on MikMod.
Setting |
Description |
|---|---|
loop yes|no |
Allow backward loops in modules. Default is no. |
sample_rate |
Sets the sample rate generated by libmikmod. Default is 44100. |
modplug¶
Module player based on MODPlug.
Setting |
Description |
|---|---|
resampling_mode nearest|linear|spline|fir |
Sets the resampling mode. “nearest” disables interpolation (good for chiptunes). “linear” makes modplug use linear interpolation (fast, good quality). “spline” makes modplug use cubic spline interpolation (high quality). “fir” makes modplug use 8-tap fir filter (extremely high quality). Defaults to “fir”. |
loop_count |
Number of times to loop the module if it uses backward loops. Default is 0 which prevents looping. -1 loops forever. |
openmpt¶
Module player based on libopenmpt.
Setting |
Description |
|---|---|
repeat_count |
Set how many times the module repeats. -1: repeat forever. 0: play once, repeat zero times (the default). n>0: play once and repeat n times after that. |
stereo_separation |
Sets the stereo separation. The supported value range is [0,200]. Defaults to 100. |
interpolation_filter 0|1|2|4|8 |
Sets the interpolation filter. 0: internal default. 1: no interpolation (zero order hold). 2: linear interpolation. 4: cubic interpolation. 8: windowed sinc with 8 taps. Defaults to 0. |
override_mptm_interp_filter yes|no |
If interpolation_filter has been changed, setting this to yes will force all MPTM modules to use that interpolation filter. If set to no, MPTM modules will play with their own interpolation filter regardless of the value of interpolation_filter. Defaults to no. |
volume_ramping |
Sets the amount of volume ramping done by the libopenmpt mixer. The default value is -1, which indicates a recommended default value. The meaningful value range is [-1..10]. A value of 0 completely disables volume ramping. This might cause clicks in sound output. Higher values imply slower/softer volume ramps. |
sync_samples yes|no |
Syncs sample playback when seeking. Defaults to yes. |
emulate_amiga yes|no |
Enables the Amiga resampler for Amiga modules. This emulates the sound characteristics of the Paula chip and overrides the selected interpolation filter. Non-Amiga module formats are not affected by this setting. Defaults to yes. |
emulate_amiga_type |
Configures the filter type to use for the Amiga resampler. Supported values are: “auto”: Filter type is chosen by the library and might change. This is the default. “a500”: Amiga A500 filter. “a1200”: Amiga A1200 filter. “unfiltered”: BLEP synthesis without model-specific filters. The LED filter is ignored by this setting. This filter mode is considered to be experimental and might change in the future. Defaults to “auto”. Requires libopenmpt 0.5 or higher. |
mpcdec¶
Decodes Musepack files using libmpcdec.
mpg123¶
Decodes MP3 files using libmpg123. Currently, this decoder does not support streams (e.g. archived files, remote files over HTTP, …), only regular local files.
opus¶
Decodes Opus files using libopus.
pcm¶
Reads raw PCM samples. It understands the “audio/L16” MIME type with parameters “rate” and “channels” according to RFC 2586. It also understands the MPD-specific MIME type “audio/x-mpd-float”.
sidplay¶
C64 SID decoder based on libsidplayfp or libsidplay2.
Setting |
Description |
|---|---|
songlength_database PATH |
Location of your songlengths file, as distributed with the HVSC. The sidplay plugin checks this for matching MD5 fingerprints. See http://www.hvsc.c64.org/download/C64Music/DOCUMENTS/Songlengths.faq. New songlength format support requires libsidplayfp 2.0 or later. |
default_songlength SECONDS |
This is the default playing time in seconds for songs not in the songlength database, or in case you’re not using a database. A value of 0 means play indefinitely. |
default_genre GENRE |
Optional default genre for SID songs. |
filter yes|no |
Turns the SID filter emulation on or off. |
kernal |
Only libsidplayfp. Roms are not embedded in libsidplayfp - please note https://sourceforge.net/p/sidplay-residfp/news/2013/01/released-libsidplayfp-100beta1/ But some SID tunes require rom images to play. Make C64 rom dumps from your own vintage gear or use rom files from Frodo or VICE emulation software tarballs. Absolute path to kernal rom image file. |
basic |
Only libsidplayfp. Absolute path to basic rom image file. |
sndfile¶
Decodes WAV and AIFF files using libsndfile.
vorbis¶
Decodes Ogg-Vorbis files using libvorbis.
wavpack¶
Decodes WavPack files using libwavpack.
wildmidi¶
MIDI decoder based on libwildmidi.
Setting |
Description |
|---|---|
config_file |
The absolute path of the timidity config file. Defaults to |
Encoder plugins¶
flac¶
Encodes into FLAC (lossless).
Setting |
Description |
|---|---|
compression |
Sets the libFLAC compression level. The levels range from 0 (fastest, least compression) to 8 (slowest, most compression). |
oggflac yes|no |
Configures if the stream should be Ogg FLAC versus native FLAC. Defaults to “no” (use native FLAC). |
oggchaining yes|no |
Configures if the stream should use Ogg Chaining for in-stream metadata. Defaults to “no”. Setting this to “yes” also enables Ogg FLAC. |
lame¶
Encodes into MP3 using the LAME library.
Setting |
Description |
|---|---|
quality |
Sets the quality for VBR. 0 is the highest quality, 9 is the lowest quality. Cannot be used with bitrate. |
bitrate |
Sets the bit rate in kilobit per second. Cannot be used with quality. |
null¶
Does not encode anything, passes the input PCM data as-is.
shine¶
Encodes into MP3 using the Shine library.
Setting |
Description |
|---|---|
bitrate |
Sets the bit rate in kilobit per second. |
twolame¶
Encodes into MP2 using the TwoLAME library.
Setting |
Description |
|---|---|
quality |
Sets the quality for VBR. 0 is the highest quality, 9 is the lowest quality. Cannot be used with bitrate. |
bitrate |
Sets the bit rate in kilobit per second. Cannot be used with quality. |
opus¶
Encodes into Ogg Opus.
Setting |
Description |
|---|---|
bitrate |
Sets the data rate in bits per second. The special value “auto” lets libopus choose a rate (which is the default), and “max” uses the maximum possible data rate. |
complexity |
Sets the Opus complexity. |
signal |
Sets the Opus signal type. Valid values are “auto” (the default), “voice” and “music”. |
vbr yes|no|constrained |
Sets the vbr mode. Setting to “yes” (default) enables variable bitrate, “no” forces constant bitrate and frame sizes, “constrained” uses constant bitrate analogous to CBR in AAC and MP3. |
packet_loss |
Sets the expected packet loss percentage. This value can be increased from the default “0” for a more redundant stream at the expense of quality. |
opustags yes|no |
Configures how metadata is interleaved into the stream. If set to yes, then metadata is inserted using ogg stream chaining, as specified in RFC 7845. If set to no (the default), then ogg stream chaining is avoided and other output-dependent method is used, if available. |
vorbis¶
Encodes into Ogg Vorbis.
Setting |
Description |
|---|---|
quality |
Sets the quality for VBR. -1 is the lowest quality, 10 is the highest quality. Defaults to 3. Cannot be used with bitrate. |
bitrate |
Sets the bit rate in kilobit per second. Cannot be used with quality. |
wave¶
Encodes into WAV (lossless).
Resampler plugins¶
The resampler can be configured in a block named resampler, for example:
resampler {
plugin "soxr"
quality "very high"
}
The following table lists the resampler options valid for all plugins:
Name |
Description |
|---|---|
plugin |
The name of the plugin. |
internal¶
A resampler built into MPD. Its quality is very poor, but its CPU usage is low. This is the fallback if MPD was compiled without an external resampler.
libsamplerate¶
A resampler using libsamplerate a.k.a. Secret Rabbit Code (SRC).
Name |
Description |
|---|---|
type |
The interpolator type. Defaults to |
The following converter types are provided by libsamplerate:
Type |
Description |
|---|---|
“Best Sinc Interpolator” or “0” |
Band limited sinc interpolation, best quality, 97dB SNR, 96% BW. |
“Medium Sinc Interpolator” or “1” |
Band limited sinc interpolation, medium quality, 97dB SNR, 90% BW. |
“Fastest Sinc Interpolator” or “2” |
Band limited sinc interpolation, fastest, 97dB SNR, 80% BW. |
“ZOH Sinc Interpolator” or “3” |
Zero order hold interpolator, very fast, very poor quality with audible distortions. |
“Linear Interpolator” or “4” |
Linear interpolator, very fast, poor quality. |
soxr¶
A resampler using libsoxr, the SoX Resampler library
Name |
Description |
|---|---|
quality |
The libsoxr quality setting. Valid values see below. |
threads |
The number of libsoxr threads. “0” means “automatic”. The default is “1” which disables multi-threading. |
Valid quality values for libsoxr:
“very high”
“high” (the default)
“medium”
“low”
“quick”
“custom”
If the quality is set to custom also the following settings are available:
Name |
Description |
|---|---|
precision |
The precision in bits. Valid values 16,20,24,28 and 32 bits. |
phase_response |
Between the 0-100, Where 0=MINIMUM_PHASE and 50=LINEAR_PHASE. |
passband_end |
The % of source bandwidth where to start filtering. Typical between the 90-99.7. |
stopband_begin |
The % of the source bandwidth Where the anti aliasing filter start. Value 100+. |
attenuation |
Reduction in dB’s to prevent clipping from the resampling process. |
flags |
Bitmask with additional option see soxr documentation for specific flags. |
Output plugins¶
alsa¶
The Advanced Linux Sound Architecture (ALSA) plugin uses libasound. It is recommended if you are using Linux.
Setting |
Description |
|---|---|
device NAME |
Sets the device which should be used. This can be any valid ALSA device name. The default value is “default”, which makes libasound choose a device. It is recommended to use a “hw” or “plughw” device, because otherwise, libasound automatically enables “dmix”, which has major disadvantages (fixed sample rate, poor resampler, …). |
buffer_time US |
Sets the device’s buffer time in microseconds. Don’t change unless you know what you’re doing. |
period_time US |
Sets the device’s period time in microseconds. Don’t change unless you really know what you’re doing. |
auto_resample yes|no |
If set to no, then libasound will not attempt to resample, handing the responsibility over to MPD. It is recommended to let MPD resample (with libsamplerate), because ALSA is quite poor at doing so. |
auto_channels yes|no |
If set to no, then libasound will not attempt to convert between different channel numbers. |
auto_format yes|no |
If set to no, then libasound will not attempt to convert between different sample formats (16 bit, 24 bit, floating point, …). |
dop yes|no |
If set to yes, then DSD over PCM according to the DoP standard is enabled. This wraps DSD samples in fake 24 bit PCM, and is understood by some DSD capable products, but may be harmful to other hardware. Therefore, the default is no and you can enable the option at your own risk. |
stop_dsd_silence yes|no |
If enabled, silence is played before manually stopping playback (“stop” or “pause”) in DSD mode (native DSD or DoP). This is a workaround for some DACs which emit noise when stopping DSD playback. |
thesycon_dsd_workaround yes|no |
If enabled, enables a workaround for a bug in Thesycon USB audio receivers. On these devices, playing DSD512 or PCM causes all subsequent attempts to play other DSD rates to fail, which can be fixed by briefly playing PCM at 44.1 kHz. |
allowed_formats F1 F2 … |
Specifies a list of allowed audio formats, separated by a space. All items may contain asterisks as a wild card, and may be followed by “=dop” to enable DoP (DSD over PCM) for this particular format. The first matching format is used, and if none matches, MPD chooses the best fallback of this list. Example: “96000:16:* 192000:24:* dsd64:=dop *:dsd:”. |
The according hardware mixer plugin understands the following settings:
Setting |
Description |
|---|---|
mixer_device DEVICE |
Sets the ALSA mixer device name, defaulting to default which lets ALSA pick a value. |
mixer_control NAME |
Choose a mixer control, defaulting to PCM. Type amixer scontrols to get a list of available mixer controls. |
mixer_index NUMBER |
Choose a mixer control index. This is necessary if there is more than one control with the same name. Defaults to 0 (the first one). |
The following attributes can be configured at runtime using the outputset command:
Setting |
Description |
|---|---|
dop 1|0 |
Allows changing the dop configuration setting at runtime. This takes effect the next time the output is opened. |
allowed_formats F1 F2 … |
Allows changing the allowed_formats configuration setting at runtime. This takes effect the next time the output is opened. |
ao¶
The ao plugin uses the portable libao library. Use only if there is no native plugin for your operating system.
Setting |
Description |
|---|---|
driver D |
The libao driver to use for audio output. Possible values depend on what libao drivers are available. See http://www.xiph.org/ao/doc/drivers.html for information on some commonly used drivers. Typical values for Linux include “oss” and “alsa09”. The default is “default”, which causes libao to select an appropriate plugin. |
options O |
Options to pass to the selected libao driver. |
write_size O |
This specifies how many bytes to write to the audio device at once. This parameter is to work around a bug in older versions of libao on sound cards with very small buffers. The default is 1024. |
sndio¶
The sndio plugin uses the sndio library. It should normally be used on OpenBSD.
Setting |
Description |
|---|---|
device NAME |
The audio output device libsndio will attempt to use. The default is “default” which causes libsndio to select the first output device. |
buffer_time MS |
Set the application buffer time in milliseconds. |
fifo¶
The fifo plugin writes raw PCM data to a FIFO (First In, First Out) file. The data can be read by another program.
Setting |
Description |
|---|---|
path P |
This specifies the path of the FIFO to write to. Must be an absolute path. If the path does not exist, it will be created when MPD is started, and removed when MPD is stopped. The FIFO will be created with the same user and group as MPD is running as. Default permissions can be modified by using the builtin shell command umask. If a FIFO already exists at the specified path it will be reused, and will not be removed when MPD is stopped. You can use the “mkfifo” command to create this, and then you may modify the permissions to your liking. |
haiku¶
Use the SoundPlayer API on the Haiku operating system.
This plugin is unmaintained and contains known bugs. It will be removed soon, unless there is a new maintainer.
jack¶
The jack plugin connects to a JACK server.
On Windows, this plugin loads libjack64.dll at runtime. This
means you need to download and install the JACK windows build.
Setting |
Description |
|---|---|
client_name NAME |
The name of the JACK client. Defaults to “Music Player Daemon”. |
server_name NAME |
Optional name of the JACK server. |
autostart yes|no |
If set to yes, then libjack will automatically launch the JACK daemon. Disabled by default. |
source_ports A,B |
The names of the JACK source ports to be created. By default, the ports “left” and “right” are created. To use more ports, you have to tweak this option. |
destination_ports A,B |
The names of the JACK destination ports to connect to. |
auto_destination_ports yes|no |
If set to yes, then MPD will automatically create connections between the send ports of MPD and receive ports of the first sound card; if set to no, then MPD will only create connections to the contents of destination_ports if it is set. Enabled by default. |
ringbuffer_size NBYTES |
Sets the size of the ring buffer for each channel. Do not configure this value unless you know what you’re doing. |
httpd¶
The httpd plugin creates a HTTP server, similar to ShoutCast / IceCast. HTTP streaming clients like mplayer, VLC, and mpv can connect to it.
It is highly recommended to configure a fixed format, because a stream cannot switch its audio format on-the-fly when the song changes.
Setting |
Description |
|---|---|
port P |
Binds the HTTP server to the specified port. |
bind_to_address ADDR |
Binds the HTTP server to the specified address (IPv4, IPv6 or local socket). Multiple addresses in parallel are not supported. |
encoder NAME |
Chooses an encoder plugin. A list of encoder plugins can be found in the encoder plugin reference Encoder plugins. |
max_clients MC |
Sets a limit, number of concurrent clients. When set to 0 no limit will apply. |
null¶
The null plugin does nothing. It discards everything sent to it.
Setting |
Description |
|---|---|
sync yes|no |
If set to no, then the timer is disabled - the device will accept PCM chunks at arbitrary rate (useful for benchmarking). The default behaviour is to play in real time. |
oss¶
The “Open Sound System” plugin is supported on most Unix platforms.
On Linux, OSS has been superseded by ALSA. Use the ALSA output plugin alsa instead of this one on Linux.
Setting |
Description |
|---|---|
device PATH |
Sets the path of the PCM device. If not specified, then MPD will attempt to open /dev/sound/dsp and /dev/dsp. |
dop yes|no |
If set to yes, then DSD over PCM according to the DoP standard is enabled. This wraps DSD samples in fake 24 bit PCM, and is understood by some DSD capable products, but may be harmful to other hardware. Therefore, the default is no and you can enable the option at your own risk. |
The according hardware mixer plugin understands the following settings:
Setting |
Description |
|---|---|
mixer_device DEVICE |
Sets the OSS mixer device path, defaulting to /dev/mixer. |
mixer_control NAME |
Choose a mixer control, defaulting to PCM. |
openal¶
The “OpenAL” plugin uses libopenal. It is supported on many platforms. Use only if there is no native plugin for your operating system.
Setting |
Description |
|---|---|
device NAME |
Sets the device which should be used. This can be any valid OpenAL device name. If not specified, then libopenal will choose a default device. |
osx¶
The “Mac OS X” plugin uses Apple’s CoreAudio API.
Setting |
Description |
|---|---|
device NAME |
Sets the device which should be used. Uses device names as listed in the “Audio Devices” window of “Audio MIDI Setup”. |
hog_device yes|no |
Hog the device. This means that it takes exclusive control of the audio output device it is playing through, and no other program can access it. |
dop yes|no |
If set to yes, then DSD over PCM according to the DoP standard is enabled. This wraps DSD samples in fake 24 bit PCM, and is understood by some DSD capable products, but may be harmful to other hardware. Therefore, the default is no and you can enable the option at your own risk. Under macOS you must make sure to select a physical mode on the output device which supports at least 24 bits per channel as the Mac OS X plugin only changes the sample rate. |
channel_map SOURCE,SOURCE,… |
Specifies a channel map. If your audio device has more than two outputs this allows you to route audio to auxillary outputs. For predictable results you should also specify a “format” with a fixed number of channels, e.g. “::2”. The number of items in the channel map must match the number of output channels of your output device. Each list entry specifies the source for that output channel; use “-1” to silence an output. For example, if you have a four-channel output device and you wish to send stereo sound (format “::2”) to outputs 3 and 4 while leaving outputs 1 and 2 silent then set the channel map to “-1,-1,0,1”. In this example ‘0’ and ‘1’ denote the left and right channel respectively. The channel map may not refer to outputs that do not exist according to the format. If the format is “::1” (mono) and you have a four-channel sound card then “-1,-1,0,0” (dual mono output on the second pair of sound card outputs) is a valid channel map but “-1,-1,0,1” is not because the second channel (‘1’) does not exist when the output is mono. |
pipe¶
The pipe plugin starts a program and writes raw PCM data into its standard input.
Setting |
Description |
|---|---|
command CMD |
This command is invoked with the shell. |
pipewire¶
Connect to a PipeWire server. Requires
libpipewire.
Setting |
Description |
|---|---|
target NAME |
Link to the given target. If not specified, let the PipeWire
manager select a target. To get a list of available targets,
type |
remote NAME |
The name of the remote to connect to. The default is
|
dsd yes|no |
Enable DSD playback. This requires PipeWire 0.38. |
pulse¶
The pulse plugin connects to a PulseAudio server. Requires libpulse.
Setting |
Description |
|---|---|
server HOSTNAME |
Sets the host name of the PulseAudio server. By default, MPD connects to the local PulseAudio server. |
sink NAME |
Specifies the name of the PulseAudio sink MPD should play on. |
media_role ROLE |
Specifies a custom media role that MPD reports to PulseAudio. Default is “music”. (optional). |
scale_volume FACTOR |
Specifies a linear scaling coefficient (ranging from 0.5 to 5.0) to apply when adjusting volume through MPD. For example, chosing a factor equal to |
recorder¶
The recorder plugin writes the audio played by MPD to a file. This may be useful for recording radio streams.
Setting |
Description |
|---|---|
path P |
Write to this file. |
format_path P |
An alternative to path which provides a format string referring to tag values. The special tag iso8601 emits the current date and time in ISO8601 format (UTC). Every time a new song starts or a new tag gets received from a radio station, a new file is opened. If the format does not render a file name, nothing is recorded. A tag name enclosed in percent signs (‘%’) is replaced with the tag value. Example: |
encoder NAME |
Chooses an encoder plugin. A list of encoder plugins can be found in the encoder plugin reference Encoder plugins. |
shout¶
The shout plugin connects to a ShoutCast or IceCast server using libshout. It forwards tags to this server.
You must set a format.
Setting |
Description |
|---|---|
host HOSTNAME |
|
port PORTNUMBER |
Connect to this port number on the specified host. |
protocol icecast2|icecast1|shoutcast |
Specifies the protocol that wil be used to connect to the server. The default is “icecast2”. |
tls disabled|auto|auto_no_plain|rfc2818|rfc2817 |
Specifies what kind of TLS to use. The default is “disabled” (no TLS). |
mount URI |
Mounts the MPD stream in the specified URI. |
user USERNAME |
Sets the user name for submitting the stream to the server. Default is “source”. |
password PWD |
Sets the password for submitting the stream to the server. |
name NAME |
Sets the name of the stream. |
genre GENRE |
Sets the genre of the stream (optional). |
description DESCRIPTION |
Sets a short description of the stream (optional). |
url URL |
Sets a URL associated with the stream (optional). |
public yes|no |
Specifies whether the stream should be “public”. Default is no. |
encoder PLUGIN |
Chooses an encoder plugin. Default is vorbis vorbis. A list of encoder plugins can be found in the encoder plugin reference Encoder plugins. |
sles¶
Plugin using the OpenSL ES audio API. Its primary use is local playback on Android, where ALSA is not available. It supports 16 bit and floating point samples.
snapcast¶
Snapcast is a multiroom client-server audio player. This plugin allows MPD to act as a Snapcast server. Snapcast clients connect to it and receive audio data from MPD.
You must set a format.
Setting |
Description |
|---|---|
port P |
Binds the Snapcast server to the specified port. The default
port is |
bind_to_address ADDR |
Binds the Snapcast server to the specified address. Multiple
addresses in parallel are not supported. The default is to
bind on all addresses on port |
zeroconf yes|no |
Publish the Snapcast server as service type |
solaris¶
The “Solaris” plugin runs only on SUN Solaris, and plays via /dev/audio.
Setting |
Description |
|---|---|
device PATH |
Sets the path of the audio device, defaults to /dev/audio. |
wasapi¶
The Windows Audio Session API plugin uses WASAPI, which is supported started from Windows Vista. It is recommended if you are using Windows.
Setting |
Description |
|---|---|
device NAME |
Sets the device which should be used. This can be any valid audio device name, or index number. The default value is “”, which makes WASAPI choose the default output device. |
enumerate yes|no |
Enumerate all devices in log while playing started. Useful for device configuration. The default value is “no”. |
exclusive yes|no |
Exclusive mode blocks all other audio source, and get best audio quality without resampling. Stopping playing release the exclusive control of the output device. The default value is “no”. |
dop yes|no |
Enable DSD over PCM. Require exclusive mode. The default value is “no”. |
Filter plugins¶
ffmpeg¶
Configures a FFmpeg filter graph.
This plugin requires building with libavfilter (FFmpeg).
Setting |
Description |
|---|---|
graph “…” |
Specifies the |
hdcd¶
Decode HDCD.
This plugin requires building with libavfilter (FFmpeg).
normalize¶
Normalize the volume during playback (at the expense of quality).
null¶
A no-op filter. Audio data is returned as-is.
route¶
Reroute channels.
Setting |
Description |
|---|---|
routes “0>0, 1>1, …” |
Specifies the channel mapping. |
Playlist plugins¶
asx¶
Reads .asx playlist files.
cue¶
Reads .cue files.
embcue¶
Reads CUE sheets from the CUESHEET tag of song files.
m3u¶
Reads .m3u playlist files.
extm3u¶
Reads extended .m3u playlist files.
flac¶
Reads the cuesheet metablock from a FLAC file.
pls¶
Reads .pls playlist files.
rss¶
Reads music links from .rss files.
soundcloud¶
Download playlist from SoundCloud. It accepts URIs starting with soundcloud://.
Setting |
Description |
|---|---|
apikey KEY |
An API key to access the SoundCloud servers. |
xspf¶
Reads XSPF playlist files.
Archive plugins¶
bz2¶
Allows to load single bzip2 compressed files using libbz2. Does not support seeking.
zzip¶
Allows to load music files from ZIP archives using zziplib.
iso¶
Allows to load music files from ISO 9660 images using libcdio.
Developer’s Manual¶
Introduction¶
This is a guide for those who wish to hack on the MPD source code. MPD is an open project, and we are always happy about contributions. So far, more than 150 people have contributed patches. This document is work in progress. Most of it may be incomplete yet. Please help!
Code Style¶
indent with tabs (width 8)
don’t write CPP when you can write C++: use inline functions and constexpr instead of macros
comment your code, document your APIs
the code should be C++17 compliant, and must compile with GCC 8 and clang 5
all code must be exception-safe
classes and functions names use CamelCase; variables are lower-case with words separated by underscore
Some example code:
Foo(const char *abc, int xyz)
{
if (abc == nullptr) {
LogWarning("Foo happened!");
return -1;
}
return xyz;
}
Error handling¶
If an error occurs, throw a C++ exception, preferably derived from
std::runtime_error. The function’s API documentation should
mention that. If a function cannot throw exceptions, add
noexcept to its prototype.
Some parts of MPD use callbacks to report completion; the handler
classes usually have an “error” callback which receives a
std::exception_ptr
(e.g. BufferedSocket::OnSocketError()). Wrapping errors in
std::exception_ptr allows propagating details about the error
across thread boundaries to the entity which is interested in handling
it (e.g. giving the MPD client details about an I/O error caught by
the decoder thread).
Out-of-memory errors (i.e. std::bad_alloc) do not need to be
handled. Some operating systems such as Linux do not report
out-of-memory to userspace, and instead kill a process to recover.
Even if we know we are out of memory, there is little we can do except
for aborting the process quickly. Any other attempts to give back
memory may cause page faults on the way which make the situation
worse.
Error conditions which are caused by a bug do not need to be handled
at runtime; instead, use assert() to detect them in debug
builds.
git Branches¶
There are two active branches in the git repository:
the “unstable” branch called
masterwhere new features are merged. This will become the next major release eventually.the “stable” branch (currently called
v0.22.x) where only bug fixes are merged.
Once MPD 0.23 is released, a new branch called v0.23.x
will be created for 0.23 bug-fix releases; after that, v0.22.x
will eventually cease to be maintained.
After bug fixes have been added to the “stable” branch, it will be
merged into master. This ensures that all known bugs are fixed in
all active branches.
Hacking The Source¶
MPD sources are managed in a git repository on Github.
Always write your code against the latest git:
git clone git://github.com/MusicPlayerDaemon/MPD
If you already have a clone, update it:
git pull --rebase git://github.com/MusicPlayerDaemon/MPD master
You can do without --rebase, but we recommend that you rebase
your repository on the “master” repository all the time.
Configure with the option --werror. Enable as many plugins as
possible, to be sure that you don’t break any disabled code.
Don’t mix several changes in one single patch. Create a separate patch for every change. Tools like stgit help you with that. This way, we can review your patches more easily, and we can pick the patches we like most first.
Basic stgit usage¶
stgit allows you to create a set of patches and refine all of them: you can go back to any patch at any time, and re-edit it (both the code and the commit message). You can reorder patches and insert new patches at any position. It encourages creating separate patches for tiny changes.
stgit needs to be initialized on a git repository:
stg init
Before you edit the code, create a patch:
stg new my-patch-name
stgit now asks you for the commit message.
Now edit the code. Once you’re finished, you have to “refresh” the patch, i.e. your edits are incorporated into the patch you have created:
stg refresh
You may now continue editing the same patch, and refresh it as often as you like. Create more patches, edit and refresh them.
To view the list of patches, type stg series. To go back to a specific patch, type stg goto my-patch-name; now you can re-edit it (don’t forget stg refresh when you’re finished with that patch).
When the whole patch series is finished, convert stgit patches to git commits:
stg commit
Submitting Patches¶
Submit pull requests on GitHub: https://github.com/MusicPlayerDaemon/MPD/pulls
Client Developer’s Manual¶
Introduction¶
MPD is a music player without a user interface. The user interface will be provided by independent clients, which connect to MPD over socket connections (TCP or local sockets).
This chapter describes how to develop a client.
Before you develop a new client, consider joining an existing client project. There are many clients, but few are mature; we need fewer, but better clients.
Client Libraries¶
There are many libraries which help with connecting to MPD. If you develop a MPD client, use a library instead of reinventing the wheel. The MPD website has a list of libraries: https://www.musicpd.org/libs/
Connecting to MPD¶
Do not hard-code your client to connect to localhost:6600.
Instead, use the defaults of the client library. For example, with
libmpdclient, don’t do:
c = mpd_connection_new("localhost", 6600, 30000);
Instead, do:
c = mpd_connection_new(NULL, 0, 0);
This way, the library can choose the best defaults, maybe derived from environment variables, so all MPD clients use the same settings.
If you need to reimplement those defaults (or if you are developing a client library), this is a good set of addresses to attempt to connect to:
if the environment variable
MPD_HOSTis set:$MPD_HOST:$MPD_PORT(MPD_PORTdefaulting to 6600)if the environment variable
XDG_RUNTIME_DIRis set:$XDG_RUNTIME_DIR/mpd/socket/run/mpd/socketlocalhost:$MPD_PORT(MPD_PORTdefaulting to 6600)
Environment Variables¶
The following environment variables should be obeyed by all clients (preferably by the client library):
MPD_HOST: the host (or local socket path) to connect to; on Linux, this may start with a@to connect to an abstract socket. To use a password with MPD, setMPD_HOSTtopassword@host(then abstract socket requires double@:password@@socket).MPD_PORT: the port number; defaults to 6600.MPD_TIMEOUT: timeout for connecting to MPD and for waiting for MPD’s response in seconds. A good default is 30 seconds.
Protocol¶
General protocol syntax¶
Protocol overview¶
The MPD command protocol exchanges line-based text records between client and server over TCP. Once the client is connected to the server, they conduct a conversation until the client closes the connection. The conversation flow is always initiated by the client.
All data between the client and the server is encoded in UTF-8.
The client transmits a command sequence, terminated by the
newline character \n. The server will
respond with one or more lines, the last of which will be a
completion code.
When the client connects to the server, the server will answer with the following line:
OK MPD version
where version is a version identifier such as
0.12.2. This version identifier is the version of the protocol
spoken, not the real version of the daemon. (There is no way to
retrieve this real version identifier from the connection.)
Requests¶
COMMAND [ARG...]
If arguments contain spaces, they should be surrounded by double quotation marks.
Argument strings are separated from the command and any other arguments by linear white-space (’ ‘ or ‘\t’).
Responses¶
A command returns OK on completion or
ACK some error on failure. These
denote the end of command execution.
Some commands return more data before the response ends with OK.
Each line is usually in the form NAME: VALUE. Example:
foo: bar
OK
Binary Responses¶
Some commands can return binary data. This is initiated by a line
containing binary: 1234 (followed as usual by a newline). After
that, the specified number of bytes of binary data follows, then a
newline, and finally the OK line.
If the object to be transmitted is large, the server may choose a reasonable chunk size and transmit only a portion. The maximum chunk size can be changed by clients with the binarylimit command.
Usually, the response also contains a size line which specifies
the total (uncropped) size, and the command usually has a way to
specify an offset into the object; this way, the client can copy the
whole file without blocking the connection for too long.
Example:
foo: bar
binary: 42
<42 bytes>
OK
Failure responses¶
The nature of the error can be gleaned from the information
that follows the ACK.
ACK lines are of the form:
ACK [error@command_listNum] {current_command} message_text
These responses are generated by a call to
commandError. They contain four separate
terms. Let’s look at each of them:
error: numeric value of one of theACK_ERRORconstants defined in src/protocol/Ack.hxx.command_listNum: offset of the command that caused the error in a Command List. An error will always cause a command list to terminate at the command that causes the error.current_command: name of the command, in a Command List, that was executing when the error occurred.message_text: some (hopefully) informative text that describes the nature of the error.
An example might help. Consider the following sequence sent from the client to the server:
command_list_begin
volume 86
play 10240
status
command_list_end
The server responds with:
ACK [50@1] {play} song doesn't exist: "10240"
This tells us that the play command, which was the second in the list
(the first or only command is numbered 0), failed with error 50. The
number 50 translates to ACK_ERROR_NO_EXIST – the song doesn’t
exist. This is reiterated by the message text which also tells us
which song doesn’t exist.
Command lists¶
To facilitate faster adding of files etc. you can pass a list of commands all at once using a command list. The command list begins with command_list_begin or command_list_ok_begin and ends with command_list_end.
It does not execute any commands until the list has ended. The
response is a concatentation of all individual responses.
On success for all commands,
OK is returned. If a command
fails, no more commands are executed and the appropriate
ACK error is returned. If
command_list_ok_begin is used,
list_OK is returned for each
successful command executed in the command list.
Ranges¶
Some commands (e.g. delete) allow specifying a
range in the form START:END (the END item is not included in
the range, similar to ranges in the Python programming language). If
END is omitted, then the maximum possible value is assumed.
Filters¶
All commands which search for songs (e.g. find and searchadd) share a common filter syntax:
find EXPRESSION
EXPRESSION is a string enclosed in parentheses which can be one
of:
(TAG == 'VALUE'): match a tag value; if there are multiple values of the given type, at least one must match.(TAG != 'VALUE'): mismatch a tag value; if there are multiple values of the given type, none of them must match. The special taganychecks all tag types.AlbumArtistlooks forVALUEinAlbumArtistand falls back toArtisttags ifAlbumArtistdoes not exist.VALUEis what to find. An empty value string means: match only if the given tag type does not exist at all; this implies that negation with an empty value checks for the existence of the given tag type.(TAG contains 'VALUE')checks if the given value is a substring of the tag value.(TAG =~ 'VALUE')and(TAG !~ 'VALUE')use a Perl-compatible regular expression instead of doing a simple string comparison. (This feature is only available if MPD was compiled withlibpcre)(file == 'VALUE'): match the full song URI (relative to the music directory).(base 'VALUE'): restrict the search to songs in the given directory (relative to the music directory).(modified-since 'VALUE'): compares the file’s time stamp with the given value (ISO 8601 or UNIX time stamp).(AudioFormat == 'SAMPLERATE:BITS:CHANNELS'): compares the audio format with the given value. See Global Audio Format for a detailed explanation.(AudioFormat =~ 'SAMPLERATE:BITS:CHANNELS'): matches the audio format with the given mask (i.e. one or more attributes may be*).(!EXPRESSION): negate an expression. Note that each expression must be enclosed in parentheses, e.g.(!(artist == 'VALUE'))(which is equivalent to(artist != 'VALUE'))(EXPRESSION1 AND EXPRESSION2 ...): combine two or more expressions with logical “and”. Note that each expression must be enclosed in parentheses, e.g.((artist == 'FOO') AND (album == 'BAR'))
The find commands are case sensitive, while search and related commands ignore case.
Prior to MPD 0.21, the syntax looked like this:
find TYPE VALUE
Escaping String Values¶
String values are quoted with single or double quotes, and special
characters within those values must be escaped with the backslash
(\). Keep in mind that the backslash is also the escape character
on the protocol level, which means you may need to use double
backslash.
Example expression which matches an artist named foo'bar":
(Artist == "foo\'bar\"")
At the protocol level, the command must look like this:
find "(Artist == \"foo\\'bar\\\"\")"
The double quotes enclosing the artist name must be escaped because
they are inside a double-quoted find parameter. The single quote
inside that artist name must be escaped with two backslashes; one to
escape the single quote, and another one because the backslash inside
the string inside the parameter needs to be escaped as well. The
double quote has three confusing backslashes: two to build one
backslash, and another one to escape the double quote on the protocol
level. Phew!
To reduce confusion, you should use a library such as libmpdclient which escapes command arguments for you.
Other Metadata¶
The response to lsinfo and similar commands may contain song tags and other metadata, specifically:
duration: the duration of the song in seconds; may contain a fractional part.time: likeduration, but as integer value. This is deprecated and is only here for compatibility with older clients. Do not use.Range: if this is a queue item referring only to a portion of the song file, then this attribute contains the time range in the formSTART-ENDorSTART-(open ended); bothSTARTandENDare time stamps within the song in seconds (may contain a fractional part). Example:60-120plays only the second minute; “180skips the first three minutes.Format: the audio format of the song (or an approximation to a format supported by MPD and the decoder plugin being used). When playing this file, theaudiovalue in the status response should be the same.Last-Modified: the time stamp of the last modification of the underlying file in ISO 8601 format. Example: “2008-09-28T20:04:57Z”
Recipes¶
Queuing¶
Often, users run MPD with random enabled, but want to be able to insert songs “before” the rest of the playlist. That is commonly called “queuing”.
MPD implements this by allowing the client to specify a “priority” for each song in the playlist (commands priod and priodid). A higher priority means that the song is going to be played before the other songs.
In “random” mode, MPD maintains an internal randomized sequence of songs. In this sequence, songs with a higher priority come first, and all songs with the same priority are shuffled (by default, all songs are shuffled, because all have the same priority “0”). When you increase the priority of a song, it is moved to the front of the sequence according to its new priority, but always after the current one. A song that has been played already (it’s “before” the current song in that sequence) will only be scheduled for repeated playback if its priority has become bigger than the priority of the current song. Decreasing the priority of a song will move it farther to the end of the sequence. Changing the priority of the current song has no effect on the sequence. During playback, a song’s priority is reset to zero.
Command reference¶
Note
For manipulating playlists and playing, there are two sets of commands. One set uses the song id of a song in the playlist, while another set uses the playlist position of the song. The commands using song ids should be used instead of the commands that manipulate and control playback based on playlist position. Using song ids is a safer method when multiple clients are interacting with MPD.
Querying MPD’s status¶
- clearerror
Clears the current error message in status (this is also accomplished by any command that starts playback).
- currentsong
Displays the song info of the current song (same song that is identified in status). Information about the current song is represented by key-value pairs, one on each line. The first pair must be the file key-value pair.
- idle [SUBSYSTEMS...] [1]
Waits until there is a noteworthy change in one or more of MPD’s subsystems. As soon as there is one, it lists all changed systems in a line in the format
changed: SUBSYSTEM, where SUBSYSTEM is one of the following:database: the song database has been modified after update.update: a database update has started or finished. If the database was modified during the update, thedatabaseevent is also emitted.stored_playlist: a stored playlist has been modified, renamed, created or deletedplaylist: the queue (i.e. the current playlist) has been modifiedplayer: the player has been started, stopped or seeked or tags of the currently playing song have changed (e.g. received from stream)mixer: the volume has been changedoutput: an audio output has been added, removed or modified (e.g. renamed, enabled or disabled)options: options like repeat, random, crossfade, replay gainpartition: a partition was added, removed or changedsticker: the sticker database has been modified.subscription: a client has subscribed or unsubscribed to a channelmessage: a message was received on a channel this client is subscribed to; this event is only emitted when the queue is emptyneighbor: a neighbor was found or lostmount: the mount list has changed
Change events accumulate, even while the connection is not in “idle” mode; no events get lost while the client is doing something else with the connection. If an event had already occurred since the last call, the new idle command will return immediately.
While a client is waiting for idle results, the server disables timeouts, allowing a client to wait for events as long as mpd runs. The idle command can be canceled by sending the command noidle (no other commands are allowed). MPD will then leave idle mode and print results immediately; might be empty at this time. If the optional
SUBSYSTEMSargument is used, MPD will only send notifications when something changed in one of the specified subsytems.
- status
Reports the current status of the player and the volume level.
partition: the name of the current partition (see Partition commands)volume:0-100(deprecated:-1if the volume cannot be determined)repeat:0or1random:0or1consume[2]:0or1playlist: 31-bit unsigned integer, the playlist version numberplaylistlength: integer, the length of the playliststate:play,stop, orpausesong: playlist song number of the current song stopped on or playingsongid: playlist songid of the current song stopped on or playingnextsong[2]: playlist song number of the next song to be playednextsongid[2]: playlist songid of the next song to be playedtime: total time elapsed (of current playing/paused song) in seconds (deprecated, useelapsedinstead)elapsed[3]: Total time elapsed within the current song in seconds, but with higher resolution.duration[5]: Duration of the current song in seconds.bitrate: instantaneous bitrate in kbpsxfade:crossfadein seconds (see Cross-Fading)mixrampdb:mixrampthreshold in dBmixrampdelay:mixrampdelayin secondsaudio: The format emitted by the decoder plugin during playback, format:samplerate:bits:channels. See Global Audio Format for a detailed explanation.updating_db:job iderror: if there is an error, returns message here
MPD may omit lines which have no (known) value. Older MPD versions used to have a “magic” value for “unknown”, e.g. “
volume: -1”.
- stats
Displays statistics.
artists: number of artistsalbums: number of albumssongs: number of songsuptime: daemon uptime in secondsdb_playtime: sum of all song times in the database in secondsdb_update: last db update in UNIX time (seconds since 1970-01-01 UTC)playtime: time length of music played
Playback options¶
- consume {STATE} [2]
Sets consume state to
STATE,STATEshould be 0 or 1. When consume is activated, each song played is removed from playlist.
- crossfade {SECONDS}
Sets crossfading between songs. See Cross-Fading.
- mixrampdb {deciBels}
Sets the threshold at which songs will be overlapped. See MixRamp.
- mixrampdelay {SECONDS}
Additional time subtracted from the overlap calculated by mixrampdb. A value of “nan” disables MixRamp overlapping and falls back to crossfading. See MixRamp.
- random {STATE}
Sets random state to
STATE,STATEshould be 0 or 1.
- repeat {STATE}
Sets repeat state to
STATE,STATEshould be 0 or 1.If enabled, MPD keeps repeating the whole queue (single mode disabled) or the current song (single mode enabled).
If random mode is also enabled, the playback order will be shuffled each time the queue gets repeated.
- setvol {VOL}
Sets volume to
VOL, the range of volume is 0-100.
getvol [8]
Read the volume. The result is a
volume:line like in status. If there is no mixer, MPD will emit an empty response. Example:getvol volume: 42 OK
- single {STATE} [2]
Sets single state to
STATE,STATEshould be0,1oroneshot[6]. When single is activated, playback is stopped after current song, or song is repeated if the ‘repeat’ mode is enabled.
- replay_gain_mode {MODE} [3]
Sets the replay gain mode. One of
off,track,album,auto. Changing the mode during playback may take several seconds, because the new settings do not affect the buffered data. This command triggers theoptionsidle event.
- replay_gain_status
Prints replay gain options. Currently, only the variable
replay_gain_modeis returned.
- volume {CHANGE}
Changes volume by amount
CHANGE. Deprecated, use setvol instead.
Controlling playback¶
- next
Plays next song in the playlist.
- pause {STATE}
Pause or resume playback. Pass
1to pause playback or0to resume playback. Without the parameter, the pause state is toggled.
- play [SONGPOS]
Begins playing the playlist at song number
SONGPOS.
- playid [SONGID]
Begins playing the playlist at song
SONGID.
- previous
Plays previous song in the playlist.
- seek {SONGPOS} {TIME}
Seeks to the position
TIME(in seconds; fractions allowed) of entrySONGPOSin the playlist.
- seekid {SONGID} {TIME}
Seeks to the position
TIME(in seconds; fractions allowed) of songSONGID.
- seekcur {TIME}
Seeks to the position
TIME(in seconds; fractions allowed) within the current song. If prefixed by+or-, then the time is relative to the current playing position.
- stop
Stops playing.
The Queue¶
Note
The “queue” used to be called “current playlist” or just “playlist”, but that was deemed confusing, because “playlists” are also files containing a sequence of songs. Those “playlist files” or “stored playlists” can be loaded into the queue and the queue can be saved into a playlist file, but they are not to be confused with the queue.
Many of the command names in this section reflect the old naming convention, but for the sake of compatibility, we cannot rename commands.
There are two ways to address songs within the queue: by their position and by their id.
The position is a 0-based index. It is unstable by design: if you move, delete or insert songs, all following indices will change, and a client can never be sure what song is behind a given index/position.
Song ids on the other hand are stable: an id is assigned to a song when it is added, and will stay the same, no matter how much it is moved around. Adding the same song twice will assign different ids to them, and a deleted-and-readded song will have a new id. This way, a client can always be sure the correct song is being used.
Many commands come in two flavors, one for each address type. Whenever possible, ids should be used.
- add {URI} [POSITION]
Adds the file
URIto the playlist (directories add recursively).URIcan also be a single file.The position parameter is the same as in addid. [10]
Clients that are connected via local socket may add arbitrary local files (URI is an absolute path). Example:
add "/home/foo/Music/bar.ogg"
- addid {URI} [POSITION]
Adds a song to the playlist (non-recursive) and returns the song id.
URIis always a single file or URL. For example:addid "foo.mp3" Id: 999 OK
If the second parameter is given, then the song is inserted at the specified position. If the parameter starts with
+or-, then it is relative to the current song [8]; e.g.+0inserts right after the current song and-0inserts right before the current song (i.e. zero songs between the current song and the newly added song).
- clear
Clears the queue.
- delete [{POS} | {START:END}]
Deletes a song from the playlist.
- deleteid {SONGID}
Deletes the song
SONGIDfrom the playlist
- move [{FROM} | {START:END}] {TO}
Moves the song at
FROMor range of songs atSTART:END[2] toTOin the playlist.If
TOstarts with+or-, then it is relative to the current song; e.g.+0moves to right after the current song and-0moves to right before the current song (i.e. zero songs between the current song and the moved range).
- moveid {FROM} {TO}
Moves the song with
FROM(songid) toTO(playlist index) in the playlist.If
TOstarts with+or-, then it is relative to the current song; e.g.+0moves to right after the current song and-0moves to right before the current song (i.e. zero songs between the current song and the moved song).
playlist
Displays the queue.
Do not use this, instead use playlistinfo.
- playlistfind {FILTER}
Search the queue for songs matching
FILTER(see Filters).
- playlistid {SONGID}
Displays a list of songs in the playlist.
SONGIDis optional and specifies a single song to display info for.
- playlistinfo [[SONGPOS] | [START:END]]
Displays a list of all songs in the playlist, or if the optional argument is given, displays information only for the song
SONGPOSor the range of songsSTART:END[2]
- playlistsearch {FILTER}
Search the queue for songs matching
FILTER(see Filters). Parameters have the same meaning as for find, except that search is not case sensitive.
- plchanges {VERSION} [START:END]
Displays changed songs currently in the playlist since
VERSION. Start and end positions may be given to limit the output to changes in the given range.To detect songs that were deleted at the end of the playlist, use playlistlength returned by status command.
- plchangesposid {VERSION} [START:END]
Displays changed songs currently in the playlist since
VERSION. This function only returns the position and the id of the changed song, not the complete metadata. This is more bandwidth efficient.To detect songs that were deleted at the end of the playlist, use playlistlength returned by status command.
- prio {PRIORITY} {START:END...}
Set the priority of the specified songs. A higher priority means that it will be played first when “random” mode is enabled.
A priority is an integer between 0 and 255. The default priority of new songs is 0.
- prioid {PRIORITY} {ID...}
Same as priod, but address the songs with their id.
- rangeid {ID} {START:END} [4]
Since MPD 0.19 Specifies the portion of the song that shall be played.
STARTandENDare offsets in seconds (fractional seconds allowed); both are optional. Omitting both (i.e. sending just “:”) means “remove the range, play everything”. A song that is currently playing cannot be manipulated this way.
- shuffle [START:END]
Shuffles the queue.
START:ENDis optional and specifies a range of songs.
- swap {SONG1} {SONG2}
Swaps the positions of
SONG1andSONG2.
- swapid {SONG1} {SONG2}
Swaps the positions of
SONG1andSONG2(both song ids).
- addtagid {SONGID} {TAG} {VALUE}
Adds a tag to the specified song. Editing song tags is only possible for remote songs. This change is volatile: it may be overwritten by tags received from the server, and the data is gone when the song gets removed from the queue.
- cleartagid {SONGID} [TAG]
Removes tags from the specified song. If
TAGis not specified, then all tag values will be removed. Editing song tags is only possible for remote songs.
Stored playlists¶
Playlists are stored inside the configured playlist directory. They are addressed with their file name (without the directory and without the .m3u suffix).
Some of the commands described in this section can be used to run playlist plugins instead of the hard-coded simple m3u parser. They can access playlists in the music directory (relative path including the suffix), playlists in arbitrary location (absolute path including the suffix; allowed only for clients that are connected via local socket), or remote playlists (absolute URI with a supported scheme).
- listplaylist {NAME}
Lists the songs in the playlist. Playlist plugins are supported.
- listplaylistinfo {NAME}
Lists the songs with metadata in the playlist. Playlist plugins are supported.
- listplaylists
Prints a list of the playlist directory. After each playlist name the server sends its last modification time as attribute “Last-Modified” in ISO 8601 format. To avoid problems due to clock differences between clients and the server, clients should not compare this value with their local clock.
- load {NAME} [START:END] [POSITION]
Loads the playlist into the current queue. Playlist plugins are supported. A range may be specified to load only a part of the playlist.
The
POSITIONparameter specifies where the songs will be inserted into the queue; it can be relative as described in addid. (This requires specifying the range as well; the special value 0: can be used if the whole playlist shall be loaded at a certain queue position.) [9]
- playlistadd {NAME} {URI} [POSITION]
Adds
URIto the playlist NAME.m3u. NAME.m3u will be created if it does not exist.The
POSITIONparameter specifies where the songs will be inserted into the playlist. [10]
- playlistclear {NAME}
Clears the playlist NAME.m3u.
- playlistdelete {NAME} {SONGPOS}
Deletes
SONGPOSfrom the playlist NAME.m3u.The second parameter can be a range. [10]
- playlistmove {NAME} {FROM} {TO}
Moves the song at position
FROMin the playlist NAME.m3u to the positionTO.
- rename {NAME} {NEW_NAME}
Renames the playlist NAME.m3u to NEW_NAME.m3u.
- rm {NAME}
Removes the playlist NAME.m3u from the playlist directory.
- save {NAME}
Saves the queue to NAME.m3u in the playlist directory.
The music database¶
- albumart {URI} {OFFSET}
Locate album art for the given song and return a chunk of an album art image file at offset
OFFSET.This is currently implemented by searching the directory the file resides in for a file called
cover.png,cover.jpg,cover.tifforcover.bmp.Returns the file size and actual number of bytes read at the requested offset, followed by the chunk requested as raw bytes (see Binary Responses), then a newline and the completion code.
Example:
albumart foo/bar.ogg 0 size: 1024768 binary: 8192 <8192 bytes> OK
- count {FILTER} [group {GROUPTYPE}]
Count the number of songs and their total playtime in the database matching
FILTER(see Filters). The following prints the number of songs whose title matches “Echoes”:count title Echoes
The group keyword may be used to group the results by a tag. The first following example prints per-artist counts while the next prints the number of songs whose title matches “Echoes” grouped by artist:
count group artist count title Echoes group artist
A group with an empty value contains counts of matching songs which don’t have this group tag. It exists only if at least one such song is found.
getfingerprint {URI}
Calculate the song’s audio fingerprint. Example (abbreviated fingerprint):
getfingerprint "foo/bar.ogg" chromaprint: AQACcEmSREmWJJmkIT_6CCf64... OKThis command is only available if MPD was built with
libchromaprint(-Dchromaprint=enabled).
- find {FILTER} [sort {TYPE}] [window {START:END}]
Search the database for songs matching
FILTER(see Filters).sortsorts the result by the specified tag. The sort is descending if the tag is prefixed with a minus (‘-‘). Withoutsort, the order is undefined. Only the first tag value will be used, if multiple of the same type exist. To sort by “Artist”, “Album” or “AlbumArtist”, you should specify “ArtistSort”, “AlbumSort” or “AlbumArtistSort” instead. These will automatically fall back to the former if “*Sort” doesn’t exist. “AlbumArtist” falls back to just “Artist”. The type “Last-Modified” can sort by file modification time.windowcan be used to query only a portion of the real response. The parameter is two zero-based record numbers; a start number and an end number.
- findadd {FILTER} [sort {TYPE}] [window {START:END}] [position POS]
Search the database for songs matching
FILTER(see Filters) and add them to the queue. Parameters have the same meaning as for find and searchadd.
- list {TYPE} {FILTER} [group {GROUPTYPE}]
Lists unique tags values of the specified type.
TYPEcan be any tag supported by MPD.Additional arguments may specify a filter. The group keyword may be used (repeatedly) to group the results by one or more tags.
The following example lists all album names, grouped by their respective (album) artist:
list album group albumartist
list filewas implemented in an early MPD version, but does not appear to make a lot of sense. It still works (to avoid breaking compatibility), but is deprecated.
- listall [URI]
Lists all songs and directories in
URI.Do not use this command. Do not manage a client-side copy of MPD’s database. That is fragile and adds huge overhead. It will break with large databases. Instead, query MPD whenever you need something.
- listallinfo [URI]
Same as listall, except it also returns metadata info in the same format as lsinfo
Do not use this command. Do not manage a client-side copy of MPD’s database. That is fragile and adds huge overhead. It will break with large databases. Instead, query MPD whenever you need something.
- listfiles {URI}
Lists the contents of the directory
URI, including files are not recognized by MPD.URIcan be a path relative to the music directory or an URI understood by one of the storage plugins. The response contains at least one line for each directory entry with the prefix “file: ” or “directory: “, and may be followed by file attributes such as “Last-Modified” and “size”.For example, “smb://SERVER” returns a list of all shares on the given SMB/CIFS server; “nfs://servername/path” obtains a directory listing from the NFS server.
- lsinfo [URI]
Lists the contents of the directory
URI. The response contains records starting withfile,directoryorplaylist, each followed by metadata (tags or other metadata).When listing the root directory, this currently returns the list of stored playlists. This behavior is deprecated; use “listplaylists” instead.
This command may be used to list metadata of remote files (e.g. URI beginning with “http://” or “smb://”).
Clients that are connected via local socket may use this command to read the tags of an arbitrary local file (URI is an absolute path).
- readcomments {URI}
Read “comments” (i.e. key-value pairs) from the file specified by “URI”. This “URI” can be a path relative to the music directory or an absolute path.
This command may be used to list metadata of remote files (e.g. URI beginning with “http://” or “smb://”).
The response consists of lines in the form “KEY: VALUE”. Comments with suspicious characters (e.g. newlines) are ignored silently.
The meaning of these depends on the codec, and not all decoder plugins support it. For example, on Ogg files, this lists the Vorbis comments.
- readpicture {URI} {OFFSET}
Locate a picture for the given song and return a chunk of the image file at offset
OFFSET. This is usually implemented by reading embedded pictures from binary tags (e.g. ID3v2’sAPICtag).Returns the following values:
size: the total file sizetype: the file’s MIME type (optional)binary: see Binary Responses
If the song file was recognized, but there is no picture, the response is successful, but is otherwise empty.
Example:
readpicture foo/bar.ogg 0 size: 1024768 type: image/jpeg binary: 8192 <8192 bytes> OK
- search {FILTER} [sort {TYPE}] [window {START:END}]
Search the database for songs matching
FILTER(see Filters). Parameters have the same meaning as for find, except that search is not case sensitive.
- searchadd {FILTER} [sort {TYPE}] [window {START:END}] [position POS]
Search the database for songs matching
FILTER(see Filters) and add them to the queue.Parameters have the same meaning as for search.
The
positionparameter specifies where the songs will be inserted. [8] It can be relative to the current song as in addid. [12]
- searchaddpl {NAME} {FILTER} [sort {TYPE}] [window {START:END}] [position POS]
Search the database for songs matching
FILTER(see Filters) and add them to the playlist namedNAME.If a playlist by that name doesn’t exist it is created.
Parameters have the same meaning as for search.
The
positionparameter specifies where the songs will be inserted. [11]
- update [URI]
Updates the music database: find new files, remove deleted files, update modified files.
URIis a particular directory or song/file to update. If you do not specify it, everything is updated.Prints
updating_db: JOBIDwhereJOBIDis a positive number identifying the update job. You can read the current job id in the status response.
- rescan [URI]
Same as update, but also rescans unmodified files.
Mounts and neighbors¶
A “storage” provides access to files in a directory tree. The most basic storage plugin is the “local” storage plugin which accesses the local file system, and there are plugins to access NFS and SMB servers.
Multiple storages can be “mounted” together, similar to the mount command on many operating systems, but without cooperation from the kernel. No superuser privileges are necessary, because this mapping exists only inside the MPD process.
- mount {PATH} {URI}
Mount the specified remote storage URI at the given path. Example:
mount foo nfs://192.168.1.4/export/mp3
- unmount {PATH}
Unmounts the specified path. Example:
unmount foo
- listmounts
Queries a list of all mounts. By default, this contains just the configured
music_directory. Example:listmounts mount: storage: /home/foo/music mount: foo storage: nfs://192.168.1.4/export/mp3 OK
- listneighbors
Queries a list of “neighbors” (e.g. accessible file servers on the local net). Items on that list may be used with the mount command. Example:
listneighbors neighbor: smb://FOO name: FOO (Samba 4.1.11-Debian) OK
Stickers¶
“Stickers” [2] are pieces of information attached to existing MPD objects (e.g. song files, directories, albums; but currently, they are only implemented for song). Clients can create arbitrary name/value pairs. MPD itself does not assume any special meaning in them.
The goal is to allow clients to share additional (possibly dynamic) information about songs, which is neither stored on the client (not available to other clients), nor stored in the song files (MPD has no write access).
Client developers should create a standard for common sticker names, to ensure interoperability.
Objects which may have stickers are addressed by their object type (“song” for song objects) and their URI (the path within the database for songs).
- sticker get {TYPE} {URI} {NAME}
Reads a sticker value for the specified object.
- sticker set {TYPE} {URI} {NAME} {VALUE}
Adds a sticker value to the specified object. If a sticker item with that name already exists, it is replaced.
- sticker delete {TYPE} {URI} [NAME]
Deletes a sticker value from the specified object. If you do not specify a sticker name, all sticker values are deleted.
- sticker list {TYPE} {URI}
Lists the stickers for the specified object.
- sticker find {TYPE} {URI} {NAME}
Searches the sticker database for stickers with the specified name, below the specified directory (URI). For each matching song, it prints the URI and that one sticker’s value.
- sticker find {TYPE} {URI} {NAME} = {VALUE}
Searches for stickers with the given value.
Other supported operators are: “
<”, “>”
Connection settings¶
- close
Closes the connection to MPD. MPD will try to send the remaining output buffer before it actually closes the connection, but that cannot be guaranteed. This command will not generate a response.
Clients should not use this command; instead, they should just close the socket.
- kill
Kills MPD.
Do not use this command. Send
SIGTERMto MPD instead, or better: let your service manager handle MPD shutdown (e.g. systemctl stop mpd).
- password {PASSWORD}
This is used for authentication with the server.
PASSWORDis simply the plaintext password.
- ping
Does nothing but return “OK”.
binarylimit SIZE [7]
Set the maximum binary response size for the current connection to the specified number of bytes.
A bigger value means less overhead for transmitting large entities, but it also means that the connection is blocked for a longer time.
- tagtypes
Shows a list of available tag types. It is an intersection of the
metadata_to_usesetting and this client’s tag mask.About the tag mask: each client can decide to disable any number of tag types, which will be omitted from responses to this client. That is a good idea, because it makes responses smaller. The following
tagtypessub commands configure this list.
- tagtypes disable {NAME...}
Remove one or more tags from the list of tag types the client is interested in. These will be omitted from responses to this client.
- tagtypes enable {NAME...}
Re-enable one or more tags from the list of tag types for this client. These will no longer be hidden from responses to this client.
- tagtypes clear
Clear the list of tag types this client is interested in. This means that MPD will not send any tags to this client.
- tagtypes all
Announce that this client is interested in all tag types. This is the default setting for new clients.
Partition commands¶
These commands allow a client to inspect and manage “partitions”. A partition is one frontend of a multi-player MPD process: it has separate queue, player and outputs. A client is assigned to one partition at a time.
- partition {NAME}
Switch the client to a different partition.
- listpartitions
Print a list of partitions. Each partition starts with a
partitionkeyword and the partition’s name, followed by information about the partition.
- newpartition {NAME}
Create a new partition.
- delpartition {NAME}
Delete a partition. The partition must be empty (no connected clients and no outputs).
- moveoutput {OUTPUTNAME}
Move an output to the current partition.
Audio output devices¶
- disableoutput {ID}
Turns an output off.
- enableoutput {ID}
Turns an output on.
- toggleoutput {ID}
Turns an output on or off, depending on the current state.
- outputs
Shows information about all outputs.
outputid: 0 outputname: My ALSA Device plugin: alsa outputenabled: 0 attribute: dop=0 OK
Return information:
outputid: ID of the output. May change between executionsoutputname: Name of the output. It can be any.outputenabled: Status of the output. 0 if disabled, 1 if enabled.
- outputset {ID} {NAME} {VALUE}
Set a runtime attribute. These are specific to the output plugin, and supported values are usually printed in the outputs response.
Reflection¶
- config
Dumps configuration values that may be interesting for the client. This command is only permitted to “local” clients (connected via local socket).
The following response attributes are available:
music_directory: The absolute path of the music directory.
- commands
Shows which commands the current user has access to.
- notcommands
Shows which commands the current user does not have access to.
- urlhandlers
Gets a list of available URL handlers.
- decoders
Print a list of decoder plugins, followed by their supported suffixes and MIME types. Example response:
plugin: mad suffix: mp3 suffix: mp2 mime_type: audio/mpeg plugin: mpcdec suffix: mpc
Client to client¶
Clients can communicate with each others over “channels”. A channel is created by a client subscribing to it. More than one client can be subscribed to a channel at a time; all of them will receive the messages which get sent to it.
Each time a client subscribes or unsubscribes, the global idle
event subscription is generated. In
conjunction with the channels
command, this may be used to auto-detect clients providing
additional services.
New messages are indicated by the message
idle event.
If your MPD instance has multiple partitions, note that client-to-client messages are local to the current partition.
- subscribe {NAME}
Subscribe to a channel. The channel is created if it does not exist already. The name may consist of alphanumeric ASCII characters plus underscore, dash, dot and colon.
- unsubscribe {NAME}
Unsubscribe from a channel.
- channels
Obtain a list of all channels. The response is a list of “channel:” lines.
- readmessages
Reads messages for this client. The response is a list of “channel:” and “message:” lines.
- sendmessage {CHANNEL} {TEXT}
Send a message to the specified channel.
Footnotes
mpd¶
SYNOPSIS¶
mpd [options] [CONF_FILE]
DESCRIPTION¶
MPD is a daemon for playing music. Music is played through the configured audio output(s) (which are generally local, but can be remote). The daemon stores info about all available music, and this info can be easily searched and retrieved. Player control, info retrieval, and playlist management can all be managed remotely.
MPD searches for a config file in $XDG_CONFIG_HOME/mpd/mpd.conf
then ~/.mpdconf then ~/.mpd/mpd.conf then /etc/mpd.conf or uses CONF_FILE.
Read more about MPD at http://www.musicpd.org/
OPTIONS¶
- --help¶
Output a brief help message.
- --kill¶
Kill the currently running mpd session. The pid_file parameter must be specified in the config file for this to work.
- --no-config¶
Don’t read from the configuration file.
- --no-daemon¶
Don’t detach from console.
- --stderr¶
Print messages to stderr.
- --verbose¶
Verbose logging.
- --version¶
Print version information.
FILES¶
$XDG_CONFIG_HOME/mpd/mpd.confUser configuration file (usually
~/.config/mpd/mpd.conf)./etc/mpd.confGlobal configuration file.
SEE ALSO¶
mpd.conf(5), mpc(1)
BUGS¶
If you find a bug, please report it at https://github.com/MusicPlayerDaemon/MPD/issues/
mpd.conf¶
DESCRIPTION¶
mpd.conf is the configuration file for mpd(1). If
not specified on the command line, MPD first searches for it at
$XDG_CONFIG_HOME/mpd/mpd.conf then at ~/.mpdconf then
at ~/.mpd/mpd.conf and then in /etc/mpd.conf.
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"
You can use include_optional instead if you want the included file to be optional; the directive will be ignored if the file does not exist:
include_optional "may_not_exist.conf"
See docs/mpdconf.example in the source tarball for an example
configuration file.
This manual is not complete, it lists only the most important options. Please read the MPD user manual for a complete configuration guide: http://www.musicpd.org/doc/user/
OPTIONAL PARAMETERS¶
- db_file <file>
This specifies where the db file will be stored.
- log_file <file>
This specifies where the log file should be located. The special value “syslog” makes MPD use the local syslog daemon.
- sticker_file <file>
The location of the sticker database. This is a database which manages dynamic information attached to songs.
- pid_file <file>
This specifies the file to save mpd’s process ID in.
- music_directory <directory>
This specifies the directory where music is located. If you do not configure this, you can only play streams.
- playlist_directory <directory>
This specifies the directory where saved playlists are stored. If you do not configure this, you cannot save playlists.
- state_file <file>
This specifies if a state file is used and where it is located. The state of mpd will be saved to this file when mpd is terminated by a TERM signal or by the kill command. When mpd is restarted, it will read the state file and restore the state of mpd (including the playlist).
- restore_paused <yes or no>
Put MPD into pause mode instead of starting playback after startup.
- user <username>
This specifies the user that MPD will run as, if set. MPD should never run as root, and you may use this option to make MPD change its user id after initialization. Do not use this option if you start MPD as an unprivileged user.
- port <port>
This specifies the port that mpd listens on. The default is 6600.
- log_level <level>
Suppress all messages below the given threshold. The following log levels are available:
error: errorswarning: warningsnotice: interesting informational messagesinfo: unimportant informational messagesverbose: debug messages (for developers and for troubleshooting)
The default is
notice.- follow_outside_symlinks <yes or no>
Control if MPD will follow symbolic links pointing outside the music dir. You must recreate the database after changing this option. The default is “yes”.
- follow_inside_symlinks <yes or no>
Control if MPD will follow symbolic links pointing inside the music dir, potentially adding duplicates to the database. You must recreate the database after changing this option. The default is “yes”.
- zeroconf_enabled <yes or no>
If yes, and MPD has been compiled with support for Avahi or Bonjour, service information will be published with Zeroconf. The default is yes.
- zeroconf_name <name>
If Zeroconf is enabled, this is the service name to publish. This name should be unique to your local network, but name collisions will be properly dealt with. The default is “Music Player @ %h”, where %h will be replaced with the hostname of the machine running MPD.
- audio_output
See DESCRIPTION and the various
AUDIO OUTPUT PARAMETERSsections for the format of this parameter. Multiple audio_output sections may be specified. If no audio_output section is specified, then MPD will scan for a usable audio output.- filesystem_charset <charset>
This specifies the character set used for the filesystem. A list of supported character sets can be obtained by running “iconv -l”. The default is determined from the locale when the db was originally created.
- save_absolute_paths_in_playlists <yes or no>
This specifies whether relative or absolute paths for song filenames are used when saving playlists. The default is “no”.
- auto_update <yes or no>
This specifies the whether to support automatic update of music database when files are changed in music_directory. The default is to disable autoupdate of database.
- auto_update_depth <N>
Limit the depth of the directories being watched, 0 means only watch the music directory itself. There is no limit by default.
REQUIRED AUDIO OUTPUT PARAMETERS¶
- type <type>
This specifies the audio output type. See the list of supported outputs in
mpd --versionfor possible values.- name <name>
This specifies a unique name for the audio output.
OPTIONAL AUDIO OUTPUT PARAMETERS¶
- format <sample_rate:bits:channels>
This specifies the sample rate, bits per sample, and number of channels of audio that is sent to the audio output device. See documentation for the
audio_output_formatparameter for more details. The default is to use whatever audio format is passed to the audio output. Any of the three attributes may be an asterisk to specify that this attribute should not be enforced- replay_gain_handler <software, mixer or none>
Specifies how replay gain is applied. The default is “software”, which uses an internal software volume control. “mixer” uses the configured (hardware) mixer control. “none” disables replay gain on this audio output.
- mixer_type <hardware, software or none>
Specifies which mixer should be used for this audio output: the hardware mixer (available for ALSA, OSS and PulseAudio), the software mixer or no mixer (“none”). By default, the hardware mixer is used for devices which support it, and none for the others.
FILES¶
$XDG_CONFIG_HOME/mpd/mpd.confUser configuration file (usually
~/.config/mpd/mpd.conf)./etc/mpd.confGlobal configuration file.
SEE ALSO¶
mpd(1), mpc(1)