Upmpdcli

Introduction

This manual is about Upmpdcli, a combined UPnP Media Renderer and Media Server program.

The two functions, as Renderer or Server, are completely independent, and any instance can be configured to run as one, or the other, or both. The reason that they are implemented in a single program is mostly historical, and also justified by the shared UPnP libraries. In any case, if you are only interested in one aspect, you can completely ignore the sections of this document which deal with the other.

For its Media Renderer function, upmpdcli uses the great Music Player Daemon (mpd) for audio stream processing. upmpdcli itself never touches the audio stream, which goes directly from its origin to mpd.

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 network streamer.

As a Media Server, upmpdcli implements its functions through independent plugins. One of these will make local audio files accessible through UPnP, and some others will turn upmpdcli into a proxy for a number of streaming services, exposing their catalog and streams to the UPnP side. Some other plugins implement miscellaneous functions, mostly dealing with radio stations or catalogs.

The 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 upmpdcli overview section, which exposes the above in a little more detail, or, even directly to the upmpdcli media renderer section, or to one of the chapters in the upmpdcli media server section.

Security

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.

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).

Figure 1. Network Audio

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 a Renderer. This is the main reason for using OpenHome (see next).

OpenHome

The OpenHome family of open protocols were designed by Linn to correct the weaknesses in UPnP AV. They implement extended services over the base UPnP mechanisms.

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 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).

Songcast

Songcast is an open protocol designed by Linn for real-time network audio, allowing synchronized playing on multiple sources. 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.

The protocols links two types of entities:

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

Linn used to supply free audio capture drivers functionning as Songcast Senders, for MS-Windows and Mac OS X. This enabled playing the audio of any application (Windows Media Player, Spotify, etc.) onto one or several Songcast Receivers, without any need for the applications to know about Songcast. These drivers are now discontinued, apparently due to changes in the OS security models. However, Songcast can still be useful for synchronized playing on multiple Songcast-aware players, Linn or other.

Gapless ?

This is a relatively small issue, but people are very sensitive to it, it is important from some music pieces and you will hear about it all the time if you read forums, so, a quick explanation follows.

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 renderer before the current track finishes (e.g. UPnP/AV SetNextTransportURI).

Bitperfect ?

This is the quality of the audio transport pipeline which will exactly preserve the binary values stored in the source material down to the input of the Digital Analogic Converter. Having a bitperfect transport can be significant if you need to preserve some special data stored in the low encoding bits (e.g. MQA), or if you have very good ears.

This is meaningful for material stored either as PCM data (e.g. uncompressed WAV or AIFF), or stored in a lossless compression format (e.g. FLAC). It does not make much sense if the audio is originally stored in a lossy compression format.

Several operations can change the sample values. The most common one is software volume adjustment. Some, but not all, transcoding operations can also affect the values. Almost by definition these are the conversions from and to lossy compression methods. Conversions to/from a lossless format (FLAC) should not affect the values if correctly implemented.

In the UPnP world, some conversions may occur on the Media Server and on the Renderer. The Control Point has no influence on the audio stream (actually it does not see it at all). Some Control Points implementations may also include internal Renderer or Media Server functions, in which case they can affect the audio data as any other implementation of these.

You need to have a look at the documentation of the UPnP Media Renderer and Media Server for information on if and what transcoding may take place. (Transcoding can be negotiated differently between the renderer and each receiving client).

The Mpd audio pipeline may be bitperfect or not depending on configuration. Upmpdcli itself never modifies the audio stream (actually the renderer part does not see it at all).

Upplay, the companion Control Point, never accesses or modifies the audio data.

Upmpdcli overview

Upmpdcli was originally primarily an UPnP Media Renderer, using MPD to actually process the audio data. The renderer supports UPnP gapless track transitions and the OpenHome ohMedia services (including a Radio service to listen to Internet streams).

Figure 2. The Grand Upmpdcli Media Renderer Scheme of Things

Additionally:

The upmpdcli program also implements a Media Server. This function is hosted in the same program (and usually runs in separate threads of the same process), but it is completely independent: upmpdcli can run as Renderer only, or Media Server only, or both, and the Media Server can be accessed by any Control Point and serve streams to any Renderer, not only to its co-hosted one. The Upmpdcli Media Server implements gateways to external streaming services (Highresaudio, Qobuz, Tidal…), and also includes the uprcl module, which provides a Media Server for local audio files. uprcl is based on the Recoll medata extraction and search functions.
Upmpdcli implements control functions for the Linn Songcast protocol, allowing the local machine to behave as a Songcast Receiver or Sender (with help from the closely related sc2mpd package, for processing the audio streams).

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.

If some cases, Upmpdcli can operate without a configuration file, as a few of the main parameters can be set on the command line or in the environment.

Most parameters can only be set in the configuration file, though. The file is designated with the -c command line option. The usual location is /etc/upmpdcli.conf.

The configuration file has a simple name = value format, and is fully described in the configuration reference section.

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.

The upmpdcli-config graphical tool can help you edit the configuration file, it can present the same information as this manual, directly linked with the controls used to modify the parameters.

Upmpdcli can be run as root. In this case it will change its user id to upmpdcli after some initialisation and permissions setup for its data cache, usually under /var. The process can also be started by any regular user, in which case it will store its data under ~/.cache/upmpdcli.

Upmpdcli Media Renderer

This section goes in a little more detail about miscellaneous aspects of the Media Renderer, and describe a few of the most used configuration parameters. See the configuration reference section for more details (I would very much like to link each parameter to its definition but Asciidoc won’t let me do it, so they link to the top of the appropriate section.).

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 Points can be set with the friendlyname configuration parameter. Some Linn Control Points (e.g. Kazoo) use another value, set with ohproductroom.

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

