upmpdcli-config.txt 16.5 KB
Newer Older
1
2
== Upmpdcli configuration 

3
4
=== Upmpdcli general parameters 

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
[[logfilename]]
logfilename:: Log file
name. Defaults to stderr. This can also be specified as -d
logfilename.

[[loglevel]]
loglevel:: Log
level. Can also be specified as -l loglevel.

[[pkgdatadir]]
pkgdatadir:: XML and other constant data storage
directory. Default: '$prefix/share/upmpcli' (e.g.:
'/usr/share/upmpdcli').

[[pidfile]]
pidfile:: Name of lock file used to store the
current process pid. Only used if the process is launched
by user root. Used by the init system, and to avoid multiple
instances. The only reason to change the value is if you actually want to
have several instances running (also change cachedir in this
case).

=== UPnP network parameters 

[[upnpiface]]
upnpiface:: Network interface to
use for UPnP. libupnp/pupnp only supports communicating on
a single interface and will use the first found, this allows forcing the
use of another interface.

[[upnpip]]
upnpip:: IP address to use for UPnP,
alternative to using an interface name. 

[[upnpport]]
upnpport:: Port number
used for UPnP. libupnp/pupnp defaults to using the first
free port after 49152. Note that clients do not need to know about the
value, which is automatically discovered.

=== Media Renderer parameters 

47
[[friendlyname]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
48
49
50
51
friendlyname:: "Friendly Name" for the
UPnP Media Renderer. This will be displayed by most Control
Points to identify the Renderer. Some OpenHome Control Points may display
the 'ohproductroom' value instead.
52

53
[[upnpav]]
54
55
56
57
58
upnpav:: Enable UPnP AV services
(0/1). This is set by default, but it may useful to switch
it off with some OpenHome Control Points which are too easily confused by
the presence of UPnP AV services.

59
[[openhome]]
60
61
62
63
64
openhome:: Enable OpenHome services
(0/1). This defaults to 1, as OpenHome queuing is superior
for most usages. There should be little reason to turn it
off.

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
65
66
67
68
69
70
[[lumincompat]]
lumincompat:: For upmpdcli
version 1.3: enable Lumin compatibility mode (lose ohcredentials)
(0/1). For some unknown reason, Lumin 1.10 can't discover
upmpdcli when the OpenHome Credentials service is enabled. Setting this
allows upmpdcli to work with Lumin, at the cost of losing the use of the
71
Credentials service (normally used for logging in to Qobuz or Tidal inside
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
72
73
Kazoo).

74
75
76
77
78
79
80
81
82
[[saveohcredentials]]
saveohcredentials:: Save the streaming
services login parameters to disk. This allows sharing the
password with the upmpdcli media server streaming service proxy, if you
are also using it. Avoids having to enter the password in the regular
configuration file. Depending on your situation, you may see this as a
security risk. The default is true, because I don't see this as a real
issue in the general case.

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
83
84
85
86
87
88
89
[[checkcontentformat]]
checkcontentformat:: Check that
input format is supported. Extract the protocolinfo
information from the input metadata and check it against our supported
formats. Set this option to 0 if a control point or media server sends
good audio data with bad metadata.

90
91
92
93
[[opensslcmd]]
opensslcmd:: Path to the openssl command The OHCredentials service needs openssl 1.1.x or newer.
Path to the openssl command to use if the system one (in /usr/bin) is too
old. Not set by default.
94

95
[[iconpath]]
96
97
98
99
100
101
102
103
iconpath:: Path to the Renderer icon. The image will be displayed by Control Points which support
it. The UPnP protocol has provisions for a renderer to send the URL to a
descriptive icon as part of the device description. Due to current (and
probably permanent) *upmpdcli* limitations, the image file *must* be a
64x64 32 bits-per-pixel png file. Default: '$pkgdatadir/icon.png'.
The icon will only be read once, when upmpdcli starts
up.

104
[[cachedir]]
105
106
107
108
109
cachedir:: Directory used to store cached
data Only used for the OpenHome queue metadata for now.
The default value is ~/.cache/upmpdcli for normal users or
/var/cache/upmpdcli when upmpdcli is started as root.

110
[[presentationhtml]]
111
112
113
114
115
116
117
presentationhtml:: Path to the presentation HTML
document You can change it to replace the default
presentation page. The page will only be read once, when upmpdcli starts
up. It can't presently be used for status updates (but I guess that you
could put a redirect in there, to something more dynamic served by a real
HTTP server). Default: '$pkgdatadir/presentation.html'.

Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
118
119
=== MPD parameters 

