The Music Player Daemon - User's ManualIntroduction
This document is work in progress. Most of it may be incomplete
yet. Please help!
MPD (Music Player Daemon) is, as the
name suggests, a server software allowing you to remotely play
your music, handle playlists, deliver music (HTTP streams with
various sub-protocols) and organize playlists.
It has been written with minimal resource usage and stability in
mind! Infact, it runs fine on a Pentium 75, allowing you to use
your cheap old PC to create a stereo system!
MPD supports also gapless playback,
buffered audio output, and crossfading!
The separate client and server design allows users to choose a
user interface that best suites their tastes independently of
the underlying daemon, which actually plays music!
Installation
We recommend that you use the software installation routines of
your distribution to install MPD.
Most operating systems have a MPD
package, which is very easy to install.
Installing on Debian/Ubuntu
Install the package MPD via APT:
apt-get 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...
Compiling from source
Download the source tarball from the
MPD home page and unpack
it:
tar xf mpd-version.tar.xz
cd mpd-version
Make sure that all the required libraries and build tools are
installed. The INSTALL file has a list.
For example, the following installs a fairly complete list of
build dependencies on Debian Wheezy:
apt-get install g++ \
libmad0-dev libmpg123-dev libid3tag0-dev \
libflac-dev libvorbis-dev libopus-dev \
libadplug-dev libaudiofile-dev libsndfile1-dev libfaad-dev \
libfluidsynth-dev libgme-dev libmikmod2-dev libmodplug-dev \
libmpcdec-dev libwavpack-dev libwildmidi-dev \
libsidplay2-dev libsidutils-dev libresid-builder-dev \
libavcodec-dev libavformat-dev \
libmp3lame-dev \
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 libroar-dev libshout3-dev \
libmpdclient-dev \
libnfs-dev libsmbclient-dev \
libupnp-dev \
libavahi-client-dev \
libsqlite3-dev \
libsystemd-daemon-dev libwrap0-dev \
libcppunit-dev xmlto \
libboost-dev \
libicu-dev
Now configure the source tree:
./configure
The --help argument shows a list of
compile-time options. When everything is ready and
configured, compile:
make
And install:
make installsystemd 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 only be installed when
MPD was configured with
--with-systemdsystemunitdir=/lib/systemd/system.
To enable socket activation, type:
systemctl enable mpd.socket
systemctl start mpd.socket
In this configuration, MPD will
ignore the bind_to_address and
port settings.
systemd user unit
You can launch MPD as a
systemd user unit. The service file will
only be installed when MPD was
configured with
--with-systemduserunitdir=/usr/lib/systemd/user
or
--with-systemduserunitdir=$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 mpdConfigurationThe Configuration FileMPD 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).
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"
}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.
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"
}
The following table lists the database
options valid for all plugins:
Name
Description
plugin
The name of the plugin.
More information can be found in the database plugin reference.
Configuring neighbor plugins
All neighbor plugins are disabled by default to avoid unwanted
overhead. To enable (and configure) a plugin, add a
neighbor block to
mpd.conf:
neighbors {
plugin "smbclient"
}
The following table lists the neighbor
options valid for all plugins:
Name
Description
plugin
The name of the plugin.
More information can be found in the neighbor plugin reference.
Configuring input plugins
To configure an input plugin, add a 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.
enabledyes|no
Allows you to disable a input plugin without
recompiling. By default, all plugins are enabled.
More information can be found in the input plugin reference.
Configuring decoder plugins
Most decoder plugins do not need any special configuration.
To configure a decoder, add a decoder block
to mpd.conf:
decoder {
plugin "wildmidi"
config_file "/etc/timidity/timidity.cfg"
}
The following table lists the decoder
options valid for all plugins:
Name
Description
plugin
The name of the plugin.
enabledyes|no
Allows you to disable a decoder plugin without
recompiling. By default, all plugins are enabled.
More information can be found in the decoder plugin reference.
Configuring encoder plugins
Encoders are used by some of the output plugins (such as shout). The
encoder settings are included in the
audio_output section. More information can
be found in the encoder plugin
reference.
Configuring audio outputs
Audio outputs are devices which actually play the audio chunks
produced by MPD. You can configure
any number of audio output devices, but there must be at least
one. If none is configured, MPD
attempts to auto-detect. Usually, this works quite well with
ALSA, OSS and on Mac OS X.
To configure an audio output manually, add one or more
audio_output blocks to
mpd.conf:
audio_output {
type "alsa"
name "my ALSA device"
device "hw:0"
}
The following table lists the audio_output
options valid for all plugins:
Name
Description
type
The name of the plugin.
name
The name of the audio output. It is visible to the
client. Some plugins also use it internally, e.g. as
a name registered in the PULSE server.
format
Always open the audio output with the specified
audio format
(samplerate:bits:channels),
regardless of the format of the input file. This is
optional for most plugins.
Any of the three attributes may be an asterisk to
specify that this attribute should not be enforced,
example: 48000:16:*.
*:*:* is equal to not having
a format specification.
The following values are valid for
bits: 8
(signed 8 bit integer samples),
16, 24 (signed
24 bit integer samples padded to 32 bit),
32 (signed 32 bit integer
samples), f (32 bit floating
point, -1.0 to 1.0), "dsd" means
DSD (Direct Stream Digital).
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).
enabledyes|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.
tagsyes|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_onyes|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_typehardware|software|null|none
Specifies which mixer should be used for this audio
output: the hardware mixer (available for ALSA, OSS and PulseAudio), the
software mixer, the "null" mixer
(null; allows setting the
volume, but with no effect; this can be used as a
trick to implement an external mixer) or no
mixer (none). By default, the
hardware mixer is used for devices which support it,
and none for the others.
replay_gain_handlersoftware|mixer|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.
Configuring filters
Filters are plugins which modify an audio stream.
To configure a filter, add a filter block
to mpd.conf:
filter {
plugin "volume"
name "software volume"
}
The following table lists the filter
options valid for all plugins:
Name
Description
plugin
The name of the plugin.
name
The name of the filter.
Configuring playlist plugins
Playlist plugins are used to load remote playlists. 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.
enabledyes|no
Allows you to disable a input plugin without
recompiling. By default, all plugins are enabled.
More information can be found in the playlist plugin reference.
Audio Format SettingsGlobal Audio Format
The setting audio_output_format forces
MPD to use one audio format for
all outputs. Doing that is usually not a good idea. The
values are the same as in format in the audio_output
section.
Resampler
Sometimes, music needs to be resampled before it can be
played; for example, CDs use a sample rate of 44,100 Hz
while many cheap audio chips can only handle 48,000 Hz.
Resampling reduces the quality and consumes a lot of CPU.
There are different options, some of them optimized for high
quality and others for low CPU usage, but you can't have
both at the same time. Often, the resampler is the
component that is responsible for most of
MPD's CPU usage. Since
MPD comes with high quality
defaults, it may appear that MPD
consumes more CPU than other software.
Check the resampler plugin
reference for a list of resamplers and how to
configure them.
Other SettingsSettingDescriptionmetadata_to_useTAG1,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.
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).
SettingDescriptionstate_filePATH
Specify the state file location. The parent
directory must be writable by the
MPD user
(+wx).
state_file_intervalSECONDS
Auto-save the state file this number of seconds
after each state change. Defaults to
120 (2 minutes).
Resource Limitations
These settings are various limitations to prevent
MPD from using too many
resources (denial of service).
SettingDescriptionconnection_timeoutSECONDS
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_connectionsNUMBER
This specifies the maximum number of clients that
can be connected to MPD
at the same time. Default is
5.
max_playlist_lengthNUMBER
The maximum number of songs that can be in the
playlist. Default is 16384.
max_command_list_sizeKBYTES
The maximum size a command list. Default is
2048 (2 MiB).
max_output_buffer_sizeKBYTES
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.
SettingDescriptionaudio_buffer_sizeKBYTES
Adjust the size of the internal audio buffer.
Default is 4096 (4 MiB).
buffer_before_playPERCENT
Control the percentage of the buffer which is filled
before beginning to play. Increasing this reduces
the chance of audio file skipping, at the cost of
increased time prior to audio playback. Default is
10%.
Advanced configurationSatellite setupMPD runs well on weak machines such
as the Raspberry
Pi. However, such hardware tends to not have storage
big enough to hold a music collection. Mounting music from a
file server can be very slow, especially when updating the
database.
One approach for optimization is running
MPD on the file server, which not
only exports raw files, but also provides access to a readily
scanned database. Example configuration:
music_directory "nfs://fileserver.local/srv/mp3"
#music_directory "smb://fileserver.local/mp3"
database {
plugin "proxy"
host "fileserver.local"
}
The music_directory
setting tells MPD to read files
from the given NFS server. It does this by connecting to the
server from userspace. This does not actually mount the file
server into the kernel's virtual file system, and thus
requires no kernel cooperation and no special privileges. It
does not even require a kernel with NFS support, only the
nfs
storage plugin (using the libnfs
userspace library). The same can be done with SMB/CIFS using
the smbclient
storage plugin (using libsmbclient).
The database
setting tells MPD to pass all
database queries on to the MPD
instance running on the file server (using the proxy
plugin).
Real-Time Scheduling
On Linux, MPD attempts to configure
real-time
scheduling for some threads that benefit from it.
This is only possible you allow MPD
to do it. This privilege is controlled by
RLIMIT_RTPRIORLIMIT_RTTIME. You can configure this
privilege with ulimit before launching
MPD:
ulimit -HS -r 50; mpd
Or you can use the prlimit program from the
util-linux package:
prlimit --rtprio=50 --rttime=unlimited mpd
The systemd service file shipped
with MPD comes with this setting.
This works only if the Linux kernel was compiled with
CONFIG_RT_GROUP_SCHED disabled. Use the
following command to check this option for your current
kernel:
zgrep ^CONFIG_RT_GROUP_SCHED /proc/config.gz
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 MPDThe client
After you have installed, configured and started
MPD, you choose a client to control
the playback.
The most basic client is mpc, which
provides a command line interface. It is useful in shell
scripts. Many people bind specific mpc
commands to hotkeys.
The MPD
Wiki contains an extensive list of clients to choose
from.
The music directory and the database
The "music directory" is where you store your music files.
MPD stores all relevant meta
information about all songs in its "database". Whenever you
add, modify or remove songs in the music directory, you have
to update the database, for example with
mpc:
mpc update
Depending on the size of your music collection and the speed
of the storage, this can take a while.
To exclude a file from the update, create a file called
.mpdignore in its parent directory. Each
line of that file may contain a list of shell wildcards.
Matching files in the current directory and all subdirectories
are excluded.
Metadata
When scanning or playing a song,
MPD parses its metadata. The
following tags are supported:
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 usageBit-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
sond chip cannot play 24 bit. It falls back to 16 bit,
discarding 8 bit.
However, this does not yet prove bit-perfect playback;
ALSA may be fooling
MPD that the audio format is
supported. To verify the format really being sent to the
physical sound chip, try:
cat /proc/asound/card*/pcm*p/sub*/hw_params
access: RW_INTERLEAVED
format: S16_LE
subformat: STD
channels: 2
rate: 44100 (44100/1)
period_size: 4096
buffer_size: 16384
Obey the "format" row, which indicates that the current
playback format is 16 bit (signed 16 bit integer, little
endian).
Check list for bit-perfect playback:
Use the ALSA output
plugin.
Disable sound processing inside
ALSA by configuring a
"hardware" device (hw:0,0 or
similar).
Don't use software volume (setting mixer_type).
Don't force MPD to use a
specific audio format (settings format,
audio_output_format).
Verify that you are really doing bit-perfect playback
using MPD's verbose log and
/proc/asound/card*/pcm*p/sub*/hw_params.
Some DACs can also indicate the audio format.
Direct Stream Digital (DSD)
DSD (Direct
Stream Digital) is a digital format that stores audio
as a sequence of single-bit values at a very high sampling
rate.
MPD understands the file formats
dff
and dsf. There
are three ways to play back DSD:
Native DSD playback. Requires
ALSA 1.0.27.1 or later, a sound
driver/chip that supports DSD and of course a DAC that
supports DSD.
DoP (DSD over PCM) playback. This wraps DSD inside fake
24 bit PCM according to the DoP
standard. Requires a DAC that supports DSD. No
support from ALSA and the sound chip required (except for
bit-perfect 24 bit PCM
support).
Convert DSD to PCM on-the-fly.
Native DSD playback is used automatically if available. DoP
is only used if enabled explicitly using the dop option,
because there is no way for MPD to
find out whether the DAC supports it. DSD to PCM conversion
is the fallback if DSD cannot be used directly.
Client HacksExternal 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.
TroubleshootingWhere to start
Make sure you have the latest MPD
version (via mpd --version, not
mpc version). All the time, bugs are found
and fixed, and your problem might be a bug that is fixed
already. Do not ask for help unless you have the latest
MPD version. The most common
excuse is when your distribution ships an old
MPD version - in that case, please
ask your distribution for help, and not the
MPD project.
Check the log file. Configure 'log_level
"verbose"' or pass
--verbose to mpd.
Sometimes, it is helpful to run MPD
in a terminal and follow what happens. This is how to do it:
mpd --stdout --no-daemon --verboseSupportGetting Help
The MPD project runs a forum and an IRC
channel (#mpd on Freenode) for requesting
help. Visit the
MPD help page for details
on how to get help.
Common ProblemsDatabase
I can't see my music in the
MPD database!
Check your music_directory
setting.
Does the MPD user
have read permission on all music files, and
read+execute permission on all music directories
(and all of their parent directories)?
Did you update the database? (mpc
update)
Did you enable all relevant decoder plugins at
compile time? mpd --version
will tell you.
MPD doesn't read ID3
tags!
You probably compiled MPD
without libid3tag.
mpd --version will tell you.
PlaybackI 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.
"Device or resource busy"
This ALSA error means that another program uses your
sound hardware exclusively. You can stop that
program to allow MPD to
use it.
Sometimes, this other program is
PulseAudio, which can
multiplex sound from several applications, to allow
them to share your sound chip. In this case, it
might be a good idea for MPD
to use PulseAudio
as well, instead of using ALSA directly.
Reporting Bugs
If you believe you found a bug in
MPD, report it on the bug
tracker.
Your bug report should contain:
the output of mpd --version
your configuration file
(mpd.conf)
relevant portions of the log file (--verbose)
be clear about what you expect MPD to do, and what is
actually happening
MPD crashes
All MPD crashes are bugs which
must be fixed by a developer, and you should write a bug
report. (Many crash bugs are caused by codec libraries
used by MPD, and then that
library must be fixed; but in any case, the
MPD bug tracker is a good place
to report it first if you don't know.)
A crash bug report needs to contain a "backtrace".
First of all, your MPD executable
must not be "stripped" (i.e. debug information deleted).
The executables shipped with Linux distributions are usually
stripped, but some have so-called "debug" packages (package
mpd-dbg or
mpd-dbgsym on Debian,
mpd-debug on other distributions).
Make sure this package is installed.
You can extract the backtrace from a core dump, or by
running MPD in a debugger, e.g.:
gdb --args mpd --stdout --no-daemon --verbose
run
As soon as you have reproduced the crash, type
"bt" on the gdb
command prompt. Copy the output to your bug report.
Plugin referenceDatabase pluginssimple
The default plugin. Stores a copy of the database in
memory. A file is used for permanent storage.
SettingDescriptionpath
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.
compressyes|no
Compress the database file using
gzip? Enabled by default (if
built with zlib).
proxy
Provides access to the database of another
MPD instance using
libmpdclient. This is useful when you
run mount the music directory via NFS/SMB, and the file
server already runs a MPD
instance. Only the file server needs to update the
database.
SettingDescriptionhost
The host name of the "master"
MPD instance.
port
The port number of the "master"
MPD instance.
keepaliveyes|no
Send TCP keepalive packets to the "master"
MPD instance? This option can
help avoid certain firewalls dropping inactive
connections, at the expensive of a very small amount of
additional network traffic. Disabled by default.
upnp
Provides access to UPnP media servers.
Storage pluginslocal
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".
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".
This plugin uses libnfs,
which supports only NFS version 3. Since
MPD is not allowed to bind to
"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: "insecure" does not mean that your NFS server is
insecure. A few decades ago, people thought the concept of
"privileged ports" would make network services "secure",
which was a fallacy. The absence of this obsolete
"security" measure means little.
Neighbor pluginssmbclient
Provides a list of SMB/CIFS servers on the local network.
upnp
Provides a list of UPnP servers on the local network.
Input pluginsalsa
Allows MPD on Linux to play audio
directly from a soundcard using the scheme
alsa://. Audio is formatted as 44.1 kHz
16-bit stereo (CD format). Examples:
mpc add alsa:// plays audio from device hw:0,0
mpc add alsa://hw:1,0 plays audio from device
hw:1,0
cdio_paranoia
Plays audio CDs. The URI has the form:
"cdda://[DEVICE][/TRACK]". The
simplest form cdda:// plays the whole
disc in the default drive.
SettingDescriptiondefault_byte_orderlittle_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.
curl
Opens remote files or streams over HTTP.
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 or specified in
~/.curlrc will be in effect.
SettingDescriptionproxy
Sets the address of the HTTP proxy server.
proxy_user,
proxy_password
Configures proxy authentication.
verify_peeryes|no
Verify the peer's SSL certificate? More
information.
verify_hostyes|no
Verify the certificate's name against host? 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.
nfs
Allows MPD to access files on
NFSv3 servers without actually mounting them (i.e. 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
Note that this usually requires enabling the "insecure" flag
in the server's /etc/exports file,
because MPD cannot bind to
so-called "privileged" ports. Don't fear: this will not
make your file server insecure; the flag was named in 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.oggDecoder pluginsadplug
Decodes AdLib files.
SettingDescriptionsample_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.
SettingDescriptionanalyzedurationVALUE
Sets the FFmpeg muxer option
analyzeduration, which specifies
how many microseconds are analyzed to probe the
input. The FFmpeg
formats documentation has more information.
probesizeVALUE
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 DFF files containing DSDIFF data (e.g. SACD rips).
SettingDescriptionlsbitfirstyes|no
Decode the least significant bit first. Default is
no.
dsf
Decodes DSF files containing DSDIFF data (e.g. SACD rips).
fluidsynth
MIDI decoder based on FluidSynth.
SettingDescriptionsample_rate
The sample rate that shall be synthesized by the
plugin. Defaults to 48000.
soundfont
The absolute path of the soundfont file. Defaults
to
/usr/share/sounds/sf2/FluidR3_GM.sf2.
gme
Video game music file emulator based on game-music-emu.
SettingDescriptionaccuracyyes|no
Enable more accurate sound emulation.
mad
Decodes MP3 files using libmad.
mikmod
Module player based on MikMod.
SettingDescriptionloopyes|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.
SettingDescriptionloop_count
Number of times to loop the module if it uses backward loops.
Default is 0 which prevents looping.
-1 loops forever.
mpcdec
Decodes Musepack files using
libmpcdec.
mpg123
Decodes MP3 files using libmpg123.
pcm
Read 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
libsidplay.
SettingDescriptionsonglength_databasePATH
Location of your songlengths file, as distributed
with the HVSC. The sidplay
plugin checks this for matching MD5 fingerprints.
See .
default_songlengthSECONDS
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.
filteryes|no
Turns the SID filter emulation on or off.
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.
SettingDescriptionconfig_file
The absolute path of the timidity config file. Defaults
to
/etc/timidity/timidity.cfg.
Encoder pluginsflac
Encodes into FLAC (lossless).
SettingDescriptioncompression
Sets the libFLAC compression
level. The levels range from 0 (fastest, least
compression) to 8 (slowest, most compression).
lame
Encodes into MP3 using the LAME
library.
SettingDescriptionquality
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.
SettingDescriptionbitrate
Sets the bit rate in kilobit per second.
twolame
Encodes into MP2 using the TwoLAME
library.
SettingDescriptionquality
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.
vorbis
Encodes into Ogg
Vorbis.
SettingDescriptionquality
Sets the quality for VBR. -1 is the lowest quality,
10 is the highest quality. 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. See below for a list of
known types.
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 are:
"very high"
"high" (the default)
"medium"
"low"
"quick"
threads
The number of libsoxr
threads. "0" means "automatic". The default is "1"
which disables multi-threading.
Output pluginsalsa
The Advanced
Linux Sound Architecture
(ALSA) plugin uses
libasound. It is recommended if you
are using Linux.
SettingDescriptiondeviceNAME
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_timeUS
Sets the device's buffer time in microseconds.
Don't change unless you know what you're doing.
period_timeUS
Sets the device's period time in microseconds.
Don't change unless you really know what you're
doing.
auto_resampleyes|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_channelsyes|no
If set to no, then
libasound will not attempt to
convert between different channel numbers.
auto_formatyes|no
If set to no, then
libasound will not attempt to
convert between different sample formats (16 bit, 24
bit, floating point, ...).
dopyes|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:
SettingDescriptionmixer_deviceDEVICE
Sets the ALSA mixer device name, defaulting to
default which lets ALSA
pick a value.
mixer_controlNAME
Choose a mixer control, defaulting to
PCM. Type amixer
scontrols to get a list of available
mixer controls.
mixer_indexNUMBER
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).
ao
The ao plugin uses the portable libao
library. Use only if there is no native plugin for your
operating system.
SettingDescriptiondriverD
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.
optionsO
Options to pass to the selected
libao driver.
write_sizeO
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.
SettingDescriptiondeviceNAME
The audio output device libsndio
will attempt to use. The default is "default" which
causes libsndio to select the first output device.
buffer_timeMS
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.
SettingDescriptionpathP
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.
jack
The jack plugin connects to a JACK
server.
SettingDescriptionclient_nameNAME
The name of the JACK
client. Defaults to "Music Player Daemon".
server_nameNAME
Optional name of the JACK
server.
autostartyes|no
If set to yes, then
libjack will automatically
launch the JACK daemon.
Disabled by default.
source_portsA,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_portsA,B
The names of the JACK
destination ports to connect to.
ringbuffer_sizeNBYTES
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.
SettingDescriptionportP
Binds the HTTP server to the specified port.
bind_to_addressADDR
Binds the HTTP server to the specified address (IPv4 or
IPv6). Multiple addresses in parallel are not supported.
encoderNAME
Chooses an encoder plugin. A list of encoder
plugins can be found in the encoder plugin
reference.
max_clientsMC
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.
SettingDescriptionsyncyes|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 instead of this one on Linux.
SettingDescriptiondevicePATH
Sets the path of the PCM device. If not specified,
then MPD will attempt to
open /dev/sound/dsp and
/dev/dsp.
The according hardware mixer plugin understands the
following settings:
SettingDescriptionmixer_deviceDEVICE
Sets the OSS mixer device path, defaulting to
/dev/mixer.
mixer_controlNAME
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.
SettingDescriptiondeviceNAME
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.
SettingDescriptiondeviceNAME
Sets the device which should be used. Uses device names as listed in the
"Audio Devices" window of "Audio MIDI Setup".
hog_deviceyes|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.
sync_sample_rateyes|no
Synchronize the sample rate. It will try to set the output device sample
rate to the corresponding sample rate of the file playing. If the output
device does not support the sample rate the track has, it will try to
select the best possible for each file.
channel_mapSOURCE,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.
SettingDescriptioncommandCMD
This command is invoked with the shell.
pulse
The pulse plugin connects to a PulseAudio
server.
SettingDescriptionserverHOSTNAME
Sets the host name of the
PulseAudio server. By
default, MPD connects to
the local PulseAudio
server.
sinkNAME
Specifies the name of the
PulseAudio sink
MPD should play on.
roar
The roar plugin connects to a RoarAudio
server.
SettingDescriptionserverHOSTNAME
The host name of the RoarAudio server. If not
specified, then MPD will
connect to the default locations.
roleROLE
The "role" that MPD
registers itself as in the RoarAudio server. The
default is "music".
recorder
The recorder plugin writes the audio
played by MPD to a file. This
may be useful for recording radio streams.
SettingDescriptionpathP
Write to this file.
format_pathP
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:
~/.mpd/recorder/%artist% -
%title%.ogg
Square brackets can be used to group a substring.
If none of the tags referred in the group can be
found, the whole group is omitted. Example:
[~/.mpd/recorder/[%artist% -
]%title%.ogg] (this omits the dash
when no artist tag exists; if title also doesn't
exist, no file is written)
The operators "|" (logical "or") and "&"
(logical "and") can be used to select portions of
the format string depending on the existing tag
values. Example:
~/.mpd/recorder/[%title|%name%].ogg
(use the "name" tag if no title exists)
encoderNAME
Chooses an encoder plugin. A list of encoder
plugins can be found in the encoder plugin
reference.
shout
The shout plugin connects to a ShoutCast
or IceCast
server. It forwards tags to this server.
You must set a format.
SettingDescriptionhostHOSTNAME
Sets the host name of the ShoutCast
/ IceCast
server.
portPORTNUMBER
Connect to this port number on the specified host.
timeoutSECONDS
Set the timeout for the shout connection in seconds.
Defaults to 2 seconds.
protocolicecast2|icecast1|shoutcast
Specifies the protocol that wil be used to connect
to the server. The default is
"icecast2".
mountURI
Mounts the MPD stream in
the specified URI.
userUSERNAME
Sets the user name for submitting the stream to the
server. Default is "source".
passwordPWD
Sets the password for submitting the stream to the
server.
nameNAME
Sets the name of the stream.
genreGENRE
Sets the genre of the stream (optional).
descriptionDESCRIPTION
Sets a short description of the stream (optional).
urlURL
Sets a URL associated with the stream (optional).
publicyes|no
Specifies whether the stream should be "public".
Default is no.
encoderPLUGIN
Chooses an encoder plugin. Default is vorbis.
A list of encoder plugins can be found in the encoder plugin
reference.
solaris
The "Solaris" plugin runs only on SUN Solaris, and plays via
/dev/audio.
SettingDescriptiondevicePATH
Sets the path of the audio device, defaults to
/dev/audio.
Playlist pluginsembcue
Reads CUE sheets from the "CUESHEET" tag of song files.
m3u
Reads .m3u playlist files.
extm3u
Reads extended .m3u playlist files.
pls
Reads .pls playlist files.
xspf
Reads XSPF
playlist files.