--- a
+++ b/doc/sc2mpd.txt
@@ -0,0 +1,139 @@
+= upmpdcli Linn Songcast integration
+
+The *upmdcli* UPnP front-end to MPD implements support for Linn Songcast with
+help from the *sc2mpd* auxiliary process.
+
+*_This has mostly been tested with 16 bits sound but a recent change seems
+to have fixed 24 bits sound, so this should be now usable for MACs. This
+needs mpd 0.19 on the renderer. Still be a bit careful as this is quite new
+and there is a risk of strange noises !_*
+
+*_Do not try 24 bits sound with MPD 0.18 !_* (or turn the volume very
+low...). Using Songcast from a Mac (24 bits audio) needs *mpd 0.19*,
+configured with `--disable-audiofile`.
+
+As Debian and Ubuntu tend to lag quite bit on MPD progresses, I have setup
+link:downloads.html#mpd[backport repositories] for recent mpd versions
+(currently 0.19.9), for Ubuntu, Debian i386/amd64 and Raspbian.
+
+== What is Songcast
+
+Songcast is a protocol for transporting audio streams across the
+network. This is independant from the UPnP framework which mostly deals
+with URLs and audio files (usually, but not necessarily, compressed).
+
+The streams transported by Songcast are actual real-time audio data, which
+can go straight to an audio card for playing.
+
+Controlling the streams on the renderer (connecting, starting, stopping) is
+done through an UPnP service named OpenHome _Receiver_.
+
+The typical use of Songcast is to have an audio driver on a Windows or OS X
+desktop capture and forward the audio stream to a remote Songcast device.
+
+Any application on the desktop will (be compelled to) transparently play to
+the remote device, without need to know anything about Songcast.
+
+== Implementation of Songcast support in upmpdcli
+
+*upmpdcli* implements the _Receiver_ service, and uses an auxiliary process
+(*sc2mpd*) for transporting the audio data. *sc2mpd* is a slight
+modification of the sample program which comes with the Linn Songcast
+open-source implementation, with the addition of an HTTP interface (based
+on _libmicrohttpd_) to forward the data to *mpd*.
+
+Setting up a connection happens as follows:
+
+- If it finds an executable *sc2mpd* command in the PATH when starting up,
+ *upmpdcli* advertises a _Receiver_ service.
+
+- The Songcast implementation from the desktop finds out about the
+ _Receiver_ through the normal UPnP mechanisms and can be instructed to
+ use it. It then tells the _Receiver_ in *upmpdcli* to start playing.
+
+- *upmdpcli* starts the *sc2mpd* process, which gets ready to receive data
+ through Songcast, and make it available through HTTP.
+
+- *upmpdcli* instructs *mpd* to play the URL for the *sc2mpd* output.
+
+There is currently a 10-12 S delay between the connection request and the
+moment the audio starts playing. This is not normal, but I could not find
+the reason for it, so it's an unavoidable inconvenience at the moment.
+
+== Configuration
+
+No configuration is necessary by default: if *sc2mpd* is present,
+*upmpdcli* will advertise the Songcast capability, and any host with a
+Songcast sender installed should be able to use it.
+
+However, you can set a number of values in the upmpdcli configuration file
+(you *must* set the *upmpdcli* `-c` option for *sc2mpd* to see them, the
+environment variable will not work):
+
+sclogfilename::
+Name of the file which will receive *sc2mpd* log messages. `stderr` by
+default. This _can't be_ the same file used by *upmpdcli*.
+
+scloglevel::
+Log verbosity.
+
+schttpport::
+
+HTTP port used by *mpd* to connect to *sc2mpd*. 8888 by default. This must
+be an available port on `localhost`, and it will only accept connections from
+`localhost`.
+
+sc2mpd::
+Path for the *sc2mpd* executable file (e.g. `/usr/local/bin/sc2mpd`). Only
+useful if *sc2mpd* was not installed to a location in the executable $PATH
+set for the init scripts. Typically only `/bin` and `/usr/bin` are in
+there.
+
+== Building sc2mpd
+
+There are two parts in building *sc2mpd*:
+
+- Building the Openhome libraries
+- Building *sc2mpd* proper
+
+First clone the *sc2mpd* Github repository:
+http://www.github.com/medoc92/sc2mpd.
+
+*sc2mpd* depends on the microhttpd library. Install the development and
+runtime packages which are currently named _libmicrohttpd-dev_ and
+_libmicrohttpd10_ on Debian-derived systems (use _libmicrohttpd_ and
+_libmicrohttpd-devel_ for Fedora).
+
+
+Building the Openhome libraries is a bit of a black art, and the *sc2mpd*
+source comes with an _ohbuild.sh_ script which will try to clone the
+Openhome Git repositories and build the libs:
+
+ cd sc2mpd
+ mkdir /my/place/for/openhome
+ sh ohbuild.sh /my/place/for/openhome
+
+Miscellaneous error messages will be displayed during the build. Hope for
+the best...
+
+
+When this is done, build *sc2mpd*, using the following commands inside the
+_sc2mpd_ directory:
+
+ sh autogen.sh
+ ./configure --prefix=/usr --with-openhome=/my/place/for/openhome
+ make
+ sudo make install
+
+The build uses static Openhome libraries, so you can move the executable to
+another machine without needing the Openhome directory (don't forget to
+install the _libmicrohttpd_ runtime though).
+
+After restarting *upmpdcli*, it should advertise the _Receiver_ service and
+appear in the Songcast Sender menus.
+
+== Miscellaneous remarks
+
+Songcast is probably best transported over a wired connection. If you are
+doing this over WIFI and experiencing glitches, the wireless is the first
+suspect.