--- a
+++ b/doc/upmpdcli.txt
@@ -0,0 +1,107 @@
+= 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.
+
+*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.
+
+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.
+
+_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.
+
+[[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.
+
+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`.
+
+This should make it reasonably easy to write an init script for the
+daemon. Such a script exists in the `debian` directory inside the source
+tree.
+
+[[upmpdcli.downloads]]
+== Source code, packages
+
+The source repository is on link:http://www.github.com/medoc92/upmpdcli[GitHub].
+
+See the link:http://www.lesbonscomptes.com/upmpdcli[home page] for pointers
+to releases and built packages.
+
+[[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
+