Output plugins

alsa

The Advanced Linux Sound Architecture (ALSA) plugin uses libasound. It is recommended if you are using Linux.

SettingDescription
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.

The according hardware mixer plugin understands the following settings:

SettingDescription
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).

ao

The ao plugin uses the portable libao library. Use only if there is no native plugin for your operating system.

SettingDescription
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.

SettingDescription
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.

SettingDescription
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.

jack

The jack plugin connects to a JACK server.

SettingDescription
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.
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.

SettingDescription
port P Binds the HTTP server to the specified port.
bind_to_address ADDR Binds the HTTP server to the specified address (IPv4 or IPv6). 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.
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.

SettingDescription
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 instead of this one on Linux.

SettingDescription
device PATH 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:

SettingDescription
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.

SettingDescription
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.

SettingDescription
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.
sync_sample_rate yes|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_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.

SettingDescription
command CMD This command is invoked with the shell.

pulse

The pulse plugin connects to a PulseAudio server. Requires libpulse.

SettingDescription
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.

roar

The roar plugin connects to a RoarAudio server.

SettingDescription
server HOSTNAME The host name of the RoarAudio server. If not specified, then MPD will connect to the default locations.
role ROLE 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.

SettingDescription
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: ~/.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)

encoder NAME 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 using libshout. It forwards tags to this server.

You must set a format.

SettingDescription
host HOSTNAME Sets the host name of the ShoutCast / IceCast server.
port PORTNUMBER Connect to this port number on the specified host.
timeout SECONDS Set the timeout for the shout connection in seconds. Defaults to 2 seconds.
protocol icecast2|icecast1|shoutcast Specifies the protocol that wil be used to connect to the server. The default is "icecast2".
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. 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.

SettingDescription
device PATH Sets the path of the audio device, defaults to /dev/audio.