upmpdcli-manual.txt 65.8 KB
Newer Older
1
= Upmpdcli
2
:toc: left
3
4
5

== Introduction

6
7
Upmpdcli is primarily an UPnP Renderer front-end to the MPD music player.
It has a number of additional or alternative functions.
8
9
10
11
12

The xref:UPNP[next section] explains the network audio terms (UPnP, Media
Renderer, etc.) if your knowledge needs a little brushing up. Else, you can
jump to the xref:UPMPDCLI-OVERVIEW[upmpdcli overview] section.

13
14
Do not scrap your old amp yet, with 100 Euros (a Raspberry Pi and a high
quality DAC I2S daugtherboard) you can transform it into a state of the art
15
network streamer.
16

17
=== Security
18

19
20
21
22
WARNING: The UPnP protocols have no security
provisions. Upmpdcli is not audited for security issues, and, as far as I
know, it is full of exploitable bugs. Do not run it on an Internet-facing
host.
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

[[UPNP]]
== UPnP and all that

=== UPnP AV

UPnP is a family of network protocols, designed for easily connecting
_stuff_ in home networks (mostly). Its name ("Universal Plug and Play") was
chosen because little or no configuration is needed for the different
elements to discover each other and play together.

The UPnP audio/video section (UPnP AV) implements a way for data stored on
a network host (PC, NAS, etc.) to be displayed on another one (TV, audio
streamer, etc.).

Generally, there are four building blocks in a network audio solution:

- An audio File/Data server stores the (bulky) audio data and makes it
  available to clients using an appropriate protocol (NFS, SMB, HTTP,
  etc. depending on client).
- The directory/tags manager extracts audio tags from the files (usually
  accessing them directly or through a network file sharing protocol), and
  builds a database used for searching or browsing the collection.
- Audio players (renderers) take encoded audio data and actually make
  sound, using some kind of DAC (Digital Analog Conversion) device, such as
  an internal or USB sound card.
- The user interface is a remote control which sits in your hand (or it's
  the PC in front of you). You use the application which runs on it to
  choose songs from the database and control the playback. It interacts
  both with the tags database and player parts (usually not with the file
  server, except maybe to fetch cover art).

.Network Audio
image::pics/netaudio.png["Network Audio Elements"]

In the UPnP world:

 - The tags manager is named Media Server (more precisely, the Content
   Directory service inside the Media Server device). Data is usually
   stored on the Media Server, but it could also live elsewhere. Data
   access is almost always performed through HTTP.
 - The player is named Media Renderer. It usually does not implement much
   user interface.
 - The remote control is named Control Point
  
The good people who specified UPnP AV got something wrong: the playlist
is owned by the Control Point, not by the Renderer. This means that the
Renderer will not play the next track if the Control Point goes to sleep,
and that havoc is almost guaranteed if several Control Points try to share
72
a Renderer. This is the main reason for using OpenHome (see <<OPENHOME,next>>).
73

74
[[OPENHOME]]
75
76
=== OpenHome

77
78
79
80
The link:http://wiki.openhome.org/wiki/OhMediaDevelopers[OpenHome] family
of open protocols were designed by link:http://www.linn.co.uk/[Linn] to correct
the weaknesses in UPnP AV. They implement extended services over the base
UPnP mechanisms.
81
82
83
84
85
86
87

Principally, the OpenHome playlist lives on the Renderer. It will continue
playing if the Control Points goes to sleep, and it can be shared. This is
a compelling advantage and most well-known Control Points (e.g. BubbleUPnP,
Kazoo, PlugPlayer...) support OpenHome.

Beyond this, OpenHome also defines additional services, for example for
88
89
90
91
92
93
94
95
accessing Internet radios. The different possible origins of audio data
inside an OpenHome Renderer are named _Sources_, e.g. Radio Source,
Playlist Source. Sources are switchable from any Control Point supporting
OpenHome.

OpenHome Sources are designated by a type and name, and a Renderer can have
any number of them (for example, Upmpdcli uses additional sources to
control its Sender mode).
96
97
98

=== Songcast 

99
100
101
102
103
104
link:http://oss.linn.co.uk/trac/wiki/Songcast[Songcast] is an open protocol
designed by Linn for real-time network audio. Its only relationship
with UPnP is that UPnP services are used to control the
connections. Songcast allows playing the same audio on multiple players,
with almost perfect synchronization, or capturing audio on a computer to
play it on another system.
105
106
107
108
109
110

The protocols links two types of entities:

 - A Songcast Sender generates an audio stream.
 - One or several Songcast Receivers receive and play the stream.

111
112
113
114
115
Linn supplies free audio capture drivers functionning as Songcast Senders,
for MS-Windows and Mac OS X.  This enables playing the audio of *any*
application (Windows Media Player, Spotify, Tidal, etc.) onto one or
several Songcast Receivers, without any need for the applications to know
about Songcast.
116
117
118
119
120
121

=== Gapless ?
 	
This is a relatively small issue, but people are very sensitive to it, it
is important from some music pieces (Goldberg variations with gaps: not
nice) and you will hear about it all the time if you read forums, so, a
122
quick explanation follows.
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

Some music tracks need to flow into each other when played consecutively,
for example tracks on some live albums (the background noise from the
audience never stops), or some classical music pieces. 

When playing from separate audio files, it is not trivial for a renderer to
ensure a seamless flow: the audio hardware has an input pipe which must be
kept full at all times, else it will stop, and a period of silence will
ensue: not gapless ! 

To avoid this, the renderer has to know in advance which file it will
process after the current one, to be able to begin filling the audio pipe
with data from the next track before it empties at the end of the current
one.

There are two ways that this can be achieved: either the renderer is also
in charge of the play queue, so it knows the whole sequence all the time
(e.g. MPD, OpenHome, …), or the controller indicates the next track to the
141
142
renderer before the current track finishes (e.g. UPnP SetNextTransportURI).

143
144
145
146
147
148
149
150
151
152
153
154
155

[[UPMPDCLI-OVERVIEW]]
== Upmpdcli overview


Upmpdcli is primarily a UPnP Media Renderer frontend, using a slave MPD to
actually process the audio data. It supports UPnP gapless track transitions
and the OpenHome ohMedia services (including a Radio service to listen to
Internet streams). 

.The Grand Upmpdcli Scheme of Things
image::pics/upmpdcli.png["The Grand Scheme of Things"]

156
157
158
Additionally:

- Upmpdcli implements control functions for the Linn Songcast protocol,
159
allowing the local machine to behave as a Songcast Receiver or Sender (with
160
161
help from the closely related *sc2mpd* package, for processing the audio
streams).
162

163
- Upmpdcli provides a Media Server interface, mostly used for accessing
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
164
165
external streaming services (Spotify, Highresaudio, Qobuz, Deezer). The
*uprcl* module provides a local Media Server based on the
166
link:https://www.recoll.org[Recoll] medata extraction and search functions.
167
168
169
170
171
172
173
174
175
176
177

Upmpdcli can be installed on most Linux systems. It is frequently used on
small single board computers like the Raspberry Pi. As far as I know, all
audio-oriented distributions currently use it as their UPnP Media Renderer
interface, and it is also present in a number of commercial devices.

Upmpdcli is mostly configured through values set in a configuration file
but, for basic operation without a configuration file, a few of the main
parameters can be set on the
xref:COMMAND-ENVIRON[command line or in the environment].

178
Most parameters can only be set in the configuration file, which is
179
180
designated with the `-c` command line option. The usual location is
`/etc/upmpdcli.conf`.
181

182
183
The configuration file has a simple `name = value` format, and is fully
described in the <<UPMPDCLI-CONFIGURATION,configuration reference section>>.
184

185
186
187
188
189
190
191
upmpdcli has many configuration parameters, which may make the
configuration intimidating. However, most parameters only relate to one
function of the program and they are grouped in sections, many of which
are probably not relevant to you. In each section, the most important
parameters are presented first, and you probably will never need to bother
with the bottom of the list.

Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
192
The <<UPMPDCLI-CONFIG-GUI,upmpdcli-config graphical tool>> can help you edit
193
194
the configuration file, it can present the same information as this manual,
directly linked with the controls used to modify the parameters.
195
196

[[UPMPDCLI-RENDERER]]
197
198
199
== Upmpdcli Media Renderer


200
////
201
202
// Note about configuration section refs: only the first parameter in a
// subsection can be referenced, and it references the whole
203
// subsection. Hence refs like <<mpdhost,`mpdport`>>, which are not typos
204
////
205

