Introduction

Upmpdcli is primarily an UPnP Renderer front-end to the MPD music player. It has a number of additional or alternative functions.

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.

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 (my main one is 25 years old).

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

Network Audio Elements
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. 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 supplies free audio capture drivers functionning as Songcast Senders, for MS-Windows and Mac OS X. This enables playing the audio of any application (Windows Media Player, Spotify, Tidal, etc.) onto one or several Songcast Receivers, without any need for the applications to know about Songcast.

Gapless ?

This is a relatively small issue, but people are very sensitive to it, it is important from some music pieces (Goldberg variations with gaps: not nice) and you will hear about it all the time if you read forums, so, a 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 SetNextTransportURI).

Upmpdcli overview

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

The Grand Scheme of Things
Figure 2. The Grand Upmpdcli Scheme of Things

Additionally:

  • 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 provides a Media Server interface, currently used for accessing external streaming services (Qobuz, Tidal, Google Music). A local media server is in the early planning phase, the motivation being that I find none which is both open-source and really satisfying (MinimServer is great but not open-source).

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

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

However, a majority of parameters can only be set in the configuration file, which is designated with the -c command line option. The usual path is /etc/upmpdcli.conf

The configuration file has a simple name = value format.

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 station definitions

Upmpdcli versions after 0.13 implement an OpenHome Radio service which allows selecting and listening to internet radio stations.

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

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.

Radio channels can be accessed by selecting the Radio Source from an OpenHome Control Point.

Example entry:

[radio Radio Teddy]
url = http://opml.radiotime.com/Tune.ashx?id=s80044
artUrl = http://cdn-radiotime-logos.tunein.com/s80044q.png
artScript = /path/to/some/script
metaScript = /path/to/some/other/script

The section name must begin with radio, the rest will be displayed as the station name. The section has several possible entries. Only url is mandatory, it points to the playlist or stream.

If set, artUrl is a link to a static icon for the radio (displayed as album art).

If set, artScript is the path to an executable script which can retrieve the image for the currently playing title.

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. As a very rough example here follows a command which would retrieve the Radio Paradise URI (as long as they don’t change their format, a proper approach would use an XML parser of course):

curl --max-time 5 -s http://radioparadise.com/xml/now.xml | \
     grep '<coverart>' | sed -e 's/<coverart>//' -e 's!</coverart>!!'

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

If set, metaScript is the path to an executable script which can retrieve the metadata (possibly including art Url) for the currently playing title.

The script should output the metadata in JSON format. Example output (the newlines and blank space are just here for readability):

