--- a/doc/sc2mpd.txt
+++ b/doc/sc2mpd.txt
@@ -4,89 +4,131 @@
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
+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.
-*NEW: Debian packages for sc2mpd:* as the procedure for building sc2mpd is
-not completely obvious and automatic, I have also added *sc2mpd* packages
-to the *upmpdcli* Debian repository. Packages exist for architectures i386,
-amd64 and Raspberry Pi. You can follow the procedure on the
-link:downloads.html[upmpdcli download page] to add the repository, then
-just use the following to install sc2mpd:
-
- sudo apt-get install sc2mpd
-
-NOTE: For rebuilding from the source package: the installed binary has a
-static link to the OpenHome libraries. This means that, in order to rebuild
-from the source package, you need to follow the normal procedure to build
-the OpenHome libs first (see the ohbuild.sh script further down). The build
-tree should be located under /opt/openhome for the package rebuild to work.
-
+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.
-There are two types of entities involved in the protocol:
-
- - A *Songcast* _Sender_ generates an audio stream.
- - A *Songcast* _Receiver_, which typically runs on an OpenHome Renderer,
- receives the stream and plays it.
-
-The streams transported by *Songcast* are actual real-time audio data, which
-can go straight to an audio card for playing.
+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.
-
-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
-(this is the main purpose of the *Songcast* Mac and Windows applications,
-apart from actually controlling the audio destination).
-
-Any application on the desktop will (be compelled to) transparently play to
-the remote device, without need to know anything about *Songcast*.
+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, with the addition of an HTTP interface (based
-on _libmicrohttpd_) to forward the data to *mpd*.
-
-Setting up a connection happens as follows:
+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. *_This only works with 16
+ bits sound for now (so only with a Windows sender, no Macs allowed)_*
+
+What approach is used is decided by a parameter in the upmpdcli
+configuration file: `scplaymethod` (see <<Configuration>> further)
-- 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
+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 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.
-
+ 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.
@@ -95,6 +137,18 @@
(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*.
@@ -103,16 +157,35 @@
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`.
+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.
+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
@@ -121,14 +194,20 @@
- 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).
-
+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
@@ -152,7 +231,8 @@
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).
+install the _libmicrohttpd_, _libsamplerate_ and _libasound_ runtimes
+though).
After restarting *upmpdcli*, it should advertise the _Receiver_ service and
appear in the Songcast Sender menus.