The Upmpdcli Media Renderer has two active interfaces by default: UPnP AV 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 openhome and upnpav parameters.

Audio formats

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

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 checkcontentformat to 0.

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 little tested for streaming). Support will vary depending on the MPD versions and exactly what input plugins are configured (among ffmpeg, libaudiofile and libsndfile). Often, the same files play just fine locally, it’s the combination of HTTP access and file format which causes 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 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 parameters with the MIME type). See this issue for more details: https://www.lesbonscomptes.com/upmpdcli/github-issues/upmpdcli-html/issue-36.html

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.

Radio stations

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.).

This facility uses Python 3.x, which must be available on the system for the radio links to work.

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

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 radiolist parameter in the main configuration.

In both cases, a radio definition entry will look like the following:

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

A radio is defined in a configuration section with a name beginning with radio (e.g. [radio my radio name]). The radio string is mandatory and allows the section to be recognized as a radio definition.

Inside the section, the only mandatory entry is the url one, which should point either to the actual audio stream, or to the station playlist link which will redirect to it.

You can also set artUrl to point to a static icon image for the radio station.

The upmpdcli OpenHome radio source also has the capability to display cover art and metadata for the currently playing stream, if the Internet radio makes it available. This is implemented by executing a script to fetch the appropriate data.

See the radio scripts section for more detail.

Upmpdcli and Songcast

Upmpdcli implements the Receiver UPnP service, and uses an auxiliary process (sc2mpd) for transporting the audio data. sc2mpd is based on the sample program which comes with the Linn Songcast OpenHome open source implementation

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).

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).

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).

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.

Upmpdcli Receivers before release 1.2.14 are not visible in Linn Kazoo. Later versions can be linked, and stream, from a Linn Sender.

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.

Songcast Receiver

sc2mpd can play the Songcast audio stream in two modes:

By directly using the alsa audio driver.
By using mpd to play the stream offered from a local HTTP interface (hence the sc2mpd name)

Table 1. Upmpdcli Receiver in `alsa` and `mpd` modes
`alsa`	`mpd`

What approach is used is decided by the scplaymethod configuration parameter, which can be set to mpd or alsa.

The mpd mode is the default, because it needs no configuration, but there are multiple problems with it. If you go the alsa route, you will need to set scalsadevice in the configuration, but you probably had to set it in the MPD configuration too, so this may not be too much of an issue.

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.

