README 15.1 KB
Newer Older
Ronald van Engelen's avatar
Ronald van Engelen committed
1 2 3 4 5
---
layout: post
title: README for mpd-configure
---

6 7 8
README for mpd-configure
========================

Ronald van Engelen's avatar
Ronald van Engelen committed
9 10 11
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.
12

13 14 15 16 17 18 19
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.

Ronald van Engelen's avatar
Ronald van Engelen committed
20 21 22 23 24 25
More information is available at the following pages:

- [audiophile-mpd]
- [detect-alsa-output-capabilities]


26 27 28
Basic usage
-----------

29 30
### Getting the script

31
The latest stable version of the script may be cloned from github using `git`:
32
```bash
33
git clone https://github.com/ronalde/mpd-configure.git
34 35
```

Ronald van Engelen's avatar
Ronald van Engelen committed
36 37
Using git has the added benefit that updating the script to the latest
version is as easy as:
38 39

```bash
Ronald van Engelen's avatar
Ronald van Engelen committed
40 41
## cd /path/to/git-clone
git pull
42
```
43

Ronald van Engelen's avatar
Ronald van Engelen committed
44
Alternatively, [the tarball of the current stable
45
master](https://lacocina.nl/mpd-configure) can be downloaded and
Ronald van Engelen's avatar
Ronald van Engelen committed
46
unpacked in the current directory using `wget` and `tar`:
47 48

```bash
49
wget https://lacocina.nl/mpd-configure -O - | tar --strip-components=1 -zxf -
50
```
51

52

53 54
### Running the script

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

58
```bash
59
bash mpd-configure
60
```
61 62 63

### Storing the output of the script in a file

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

```bash
68
bash mpd-configure > mympd.conf
69
```
70

Ronald van Engelen's avatar
Ronald van Engelen committed
71 72 73 74 75
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:
76 77

```bash
78 79
bash mpd-configure -o "mympd.conf"
# or:
Ronald van Engelen's avatar
Ronald van Engelen committed
80
CONF_MPD_CONFFILE="mympd.conf" ./mpd-configure
81
```
Ronald van Engelen's avatar
Ronald van Engelen committed
82

83
### More advanced usage example
84 85 86 87

Additional setting are available using environment variables or using
the file [`./mpd-configure.conf`](./mpd-configure.conf) and
configuration snippet files in the
88
[`./confs-available/`](./confs-available) directory. 
89

Ronald van Engelen's avatar
Ronald van Engelen committed
90
For example to specify `CONF_MPD_MUSICDIR` which sets the
Ronald van Engelen's avatar
Ronald van Engelen committed
91 92
`music_directory` and saving the resulting mpd configuration file in
`mympd.conf`, use:
93 94

```bash
95
CONF_MPD_MUSICDIR="/srv/media/music" ./mpd-configure -o "/etc/mpd.conf"
96
```
97

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

101
### Fully automated usage example
102

103 104
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
105 106
creating a backup of the original `/etc/mpd.conf` in case it exists:

107
```bash
108
CONF_MPD_MUSICDIR="/srv/media/music" CONF_MPD_HOMEDIR="/var/lib/mpd" \
109
bash mpd-configure -l u -n -o "/etc/mpd.conf"
110
```
111

112
To see all available command line options run the script with `-h` or `--help`:
113
```bash
114
bash mpd-configure -h
115
```
116

117 118
Also see
- [Detailed usage instructions](#detailed-usage-instructions) for
119
more information on the usage and available settings.
120
- [Usage a as systemd service](#usage-a-as-systemd-service)
121 122


123 124
About the alsa-capabilities helper script
-----------------------------------------
125

126 127 128
[`mpd-configure`](./mpd-configure) relies on the accompanying bash
script [`alsa-capabilities`](./alsa-capabilities) for getting
information about the available audio output interfaces from
129 130 131 132 133 134 135 136 137 138 139 140
alsa. 

However, `alsa-capabilities` may be run from the commandline
independently from `mpd-configure`. It will then display each alsa
audio output interface with its capabilities, like the type
(ie. Analog, Digital or USB Audio Class) and the native (digital)
audio formats it supports, as well as other properties, like it's
character device (in `/dev/snd`) and the file to watch or monitor (in
`/proc/asound`).

With the `-j` (or `--json`) argument the script will produce output in
json format for easy parsing by machines.
141 142

The interfaces returned by the script may be reduced by setting
143
prefab or custom filters. These options can be displayed by running
Ronald van Engelen's avatar
Ronald van Engelen committed
144
the script with the `-h` help option, eg:
145

146
```bash
Ronald van Engelen's avatar
Ronald van Engelen committed
147
    bash alsa-capabilities -h
148
```    
149

150 151
The script can also run 'directly' from github using:

152
```bash
153
    bash <(wget -q -O - "https://lacocina.nl/alsa-capabilities")
154
```
155

156 157
To specify an option (like `-l usb`) use the following syntax:

158
```bash
159
    bash <(wget -q -O - "https://lacocina.nl/alsa-capabilities") -l usb    
160
```
161

162 163
To display the alsa playback interfaces on a remote host to which you
have ssh access, use:
164

165
```bash
166
    ssh ${username}@${remotehost} "bash <(wget -q -O - "https://lacocina.nl/alsa-capabilities")"
167
```
168

169
Proper detection of the sample rates each format supports on an
170
interface currently is very slow for non-USB Audio cards. It therefore
Ronald van Engelen's avatar
Ronald van Engelen committed
171
is a non-default option, `-s` or `--samplerates`.
172

173 174
- It is recommended to *mute all output interfaces* because the script
  will play (pseudo) random noise on each interface.
175

Ronald van Engelen's avatar
Ronald van Engelen committed
176 177
Usage:

178 179 180
```bash
bash alsa-capabilities -s
```
181

182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260
### alsa-capabilities: Usage with web services using json

By using the `-j` (or `--json`) argument, the output of the script is
valid json for easy parsing by web services.

* Example *without* the `-s` (`--samplerates`) argument:

```json
{
      "alsa_outputdevices": [ 
         {
      "id": 1,
      "hwaddr": "hw:0,0",
      "description": "Analog alsa audio output interface",
      "cardnumber": 0,
      "interfacenumber": 0,
      "cardname": "HDA Intel PCH",
      "interfacename": "ALC887-VD Analog",
      "chardev": "/dev/snd/pcmC0D0p",
      "monitorfile": "/proc/asound/card0/pcm0p/sub0/hw_params",
      "streamfile": "(n/a)",
      "usbaudioclass": "(n/a)",
      "encoding_formats": [
		"bycommand`/usr/bin/pulseaudio--daemonize=no'withPID5075."
	] 
     },

  ]
}
```

* Example json output *with* the `-s` (`--samplerates`) argument:

```json
{
      "alsa_outputdevices": [ 
         {
      "id": 1,
      "hwaddr": "hw:0,0",
      "description": "Analog alsa audio output interface",
      "cardnumber": 0,
      "interfacenumber": 0,
      "cardname": "HDA Intel PCH",
      "interfacename": "ALC887-VD Analog",
      "chardev": "/dev/snd/pcmC0D0p",
      "monitorfile": "/proc/asound/card0/pcm0p/sub0/hw_params",
      "streamfile": "(n/a)",
      "usbaudioclass": "(n/a)",
      "encoding_formats": [
		{
"format":"S16_LE",
"samplerates":[
		"44.1",
		"48",
		"88.2",
		"96",
		"176.4",
		"192"
]
},
		{
"format":"S32_LE",
"samplerates":[
		"44.1",
		"48",
		"88.2",
		"96",
		"176.4",
		"192"
]
}
	] 
     },

  ]
}
```


261 262 263
About the mpd-monitor helper script
-----------------------------------

264 265 266 267
The [mpd-monitor](/mpd-monitor) script displays the way a digital audio 
file is streamed from storage (eg. a file), though MPD, to the (USB)DAC.

Usage:
268

269
```bash
270
bash <(wget -q -O - "https://lacocina.nl/mpd-monitor")
271
```
272 273 274 275

Or, when mpd is running on a remote host to which you have (key based)
ssh access, execute:

276
```bash
277
bash <(wget -q -O - "https://lacocina.nl/mpd-monitor") -m $MPD_HOST -p $MPD_PORT -u $SSH_USER -d ${MUSICDIR}
278
```
279 280 281

For example:

282
```bash
283
bash <(wget -q -O - "https://lacocina.nl/mpd-monitor") -m mpd -u root -d /srv/media/music
284
```
285

286
- NOTE: *The mpd-monitor script is in a testing state.*
287 288


289 290 291
Background
----------

292 293 294
I created this script to assist users in turning mpd in an audiophile
digital music player. See the article [How to turn Music Player Daemon
(mpd) into an audiophile music
295
player](https://lacocina.nl/audiophile-mpd).
296

297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316
It does this by creating a proper formatted `audio_output`
configuration snippet for mpd's [alsa audio output
plugin](http://www.musicpd.org/doc/user/config_audio_outputs.html)
using the sound cards hardware address and turning all options off
which might cause mpd to alter the incoming sound. For example:

````bash
## start processing `01_output-audio-alsa.conf'
audio_output {
        type             "alsa"
        name             "Peachtree 24/192 USB X - USB Audio"
        device           "hw:1,0"
        auto_resample    "no"
        auto_format      "no"
        auto_channels    "no"
}
replaygain                 "off"
mixer_type                 "none"
## done processing
````
317