206
207
208

This section goes in a little more detail about miscellaneous aspects of
the Media Renderer, and describe a few of the most used configuration
209
parameters. See the <<UPMPDCLI-CONFIGURATION,configuration reference section>>
210
for more details (I would very much like to link each parameter to its
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
211
212
definition but Asciidoc won't let me do it, so they link to the top of the
appropriate section.).
213
214
215

If several instances of *upmpdcli* run on the same network, you will want
to give them distinct names. The name which is displayed by most Control
216
Points can be set with the <<friendlyname,`friendlyname`>> configuration
217
parameter. Some Linn Control Points (e.g. Kazoo) use another value, set
218
with <<ohproductroom,`ohproductroom`>>.
219
220
221

Upmpdcli usually controls the MPD instance running on the same
host. However, there may be reasons to do otherwise, and the host name and
222
223
port where mpd should be reached can be set with <<mpdhost,`mpdhost`>>,
and <<mpdhost,`mpdport`>>.
224
225

The Upmpdcli Media Renderer has two active interfaces by default: UPnP AV
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
226
227
228
229
230
and OpenHome. Only OpenHome Control Points can share the renderer. If you
use an UPnP AV Control Point, it must be the only one. This is not
enforced, and misuse will result in miscellaneous weirdnesses. In some
special situations, it may be useful to limit the interface to UPnP AV or
OpenHome only (or disable both), which can be done with the
231
<<friendlyname,`openhome`>> and <<friendlyname,`upnpav`>> parameters.
232
233
234
235
236
237
238

[[UPMPDCLI-RENDERER-FORMATS]]
=== Audio formats

Upmpdcli can accept most audio formats supported by MPD, meaning about
anything, including DSD.

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
239
240
241
Upmpdcli normally checks that the format of a resource to be played is
compatible with what it thinks MPD can do. This check is sometimes
pessimistic and can be disabled by setting
242
<<friendlyname,`checkcontentformat`>> to 0.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
243

244
245
246
247
248
You should know that MPD has difficulties with some formats _when accessed
through HTTP_ which is how the Media Server transfers the data.

Specifically, WAV and AIFF files, especially with samples wider than 16
bits are a frequent source of trouble (because they are little used and
249
little tested for streaming). Support will vary depending on the MPD
250
251
versions and exactly what input plugins are configured (among *ffmpeg*,
*libaudiofile* and *libsndfile*). Often, the same files play just fine
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
252
locally, it's the combination of HTTP access and file format which causes
253
254
255
256
257
258
259
problems.

Raw PCM streams are another special case. The reason is that these streams
do not, by definition, carry metadata to define the exact format (sample
rate, bits per sample, number of channels, byte order). *upmpdcli* has no
way to transfer these parameters to *MPD* (this is a limitation of the
client protocol). The parameters can be transferred from the Media Server
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
260
261
262
to the player along with the MIME type though. In consequence, only recent
versions of Upmpdcli and MPD (0.20 and later) do support audio/L16, but
not with any Media Server (it must output the audio formats
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
263
264
parameters with the MIME type). See this issue for more details:
https://www.lesbonscomptes.com/upmpdcli/github-issues/upmpdcli-html/issue-36.html
265
266
267
268
269
270
271
272

In general, there are few reasons to use these linear formats, when FLAC
will produce exactly the same bits, with less network load (which largely
compensates the small additional CPU load).

There are situations where the linear formats are needed though, and where
it may be necessary to use the right MPD and plugins versions.

273
274
[[radio-stations]]
=== Radio stations
275

276
277
278
Upmpdcli implements an OpenHome Radio service which allows selecting and
listening to internet radio stations when using an OpenHome-compatible
Control Point (e.g. Kazoo, Lumin, Bubble UPnP, etc.).
279

Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
280
This facility uses Python 3.x, which must be available on the system for
281
282
the radio links to work.

283
284
285
Radio channels can be accessed by using the Control Point application to
select the _Radio_ OpenHome source.

286
287
Radio stations can be defined in the configuration (at the end because of
the use of section indicators), or in in a separate file by setting the
288
<<ohproductroom,`radiolist`>> parameter in the main configuration.
289

290
An example of a simple radio station definition follows. The only mandatory
291
value is the `url` one, which should point to the actual audio stream or to
292
the station playlist link which will redirect to it (more detail in the
293
<<RADIO-SCRIPTS,radio scripts section>>. `artUrl` points to a
294
static logo image for the station.
295
296

----
297
298
299
[radio Radio Eins]
url = http://opml.radiotime.com/Tune.ashx?id=s25111
artUrl = http://cdn-radiotime-logos.tunein.com/s25111q.png
300
301
----

302
303
304
Radio definitions may also include paths to scripts to be executed for
retrieving the metadata and album art for the currently playing song. See
the <<RADIO-SCRIPTS,radio scripts section>> for more detail.
305

306
307
308
309
[[UPMPDCLI-SONGCAST]]
== Upmpdcli and Songcast

Upmpdcli implements the Receiver UPnP service, and uses an auxiliary
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
310
311
process (*sc2mpd*) for transporting the audio data. *sc2mpd* is based
on the sample program which comes with the Linn Songcast
312
313
OpenHome open source implementation

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
314
315
316
317
318
319
Upmpdcli can also manage a Sender subsystem, which is implemented by using
a separate *mpd* instance sending audio to an *mpd2sc* command (part of the
*sc2mpd* package). The latter is a modified version of the OpenHome
WavSender sample program. This allows playing the usual Upmpdcli playlist
or a a radio channel on several synchronized players, but also doing the
same thing with a captured analog source (e.g. *arecord* output).
320
321
322
323
324
325
326
327

NOTE: You should know that it is possible to control the Songcast Sender
from another local network PC to snoop on what you are listening (Radio or
Playlist). This is detectable from the Renderer state, but not obvious. In
any case, the playlist itself is public (there are no privacy provisions in
UPnP), so this is probably not a major additional issue. The system will
not capture anything besides what *mpd*, or an explicitely setup additional
source are playing (e.g. Skype phone conversations are out of reach).
328

Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
329
330
331
332
333
334
[[UPMPDCLI-SONGCAST-COMPAT]]
=== Upmpdcli Songcast Control Point compatibility

Upmpdcli Senders and Receivers can be mixed with Linn ones and controlled
from Upplay or Bubble DS (an maybe other control points).

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
335
336
Neither Linn nor upmpdcli receivers can be linked to an upmpdcli Sender using 
Linn Kazoo (tested with release 4.11.226), the reason is unknown.
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
337

338
339
Upmpdcli Receivers before release 1.2.14 are not visible in Linn
Kazoo. Later versions can be linked, and stream, from a Linn Sender.
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
340

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
341
342
343
344
Linn Kazoo can control the playlist in an upmpdcli instance which has been
put in Sender mode by another CP (i.e. currently using the PL-To-Sender
source). The Lumin IOS app will reset the Source to Playlist when
connecting, so it is unusable in this context.
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
345

346
[[UPMPDCLI-RECEIVER]]
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
347
=== Upmpdcli Songcast Receiver
348
349
350
351

*sc2mpd* can play the *Songcast* audio stream in two modes:

 - By directly using the *alsa* audio driver.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
352
353
 - By using *mpd* to play the stream offered from a local HTTP interface
   (hence the *sc2mpd* name)
354
355
356
357
358
359
360
361

.Upmpdcli Receiver in `alsa` and `mpd` modes
[options="header"]
|=============
|`alsa`|`mpd`
|image:pics/upmpdcli-receiver-alsa.png[Upmpdcli Receiver, alsa mode]|image:pics/upmpdcli-receiver-mpd.png[Upmpdcli Receiver, mpd mode]
|=============

362
What approach is used is decided by the <<sclogfilename,`scplaymethod`>>
363
configuration parameter, which can be set to _mpd_ or _alsa_. 
364

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
365
366
The _mpd_ mode is the default, because it needs no configuration, but there
are *multiple* problems with it. If you go the _alsa_ route,
367
you will need to set <<sclogfilename, `scalsadevice`>> in the
368
369
configuration, but you probably had to set it in the MPD configuration too,
so this may not be too much of an issue.
370
 
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
371
372
373
374
375
376
377
378
NOTE: when using the _alsa_ approach, *sc2mpd* will open the audio driver
directly. The *sc2mpd* process is started by *upmpdcli*, which normally
runs with user id _upmpdcli_. A frequent cause preventing the Receiver from
working is that the driver open fails because _upmpdcli_ user has no
permission to access it. One solution is to create an _audio_ group (if it
does not exist), make the devices writable by _audio_, and add _upmpdcli_
(and others) to the _audio_ group.

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
379
When using *mpd*, more bufferisation occurs and there may be a significant
380
381
382
383
384
385
386
delay (up to around 10&nbsp;S) between the time when Songcast is activated
and the time sound appears.

NOTE: When using _mpd_, from a Mac (24 bits audio) you need an
appropriately configured and recent MPD version (usually configured with
`--disable-audiofile`), else you risk producing high volume noise.  As
Debian and Ubuntu tend to lag quite bit on MPD progresses, I have set up
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
387
388
389
390
391
link:https://www.lesbonscomptes.com/upmpdcli/pages/downloads.html#mpd[backport
repositories] for appropriately configured recent mpd versions, for Ubuntu,
Debian i386/amd64 and Raspbian. Unfortunately, not only the MPD version is
significant, there are sometimes also problems in the input plugins
libraries.
392
393
394
395