When using mpd, more bufferisation occurs and there may be a significant delay (up to around 10 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 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.

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 time. The reasons are explained in the multiroom synchronization section.

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.

Note

Songcast can use IP multicast for lower load on the network when 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.

Songcast Receiver Volume control

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 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 scusempdvolume variable to 1 in the local upmpdcli.conf. This only works if if scplaymethod is alsa.

Songcast Sender

Upmpdcli Sender mode allows you to broadcast the Playlist or Radio source (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, so that you won’t be able to cast other applications transparently (but there are specific workarounds).

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 upplay, for example, you can select the source from the File→`Select Source` menu entry.

The sc2mpd configuration must be set with scplaymethod = alsa for the XX-to-Songcast sources to appear. See the configuration section, and the section about synchronisation.

When entering Sender mode, upmpdcli will start an auxiliary MPD process (after stopping the main one), configured to send audio to the mpd2sc OpenHome Sender process. It will then also start its own Songcast Receiver mode, transfer the playlist, stop the main MPD and start the 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 the Songcast Receiver. Other Receivers can be connected and will play in good synchronization.

This looks complicated, but in practise, starting the mode and connecting other Receivers from the upplay control panel is quite straightforward.

Managing external sources

In the Sender modes described above, upmpdcli (or rather its mpd 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.

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).

Still the details are a bit too much involved for the main body of the manual, so I have moved them to an annex.

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 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.

Synchronisation issues

The short version is: for good synchronization, all sc2mpd instances must be configured to play directly to the audio driver with scplaymethod = alsa. See the configuration section.

Longer version: Songcast is a real-time audio stream. As the Sender and Receiver sample clocks (the 44.1 or 48 KHz clocks) are independent, 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).

Independently 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.

Upmpdcli Media Server

Overview

The upmpdcli Media Server provides a number of separate functions, which can be activated through the configuration file.

The uprcl plugin enables access to your local audio media collection.
The subsonic plugin proxies access from a Subsonic/Navidrome server to UPnP.
Several plugins function as gateways for commercial streaming services such as Qobuz.
And other plugins provide various functions: an access to the upmpdcli internet radio list, access to the BBC Sounds service, or the Radio Browser Web radios catalog…
A plugin can be a quite simple Python program, and if you feel like writing one, we have a doc for you.

When at least one plugin is activated, upmpdcli creates a separate auxiliary Media Server. By default, the Media Server name is the friendlyname for the Upmpdcli instance, with -mediaserver appended, but this can be changed in the configuration.

In general, a plugin is activated by being installed, and having its user name defined in the configuration file (e.g. for a plugin named myplugin mypluginuser = somevalue). Depending on the plugin, the variable value maybe real (e.g. a Qobuz user name), or bogus and unused.

A description of each of the plugins follows. Some of them need the additional installation of Python extensions from Pypi. These should be done globally, or in some alternate way ensuring that they are visible to the boot-started upmpdcli. If a given dependency is packaged by your distribution, it may have been installed with the plugin.YMMV: look at the error output with, e.g. journalctl if things do not work.

Uprcl Media Server

The Upmpdcli application includes a Media Server function for local music files, analog to MinimServer or ReadyMedia/MiniDLNA. The plugin module is named uprcl.

Enable this function by installing the upmpdcli uprcl module (which may be a separate package, e.g. upmpdcli-uprcl on Debian), and uncommenting the bogus setting for the uprcluser variable in the upmpdcli configuration file. You may also want to set uprclautostart to 1 so that initialisation is performed as soon as the program start, and not on the first access. Also: you need to install Recoll (just the command line and Python3 extension are needed) if your package manager did not do it for you. If you are using the upmpdcli repositories (on Launchpad for Ubuntu or the lesbonscomptes server for Debian), this will happen automatically.

Note	'python3-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).

Note	uprcl needs Python 3.5 at least. This means that it does not work on Debian Jessie (8.x)

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 (python3), 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.
Uses Recoll and python3-recoll (hence the uprcl name) for harvesting the metadata and searching.
Uses Python3 Sqlite3 (on a memory DB) for the tags tree.
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:

contentDir will be used if uprclmediadirs is not set in '/etc/upmpdcli.conf'
excludePattern
aliasTags
indexTags
showExtras
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.

Installation and configuration: have a look at the configuration variables

The server also starts a minimal Web interface displaying the current running status and allowing to ask for an incremental or full scan of the media directories. By default, this runs on port 9090.

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.

SubSonic plugin

The plugin allows access to a SubSonic server. Specifically, it has been tested against a Navidrome instance, but there is nothing Navidrome-specific in the code.

Note	The plugin needs the installation of two additional Python packages: subsonic-connector version 0.3.2 and py-sonic.

List of currently available Features:

List Newest Albums
List Recently Played Albums
List Highest Rated Albums
List Most Played Albums
List Random Albums
List Favourite Albums
List Artists (All)
List Artists (By Initial)
List Favourite Artists
List Random Songs (Navigable and List mode)
List Favourite Songs (Navigable and List mode)
List Genres: each Genre return Albums and the relevant Artists
List Playlists
List Internet Radios
Artist view: Similar Artists
Artist view: Top Songs (Navigable and List mode)
Artist view: Radio (Navigable and List mode)
Album view (when not coming from the Artist): Link to Artist
Album view (when not coming from the Artist): Top Songs by Artist (Navigable and List mode)
Album view (when not coming from the Artist): Similar Artists
Album view (when not coming from the Artist): Radio (Navigable and List mode)
Song view (when not coming from the Artist/Album): Link to Album
Song view (when not coming from the Artist/Album): Link to Artist
Search Albums
Search Tracks
Search Artists

Notes on navigation by genre: - Clicking on a Genre will show two entries, named Artists and Albums - Clicking on Albums from a selected Genre, you will see a list of Albums from the selected genre - Clicking on Artists from a selected Genre, you will get a list of Artist which have albums for the selected Genre - Clicking on Albums from an Artist within a Genre, you will get a list of Albums from the selected artist in the select genre

The subsonic plugin is enabled by uncommenting the bogus setting for the subsonicuser variable in the upmpdcli configuration file. So you will also need to specify:

subsonicbaseurl
subsonicport
subsonicuser
subsonicpassword

and, optionally,

subsoniclegacyauth

For example if your server is https://my-navidrome.mydomain.com, you will need to set

subsonicbaseurl = https://my-navidrome.mydomain.com
subsonicport = 443

if your server is http://my-navidrome.homelab.local:4533, you will need to set

subsonicbaseurl = http://my-navidrome.homelab.local
subsonicport = 4533

Consider that mpd will need to access those url, as well as your phone/tablet if you plan to use BubbleUpnpServer. Consider using ip addresses if your android phone has difficulties resolving local network hostnames. If this happens, you might not be able to see the album covers, for example.

The parameter subsoniclegacyauth is optional and disabled by default. Legacy authentication should be set (enable it with 1) for subsonic servers which need these authentication mode. To my knowledge, only lms (Lightweight Media Server) currently needs legacy authentication to be enabled.

There are currently a few additional configuration parameters in the configuration section.

Streaming Services

The Media Server function in Upmpdcli gives access to external streaming services: Highresaudio, Tidal and Qobuz currently work fine (1.7.0). Deezer used to work, but does not any more (API change fall 2023).

You will need a valid subscription for any service that you want to use.

Streaming is not limited to the local Upmpdcli Renderer, and the Media Server will happily send music to other Renderers (within the limitations set by the service).

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 in a separate package (e.g upmpdcli-qobuz).
The user variable for the service must be present in the configuration file (e.g qobuzuser).

Some other parameters (e.g. a password) may be needed for the access to work, depending on the specific service. See the service-specific notes below.

There are several possible approaches for proxying access to streaming services. We have a little more detailed documentation in a separate section.

Note	The streaming services passwords are stored in the upmpdcli 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 the password: `chmod 600 /etc/upmpdcli.conf`.

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.

Tidal

You will need the upmpdcli-tidal module. Depending on your distribution and installation method, this may come as part of the base installation, or be a separate package.

The Tidal module code is is based on the Tidal API currently at version 0.8.1, by Thomas Amland (also using other useful modules by Thomas). You will need to install the package separately, preferably system-wide, for example:

sudo python3 -m pip install tidalapi==0.8.1

Depending on the version of your operating system, you might need to append the following to the previous instruction:

--break-system-packages

The Tidal plugin only works with a valid Tidal subscription. It is not officially supported by Tidal, and may just stop to work one day…

Keep in mind that if you choose HI_RES_LOSSLESS audio quality, your renderer must be able to play MPEG-DASH streams. Currently, only mpd and gmrender-resurrect support this type of streams.

Accessing Tidal requires you to obtain a set of valid Tidal credentials.

The credentials can be obtained by running a Python script, by default at the following location (which may depend on the installation location):

python3 /usr/share/upmpdcli/cdplugins/tidal/get_credentials.py

After running the script, you will be presented with the following output:

Visit https://link.tidal.com/XXXXX to log in, the code will expire in 300 seconds

Copy the URL and paste it to your browser. You will be presented with a Tidal authentication screen. Log in with your username and password (if you weren’t logged in already), and then click on the "Authorize application" (or the button with some similar text). After that, you will get an output from the script, which will include a json file. This is the content that you should store in the tidal cache plugin, which is typically /var/cache/upmpdcli/tidal.

If you want, you can use the -f argument and specify the target file. You can use this feature and have your credentials file written directly by the get_credentials.py program. Example:

sudo -u upmpdcli python3 /usr/share/upmpdcli/cdplugins/tidal/get_credentials.py \
  -f /var/cache/upmpdcli/tidal/oauth2.credentials.json

The ownership of the generated file depend on the user which runs the script. In the previous example, the script will run as the upmpdcli user.

Alternatively, you can skip all configuration parameters, and authenticate directly on the first access to tidal. In order to do so, you will need to monitor the upmpdcli application logs. When the plugin is accessed and authentication details are not available yet, the log will present the same output described before:

Visit https://link.tidal.com/XXXXX to log in, the code will expire in 300 seconds

Just visit the link, authenticate and authorize. The plugin will save a json file named oauth2.credentials.json in the plugin cache folder. If you need to re-authenticate, just delete the oauth2.credentials.json file in the plugin cache folder.

Also, HI_RES_LOSSLESS quality mode requires the webserverdocumentroot to be enabled in upmpdcli.conf. Set it to a value like /var/cache/upmpdcli/public.

The configuration variables are further described in the configuration section

Qobuz

This is based on the service API from the 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 just stop to work one day.

Note	The plugin uses the `requests` Python3 package, which is usually installed as a package dependency. Else install it from Pypi.

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.

You need a valid Qobuz subscription.

Enable this function by installing the upmpdcli Qobuz module (which may be a separate package, e.g. upmpdcli-qobuz on Debian), and adding your login and password to the configuration (as qobuzuer and qobuzpass).

The configuration parameters are described in the configuration section

If you are using the Linn Kazoo Control Point, upmpdcli has support for the Credentials service, which facilitates configuration. Details here.

radio-browser.info

The plugin allows access to the Radio Browser Web radios catalog. Radios can be selected by country, language and tag, and/or searched for by name.

This uses the pyradios Python module.

Note	`pyradios` is usually not packaged by the Linux distributions (e.g. Debian). You need to install it separately, using, e.g. `pip3`.

Then enable the function by installing the upmpdcli radio-browser module (which may be a separate package), and uncommenting the bogus setting for the radio-browseruser variable in the upmpdcli configuration file.

There is an option to enable local radios. So, instead of navigating to countries and then select your country, you can also have direct access to a local entry, which will represent a convenient shortcut.

You can enable this feature using either the parameter radio-browsercountry and setting it to the 2-digit country code of your choice (FR, IT, etc) or you can configure the parameter radio-browseripinfotoken to the token you can obtain registering to ipinfo. In the latter case, the country will be selected according to the country of your internet service provider.

The radio-browsercountry parameter has the priority on the radio-browseripinfotoken parameter.

The plugin arguments are listed in the configuration section.

radioparadise.com

The plugin allows access to the Radio Paradise Web radios catalog.

Then enable the function by installing the upmpdcli radio-paradise module (which may be a separate package), and uncommenting the bogus setting for the radio-paradiseuser variable in the upmpdcli configuration file.

There are currently no additional configuration parameters. Any would go in the configuration section.

motherearthradio.de

The plugin allows access to the Mother Earth Radio Web radios catalog.

Then enable the function by installing the upmpdcli mother-earth-radio module (which may be a separate package), and uncommenting the bogus setting for the mother-earth-radiouser variable in the upmpdcli configuration file.

There are currently no additional configuration parameters. Any would go in the configuration section.

BBC Sounds

The plugin allows access to the BBC Sounds resource for listening to past BBC programs. It normally lists the 30 previous days, this can be changed with a configuration variable.

Enable this function by installing the upmpdcli BBC module (which may be a separate package, e.g. upmpdcli-bbc on Debian), and uncommenting the bogus setting for the bbcuser variable in the upmpdcli configuration file.

The configuration parameters are described in the configuration section.

Note	the plugin needs the installation of additional Python3 packages, which may or may not be packaged by your distribution. beautifulsoup4 (aka bs4), dateutil, feedparser, and requests. Install them as packages if possible, else, from Pypi.

Upradios radio list

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

Because just the stream URL is computed/used, the functionality is reduced when compared to using Upmpdcli OpenHome Radio service: there will be no dynamic art or special metadata features: artScript and metaScript entries are just ignored.

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.

Enable this function by installing the upmpdcli Radios module (which may be a separate package, e.g. upmpdcli-radios on Debian), and uncommenting the bogus setting for the 'upradiosuser' variable in the upmpdcli configuration file.

The configuration parameters are described in the configuration section.

Configuration file reference

A description of upmpdcli configuration variables follow. As of upmpdcli 1.6.0, all values can also be set through environment variables named UPMPD_XXX where XXX is the upper-cased version of the variable name (Ex: loglevel → UPMPD_LOGLEVEL).

In the case where a variable is set in several ways, the order of precedence is: command line (highest), configuration file, environment.

If used, the configuration file name can be set either with the -c command line option or through the UPMPD_CONFIG environment variable.

Upmpdcli configuration

Upmpdcli general parameters

logfilename: Log file name. Defaults to stderr. This can also be specified as -d logfilename.

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

upnplogfilename: Log file name for the low level UPnP lib (libnpupnp). This log is not active if this variable is not set at all. Use an empty value for the messages to go to stderr.

upnploglevel: Log level for the low level UPnP lib. For historical reasons the matching values are 1 less than equivalent values for the upmpdcli log. 4 is very verbose.

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

pidfile: Name of the 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: Network interface(s) to use for UPnP. This can be left empty to use the first found suitable interface, or set to a single "*" character for using all interfaces. Else set it to a space-separated list of interface names (use double quotes if the names have embedded space characters).

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

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.

useipv6: Enable use of IPV6. By default we only use IPV4.

Media Renderer parameters

friendlyname: "Friendly Name" for the Media Renderer. This will be displayed by most Control Points to identify the Renderer. Some OpenHome Control Points may display the 'ohproductroom' value instead.

avfriendlyname: Specific friendly name for the UPnP/AV Media Renderer. The default is to append "-av" to the friendlyname value.

upnpav: Enable UPnP AV services (0/1). This is set by default, but it may useful to switch it off to avoid cluttering the Renderer choices if you only use OpenHome.

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.

lumincompat: Disable the OpenHome Credentials service. At some point, this was necessary to enable Lumin to see upmpdcli instances: for some unknown reason, Lumin 1.10 did not discover upmpdcli with Credentials enabled.

ohinfotexttodata: Store metadata into the OpenHome "metatext" variable. The OpenHome Info service are supposed to hold different data, mostly for radios, with permanent radio data (icon, url, radio name) set in the "Metadata" variable, and information about the current title recorded in the "Metatext" variable. Setting this option will have upmpdcli store any non-empty Metatext data in the Metadata variable. This will help some players display the album art for the current title (e.g. Kazoo).

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.

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.

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.

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.

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.

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'.

enablel16: Advertise L16 format support L16 is a raw linear 16 bits audio stream and the source of many issues because it does not include identifying information. It used to be disabled by default, because of an mpd bug resulting in a lot of noise. It’s now on by default, but can still be disabled if needed. It seems that it sometimes interfers badly with the win10 "cast to device" feature, so you may try to turn it off if you have problems with this.

MPD parameters

mpdhost: Host MPD runs on. Defaults to localhost. This can also be specified as -h host

mpdport: IP port used by MPD Can also be specified as -p port. Defaults to the normal MPD port, 6600

mpdpassword: MPD password. Password for connecting to MPD (only necessary if password access is enabled in the MPD configuration file).

mpdtimeoutms: MPD connection timeout in milliseconds. If this is not zero, dialogs with mpd will timeout after the value. This will allow upmpdcli to stay responsive (return errors) if MPD ever becomes stuck.

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.

Audio control hooks

onstart: Command to run when playback is about to begin. Specify the full path to the program, e.g. /usr/bin/logger.

onplay: Command to run when MPD state switches to "PLAY". Specify the full path to the program, e.g. /usr/bin/logger.

onpause: Command to run when MPD state switches to "PAUSE". Specify the full path to the program, e.g. /usr/bin/logger.

onstop: Command to run when MPD state switches to "STOP". Specify the full path to the program, e.g. /usr/bin/logger.

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.

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'

getexternalvolume: Command to run for reading the sound volume. The command should write a 0-100 numeric value to stdout.

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.

UPnP/AV tweaking

avtautoplay: Automatically fake a Play command when track is set. The UPnP/AV SetAVTransportURI, used to set the track to play, normally does not change the current transport state: an explicit Play command is required to start playing if the transport was stopped. Setting this parameter will synthetize a Play command after receiving SetAVTransportURI. This is needed by some control points which do not send the Play command.

OpenHome parameters

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.

radiolist: Path to an external file with radio definitions. Radio stations can be defined in this file (main configuration file), or in an external file (or both). Using an external file can ease distribution to multiple machines, makes things clearer and is now the default. See the distributed file (name below) for information on how to define a radio station. In case you want to define radios in the main configuration file, they MUST occur at the end of the file (because they are defined as subsections, the last of which extends to the end of the file).

radioscripts: Radio metadata scripts directory. Path of a directory where the scripts used for fetching the channel metadata are located. The default is /usr/share/upmpdcli/radio_scripts. Note that the scripts are always first looked for in the locations defined by $PATH.

ohmanufacturername: Manufacturer name.

ohmanufacturerinfo: Manufacturer information.

ohmanufacturerurl: URL for manufacturer web site.

ohmanufacturerimageuri: Uri for manufacturer’s logo.

ohmodelname: Model name.

ohmodelinfo: Model information.

ohmodelurl: URL for model web site.

ohmodelimageuri: Uri for model’s icon.

ohproductname: User-visible product name. By default this is set to ModelName.

ohproductinfo: Product information.

ohproducturl: URL for product web site. This may be the UPnP presentation page.

ohproductimageuri: Uri for product image.

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: 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).

