sc2mpd / Code / Diff of /doc/sc2mpd.html

Diff of /doc/sc2mpd.html [fae4bf] .. [882899]

Switch to unified view

-a/doc/sc2mpd.html
+b/doc/sc2mpd.html
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
 <head>
 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
-<meta name="generator" content="AsciiDoc 8.6.7" />
+<meta name="generator" content="AsciiDoc 8.6.9" />
 <title>sc2mpd: helper for upmpdcli Songcast support</title>
 <style type="text/css">
 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */
 /* Default font. */
 ...
   margin-top: 0;
+}
 ul > li     { color: #aaa; }
 ul > li > * { color: black; }
-pre {
+.monospaced, code, pre {
+  font-family: "Courier New", Courier, monospace;
+  font-size: inherit;
+  color: navy;
   padding: 0;
   margin: 0;
+}
+pre {
+  white-space: pre-wrap;
+}
 #author {
   color: #527bbd;
   font-weight: bold;
 ...
   border-left: 3px solid #dddddd;
   padding-left: 0.5em;
+}
 div.imageblock div.content { padding-left: 0; }
-span.image img { border-style: none; }
+span.image img { border-style: none; vertical-align: text-bottom; }
 a.image:visited { color: white; }
 dl {
   margin-top: 0.8em;
   margin-bottom: 0.8em;
 ...
 /*
  * xhtml11 specific
+ *
  * */
-tt {
-  font-family: "Courier New", Courier, monospace;
-  font-size: inherit;
-  color: navy;
 div.tableblock {
   margin-top: 1.0em;
   margin-bottom: 1.5em;
+}
 div.tableblock > table {
 ...
 /*
  * html5 specific
+ *
  * */
-.monospaced {
-  font-family: "Courier New", Courier, monospace;
-  font-size: inherit;
-  color: navy;
 table.tableblock {
   margin-top: 1.0em;
   margin-bottom: 1.5em;
+}
 ...
+}
 @media print {
   body.manpage div#toc { display: none; }
+}
 </style>
 <script type="text/javascript">
 /*<![CDATA[*/
 var asciidoc = {  // Namespace.
 ...
 <div id="preamble">
 <div class="sectionbody">
 <div class="paragraph"><p>The <strong>sc2mpd</strong> auxiliary process implements part of Linn <strong>Songcast</strong> support
 for the <strong>upmdcli</strong> UPnP MPD front-end. Specifically, it implements a
 <strong>Songcast</strong> <em>Receiver</em> service, managed by <strong>upmpdcli</strong>.</p></div>
+<div class="paragraph"><p>To use it, you need the
+<a href="http://www.linn.co.uk/software#songcast">Linn Songcast application</a>
+installed on a Microsoft Windows or Apple Mac OS X PC. See
+<a href="#whatis_songcast">further</a> for more explanations about what this does.</p></div>
-<div class="paragraph"><p><strong><em>This has mostly been tested with 16 bits sound but a recent change seems
+<div class="paragraph"><p><strong>sc2mpd</strong> has mostly been tested with 16 bits sound but a recent change
-to have fixed 24 bits sound, so this should be now usable for MACs.  This
+seems to have fixed 24 bits sound, so this should be now usable for
-needs mpd 0.19 on the renderer. Still be a bit careful as this is quite new
+MACs. <strong><em>This needs mpd 0.19 on the renderer. Do not try 24 bits sound with
-and there is a risk of strange noises !</em></strong></p></div>
+mpd 0.18 !</em></strong> (or turn the volume very low&#8230;). Using Songcast from a Mac (24
-<div class="paragraph"><p><strong><em>Do not try 24 bits sound with MPD 0.18 !</em></strong> (or turn the volume very
+ bits audio) needs <strong>mpd 0.19</strong>, configured with <code>--disable-audiofile</code>.
-low&#8230;). Using Songcast from a Mac (24 bits audio) needs <strong>mpd 0.19</strong>,
-configured with <tt>--disable-audiofile</tt>.</p></div>
-<div class="paragraph"><p>As Debian and Ubuntu tend to lag quite bit on MPD progresses, I have setup
+As Debian and Ubuntu tend to lag quite bit on MPD progresses, I have set up
 <a href="downloads.html#mpd">backport repositories</a> for recent mpd versions
 (currently 0.19.9), for Ubuntu, Debian i386/amd64 and Raspbian.</p></div>
-<div class="paragraph"><p><strong>NEW: Debian packages for sc2mpd:</strong> as the procedure for building sc2mpd is
+<div class="paragraph"><p>And to conclude the misc warnings section: <strong>there is no software volume
-not completely obvious and automatic, I have also added <strong>sc2mpd</strong> packages
+control</strong> of the Songcast Receivers for now: use either a local mixer or the
-to the <strong>upmpdcli</strong> Debian repository. Packages exist for architectures i386,
+little round things on the power amps.</p></div>
-amd64 and Raspberry Pi. You can follow the procedure on the
+<div class="paragraph"><p>There are Debian Wheezy <strong>sc2mpd</strong>
-<a href="downloads.html">upmpdcli download page</a> to add the repository, then
+packages in the <strong>upmpdcli</strong> repository for i386, amd64 and Raspberry Pi
-just use the following to install sc2mpd:</p></div>
+(Raspbian): see the <a href="downloads.html">upmpdcli download page</a>, so you do
-<div class="literalblock">
+not need to build any software if you use these systems.</p></div>
-<div class="content">
-<pre><tt>sudo apt-get install sc2mpd</tt></pre>
-</div></div>
 <div class="admonitionblock">
 <table><tr>
 <td class="icon">
 <div class="title">Note</div>
 </td>
-<td class="content">For rebuilding from the source package: the installed binary has a
+<td class="content">you know what Songcast is and have a Rasberry PI which wants to play:
-static link to the OpenHome libraries. This means that, in order to rebuild
+<a href="#rpi_quick">quick install for the Raspberry PI</a>  (also works for i386
-from the source package, you need to follow the normal procedure to build
+and amd64 Debian Wheezy).</td>
-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.</td>
 </tr></table>
 </div>
 </div>
 </div>
 <div class="sect1">
-<h2 id="_what_is_songcast">What is Songcast</h2>
+<h2 id="whatis_songcast">What is Linn Songcast</h2>
 <div class="sectionbody">
-<div class="paragraph"><p>Songcast is a protocol for transporting audio streams across the
+<div class="paragraph"><p><strong>Songcast</strong> is a protocol for transporting audio streams across the network,
-network. This is independant from the UPnP framework which mostly deals
+developped by <a href="http://oss.linn.co.uk/trac/wiki/Songcast">Linn</a> as a
-with URLs and audio files (usually, but not necessarily, compressed).</p></div>
+series of open-source libraries and applications.</p></div>
-<div class="paragraph"><p>The streams transported by Songcast are actual real-time audio data, which
+<div class="paragraph"><p>The protocol links two types of entities:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+A <strong>Songcast</strong> <em>Sender</em> generates an audio stream (Windows or Mac).
+</p>
+</li>
+<li>
+<p>
+<strong>Songcast</strong> <em>Receivers</em> receive and play the stream.
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>There are <strong>Songcast</strong> applications (<em>Senders</em>) for Windows and Mac OS X
+(nothing for Linux, iOS or Android for now). The <strong>Songcast</strong> application
+captures and forward the system audio stream to a remote <strong>Songcast</strong>
+<em>Receiver</em>.</p></div>
+<div class="paragraph"><p><strong>Any</strong> application on the desktop (Windows Media Player, Spotify, Tidal,
+etc.) will transparently play to the remote device, without any need to
+know about <strong>Songcast</strong>. <strong><em>Any</em></strong> audio service available on Windows or the
+Mac can be forwarded to one or <a href="scmulti.html">many</a> audio players around
+the house.</p></div>
+<div class="paragraph"><p>The <strong>Songcast</strong> streams are real-time audio data, which can go straight
-can go straight to an audio card for playing.</p></div>
+to an audio card for playing.</p></div>
-<div class="paragraph"><p>Controlling the streams on the renderer (connecting, starting, stopping) is
+<div class="paragraph"><p>Controlling the streams (connecting, starting, stopping) is
-done through an UPnP service named OpenHome <em>Receiver</em>.</p></div>
+done through an UPnP service named OpenHome <em>Receiver</em>, which runs on an
-<div class="paragraph"><p>The typical use of Songcast is to have an audio driver on a Windows or OS X
+UPnP Media Renderer implementing the OpenHome services (e.g. <strong>upmpdcli</strong>).</p></div>
-desktop capture and forward the audio stream to a remote Songcast device.</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 Songcast.</p></div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="_implementation_of_songcast_support_in_upmpdcli">Implementation of Songcast support in upmpdcli</h2>
 <div class="sectionbody">
 <div class="paragraph"><p><strong>upmpdcli</strong> implements the <em>Receiver</em> service, and uses an auxiliary process
 (<strong>sc2mpd</strong>) for transporting the audio data. <strong>sc2mpd</strong> 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
+open-source implementation</p></div>
-on <em>libmicrohttpd</em>) to forward the data to <strong>mpd</strong>.</p></div>
+<div class="paragraph"><p><strong>sc2mpd</strong> can play the audio stream in two modes:</p></div>
-<div class="paragraph"><p>Setting up a connection happens as follows:</p></div>
 <div class="ulist"><ul>
 <li>
 <p>
-If it finds an executable <strong>sc2mpd</strong> command in the PATH when starting up,
+By offering a local HTTP interface (based on <em>libmicrohttpd</em>) from which
-  <strong>upmpdcli</strong> advertises a <em>Receiver</em> service.
+   <strong>mpd</strong> will play the stream.
-</p>
-</li>
+</p>
-<li>
+</li>
+<li>
+<p>
+By directly using the <strong>alsa</strong> audio driver. <strong><em>This only works with 16
+   bits sound for now (so only with a Windows sender, no Macs allowed)</em></strong>
-<p>
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>What approach is used is decided by a parameter in the upmpdcli
+configuration file: <code>scplaymethod</code> (see <a href="#Configuration">[Configuration]</a> further)</p></div>
+<div class="paragraph"><p>Control:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+If <strong>upmpdcli</strong> finds an executable <strong>sc2mpd</strong> command in the PATH when
+  starting up, it advertises a <em>Receiver</em> service.
+</p>
+</li>
+<li>
+<p>
-The Songcast implementation from the desktop finds out about the
+The <strong>Songcast</strong> application on the desktop finds out about the
   <em>Receiver</em> through the normal UPnP mechanisms and can be instructed to
   use it. It then tells the <em>Receiver</em> in <strong>upmpdcli</strong> to start playing.
 </p>
 </li>
 <li>
 <p>
 <strong>upmdpcli</strong> starts the <strong>sc2mpd</strong> process, which gets ready to receive data
-  through Songcast, and make it available through HTTP.
+  through Songcast, and either play it directly or make it available
-</p>
+  through HTTP.
-</li>
+</p>
-<li>
+</li>
+<li>
 <p>
-<strong>upmpdcli</strong> instructs <strong>mpd</strong> to play the URL for the <strong>sc2mpd</strong> output.
+If the <em><code>mpd</code></em> method is in use, <strong>upmpdcli</strong> instructs <strong>mpd</strong> to play the
+  URL for the <strong>sc2mpd</strong> output.
 </p>
 </li>
 </ul></div>
-<div class="paragraph"><p>There is currently a 10-12 S delay between the connection request and the
+<div class="paragraph"><p>When using <em><code>mpd</code></em> more bufferisation occurs and there may be a significant
-moment the audio starts playing. This is not normal, but I could not find
+delay (up to around 10S) between the time when Songcast is activated and
-the reason for it, so it&#8217;s an unavoidable inconvenience at the moment.</p></div>
+the time sound appears.</p></div>
+<div class="paragraph"><p>Given the bufferisation and delay control issues when going through MPD,
+only the <em><code>alsa</code></em> method is usable in multi-room configurations. Even with a
+single player, the <em><code>mpd</code></em> method will experience skips from time to
+time. The reasons are explained in the <a href="scmulti.html">multi-room</a>
+page.</p></div>
 </div>
 </div>
 <div class="sect1">
-<h2 id="_configuration">Configuration</h2>
+<h2 id="rpi_quick">Quick install for Debian Wheezy systems</h2>
 <div class="sectionbody">
+<div class="paragraph"><p>There are packages available for Raspbian and Debian Wheezy i386 and amd64.</p></div>
+<div class="paragraph"><p>So add the repositories:</p></div>
+<div class="literalblock">
+<div class="content">
+<pre><code>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</code></pre>
+</div></div>
+<div class="paragraph"><p>Install (the mpd and libupnp versions in the repo have bug fixes):</p></div>
+<div class="literalblock">
+<div class="content">
+<pre><code>sudo apt-get update
+sudo apt-get install upmpdcli sc2mpd mpd libupnp6</code></pre>
+</div></div>
+<div class="paragraph"><p>And seed the next section for configuring.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="Configuration">Configuration</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_on_the_receiver_side">On the Receiver side</h3>
 <div class="paragraph"><p>No configuration is necessary by default: if <strong>sc2mpd</strong> is present,
 <strong>upmpdcli</strong> will advertise the Songcast capability, and any host with a
 Songcast sender installed should be able to use it.</p></div>
 <div class="paragraph"><p>However, you can set a number of values in the upmpdcli configuration file
-(you <strong>must</strong> set the <strong>upmpdcli</strong> <tt>-c</tt> option for <strong>sc2mpd</strong> to see them, the
+(you <strong>must</strong> set the <strong>upmpdcli</strong> <code>-c</code> option for <strong>sc2mpd</strong> to see them, the
 environment variable will not work):</p></div>
 <div class="dlist"><dl>
+<dt class="hdlist1">
+scplaymethod
+</dt>
+<dd>
+<p>
+This decides how audio is played, with 2 possible
+values, <em><code>alsa</code></em> or <em><code>mpd</code></em>. Using <em><code>mpd</code></em> is somewhat easier, but
+unusable in <a href="scmulti.html">multi-room</a> configurations, and you risk
+small drops even in single-player settings.
+</p>
+</dd>
+<dt class="hdlist1">
+scalsadevice
+</dt>
+<dd>
+<p>
+If the <em><code>alsa</code></em> method is set, the <code>scalsadevice</code>
+parameter defines the interface name. Use <code>aplay -L</code> to find the
+appropriate name. Also check that user <em><code>upmpdcli</code></em> belongs to the
+<em><code>audio</code></em> group.
+</p>
+</dd>
 <dt class="hdlist1">
 sclogfilename
 </dt>
 <dd>
 <p>
-Name of the file which will receive <strong>sc2mpd</strong> log messages. <tt>stderr</tt> by
+Name of the file which will receive <strong>sc2mpd</strong> log messages. <code>stderr</code> by
 default. This <em>can&#8217;t be</em> the same file used by <strong>upmpdcli</strong>.
 </p>
 </dd>
 <dt class="hdlist1">
 scloglevel
 ...
 <dt class="hdlist1">
 schttpport
 </dt>
 <dd>
 <p>
-HTTP port used by <strong>mpd</strong> to connect to <strong>sc2mpd</strong>. 8888 by default. This must
+If the <em><code>mpd</code></em> method is set, this defines the HTTP port used by <strong>mpd</strong> to
-be an available port on <tt>localhost</tt>, and it will only accept connections from
+connect to <strong>sc2mpd</strong>. 8768 by default. This must be an available port on
-<tt>localhost</tt>.
+<code>localhost</code>, and it will only accept connections from <code>localhost</code>.
 </p>
 </dd>
 <dt class="hdlist1">
 sc2mpd
 </dt>
 <dd>
 <p>
-Path for the <strong>sc2mpd</strong> executable file (e.g. <tt>/usr/local/bin/sc2mpd</tt>). Only
+Path for the <strong>sc2mpd</strong> executable file (e.g. <code>/usr/local/bin/sc2mpd</code>). Only
 useful if <strong>sc2mpd</strong> was not installed to a location in the executable $PATH
-set for the init scripts. Typically only <tt>/bin</tt> and <tt>/usr/bin</tt> are in
+set for the init scripts. Typically only <code>/bin</code> and <code>/usr/bin</code> are in
-there.
+there. This allows <strong>upmpdcli</strong> to find <strong>sc2mpd</strong> if it is not in the standard
+location.
 </p>
 </dd>
 </dl></div>
+</div>
+<div class="sect2">
+<h3 id="_on_the_sender_windows_mac_side">On the Sender (Windows/Mac) side</h3>
+<div class="paragraph"><p>I could not get IP multicast to work with WIFI Receivers (the sound drops
+constantly).</p></div>
+<div class="paragraph"><p>There are well-known problems with multicast and WIFI (see for example
+<a href="http://superuser.com/questions/730288/why-do-some-wifi-routers-block-multicast-packets-going-from-wired-to-wireless">this
+superuser.com question</a>
+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.</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>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).</p></div>
+</div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="_building_sc2mpd">Building sc2mpd</h2>
 <div class="sectionbody">
 ...
 <p>
 Building <strong>sc2mpd</strong> proper
 </p>
 </li>
 </ul></div>
-<div class="paragraph"><p>First clone the <strong>sc2mpd</strong> Github repository:
+<div class="paragraph"><p>First download a
+<a href="http://www.lesbonscomptes.com/upmpdcli/downloads.html"><strong>sc2mpd</strong>
+release</a> or clone the <strong>sc2mpd</strong>
-<a href="http://www.github.com/medoc92/sc2mpd">http://www.github.com/medoc92/sc2mpd</a>.</p></div>
+<a href="http://www.github.com/medoc92/sc2mpd">Github repository</a>.</p></div>
-<div class="paragraph"><p><strong>sc2mpd</strong> depends on the microhttpd library. Install the development and
+<div class="paragraph"><p><strong>sc2mpd</strong> depends on a number of libraries:</p></div>
-runtime packages which are currently named <em>libmicrohttpd-dev</em> and
+<div class="ulist"><ul>
-<em>libmicrohttpd10</em> on Debian-derived systems (use <em>libmicrohttpd</em> and
+<li>
-<em>libmicrohttpd-devel</em> for Fedora).</p></div>
+<p>
+The <a href="http://www.gnu.org/software/libmicrohttpd/">microhttpd</a>
+  library. Install the development and runtime packages which are currently
+  named <em>libmicrohttpd-dev</em> and <em>libmicrohttpd10</em> on Debian-derived systems
+  (use <em>libmicrohttpd</em> and <em>libmicrohttpd-devel</em> for Fedora).
+</p>
+</li>
+<li>
+<p>
+The <a href="http://www.mega-nerd.com/SRC/">libsamplerate</a>
+  library. <em>libsamplerate0</em> on debian-derived systems.
+</p>
+</li>
+<li>
+<p>
+The <strong>libasound</strong> Alsa interface library (<em>libasound2</em>).
+</p>
+</li>
+</ul></div>
 <div class="paragraph"><p>Building the Openhome libraries is a bit of a black art, and the <strong>sc2mpd</strong>
 source comes with an <em>ohbuild.sh</em> script which will try to clone the
 Openhome Git repositories and build the libs:</p></div>
 <div class="literalblock">
 <div class="content">
-<pre><tt>cd sc2mpd
+<pre><code>cd sc2mpd
 mkdir /my/place/for/openhome
-sh ohbuild.sh /my/place/for/openhome</tt></pre>
+sh ohbuild.sh /my/place/for/openhome</code></pre>
 </div></div>
 <div class="paragraph"><p>Miscellaneous error messages will be displayed during the build. Hope for
 the best&#8230;</p></div>
 <div class="paragraph"><p>When this is done, build <strong>sc2mpd</strong>, using the following commands inside the
 <em>sc2mpd</em> directory:</p></div>
 <div class="literalblock">
 <div class="content">
-<pre><tt>sh autogen.sh
+<pre><code>sh autogen.sh
 ./configure --prefix=/usr --with-openhome=/my/place/for/openhome
 make
-sudo make install</tt></pre>
+sudo make install</code></pre>
 </div></div>
 <div class="paragraph"><p>The build uses static Openhome libraries, so you can move the executable to
 another machine without needing the Openhome directory (don&#8217;t forget to
-install the <em>libmicrohttpd</em> runtime though).</p></div>
+install the <em>libmicrohttpd</em>, <em>libsamplerate</em> and <em>libasound</em> runtimes
+though).</p></div>
 <div class="paragraph"><p>After restarting <strong>upmpdcli</strong>, it should advertise the <em>Receiver</em> service and
 appear in the Songcast Sender menus.</p></div>
 </div>
 </div>
 <div class="sect1">
 ...
 </div>
 </div>
 <div id="footnotes"><hr /></div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2015-04-07 16:20:40 CEST
+Last updated 2015-07-19 18:32:36 CEST
 </div>
 </div>
 </body>
 </html>