= sc2mpd: upmpdcli Songcast support

== Executive summary :-)

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)

The link:http://www.linn.co.uk/[Linn] *Songcast* protocol distributes an
audio stream on a local network so that multiple hosts (_Receivers_) can
play quasi-synchronously from a single source (_Sender_).

The audio source (Sender) can be a
link:http://www.linn.co.uk/software#songcast[Songcast application]
installed on a Windows or Mac host. This will allow capturing and
broadcasting the audio from *any* local application (e.g. Spotify, Qobuz,
Tidal, Windows Media Player etc.).

The audio source can also be a Unix/Linux host running *upmpdcli*/*sc2mpd*,
which is mostly useful for multiroom audio. This will also work for a line
input, so that you can distribute an analog source to multiple Receivers
over Songcast.

The _Receiver_ instances can be Unix/Linux hosts (possibly Rasberry Pi or
similar) with *upmpdcli*/*sc2mpd* installed, or ones running
link:https://github.com/PeteManchester/MediaPlayer[MediaPlayer], or actual
Linn hardware (and probably others I don't know of).

   
== Installing

If you want to play from a Mac or Windows machine, install the 
link:http://www.linn.co.uk/software#songcast[Songcast application]

NOTE: Not all Windows Songcast versions work well with upmpdcli. Lately
I've had good luck with
http://oss.linn.co.uk/Releases/Songcast/Davaar/Songcast_4.4.190_win.exe[4.4.190]
but not with the 4.5 ones (it's possible to get them to work with
*upmpdcli* from the *upplay* control panel, but the Windows app claims that
the *upmpdcli* receiver is unavailable.).

If the _Sender_ is a *upmpdcli* host, you should probably also install the
link:http://www.lesbonscomptes.com/upplay/[upplay] Control Point
somewhere. Recent upplay versions include a tool to control _Sender_ and
_Receiver_ instances. This is less necessary if the Sender is on Windows or
Mac, as the Songcast application on these platforms includes a limited
connection tool (no multiroom).

Download and install the *upmpdcli* and *sc2mpd* packages for your Linux
system. See
link:http://www.lesbonscomptes.com/upmpdcli/downloads.html#packages[the
download page here]. Also, link:#rpi_quick[Rasberry Pi quick install notes].

When using a single _Receiver_, things should just work, the _UpMpd_
_Receiver_ should appear in the Songcast app on the host (or in the *upplay*
control panel).

WARNING: There is *no software volume control* for the *upmpdcli* Songcast
Receivers for now: use either a local mixer or the little round things on
the pre-amps. Set the volume low when experimenting !

NOTE: The receiver side does not work too well on Raspberry Pis using an
USB DAC (as far as I could see). The reason may be that the data rate of
the uncompressed stream is just too much for the poor Pi Ethernet/USB
chip. Things work just fine with an I2S DAC (or on HDMI probably). When on
WIFI, the results are sometimes irregular too, depending on the quality of
the connection. If you have no Ethernet cabling, Ethernet over power lines
may work better than WIFI. The best combination of network and DAC link is
definitely Wired and I2S (or HDMI).

When using multiple _Receiver_ instances, you need to at least customize
their names, and you want to take care of synchronization issues. You will
need to take a look at a bit more documentation:

 - link:upmpdcli.html[upmpdcli documentation], look for _friendlyname_.
 - link:scmulti.html[audio synchronization issues and *sc2mpd*
   configuration].


[[SENDERRECEIVER]]
== Upmpdcli as Songcast Sender

Upmpdcli Sender mode allows you to broadcast the Playlist or Radio source
to other Songcast Receivers. The local host plays through its local Receiver
too, in order to achieve synchronisation. Unlike on Windows, the audio is
not captured from the driver, so that you won't be able to cast other
applications.

You can set *umpdcli* in _Sender_ mode from an OpenHome-capable Control
Point, by selecting the Source of type `Playlist`, name `PL-to-Songcast` or
type `Radio`, name `RD-to-Songcast`.

The *sc2mpd* configuration must be set to play directly to Alsa for the
`XX-to-Songcast` sources to appear. See the
link:sc2mpd.html#Configuration[configuration section], and
link:scmulti.html[the page about synchronisation].

Selecting the source can be done, for example, from the
link:http://www.lesbonscomptes.com/upplay/index.html[upplay]
`File`->`Select Source` menu entry.

When entering this mode, *upmpdcli* will start an auxiliary MPD process
(after stopping the main one), configured to send audio to the *mpd2sc*
OpenHome _Sender_ process. It will then also start its own Songcast
_Receiver_ mode, transfer the playlist, stop the main MPD and start the
auxiliary one...

The resulting state is that the *upmpdcli* instance can be managed in
Playlist mode from the Control Point. The audio is played locally through
the Songcast _Receiver_. Other _Receivers_ can be connected and will play
in good synchronization.

image::upmpdcli-sender-receiver.png["Sender/Receiver mode"]

This looks complicated, but in practise, starting the mode and connecting
other Receivers from the `upplay` control panel is quite easy.

[[SENDERRECEIVER.EXTSOURCES]]
=== Managing external sources

In the `Sender` modes described above, `upmpdcli` (or rather its slave
MPD process) is the source of the audio stream.