Media Server general parameters

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

msrootalias

Media Server root alias Object ID. Use the specified Media Server container as root. The Control Point will directly show this container when connecting, which will avoid having to skip over the top levels if you don’t use them. (E.g. the active plugin list if there is only one plugin). The value is an UPnP object ID, which is unfortunately not generally obtainable from Control Points. However the commonly useful values are simple:

0$uprcl$ Direct access to the Local Media root
0$uprcl$folders Direct access to the Local Media [folders] tree.

An alias must begin with 0 (which is the mandatory UPnP root object ID), followed by $pluginname$ where pluginname could be any subdirectory of /usr/share/upmpdcli/cdplugins except pycommon (e.g. uprcl, qobuz, upradios…), and the rest would depend on the plugin type.

plgmicrohttphost: Hostname/IP address used in proxy URLs. The default is to use the same host/address as the UPnP server. Using localhost/127.0.0.1 instead loses the ability to stream to a remote renderer, but allows for portable playlists.

plgmicrohttpport: IP port for the tidal/qobuz 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.

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.

msiconpath: Path to the Media Server icon. The image will be displayed by Control Points which support it. 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.

webserverdocumentroot: Directory from which the internal HTTP server will directly serve files This is disabled by default for compatibility with older versions which never served files directly from the filesystem. Some Mediaserver plugins ask to enable it, e.g. for serving icon files (normally from directories under /usr/share/upmpdcli/www).

