diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guix.texi | 103 |
1 files changed, 71 insertions, 32 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 585baf358f..58cc3d7aad 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -34241,36 +34241,57 @@ The Music Player Daemon (MPD) is a service that can play music while being controlled from the local machine or over the network by a variety of clients. -The following example shows how one might run @code{mpd} as user -@code{"bob"} on port @code{6666}. It uses pulseaudio for output. +The following example shows the simplest configuration to locally +expose, via PulseAudio, a music collection kept at @file{/srv/music}, +with @command{mpd} running as the default @samp{mpd} user. This user +will spawn its own PulseAudio daemon, which may compete for the sound +card access with that of your own user. In this configuration, you may +have to stop the playback of your user audio applications to hear MPD's +output and vice-versa. @lisp (service mpd-service-type (mpd-configuration - (user "bob") - (port "6666"))) + (music-directory "/srv/music"))) @end lisp +@quotation Important +The music directory must be readable to the MPD user, by default, +@samp{mpd}. Permission problems will be reported via @samp{Permission +denied} errors in the MPD logs, which appear in @file{/var/log/messages} +by default. +@end quotation + +Most MPD clients will trigger a database update upon connecting, but you +can also use the @code{update} action do to so: + +@example +herd update mpd +@end example + +All the MPD configuration fields are documented below, and a more +complex example follows. + @defvar mpd-service-type The service type for @command{mpd} @end defvar +@c %start of fragment @deftp {Data Type} mpd-configuration -Data type representing the configuration of @command{mpd}. +Available @code{mpd-configuration} fields are: @table @asis @item @code{package} (default: @code{mpd}) (type: file-like) The MPD package. -@item @code{user} (default: @code{%mpd-user}) (type: user-account) +@item @code{user} (type: user-account) The user to run mpd as. -The default @code{%mpd-user} is a system user with the name ``mpd'', -who is a part of the group @var{group} (see below). -@item @code{group} (default: @code{%mpd-group}) (type: user-group) +@item @code{group} (type: user-group) The group to run mpd as. The default @code{%mpd-group} is a system group with name ``mpd''. + @item @code{shepherd-requirement} (default: @code{'()}) (type: list-of-symbol) A list of symbols naming Shepherd services that this service will depend on. @@ -34278,24 +34299,31 @@ will depend on. @item @code{environment-variables} (default: @code{'("PULSE_CLIENTCONFIG=/etc/pulse/client.conf" "PULSE_CONFIG=/etc/pulse/daemon.conf")}) (type: list-of-strings) A list of strings specifying environment variables. -@item @code{log-file} (default: @code{"/var/log/mpd/log"}) (type: maybe-string) -The location of the log file. Set to @code{syslog} to use the local -syslog daemon or @code{%unset-value} to omit this directive from the -configuration file. +@item @code{log-file} (type: maybe-string) +The location of the log file. Unless specified, logs are sent to the +local syslog daemon. Alternatively, a log file name can be specified, +for example @file{/var/log/mpd.log}. @item @code{log-level} (type: maybe-string) -Suppress any messages below this threshold. Available values: -@code{notice}, @code{info}, @code{verbose}, @code{warning} and -@code{error}. +Supress any messages below this threshold. The available values, in +decreasing order of verbosity, are: @code{verbose}, @code{info}, +@code{notice}, @code{warning} and @code{error}. @item @code{music-directory} (type: maybe-string) The directory to scan for music files. +@item @code{music-dir} (type: maybe-string) +The directory to scan for music files. + @item @code{playlist-directory} (type: maybe-string) The directory to store playlists. +@item @code{playlist-dir} (type: maybe-string) +The directory to store playlists. + @item @code{db-file} (type: maybe-string) -The location of the music database. +The location of the music database. When left unspecified, +@file{~/.cache/db} is used. @item @code{state-file} (type: maybe-string) The location of the file that stores current MPD's state. @@ -34303,15 +34331,19 @@ The location of the file that stores current MPD's state. @item @code{sticker-file} (type: maybe-string) The location of the sticker database. -@item @code{default-port} (default: @code{6600}) (type: maybe-integer) +@item @code{default-port} (default: @code{6600}) (type: maybe-port) The default port to run mpd on. @item @code{endpoints} (type: maybe-list-of-strings) -The addresses that mpd will bind to. A port different from @var{default-port} -may be specified, e.g. @code{localhost:6602} and IPv6 addresses must be -enclosed in square brackets when a different port is used. -To use a Unix domain socket, an absolute path or a path starting with @code{~} -can be specified here. +The addresses that mpd will bind to. A port different from +@var{default-port} may be specified, e.g. @code{localhost:6602} and +IPv6 addresses must be enclosed in square brackets when a different port +is used. To use a Unix domain socket, an absolute path or a path +starting with @code{~} can be specified here. + +@item @code{address} (type: maybe-string) +The address that mpd will bind to. To use a Unix domain socket, an +absolute path can be specified here. @item @code{database} (type: maybe-mpd-plugin) MPD database plugin configuration. @@ -34328,6 +34360,10 @@ List of MPD input plugin configurations. @item @code{archive-plugins} (default: @code{'()}) (type: list-of-mpd-plugin) List of MPD archive plugin configurations. +@item @code{auto-update?} (type: maybe-boolean) +Whether to automatically update the music database when files are +changed in the @var{music-directory}. + @item @code{input-cache-size} (type: maybe-string) MPD input cache size. @@ -34353,6 +34389,7 @@ appended to the configuration. @end table @end deftp +@c %end of fragment @deftp {Data Type} mpd-plugin Data type representing a @command{mpd} plugin. @@ -34392,8 +34429,9 @@ Partitions} for available options. @end table @end deftp +@c %start of fragment @deftp {Data Type} mpd-output -Data type representing a @command{mpd} audio output. +Available @code{mpd-output} fields are: @table @asis @item @code{name} (default: @code{"MPD"}) (type: string) @@ -34420,15 +34458,16 @@ is only useful for output plugins that can receive tags, for example the @item @code{always-on?} (default: @code{#f}) (type: boolean) If set to @code{#t}, then MPD attempts to keep this audio output always -open. This may be useful for streaming servers, when you don?t want to +open. This may be useful for streaming servers, when you don’t want to disconnect all listeners even when playback is accidentally stopped. -@item @code{mixer-type} (default: @code{"none"}) (type: string) +@item @code{mixer-type} (type: maybe-string) This field accepts a string that specifies which mixer should be used for this audio output: the @code{hardware} mixer, the @code{software} mixer, the @code{null} mixer (allows setting the volume, but with no effect; this can be used as a trick to implement an external mixer -External Mixer) or no mixer (@code{none}). +External Mixer) or no mixer (@code{none}). When left unspecified, a +@code{hardware} mixer is used for devices that support it. @item @code{replay-gain-handler} (type: maybe-string) This field accepts a string that specifies how @@ -34443,6 +34482,7 @@ appended to the audio output configuration. @end table @end deftp +@c %end of fragment The following example shows a configuration of @command{mpd} that configures some of its plugins and provides a HTTP audio streaming output. @@ -34540,11 +34580,10 @@ HTTP port to listen on. How much detail to include in logs, possible values: @code{0} to @code{7}. -@item @code{log-to} (default: @code{"/var/log/mympd/log"}) (type: string-or-symbol) -Where to send logs. By default, the service logs to -@file{/var/log/mympd.log}. The alternative is @code{'syslog}, which -sends output to the running syslog service under the @samp{daemon} -facility. +@item @code{log-to} (type: maybe-string) +Where to send logs. Unless specified, the service logs to the local +syslog service under the @samp{daemon} facility. Alternatively, a log +file name can be specified, for example @file{/var/log/mympd.log}. @item @code{lualibs} (default: @code{"all"}) (type: maybe-string) See |