= Managing multiroom audio with Linn Songcast and upmpdcli

General information about *upmpdcli* support for *Songcast* can be found
link:sc2mpd.html[here]. This page explains how to set up a multiroom
synchronized audio system using *upmpdcli* and *Songcast*.

NOTE: multicast and WIFI don't mix well in many cases. If you have
wireless Receivers experiencing sound drop issues, try selecting unicast in
the Songcast advanced configuration panel on the desktop.

== Multiple Receivers

Multiple *Songcast* _Receiver_ hosts can connect to the same _Sender_, so
that they will all be playing the same audio. 

The Mac and Windows *Songcast* apps only let you activate one _Receiver_.

The *upmpdcli* package now includes the *scctl* command line utility, which
can list the state of the local *Songcast* _Receivers_, make a _Receiver_
play from the same URI as another one (for building multi-room groups), or
return a _Media Renderer_ from _Receiver_ to normal operation.

As the Songcast application is only available on Windows or Mac desktops,
it would be inconvenient to have to access the Linux command line to
control the multi-room groups, and the *upmpdcli* package also includes a
small Web application which can be accessed from a desktop web browser to
control the groups.

This has only be tested with *upmpdcli* and its link:sc2mpd.html[sc2mpd]
*Songcast* auxiliary process as Receiver implementation, but I'd guess that
there is a good chance it would work with others.

== Synchronisation issues

The short version is: all *sc2mpd* instances must be configured to play
directly to Alsa. See the link:sc2mpd.html#Configuration[configuration
section].

Longer version: *Songcast* is a real-time audio stream. As the _Sender_ and
_Receiver_ sample clocks (the 44.1 or 48 KHz clocks) are independant, audio
reproduction on the two systems will slowly drift. If nothing is done,
after a time, the _Receiver_ will have to skip samples or add a period of
silence (depending if its clock is slower or faster), which is quite
audible and ennoying, and will happen "from time to time", depending of how
much the clocks differ.

The only way to control this is to adjust the rate of reproduction on the
_Receiver_, which can be done in two ways:

 - *Linn* hardware uses timestamps embedded in the audio stream to adjust
   their hardware sample clock.
 - *sc2mpd* in _`alsa`_ mode uses sample rate conversion to adjust the stream.

This is not specific to *Songcast* of course, all real time audio network
transports have to do something similar.

Independantly of the clock issue, all _Receivers_ should use approximately
the same amount of buffering for the audio to be reasonably synchronous
(with no more shifts than moving around would produce anyway). This is
impossible to achieve when going through mpd, and the second reason why
*sc2mpd* must be set in _`alsa`_ mode for multiroom setups. In _`mpd`_
mode, the _Receivers_ can be out of sync by several seconds.

== Setting things up

 - Install upmpdcli and sc2mpd on each of the _Receiver_ systems. Edit
   `/etc/upmpdcli.conf` to set:
   * `friendlyname`, this is quite useful when managing several systems.
   * `scplaymethod` = _`alsa`_
   * `scalsadevice`: use `aplay -L` to chose an appropriate device.

You can control the connections between senders and receivers either from
the *upplay* `File->Songcast Tool` menu, or from the local web tool. The
*upplay* approach is easier and recommended. We describe the web way here
because it is more complicated:

 - Activate the web interface on one of the _Receivers_ (or on any machine
   with upmpdcli installed actually). Edit `/etc/default/scweb` to
   configure the interface (see comments in there) and start it with
   `service scweb start`.

 - Activate a _Receiver_ from the PC *Songcast* interface. Play something and
   leave it playing.

 - Connect to the Web interface (host and port chosen above) with a
   browser, and use it to list, activate, or disconnect the _Receivers_.

Once the slave _Receivers_ are associated with the _Sender_, they should stay
in this state until you change it. So you can stop/start *Songcast* on the
PC, and they will usually just follow.

An "associated" _Receiver_ is just one which plays from the same URI, it
keeps no other relation to the "Master". Only one _Receiver_ is a bit special
because it is the one known from the PC, but there is no specific reason to
use it as Master, the Master is only used to get the URI. Avoid changing
the state of the "PC"'s _Receiver_ from outside the PC *Songcast* interface,
this can only confuse things.

== More detail about the Web interface

This is only useful if you have no machine to run *upplay* on. The *upplay
Songcast tool is easier to use than the web tool.

To avoid having to access the command line interface to control the
*Songcast* groups, *upmpdcli* comes with a small Web server which uses
*scctl* to actually do the work. This is found inside the `web/`
subdirectory inside the *upmpdcli* source tree.

The server is based on the 
link:http://bottlepy.org/docs/dev/index.html[Bottle Python Web Framework]
and it only depends on Python (version 2 and 3 are supported by *Bottle*,
but the current app only works with Python 2).

You can use the `scweb-standalone.py` script to manually start the
interface:
    
    python2 ./scweb-standalone.py

This will start a server on localhost, on port 8680 by default which is
good for testing, but not very useful. Use the -a 0.0.0.0 option to let the
server answer on all local addresses (or specify the address to use a
specific interface):

    python2 ./scweb-standalone.py -a 0.0.0.0

-p can be used to specify a port.

Once started, connecting to the server from any browser should hopefully
display a reasonably self-explanatory interface.

Recent *upmpdcli* packages install the web app as a service named
*scweb*. The service is not started by default though, you need to edit
`/etc/default/scweb`.