= Upmpdcli: MPD UPnP Renderer Front-End


*upmpdcli* is an UPnP Media Renderer front-end to *MPD*, the Music Player
Daemon. It supports both pure UPnP and the OpenHome ohMedia services.

In OpenHome mode, it supports radio streams.

It has the ability to interface to Linn Songcast for multiroom synchronized
playing either of audio captured on Windows or Mac OS X or of its own
stream.

As of version 1.2.0, the software includes a Media Server gateway to
cloud streaming music services.

[[upmpdcli.security]]
== Security

*upmpdcli* is not audited for security issues, and, as far as I
know, it may be full of exploitable bugs. Do not run it on an
Internet-facing host.

[[upmpdcli.audioformats]]
== Audio format support

The actual audio decoding and playing is performed by *MPD*, the Music
Player Daemon. In consequence, *upmpdcli* can accept most audio formats
supported by *MPD*, meaning about anything, including DSD.

Raw PCM streams are an exception though. 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). There is actually little reason to use raw PCM, and, for
example, WAV streams, which have an identification header, will be handled
just fine.

There is an exception: recent versions of upmpdcli do support audio/L16,
but only with the development version of MPD (0.20) and there are
conditions on the Media Server (it must output the audio formats parameters
with the MIME type). See this Github issue for more details:
https://github.com/medoc92/upmpdcli/issues/36#issuecomment-227761220

[[upmpdcli.streaming]]
== Streaming services support

Upmpdcli versions 1.2.0 and later offer support for accessing music on some
streaming services. You will need a valid account on the services you want
to use. The initial release supports Google Play Music, Qobuz and Tidal.


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 one for the upmpdcli instance, with "-mediaserver" appended.

Streaming is not limited to the local upmpdcli renderer, and the Media
Server should happily send music to other renderers.

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
link:https://github.com/tamland/kodi-tidal[Kodi Tidal add-on] and the
link:https://github.com/tamland/python-tidal[Tidal API], by Thomas
Amland (also using other useful modules by Thomas). I was able to reuse
most of the Kodi code.

The Tidal api module was recently updated and the login code comes from
link:https://github.com/arnesongit/kodi-tidal[this Git repository].

The software is not officially supported by Tidal, and may just stop to
work one day...

It only works with a valid Tidal subscription.

The configuration parameters are described
link:#_tidal_streaming_service_parameters[further down]. 

=== Notes on the Qobuz interface

This is based on the service API from the
link:https://github.com/tidalf/plugin.audio.qobuz[Kodi add-on], by Joachim
Basmaison and Cyril Leclerc, with the upper-level code adapted from the
Tidal add-on.

The WEB API is not officially supported by Qobuz, and may just stop to work
one day.

You need a valid Qobuz subscription.

Qobuz search does not allow specifying what field to search (e.g. are we
searching artist names or track titles). This is a bad match with UPnP
searches supported by upmpdcli and results in a weird interface and mixed
up results.

The configuration parameters are described
link:#_qobuz_streaming_service_parameters[further down]. 

[[upmpdcli.googlemusicnotes]]
=== Notes on the Google Music interface

This is based on the
link:https://github.com/simon-weber/gmusicapi[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. 
link:http://unofficial-google-music-api.readthedocs.io/en/latest/usage.html#usage[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.

The configuration parameters are described 
link:#_google_music_streaming_service_parameters[further down].


[[upmpdcli.config]]
== Configuration

See the man page for command line details. 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.

The 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. A majority of parameters can only be set in the configuration file.

The configuration file has a simple `name = value` format.

All parameters have defaults, and a typical installation will need no
customisation at all. If several instances of *upmpdcli* run on the same
network, you will want to give them distinct names (_friendlyname_
parameter). The other parameters are only useful in special situations.

The following parameters can be set by several methods. The parameters
which can only be set in the configuration file are described further down.

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


In addition to the above basic parameters, many configuration variables can
be set in the configuration file.

[[upmpdcli.configfile]]
include::upmpdcli-config.txt[]

[[radio-definitions]]
=== Radio station definitions

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

The section name must begin with `radio`, the rest will be displayed as the
station name. `url` and `artUrl` designate the playlist or stream, and an
icon. `artUrl` is optional.

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


Some radios (e.g. radioparadise) publish the album art for the currently
playing title. The details vary. `artScript`, 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 radioparadise uri (as long as they don't change their format,
a proper approach would use an xml parser of course):

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

[[upmpdcli.songcast]]
== Songcast integration

upmpdcli recent versions support Songcast, only when the sc2mpd extension
package is installed. See the link:sc2mpd.html[description here]. upmpdcli
can act both as a Receiver (playing audio from, e.g., a Windows system),
and as a Sender (for distributing synchronized audio to multiple players).

NOTE: (You can ignore this if you are not installing the Songcast
complements, especially the Sender part). If you do install them, 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 is playing (e.g. Skype phone
conversations are out of reach).


[[upmpdcli.boot]]
== 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.

[[upmpdcli.building]]
== Building

For building from source, you will need a recent `C++` compiler (`C++11`),
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's only needed at
run time). Also gmusicapi for Google Music.

If you are using the source from Github, 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 github repositories:
https://github.com/medoc92/libupnpp and
https://github.com/medoc92/upmpdcli,
or download the release tar files from the the
link:downloads.html[download area]

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/`