Given the bufferisation and delay control issues when going through MPD,
only the _alsa_ method is usable in multi-room configurations. Even with a
single player, the _mpd_ method will experience skips from time to
396
397
time. The reasons are explained in the xref:UPMPDCLI-MULTIROOM-SYNC[multiroom
synchronization section]. 
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414

The following steps are taken for establishing a Songcast connection:

- If *upmpdcli* finds an executable *sc2mpd* command in the PATH when
  starting up, it advertises a Receiver service.

- The *Songcast* application on the desktop finds out about the
  Receiver through the normal UPnP mechanisms and can be instructed to
  use it. It then tells the Receiver in *upmpdcli* to start playing.

- *upmdpcli* starts the *sc2mpd* process, which gets ready to receive data
  through Songcast, and either play it directly or make it available
  through HTTP.

- If the _`mpd`_ method is in use, *upmpdcli* instructs *mpd* to play the
  URL for the *sc2mpd* output.

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
415
NOTE: Songcast can use IP multicast for lower load on the network when
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
416
417
418
419
playing on several hosts. Unfortunately, multicast and WIFI don't mix well
in many cases. If you have wireless Receivers experiencing sound drop
issues, try selecting unicast in the Songcast advanced configuration panel
on the desktop.
420

421
422
423
[[UPMPDCLI-RECEIVER-VOLUME]]
=== Songcast Receiver Volume control

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
This section used to claim that the *upmpdcli* Songcast Receivers
implemented no software volume control and that you needed to use either a
local mixer or the little round things on the pre-amps.

Actually, as of *sc2mpd* version 1.1.6, there are two possible ways to
control the volume on an upmpdcli Songcast receiver, one of which has
existed for a long time. Both approaches are based on the fact that a
control point connected to the upmpdcli instance can set the volume level
using the normal UPnP/OpenHome interfaces.

The first method, which has been available for a long time is to use the
<<onstart,`externalvolumecontrol`>> feature, and set up the corresponding
scripts to set and retrieve the volume from the audio mixer (e.g. using
amixer or such). This will adjust the volume without any change to the
Songcast stream.

The second method, available for *sc2mpd* versions 1.1.6 and later can
scale the audio stream according to the local *mpd* volume setting.  The
volume control goes from the control point to *upmpdcli*, which sets it in
*mpd*, from which *sc2mpd* retrieves it to set the scale factor. This is
not active by default, you can enable it by setting the <<sclogfilename,
`scusempdvolume`>> variable to 1 in the local `upmpdcli.conf`. This only
works if if `scplaymethod` is _alsa_.
447

448
[[UPMPDCLI-SENDER]]
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
449
=== Upmpdcli Songcast Sender
450
451

Upmpdcli Sender mode allows you to broadcast the Playlist or Radio source
452
453
454
455
(or the output of any process which can write to a Fifo, e.g. *arecord*) to
other Songcast Receivers. The local *upmpdcli* plays through its Receiver
too, in order to achieve good synchronisation. Unlike the Songcast
applications on Windows or Mac, the audio is not captured from the driver,
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
456
457
so that you won't be able to cast other applications transparently (but
there are specific workarounds).
458
459
460
461
462
463
464
465

You can set *umpdcli* in Sender mode from an OpenHome Control Point, by
selecting the Source of type `Playlist`, name `PL-to-Songcast` or type
`Radio`, name `RD-to-Songcast` (and others if using the extension
mechanism).  With
link:http://www.lesbonscomptes.com/upplay/index.html[upplay], for example,
you can select the source from the `File`->`Select Source` menu entry.

466
The *sc2mpd* configuration *must* be set with `scplaymethod = alsa` for the
467
`XX-to-Songcast` sources to appear. See the
468
469
xref:sclogfilename[configuration section], and the
xref:UPMPDCLI-MULTIROOM-SYNC[section about synchronisation].
470

471
When entering Sender mode, *upmpdcli* will start an auxiliary MPD process
472
473
(after stopping the main one), configured to send audio to the *mpd2sc*
OpenHome Sender process. It will then also start its own Songcast
474
Receiver mode, transfer the playlist, stop the main MPD and start the
475
476
477
478
auxiliary one...

The resulting state is that the *upmpdcli* instance can be managed in
Playlist mode from the Control Point. The audio is played locally through
479
480
the Songcast Receiver. Other Receivers can be connected and will play in
good synchronization.
481

482
image::pics/upmpdcli-sender-receiver.png["Sender/Receiver mode"]
483
484

This looks complicated, but in practise, starting the mode and connecting
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
485
other Receivers from the *upplay* control panel is quite straightforward.
486
487
488
489

[[UPMPDCLI-SENDER-EXTSOURCES]]
==== Managing external sources

490
In the Sender modes described above, *upmpdcli* (or rather its slave *mpd*
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
491
492
493
494
495
496
497
process) is the source of the audio stream. The *mpd2sc* program (which is
just a slight modification of a Linn sample) reads the *mpd* output from 
a FIFO and sends it to Songcast Receivers (including the local one).

There is nothing special with the *mpd* output (it is just PCM audio), and
it is also possible to set things up for *mpd2sc* to read from another
source.
498

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
499
500
501
502
503
504
This is made reasonably easy because the pipe is actually built by
a script (the default one is named 'scmakempdsender'), and *upmpdcli* has
built-in functionality for choosing different ones (creating OpenHome
sources for each script it finds in a specific directory). There is a
sample script in the distribution, which itself is flexible enough to allow
connecting several inputs without programming (anything *arecord* can read).
505

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
506
507
Still the details are a bit too much involved for the main body of the
manual, so I have moved them to an xref:SENDER-EXTSOURCES[annex].
508

509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
[[UPMPDCLI-MULTIROOM]]
=== Songcast multiroom configurations and synchronization issues

Multiple Songcast Receivers can connect to the same Sender, for
synchronized playing of a the same audio stream.

The Mac and Windows Songcast applications only let you activate one Receiver.

The easiest way to manage multiple connections is to use an appropriate
control point, such as Upplay on Linux and Windows, BubbleDS on Android, or
Linn Kazoo (multiple platforms).

For the record, the *upmpdcli* package also includes the *scctl* command
line utility, which can list the state of the local Songcast Receivers,
make a Receiver play from the same URI as another one (for building
multi-room groups), or return a Media Renderer from Receiver to normal
operation. There is also a xref:SCWEB[small Web application] which can be
accessed from a desktop web browser to control the groups. This has only
be tested with *upmpdcli* as Receiver implementation, but I'd guess that
there is a good chance it would work with others. Quite frankly, I think
that you'd better use the Control Point approaches if at all possible.

[[UPMPDCLI-MULTIROOM-SYNC]]
==== Synchronisation issues

The short version is: for good syncrhronization, all *sc2mpd* instances
535
536
must be configured to play directly to the audio driver with `scplaymethod
= alsa`. See the xref:sclogfilename[configuration section].
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563

Longer version: *Songcast* is a real-time audio stream. As the Sender and
Receiver sample clocks (the 44.1 or 48 KHz clocks) are independant, audio
reproduction on the two systems will slowly drift. If nothing is done,
after a time, the Receiver will have to skip samples or add a period of
silence (depending if its clock is slower or faster), which is quite
audible and ennoying, and will happen "from time to time", depending of how
much the clocks differ.

