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

To use it, you need the
link:http://www.linn.co.uk/software#songcast[Linn Songcast application] 
installed on a Microsoft Windows or Apple Mac OS X PC. See
xref:whatis_songcast[further] for more explanations about what this does.

*sc2mpd* 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. 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 set up 
link:downloads.html#mpd[backport repositories] for recent mpd versions
(currently 0.19.9), for Ubuntu, Debian i386/amd64 and Raspbian.

And to conclude the misc warnings section: *there is no software volume
control* of the Songcast Receivers for now: use either a local mixer or the
little round things on the power amps.

There are Debian Wheezy *sc2mpd*
packages in the *upmpdcli* repository for i386, amd64 and Raspberry Pi
(Raspbian): see the link:downloads.html[upmpdcli download page], so you do
not need to build any software if you use these systems.

NOTE: you know what Songcast is and have a Rasberry PI which wants to play:
xref:rpi_quick[quick install for the Raspberry PI]  (also works for i386
and amd64 Debian Wheezy).

[[whatis_songcast]]
== What is Linn Songcast

*Songcast* is a protocol for transporting audio streams across the network,
developped by link:http://oss.linn.co.uk/trac/wiki/Songcast[Linn] as a
series of open-source libraries and applications.

The protocol links two types of entities:

 - A *Songcast* _Sender_ generates an audio stream (Windows or Mac).
 - *Songcast* _Receivers_ receive and play the stream.

There are *Songcast* applications (_Senders_) for Windows and Mac OS X
(nothing for Linux, iOS or Android for now). The *Songcast* application
captures and forward the system audio stream to a remote *Songcast*
_Receiver_.

*Any* application on the desktop (Windows Media Player, Spotify, Tidal,
etc.) will transparently play to the remote device, without any need to
know about *Songcast*. *_Any_* audio service available on Windows or the
Mac can be forwarded to one or link:scmulti.html[many] audio players around
the house.

The *Songcast* streams are real-time audio data, which can go straight
to an audio card for playing.

Controlling the streams (connecting, starting, stopping) is
done through an UPnP service named OpenHome __Receiver__, which runs on an
UPnP Media Renderer implementing the OpenHome services (e.g. *upmpdcli*).


== 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

*sc2mpd* can play the audio stream in two modes:

 - By offering a local HTTP interface (based on _libmicrohttpd_) from which
   *mpd* will play the stream.
 - By directly using the *alsa* audio driver.

What approach is used is decided by a parameter in the upmpdcli
configuration file: `scplaymethod` (see <<Configuration>> further)
 
Control:

- If *upmpdcli* finds an executable *sc2mpd* command in the PATH when
  starting up, it advertises a _Receiver_ service.

- The *Songcast* application on 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 either play it directly or make it available
  through HTTP.

- If the _`mpd`_ method is in use, *upmpdcli* instructs *mpd* to play the
  URL for the *sc2mpd* output.

When using _`mpd`_ more bufferisation occurs and there may be a significant
delay (up to around 10S) between the time when Songcast is activated and
the time sound appears. 

Given the bufferisation and delay control issues when going through MPD,
only the _`alsa`_ method is usable in multi-room configurations. Even with a
single player, the _`mpd`_ method will experience skips from time to
time. The reasons are explained in the link:scmulti.html[multi-room]
page.


[[rpi_quick]]
== Quick install for Debian Wheezy systems

There are packages available for Raspbian and Debian Wheezy i386 and amd64.

So add the repositories:

    echo deb http://www.lesbonscomptes.com/upmpdcli/downloads/debian/ unstable main | sudo tee /etc/apt/sources.list.d/upmpdcli.list 
    echo deb-src http://www.lesbonscomptes.com/upmpdcli/downloads/debian/ unstable main | sudo tee -a /etc/apt/sources.list.d/upmpdcli.list 
    echo deb http://www.lesbonscomptes.com/upmpdcli/downloads/mpd-debian/ unstable main  | sudo tee -a /etc/apt/sources.list.d/upmpdcli.list 
    echo deb-src http://www.lesbonscomptes.com/upmpdcli/downloads/mpd-debian/ unstable main  | sudo tee -a /etc/apt/sources.list.d/upmpdcli.list 

Install (the mpd and libupnp versions in the repo have bug fixes):

    sudo apt-get update 
    sudo apt-get install upmpdcli sc2mpd mpd libupnp6

And seed the next section for configuring.

[[Configuration]]
== Configuration

=== On the Receiver side
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):

scplaymethod:: 
This decides how audio is played, with 2 possible
values, _`alsa`_ or _`mpd`_. Using _`mpd`_ is somewhat easier, but
unusable in link:scmulti.html[multi-room] configurations, and you risk
small drops even in single-player settings.

scalsadevice:: 
If the _`alsa`_ method is set, the `scalsadevice`
parameter defines the interface name. Use `aplay -L` to find the
appropriate name. Also check that user _`upmpdcli`_ belongs to the
_`audio`_ group.

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:: 
If the _`mpd`_ method is set, this defines the HTTP port used by *mpd* to
connect to *sc2mpd*. 8768 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. This allows *upmpdcli* to find *sc2mpd* if it is not in the standard
location.

=== On the Sender (Windows/Mac) side

I could not get IP multicast to work with WIFI Receivers (the sound drops
constantly).

There are well-known problems with multicast and WIFI (see for example
http://superuser.com/questions/730288/why-do-some-wifi-routers-block-multicast-packets-going-from-wired-to-wireless[this
superuser.com question] 
for detailed explanations). This seems to be dependant on the WIFI hardware
(router/access points) used, so maybe you will have more luck than me.

If some of your Receivers use WIFI, and you experience sound issues, check
that "Unicast" is selected in the Songcast configuration "advanced" panel
on the desktop.

Under most conditions, WIFI data rates should be more than sufficient to
transport Songcast streams (a bit over 1 Mbit/S for 48k/24bits, 700 Kbits/S
for 44.1k/16 bits).

== Building sc2mpd

There are two parts in building *sc2mpd*:

- Building the Openhome libraries
- Building *sc2mpd* proper

First download a
link:http://www.lesbonscomptes.com/upmpdcli/downloads.html[*sc2mpd*
release] or clone the *sc2mpd*
link:http://www.github.com/medoc92/sc2mpd[Github repository]. 

*sc2mpd* depends on a number of libraries:

- The link:http://www.gnu.org/software/libmicrohttpd/[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).
- The link:http://www.mega-nerd.com/SRC/[libsamplerate]
  library. _libsamplerate0_ on debian-derived systems.
- The *libasound* Alsa interface library (_libasound2_).

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_, _libsamplerate_ and _libasound_ runtimes
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.