diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/conf.py | 8 | ||||
| -rw-r--r-- | doc/developer.rst | 53 | ||||
| -rw-r--r-- | doc/meson.build | 83 | ||||
| -rw-r--r-- | doc/mpd.1 | 55 | ||||
| -rw-r--r-- | doc/mpd.1.rst | 59 | ||||
| -rw-r--r-- | doc/mpd.conf.5 | 180 | ||||
| -rw-r--r-- | doc/mpd.conf.5.rst | 189 | ||||
| -rw-r--r-- | doc/mpdconf.example | 15 | ||||
| -rw-r--r-- | doc/plugins.rst | 150 | ||||
| -rw-r--r-- | doc/protocol.rst | 109 | ||||
| -rw-r--r-- | doc/user.rst | 208 |
11 files changed, 747 insertions, 362 deletions
diff --git a/doc/conf.py b/doc/conf.py index b271647ad..7eccbef68 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -30,7 +30,7 @@ master_doc = 'index' # General information about the project. project = 'Music Player Daemon' -copyright = '2003-2018 The Music Player Daemon Project' +copyright = '2003-2020 The Music Player Daemon Project' author = 'Max Kellermann' # The version info for the project you're documenting, acts as replacement for @@ -38,7 +38,7 @@ author = 'Max Kellermann' # built documents. # # The short X.Y version. -version = '0.21.26' +version = '0.22' # The full version, including alpha/beta/rc tags. release = version @@ -212,3 +212,7 @@ html_static_path = ['_static'] # implements a search results scorer. If empty, the default will be used. # # html_search_scorer = 'scorer.js' +man_pages = [ + ('mpd.1', 'mpd', 'MPD documentation', [author], 1), + ('mpd.conf.5', 'mpd.conf', 'mpd.conf documentation', [author], 5) +] diff --git a/doc/developer.rst b/doc/developer.rst index 5296314f9..a534c0ec0 100644 --- a/doc/developer.rst +++ b/doc/developer.rst @@ -12,8 +12,7 @@ Code Style * indent with tabs (width 8) * don't write CPP when you can write C++: use inline functions and constexpr instead of macros * comment your code, document your APIs -* the code should be C++14 compliant, and must compile with :program:`GCC` 6.0 and :program:`clang` 3.4 -* report error conditions with C++ exceptions, preferable derived from :envvar:`std::runtime_error` +* the code should be C++17 compliant, and must compile with :program:`GCC` 8 and :program:`clang` 5 * all code must be exception-safe * classes and functions names use CamelCase; variables are lower-case with words separated by underscore @@ -31,6 +30,56 @@ Some example code: return xyz; } + +Error handling +============== + +If an error occurs, throw a C++ exception, preferably derived from +:code:`std::runtime_error`. The function's API documentation should +mention that. If a function cannot throw exceptions, add +:code:`noexcept` to its prototype. + +Some parts of MPD use callbacks to report completion; the handler +classes usually have an "error" callback which receives a +:code:`std::exception_ptr` +(e.g. :code:`BufferedSocket::OnSocketError()`). Wrapping errors in +:code:`std::exception_ptr` allows propagating details about the error +across thread boundaries to the entity which is interested in handling +it (e.g. giving the MPD client details about an I/O error caught by +the decoder thread). + +Out-of-memory errors (i.e. :code:`std::bad_alloc`) do not need to be +handled. Some operating systems such as Linux do not report +out-of-memory to userspace, and instead kill a process to recover. +Even if we know we are out of memory, there is little we can do except +for aborting the process quickly. Any other attempts to give back +memory may cause page faults on the way which make the situation +worse. + +Error conditions which are caused by a bug do not need to be handled +at runtime; instead, use :code:`assert()` to detect them in debug +builds. + + +git Branches +************ + +There are two active branches in the git repository: + +- the "unstable" branch called ``master`` where new features are + merged. This will become the next major release eventually. +- the "stable" branch (currently called ``v0.21.x``) where only bug + fixes are merged. + +Once :program:`MPD` 0.22 is released, a new branch called ``v0.22.x`` +will be created for 0.22 bug-fix releases; after that, ``v0.21.x`` +will eventually cease to be maintained. + +After bug fixes have been added to the "stable" branch, it will be +merged into ``master``. This ensures that all known bugs are fixed in +all active branches. + + Hacking The Source ****************** diff --git a/doc/meson.build b/doc/meson.build index d3a5ad12d..e6c1da420 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -1,33 +1,54 @@ -install_man(['mpd.1', 'mpd.conf.5']) +if not get_option('html_manual') + subdir_done() +endif -sphinx = find_program('sphinx-build') -sphinx_output = custom_target( - 'HTML documentation', - output: 'html', - input: [ - 'index.rst', 'user.rst', 'developer.rst', - 'plugins.rst', - 'protocol.rst', - 'conf.py', - ], - command: [sphinx, '-q', '-b', 'html', '-d', '@OUTDIR@/doctrees', meson.current_source_dir(), '@OUTPUT@'], - build_by_default: true, - install: true, - install_dir: join_paths(get_option('datadir'), 'doc', meson.project_name()), -) +sphinx = find_program('sphinx-build', required: get_option('documentation')) +if not sphinx.found() + subdir_done() +endif -custom_target( - 'upload', - input: sphinx_output, - output: 'upload', - build_always_stale: true, - command: [ - 'rsync', '-vpruz', '--delete', meson.current_build_dir() + '/', - 'www.musicpd.org:/var/www/mpd/doc/', - '--chmod=Dug+rwx,Do+rx,Fug+rw,Fo+r', - '--include=html', '--include=html/**', - '--exclude=*', - ], -) - - +if get_option('html_manual') + sphinx_output = custom_target( + 'HTML documentation', + output: 'html', + input: [ + 'index.rst', 'user.rst', 'developer.rst', + 'plugins.rst', + 'protocol.rst', + 'conf.py', + ], + command: [sphinx, '-q', '-b', 'html', '-d', '@OUTDIR@/doctrees', meson.current_source_dir(), '@OUTPUT@'], + build_by_default: true, + install: true, + install_dir: join_paths(get_option('datadir'), 'doc', meson.project_name()), + ) + + custom_target( + 'upload', + input: sphinx_output, + output: 'upload', + build_always_stale: true, + command: [ + 'rsync', '-vpruz', '--delete', meson.current_build_dir() + '/', + 'www.musicpd.org:/var/www/mpd/doc/', + '--chmod=Dug+rwx,Do+rx,Fug+rw,Fo+r', + '--include=html', '--include=html/**', + '--exclude=*', + ], + ) +endif + +if get_option('manpages') + # This installs all manpages in the "man1" subdirectory. Due to + # https://github.com/mesonbuild/meson/issues/1550 there appears to + # be no good solution with Meson. Sigh. + custom_target( + 'Manpage documentation', + output: 'man1', + input: ['mpd.1.rst', 'conf.py'], + command: [sphinx, '-q', '-b', 'man', '-d', '@OUTDIR@/man_doctrees', meson.current_source_dir(), '@OUTPUT@'], + build_by_default: true, + install: true, + install_dir: get_option('mandir'), + ) +endif diff --git a/doc/mpd.1 b/doc/mpd.1 deleted file mode 100644 index 5d2634570..000000000 --- a/doc/mpd.1 +++ /dev/null @@ -1,55 +0,0 @@ -.TH "Music Player Daemon" 1 -.SH NAME -MPD \- A daemon for playing music -.SH SYNOPSIS -.B mpd -.RI [ options ] -.RI [ CONF_FILE ] -.SH DESCRIPTION -MPD is a daemon for playing music. Music is played through the configured -audio output(s) (which are generally local, but can be remote). The daemon -stores info about all available music, and this info can be easily searched and -retrieved. Player control, info retrieval, and playlist management can all be -managed remotely. - -MPD searches for a config file in \fB$XDG_CONFIG_HOME/mpd/mpd.conf\fP then -\fB~/.mpdconf\fP then \fB/etc/mpd.conf\fP or uses CONF_FILE. - -Read more about MPD at <\fBhttp://www.musicpd.org/\fP>. -.SH OPTIONS -.TP -.BI \-\-help -Output a brief help message. -.TP -.BI \-\-kill -Kill the currently running mpd session. The pid_file parameter must be -specified in the config file for this to work. -.TP -.BI \-\-no\-daemon -Don't detach from console. -.TP -.BI \-\-stderr -Print messages stderr. -.TP -.BI \-\-verbose -Verbose logging. -.TP -.BI \-\-version -Print version information. -.SH FILES -.TP -.BI ~/.mpdconf -User configuration file. -.TP -.BI /etc/mpd.conf -Global configuration file. -.SH SEE ALSO -mpd.conf(5), mpc(1) -.SH BUGS -If you find a bug, please report it at -.br -<\fBhttps://github.com/MusicPlayerDaemon/MPD/issues/\fP>. -.SH AUTHORS -Max Kellermann <max.kellermann@gmail.com> - -Special thanks to all the people that provided feedback and patches. diff --git a/doc/mpd.1.rst b/doc/mpd.1.rst new file mode 100644 index 000000000..6a48ad89e --- /dev/null +++ b/doc/mpd.1.rst @@ -0,0 +1,59 @@ +=== +mpd +=== + +SYNOPSIS +-------- + +``mpd`` [options] [CONF_FILE] + +DESCRIPTION +------------ + +MPD is a daemon for playing music. Music is played through the configured audio output(s) (which are generally local, but can be remote). The daemon stores info about all available music, and this info can be easily searched and retrieved. Player control, info retrieval, and playlist management can all be managed remotely. + +MPD searches for a config file in ``$XDG_CONFIG_HOME/mpd/mpd.conf`` then ``~/.mpdconf`` then ``/etc/mpd.conf`` or uses CONF_FILE. + +Read more about MPD at ``<http://www.musicpd.org/>``. + +OPTIONS +------- + +--help + Output a brief help message. + +--kill + Kill the currently running mpd session. The pid_file parameter must be specified in the config file for this to work. + +--no-config + Don't read from the configuration file. + +--no-daemon + Don't detach from console. + +--stderr + Print messages to stderr. + +--verbose + Verbose logging. + +--version + Print version information. + +FILES +----- + +~/.mpdconf + User configuration file. + +/etc/mpd.conf + Global configuration file. + +SEE ALSO +-------- + +mpd.conf(5), mpc(1) + +BUGS +---- +If you find a bug, please report it at ``<https://github.com/MusicPlayerDaemon/MPD/issues/>``. diff --git a/doc/mpd.conf.5 b/doc/mpd.conf.5 deleted file mode 100644 index 58d951b53..000000000 --- a/doc/mpd.conf.5 +++ /dev/null @@ -1,180 +0,0 @@ -.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$XDG_CONFIG_HOME/mpd/mpd.conf\fP -then 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. - -This manual is not complete, it lists only the most important options. -Please read the MPD user manual for a complete configuration guide: -<\fBhttp://www.musicpd.org/doc/user/\fP> -.SH REQUIRED PARAMETERS -.TP -.B db_file <file> -This specifies where the db file will be stored. -.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 sticker_file <file> -The location of the sticker database. This is a database which -manages dynamic information attached to songs. -.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 restore_paused <yes or no> -Put MPD into pause mode instead of starting playback after startup. -.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 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 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 inside the music dir, -potentially adding duplicates to the database. -You must recreate the database after changing this option. -The default is "yes". -.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 @ %h", where %h will be replaced with the -hostname of the machine running MPD. -.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 replaygain <off or album or track or auto> -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. "auto" uses the track ReplayGain -tags if random play is activated otherwise the album 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 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 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 auto_update <yes or no> -This specifies the whether to support automatic update of music database when -files are changed in music_directory. The default is to disable autoupdate -of database. -.TP -.B auto_update_depth <N> -Limit the depth of the directories being watched, 0 means only watch -the music directory itself. There is no limit by default. -.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. -Any of the three attributes may be an asterisk to specify that this -attribute should not be enforced -.TP -.B replay_gain_handler <software, mixer or 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. -.TP -.B mixer_type <hardware, software or 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. -.SH FILES -.TP -.BI ~/.mpdconf -User configuration file. -.TP -.BI /etc/mpd.conf -Global configuration file. -.SH SEE ALSO -mpd(1), mpc(1) diff --git a/doc/mpd.conf.5.rst b/doc/mpd.conf.5.rst new file mode 100644 index 000000000..95da0b506 --- /dev/null +++ b/doc/mpd.conf.5.rst @@ -0,0 +1,189 @@ +======== +mpd.conf +======== + + +DESCRIPTION +------------ + +``mpd.conf`` is the configuration file for mpd(1). If not specified on the command line, MPD first searches for it at ``$XDG_CONFIG_HOME/mpd/mpd.conf`` then at ``~/.mpdconf`` then at ``~/.mpd/mpd.conf`` and then in ``/etc/mpd.conf``. + +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 theform:: + + audio_output { + parameter1 "value" + parameter2 "value" + } + + +Parameters that take a file or directory as an argument should use absolute paths. + +See ``docs/mpdconf.example`` in the source tarball for an example configuration file. + +This manual is not complete, it lists only the most important options. +Please read the MPD user manual for a complete configuration guide: +``<http://www.musicpd.org/doc/user/>`` + + +REQUIRED PARAMETERS +------------------- + +db_file <file> + This specifies where the db file will be stored. + +log_file <file> + This specifies where the log file should be located. The special value "syslog" makes MPD use the local syslog daemon. + +OPTIONAL PARAMETERS +------------------- + +sticker_file <file> + The location of the sticker database. This is a database which manages + dynamic information attached to songs. + +pid_file <file> + This specifies the file to save mpd's process ID in. + +music_directory <directory> + This specifies the directory where music is located. If you do not configure + this, you can only play streams. + +playlist_directory <directory> + This specifies the directory where saved playlists are stored. If + you do not configure this, you cannot save playlists. + +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). + +restore_paused <yes or no> + Put MPD into pause mode instead of starting playback after startup. + +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. + +port <port> + This specifies the port that mpd listens on. The default is 6600. + +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". + +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". + +follow_inside_symlinks <yes or no> + Control if MPD will follow symbolic links pointing inside the music dir, + potentially adding duplicates to the database. You must recreate the + database after changing this option. The default is "yes". + +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. + +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 @ %h", where %h will be replaced with the + hostname of the machine running MPD. + +audio_output + See DESCRIPTION and the various ``AUDIO OUTPUT PARAMETERS`` 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. + +replaygain <off or album or track or auto> + If specified, mpd will adjust the volume of songs played using ReplayGain + tags (see ``<http://www.replaygain.org/>``). 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. "auto" uses the track + ReplayGain tags if random play is activated otherwise the album ReplayGain + tags. Currently only FLAC, Ogg Vorbis, Musepack, and MP3 (through ID3v2 + ReplayGain tags, not APEv2) are supported. + +replaygain_preamp <-15 to 15> + This is the gain (in dB) applied to songs with ReplayGain tags. + +volume_normalization <yes or no> + If yes, mpd will normalize the volume of songs as they play. The default is + no. + +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. + +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". + +auto_update <yes or no> + This specifies the whether to support automatic update of music database + when files are changed in music_directory. The default is to disable + autoupdate of database. + +auto_update_depth <N> + Limit the depth of the directories being watched, 0 means only watch the + music directory itself. There is no limit by default. + +REQUIRED AUDIO OUTPUT PARAMETERS +-------------------------------- + +type <type> + This specifies the audio output type. See the list of supported outputs in + mpd --version for possible values. + +name <name> + This specifies a unique name for the audio output. + +OPTIONAL AUDIO OUTPUT PARAMETERS +-------------------------------- + +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 + ``audio_output_format`` parameter for more details. The default is to use + whatever audio format is passed to the audio output. Any of the three + attributes may be an asterisk to specify that this attribute should not be + enforced + +replay_gain_handler <software, mixer or 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. + +mixer_type <hardware, software or 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. + +FILES +----- + +~/.mpdconf + User configuration file. + +/etc/mpd.conf + Global configuration file. + +SEE ALSO +-------- + + mpd(1), mpc(1) diff --git a/doc/mpdconf.example b/doc/mpdconf.example index 11ef55887..c401d6605 100644 --- a/doc/mpdconf.example +++ b/doc/mpdconf.example @@ -280,6 +280,7 @@ input { # name "My Pulse Output" ## server "remote_server" # optional ## sink "remote_server_sink" # optional +## media_role "media_role" #optional #} # # An example of a winmm output (Windows multimedia API). @@ -293,6 +294,20 @@ input { ## mixer_type "hardware" # optional #} # +# An example of a wasapi output (Windows multimedia API). +# +#audio_output { +# type "wasapi" +# name "My WASAPI output" +## device "Digital Audio (S/PDIF) (High Definition Audio Device)" # optional +# or +## device "0" # optional +## Exclusive mode blocks all other audio source, and get best audio quality without resampling. +## exclusive "no" # optional +## Enumerate all devices in log. +## enumerate "no" # optional +#} +# # An example of an openal output. # #audio_output { diff --git a/doc/plugins.rst b/doc/plugins.rst index d485e6fb2..e5056a7ab 100644 --- a/doc/plugins.rst +++ b/doc/plugins.rst @@ -27,7 +27,7 @@ The default plugin. Stores a copy of the database in memory. A file is used for proxy ----- -Provides access to the database of another :program:`MPD` instance using libmpdclient. This is useful when you run mount the music directory via NFS/SMB, and the file server already runs a :program:`MPD` instance. Only the file server needs to update the database. +Provides access to the database of another :program:`MPD` instance using libmpdclient. This is useful when you mount the music directory via NFS/SMB, and the file server already runs a :program:`MPD` instance. Only the file server needs to update the database. .. list-table:: :widths: 20 80 @@ -116,7 +116,7 @@ Provides a list of SMB/CIFS servers on the local network. udisks ------ -Queries the udisks2 daemon via D-Bus and obtain a list of file systems (e.g. USB sticks or other removable media). +Queries the udisks2 daemon via D-Bus and obtains a list of file systems (e.g. USB sticks or other removable media). upnp ---- @@ -131,15 +131,39 @@ Input plugins alsa ---- -Allows :program:`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: +Allows :program:`MPD` on Linux to play audio directly from a soundcard using the scheme alsa://. Audio is by default formatted as 48 kHz 16-bit stereo, but this default can be overidden by a config file setting or by the URI. Examples: .. code-block:: none - mpc add alsa:// plays audio from device hw:0,0 + mpc add alsa:// plays audio from device default .. code-block:: none - mpc add alsa://hw:1,0 plays audio from device hw:1,0 cdio_paranoia + mpc add alsa://hw:1,0 plays audio from device hw:1,0 + +.. code-block:: none + + mpc add alsa://hw:1,0?format=44100:16:2 plays audio from device hw:1,0 sampling 16-bit stereo at 44.1kHz. + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Setting + - Description + * - **default_device NAME** + - The alsa device id to use when none is specified in the URI. + * - **default_format F** + - The sampling rate, size and channels to use. Wildcards are not allowed. + + Example - "44100:16:2" + + * - **auto_resample yes|no** + - If set to no, then libasound will not attempt to resample. In this case, the user is responsible for ensuring that the requested sample rate can be produced natively by the device, otherwise an error will occur. + * - **auto_channels yes|no** + - If set to no, then libasound will not attempt to convert between different channel numbers. The user must ensure that the device supports the requested channels when sampling. + * - **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, ...). Again the user must ensure that the requested format is available natively from the device. cdio_paranoia ------------- @@ -326,6 +350,8 @@ faad Decodes AAC files using libfaad. +.. _decoder_ffmpeg: + ffmpeg ------ @@ -395,30 +421,22 @@ Video game music file emulator based on `game-music-emu <https://bitbucket.org/m - Description * - **accuracy yes|no** - Enable more accurate sound emulation. + * - **default_fade** + - The default fade-out time, in seconds. Used by songs that don't specify their own fade-out time. hybrid_dsd ---------- `Hybrid-DSD <http://dsdmaster.blogspot.de/p/bitperfect-introduces-hybrid-dsd-file.html>`_ -is a MP4 container file (:file:`*.m4a`) which contains both ALAC and +is an MP4 container file (:file:`*.m4a`) which contains both ALAC and DSD data. It is disabled by default, and works only if you explicitly enable it. Without this plugin, the ALAC parts gets handled by the -`FFmpeg decoder plugin -<https://www.musicpd.org/doc/user/decoder_plugins.html#ffmpeg_decoder>`_. This +:ref:`FFmpeg decoder plugin <decoder_ffmpeg>`. This plugin should be enabled only if you have a bit-perfect playback path to a DSD-capable DAC; for everybody else, playing back the ALAC copy of the file is better. -.. list-table:: - :widths: 20 80 - :header-rows: 1 - - * - Setting - - Description - * - **gapless yes|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 <http://www.willwap.co.uk/Programs/vbrfix.php>`_ instead of disabling gapless MP3 playback. The default is to support gapless MP3 playback. - mad --- @@ -462,7 +480,9 @@ Decodes Musepack files using `libmpcdec <http://www.musepack.net/>`_. mpg123 ------ -Decodes MP3 files using `libmpg123 <http://www.mpg123.de/>`_. +Decodes MP3 files using `libmpg123 <http://www.mpg123.de/>`_. Currently, this +decoder does not support streams (e.g. archived files, remote files over HTTP, +...), only regular local files. opus ---- @@ -472,7 +492,7 @@ Decodes Opus files using `libopus <http://www.opus-codec.org/>`_. 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". +Reads 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 ------- @@ -486,9 +506,11 @@ C64 SID decoder based on `libsidplayfp <https://sourceforge.net/projects/sidplay * - Setting - Description * - **songlength_database PATH** - - Location of your songlengths file, as distributed with the HVSC. The sidplay plugin checks this for matching MD5 fingerprints. See http://www.hvsc.c64.org/download/C64Music/DOCUMENTS/Songlengths.faq. + - Location of your songlengths file, as distributed with the HVSC. The sidplay plugin checks this for matching MD5 fingerprints. See http://www.hvsc.c64.org/download/C64Music/DOCUMENTS/Songlengths.faq. New songlength format support requires libsidplayfp 2.0 or later. * - **default_songlength SECONDS** - 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. + * - **default_genre GENRE** + - Optional default genre for SID songs. * - **filter yes|no** - Turns the SID filter emulation on or off. * - **kernal** @@ -724,6 +746,25 @@ Valid quality values for libsoxr: * "medium" * "low" * "quick" +* "custom" + +If the quality is set to custom also the following settings are available: + + * - Name + - Description + * - **precision** + - The precision in bits. Valid values 16,20,24,28 and 32 bits. + * - **phase_response** + - Between the 0-100, Where 0=MINIMUM_PHASE and 50=LINEAR_PHASE. + * - **passband_end** + - The % of source bandwidth where to start filtering. Typical between the 90-99.7. + * - **stopband_begin** + - The % of the source bandwidth Where the anti aliasing filter start. Value 100+. + * - **attenuation** + - Reduction in dB's to prevent clipping from the resampling process. + * - **flags** + - Bitmask with additional option see soxr documentation for specific flags. + .. _output_plugins: @@ -868,6 +909,10 @@ The jack plugin connects to a `JACK server <http://jackaudio.org/>`_. - 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. + * - **auto_destination_ports yes|no** + - If set to *yes*, then MPD will automatically create connections between the send ports of + MPD and receive ports of the first sound card; if set to *no*, then MPD will only create + connections to the contents of *destination_ports* if it is set. Enabled by default. * - **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. @@ -1002,6 +1047,8 @@ The pulse plugin connects to a `PulseAudio <http://www.freedesktop.org/wiki/Soft - Sets the host name of the PulseAudio server. By default, :program:`MPD` connects to the local PulseAudio server. * - **sink NAME** - Specifies the name of the PulseAudio sink :program:`MPD` should play on. + * - **media_role ROLE** + - Specifies a custom media role that :program:`MPD` reports to PulseAudio. Default is "music". (optional). * - **scale_volume FACTOR** - Specifies a linear scaling coefficient (ranging from 0.5 to 5.0) to apply when adjusting volume through :program:`MPD`. For example, chosing a factor equal to ``"0.7"`` means that setting the volume to 100 in :program:`MPD` will set the PulseAudio volume to 70%, and a factor equal to ``"3.5"`` means that volume 100 in :program:`MPD` corresponds to a 350% PulseAudio volume. @@ -1090,11 +1137,58 @@ The "Solaris" plugin runs only on SUN Solaris, and plays via /dev/audio. - Sets the path of the audio device, defaults to /dev/audio. +wasapi +------ + +The `Windows Audio Session API <https://docs.microsoft.com/en-us/windows/win32/coreaudio/wasapi>`_ plugin uses WASAPI, which is supported started from Windows Vista. It is recommended if you are using Windows. + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Setting + - Description + * - **device NAME** + - Sets the device which should be used. This can be any valid audio device name, or index number. The default value is "", which makes WASAPI choose the default output device. + * - **enumerate yes|no** + - Enumerate all devices in log while playing started. Useful for device configuration. The default value is "no". + * - **exclusive yes|no** + - Exclusive mode blocks all other audio source, and get best audio quality without resampling. Stopping playing release the exclusive control of the output device. The default value is "no". + + .. _filter_plugins: Filter plugins ============== +ffmpeg +------ + +Configures a FFmpeg filter graph. + +This plugin requires building with ``libavfilter`` (FFmpeg). + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Setting + - Description + * - **graph "..."** + - Specifies the ``libavfilter`` graph; read the `FFmpeg + documentation + <https://libav.org/documentation/libavfilter.html#Filtergraph-syntax-1>`_ + for details + + +hdcd +---- + +Decode `HDCD +<https://en.wikipedia.org/wiki/High_Definition_Compatible_Digital>`_. + +This plugin requires building with ``libavfilter`` (FFmpeg). + normalize --------- @@ -1177,3 +1271,19 @@ Download playlist from SoundCloud. It accepts URIs starting with soundcloud://. xspf ---- Reads XSPF playlist files. + + +Archive plugins +=============== + +bz2 +--- +Allows to load single bzip2 compressed files using `libbz2 <https://www.sourceware.org/bzip2/>`_. Does not support seeking. + +zzip +---- +Allows to load music files from ZIP archives using `zziplib <http://zziplib.sourceforge.net/>`_. + +iso +--- +Allows to load music files from ISO 9660 images using `libcdio <https://www.gnu.org/software/libcdio/>`_. diff --git a/doc/protocol.rst b/doc/protocol.rst index fe60d9c61..200d5dcf6 100644 --- a/doc/protocol.rst +++ b/doc/protocol.rst @@ -66,7 +66,16 @@ Binary Responses Some commands can return binary data. This is initiated by a line containing ``binary: 1234`` (followed as usual by a newline). After that, the specified number of bytes of binary data follows, then a -newline, and finally the ``OK`` line. Example:: +newline, and finally the ``OK`` line. + +If the object to be transmitted is large, the server may choose a +reasonable chunk size and transmit only a portion. Usually, the +response also contains a ``size`` line which specifies the total +(uncropped) size, and the command usually has a way to specify an +offset into the object; this way, the client can copy the whole file +without blocking the connection for too long. + +Example:: foo: bar binary: 42 @@ -163,7 +172,7 @@ syntax:: find EXPRESSION -``EXPRESSION`` is a string enclosed in parantheses which can be one +``EXPRESSION`` is a string enclosed in parentheses which can be one of: - ``(TAG == 'VALUE')``: match a tag value; if there are multiple @@ -209,15 +218,15 @@ of: or more attributes may be ``*``). - ``(!EXPRESSION)``: negate an expression. Note that each expression - must be enclosed in parantheses, e.g. :code:`(!(artist == 'VALUE'))` + must be enclosed in parentheses, e.g. :code:`(!(artist == 'VALUE'))` (which is equivalent to :code:`(artist != 'VALUE')`) - ``(EXPRESSION1 AND EXPRESSION2 ...)``: combine two or more expressions with logical "and". Note that each expression must - be enclosed in parantheses, e.g. :code:`((artist == 'FOO') AND + be enclosed in parentheses, e.g. :code:`((artist == 'FOO') AND (album == 'BAR'))` -The :command:`find` commands are case sensitive, which +The :command:`find` commands are case sensitive, while :command:`search` and related commands ignore case. Prior to MPD 0.21, the syntax looked like this:: @@ -274,6 +283,12 @@ The following tags are supported by :program:`MPD`: * **date**: the song's release date. This is usually a 4-digit year. * **composer**: the artist who composed the song. * **performer**: the artist who performed the song. +* **conductor**: the conductor who conducted the song. +* **work**: `"a work is a distinct intellectual or artistic creation, + which can be expressed in the form of one or more audio recordings" <https://musicbrainz.org/doc/Work>`_ +* **grouping**: "used if the sound belongs to a larger category of + sounds/music" (`from the IDv2.4.0 TIT1 description + <http://id3.org/id3v2.4.0-frames>`_). * **comment**: a human-readable comment about this song. The exact meaning of this tag is not well-defined. * **disc**: the decimal disc number in a multi-disc album. * **label**: the name of the label or publisher. @@ -374,7 +389,9 @@ Querying :program:`MPD`'s status :command:`currentsong` Displays the song info of the current song (same song that - is identified in status). + is identified in status). Information about the current song + is represented by key-value pairs, one on each line. The first + pair must be the `file` key-value pair. .. _command_idle: @@ -398,9 +415,11 @@ Querying :program:`MPD`'s status - ``sticker``: the sticker database has been modified. - ``subscription``: a client has subscribed or unsubscribed to a channel - ``message``: a message was received on a channel this client is subscribed to; this event is only emitted when the queue is empty + - ``neighbor``: a neighbor was found or lost + - ``mount``: the mount list has changed Change events accumulate, even while the connection is not in - "idle" mode; no events gets lost while the client is doing + "idle" mode; no events get lost while the client is doing something else with the connection. If an event had already occurred since the last call, the new :ref:`idle <command_idle>` command will return immediately. @@ -424,6 +443,8 @@ Querying :program:`MPD`'s status Reports the current status of the player and the volume level. + - ``partition``: the name of the current partition (see + :ref:`partition_commands`) - ``volume``: ``0-100`` (deprecated: ``-1`` if the volume cannot be determined) - ``repeat``: ``0`` or ``1`` @@ -515,7 +536,7 @@ Playback options ``auto`` . Changing the mode during playback may take several - seconds, because the new settings does not affect the + seconds, because the new settings do not affect the buffered data. This command triggers the ``options`` idle event. @@ -809,11 +830,12 @@ The music database ================== :command:`albumart {URI} {OFFSET}` - Searches the directory the file ``URI`` - resides in and attempts to return a chunk of an album + Locate album art for the given song and return a chunk of an album art image file at offset ``OFFSET``. - Uses the filename "cover" with any of ".png, .jpg, - .tiff, .bmp". + + This is currently implemented by searching the directory the file + resides in for a file called :file:`cover.png`, :file:`cover.jpg`, + :file:`cover.tiff` or :file:`cover.bmp`. Returns the file size and actual number of bytes read at the requested offset, followed @@ -822,7 +844,7 @@ The music database Example:: - albumart + albumart foo/bar.ogg 0 size: 1024768 binary: 8192 <8192 bytes> @@ -846,10 +868,21 @@ The music database count group artist count title Echoes group artist - A group with an empty value contains counts of matching song which - don't this group tag. It exists only if at least one such song is + A group with an empty value contains counts of matching songs which + don't have this group tag. It exists only if at least one such song is found. +:command:`getfingerprint {URI}` + + Calculate the song's audio fingerprint. Example (abbreviated fingerprint):: + + getfingerprint "foo/bar.ogg" + chromaprint: AQACcEmSREmWJJmkIT_6CCf64... + OK + + This command is only available if MPD was built with + :file:`libchromaprint` (``-Dchromaprint=enabled``). + .. _command_find: :command:`find {FILTER} [sort {TYPE}] [window {START:END}]` @@ -876,7 +909,7 @@ The music database .. _command_findadd: -:command:`findadd {FILTER}` +:command:`findadd {FILTER} [sort {TYPE}] [window {START:END}]` Search the database for songs matching ``FILTER`` (see :ref:`Filters <filter_syntax>`) and add them to the queue. Parameters have the same meaning as for @@ -981,6 +1014,30 @@ The music database decoder plugins support it. For example, on Ogg files, this lists the Vorbis comments. +:command:`readpicture {URI} {OFFSET}` + Locate a picture for the given song and return a chunk of the + image file at offset ``OFFSET``. This is usually implemented by + reading embedded pictures from binary tags (e.g. ID3v2's ``APIC`` + tag). + + Returns the following values: + + - ``size``: the total file size + - ``type``: the file's MIME type (optional) + - ``binary``: see :ref:`binary` + + If the song file was recognized, but there is no picture, the + response is successful, but is otherwise empty. + + Example:: + + readpicture foo/bar.ogg 0 + size: 1024768 + type: image/jpeg + binary: 8192 + <8192 bytes> + OK + .. _command_search: :command:`search {FILTER} [sort {TYPE}] [window {START:END}]` @@ -991,14 +1048,14 @@ The music database .. _command_searchadd: -:command:`searchadd {FILTER}` +:command:`searchadd {FILTER} [sort {TYPE}] [window {START:END}]` Search the database for songs matching ``FILTER`` (see :ref:`Filters <filter_syntax>`) and add them to the queue. Parameters have the same meaning as for :ref:`search <command_search>`. -:command:`searchaddpl {NAME} {FILTER}` +:command:`searchaddpl {NAME} {FILTER} [sort {TYPE}] [window {START:END}]` Search the database for songs matching ``FILTER`` (see :ref:`Filters <filter_syntax>`) and add them to the playlist named ``NAME``. @@ -1038,8 +1095,8 @@ access NFS and SMB servers. Multiple storages can be "mounted" together, similar to the `mount` command on many operating systems, but without cooperation from the kernel. No -superuser privileges are necessary, beause this mapping exists -only inside the :program:`MPD` process +superuser privileges are necessary, because this mapping exists +only inside the :program:`MPD` process. .. _command_mount: @@ -1188,6 +1245,8 @@ Connection settings Announce that this client is interested in all tag types. This is the default setting for new clients. +.. _partition_commands: + Partition commands ================== @@ -1208,6 +1267,13 @@ client is assigned to one partition at a time. :command:`newpartition {NAME}` Create a new partition. +:command:`delpartition {NAME}` + Delete a partition. The partition must be empty (no connected + clients and no outputs). + +:command:`moveoutput {OUTPUTNAME}` + Move an output to the current partition. + Audio output devices ==================== @@ -1297,6 +1363,9 @@ additional services. New messages are indicated by the ``message`` idle event. +If your MPD instance has multiple partitions, note that +client-to-client messages are local to the current partition. + :command:`subscribe {NAME}` Subscribe to a channel. The channel is created if it does not exist already. The name may consist of diff --git a/doc/user.rst b/doc/user.rst index f2ea36697..e48af7489 100644 --- a/doc/user.rst +++ b/doc/user.rst @@ -53,7 +53,7 @@ Download the source tarball from the `MPD home page <https://musicpd.org>`_ and In any case, you need: -* a C++14 compiler (e.g. gcc 6.0 or clang 3.9) +* a C++14 compiler (e.g. GCC 8 or clang 5) * `Meson 0.49.0 <http://mesonbuild.com/>`__ and `Ninja <https://ninja-build.org/>`__ * Boost 1.58 @@ -185,47 +185,6 @@ ABI is the Android ABI to be built, e.g. ":code:`arm64-v8a`". This downloads various library sources, and then configures and builds :program:`MPD`. -systemd socket activation -------------------------- - -Using systemd, you can launch :program:`MPD` on demand when the first client attempts to connect. - -:program:`MPD` comes with two systemd unit files: a "service" unit and -a "socket" unit. These will be installed to the directory specified -with :code:`-Dsystemd_system_unit_dir=...`, -e.g. :file:`/lib/systemd/system`. - -To enable socket activation, type: - -.. code-block:: none - - systemctl enable mpd.socket - systemctl start mpd.socket - -In this configuration, :program:`MPD` will ignore the :ref:`listener -settings <listeners>` (``bind_to_address`` and ``port``). - -systemd user unit ------------------ - -You can launch :program:`MPD` as a systemd user unit. These will be -installed to the directory specified with -:code:`-Dsystemd_user_unit_dir=...`, -e.g. :file:`/usr/lib/systemd/user` or -:file:`$HOME/.local/share/systemd/user`. - -Once the user unit is installed, you can start and stop :program:`MPD` like any other service: - -.. code-block:: none - - systemctl --user start mpd - -To auto-start :program:`MPD` upon login, type: - -.. code-block:: none - - systemctl --user enable mpd - Configuration ************* @@ -260,6 +219,13 @@ another file; the given file name is relative to the current file: include "other.conf" +You can use :code:`include_optional` instead if you want the included file +to be optional; the directive will be ignored if the file does not exist: + +.. code-block:: none + + include_optional "may_not_exist.conf" + Configuring the music directory ------------------------------- @@ -336,6 +302,44 @@ The following table lists the input options valid for all plugins: More information can be found in the :ref:`input_plugins` reference. +.. _input_cache: + +Configuring the Input Cache +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The input cache prefetches queued song files before they are going to +be played. This has several advantages: + +- risk of buffer underruns during playback is reduced because this + decouples playback from disk (or network) I/O +- bulk transfers may be faster and more energy efficient than loading + small chunks on-the-fly +- by prefetching several songs at a time, the hard disk can spin down + for longer periods of time + +This comes at a cost: + +- memory usage +- bulk transfers may reduce the performance of other applications + which also want to access the disk (if the kernel's I/O scheduler + isn't doing its job properly) + +To enable the input cache, add an ``input_cache`` block to the +configuration file: + +.. code-block:: none + + input_cache { + size "1 GB" + } + +This allocates a cache of 1 GB. If the cache grows larger than that, +older files will be evicted. + +You can flush the cache at any time by sending ``SIGHUP`` to the +:program:`MPD` process, see :ref:`signals`. + + Configuring decoder plugins --------------------------- @@ -419,7 +423,7 @@ The following table lists the audio_output options valid for all plugins: :ref:`oss_plugin` and PulseAudio :ref:`pulse_plugin`), the software mixer, the ":samp:`null`" mixer (allows setting the volume, but with no effect; this can be used as a trick to - implement an external mixer :ref:`external_mixer`) or no mixer + implement an external mixer, see :ref:`external_mixer`) or no mixer (:samp:`none`). By default, the hardware mixer is used for devices which support it, and none for the others. * - **filters "name,...**" @@ -714,8 +718,9 @@ Do not change these unless you know what you are doing. * - Setting - Description - * - **audio_buffer_size KBYTES** - - Adjust the size of the internal audio buffer. Default is 4096 (4 MiB). + * - **audio_buffer_size SIZE** + - Adjust the size of the internal audio buffer. Default is + :samp:`4 MB` (4 MiB). Zeroconf ^^^^^^^^ @@ -768,17 +773,17 @@ Real-Time Scheduling On Linux, :program:`MPD` attempts to configure real-time scheduling for some threads that benefit from it. -This is only possible you allow :program:`MPD` to do it. This privilege is controlled by :envvar:`RLIMIT_RTPRIO` :envvar:`RLIMIT_RTTIME`. You can configure this privilege with :command:`ulimit` before launching :program:`MPD`: +This is only possible if you allow :program:`MPD` to do it. This privilege is controlled by :envvar:`RLIMIT_RTPRIO` :envvar:`RLIMIT_RTTIME`. You can configure this privilege with :command:`ulimit` before launching :program:`MPD`: .. code-block:: none - ulimit -HS -r 50; mpd + ulimit -HS -r 40; mpd Or you can use the :command:`prlimit` program from the util-linux package: .. code-block:: none - prlimit --rtprio=50 --rttime=unlimited mpd + prlimit --rtprio=40 --rttime=unlimited mpd The systemd service file shipped with :program:`MPD` comes with this setting. @@ -796,10 +801,10 @@ You can verify whether the real-time scheduler is active with the ps command: PID TID CLS RTPRIO COMMAND 16257 16257 TS - mpd 16257 16258 TS - io - 16257 16259 FF 50 rtio + 16257 16259 FF 40 rtio 16257 16260 TS - player 16257 16261 TS - decoder - 16257 16262 FF 50 output:ALSA + 16257 16262 FF 40 output:ALSA 16257 16263 IDL 0 update The CLS column shows the CPU scheduler; TS is the normal scheduler; FF and RR are real-time schedulers. In this example, two threads use the real-time scheduler: the output thread and the rtio (real-time I/O) thread; these two are the important ones. The database update thread uses the idle scheduler ("IDL in ps), which only gets CPU when no other process needs it. @@ -814,6 +819,89 @@ The CLS column shows the CPU scheduler; TS is the normal scheduler; FF and RR ar Using MPD ********* +Starting and Stopping MPD +------------------------- + +The simplest (but not the best) way to start :program:`MPD` is to +simply type:: + + mpd + +This will start :program:`MPD` as a daemon process (which means it +detaches from your terminal and continues to run in background). To +stop it, send ``SIGTERM`` to the process; if you have configured a +``pid_file``, you can use the ``--kill`` option:: + + mpd --kill + +The best way to manage :program:`MPD` processes is to use a service +manager such as :program:`systemd`. + +systemd +^^^^^^^ + +:program:`MPD` ships with :program:`systemd` service units. + +If you have installed :program:`MPD` with your operating system's +package manager, these are probably preinstalled, so you can start and +stop :program:`MPD` this way (like any other service):: + + systemctl start mpd + systemctl stop mpd + +systemd socket activation +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Using systemd, you can launch :program:`MPD` on demand when the first client attempts to connect. + +:program:`MPD` comes with two systemd unit files: a "service" unit and +a "socket" unit. These will be installed to the directory specified +with :code:`-Dsystemd_system_unit_dir=...`, +e.g. :file:`/lib/systemd/system`. + +To enable socket activation, type: + +.. code-block:: none + + systemctl enable mpd.socket + systemctl start mpd.socket + +In this configuration, :program:`MPD` will ignore the :ref:`listener +settings <listeners>` (``bind_to_address`` and ``port``). + +systemd user unit +^^^^^^^^^^^^^^^^^ + +You can launch :program:`MPD` as a systemd user unit. These will be +installed to the directory specified with +:code:`-Dsystemd_user_unit_dir=...`, +e.g. :file:`/usr/lib/systemd/user` or +:file:`$HOME/.local/share/systemd/user`. + +Once the user unit is installed, you can start and stop :program:`MPD` like any other service: + +.. code-block:: none + + systemctl --user start mpd + +To auto-start :program:`MPD` upon login, type: + +.. code-block:: none + + systemctl --user enable mpd + +.. _signals: + +Signals +------- + +:program:`MPD` understands the following UNIX signals: + +- ``SIGTERM``, ``SIGINT``: shut down MPD +- ``SIGHUP``: reopen log files (send this after log rotation) and + flush caches (see :ref:`input_cache`) + + The client ---------- @@ -953,6 +1041,22 @@ is no way for :program:`MPD` to find out whether the DAC supports it. DSD to PCM conversion is the fallback if DSD cannot be used directly. +ICY-MetaData +------------ + +Some MP3 streams send information about the current song with a +protocol named `"ICY-MetaData" +<http://www.smackfu.com/stuff/programming/shoutcast.html>`_. +:program:`MPD` makes its ``StreamTitle`` value available as ``Title`` +tag. + +By default, :program:`MPD` assumes this tag is UTF-8-encoded. To tell +:program:`MPD` to assume a different character set, specify it in the +``charset`` URL fragment parameter, e.g.:: + + mpc add 'http://radio.example.com/stream#charset=cp1251' + + Client Hacks ************ @@ -977,7 +1081,7 @@ Sometimes, it is helpful to run :program:`MPD` in a terminal and follow what hap .. code-block:: none - mpd --stdout --no-daemon --verbose + mpd --stderr --no-daemon --verbose Support ------- @@ -1057,7 +1161,7 @@ You can extract the backtrace from a core dump, or by running :program:`MPD` in .. code-block:: none - gdb --args mpd --stdout --no-daemon --verbose + gdb --args mpd --stderr --no-daemon --verbose run As soon as you have reproduced the crash, type ":command:`bt`" on the |