The only way to control this is to adjust the rate of reproduction on the
Receiver, which can be done in two ways:

 - *Linn* hardware uses timestamps embedded in the audio stream to adjust
   their hardware sample clock.
 - *sc2mpd* in _alsa_ mode uses sample rate conversion to adjust the stream.
 - *sc2mpd* in _mpd_ mode can't do a thing about it.
 
This is not specific to *Songcast* of course, all real time audio network
transports have to do something similar (e.g. Roon does individual stream
adjustments on the server).

Independantly of the clock issue, all Receivers should use approximately
the same amount of buffering for the audio to be reasonably synchronous
(with no more shifts than moving around would produce anyway). This is
impossible to achieve when going through *mpd*, and the second reason why
*sc2mpd* must be set in _alsa_ mode for multiroom setups. In _mpd_ mode,
the Receivers can be out of sync by several seconds.
564
565


Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
566
[[UPMPDCLI-MS-STR]]
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
567
568
569
570
== Support for Streaming Services

=== Streaming Services and UPnP

Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
571
Streaming services like Highresaudio or Spotify give access to a huge
572
573
catalog of music through a WEB programming interface which is also usable
by programs other than their own applications.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
574

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
575
576
The only thing that they have in common with UPnP is that most of them use
HTTP to retrieve the audio stream (as a short-lived URL). Spotify is an
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
577
exception, and uses a specific protocol for streaming.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
578
579
580
581

Given the importance of these services for music consumers, many UPnP
Control Points and Renderers have been extended with specific interfaces to
the different services.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600

There are three main ways to integrate the streaming services in an UPnP
framework, and knowing which way you are using will avoid confusion:

- The first approach is to have a UPnP Media Server act as a proxy for the
  service: the catalog is browsed through a standard UPnP interface (the
  Media Server translates this to the service API behind the scenes), and
  the audio URIs are also accessed in an almost standard way (after a bit
  of magic inside the Media Server). The one inconvenient of this approach
  is that the special functions of the service (like managing the user
  favourites lists) are mostly inaccessible. The advantage is that any
  naive UPnP Control Point can access the streaming service. The Media
  Server inside upmpdcli xref:UPMPDCLI-MS-STR-MS[implements this method].

- The second approach is to do everything inside the Control Point. The CP
  uses the service API for browsing (and possibly do things like managing
  favourites). The CP also mediates the HTTP access to the audio streams
  (the URIs the CP sends to the Renderer point to itself, and it arranges
  to forward the data from the service). This is implemented, for example,
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
601
602
603
  by Bubble UPnP. The drawback of this approach is that the Control Point
  device must not go to sleep or out of reach, else the music will stop
  (maybe at the next track).
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
604
605
606
607
608
609

- The third approach is to distribute the function between CP and
  Renderer. The Control Point performs the browsing and access to special
  functions, and the Renderer knows how to access the service streams. This
  is the OpenHome approach and can be considered the best of both worlds,
  at the price of complexity and compatibility issues. This method is
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
610
611
  implemented by the Linn Kazoo Control Point, and a number of Renderers,
  the Linn and Lumin ones of course, but also,
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
612
613
614
615
  xref:UPMPDCLI-MS-STR-CRED[lately by upmpdcli]. +
  * At the moment, the upmpdcli implementation is not useful any more, as
    changes in services access methods have made it such that none of them
    is currently usable with upmpdcli through this method.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
616
617
618
619

[[UPMPDCLI-MS-STR-MS]]
=== Accessing Streaming Services through the upmpdcli Media Server
  
620
The Media Server function in Upmpdcli gives access to external streaming
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
621
622
623
624
services: Spotify, Highresaudio and Qobuz currently work unconditionally
(1.5.5). I am not sure about Tidal support: in any case it will only work
if you can find a working application token (Tidal), and even then, maybe
not as their access control API is evolving.
625

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
626
627
628
A plugin for Deezer has been added recently (2021-02-23 git or future
1.5.9), and currently only provide access to 128 kb/s mp3 streams.

629
630
You will need a valid subscription for any service that you want to use
(for Spotify, this means a premium account, the free ones will not work).
631
632
633
634
635

When the function is activated, *upmpdcli* creates a separate auxiliary Media
Server, with the sole purpose of presenting the streaming server
catalog. You will see it appear on the network if streaming service
parameters are present in the configuration file. The Media Server name is
636
the `friendlyname` for the Upmpdcli instance, with _-mediaserver_ appended.
637
638

Streaming is not limited to the local Upmpdcli Renderer, and the Media
639
640
Server will happily send music to other Renderers (within the limitations
set by the service).
641
642
643
644
645

Two conditions must be true for the Media Server to appear with an entry
for a streaming service:

 - The code for the service plugin must be installed. This comes generally
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
646
   in a separate package (e.g _upmpdcli-qobuz_).
647
 - The user variable for the service must be present in the configuration
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
648
   file (e.g `qobuzuser`).
649
650

Some other parameters (e.g. a password) may be needed for the access to
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
651
work, depending on the specific service. See the service-specific notes below.
652
653

NOTE: The streaming services passwords are stored in the upmpdcli
654
655
configuration file ('/etc/upmpdcli.conf'). The installer does not make this
file r/w by owner only. You should probably change the mode after setting
656
the password: `chmod&#160;600&#160;/etc/upmpdcli.conf`.
657
658
659
660
661

NOTE: I have no reason to believe that upmpdcli is technically mis-using
the streaming services in any way, but it is definitely not approved by any
of them, and you are using it under your own responsibility.

Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
662
////
663
664
665
[[UPMPDCLI-MS-STR-CRED]]
=== Accessing the streaming services with OpenHome from Kazoo

666
667
668
669
670
This implements the `OpenHome Credentials` service only works for Tidal and
Qobuz, if you have found an API token or appid/secret pair and only with
upmpdcli versions 1.3.0 and later. The corresponding media server module
must be installed (upmpdcli-tidal), but no other configuration should be
necessary on the renderer.
671
672
673
674

This should also work with Lumin, but it does not currently, the reason is
unknown. When feature is active, it actually prevents Lumin from
discovering upmpdcli at all, so there is a configuration variable to
675
disable it: '`lumincompat`'. Set to 1 to use upmpdcli v1.3.0 with Lumin.
676
677

Upmpdcli uses the *openssl* command to perform the cryptography work. This
678
679
680
681
682
683
684
685
686
was not made a hard dependancy, so you should check that it is
installed. Unfortunately, I was only able to make things work with a fairly
recent version of OpenSSL (1.1). This is available in Debian Stretch (9.x),
but not Jessie (8.x) (on which Volumio, for example is based at this
moment (12-2018)). If you are running Jessie, there is a fairly easy
workaround available by building a static version of openssl and telling
upmpdcli what version to use. See <<OHCREDS-OPENSSL, some instructions in
this annex>>.

687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
The media service icons will appear in the Control Point interface, and the
service will be accessible after entering the login and password.

NOTE: the user name and password will be stored on the renderer in an
insecure way, meaning that if someone steals the machine or obtains root
access, there is nothing to prevent them from getting the credentials.

Of course Kazoo or Lumin can also access the services through the media
server interface (after configuring upmpdcli, see the
xref:UPMPDCLI-MS-STR-MS[previous section]).

For reference, this method is *not* usable with *Upplay*

The notes which follow relate to accessing the services through the
Upmpdcli Media Server.

=== Using Tidal through the Upmpdcli Media Server
704
705

[NOTE]
706
====
707
708
709
710
711
712
There seems to sometimes be problems when streaming Tidal lossless/FLAC
streams, with the default MPD configuration. A preliminary and rather
superficial enquiry seems to indicate that this is caused by too much
buffering by MPD. Adding the following parameters to the MPD configuration
file (/etc/mpd.conf) reduces the pre-fetch period and seems to fix the
issues for me (YMMV...):
713
714
715

    audio_buffer_size "2048"
    buffer_before_play "20%"
716
717

====
718

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
719
720
You will need to install the upmpdcli-tidal module.

721
722
723
724
725
726
727
728
729
The Tidal module code is is based on the
link:https://github.com/tamland/kodi-tidal[Kodi Tidal add-on] and the
link:https://github.com/tamland/python-tidal[Tidal API], by Thomas Amland
(also using other useful modules by Thomas). I was able to reuse most of
the Kodi code. The Tidal api module was recently updated and the login code
comes from link:https://github.com/arnesongit/kodi-tidal[this Git
repository]. The software is not officially supported by Tidal, and may
just stop to work one day...