318 319
Detailed usage instructions
---------------------------
320

321
After creating a mpd configuration file, `mpd` can be told to use this
322
configuration file with:
323

Ronald van Engelen's avatar
Ronald van Engelen committed
324 325 326
````bash
    mpd ./mpd.conf
````
327

328 329 330
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:
331

Ronald van Engelen's avatar
Ronald van Engelen committed
332
````bash
333
    sudo bash mpd-configure -o "/etc/mpd.conf"
Ronald van Engelen's avatar
Ronald van Engelen committed
334 335
    sudo systemctl restart mpd
````
336

337 338 339
More complex usage
------------------

340 341 342
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:
343

Ronald van Engelen's avatar
Ronald van Engelen committed
344 345 346
````bash
    DEBUG="True" INCLUDE_COMMENTS="True" bash mpd-configure
````    
347

348 349 350
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.
351

352 353 354 355
## Usage a as 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
356 357
the service file systemd makes sure mpd-configure is run before mpd is
started, and tries to start mpd.
358

359
- See: [./examples/systemd_mpd-configure.service](./examples/systemd_mpd-configure.service)
360

361

362 363
### Usage from within another bash or sh script

364
The bash script
365
[./examples/bash-example.sh](./examples/bash-example.sh)
366 367
demonstrates the way alsa-capabilities can be used from another bash
script.
368

369 370
This demo script returns the monitoring file of the file specified as
an argument:
371 372 373 374 375 376 377 378 379 380 381

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

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

382

Ronald van Engelen's avatar
Ronald van Engelen committed
383 384
### Usage from within python

385 386
Assuming your in the `mpd-configure` directory, run:
````bash
387
    python examples/get-interfaces.py
388 389 390
````

The python script
391
[./examples/get-interfaces.py](./examples/get-interfaces.py)
392
uses a helper bash script
393
([./examples/get-interfaces-for-python.sh](./examples/get-interfaces-for-python.sh)),
394
which in turn sources `alsa-capabilities`.
395

396

397 398 399 400 401 402 403 404 405 406 407
### LTSP-specific auto logon sample

For my LTPS-environments the script directory can be copied to the
home directory of the auto logon user specified in
`/var/lib/tftpboot/ltsp/i386/lts.conf`. It's `~/.profile` should be
edited to run the script and start `mpd` using the script generated
`~/.mpd/mpd.conf`, ie:

````bash
    systemctl stop mpd && \
    CONF_MPD_MUSICDIR="/srv/media/music" CONF_MPD_HOMEDIR="/var/lib/mpd" \
408
    bash ~/mpd-configure/mpd-configure -l usb -n -q --nobackup -o "~/.mpd/mpd.conf"  && \