120
[[mpdhost]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
121
122
123
mpdhost:: Host MPD runs on. Defaults to localhost. This can also be specified as -h
host

124
[[mpdport]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
125
126
127
128
mpdport:: IP port used by
MPD Can also be specified as -p port. Defaults to the
normal MPD port, 6600

129
[[mpdpassword]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
130
131
132
133
134
mpdpassword:: MPD
password. Password for connecting to MPD (only necessary
if password access is enabled in the MPD configuration
file).

135
[[ownqueue]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
136
137
138
139
ownqueue:: Set if we own the MPD
queue. If this is set (on by default), we own the MPD
queue and will fearlessly clear it. Can also be specified as -q
0|1.
140
141
142

=== Audio control hooks 

143
[[onstart]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
144
145
146
onstart:: Command to run when playback is
about to begin. Specify the full path to the program,
e.g. /usr/bin/logger.
147

148
[[onplay]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
149
150
onplay:: Command to run when MPD state
switches to "PLAY".   Specify the full path to the program,
151
152
e.g. /usr/bin/logger.

Shoaib Ahmed's avatar
Shoaib Ahmed committed
153
154
155
156
157
[[onpause]]
onpause:: Command to run when MPD state
switches to "PAUSE".   Specify the full path to the program,
e.g. /usr/bin/logger.

158
[[onstop]]
159
160
161
162
onstop:: Command to run when MPD state switches to
"STOP". Specify the full path to the program,
e.g. /usr/bin/logger.

Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
163
164
165
166
167
168
169
[[onstandby]]
onstandby:: Command to run when the setstandby
action is called. Specify the full path to the program. It
is called with one 0/1 argument to change the standby state (1 for activating
standby), and with no argument to query the state. In all cases, it should
print the standby state (0/1) to stdout before exiting.

170
[[externalvolumecontrol]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
171
172
173
174
175
176
177
externalvolumecontrol:: Use external command
to manage the the sound volume (0/1). This is used in the
case where MPD is unable to control the volume, but some other command
can, for example if you have an external amp on which it is possible to
set and read the volume through scripts. If set, the calls to MPD to set
and read the volume will be replaced by executions of 'onvolumechange'
and 'getexternalvolume'
178

179
[[getexternalvolume]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
180
181
182
getexternalvolume:: Command to run for reading
the sound volume. The command should write a 0-100 numeric
value to stdout.
183

184
[[onvolumechange]]
185
186
187
188
189
190
191
onvolumechange:: Command to run to set the
volume. Used when 'externalvolumecontrol' is set.
Specify the full path to the program, which is called with the volume as
the first argument, e.g. /some/script 85.

=== OpenHome parameters 

192
193
194
195
196
197
198
199
200
[[ohproductroom]]
ohproductroom:: The name of the room where
the Product is located. Set to “Main Room” by default,
displayed in place of the "friendly name" by some control points.
ProductRoom is used to group the Product with other related Products in
the same physical room (e.g. a source with a pre-amp). Products which are
physically linked must always share the same ProductRoom
name.

201
[[radiolist]]
202
203
radiolist:: Path to an external file with radio
definitions. Radio stations can be defined at the end of
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
204
the main file, or in an external file (or both). Using an external file
205
can ease distribution to multiple machines. Either way, each radio
206
207
208
209
210
211
212
station is defined as a section with a name beginning with 'radio',
containing a mandatory URL parameter, and optional values. The part of
the name after 'radio' will be the displayed radio name (as album title).
- artUrl: an optional static radio icon URL.
- artScript: an optional script to retrieve an image for the current title
- metaScript: an optional script to retrieve metadata for the current
title.
213
- preferScript: decide if values from script should override icy metadata
214
215
216
See the xref:radio-definitions[section about radio station definitions]
for details about the scripts.
Example:
217
218
219
220
----
[radio My Radio]
url = http://some.host/some/path.pls
artUrl = http://some.host/icon/path.png
221
artScript = /path/to/script/dynamic-art-getter
222
metaScript = /path/to/script/metadata-getter
223
preferScript = 1
224
225
226
----


227
[[ohmanufacturername]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
228
229
ohmanufacturername:: Manufacturer
name.  
230

231
[[ohmanufacturerinfo]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
232
233
ohmanufacturerinfo:: Manufacturer
information.  
234

235
[[ohmanufacturerurl]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
236
237
ohmanufacturerurl:: URL for manufacturer
web site.  
238

239
[[ohmanufacturerimageuri]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
240
241
ohmanufacturerimageuri:: Uri for
manufacturer’s logo.  
242

243
[[ohmodelname]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
244
ohmodelname:: Model name. 
245

246
[[ohmodelinfo]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
247
ohmodelinfo:: Model information. 
248

249
[[ohmodelurl]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
250
251
ohmodelurl:: URL for model web
site. 
252

253
[[ohmodelimageuri]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
254
255
ohmodelimageuri:: Uri for model’s
icon.  
256

257
[[ohproductname]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
258
259
ohproductname:: User-visible product
name. By default this is set to ModelName. 
260

261
[[ohproductinfo]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
262
263
ohproductinfo:: Product information.
 
264

265
[[ohproducturl]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
266
267
ohproducturl:: URL for product web
site. This may be the UPnP presentation page. 
268

269
[[ohproductimageuri]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
270
271
ohproductimageuri:: Uri for product
image.  
272

273
274
275
276
277
278
279
280
281
282
283
284
285
[[ohmetapersist]]
ohmetapersist:: Save queue
metadata to disk (0/1). This allows persistence of the
metadata information across restarts, the default is 1, and there is no
reason to turn it off.

[[ohmetasleep]]
ohmetasleep:: Mimimum
interval (Seconds) between two cache saves. Increasing this
may improve playlist load speed on a slow device. The default is to start
a new save as soon as the previous one is done (if the list changed again
inbetween).

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
286
287
288
289
290
291
292
293
=== Media Server general parameters 

[[msfriendlyname]]
msfriendlyname:: Friendly name for the
Media Server (if enabled). The default is to append
"-mediaserver" to the friendlyname value.

[[plgmicrohttpport]]
294
295
296
297
298
plgmicrohttpport:: IP
port for the tidal/qobuz/gmusic local HTTP service. The
URLs for tracks streamed from these services point to a local microhttpd
server running on this port (it uses redirection to the actual service
URL when actually streaming). The default is 49149.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
299

300
301
302
303
304
305
[[plgproxymethod]]
plgproxymethod:: Decide if we proxy (copy: fetch/serve), or redirect the streaming
services streams. Using redirect is much more efficient,
but the proxy has a facility to retry when a stream is dropped by the
service, which seems to happen esp. with Qobuz.

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
=== Tidal streaming service parameters 

[[tidaluser]]
tidaluser:: Tidal user name. Your Tidal login name.

[[tidalpass]]
tidalpass:: Tidal password. The password for your Tidal account.

[[tidalquality]]
tidalquality:: Tidal stream quality. 'low' and 'high' are aac
streams. 'lossless' is FLAC and will only work if your subscription
allows it.

=== Qobuz streaming service parameters 

[[qobuzuser]]
qobuzuser:: Qobuz user name. Your Qobuz login name.

[[qobuzpass]]
qobuzpass:: Qobuz password. The password for your Qobuz account.

[[qobuzformatid]]
qobuzformatid:: Qobuz stream quality. 5 for mp3/320, 7 for FLAC if
your subscription allows it.

=== Google Music streaming service parameters 

[[gmusicuser]]
gmusicuser:: Google Music user name. Your Google Music login name (probably a gmail address).

[[gmusicpass]]
gmusicpass:: Google Music password. The password for your Google Music account.

[[gmusicquality]]
gmusicquality:: Google Music stream quality. 'hi' for mp3/320, 'med'
for mp3/160, 'low' for mp3/128.

[[gmusicdeviceid]]
gmusicdeviceid:: Google Music device
id. Your system MAC address will be used by default, but
346
347
348
349
350
351
352
353
354
355
356
357
358
it seems that this does not work any more and that an Android deviceid is
needed. upmpdcli will try to get one from the list of registered
devices. If this does not work, you will need to set the gmusicdeviceid
value to the device ID from a phone or tablet on which you also use
Google Play Music (look up "Android deviceid" for help).

=== Spotify streaming service parameters 

[[spotifyuser]]
spotifyuser:: Spotify user name. Your Spotify login name.

[[spotifypass]]
spotifypass:: Spotify password. The password for your Spotify account.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373

=== Local Media Server parameters 

[[uprcluser]]
uprcluser:: Bogus user name variable. Used for consistency with other Media Server plugins to decide if
the service should be started (so, do set it if you want a Media Server).


[[uprclmediadirs]]
uprclmediadirs:: Media
directories This is a space-separated list of directories
to explore for music files. This is used directly as the recoll "topdirs"
value, so you can use double-quote quoting for paths with embedded
spaces.

374
375
376
377
378
[[uprcltitle]]
uprcltitle:: Plugin Title. This
will be displayed as the plugin entry in the Media Server root
directory.

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
379
[[uprclhostport]]
380
uprclhostport:: HTTP host and port for
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
381
382
383
384
385
386
387
serving media files The Media Server HTTP server will run
on this address and port, which will also be inserted on the URLs we
produce. If the variable is not set, we will use port 9090 and the first
non-loopback ipv4 address in "ip addr" output, which may be right or
not. Example: 192.168.1.1:9090

[[uprclpaths]]
388
389
390
uprclpaths:: Path translations. Translations from real paths to ones relative to the HTTP server
doc tree. If this is not set, uprcl will use a null translation for each
of the uprclmediadirs entries.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
391
392
393
394

[[uprclconfdir]]
uprclconfdir:: Recoll index
directory This is usually not defined and defaults to
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
395
396
397
/var/cache/upmpdcli/uprcl. The name is a bit misleading because there is
no real configuration data in there: it's all programmatically
generated from actual configuration found elsewhere.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
398
399
400
401
402
403

[[uprclautostart]]
uprclautostart:: Initialize uprcl as soon as
upmpdcli starts This is useful because uprcl initialization
can take quite some time so it is better not to wait for the first
access. The general default is false for the autostart variables, so this
404
needs to be explicitely set to true.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
405

406
407
=== Songcast Receiver parameters 

408
[[sclogfilename]]
409
410
sclogfilename:: Log file name for sc2mpd (default
stderr) The value *must not* be the same as the one used
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
411
for upmpdcli (except if empty).
412

413
[[scloglevel]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
414
415
scloglevel:: Log verbosity for
sc2mpd. 
416

417
[[scplaymethod]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
418
419
420
421
scplaymethod:: sc2mpd
play method (mpd/alsa). With this set as 'alsa', sc2mpd
will send the audio directly to the sound driver, which is the only way
to really avoid skips and control the synchronization in multi-room
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
422
423
setups. *For 'alsa', make sure that user upmpdcli has permission to
access the audio devices !*
424

425
[[schttpport]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
426
427
428
429
schttpport:: Port
used by sc2mpd for MPD to connect to. Used only for
scplaymethod=mpd. sc2mpd only accepts connections from
localhost.
430

431
[[scalsadevice]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
432
433
434
scalsadevice:: Alsa device used by sc2mpd
for playing audio. Only used for scplaymethod=alsa. Use
'aplay -L' to see the possible values.
435

436
[[sccvttype]]
437
438
439
440
441
442
443
444
445
446
sccvttype:: sc2mpd resampling method. 
Only used for scplaymethod=alsa. sc2mpd uses libsamplerate. The default
method is SRC_SINC_FASTEST and a Rasberry Pi 1 is fast enough to use it.
Possible values: SRC_SINC_BEST_QUALITY, SRC_SINC_MEDIUM_QUALITY,
SRC_SINC_FASTEST, SRC_ZERO_ORDER_HOLD, SRC_LINEAR.  See the libsamplerate
documentation for descriptions. Anything above SRC_SINC_FASTEST needs a
serious CPU.  BEST_QUALITY uses approx 25% cpu on a core i7
4770T. Obviously too much, actually might not be sustainable (it's almost
100% of 1 cpu).  MEDIUM_QUALITY is around 10% on the same machine,
FASTEST is 4-5%. Given that this is measured for the full process, probably
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
447
448
449
a couple % for the conversion in fact. NONE will turn resampling off:
minimum CPU and best quality, but guaranteed glitches from time
to time, depending on the clocks skew.
450

451
[[sc2mpd]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
452
453
454
sc2mpd:: Path to
sc2mpd. Only useful if it is not in /usr/bin and the
location is not in the $PATH for the init scripts.
455

Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
456
457
458
459
460
461
462
[[screceiverstatefile]]
screceiverstatefile:: Path to a screceiver
state file. If set, the sender uri and metadata will be read
from the file when initializing the Songcast Receiver service and written to
the file when a Sender is set for the service. Useful for preserving the
sender information between restarts.

463
464
=== Songcast Sender parameters 

465
466
467
468
469
470
[[scstreamcodec]]
scstreamcodec:: !!Standard Songcast receivers only support PCM!! Codec to use for
the network stream. Set to empty or PCM to support
foreign receivers. Or use FLAC or OPUS for lower network
load.

471
[[scsenderpath]]
472
473
474
scsenderpath:: Path to starter script This is normally scmakempdsender which starts the auxiliary mpd
and the sender process. Empty and searched in the PATH by
default.
475

476
[[scstreamscaled]]
477
478
479
480
481
scstreamscaled:: Scale the
Songcast stream. If set, MPD software volume control will
be applied to the stream. True by default: using a Control Point to set
the volume on the upmpdcli instance which started the Sender affects the
volume for all Receivers.
482

483
[[scsendermpdport]]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
484
scsendermpdport:: localhost port to be used by the auxiliary mpd. 
485

486
[[scripts_dir]]
487
488
489
490
scripts_dir:: External sources script
directory. Location for the scripts used to set up
additional external sources. See the Songcast Sender support
documentation page.
491

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
492
493
494
495
[[scscriptgracesecs]]
scscriptgracesecs:: Grace period to wait for
a script process to exit before it is forcely killed. In seconds. Default 2 S.

496