Highresaudio streaming service parameters

hrauser: Hra user name. Your Hra login name.

hrapass: Hra password. The password for your Hra account.

hralang: Hra language setting (en/de). Some Highresaudio messages will be set in the appropriate language.

hratitle: Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

Qobuz streaming service parameters

qobuzuser: Qobuz user name. Your Qobuz login name.

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

qobuzformatid: Qobuz stream quality. 5 for mp3/320, 6 for FLAC, 7 FLAC 24/96, 27 for hi-res (if your subscription allows streaming each of the formats).

qobuzrenumtracks: Qobuz track renumbering. Renumber tracks by counting elements, avoiding issues with Kodi. Enabled by default.

qobuzexplicititemnumbers: Explicit item numbers in brackets. Add item numbers in square brackes in lists, mostly for kodi compatibility/usability. Disabled by default.

qobuzprependartisttoalbum: Artist name before albums in album lists. Prepend artist to album in album lists, mostly for kodi compatibility/usability. Disabled by default.

qobuztitle: Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

Tidal streaming service parameters

tidaluser: Bogus user name variable. Decides if the service should be started. Set it to any arbitrary value.

tidaltokentype: Oath2 authentication token type. The type of token used for OAUTH2 authentication, typically Bearer.

tidalaudioquality: Tidal maximum stream quality. LOW for mp3/96, HIGH for mp3/320, LOSSLESS for FLAC 16/44, HI_RES for FLAC up to 24/48, HI_RES_LOSSLESS for hi-res FLAC files (if your subscription allows streaming each of the formats).

