Commit cf117be5 authored by Ronald van Engelen's avatar Ronald van Engelen

added commandline parameters

parent 2c40856d
......@@ -48,51 +48,50 @@ The output can simply be redirected to a file (in this example
bash mpd-configure > mympd.conf
````
Although the same may be achieved by setting `CONF_MPD_CONFFILE` on
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:
````bash
CONF_MPD_CONFFILE="mympd.conf" bash mpd-configure
# or, in case the script was downloaded correctly with the execute bit set:
bash mpd-configure -o "mympd.conf"
# or:
CONF_MPD_CONFFILE="mympd.conf" ./mpd-configure
````
### More advanced usage example
Apart from standard settings all configuration parameters for mpd are
available in configuration snippet files in the [`./confs-available/`](./confs-available) directory. By symlinking them to the [`./confs-enabled/`](./confs-enabled) directory,
they will be included by the `mpd-configure` script in the resulting
mpd configuration file. Any bash variable in those configuration
snippets, will be expanded to their calculated values by the
script. Any setting may be specified in the file
`./mpd-configure.conf` or on the command line.
To see all available command line options run the script with `-h` or `--help`:
````bash
bash mpd-configure -h
````
Additional setting are available using environment variables or using
the file [`./mpd-configure.conf`](./mpd-configure.conf) and
configuration snippet files in the
[`./confs-available/`](./confs-available) directory. By symlinking
them to the [`./confs-enabled/`](./confs-enabled) directory, they will
be included by the `mpd-configure` script in the resulting mpd
configuration file. Any bash variable in those configuration snippets,
will be expanded to their calculated values by the script.
For example to specify `CONF_MPD_MUSICDIR` which sets the
`music_directory` and `CONF_MPD_CONFFILE` which specifies the path to
store the resulting configuration file in, run it as follows:
`music_directory` and saving the resulting mpd configuration file in `mympd.conf`, use:
````bash
CONF_MPD_MUSICDIR="/srv/media/music" \
CONF_MPD_CONFFILE="/etc/mpd.conf" \
./mpd-configure
CONF_MPD_MUSICDIR="/srv/media/music" ./mpd-configure -o "/etc/mpd.conf"
````
By default `mpd-configure` prompts the user when the specified file
already exists, and makes a backup of any existing file.
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 (by setting
`DISABLE_PROMPTS`), uses the first available USB Audio Class interface
(by setting `LIMIT_INTERFACE_TYPE=usb`) and sets some paths, while
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:
````bash
DISABLE_PROMPTS="True" LIMIT_INTERFACE_TYPE="usb" CONF_MPD_CONFFILE="/etc/mpd.conf" \
CONF_MPD_MUSICDIR="/srv/media/music" CONF_MPD_HOMEDIR="/var/lib/mpd" \
bash mpd-configure
bash mpd-configure -l u -n -o "/etc/mpd.conf"
````
Also see
......@@ -210,28 +209,7 @@ mixer_type "none"
Detailed usage instructions
---------------------------
For systems with a fixed configuration --eg a PC with a locally
installed mpd connected to some USB DAC or with an internal soundcard--
the script may be invoked manually:
````bash
bash mpd-configure > mpd.conf
````
or
````bash
CONF_MPD_CONFFILE="mpd.conf" bash mpd-configure
````
Both will create the file `mpd.conf` in the current directory,
configured to use the first available audio output interface in bit
perfect mode. If more than one alsa output interface (or DAC) is found, it
will prompt you to specify which one to use. As bitperfect mode
assumes that `mpd` has exclusive access to this output interface, the
script will notify the user if its in use.
After creating such a configuration file, `mpd` can be told to use this
After creating a mpd configuration file, `mpd` can be told to use this
configuration file with:
````bash
......@@ -243,34 +221,10 @@ to the system wide mpd configuration file when you want to run `mpd`
as a system daemon:
````bash
sudo cp ~/mpd.conf /etc/mpd.conf
sudo bash mpd-configure -o "/etc/mpd.conf"
sudo systemctl restart mpd
````
or directly from the script:
````bash
sudo CONF_MPD_CONFFILE="/etc/mpd.conf" bash mpd-configure
sudo systemctl restart mpd
````
Suppose your PC is configured with an internal (embedded) soundcard
and a (single) USB Audio Class external DAC, you may specify the
`LIMIT_INTERFACE_TYPE="usb"` parameter in the `mpd-configure.conf`
file or on the command line, and it will automagically and without
questions configure mpd to use that DAC:
````bash
LIMIT_INTERFACE_TYPE="usb" bash mpd-configure > ~/mpd.conf
````
Or, when you want to store the results in the system wide mpd
configuration file:
````bash
sudo LIMIT_INTERFACE_TYPE="usb" CONF_MPD_CONFFILE="/etc/mpd.conf" \
bash mpd-configure
````
More complex usage
------------------
......@@ -282,9 +236,9 @@ the command line, eg:
DEBUG="True" INCLUDE_COMMENTS="True" bash mpd-configure
````
In dynamic environments --for example a network booted ltsp client,
which hardware may be altered each boot, connected to whatever DAC--
the script should be put in a logon script or systemd service file.
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 a as systemd service
......@@ -340,11 +294,8 @@ edited to run the script and start `mpd` using the script generated
````bash
systemctl stop mpd && \
LIMIT_INTERFACE_TYPE="usb" \
DISABLE_PROMPTS="True " SKIP_BACKUP="True" OPT_QUIET="True" \
CONF_MPD_MUSICDIR="/srv/media/music" CONF_MPD_HOMEDIR="/var/lib/mpd" \
CONF_MPD_CONFFILE=~/.mpd/mpd.conf \
bash ~/mpd-configure/mpd-configure && \
bash ~/mpd-configure/mpd-configure -l usb -n -q --nobackup -o "~/.mpd/mpd.conf" && \
systemctl start mpd
````
......@@ -356,7 +307,7 @@ Preferences can be set in the file `mpd-configure.conf`. By default all
preferences are commented out.
### General parameters
### General environment variables
`DEBUG`
Output values of variables and program flow to std_err for easier
......@@ -372,7 +323,7 @@ the generated mpd configuration file:
- `1` (or non-empty): enabled
`MPD_CONFFILE`
`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
......
......@@ -1300,10 +1300,7 @@ MSG_ALSA_SAMPLERATES="sample rates"
MSG_ALSA_MONITORFILE="monitor file"
## command line options
### optional input parameters, the ones with `:' need an argument
declare -a OPT_LIMIT_ARGS=("a" "analog" "d" "digital" "u" "usb" "uac")
SHORT_OPTS=("l:" "c:" "a:" "s" "q" "h")
## also see analyze_command_line
OPT_LIMIT_AO=${OPT_LIMIT_AO:-}
OPT_LIMIT_DO=${OPT_LIMIT_DO:-}
OPT_LIMIT_UO=${OPT_LIMIT_UO:-}
......
......@@ -12,6 +12,8 @@
## proper settings).
## Also make sure that the `User` specified below has access to the
## target file specified by `CONF_MPD_CONFFILE`.
## In this example the first available USB Audio Class playback device
recognized by alsa will be used.
##
## After copying the file it can be managed using systemd. For example
## to start it manually:
......@@ -38,14 +40,10 @@ Wants=mpd.service
[Service]
User=mpd
Environment="LIMIT_INTERFACE_TYPE=usb"
Environment="DISABLE_PROMPTS=True"
Environment="SKIP_BACKUP=True"
Environment="OPT_QUIET=True"
Environment="CONF_MPD_MUSICDIR=/srv/media/music"
Environment="CONF_MPD_HOMEDIR=/var/lib/mpd"
Environment="CONF_MPD_CONFFILE=/etc/mpd.conf"
ExecStart=/var/lib/mpd/mpd-configure/mpd-configure
ExecStart=/var/lib/mpd/mpd-configure/mpd-configure \
--limit usb --noprompts --nobackup --quiet --output /etc/mpd.conf
[Install]
WantedBy=default.target
......@@ -835,6 +835,8 @@ function do_configure() {
## main function
[[ ! -z "${DEBUG}" ]] && debug_function "${FUNCNAME}" "$*"
analyze_command_line_conf "$@" || exit
## fill the ALSA_AIF_HWADDRESSES and ALSA_AIF_DEVLABELS arrays and
## get a count of number of audio output interfaces
fetch_alsa_hwaddresses
......@@ -900,6 +902,166 @@ ${ALSA_AIF_LABELS[${selected_array_index}]}"
exit
}
function display_usageinfo_conf() {
## display syntax and exit
[[ ! -z ${DEBUG} ]] && \
debug_function_ac "${FUNCNAME}" "$*"
msg=$(cat <<EOF
Usage:
$0 [-o PATH] [ -l a|d|u ] [ -c REGEXP ] [-a HWADDRESS] [-s] [-q] [--nobackup]
Creates a valid mpd configuration file based on the audio playback
interfaces avaliable to alsa. Without settings it prints the results
to stdout.
When multiple alsa playback devices are found, the scripts prompts the
user to enter the alsa hardware address of device to be used. The
\`-l' (\`--limit'), \`-c' (\`--customfilter') and \`-a' (\`--address')
may be used to filter the returned alsa devices.
The \`-q' (\`--quiet'), \`-n' (\`--noprompts') and \`--nobackup'
options are meant for fully automated usage, for instance as a systemd
service.
-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 interfaces to TYPEFILTER. Can be one of
\`a' (or \`analog'), \`d' (or \`digital'),
\`u' (or \`usb', for USB Audio Class (UAC1 or UAC2)
devices).
-c REGEXP, --customlimit REGEXP
Limit the available interfaces (further) to match
\`REGEXP'.
-a HWADDRESS, --address HWADDRESS
Limit the returned interface (further) to the one
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 conf
file (specified with \`-o' or
\`--outputfile'). Setting this option prevents
that and overwrites the file without making a
backup.
-h, --help Show this help message
EOF
)
printf "%s\n" "${msg}" 1>&2;
}
function analyze_command_line_conf() {
## parse command line arguments using the `manual loop` method
## described in http://mywiki.wooledge.org/BashFAQ/035.
[[ ! -z ${DEBUG} ]] && \
debug_function_ac "${FUNCNAME}" "$*"
while :; do
case "${1:-}" in
-o|--output)
if [ -n "${2:-}" ]; then
[[ ! -z ${DEBUG} ]] && \
debug "$(printf "option \`%s' set to \`%s'.\n" "$1" "$2")"
CONF_MPD_CONFFILE="${2}"
shift 2
continue
else
## in alsa-capabilities
analyze_opt_limit "$1"
exit 1
fi
;;
-l|--limit)
if [ -n "${2:-}" ]; then
[[ ! -z ${DEBUG} ]] && \
debug "$(printf "option \`%s' set to \`%s'.\n" "$1" "$2")"
OPT_LIMIT="True"
analyze_opt_limit "$1" "$2"
shift 2
continue
else
## in alsa-capabilities
analyze_opt_limit "$1"
exit 1
fi
;;
-c|--customfilter)
if [ -n "${2:-}" ]; then
[[ ! -z ${DEBUG} ]] && \
debug "$(printf "option \`%s' set to \`%s'.\n" "$1" "$2")"
OPT_FILTER="${2}"
shift 2
continue
else
printf "ERROR: option \`%s' requires a non-empty argument.\n" "$1" 1>&2
exit 1
fi
;;
-a|--address)
if [ -n "${2:-}" ]; then
[[ ! -z ${DEBUG} ]] && \
debug "option \`$1' set to \`$2'"
OPT_HWFILTER="$2"
shift 2
continue
else
printf "ERROR: option \`%s' requires a alsa hardware address \
as an argument (eg \`hw:x,y')\n" "$1" 1>&2
exit 1
fi
;;
-q|--quiet|--silent)
[[ ! -z ${DEBUG} ]] && \
debug "option \`$1' set"
OPT_QUIET=true
shift
continue
;;
-n|--noprompts|--noprompt)
[[ ! -z ${DEBUG} ]] && \
debug "option \`$1' set"
DISABLE_PROMPTS=true
shift
continue
;;
--nobackup|--no-backup)
[[ ! -z ${DEBUG} ]] && \
debug "option \`$1' set"
SKIP_BACKUP=true
shift
continue
;;
-h|-\?|--help)
display_usageinfo_conf
exit
;;
--)
shift
break
;;
-?*)
printf "Notice: unknown option \`%s' ignored\n\n." "$1" 1>&2
display_usageinfo_conf
exit
;;
*)
break
esac
done
}
### program start
## check if we're re being sourced
......@@ -1069,7 +1231,7 @@ if [[ -z "${SOURCED}" ]]; then
[[ ! -z ${DEBUG} ]] && \
debug_configure "start main function \`do_configure' ..."
do_configure
do_configure "$@"
[[ ! -z ${DEBUG} ]] && \
debug_configure "... main function \`do_configure' done."
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment