460 lines
19 KiB
Groff
460 lines
19 KiB
Groff
.TH mpd.conf 5
|
|
.SH NAME
|
|
mpd.conf \- Music Player Daemon configuration file
|
|
.SH DESCRIPTION
|
|
\fBmpd.conf\fP is the configuration file for mpd(1). If not specified on the
|
|
command line, MPD first searches for it at \fB~/.mpdconf\fP then at
|
|
\fB~/.mpd/mpd.conf\fP and then in \fB/etc/mpd.conf\fP.
|
|
|
|
Lines beginning with a "#" character are comments. All other non-empty lines
|
|
specify parameters and their values. These lines contain the parameter name
|
|
and parameter value (surrounded by double quotes) separated by whitespace
|
|
(either tabs or spaces). For example:
|
|
|
|
parameter "value"
|
|
|
|
The exception to this rule is the audio_output parameter, which is of the form:
|
|
|
|
audio_output {
|
|
.br
|
|
parameter1 "value"
|
|
parameter2 "value"
|
|
.br
|
|
}
|
|
|
|
Parameters that take a file or directory as an argument should use absolute
|
|
paths.
|
|
|
|
See \fBdocs/mpdconf.example\fP in the source tarball for an example
|
|
configuration file.
|
|
.SH REQUIRED PARAMETERS
|
|
.TP
|
|
.B 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".
|
|
.TP
|
|
.B follow_inside_symlinks <yes or no>
|
|
Control if MPD will follow symbolic links pointing outside the music dir, potentially
|
|
adding duplicates to the database.
|
|
You must recreate the database after changing this option.
|
|
The default is "yes".
|
|
.TP
|
|
.B db_file <file>
|
|
This specifies where the db file will be stored.
|
|
.TP
|
|
.B sticker_file <file>
|
|
The location of the sticker database. This is a database which
|
|
manages dynamic information attached to songs.
|
|
.TP
|
|
.B log_file <file>
|
|
This specifies where the log file should be located.
|
|
The special value "syslog" makes MPD use the local syslog daemon.
|
|
.SH OPTIONAL PARAMETERS
|
|
.TP
|
|
.B pid_file <file>
|
|
This specifies the file to save mpd's process ID in.
|
|
.TP
|
|
.B music_directory <directory>
|
|
This specifies the directory where music is located.
|
|
If you do not configure this, you can only play streams.
|
|
.TP
|
|
.B playlist_directory <directory>
|
|
This specifies the directory where saved playlists are stored.
|
|
If you do not configure this, you cannot save playlists.
|
|
.TP
|
|
.B 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).
|
|
.TP
|
|
.B 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.
|
|
.TP
|
|
.B bind_to_address <ip address or hostname or any>
|
|
This specifies which address mpd binds to and listens on. Multiple
|
|
bind_to_address parameters may be specified. The default is "any", which binds
|
|
to all available addresses.
|
|
|
|
To bind to a Unix domain socket, specify an absolute path. For a
|
|
system-wide MPD, we suggest the path "\fB/var/run/mpd/socket\fP".
|
|
.TP
|
|
.B port <port>
|
|
This specifies the port that mpd listens on. The default is 6600.
|
|
.TP
|
|
.B log_level <default, secure, or verbose>
|
|
This specifies how verbose logs are. "default" is minimal logging, "secure"
|
|
reports from what address a connection is opened, and when it is closed, and
|
|
"verbose" records excessive amounts of information for debugging purposes. The
|
|
default is "default".
|
|
.TP
|
|
.B 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.
|
|
.TP
|
|
.B 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".
|
|
.TP
|
|
.B password <password@permissions>
|
|
This specifies a password for access to mpd. The format is
|
|
"password@permissions" where permissions is a comma delimited list composed
|
|
of "read", "add", "control", and/or "admin". "read" allows for reading of the
|
|
database, displaying the current playlist, and current status of mpd. "add"
|
|
allows for adding songs and loading playlists. "control" allows for all other
|
|
player and playlist manipulations. "admin" allows the db to be updated and for
|
|
the client to kill mpd. An example value is "somePassword@read,add". Multiple
|
|
password parameters may be specified.
|
|
.TP
|
|
.B default_permissions <permissions>
|
|
This specifies the permissions of a client that has not been authenticated
|
|
using a password. The format of permissions is specified in the description of
|
|
the "password" config parameter. If no passwords are specified, the default is
|
|
"read,add,control,admin", otherwise it is "" (no permissions).
|
|
.TP
|
|
.B audio_output
|
|
See \fBDESCRIPTION\fP and the various \fBAUDIO OUTPUT PARAMETERS\fP sections
|
|
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.
|
|
.TP
|
|
.B audio_output_format <sample_rate:bits:channels>
|
|
This specifies the sample rate, bits per sample, and number of channels of
|
|
audio that is sent to each audio output. Note that audio outputs may specify
|
|
their own audio format which will be used for actual output to the audio
|
|
device. An example is "44100:16:2" for 44100Hz, 16 bits, and 2 channels. The
|
|
default is to use the audio format of the input file.
|
|
.TP
|
|
.B samplerate_converter <integer or prefix>
|
|
This specifies the libsamplerate converter to use. The supplied value should
|
|
either be an integer or a prefix of the name of a converter. The default is
|
|
"Fastest Sinc Interpolator".
|
|
|
|
At the time of this writing, the following converters are available:
|
|
.RS
|
|
.TP
|
|
Best Sinc Interpolator (0)
|
|
|
|
Band limited sinc interpolation, best quality, 97dB SNR, 96% BW.
|
|
.TP
|
|
Medium Sinc Interpolator (1)
|
|
|
|
Band limited sinc interpolation, medium quality, 97dB SNR, 90% BW.
|
|
.TP
|
|
Fastest Sinc Interpolator (2)
|
|
|
|
Band limited sinc interpolation, fastest, 97dB SNR, 80% BW.
|
|
.TP
|
|
ZOH Interpolator (3)
|
|
|
|
Zero order hold interpolator, very fast, very poor quality with audible
|
|
distortions.
|
|
.TP
|
|
Linear Interpolator (4)
|
|
|
|
Linear interpolator, very fast, poor quality.
|
|
.RE
|
|
.IP
|
|
For an up-to-date list of available converters, please see the libsamplerate
|
|
documentation (available online at <\fBhttp://www.mega-nerd.com/SRC/\fP>).
|
|
.TP
|
|
.B mixer_type <alsa, oss, software, hardware or disabled>
|
|
This specifies which mixer to use. The default is hardware and depends on
|
|
what audio output support mpd was built with. Options alsa and oss are
|
|
legacy and should not be used in new configs, but when set mixer_device
|
|
and mixer_control will apply.
|
|
.TP
|
|
.B mixer_device <mixer dev>
|
|
This specifies which mixer to use. The default for oss is "/dev/mixer"; the
|
|
default for alsa is "default". This option is deprecated and should not be
|
|
used. Look at the mixer_device option of corresponding output device instead.
|
|
.TP
|
|
.B mixer_control <mixer ctrl>
|
|
This specifies which mixer control to use (sometimes referred to as the
|
|
"device"). Examples of mixer controls are PCM, Line1, Master, etc. An example
|
|
for OSS is "Pcm", and an example for alsa is "PCM". This option is deprecated
|
|
and should not be used. Look at the mixer_control option of corresponding
|
|
output device instead.
|
|
.TP
|
|
.B replaygain <album or track>
|
|
If specified, mpd will adjust the volume of songs played using ReplayGain tags
|
|
(see <\fBhttp://www.replaygain.org/\fP>). 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. Currently only FLAC, Ogg Vorbis,
|
|
Musepack, and MP3 (through ID3v2 ReplayGain tags, not APEv2) are supported.
|
|
.TP
|
|
.B replaygain_preamp <-15 to 15>
|
|
This is the gain (in dB) applied to songs with ReplayGain tags.
|
|
.TP
|
|
.B volume_normalization <yes or no>
|
|
If yes, mpd will normalize the volume of songs as they play. The default is no.
|
|
.TP
|
|
.B audio_buffer_size <size in KiB>
|
|
This specifies the size of the audio buffer in kibibytes. The default is 2048,
|
|
large enough for nearly 12 seconds of CD-quality audio.
|
|
.TP
|
|
.B buffer_before_play <0-100%>
|
|
This specifies how much of the audio buffer should be filled before playing a
|
|
song. Try increasing this if you hear skipping when manually changing songs.
|
|
The default is 10%, a little over 1 second of CD-quality audio with the default
|
|
buffer size.
|
|
.TP
|
|
.B http_proxy_host <hostname>
|
|
Use to specify the proxy host used for HTTP connections.
|
|
.TP
|
|
.B http_proxy_port <port>
|
|
The port that the HTTP proxy host uses.
|
|
.TP
|
|
.B http_proxy_user <username>
|
|
If the HTTP proxy server requires authentication, this specifies the username.
|
|
.TP
|
|
.B http_proxy_password <password>
|
|
If the HTTP proxy server requires authentication, this specifies the password.
|
|
.TP
|
|
.B connection_timeout <seconds>
|
|
If a client does not send any new data in this time period, the connection is
|
|
closed. The default is 60.
|
|
.TP
|
|
.B max_connections <number>
|
|
This specifies the maximum number of clients that can be connected to mpd. The
|
|
default is 5.
|
|
.TP
|
|
.B max_playlist_length <number>
|
|
This specifies the maximum number of songs that can be in the playlist. The
|
|
default is 4096.
|
|
.TP
|
|
.B max_command_list_size <size in KiB>
|
|
This specifies the maximum size a command list can be. The default is 2048.
|
|
.TP
|
|
.B max_output_buffer_size <size in KiB>
|
|
This specifies the maximum size of the output buffer to a client. The default
|
|
is 8192.
|
|
.TP
|
|
.B 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.
|
|
.TP
|
|
.B id3v1_encoding <charset>
|
|
This specifies the character set which ID3v1 tags are encoded in. A list of
|
|
supported character sets can be obtained by running "iconv -l". The default is
|
|
to let libid3tag convert them (from ISO-8859-1, as the standard specifies) and
|
|
do no additional conversion.
|
|
.TP
|
|
.B gapless_mp3_playback <yes or no>
|
|
This specifies whether to support gapless playback of MP3s which have the
|
|
necessary headers. Useful if your MP3s have headers with incorrect
|
|
information. If you have such MP3s, it is highly recommended that you fix them
|
|
using vbrfix (available from <http://www.willwap.co.uk/Programs/vbrfix.php>)
|
|
instead of disabling gapless MP3 playback. The default is to support gapless
|
|
MP3 playback.
|
|
.TP
|
|
.B 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".
|
|
.TP
|
|
.B metadata_to_use <tags>
|
|
This specifies the tag types that will be scanned for and made available to
|
|
clients. Note that you must recreate (not update) your database for changes to
|
|
this parameter to take effect. Possible values are artist, album, title,
|
|
track, name, genre, date, composer, performer, comment, and disc. Multiple
|
|
tags may be specified as a comma separated list. An example value is
|
|
"artist,album,title,track". The special value "none" may be used alone to
|
|
disable all metadata. The default is to use all known tag types except for
|
|
comments.
|
|
.SH REQUIRED AUDIO OUTPUT PARAMETERS
|
|
.TP
|
|
.B type <type>
|
|
This specifies the audio output type. See the list of supported outputs in mpd
|
|
--version for possible values.
|
|
.TP
|
|
.B name <name>
|
|
This specifies a unique name for the audio output.
|
|
.SH OPTIONAL AUDIO OUTPUT PARAMETERS
|
|
.TP
|
|
.B 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
|
|
\fBaudio_output_format\fP parameter for more details. The default is to use
|
|
whatever audio format is passed to the audio output.
|
|
.SH OPTIONAL ALSA OUTPUT PARAMETERS
|
|
.TP
|
|
.B device <dev>
|
|
This specifies the device to use for audio output. The default is "default".
|
|
.TP
|
|
.B mixer_device <mixer dev>
|
|
This specifies which mixer to use. The default for oss is "/dev/mixer"; the
|
|
default for alsa is "default".
|
|
.TP
|
|
.B mixer_control <mixer ctrl>
|
|
This specifies which mixer control to use (sometimes referred to as the
|
|
"device"). Examples of mixer controls are PCM, Line1, Master, etc. An example
|
|
for OSS is "Pcm", and an example for alsa is "PCM".
|
|
.TP
|
|
.B use_mmap <yes or no>
|
|
Setting this allows you to use memory-mapped I/O. Certain hardware setups may
|
|
benefit from this, but most do not. Most users do not need to set this. The
|
|
default is to not use memory-mapped I/O.
|
|
.TP
|
|
.B auto_resample <yes or no>
|
|
Setting this to "no" disables ALSA's software resampling, if the
|
|
hardware does not support a specific sample rate. This lets MPD do
|
|
the resampling. "yes" is the default and allows ALSA to resample.
|
|
.TP
|
|
.B auto_channels <yes or no>
|
|
Setting this to "no" disables ALSA's channel conversion, if the
|
|
hardware does not support a specific number of channels. Default: "yes".
|
|
.TP
|
|
.B auto_format <yes or no>
|
|
Setting this to "no" disables ALSA's sample format conversion, if the
|
|
hardware does not support a specific sample format. Default: "yes".
|
|
.TP
|
|
.B buffer_time <time in microseconds>
|
|
This sets the length of the hardware sample buffer in microseconds. Increasing
|
|
it may help to reduce or eliminate skipping on certain setups. Most users do
|
|
not need to change this. The default is 500000 microseconds (0.5 seconds).
|
|
.TP
|
|
.B period_time <time in microseconds>
|
|
This sets the time between hardware sample transfers in microseconds.
|
|
Increasing this can reduce CPU usage while lowering it can reduce underrun
|
|
errors on bandwidth-limited devices. Some users have reported good results
|
|
with this set to 50000, but not all devices support values this high. Most
|
|
users do not need to change this. The default is 256000000 / sample_rate(kHz),
|
|
or 5804 microseconds for CD-quality audio.
|
|
.SH OPTIONAL OSS OUTPUT PARAMETERS
|
|
.TP
|
|
.B device <dev>
|
|
This specifies the device to use for audio output. The default is "/dev/dsp".
|
|
.SH OPTIONAL PULSE OUTPUT PARAMETERS
|
|
.TP
|
|
.B server <server list>
|
|
A space separated list of servers to try to connect to. See
|
|
<\fBhttp://www.pulseaudio.org/wiki/ServerStrings\fP> for more details. The
|
|
default is to let PulseAudio choose a server.
|
|
If you specify more than one server name, MPD tries to connect to one
|
|
after another until it successfully establishes a connection.
|
|
.TP
|
|
.B sink <sink>
|
|
The sink to output to. The default is to let PulseAudio choose a sink.
|
|
.SH REQUIRED JACK OUTPUT PARAMETERS
|
|
.TP
|
|
.B name <name>
|
|
The client name to use when connecting to JACK. The output ports <name>:left
|
|
and <name>:right will also be created for the left and right channels,
|
|
respectively.
|
|
.SH OPTIONAL JACK OUTPUT PARAMETERS
|
|
.TP
|
|
.B ports <left_port,right_port>
|
|
This specifies the left and right ports to connect to for the left and right
|
|
channels, respectively. The default is to let JACK choose a pair of ports.
|
|
.TP
|
|
.B ringbuffer_size <size in bytes>
|
|
This specifies the size of the ringbuffer in bytes. The default is 32768.
|
|
.SH OPTIONAL AO OUTPUT PARAMETERS
|
|
.TP
|
|
.B driver <driver>
|
|
This specifies the libao driver to use for audio output. Possible values
|
|
depend on what libao drivers are available. See
|
|
<\fBhttp://www.xiph.org/ao/doc/drivers.html\fP> 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.
|
|
.TP
|
|
.B options <opts>
|
|
This specifies the options to use for the selected libao driver. For oss, the
|
|
only option available is "dsp". For alsa09, the available options are: "dev",
|
|
"buf_size", and "periods". See <\fBhttp://www.xiph.org/ao/doc/drivers.html\fP>
|
|
for available options for some commonly used drivers. Options are assigned
|
|
using "=", and ";" is used to separate options. An example for oss:
|
|
"dsp=/dev/dsp". An example for alsa09: "dev=hw:0,0;buf_size=4096". The
|
|
default is "".
|
|
.TP
|
|
.B write_size <size in bytes>
|
|
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.
|
|
.SH REQUIRED FIFO OUTPUT PARAMETERS
|
|
.TP
|
|
.B path <path>
|
|
This specifies the path of the FIFO to output 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 \fBnot\fP 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.
|
|
.SH REQUIRED SHOUT OUTPUT PARAMETERS
|
|
.TP
|
|
.B name <name>
|
|
This specifies not only the unique audio output name, but also the stream
|
|
title.
|
|
.TP
|
|
.B host <hostname>
|
|
This specifies the hostname of the icecast server to connect to.
|
|
.TP
|
|
.B port <port>
|
|
This specifies the port of the icecast server to connect to.
|
|
.TP
|
|
.B mount <mountpoint>
|
|
This specifies the icecast mountpoint to use.
|
|
.TP
|
|
.B password <password>
|
|
This specifies the password to use when logging in to the icecast server.
|
|
.TP
|
|
.B quality <quality>
|
|
This specifies the encoding quality to use. The value must be between 0
|
|
and 10. Fractional values, such as 2.5, are permitted. Either the quality or
|
|
the bitrate parameter must be specified, but not both. For Ogg, a
|
|
higher quality number produces higher quality output. For MP3, it's
|
|
just the opposite, with lower numbers producing higher quality output.
|
|
.TP
|
|
.B bitrate <kbps>
|
|
This specifies the bitrate to use for encoding. Either the quality or the
|
|
bitrate parameter must be specified, but not both.
|
|
.TP
|
|
.B format <sample_rate:bits:channels>
|
|
This specifies the sample rate, bits per sample, and number of channels to use
|
|
for encoding.
|
|
.SH OPTIONAL SHOUT OUTPUT PARAMETERS
|
|
.TP
|
|
.B encoding <encoding>
|
|
This specifies which output encoding to use. Should be either "ogg"
|
|
or "mp3", "mp3" is needed for shoutcast streaming. The default is "ogg".
|
|
.TP
|
|
.B protocol <protocol>
|
|
This specifies the protocol that wil be used to connect to the
|
|
icecast/shoutcast server. The options are "shoutcast", "icecast1" and
|
|
"icecast2". The default is "icecast2".
|
|
.TP
|
|
.B user <username>
|
|
This specifies the username to use when logging in to the icecast server. The
|
|
default is "source".
|
|
.TP
|
|
.B public <yes or no>
|
|
This specifies whether to request that the stream be listed in all public
|
|
stream directories that the icecast server knows about. The default is no.
|
|
.TP
|
|
.B timeout <seconds>
|
|
This specifies the number of seconds to wait before giving up on trying to
|
|
connect to the icecast server. The default is 2 seconds.
|
|
.TP
|
|
.B description <description>
|
|
This specifies a description of the stream.
|
|
.TP
|
|
.B genre <genre>
|
|
This specifies the genre(s) of the stream.
|
|
.SH FILES
|
|
.TP
|
|
.BI ~/.mpdconf
|
|
User configuration file.
|
|
.TP
|
|
.BI /etc/mpd.conf
|
|
Global configuration file.
|
|
.SH SEE ALSO
|
|
mpd(1), mpc(1)
|