= 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 playing audio captured on Windows or Mac OS
X or for multiroom playing.

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


[[upmpdcli.configfile]]
== Configuration file

In addition of the above, the following variables can be set in the
configuration file:

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

ownqueue:: If this is set (on by default), we own the *MPD* queue and will
fearlessly clear it.

upnpip:: UPnP IP address to use (if `upnpiface` is not used to select an
interface).

upnpav:: Activate UPnP AV services. This is set by default, but it may be
useful to switch it off with some too easily confused OpenHome Control
Points.

openhome:: Activate OpenHome services. This is set by default and there is
little reason to turn this off.

ohmetapersist:: OpenHome playlist disk persistence (default 1), no reason
to turn it off.

cachedir:: Directory for cached data (`/var/cache/upmpdcli` or
`~/.cache/upmpdcli`).

iconpath:: Path to an icon to 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. The icon to use can be
set using the *iconpath* configuration file parameter. Due to current (and
probably permanent) *upmpdcli* limitations, the image file *must* be a
64x64 32 bits-per-pixel png file.

presentationhtml:: Path to an HTML file to be used as presentation page. The
file referenced by the path will only be read once when *upmpdcli* starts,
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).

onplay:: Command to run when MPD playback is about to begin. Note that
`onplay` is also called if MPD is controlled from another tool, e.g. by
`mpc`.

onstart:: Command to run when a play action is performed. The difference to
`onplay` is that `onstart` is called *before* playback is about to begin.

onstop:: Command to run when MPD playback is about to end. Note that
`onstop` is also called if MPD is controlled from another tool, e.g. by
`mpc`.

onvolumechange:: Command to run when sound volume is changed.


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


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