{
    "title":"The title of the current track",
    "artist":"The artist playing",
    "artUrl":"https://www.somesite.com/path/to/image.jpg",
    "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.

Complete exemple with metadata script:

[radio FIP (Paris)]
url = http://direct.fipradio.fr/live/fip-midfi.mp3
artUrl = http://www.fipradio.fr/sites/default/files/fip-quadri-filet.png
metaScript = /usr/local/bin/fip-paris-meta.rb

And the script (this one in Ruby, thanks to Jacques Distler):

#!/usr/bin/ruby
require 'net/http'
require 'json'

uri = URI('http://www.fipradio.fr/livemeta/7')
response = Net::HTTP.get(uri)
songs = JSON.parse(response)['steps'].values
now = Time.now
songs.each do |song|
  song_end = Time.at(song['end'])
  if (song['embedType'] == 'song' && song_end >= now && Time.at(song['start']) <= now)
    metadata = {'title' => song['title'].split.collect{|s| s.capitalize}.join(' '),
               'artist' => song['performers'].split.collect{|s| s.capitalize}.join(' '),
               'artUrl' => song['visual'],
               'reload' => (song_end - now + 1).to_i}
    puts JSON.generate(metadata)
    break
  end
end

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

Upmpdcli Songcast Control Point compatibility

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

Upmpdcli Senders can’t be used by Linn Kazoo (tested with release 4.11.226), the reason unknown, but neither Linn nor upmpdcli receivers can be linked to an upmpdcli Sender using Kazoo.

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

Upmpdcli 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

Upmpdcli Receiver

Upmpdcli Receiver

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.

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

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

Sender/Receiver mode

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 slave 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 syncrhronization, 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 independant, audio reproduction on the two systems will slowly drift. If nothing is done, after a time, the Receiver will have to skip samples or add a period of silence (depending if its clock is slower or faster), which is quite audible and ennoying, and will happen "from time to time", depending of how much the clocks differ.

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

  • Linn hardware uses timestamps embedded in the audio stream to adjust their hardware sample clock.

  • sc2mpd in alsa mode uses sample rate conversion to adjust the stream.

  • sc2mpd in mpd mode can’t do a thing about it.

This is not specific to Songcast of course, all real time audio network transports have to do something similar (e.g. Roon does individual stream adjustments on the server).

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

Upmpdcli Media Server: streaming services

The Media Server function in Upmpdcli (1.2.0 and later) gives access to external streaming services: Qobuz, Tidal, and Google Music at the moment.

You will need a valid account on any service that you want to use.

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

Streaming is not limited to the local Upmpdcli Renderer, and the Media Server will happily send music to other Renderers.

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.

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. This will be fixed, but for now, you should probably do it after setting the password: chmod 600 /etc/upmpdcli.conf Actually, it would quite probably be a good idea not to use the same account for your mail and music uses.
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.

Notes on the Tidal interface

Note

There seems to be problems when streaming Tidal lossless/FLAC streams, with the default MPD configuration. A preliminary and rather superficial enquiry seems to indicate that this is caused by too much buffering by MPD. Adding the following parameters to the MPD configuration file (/etc/mpd.conf) reduces the pre-fetch period from 20 S to 10 S and seems to fix the issues for me:

audio_buffer_size "2048"
buffer_before_play "20%"

The Tidal module code is is based on the Kodi Tidal add-on and the Tidal API, by Thomas Amland (also using other useful modules by Thomas). I was able to reuse most of the Kodi code. The Tidal api module was recently updated and the login code comes from this Git repository. The software is not officially supported by Tidal, and may just stop to work one day…

It only works with a valid Tidal subscription.

The configuration parameters are described in the configuration section

Notes on the Qobuz interface

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

The configuration parameters are described in the configuration section

Notes on the Google Music interface

This is based on the gmusicapi Python package by Simon Weber, with upper-level code from the Tidal Kodi add-on. As for the other services, the API used is not officially supported and may stop to work one day.

This requires the installation of the external gmusicapi Python package. See the installation notes here.

Note
gmusicapi needs Python 2.7.9 or better (e.g. the standard Python version on Ubuntu Trusty is too old). Older Python versions will crash.

You will need a valid subscription for most functions.

I’m a little lost in the different google authentication/sign-in methods, but if you are using two way authentication, there is apparently a way to make things work, using an app password.

The configuration parameters are described in the configuration section

Upmpdcli local Media Server: uprcl

The current (2017-04) upmpdcli code base includes a Media Server function for local music files, analog to MinimServer or ReadyMedia/MiniDLNA. The plugin module is named uprcl.

Why yet another Media Server ? MinimServer is great, and free, but not open-source. ReadyMedia is nice too, but audio file format support is incomplete (there was a patch for DSD but it was never merged apparently), I’ve always found it a bit clunky (for example: no incremental updates), and development does not seem very active.

The new upmpdcli Media Server is at most beta quality. It probably has even less format support than MiniDLNA… But it’s written in Python, and I have good hope that it can evolve faster.

Some features:

  • Mostly written in Python, except for the pieces shared with the streaming plugins: UPnP interface proper, and plugin management, which are C++, but should not need a lot of changes.

  • Tries to mimick the MinimServer tree view, which I find quite nice. We’re not quite there yet, many functions and niceties, and the customization capability are missing.

  • Uses Recoll and python-recoll (hence the uprcl name) for harvesting the metadata and searching. Recoll already had almost everything needed in this area, no development needed. It can perform incremental updates and file system monitoring.

  • Uses Python sqlite3 (on a memory DB) for the tags tree.

Installation and configuration: have a look at the configuration variables

Note
python-mutagen which is optional for default Recoll installations is required for uprcl (this is for the case where you install by hand, the package takes care of it).

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.

Upmpdcli configuration file reference

Upmpdcli general parameters

friendlyname

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

upnpav

Enable UPnP AV services (0/1). This is set by default, but it may useful to switch it off with some OpenHome Control Points which are too easily confused by the presence of UPnP AV services.

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.

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.

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.

pkgdatadir

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

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.

pidfile

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

Tidal streaming service parameters

tidaluser

Tidal user name. Your Tidal login name.

tidalpass

Tidal password. The password for your Tidal account.

tidalquality

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

Qobuz streaming service parameters

qobuzuser

Qobuz user name. Your Qobuz login name.

qobuzpass

Qobuz password. The password for your Qobuz account.

qobuzformatid

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

Google Music streaming service parameters

gmusicuser

Google Music user name. Your Google Music login name (probably a gmail address).

gmusicpass

Google Music password. The password for your Google Music account.

gmusicquality

Google Music stream quality. hi for mp3/320, med for mp3/160, low for mp3/128.

gmusicdeviceid

Google Music device id. Your system MAC address will be used by default, but this will count against the maximum count of registered devices for this account. You can set the gmusicdeviceid value to the device ID from a phone or tablet on which you also use Google Play Music.

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

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.

uprclhostport

HTTP host and ports for serving media files The Media Server HTTP server will run on this address and port, which will also be inserted on the URLs we produce. If the variable is not set, we will use port 9090 and the first non-loopback ipv4 address in "ip addr" output, which may be right or not. Example: 192.168.1.1:9090

uprclpaths

This is used to translate real path to ones relative to the HTTP server doc tree. It also performs a form of access control. If this is not set, uprcl will use a null translation for each of the uprclmediadirs entries.

uprclconfdir

Recoll index directory This is usually not defined and defaults to /var/cache/upmpdcli/uprcl

uprclautostart

Initialize uprcl as soon as upmpdcli starts This is useful because uprcl initialization can take quite some time so it is better not to wait for the first access. The general default is false for the autostart variables, so this is normally explicitely set to true.

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

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.

UPnP network parameters

upnpiface

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

upnpip

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

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.

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.

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 at the end of the the main file, or in an external file (or both). Using an external file can ease distribution to multiple machines. Either way, each radio station is defined as a section with a name beginning with radio, containing a mandatory URL parameter, and optional values. The part of the name after radio will be the displayed radio name (as album title).

  • artUrl: an optional static radio icon URL.

  • artScript: an optional script to retrieve an image for the current title

  • metaScript: an optional script to retrieve metadata for the current title.

  • preferScript: decide if values from script should override icy metadata See the section about radio station definitions for details about the scripts. Example:

[radio My Radio]
url = http://some.host/some/path.pls
artUrl = http://some.host/icon/path.png
artScript = /path/to/script/dynamic-art-getter
metaScript = /path/to/script/metadata-getter
preferScript = 1
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).

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.

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.

