Skip to content

mpd configure.1

Jump to bottom
Ronald Record edited this page Sep 19, 2022 · 1 revision

NAME

mpd-configure - create a configuration file for the Music Player Daemon (MPD)

SYNOPSIS

mpd-configure [-o PATH] [-l a|d|u] [-c REGEXP] [-a HWADDRESS] [-q] [--nobackup]

DESCRIPTION

The mpd-configure bash script creates a valid configuration file for [mpd], optimised for bit perfect playback of any digital audio file, including those of high resolution.

With default settings the script uses the first available alsa audio interface by using its hardware address (in the form of hw:x,y), and has automagic procedures for things like the music directory and directory where files are stored, the number of items in the music direcory and the UPNP name. When multiple audio interfaces are found, the user is presented with a choice.

USAGE

The scripts lists all available alsa playback devices on the host. If multiple are found, the user is prompted to enter the hardware address of the device to be used. The -n (--noprompts) option skips the prompt and uses the first interface found instead. The -l (--limit), -c (--customfilter) and -a (--address) may be used to filter the returned alsa devices.

-o PATH, --outputfile PATH    
    Saves the result in the file specified with `PATH'.
    When this is an existing file, the scripts prompts
    the user to overwrite it, and makes a backup of the
    original file unless the `--nobackup' option is used).