tidaltitle: Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

tidalprependnumberinitemlist: Use item numbers in album lists for kodi compatibility Kodi always tries to sort things, with this parameter we force it to show the entries in the desired order.

tidalenableimagecaching: Enables image caching, requires webdocumentroot Allows the plugin to cache images for Artists and Albums, requires webdocumentroot and some disk space, recommended

tidalsearchlimit: Tidal search limit Set the maximum numbers of item returned by search, defaults to 15

tidaloverridecountrycode: Override the country code. This will allow you to specify the desired two-letter country code. When not specified, it should default to the country code of the profile.

UPRCL Local Media Server parameters

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). You probably also want to set uprclautostart=1 so that initialisation starts as soon as the program does.

uprcltitle: Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

uprclhostport: Uprcl HTTP server host and port for serving media files. Uprcl uses a separate HTTP server based on the Python Bottle framework and Waitress server. The HTTP server will listen 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 same address as the server used for other services (either plgmicrohttphost or the first ipv4 address used by the upnp layer. not. Example: 192.168.1.1:9090. As it is reasonable to use the same address as the upnp layer, see also uprclport for just specifying the port.

uprclport: Uprcl HTTP server port for serving media files. Port to use for listening for media requests. The listen address will be either plgmicrohttphost if it is set, or the first ipv4 address used by the upnp layer. Ignored if uprclhostport is set.

uprclconfdir: uprcl Recoll index directory This is usually not defined and defaults to /var/cache/upmpdcli/uprcl. The name is a bit misleading because there is little real configuration data in there: it’s mostly programmatically generated from actual configuration found elsewhere (but also see uprclconfrecolluser).

uprclconfrecolluser: Name of the user Recoll config additions file This is the name of a file with additional parameters for the uprcl recoll.conf file, to which the contents will be appended before indexing. The default is /var/cache/upmpdcli/uprcl/recoll.conf.user. If set, should be an absolute path.

uprclminimconfig: Name of the Minim Server configuration file If set, this is the name of a Minim Server configuration file from which we should fetch parameters like aliasTags, etc. (See the manual). Not set by default, and optional.

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. If not set, we will try to use contentDirs from the Minim config. An error will occur if both are empty.

uprclnotagview: Suppress folder "Tag View" entries. The "Tag View" entry allow browsing a subdirectory by tags. It can be quite useful but also a problem with some Control Points, or kinds of usage.

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.

Upmpdcli Radios plugin parameters

upradiosuser: 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 to see the radio list).

upradiostitle: Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

upradiosmaxthreads: Maximum number of threads to use while initializing the radio list Most radios are defined by playlist files which may need several network interactions before the actual URL usable by the control point can be reached. We use multiple threads to speed up this process, this is the maximum thread count.