It is also possible to set things up so that an external source (e.g. a
line in) can be connected to the Songcast Sender, allowing multiroom
playing of any external source. See the comments in the
link:https://github.com/medoc92/upmpdcli/blob/master/samplescripts/Analog-Input[sample script in the
upmpdcli source tree] for instructions about configuring this. The general
idea is that an external script, executed by *upmpdcli*, is responsible for
executing the piped source reader and Songcast Sender.


[[whatis_songcast]]
== More Details on 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 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 PCM 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_ UPnP 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
OpenHome open source implementation

*upmpdcli* can also manage a _Sender_ subsystem, which is implemented by
using a separate *mpd* instance sending audio to an *mpd2sc* command (part
of the *sc2mpd* package). The latter is a modified version of the OpenHome
WavSender sample program.

*sc2mpd* can play the *Songcast* 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.

.Upmpdcli _Receiver_ in `alsa` and `mpd` modes
[options="header"]
|=============
|`alsa`|`mpd`
|image:upmpdcli-receiver-alsa.png[Upmpdcli Receiver, alsa mode]|image:upmpdcli-receiver-mpd.png[Upmpdcli Receiver, mpd mode]
|=============

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 10&nbsp;S) between the time when Songcast is activated and
the time sound appears. 

NOTE: When using _`mpd`_, from a Mac (24 bits audio) you need *mpd 0.19*,
configured with `--disable-audiofile`, else you risk producing high volume
noise.  As Debian and Ubuntu tend to lag quite bit on MPD progresses, I
have set up link:downloads.html#mpd[backport repositories] for
appropriately configured recent mpd versions (currently 0.19.9), for
Ubuntu, Debian i386/amd64 and Raspbian.

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 and Jessie systems

There are packages available for Raspbian (armfh) and Debian i386
and amd64. These were generated on Wheezy (Debian 7) machines, but they
are also compatible with Jessie (Debian 8) systems.

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 see 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):

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.  

scplaymethod:: 
Used by *upmpdcli* and *sc2mpd*.  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.

sccvttype::
If the _`alsa`_ play method is used, this defines the libsamplerate
converter type. See http://www.mega-nerd.com/SRC/api_misc.html#Converters.
The default is to use SRC_CVT_FASTEST, resulting in around 24% CPU usage
for sc2mpd processing a 16 bits stream on a Raspberry Pi 1. The value can
be specified either as a string (e.g SRC_SINC_FASTEST), or a value (e.g 2).

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:: 
Used by *upmpdcli*. 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.

=== Parameters for the *upmpdcli* Sender


scsenderpath::
Path to the script which starts the auxiliary mpd and the sender
process. You should have no reason to change this.

scsendermpdport:: 
localhost port used by the auxiliary mpd process. Default: 6700.

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

Not all versions of Songcast work well with sc2mpd. Lately, I have had good
luck with 4.4.190, but not 4.5.298. You will find
http://oss.linn.co.uk/Releases/Songcast/Davaar/[all the Songcast installers
here]

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).

However, 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.

[[building]]
== 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]. 


=== Building the OpenHome libraries

Building the Openhome libraries is a bit of a black art for a number of
understandable reasons:

- There are no released distributions for the OpenHome libraries, but
  only a number of git repositories for the different components. The state
  of the repositories is not completely consistent at all times (there will
  be moments when a component will not build with another).
- The OpenHome build system is very complicated because it works on
  multiple platforms and multiple language bindings.

The *sc2mpd* source comes with a shell script named _ohbuild.sh_ to help
with this. It has several functions:

 - Cloning the OpenHome and checking out verified revisions
 - Applying a few minor patches to ensure that the build will work in a
   simplified environment (e.g. without a c# compiler).
 - Creating a tar file of a compact trimmed tree.
 - Running the build either from the cloned tree or the tar file.

The tar functions are mostly useful to help with building packages. For a
normal build, the procedure would be as follows:

    cd sc2mpd
    mkdir /my/place/for/openhome
    sh ohbuild.sh -b /my/place/for/openhome


=== Building sc2mpd

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

Once OpenHome is built and the auxiliary library development packages are
installed, 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.

==== Building a Debian package from an sc2mpd tar distribution

Here follows a synopsis of building a debian package for an sc2mpd tar
distribution. You'll need to replace the 1.1.1 and 20151223 versions with
whatever you are building. Note that the 1.1.1 value must match what you
have in the Debian changelog (or update the changelog).

The $distdir and $sc2mpd_src values stand for places where you store the tar
files and the sc2mpd (git) source tree.

    mkdir sc2mpd_build
    cd sc2mpd_build
    cp $distdir/sc2mpd-1.1.1.tar.gz sc2mpd_1.1.1.orig.tar.gz
    cp $distdir/openhome-sc2-20151223.tar.gz sc2mpd_1.1.1.orig-openhome.tar.gz
    tar xzf sc2mpd_1.1.1.orig.tar.gz
    cp -rp $sc2mpd_src/debian sc2mpd-1.1.1/
    cd sc2mpd-1.1.1
    mkdir openhome
    cd openhome
    tar xzf ../../sc2mpd_1.1.1.orig-openhome.tar.gz
    cd ..
    debuild