-l TYPEFILTER, --limit TYPEFILTER   
    Limit the list of available audio interfaces to
    TYPEFILTER. Can be one of `a' (or `analog'),
    `d' (or `digital'), `u' (or `usb'), the
    latter for USB Audio Class (UAC1 or UAC2) devices.
-c REGEXP, --customlimit REGEXP 
    Limit the list further to match `REGEXP'.
-a HWADDRESS, --address HWADDRESS   
    Limits the list further by the audio interface
    specified with HWADDRESS, eg. `hw:0,1'.
-q, --quiet
    Surpress listing each interface with its details,
    ie. only store the details of each card in the appropriate arrays.
-n, --noprompts
    Surpress prompting for the interface to use
    and/or to overwrite an existing conffile. Use the
    first available interface (matching the filters) instead.
--nobackup
    By default the scripts backs up an existing output file
    before overwriting. Setting this option prevents that and
    overwrites the file without making a backup.
-h, --help
    Show this help message and exit.

Running the script

Run the script with default settings to display the contents of the resulting mpd configuration file:

mpd-configure

Storing the output of the script in a file

The output of the scripts can simply be redirected to a file (in this example mympd.conf):

mpd-configure > mympd.conf

Although the same may be achieved by using the -o or --output command line parameters or setting CONF_MPD_CONFFILE on the command line. This has the benefit that the script detects if the target file exists, in which case the user is prompted to overwrite it, while making an automated backup of the original file:

mpd-configure -o "mympd.conf"
# or:
CONF_MPD_CONFFILE="mympd.conf" mpd-configure

More advanced usage example

Additional setting are available using environment variables or using the file /usr/share/musicplayerplus/mpd/mpd-configure/mpd-configure.conf and configuration snippet files in the /usr/share/musicplayerplus/mpd/mpd-configure/confs-available/ directory.

For example to specify CONF_MPD_MUSICDIR which sets the music_directory and saving the resulting mpd configuration file in mympd.conf, use:

CONF_MPD_MUSICDIR="/srv/media/music" mpd-configure -o "mympd.conf"

By default mpd-configure prompts the user to overwrite the specified file if it exists, and makes a backup of it.

Fully automated usage example

A fully automated example which does not prompt the user (-n), uses the first available USB Audio Class interface (-l u) and sets some paths, while creating a backup of the original /etc/mpd.conf in case it exists:

CONF_MPD_MUSICDIR="/srv/media/music" CONF_MPD_HOMEDIR="/var/lib/mpd" \
mpd-configure -l u -n -o "/etc/mpd.conf"

To see all available command line options run the script with -h or --help:

mpd-configure -h

mpd-configure relies on the accompanying bash script alsa-capabilities for getting information about the available audio output interfaces from alsa.

Detailed usage instructions

After creating a mpd configuration file, mpd can be told to use this configuration file with:

    mpd ./mpd.conf

To use the generated configuration file system wide, it can be copied to the system wide mpd configuration file when you want to run mpd as a system daemon:

    sudo mpd-configure -o "/etc/mpd.conf"
    sudo systemctl restart mpd

More complex usage

For debugging or testing purposes one may set the INCLUDE_COMMENTS and/or DEBUG parameters through the mpd-configure.conf file or on the command line, eg:

    DEBUG="True" INCLUDE_COMMENTS="True" mpd-configure

In dynamic environments in which hardware may be altered each boot, connected to whatever USB DAC, the script could be put in a logon script or systemd service file.

Usage as a systemd service

The script is fast and stable enough to function as a systemd service. By setting Before=mpd.service and Wants=mpd.service in the service file systemd makes sure mpd-configure is run before mpd is started, and tries to start mpd.

Usage from within another bash or sh script

The bash script /usr/share/musicplayerplus/mpd/mpd-configure/examples/bash-example.sh demonstrates the way alsa-capabilities can be used from another bash script.

This demo script returns the monitoring file of the file specified as an argument:

bash examples/bash-example.sh hw:1,0

Result:

the audio card with alsa hardware address hw:1,0 can be monitored with:
/proc/asound/card1/stream0

Usage from within python

Assuming your in the /usr/share/musicplayerplus/mpd/mpd-configure directory, run:

    python examples/get-interfaces.py

The python script ./examples/get-interfaces.py uses a helper bash script (./examples/get-interfaces-for-python.sh), which in turn sources alsa-capabilities.

PREFERENCES

Preferences can be set in the file /usr/share/musicplayerplus/mpd/mpd-configure/mpd-configure.conf. By default all preferences are commented out.

The script uses configuration file snippets in the ./confs-available/ directory. By symlinking them to the ./confs-enabled/ directory, they will be included by mpd-configure in the resulting mpd configuration file. Any bash variable in those configuration snippets, will be expanded to their calculated values by the script.

General environment variables

DEBUG Output values of variables and program flow to std_err for easier debugging. Possible values:

  • commented out: disabled (Default).
  • 1 (or non-empty): enabled.

INCLUDE_COMMENTS Include commented and empty lines from configuration snippet files in the generated mpd configuration file:

  • commentend out: disabled (Default).
  • 1 (or non-empty): enabled

CONF_MPD_CONFFILE Path to where the generated mpd configuration file will be written. Possible values:

  • commented out: don't write to a file (Default). One may redirect the output of the script using:

    bash mpd-configure > /path/to/mpd.conf

  • /path/to/mpd.conf: use the path specified.

Alsa and sound

LIMIT_INTERFACE_TYPE A keyword which limits the type of alsa interfaces to be returned:

Possible values:

  • usb, digital or analog
  • Comment it out (or leave it empty) to prevent filtering.

Default value:

  • commented out (or empty ""): do not limit the interfaces that will be found.

LIMIT_INTERFACE_FILTER The available output devices (after filtering with LIMIT_INTERFACE_TYPE when applicable) may be further limited using a regular expression (which thus is case sensentive) which should match the output of:

LANG=C aplay -l | grep ^card

If for example the output is like this:

card 0: MID [HDA Intel MID], device 0: HDMI 0 [HDMI 0]
card 1: receiv [Pink Faun USB 32/384 USB receiv], device 0: USB Audio [USB Audio]

... you could use one of the following values to match the second line (which in this example matches the alsa hw:1,1 interface, eg. the second interface of the second sound card):

"USB Audio"
"[uU][sS][bB] \w+ "

but not

"USB audio"

Possible values:

  • empty or commented out: no filtering is applied
  • Some regular expression: use the (first) interface which matches the regexp.

Default value:

  • commented out (or empty ""): use the first available interface.

Handling of pulseaudio OPT_DISABLE_PULSEAUDIO Disable pulseaudio by modifyin the current users' ~/.pulseaudio/client.conf

Possible values:

  • non-empty (1 or "True") disables pulseaudio.
  • Comment it out (or leave it empty) to prevent disabling of pulseaudio.

Default value:

  • commented out (or empty ""): do not disable it.

OPT_STOP_PULSEAUDIO Temporary disable and stop pulseaudio during detection of alsa interfaces. After the script pulseaudio's client configuration and run state will restored.

Possible values:

  • non-empty (1 or "True") temporary disables and stops pulseaudio.
  • Comment it out (or leave it empty) to prevent temporary disabling and stopping of pulseaudio.

Default value:

  • commented out (or empty ""): do not disable it.

See the configuration snippet files and accompanying README in ./confs-available for additional parameters and and explanation for their functions.

AUTHORS

Written by Ronald van Engelen ronalde@lacocina.nl

Modified and adapted by Ronald Record github@ronrecord.com

LICENSING

MPD-CONFIGURE is distributed under an Open Source license. See the file LICENSE in the MPD-CONFIGURE source distribution for information on terms & conditions for accessing and otherwise using MPD-CONFIGURE and for a DISCLAIMER OF ALL WARRANTIES.

BUGS

Submit bug reports online at:

https://github.com/doctorfree/MusicPlayerPlus/issues

SEE ALSO

mpplus(1), alsa-capabilities(1)

Full documentation and sources at:

https://github.com/doctorfree/MusicPlayerPlus

Clone this wiki locally