Radio Browser (https://www.radio-browser.info/) plugin parameters

radio-browseruser: Bogus user name variable. Decides if the service should be started. Set it to any arbitrary value.

radio-browsertitle: Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

radio-browseripinfotoken: IPInfo token. Set your ipinfo token in order to have the shortcut to the local radios.

radio-browsercountry: The preferred country. Set this to the preferred country in order to have the shortcut to the local radios. This is alternative to using the ipinfo token. The values is to be specified in the form of a country code, e.g. FR, IT, etc.

Radio Paradise (https://www.radioparadise.com/) plugin parameters

radio-paradiseuser: Bogus user name variable. Decides if the service should be started. Set it to any arbitrary value.

radio-paradisetitle: Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

Mother Earth Radio (https://www.motherearthradio.de/) plugin parameters

mother-earth-radiouser: Bogus user name variable. Decides if the service should be started. Set it to any arbitrary value.

mother-earth-radiotitle: Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

SubSonic plugin parameters

subsonicuser: SubSonic User name variable. Decides if the service should be started. Set it to the appropriate user name.

subsonicpassword: SubSonic Password variable. Required for SubSonic authentication. Set it to the appropriate password.

subsoniclegacyauth: SubSonic legacy authentication mode. Required for SubSonic authentication with some servers (e.g. lms). Set to 1 to enable.

subsonicbaseurl: SubSonic server base url. URL of the server, without the port. Specify http or https

subsonicport: SubSonic server port. The port of the SubSonic server

subsonicitemsperpage: SubSonic items per page Number of items per page for SubSonic

subsoniccachetimeoutartists: SubSonic cache timeout for artists Cache timeout for artists, defaults to 600

subsonicappendyeartoalbum: Append year to album If enabled, the year will be appended to the album in the lists. Enabled by default.

subsonictranscodecodec: Enable transcoding If a value is set, it will be used as the codec for the transcoding process

subsonictranscodemaxbitrate: Set max bitrate for transcoding If a value is set, it will be used as the max bitrate for the transcoding process

subsonicserversidescrobbling: Enable server-side scrobbling If enabled, we will scrobble the song when streaming starts. Disabled by default.

subsonicprependnumberinalbumlist: Add a progressive number to album in album lists. Mostly for Kodi compatibility and usability. Enabled by default.

subsonictaginitialpageenabledir: Subsonic enable Internet Radios Enables Internet Radios. Disabled by default, upmpdcli offers multiple ways of handling Internet Radios

subsonicshowemptyfavorites: Subsonic show empty Favorites entries Force entries for Favorites, even if there are no Favorites, disabled by default

subsonicshowemptyplaylists: Subsonic show empty Playlists entry Force entry for Playlists, even if there are no Playlists, disabled by default

subsonictitle: Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

Upmpdcli BBC Sounds plugin parameters

bbcuser: Bogus user name variable. Set this to activate the plugin, the value is ignored.

bbcprogrammedays: Past days in BBC Sounds catalog listing. This controls how many days are listed in the station displays.

bbctitle: Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

Songcast Receiver parameters

sclogfilename: Log file name for sc2mpd (default stderr) The value must not be the same as the one used for upmpdcli (except if empty).

scloglevel: Log verbosity for sc2mpd.

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 setups. For 'alsa', make sure that user upmpdcli has permission to access the audio devices !

schttpport: Port used by sc2mpd for MPD to connect to. Used only for scplaymethod=mpd. sc2mpd only accepts connections from localhost.

scalsadevice: Alsa device used by sc2mpd for playing audio. Only used for scplaymethod=alsa. Use 'aplay -L' to see the possible values.

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 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.

scusempdvolume: Scale songcast stream based on mpd volume value Allow controlling the volume from the Control Point by scaling the stream according to the mpd volume value. Only works when scplaymethod is 'alsa'.

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.

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.

Songcast Sender parameters

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.

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.

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.

scsendermpdport: localhost port to be used by the auxiliary mpd.

scripts_dir: External sources script directory. Location for the scripts used to set up additional external sources. See the Songcast Sender support documentation page.

scscriptgracesecs: Grace period to wait for a script process to exit before it is forcely killed. In seconds. Default 2 S.

Installation from packages

The upmpdcli 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).

Building from source

Running upmpdcli on Android

We’ve had an adventurous user building and running upmpdcli on Android. The main gotcha seems to be that you will need to add the upmpdcli user to appropriate groups to allow it to open TCP sockets. See the issue entries for details.

Building upmpdcli on Linux

For building from source, you will need a C++ compiler with C++17 support, and the development packages for the supporting libraries: libcurl, libmicrohttpd, libmpdclient, and possibly expat, depending on configuration options.

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

Older releases of the packages used the GNU autotools for building. Newer releases (and current git code) use meson and ninja. The change releases were libnpupnp 6.1.2, libupnpp 0.26.3 and upmpdcli 1.8.10.

For now, we will describe both methods.

If you are using the source from the git repository, and if you extract an older tag you will also need the autoconf, automake, libtool trio. Use the autogen.sh script to set things up.

For current git code or newer releases, you need the meson and ninja utilities, which are quite probably packaged by your distribution.

You need to either clone 3 git repositories:

or download the release tar files from the the upmpdcli download page

The upmpdcli build has one optional target, which needs the installation of additional dependencies (the Qt development packages), for building the upmpdcli-config GUI configuration file editor. This is set with --enable-confgui when using the autotools build, or with -Dconfgui=true with the meson build.

Once the source is extracted, the procedure is standard for each of the three packages:

For the older autotools builds:

# Only for git source
sh autogen.sh

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

With meson:

meson setup --prefix /usr build
cd build
ninja
sudo meson install

Which you should apply first to the libnpupnp source, then to libupnpp, then to upmpdcli.

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

If it is started as root, upmpdcli will try to change its uid to user upmpdcli. 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 is no need for upmpdcli to be started by root, it can run as any user, but in this case, it will create its cache files in subdirectories the user home directory.

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.

Building OpenHome and sc2mpd

There are two parts in building sc2mpd:

Building the Openhome libraries
Building sc2mpd proper

First download a sc2mpd release or clone the sc2mpd Git repository.

Creating the the OpenHome source tree

Building the Openhome libraries is a bit of a black art for a number of reasons:

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.

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.

OpenHome source tree, the easy way

Download the tar file of the appropriately patched openhome code from the 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

cd /home/me
mkdir openhome
cd openhome
tar xf /path/to/openhome-sc2-20210305.tar.gz

OpenHome source tree, the complicated way

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:

cd sc2mpd
mkdir /my/place/for/openhome
sh ohbuild.sh -b /my/place/for/openhome

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.

Building sc2mpd

sc2mpd depends on a number of libraries, which are usually packaged on Linux, and which you need to install first:

The 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 libsamplerate library (libsamplerate0 on Debian, libsamplerate-devel for Fedora).
The libasound Alsa interface library (libasound2-dev on Debian, alsa-lib-devel for Fedora).

First build openhome. Change your current directory to the top of the sc2mpd source tree, then run:

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

Once OpenHome is built and the auxiliary library development packages are installed, build sc2mpd, using the following commands inside the sc2mpd directory (you only need the autogen part for a cloned git tree, not for a tar extraction):

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
cp $distdir/openhome-sc2-20180615.tar.gz sc2mpd_1.1.1.orig-openhome.tar.gz
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

Technical note: Streaming Services and UPnP

Streaming services like Qobuz or Highresaudio give access to a huge catalog of music through a WEB programming interface which may be also usable by programs other than their own applications.

Upmpdcli offered a gateway for quite a few of these services in the past. Unfortunately, changes in some of the service APIs have made it impossible to access them from an open-source application (e.g. Spotify), and only a few remain.

The only thing that the services interfaces have in common with UPnP is that most of them use HTTP to retrieve the audio stream (as a short-lived URL). Spotify was an exception, and used a specific protocol for streaming (this was finally deprecated in 2022).

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. In many cases, this is only feasible from a closed-source application, with an agreement with the service providers, to hide "secrets" inside the app.

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 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, 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).
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 implemented by the Linn Kazoo Control Point, and a number of Renderers, the Linn and Lumin ones of course, but also, lately by upmpdcli.
- At the moment, the upmpdcli implementation only works for Qobuz, as changes in the Tidal access method have made it impossible to support.

Accessing Qobuz with OpenHome from Kazoo

This implements the OpenHome Credentials service and only works for Qobuz at the moment (it may work for Tidal if you have found an API token or appid/secret pair, but I can’t test this). The corresponding media server module must be installed (upmpdcli-qobuz), but no other configuration should be necessary on the renderer.

This should also work with Lumin devices, 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 disable it: ‘lumincompat’. Set to 1 to use upmpdcli v1.3.0 with Lumin.

Upmpdcli uses the openssl command to perform the cryptography work. This was not made a hard dependency, so you should check that it is installed.

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 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.

Annex: Songcast installation walkthrough

If you want to play from a Mac or Windows machine, install the Songcast application

Note

Not all 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.).

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 this superuser.com question for detailed explanations). This seems to be dependent 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 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 the 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:

