= Upmpdcli: an UPnP Renderer Front-End to the Music Player Daemon

[[upmpdcli.intro]]
== Introduction

*upmpdcli* is an UPnP Media Renderer front-end to *MPD*, the Music Player
Daemon. It turns *MPD* into an UPnP Media Renderer, supporting gapless
track transitions.

*upmpdcli* is open-source, free and licensed under the GPL. It is written
in C++ and uses the *libupnp* (1.6) and *libmpdclient* libraries.

The typical setup is a home network with:

- An UPnP media server (e.g. *Minidlna*, *Mediatomb*, or some commercial
  device).
- An UPnP control point (e.g. *Audionet* or *Bubble UPnP* running on a
  tablet or phone). 
- *MPD* running on some Linux device (e.g. Raspberry PI hooked up to your
  bedroom stereo). 
- *upmpdcli* running on any Linux computer on the network (the same as
  *MPD* or not). It will be discovered by the UPnP control point in a
  standard fashion.

image::upmpdcli.png["Basic flow", float="right"]

In this usage, *MPD* does not manage the audio files directly and its
configured music directory will typically be empty. It fetches them from
the Media Server through HTTP, using the *curl* input plugin, and does not
need a local tags database.

When used with an appropriate control point, the *upmpdcli*/*MPD*
combination supports gapless playback.

_What's the point ?_ If you are running an UPnP network with multiple
devices, you may prefer to use a single control application (UPnP-based)
for everything. *MPD* is a very capable and robust music-playing application,
which runs well on small computers (e.g. Raspberry PI or other "plug" type
computers). However it needs a specific control application.

*upmpdcli* lets you control your *MPD*-based players with your UPnP control
point.

== Configuration
[[upmpdcli.config]]

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 file has a simple `name = value` format.

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. 

The following parameters can be set:

|========================
|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
|Do we own the *MPD* queue and fearlessly clear it|-o 0/1||ownqueue
|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
|===========================    

[[upmpdcli.boot]]
== Boot time startup

*upmpdcli* will 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, and *libmpdclient*.

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.

Otherwise, the procedure is standard and there are currently no specific
configure options:

    configure --prefix=/usr
    make
    sudo make install