730
731
It only works with a valid Tidal subscription and valid Tidal API token,
which you must set in the `tidalapitoken` configuration variable.
732
733
734
735

The configuration parameters are described in the
<<tidaluser,configuration section>>

Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
736
737
738
739

////


740
741
[[upmpdcli.qobuznotes]]
=== Using Qobuz through the Upmpdcli Media Server
742
743
744
745
746

This is based on the service API from the
link:https://github.com/tidalf/plugin.audio.qobuz[Kodi add-on], by Joachim
Basmaison and Cyril Leclerc, with the upper-level code adapted from the
Tidal add-on. The WEB API is not officially supported by Qobuz, and may
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
747
just stop to work one day.
748

749
750
751
752
753
NOTE: the Qobuz search does not allow searching a specific field (like the
artist name or song title). All objects matching a query in any field are
returned. This means that, e.g., the field choice of upplay search is
ignored.

754
755
756
757
758
You need a valid Qobuz subscription.

The configuration parameters are described in the
<<qobuzuser,configuration section>>

759

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
[[upmpdcli.deezernotes]]
=== Using Deezer through the Upmpdcli Media Server

You will need a premium (paid) account.

The plugin is based on code from the
link:https://github.com/Valentin271/DeezerKodi.git[Kodi add-on], by 
Jakub Gawron (kubatek94) and ? (Valentin271).

It uses the Deezer "television" API and only provides access to 128 kb/s
MP3 streams.

The configuration parameters are described in the
<<deezeruser,configuration section>>. Only `deezeruser` and `deezerpass`
actually. 


777
778
[[upmpdcli.spotifynotes]]
=== Using Spotify through the Upmpdcli Media Server
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
779

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
780
781
You will need to install the upmpdcli-spotify module.

782
You will need a premium account, the free ones do not work for this.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
783

784
785
786
787
Spotify is the only service which does not use regular (short-lived) HTTP
URLs for accessing the streams, but rather a non standard transfer
protocol, implemented in a specific library.

788
789
790
791
792
793
794
795
796
797
798
799
800
801
The upmpdcli interface is based on a slightly modified version of the
link:https://spotipy.readthedocs.io/en/latest/[Spotipy Python package] and
the old `libspotify` library.

The `libspotify` library is not distributed or installed with upmpdcli, you
need to install it separately. Currently, the easiest way to obtain it is
from the link:https://github.com/mopidy/libspotify-deb[Mopidy
repository]. You can use the 'deb' packages on a Debian-derived system,
else copy the dynamic object for your architecture to /usr/lib.

NOTE: Using this module is contrary to the current Spotify terms of
service, and you use the (supposedly deprecated) library under your
own responsability.

802
The authentication method is also more complicated than for the others, and
803
will have you jump through a few hoops in addition to setting the password
804
in the configuration file.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
805

806
You will need to set some configuration parameters, which are described in the
807
808
809
<<spotifyuser,configuration section>> and then obtain an oauth2
authorization token: follow the instructions in the <<SPOTIFY-AUTH,Spotify
authorization annex>>.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
810

811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
[[UPRADIOS]]
== Upmpdcli radio list plugin

This is a minuscule plugin which just exports the Upmpdcli radio list as a
playlist, so that other renderer on the network can use it.

Of course, the functionality is reduced when compared to using the list
through the upmpdcli's own OpenHome Radio service: there will be no dynamic
art or special metadata features: `artScript` and `metaScript` entries are
just ignore.

Still the server will convert .pls and other playlist entries into actual
stream URLs, and it may be convenient for maintaining the radio list in one
place.

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
826

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
827
828
829
[[UPRCL]]
== Upmpdcli local Media Server: uprcl

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
830
831
You will need to install the upmpdcli-uprcl module.

Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
832
The current (2020-12) upmpdcli code base includes a Media Server function
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
833
for local music files, analog to MinimServer or ReadyMedia/MiniDLNA. The
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
plugin module is named *uprcl*.

Why yet another Media Server ? Mostly because my favorite, MinimServer is
great, and free, but not open-source, so I find it prudent to have an
alternative. Also, fun :)

*uprcl* only implements a small fraction of MinimServer vast list of
capabilities at this point, but it's slowly making progress, and I find it
works well enough, at least with the upmpdcli renderer, to now be my main
Media Server.

Some *uprcl* features:

- Mostly written in Python, except for the part shared with the streaming
  media server plugins, which is in C++.
- Tries to mimick the MinimServer tree view and functionality. We're
  not quite there yet, many functions and niceties are still missing.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
851
- Uses Recoll and python-recoll (hence the uprcl name) for harvesting the
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
852
  metadata and searching.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
853
- Uses Python Sqlite3 (on a memory DB) for the tags tree. 
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
854
855
856
857
858
859
860
- Can retrieve some parameters from the MinimServer configuration
  file. Will support more in the future.

The list of MinimServer functions which are _not_ supported would be too
long. Here follows what *uprcl* does support, at least partially, at this
point (1.4.3pre):

861
- `contentDir` will be used if `uprclmediadirs` is not set in
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
862
  '/etc/upmpdcli.conf' 
863
864
865
866
- `excludePattern`
- `aliasTags`
- `indexTags`
- `showExtras`
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
867
868
869
870
871
- Multidisc albums (partial).

All in all, not a lot of the customization options are supported for
now. I'd love feedback about what is missing most.

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
872
873
874
875

Installation and configuration: have a look at the
xref:uprcluser[configuration variables]

Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
876
877
NOTE: uprcl needs Python 3.5 at least. This means that it does not work on
Debian Jessie (8.x)
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
878

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
879
880
881
882
NOTE: 'python-mutagen' which is optional for default Recoll installations is
required for uprcl (this is for the case where you install by hand, the
package takes care of it).

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
[[UPRCL-SEARCH]]
=== Upmpdcli/Uprcl searches

The UPnP Media Server search function is based on a specific query
language. This language is quite verbose, and most control points will not
let you access it directly. Instead, they will usually provide a generic
entry field in which you enter search terms.  Behind the scenes, they
generate an UPnP search language string. This could be for example
something like: `upnp:class = "object.item.audioItem" and dc:title
contains "heaven"`

If it supports search at all, the Media Server will then interpret the
query string and return the results.

If the Media Server is Upmpdcli/Uprcl, there is another step: the UPnP
query string is translated into a Recoll one and Recoll is called to
perform the actual search. There is no way to directly enter a Recoll
search through the control point. However, two important Recoll
capabilities should still be visible through the layers:

.Stemming

Stemming is the capability to expand a search to the common derivatives of
a word. For example, a search for `floor` would be expanded to also look
for `floors`, `flooring`, `floored`, etc. By default, stemming is enabled
for Uprcl search. It can be turned off for any term by capitalizing the
term (Entering `Stones` will only search for `stones`, not `stone` or
`stoned`). Uprcl/Recoll searches are case-insensitive apart from this usage
of capitalization.

.Phrase searches

By default, Uprcl/Recoll searches do not observe the order
of terms: `red house` will be matched by a search for `house red` (or
`houses red`). You can change this behaviour by quoting a sequence of
words. A search for `"red house"` will only look for a text containing the
words in order. This supposes that the Control Point does not change the
user entry, but this is the case for at least some of them. Stemming
expansion does not occur within phrase searches.

Other Recoll capabilities, such as proximity searches should also be
accessible, but probably less useful when searching music titles or artist
names.




930
[[UPMPDCLI-CONFIGURATION]]
931
== Upmpdcli configuration file reference
932

933
934
935
include::upmpdcli-config.txt[]


936
[[UPMPDCLI-PACKAGES]]
937
938
== Installation from packages

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
939
The link:https://www.lesbonscomptes.com/upmpdcli/pages/downloads.html[upmpdcli
940
941
942
943
downloads page] has a number of pointers to binary packages for a number of
common distributions (Debian, Raspbian, Ubuntu, Fedora) and architectures
(ARM and x86).

944

945
946

[[UPMPDCLI-BUILDING]]
947
948
== Building from source

949
=== Building upmpdcli on Linux
950
951

For building from source, you will need a C\++ compiler with full
952
953
C++11 support, and the development packages for the supporting libraries:
*libcurl*, *libmicrohttpd*, *libmpdclient*, and *libexpat*.
954
955
956

