Output plugins
Prev | Chapter 9. Plugin reference | Next

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

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

### `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.

### `jack`

The `jack` plugin connects to a JACK server.

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

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

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

Setting | Description
--- | ---
`command` `CMD` | This command is invoked with the shell.

### `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.

### `roar`

The `roar` plugin connects to a RoarAudio server.

Setting | Description
--- | ---
`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.

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

Setting | Description
--- | ---
`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`.

Setting | Description
--- | ---
`device` `PATH` | Sets the path of the audio device, defaults to `/dev/audio`.

Prev | Up | Next
Resampler plugins | Home | Playlist plugins