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

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

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


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

----
[radio Radio Teddy]
url = http://opml.radiotime.com/Tune.ashx?id=s80044
artUrl = http://cdn-radiotime-logos.tunein.com/s80044q.png
----

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.

You can also define the radio stations in a separate file by setting the
'radiolist' parameter in the main configuration.

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

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