= 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.
[[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 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. Some less common parameters can only be set in the configuration file.
All parameters have defaults, and a typical installation needs no
modification of the configuration file. 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:
|========================
|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
|*MPD* password|||mpdpassword
|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
|UPnP network interface|-i iface|$UPMPD_UPNPIFACE|upnpiface
|UPnP IP address (if interface not set)|||upnpip
|UPnP port|-p port|$UPMPD_UPNPPORT|upnpport
|UPnP AV support switch|||upnpav
|OpenHome support switch|-O 0/1||openhome
|OpenHome playlist disk persistence (default 1)|||ohmetapersist
|Directory for cached data (/var/cache/upmpdcli or ~/.cache/upmpdcli)|||cachedir
|Path to icon to be displayed by control point. <<upmpdcli.iconpathnote,See
note>>|||iconpath
|Path to HTML file to be used as presentation
page. <<upmpdcli.presentationnote,See note>>|||presentationhtml
|Run a command (or shell script) when a play action is performed. The difference
to onplay is that onstart is called *before* playback is about to begin.|||
onstart
|Run a command (or shell script) when MPD playback is about to begin. Note that
onstart is also called if MPD is controlled from another tool, e.g. by mpc.|||
onplay
|Run a command (or shell script) when MPD playback is about to end. Note that
onstart is also called if MPD is controlled from another tool, e.g. by mpc.|||
onstop
|Run a command (or shell script) when volume is changed.|||onvolumechange
|===========================
[[upmpdcli.iconpathnote]]
*iconpath* note: 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.
[[upmpdcli.presentationnote]]
*presentationhtml* note: 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).
[[upmpdcli.openhome]]
== OpenHome ohMedia services
The support for ohMedia services (play queue managed by the player instead
of on the control point) is activated by default as of release 0.8.0, only
an explicit option will turn it off.
The previous version default was set to _off_ in the software, and _on_ in
the configuration file. As the configuration file is not usually
overwritten during an upgrade, if you are upgrading to 0.7.x from an
earlier version and you want to enable the services, you need to set the
option in the configuration file.
=== OpenHome Radio service
Recent Upmpdcli versions (after 0.13) implement an OpenHome Radio service
which allows selecting and listening to internet radio stations. The
stations are defined at the end of the configuration file in the following
way:
----
[radio The name of the radio]
url = http//www.myradio.com/path/to/the/playlist.pls
artUrl = http//www.myradio.com/path/to/the/icon.png
----
`artUrl` is optional. None of the non-radio parameters can be defined after
the first `[radio ...]` section (they would not be found).
The default config file contains a bunch of radio entries, copied from the
radiotray app. Replace with your own !
[[upmpdcli.songcast]]
== Songcast integration
upmpdcli recent versions support Songcast, only when the sc2mpd extension
package is installed. See the link:sc2mpd.html[description here].
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/`