= sc2mpd: helper for upmpdcli Songcast support

The *sc2mpd* auxiliary process implements part of Linn *Songcast* support
for the *upmdcli* UPnP MPD front-end. Specifically, it implements a
*Songcast* _Receiver_ service, managed by *upmpdcli*.

*_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.