sc2mpd / Code / Diff of /doc/sc2mpd.txt

Diff of /doc/sc2mpd.txt [5e884e] .. [882899]

Switch to unified view

-a/doc/sc2mpd.txt
+b/doc/sc2mpd.txt
 ...
 The *sc2mpd* auxiliary process implements part of Linn *Songcast* support
 for the *upmdcli* UPnP MPD front-end. Specifically, it implements a
 *Songcast* _Receiver_ service, managed by *upmpdcli*.
+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.
-*_This has mostly been tested with 16 bits sound but a recent change seems
+*sc2mpd* 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. *_This needs mpd 0.19 on the renderer. Do not try 24 bits sound with
-and there is a risk of strange noises !_*
+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`.
-*_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
+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
+And to conclude the misc warnings section: *there is no software volume
-not completely obvious and automatic, I have also added *sc2mpd* packages
+control* of the Songcast Receivers for now: use either a local mixer or the
-to the *upmpdcli* Debian repository. Packages exist for architectures i386,
+little round things on the power amps.
-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
+There are Debian Wheezy *sc2mpd*
-static link to the OpenHome libraries. This means that, in order to rebuild
+packages in the *upmpdcli* repository for i386, amd64 and Raspberry Pi
-from the source package, you need to follow the normal procedure to build
+(Raspbian): see the link:downloads.html[upmpdcli download page], so you do
-the OpenHome libs first (see the ohbuild.sh script further down). The build
+not need to build any software if you use these systems.
-tree should be located under /opt/openhome for the package rebuild to work.
+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:
+The protocol links two types of entities:
- - A *Songcast* _Sender_ generates an audio stream.
+ - A *Songcast* _Sender_ generates an audio stream (Windows or Mac).
- - A *Songcast* _Receiver_, which typically runs on an OpenHome Renderer,
+ - *Songcast* _Receivers_ receive and play the stream.
-   receives the stream and plays it.
-The streams transported by *Songcast* are actual real-time audio data, which
+There are *Songcast* applications (_Senders_) for Windows and Mac OS X
-can go straight to an audio card for playing.
+(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.
+UPnP Media Renderer implementing the OpenHome services (e.g. *upmpdcli*).
-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*.
 == 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
+open-source implementation
-on _libmicrohttpd_) to forward the data to *mpd*.
-Setting up a connection happens as follows:
+*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)
+Control:
-- If it finds an executable *sc2mpd* command in the PATH when starting up,
+- If *upmpdcli* finds an executable *sc2mpd* command in the PATH when
-  *upmpdcli* advertises a _Receiver_ service.
+  starting up, it advertises a _Receiver_ service.
-- The Songcast implementation from the desktop finds out about the
+- 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.
+  through Songcast, and either play it directly or make it available
+  through HTTP.
- *upmpdcli* instructs *mpd* to play the URL for the *sc2mpd* output.
+- If the _`mpd`_ method is in use, *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
+When using _`mpd`_ 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's an unavoidable inconvenience at the moment.
+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.
 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):
+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*.
 scloglevel::
 Log verbosity.
 schttpport::
+If the _`mpd`_ method is set, this defines the HTTP port used by *mpd* to
-HTTP port used by *mpd* to connect to *sc2mpd*. 8888 by default. This must
+connect to *sc2mpd*. 8768 by default. This must be an available port on
-be an available port on `localhost`, and it will only accept connections from
+`localhost`, and it will only accept connections from `localhost`.
-`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
 There are two parts in building *sc2mpd*:
 - Building the Openhome libraries
 - Building *sc2mpd* proper
-First clone the *sc2mpd* Github repository:
+First download a
+link:http://www.lesbonscomptes.com/upmpdcli/downloads.html[*sc2mpd*
+release] or clone the *sc2mpd*
-http://www.github.com/medoc92/sc2mpd.
+link:http://www.github.com/medoc92/sc2mpd[Github repository].
-*sc2mpd* depends on the microhttpd library. Install the development and
+*sc2mpd* depends on a number of libraries:
-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.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
 Openhome Git repositories and build the libs:
 ...
     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_ 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.
 == Miscellaneous remarks