Also the Python modules for streaming service support use the
*python-requests* package, so you may need to install it (it is only needed
957
at run time). 
958

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
959
If you are using the source from the git repository, you will also need the
960
*autoconf*, *automake*, *libtool* trio. Use the `autogen.sh` script to set
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
961
things up.
962

963
964
So you need to either clone 3 git repositories:

Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
965
966
967
- https://framagit.org/medoc92/npupnp
- https://framagit.org/medoc92/libupnpp
- https://framagit.org/medoc92/upmpdcli
968
969

or download the release tar files from the the
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
970
link:https://www.lesbonscomptes.com/upmpdcli/pages/downloads.html[upmpdcli
971
972
download page]

973
974
For upmpdcli, there are two specific configure options. Each needs the
installation of additional dependancies:
975
976
977

- --enable-confgui: build the configuration editor GUI. This will need
the Qt development packages
978
979
980
981
982
983
984
985
- -disable-spotify: do not include build the Spotify access module. This
  used to be disabled by default, but is now enabled because it does not
  create a build dependancy, as the interface include file is bundled,
  and the library itself is dynamically opened at run time, not linked. Of
  course, the library will need to be installed on the target machine for
  the Spotify access to work. Currently, the easiest way to obtain it is
  from the link:https://github.com/mopidy/libspotify-deb[Mopidy
  repository].
986
  
987
988
Once the source is extracted, the procedure is standard for each of the
three packages:
989
990
991
992

    # Only for git source
    sh autogen.sh 

993
    ./configure --prefix=/usr --sysconfdir=/etc [other options]
994
995
996
    make
    sudo make install

997
998
Which you should apply first to the *libnpupnp* source, then to *libupnpp*,
then to *upmpdcli*.
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019

If you omit the `--sysconfdir=/etc` part, `upmpdcli.conf` will end up in
`/usr/etc/`, which is ok, but confusing, as package installers put it in
`/etc/`

==== Boot time startup

*upmpdcli* will try to change its `uid` to user `upmpdcli` if it is
started by root. It will refuse to run if the user does not exist.

If started by `root`, *upmpdcli* will also write its process id to
`/var/run/upmpdcli.pid`.

There are boot-time startup scripts in the `debian/` directory inside the
source tree (for Debian/Ubuntu/Mint/Raspbian etc.). There is also a systemd
service file under `systemd/` (for Fedora et al.).

The boot scripts are installed by the pre-built packages, so will just have
to edit the configuration file after installing them, all the rest should
just work.

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
=== Building libupnpp and upmpdcli on Mac OS X

I don't run Mac OS X and I can't support this directly. However a kind user
has provided a
link:https://opensourceprojects.eu/p/upmpdcli/tickets/3/[build recipe]
based on homebrew.

You will first need to apply the patches from
link:https://www.lesbonscomptes.com/upmpdcli/files/2017-12-upmpdcli-macos-build-patches.tgz[this
file].

Then:

----
brew install mpd
brew install autoconf
brew install automake
brew install libtool
brew install libupnp libmpdclient expat jsoncpp libmicrohttpd expat curl
brew install pkg-config
brew install expat
export PKG_CONFIG_PATH=/usr/local/opt/expat/lib/pkgconfig
configure --prefix=/usr
make
----

1046
1047
1048
1049
1050
1051
1052
1053
1054

=== Building OpenHome and sc2mpd

There are two parts in building *sc2mpd*:

- Building the Openhome libraries
- Building *sc2mpd* proper

First download a
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1055
link:http://www.lesbonscomptes.com/upmpdcli/pages/downloads.html[*sc2mpd*
1056
release] or clone the *sc2mpd*
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
1057
https://framagit.org/medoc92/sc2mpd[Git repository].
1058
1059


Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1060
==== Creating the the OpenHome source tree
1061
1062

Building the Openhome libraries is a bit of a black art for a number of
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1063
reasons:
1064
1065
1066
1067
1068
1069
1070
1071

- There are no released distributions for the OpenHome libraries, but
  only a number of git repositories for the different components. The state
  of the repositories is not completely consistent at all times (there will
  be moments when a component will not build with another).
- The OpenHome build system is very complicated because it works on
  multiple platforms and multiple language bindings.

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1072
1073
1074
1075
1076
1077
The first step is to create the openhome source tree. There are two
possible ways, described just below.

In both cases, after creating the tree, you need to compile the openhome
software. See the sc2mpd build section below.

1078
===== OpenHome source tree, the easy way
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1079
1080

Download the tar file of the appropriately patched openhome code from the
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1081
1082
upmpdcli downloads page (use the current one, the date on the one below is
just an example), create an empty directory, untar it in it
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1083
1084
1085
1086

    cd /home/me
    mkdir openhome
    cd openhome
1087
    tar xf /path/to/openhome-sc2-20210305.tar.gz
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1088
    
1089
===== OpenHome source tree, the complicated way
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1090