409 410 411 412
    systemctl start mpd
````


413 414 415
Preferences
-----------

416
Preferences can be set in the file `mpd-configure.conf`. By default all
417
preferences are commented out.
418

419 420 421 422 423 424 425
The script uses configuration file snippets in the
[`./confs-available/`](./confs-available) directory. By symlinking
them to the [`./confs-enabled/`](./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.

426

427
### General environment variables
428

429
`DEBUG`
430 431
Output values of variables and program flow to std_err for easier
debugging. Possible values:
432
- commented out: disabled (Default).
433
- `1` (or non-empty): enabled.
434 435


436 437 438
`INCLUDE_COMMENTS`
Include commented and empty lines from configuration snippet files in
the generated mpd configuration file:
439
- commentend out: disabled (Default).
440
- `1` (or non-empty): enabled
441 442


443
`CONF_MPD_CONFFILE`
444 445
Path to where the generated mpd configuration file will be
written. Possible values:
446 447 448
- commented out: don't write to a file (Default). One may redirect the
  output of the script using:

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

451
- `/path/to/mpd.conf`: use the path specified.
452

453 454 455

### Alsa and sound

456 457
`LIMIT_INTERFACE_TYPE`
A keyword which limits the type of alsa interfaces to be returned: 
458

459
Possible values:
460
- `usb`, `digital` or `analog`
461 462
- Comment it out (or leave it empty) to prevent filtering.

463
Default value:
464
- commented out (or empty ""): do not limit the interfaces that will be found.
465 466


467 468 469 470 471
`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:
472 473

    LANG=C aplay -l | grep ^card
474

475
If for example the output is like this:
476

477 478
    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]
479

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

484 485 486 487 488 489 490
    "USB Audio"
    "[uU][sS][bB] \w+ "

but not

    "USB audio"

491

492
Possible values:
493
- empty or commented out: no filtering is applied
494
- `Some regular expression`: use the (first) interface which matches the regexp.
495

496
Default value:
497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522
- 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.
523 524


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

529

530 531
Reference
---------
532

533 534 535
MPD specific:

- [How to turn Music Player Daemon (mpd) into an audiophile music
536
player](https://lacocina.nl/mpd-configure-audiophile).
537
- [What digital audio format does your USB DA-converter support and
538
  use?](https://lacocina.nl/detect-alsa-output-capabilities)
Ronald van Engelen's avatar
Ronald van Engelen committed
539
- [Music Player Daemon (MPD)](http://www.musicpd.org/)
540 541 542

LTSP specific:

543 544
- [How to setup a bit-perfect digital audio streaming client with free
  software (with LTSP and
545
  MPD)](https://lacocina.nl/how-to-setup-a-bit-perfect-digital-audio-streaming-client-with-free-software-with-ltsp-and-mpd)
546
- [Linux Terminal Server Project (LTSP)](http://www.ltsp.org/)
Ronald van Engelen's avatar
Ronald van Engelen committed
547 548


549 550
[audiophile-mpd]:  https://lacocina.nl/audiophile-mpd "mpd-configure: automatically turn Linux into an audiophile music player"
[detect-alsa-output-capabilities]: https://lacocina.nl/detect-alsa-output-capabilities "Alsa-capabilities shows which digital audio formats your USB DA-converter supports"
Ronald van Engelen's avatar
Ronald van Engelen committed
551 552 553

[mpd]: http://www.musicpd.org/ "Music Player Daemon (external website)"