friendlyname
audio synchronization issues and sc2mpd configuration.

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).

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.

Based on the same mechanism (but quite different code inside the script) there is also a nice HOWTO 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 /usr/share/upmpdcli/src_scripts, but it can be changed by setting the ohsrc_scripts_dir configuration variable inside /etc/upmpdcli.conf

For managing analog sources, entries inside the directory will typically be created as symbolic links to the sample script, which is installed as /usr/share/upmpdcli/Analog-Input. For doing other things, the scripts will not be links, but they must still be named a bit specially.

The scripts (or links) must be named like SourceType-SourceName, where SourceType MUST BE one of Analog, Digital, or Hdmi, (which are all the same, and for display purpose only), and you can choose SourceName as you wish, but it should contain no space characters.

The Source will appear with type Analog, Digital or Hdmi and name SourceName in an OpenHome Source select dialog (e.g from upplay).

The Analog-Input sample script has provisions for reading the device name 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.

Annex: the radio scripts

The radio URL script

The url field inside the radio definition can be a direct audio link or a 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

If set, artScript is the path to an executable script which can retrieve 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. Radio Paradise) publish the album art for the currently playing title. The details vary. The artScript parameter, if set, should point to an 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, which may not be the case for your home. /usr/local/bin is your 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).

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

There is no reason to have an artScript if metaScript exists for the radio. metaScript can also return the image URL.

The dynamic metadata script

If set, metaScript is the path to an executable script which can retrieve 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
}

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

Any value not present will simply not be used (not an error). audioUrl is 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 ('radio-paradise-get-flac.py'). Both need the Python3 'requests' package to be installed.

Annex: command line and environment

In most situations, upmpdcli will be run as follows:

upmpdcli -c /etc/upmpdcli.conf

The -c option specifies a configuration file.

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

Some of the essential configuration parameters can be set either 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.

As of upmpdcli 1.6.0 all configuration variables can be set through the environment instead of as a configuration file entry. The set of variables which can also be set from the command line is unchanged. In case of multiple settings, the precedence is as above (command line, configuration file, environment).

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 or (1.6) $UPMPD_MPDHOST

mpdhost

TCP port for MPD

-p mpdport

$UPMPD_PORT or (1.6) $UPMPD_MPDPORT

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

(1.6) $UPMPD_LOGFILENAME

logfilename

Verbosity level (0-4)

-l loglevel

(1.6) $UPMPD_LOGLEVEL

loglevel

UPnP network interface

-i iface

$UPMPD_UPNPIFACE

upnpiface

UPnP port

-P port

$UPMPD_UPNPPORT

upnpport

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 '/usr/share/upmpdcli/upmpdcli.conf-xml').

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.

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 Bottle Python Web Framework and it only depends on Python 3.

You can use the scweb-standalone.py script to manually start the interface:

python3 ./scweb-standalone.py

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):

python3 ./scweb-standalone.py -a 0.0.0.0

-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.