The Music Player Daemon - User's Manual Introduction 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 organizze 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 xjf mpd-version.tar.bz cd mpd-version Make sure that all the required libraries and build tools are installed. The INSTALL file has a list. 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 install
Configuration
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.
Configuring input plugins To configure an input plugin, add a input block to mpd.conf: input { plugin "lastfm" user "foo" password "bar" } 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.
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.
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.
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 an audio_output block 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), 24_3 (signed 24 bit integer samples, no padding, 3 bytes per sample), 32 (signed 32 bit integer samples). enabled yes|no Specifies whether this audio output is enabled when MPD is started. By default, all audio outputs are enabled. 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 accidently stopped. mixer_type hardware|software|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. replay_gain_handler software|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 filter, 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 input plugin without recompiling. By default, all plugins are enabled.
Using MPD
The client After you have installed, configured and started MPD, you choose a client to control the playback. The most basic client is mpc, which provides a command line interface. It is useful in shell scripts. Many people bind specific mpc commands to hotkeys. The MPD Wiki contains an extensive list of clients to choose from.
The music directory and the database The "music directory" is where you store your music files. MPD stores all relevant meta information about all songs in its "database". Whenever you add, modify or remove songs in the music directory, you have to update the database, for example with mpc: mpc update Depending on the size of your music collection and the speed of the storage, this can take a while. To exclude a file from the update, create a file called .mpdignore in its parent directory. Each line of that file may contain a list of shell wildcards.
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.
Plugin reference
Input plugins
<varname>curl</varname> Opens remote files or streams over HTTP. Setting Description proxy Sets the address of the HTTP proxy server. proxy_user, proxy_password Configures proxy authentication.
<varname>file</varname> Opens local files.
<varname>mms</varname> Plays streams with the MMS protocol.
<varname>cdio_paranoia</varname> Plays audio CDs. The URI has the form: "cdda://[DEVICE][/TRACK]". The simplest form cdda:// plays the whole disc in the default drive.
Decoder plugins
<varname>mikmod</varname> Module player based on MikMod. Setting Description sample_rate Sets the sample rate generated by libmikmod. Default is 44100.
Encoder plugins
<varname>flac</varname> 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).
<varname>lame</varname> 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.
<varname>null</varname> Does not encode anything, passes the input PCM data as-is.
<varname>twolame</varname> 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.
<varname>vorbis</varname> Encodes into Ogg Vorbis. Setting Description quality 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.
<varname>wave</varname> Encodes into WAV (lossless).
Output plugins
<varname>alsa</varname> The "Advanced Linux Sound Architecture" 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, ...). use_mmap yes|no If set to yes, then libasound will try to use memory mapped I/O. 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, ...).
<varname>ao</varname> The ao plugin uses the portable libao library.
<varname>fifo</varname> The fifo plugin writes raw PCM data to a FIFO (First In, First Out) file. The data can be read by another program.
<varname>ffado</varname> The ffado plugin connects to FireWire audio devices via libffado. Warning: this plugin was not tested successfully. I just couldn't keep libffado2 from crashing. Use at your own risk. Setting Description device NAME Sets the device which should be used, e.g. "hw:0".
<varname>jack</varname> 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.
<varname>mvp</varname> The mvp plugin uses the proprietary Hauppauge Media MVP interface. We do not know any user of this plugin, and we do not know if it actually works.
<varname>httpd</varname> The httpd plugin creates a HTTP server, similar to ShoutCast / IceCast. HTTP streaming clients like mplayer can connect to it. You must configure either quality or bitrate. 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, e.g. vorbis. quality Q Configures the encoder quality (for VBR) in the range -1 .. 10. bitrate BR Sets a constant encoder bit rate, in kilobit per second. max_clients MC Sets a limit, number of concurrent clients. When set to 0 no limit will apply.
<varname>null</varname> 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.
<varname>oss</varname> The "Open Sound System" plugin is supported on most Unix platforms. 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.
<varname>openal</varname> The "OpenAL" plugin uses libopenal. It is supported on many platforms. 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.
<varname>osx</varname> The "Mac OS X" plugin uses Apple's CoreAudio API.
<varname>pipe</varname> 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.
<varname>pulse</varname> The pulse plugin connects to a PulseAudio server. 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.
<varname>recorder</varname> The recorder plugin writes the audio played by MPD to a file. This may be useful for recording radio streams. You must configure either quality or bitrate. Setting Description path P Write to this file. encoder NAME Chooses an encoder plugin, e.g. vorbis. quality Q Configures the encoder quality (for VBR) in the range -1 .. 10. bitrate BR Sets a constant encoder bit rate, in kilobit per second.
<varname>shout</varname> The shout plugin connects to a ShoutCast or IceCast server. 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. 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). public yes|no Specifies whether the stream should be "public". Default is "no". encoder PLUGIN Sets the name of the encoder plugin. Default is "vorbis". "vorbis" and "lame" are valid encoder plugins (provided that you enabled them at compile time).
<varname>solaris</varname> 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.
Playlist plugins
<varname>lastfm</varname> Plays last.fm radio. Setting Description user USERNAME The last.fm user name. password PWD The last.fm password.
<varname>m3u</varname> Reads .m3u playlist files.
<varname>extm3u</varname> Reads extended .m3u playlist files.
<varname>pls</varname> Reads .pls playlist files.
<varname>xspf</varname> Reads XSPF playlist files.