--- a/doc/scmulti.html
+++ b/doc/scmulti.html
@@ -740,46 +740,20 @@
<h1>Managing multiroom audio with Linn Songcast and upmpdcli</h1>
</div>
<div id="content">
-<div class="sect1">
-<h2 id="_what_is_linn_songcast">What is Linn Songcast</h2>
+<div id="preamble">
<div class="sectionbody">
-<div class="paragraph"><p><strong>Songcast</strong> is a protocol for transporting audio streams across the network,
-developped by <a href="http://oss.linn.co.uk/trac/wiki/Songcast">Linn</a> as a
-series of open-source libraries and applications.</p></div>
-<div class="paragraph"><p>There are two types of entities involved in the protocol:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-A <strong>Songcast</strong> <em>Sender</em> generates an audio stream.
-</p>
-</li>
-<li>
-<p>
-A <strong>Songcast</strong> <em>Receiver</em>, which typically runs on an OpenHome Renderer,
- receives the stream and plays it.
-</p>
-</li>
-</ul></div>
-<div class="paragraph"><p>The streams transported by <strong>Songcast</strong> are actual real-time audio data, which
-can go straight to an audio card for playing.</p></div>
-<div class="paragraph"><p>Controlling the streams (connecting, starting, stopping) is
-done through an UPnP service named OpenHome <em>Receiver</em>, which runs on an
-UPnP Media Renderer implementing the OpenHome services.</p></div>
-<div class="paragraph"><p>The typical use of <strong>Songcast</strong> is to have an audio driver on a Windows or OS X
-desktop capture and forward the audio stream to a remote <strong>Songcast</strong> device
-(this is the main purpose of the <strong>Songcast</strong> Mac and Windows applications,
-apart from actually controlling the audio destination).</p></div>
-<div class="paragraph"><p>Any application on the desktop will (be compelled to) transparently play to
-the remote device, without need to know anything about <strong>Songcast</strong>.</p></div>
+<div class="paragraph"><p>General information about <strong>upmpdcli</strong> support for <strong>Songcast</strong> can be found
+<a href="sc2mpd.html">here</a>. This page explains how to set up a multiroom
+synchronized audio system using <strong>upmpdcli</strong> and <strong>Songcast</strong>.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_multiple_receivers">Multiple Receivers</h2>
<div class="sectionbody">
-<div class="paragraph"><p>Multiple <em>Receiver</em> hosts can connect to the same <em>Sender</em>, so that they
-will all be playing the same audio.</p></div>
-<div class="paragraph"><p>The Mac and Windows <strong>Songcast</strong> apps only let you connect the <em>Sender</em> to one
-Receiver though.</p></div>
+<div class="paragraph"><p>Multiple <strong>Songcast</strong> <em>Receiver</em> hosts can connect to the same <em>Sender</em>, so
+that they will all be playing the same audio.</p></div>
+<div class="paragraph"><p>The Mac and Windows <strong>Songcast</strong> apps only let you activate one
+<em>Receiver</em> though.</p></div>
<div class="paragraph"><p><strong>upmpdcli</strong> now includes a small application which can list the state of
the local <strong>Songcast</strong> Receivers, make a Receiver play from the same URI as
another one (for building multiroom groups), or return a Media Renderer
@@ -791,89 +765,79 @@
<div class="paragraph"><p>This has only be tested with <strong>upmpdcli</strong> and its <a href="sc2mpd.html">sc2mpd</a>
<strong>Songcast</strong> auxiliary process as Receiver implementation, but I’d guess that
there is a good chance it would work with others.</p></div>
-<div class="paragraph"><p>This is very preliminary for now and there are a number of issues, I hope
-to improve them, but for now, this is definitely an <em>early adopters</em> system:</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_synchronisation_issues">Synchronisation issues</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>The short version is: all sc2mpd instances must be configured to play
+directly to Alsa. See the <a href="sc2mpd.html#Configuration">configuration
+section</a>.</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>The only way to control this is to adjust the rate of reproduction on the
+Receiver, which can be done in two ways:</p></div>
<div class="ulist"><ul>
<li>
<p>
-The initial synchronisation when forming the group is very bad. To
- resynchronize everything, stop or pause the playing on the PC (from the
- player, e.g. Media Player, not from the Songcast utility), wait for the
- audio to drain, and a few seconds more, then restart playing.
+Linn hardware uses timestamps embedded in the audio stream to adjust
+ their hardware sample clock.
</p>
</li>
<li>
<p>
-Receivers slowly drift out of sync, especially if they use different
- hardware. I intend to work on this, but it’s a difficult issue.
+sc2mpd in Alsa mode uses sample rate conversion to adjust the stream.
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>This is not specific to Songcast of course, all real time audio network
+transports have to do something similar.</p></div>
+<div class="paragraph"><p>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.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_setting_things_up">Setting things up</h2>
+<div class="sectionbody">
+<div class="ulist"><ul>
+<li>
+<p>
+Install upmpdcli and sc2mpd on each of the <em>Receiver</em> systems. Edit
+ <tt>/etc/upmpdcli.conf</tt> to set:
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+<tt>friendlyname</tt>, this is quite useful when managing several systems.
</p>
</li>
<li>
<p>
-It’s quite easy to put the system in a confused state where nothing
- seems to work any more. Stopping all Receivers (with <strong>scctl</strong> or the Web
- interface) and restarting the PC will normally get things back to
- sanity, but it will sometimes be necessary to restart everything.
- <strong>Always give the commands a little time to take effect</strong>. Especially,
- it’s quite common that the audio will not begin to play for around
- 10 S after activation from the <strong>Songcast</strong> PC interface. Clicking on
- stuff too early is the surest way to get into bad states, always give
- 10 S to the system when things seem to not be happening.
+<tt>scplaymethod</tt> = alsa
</p>
</li>
<li>
<p>
-<em>The following problem seems to be gone from the latest <strong>Songcast</strong>
- code</em> (which is used by the current <tt>ohbuild.sh</tt> script). Songcast can
- be transported by either unicast or multicast IP. multicast is of
- course much better for the network load, but I seem to have seen random
- <strong>sc2mpd</strong> crashes with it. I am not sure of the cause (may be not linked
- to multicast at all), but if you experience random <strong>sc2mpd</strong> crashes,
- switch <strong>Songcast</strong> to unicast (in the PC Songcast app advanced
- configuration panel. Unicast is the default).
+<tt>scalsadevice</tt>: use <tt>aplay -L</tt> to chose an appropriate device.
</p>
</li>
</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_setting_things_up">Setting things up</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The following seems to work for me:</p></div>
-<div class="ulist"><ul>
-<li>
-<p>
-Remove libupnpp and upmpdcli packages from the system to avoid confusion
-</p>
</li>
<li>
<p>
-Clone the libupnpp, upmpdcli and sc2mpd repositories from
- <a href="https://github.com/">GitHub</a>
-</p>
-</li>
-<li>
-<p>
-Follow the usual procedure to build. This should just be the usual for
- libupnpp and upmpdcli:
-</p>
-<div class="literalblock">
-<div class="content">
-<pre><tt>sh autogen.sh
-./configure --prefix=/usr
-make
-sudo make install</tt></pre>
-</div></div>
-</li>
-<li>
-<p>
-For sc2mpd, things are a small bit more complicated, see the <em>Building
- sc2mpd</em> section in <a href="sc2mpd.html">this document</a>.
-</p>
-</li>
-<li>
-<p>
-Repeat the above steps on all the machines which you want to be Receivers.
+Activate the web interface on one of the Receivers (or on any machine
+ with upmpdcli installed actually). Edit <tt>/etc/default/scweb</tt> to
+ configure the interface (see comments in there) and start it with
+ <tt>/etc/init.d/scweb-service start</tt>.
</p>
</li>
<li>
@@ -884,13 +848,8 @@
</li>
<li>
<p>
-Use either <strong>scctl</strong> (<tt>scctl -h</tt> prints a simple help message), or the Web
- interface (see further) to associate other Receivers to the same Sender.
-</p>
-</li>
-<li>
-<p>
-Stop or Pause the music. Wait 10 S, restart. <strong><em>Multiroom !</em></strong>
+Connect to the Web interface (host and port chosen above) with a
+ browser, and use it to list, activate, or disconnect the Receivers.
</p>
</li>
</ul></div>
@@ -901,17 +860,12 @@
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"l Receiver from outside the PC <strong>Songcast</strong> interface,
+the state of the "PC"'s Receiver from outside the PC <strong>Songcast</strong> interface,
this can only confuse things.</p></div>
-<div class="paragraph"><p>Every time you change the group configuration, you need to resynchronize
-the audio by pausing, waiting, restarting.</p></div>
-<div class="paragraph"><p>I do know that the whole thing is not very solid, this is a prototype and I
-hope to improve some of the issues in the future: constructive problem
-reports are more than welcome, but no flaming (for now) please :)</p></div>
</div>
</div>
<div class="sect1">
-<h2 id="_controlling_the_songcast_groups_from_the_web_interface">Controlling the Songcast groups from the Web interface</h2>
+<h2 id="_more_detail_about_the_web_interface">More detail about the Web interface</h2>
<div class="sectionbody">
<div class="paragraph"><p>To avoid having to access the command line interface to control the
<strong>Songcast</strong> groups, <strong>upmpdcli</strong> comes with a small Web server which uses
@@ -921,16 +875,16 @@
<a href="http://bottlepy.org/docs/dev/index.html">Bottle Python Web Framework</a>
and it only depends on Python (version 2 and 3 are supported by <strong>Bottle</strong>,
but the current app only works with Python 2).</p></div>
-<div class="paragraph"><p>I’ll find ways to autostart the server in the future, but for now,
-use the <tt>scweb-standalone.py</tt> script to manually start it:</p></div>
+<div class="paragraph"><p>You can use the <tt>scweb-standalone.py</tt> script to manually start the
+interface:</p></div>
<div class="literalblock">
<div class="content">
<pre><tt>python2 ./scweb-standalone.py</tt></pre>
</div></div>
-<div class="paragraph"><p>This will start a server on localhost, on port 8777 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):</p></div>
+<div class="paragraph"><p>This will start a server on localhost, on port 8780 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):</p></div>
<div class="literalblock">
<div class="content">
<pre><tt>python2 ./scweb-standalone.py -a 0.0.0.0</tt></pre>
@@ -944,7 +898,7 @@
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
-Last updated 2015-04-29 14:50:56 CEST
+Last updated 2015-05-06 10:18:31 CEST
</div>
</div>
</body>