Songcast Sender parameters

scsenderpath

Path to the script (scmakempdsender) which starts the auxiliary mpd and the sender process. Empty and searched in PATH by default.

scstreamscaled

Decide if we 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

Location for the scripts used to set up additional external sources. See the Songcast Sender support documentation page.

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

Building libupnpp and upmpdcli

For building from source, you will need a C++ compiler with full C++11 support, and the development packages for libupnp version 1.6, libcurl, libmpdclient, and libexpat.

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

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

The libupnpp library, which used to be part of upmpdcli, has been separated, and you need to build it first.

So you need to either clone two git repositories: https://opensourceprojects.eu/p/libupnpp/code and https://opensourceprojects.eu/p/upmpdcli/code or download the release tar files from the the upmpdcli download page

Once the source is extracted, the procedure is standard and there are currently no specific configure options:

# Only for git source
sh autogen.sh
./configure --prefix=/usr --sysconfdir=/etc
make
sudo make install

Which you should apply first to the libupnpp source, 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

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

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

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

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

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.

Building the OpenHome libraries

Building the Openhome libraries is a bit of a black art for a number of understandable 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 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

Building sc2mpd

sc2mpd depends on a number of libraries:

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

Once OpenHome is built and the auxiliary library development packages are installed, build sc2mpd, using the following commands inside the sc2mpd directory:

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

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 dependant on the WIFI hardware (router/access points) used, so maybe you will have more luck than me.

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

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

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

If the Sender is a upmpdcli host, you should probably also install the 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:

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: command line and environment

In most situations, upmpdcli will be run as follows:

upmpdcli -D -c /etc/upmpdcli.conf

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

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

Some of the essential configuration parameters can be set from the command line, a configuration file, or the environment in this order of priority. It would be rather confusing to use a mix of methods, so you should probably chose one.

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

What

Command line

Environment

Config variable

Configuration file name

-c config

$UPMPD_CONFIG

Host name or IP address where MPD runs

-h mpdhost

$UPMPD_HOST

mpdhost

TCP port for MPD

-p mpdport

$UPMPD_PORT

mpdport

UPnP "friendly name" for the device. This gets displayed in network search results.

-f friendlyname

$UPMPD_FRIENDLYNAME

friendlyname

Log file name. Leave empty for stderr

-d logfilename

logfilename

Verbosity level (0-4)

-l loglevel

loglevel

UPnP network interface

-i iface

$UPMPD_UPNPIFACE

upnpiface

UPnP port

-P port

$UPMPD_UPNPPORT

upnpport

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 (version 2 and 3 are supported by Bottle, but the current app only works with Python 2).

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

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

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