1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
The *sc2mpd* source comes with a shell script named _ohbuild.sh_ to help
with this. It has several functions:

 - Cloning the OpenHome and checking out verified revisions
 - Applying a few minor patches to ensure that the build will work in a
   simplified environment (e.g. without a c# compiler).
 - Creating a tar file of a compact trimmed tree.
 - Running the build either from the cloned tree or the tar file.

The tar functions are mostly useful to help with building packages. For a
normal build, the procedure would be as follows:
1102

1103
1104
1105
    cd sc2mpd
    mkdir /my/place/for/openhome
    sh ohbuild.sh -b /my/place/for/openhome
1106

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1107
1108
1109
1110
NOTE: for sc2mpd 1.1.7 you will need to copy the ohpatches directory from
the git code directory to the extracted tar file directory because I forgot
to include it in the distribution.

1111

1112
1113
==== Building sc2mpd

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1114
1115
*sc2mpd* depends on a number of libraries, which are usually packaged on
Linux, and which you need to install first:
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125

- The link:http://www.gnu.org/software/libmicrohttpd/[microhttpd]
  library. Install the development and runtime packages which are currently
  named _libmicrohttpd-dev_ and _libmicrohttpd10_ on Debian-derived systems
  (use _libmicrohttpd_ and _libmicrohttpd-devel_ for Fedora).
- The link:http://www.mega-nerd.com/SRC/[libsamplerate]
  library (_libsamplerate0_ on Debian, _libsamplerate-devel_ for Fedora).
- The *libasound* Alsa interface library (_libasound2-dev_ on Debian,
  _alsa-lib-devel_ for Fedora).

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1126
1127
1128
1129
1130
First build openhome. Change your current directory to the top of the
sc2mpd source tree, then run:

    sh ohbuild.sh /my/place/for/openhome

1131
1132
Once OpenHome is built and the auxiliary library development packages are
installed, build *sc2mpd*, using the following commands inside the
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1133
1134
_sc2mpd_ directory (you only need the autogen part for a cloned git tree,
not for a tar extraction):
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161

    sh autogen.sh
    ./configure --prefix=/usr --with-openhome=/my/place/for/openhome
    make
    sudo make install

The build uses static Openhome libraries, so you can move the executable to
another machine without needing the Openhome directory (don't forget to
install the _libmicrohttpd_, _libsamplerate_ and _libasound_ runtimes
though).

After restarting *upmpdcli*, it should advertise the _Receiver_ service and
appear in the Songcast Sender menus.

==== Building a Debian package from an sc2mpd tar distribution

Here follows a synopsis of building a debian package for an sc2mpd tar
distribution. You'll need to replace the 1.1.1 and 20151223 versions with
whatever you are building. Note that the 1.1.1 value must match what you
have in the Debian changelog (or update the changelog).

The $distdir and $sc2mpd_src values stand for places where you store the tar
files and the sc2mpd (git) source tree.

    mkdir sc2mpd_build
    cd sc2mpd_build
    cp $distdir/sc2mpd-1.1.1.tar.gz sc2mpd_1.1.1.orig.tar.gz
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1162
    cp $distdir/openhome-sc2-20180615.tar.gz sc2mpd_1.1.1.orig-openhome.tar.gz
1163
1164
1165
1166
1167
1168
1169
1170
1171
    tar xzf sc2mpd_1.1.1.orig.tar.gz
    cp -rp $sc2mpd_src/debian sc2mpd-1.1.1/
    cd sc2mpd-1.1.1
    mkdir openhome
    cd openhome
    tar xzf ../../sc2mpd_1.1.1.orig-openhome.tar.gz
    cd ..
    debuild

1172
1173
1174
1175
1176
1177
1178
1179
1180

[[SPOTIFY-AUTH]]
== Annex: setting up Spotify access authorization

Upmpdcli uses a hybrid approach for accessing Spotify: it uses the newer
WEB API for browsing the catalog, and the old libspotify library for
streaming.

As a consequence, two sets of authorization parameters must be specified:
1181
the library uses a classical user name ` password pair, to be set in the
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
<<spotifyuser,configuration file>>.

The WEB API uses a more modern (and more ennoying) oauth2
authentification/authorization method. This needs to go through a WEB
browser. You will need to execute the following steps to set things up:

- Download the
  link:http://www.lesbonscomptes.com/upmpdcli/files/upmpdcli-spotify-authinit.zip[zip
  file for the helper script]. Right-click the link and use `Save link as`.
- Unzip the file on any Linux machine with a web browser. This will create
  a 'upmpdcli-spotify-authinit' directory. The chosen machine can be the
  host where upmpdcli runs, or not: any Linux machine with a browser will do.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1194
1195
- Check that the python3-requests package is available on the chosen host, or
  install it.
1196
1197
1198
1199
1200
1201
1202
1203
- Run the helper script inside the unzipped directory. Replace 'username'
  with your Spotify user id.
  
    ./spotiauthinit.py username

- The script will start a Web browser, and you will be asked to log in to
  Spotify and authorize upmpdcli to access your data.
- At the end of the web interaction, you will be redirected to a
1204
  non-existing page (an error will be displayed in the browser). Copy the
1205
1206
1207
1208
1209
  link address from the address bar, and paste it to the spotiauthinit.py
  input line (you will have been prompted to do this by the script).
- The script will then store the authorization token in a file named
  '/tmp/spotipy-<username>-token', which you will need to copy to the host
  where upmpdcli run, and move it to a file named
1210
  '/var/cache/upmpdcli/spotify/token', or, if you changed the value of the
1211
  `cachedir` parameter, to '[cachedir]/spotify/token'.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1212
- Make sure that /var/cache/upmpdcli and its contents belong to upmpdcli:
1213

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1214
    sudo chown -R upmpdcli /var/cache/upmpdcli/spotify
1215

1216
1217
1218
1219
1220
1221
[[SC2MPD-INSTALL]]
== Annex: Songcast installation walkthrough

If you want to play from a Mac or Windows machine, install the 
link:http://www.linn.co.uk/software#songcast[Songcast application]

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1222
1223
1224
1225
1226
1227
NOTE: Not all http://oss.linn.co.uk/Releases/Songcast/Davaar/[Songcast
capture application versions] work well with upmpdcli. Lately (03-2017),
the latest version (4.8.535) seems to work fine. In the past, I've had good
luck with 4.4.190 but not with the 4.5 ones (it is possible to get them to
work with *upmpdcli* from the *upplay* control panel, but the Windows app
claims that the *upmpdcli* receiver is unavailable.).
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258

I could not get IP multicast to work with WIFI Receivers (the sound drops
constantly).

There are well-known problems with multicast and WIFI (see for example
http://superuser.com/questions/730288/why-do-some-wifi-routers-block-multicast-packets-going-from-wired-to-wireless[this
superuser.com question] 
for detailed explanations). This seems to be dependant on the WIFI hardware
(router/access points) used, so maybe you will have more luck than me.

If some of your Receivers use WIFI, and you experience sound issues, check
that "Unicast" is selected in the Songcast configuration "advanced" panel
on the desktop.

Under most conditions, WIFI data rates should be more than sufficient to
transport Songcast streams (a bit over 1 Mbit/S for 48k/24bits, 700 Kbits/S
for 44.1k/16 bits).

However, Songcast is probably best transported over a wired connection. If
you are doing this over WIFI and experiencing glitches, the wireless is the
first suspect.

If the Sender is a *upmpdcli* host, you should probably also install the
link:http://www.lesbonscomptes.com/upplay/[upplay] Control Point
somewhere. Recent upplay versions include a tool to control Sender and
Receiver instances. This is less necessary if the Sender is on Windows or
Mac, as the Songcast application on these platforms includes a limited
connection tool (no multiroom).

Download and install the *upmpdcli* and *sc2mpd* packages for your Linux
system. See
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1259
link:http://www.lesbonscomptes.com/upmpdcli/pages/downloads.html#packages[the
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
download page here].

When using a single Receiver, things should just work, the _UpMpd_
Receiver should appear in the Songcast app on the host (or in the *upplay*
control panel).

WARNING: There is *no software volume control* for the *upmpdcli* Songcast
Receivers for now: use either a local mixer or the little round things on
the pre-amps. Set the volume low when experimenting !

NOTE: The receiver side does not work too well on Raspberry Pis using an
USB DAC (as far as I could see). The reason may be that the data rate of
the uncompressed stream is just too much for the poor Pi Ethernet/USB
chip. Things work just fine with an I2S DAC (or on HDMI probably). When on
WIFI, the results are sometimes irregular too, depending on the quality of
the connection. If you have no Ethernet cabling, Ethernet over power lines
may work better than WIFI. The best combination of network and DAC link is
definitely Wired and I2S (or HDMI).

When using multiple Receiver instances, you need to at least customize
their names, and you want to take care of synchronization issues. You will
need to take a look at a bit more documentation:

1283
 - xref:friendlyname[`friendlyname`]
1284
1285
 - xref:UPMPDCLI-MULTIROOM-SYNC[audio synchronization issues and *sc2mpd*
   configuration].
1286
1287


Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
[[SENDER-EXTSOURCES]]
== Annex: Setting up external audio sources for the Songcast Sender

The *upmpdcli* Sender modes are controlled by switching OpenHome
Sources. By default, and if the *sc2mpd* package is installed, *upmpdcli*
will create 'PL-to-Songcast' and 'RD-to-Songcast' sources for broadcasting
its playlist or radio streams to Songcast.

As explained in the main body, there is nothing magical with this: *mpd*
just streams to a FIFO which is read by the *mpd2sc* command, which then
broadcasts it. This pipe is set up by a script (_scmakempdsender_).

Under certain conditions, if *upmpdcli* finds other scripts in a designated
directory, it will create more sources, and start them when the
corresponding source is selected (of course, it expects the script to
create a Songcast Sender pipe).

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1305
1306
1307
1308
1309
1310
1311
1312
The *upmpdcli* source comes with a sample script which sets things up for
*mpd2sc* to read *arecord* output, allowing multiroom playing of an
external analog source (line-in). The sample script is flexible enough to
manage different inputs without code changes, and there are comments at the
top which give detailed explanations. The parts of more general interest
will be a bit expanded here (see below). If you want to use the script
itself, you need to look at the comments. You will find the script under
'samplescripts/Analog-Input' in the source tree.
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1313
1314
1315

Based on the same mechanism (but quite different code inside the script)
there is also a nice
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1316
link:https://www.lesbonscomptes.com/upmpdcli/github-issues/upmpdcli-html/issue-71.html[HOWTO]
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1317
1318
1319
1320
explaining how to link a Bluetooth device to Songcast.

The general idea is that upmpdcli will create an Openhome Source for each
script it finds inside a designated directory. By default, the directory is
1321
1322
`/usr/share/upmpdcli/src_scripts`, but it can be changed by setting the
`ohsrc_scripts_dir` configuration variable inside `/etc/upmpdcli.conf`
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1323
1324
1325

For managing analog sources, entries inside the directory will typically
be created as symbolic links to the sample script, which is installed as
1326
`/usr/share/upmpdcli/Analog-Input`. For doing other things, the scripts
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1327
1328
1329
will not be links, but they must still be named a bit specially.

The scripts (or links) must be named like _SourceType_-_SourceName_, where
1330
_SourceType_ MUST BE one of `Analog`, `Digital`, or `Hdmi`, (which are all
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1331
1332
1333
the same, and for display purpose only), and you can choose _SourceName_ as
you wish, but it should contain no space characters.

1334
The Source will appear with type `Analog`, `Digital` or `Hdmi` and name
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1335
1336
_SourceName_ in an OpenHome Source select dialog (e.g from *upplay*).

1337
The `Analog-Input` sample script has provisions for reading the device name
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1338
1339
1340
1341
and setup/teardown instructions from external files, so that it does not
need to be modified. This is only relevant for the sample, please have a
look at the comments for details.

1342
1343
1344
1345
1346
[[RADIO-SCRIPTS]]
== Annex: the radio scripts

=== The radio URL script

1347
The `url` field inside the radio definition can be a direct audio link or a
1348
1349
1350
1351
1352
1353
1354
link to the radio station playlist. This link will be interpreted by the
'fetchstream.py' ('rdpltostream' directory inside the source tree, or see
'/usr/share/upmpdcli/rdpl2stream'). The Python code knows about the various
playlist formats used by the stations.

=== The dynamic album art script

1355
If set, `artScript` is the path to an executable script which can retrieve
1356
1357
1358
1359
1360
1361
the image URL for the currently playing title. It can also be a simple
script name if this is located in the PATH or in the 'radio_scripts'
directory inside the upmpdcli directory (typically '/usr/share/upmpdcli').

Some radios (e.g.  link:https://www.radioparadise.com/rp_2.php?#[Radio
Paradise]) publish the album art for the currently playing title. The
1362
details vary. The `artScript` parameter, if set, should point to an
1363
1364
1365
executable script which prints this dynamic art Uri to stdout. The image
will supercede the radio logo, to be displayed by control points. Beware
that the path to the script must be accessible by the _upmpdcli_ user,
1366
which may not be the case for your home. `/usr/local/bin` is your
1367
1368
1369
1370
1371
1372
1373
1374
friend. The Upmpdcli installation has a very small set of scripts inside
the '/usr/share/upmpdcli/radio_scripts' directory. This includes a very
rough example for retrieving the Radio Paradise art URI,
'radio-paradise-get-art.sh' 

The art script is executed each time the stream metadata changes (the data
is obtained by mpd from Icy metadata in the stream).

1375
Upmpdcli does not set a timeout for the `artScript` execution. A reasonable
1376
1377
value should be used inside the script, to avoid freezing upmpdcli forever.

1378
1379
There is no reason to have an `artScript` if `metaScript` exists for the
radio. `metaScript` can also return the image URL.
1380
1381
1382

=== The dynamic metadata script

1383
If set, `metaScript` is the path to an executable script which can retrieve
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
the metadata (possibly including art Url) for the currently playing
title. It can also be a simple script name if this is located in the PATH
or in the 'radio_scripts' directory inside the upmpdcli directory
(typically '/usr/share/upmpdcli').


The script should output the metadata in JSON format. An example output
follows (the newlines and whitespace are just here for readability, any
valid JSON will do):

----
{
    "title" : "The title of the current track",
    "artist" : "The artist playing",
    "album": "The album name",
    "artUrl" : "https://www.somesite.com/path/to/image.jpg",
    "audioUrl" : "http://some url",
    "reload" : 103
}
----

1405
The `reload` value gives the number of seconds after which the script
1406
1407
1408
should be re-executed (the clever radio sets this to the remaining song
time). By default, the script is executed every 10 S.

1409
Any value not present will simply not be used (not an error). `audioUrl` is
1410
1411
1412
1413
1414
1415
1416
generally not set. If it is set, it's the next audio Url to queue after the
current one (this is used for radio streams which are a sequences of URLs
rather than a continuous stream, for example the Radio Paradise FLAC
station).

The 'radio_scripts' directory has two examples of radio metadata scripts, a
simple one ('fip-meta.py'), and a quite complicated one
1417
1418
('radio-paradise-get-flac.py'). Both need the Python3 'requests' package to
be installed.
1419

Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1420

1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
[[COMMAND-ENVIRON]]
== Annex: command line and environment

In most situations, *upmpdcli* will be run as follows:

    upmpdcli -D -c /etc/upmpdcli.conf

The `-D` option tells *upmpdcli* to fork and run in background. The `-c`
option specifies a configuration file.

1431
1432
1433
See the upmpdcli(1) manual page for more information about the command
line.

1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
Some of the essential configuration parameters can be set from the command
line, a configuration file, or the environment in this order of
priority. It would be rather confusing to use a mix of methods, so you
should probably chose one.

All parameters have defaults, and a minimal installation will need no
customisation at all. 

|========================
|What|Command line|Environment|Config variable
|Configuration file name|-c config|$UPMPD_CONFIG|
|Host name or IP address where *MPD* runs|-h mpdhost|$UPMPD_HOST|mpdhost
|TCP port for *MPD*|-p mpdport|$UPMPD_PORT|mpdport
|UPnP "friendly name" for the device. This gets displayed in network search
  results.|-f friendlyname|$UPMPD_FRIENDLYNAME|friendlyname 
|Log file name. Leave empty for stderr|-d logfilename||logfilename
|Verbosity level (0-4)|-l loglevel||loglevel
|UPnP network interface|-i iface|$UPMPD_UPNPIFACE|upnpiface
|UPnP port|-P port|$UPMPD_UPNPPORT|upnpport
1453
1454
|========================

1455

1456
1457
1458
1459
1460
1461
1462
1463
[[UPMPDCLI-CONFIG-GUI]]
== Annex: the upmpdcli-config GUI configuration editor.

The upmdpcli-config tool presents a graphical interface for creating an
upmpdcli configuration file. It presents different tabs with controls,
directly matching the organisation of the parameters in the documentation.
Both the tool and the manual are generated from data in the reference
configuration distributed with the package (typically
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1464
'/usr/share/upmpdcli/upmpdcli.conf-xml').
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484

You can use the tool to create a configuration from scratch (just tweak
what you want, then save the file), or for editing an existing
configuration. The latter can be done either by passing the configuration
file name on the command line, or by using the 'Open' menu entry. If you
use the command line, the parameter automatically becomes the target of a
future 'Save' command (you can change it by using 'Save as'). When using
'Open', you will be asked to choose an output destination when saving.

Each control has a label, and an longer explanation in a tooltip, which you
can see by leaving the cursor on the label. 

Once you are satisfied with the changes, you can save the file, and move it
to its normal location if needed (e.g. '/etc/upmpdcli.conf').

Only the parameters which were changed in the configuration you edit (if
not starting from scratched), and those which you change through the
interface, will be saved to the output. Parameters unchanged from the
defaults will not appear at all, allowing for a less cluttered file.

1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
[[SCWEB]]
== Annex: the scweb Songcast control interface.

This is only useful if you have no machine on which to run *upplay*, or
*Bubble DS Next*. Either are easier to use than the web
tool.

To avoid having to access the command line interface to control the
*Songcast* groups, *upmpdcli* comes with a small Web server which uses
*scctl* to actually do the work. This is found inside the `web/`
subdirectory inside the *upmpdcli* source tree.

The server is based on the 
link:http://bottlepy.org/docs/dev/index.html[Bottle Python Web Framework]
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
1499
and it only depends on Python 3.
1500
1501
1502
1503

You can use the `scweb-standalone.py` script to manually start the
interface:
    
Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
1504
    python3 ./scweb-standalone.py
1505
1506
1507
1508
1509
1510

This will start a server on localhost, on port 8680 by default which is
good for testing, but not very useful. Use the -a 0.0.0.0 option to let the
server answer on all local addresses (or specify the address to use a
specific interface):

Jean-Francois Dockes's avatar
Jean-Francois Dockes committed
1511
    python3 ./scweb-standalone.py -a 0.0.0.0
1512
1513
1514
1515
1516
1517
1518
1519
1520

-p can be used to specify a port.

Once started, connecting to the server from any browser should hopefully
display a reasonably self-explanatory interface.

Recent *upmpdcli* packages install the web app as a service named
*scweb*. The service is not started by default though, you need to edit
`/etc/default/scweb`.
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531

[[OHCREDS-OPENSSL]]
== Annex: building openssl for Debian Jessie

The OHCredentials service needs OpenSSL 1.1 but Debian Jessie only has
1.0. The following recipee builds a static version of the openssl command,
which is installed with a specific name (upmpdcli-openssl). No libraries
are installed and the standard command is left undisturbed, so that there
is no risk of damaging the system.

Note that I am making no claims about the security of the encryption
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1532
provided by this method. This should be fairly sufficient for a Tidal
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
password going around your local network though (except maybe if you think
that the NSA is interested in your playlists).

----
sudo apt install git make gcc
cd 
git clone https://github.com/openssl/openssl.git
cd openssl
git checkout -b origin/OpenSSL_1_1_0-stable
./config
make
Jean-Francois Dockes's avatar
doc    
Jean-Francois Dockes committed
1544
cc -o upmpdcli-openssl apps/*.o  apps/libapps.a libssl.a libcrypto.a -ldl -lpthread