
...

General information about *upmpdcli* support for *Songcast* can be found
link:sc2mpd.html[here]. This page explains how to set up a multiroom
synchronized audio system using *upmpdcli* and *Songcast*.

NOTE: multicast and WIFI don't mix well in many cases. If you have
wireless Receivers experiencing sound drop issues, try selecting unicast in
the Songcast advanced configuration panel on the desktop.

== Multiple Receivers

Multiple *Songcast* _Receiver_ hosts can connect to the same _Sender_, so
that they will all be playing the same audio. They form a group only in the
sense that they play from the same URI, and are not otherwise linked.

The Mac and Windows *Songcast* apps only let you activate one  
_Receiver_ though.

The *upmpdcli* package now includes the *scctl* command line utility, which
can list the state of the local *Songcast* _Receivers_, make a _Receiver_
play from the same URI as another one (for building multi-room groups), or
return a _Media Renderer_ from _Receiver_ to normal operation.

As the Songcast application is only available on Windows or Mac desktops,

it would be inconvenient to have to access the Linux command line to
control the multi-room groups, and the *upmpdcli* package also includes a
small Web application which can be accessed from a desktop web browser to
control the groups.

This has only be tested with *upmpdcli* and its link:sc2mpd.html[sc2mpd]
*Songcast* auxiliary process as Receiver implementation, but I'd guess that
there is a good chance it would work with others.


== Synchronisation issues

The short version is: all *sc2mpd* instances must be configured to play
directly to Alsa. See the link:sc2mpd.html#Configuration[configuration
section].

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.

The only way to control this is to adjust the rate of reproduction on the
_Receiver_, which can be done in two ways:

 - *Linn* hardware uses timestamps embedded in the audio stream to adjust
   their hardware sample clock.
 - *sc2mpd* in _`alsa`_ mode uses sample rate conversion to adjust the stream.

This is not specific to *Songcast* of course, all real time audio network
transports have to do something similar.

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.


== Setting things up

 - Install upmpdcli and sc2mpd on each of the _Receiver_ systems. Edit
   `/etc/upmpdcli.conf` to set:
   * `friendlyname`, this is quite useful when managing several systems.
   * `scplaymethod` = _`alsa`_
   * `scalsadevice`: use `aplay -L` to chose an appropriate device.

 - Activate the web interface on one of the _Receivers_ (or on any machine
   with upmpdcli installed actually). Edit `/etc/default/scweb` to
   configure the interface (see comments in there) and start it with
   `service scweb start`.

 - Activate a _Receiver_ from the PC *Songcast* interface. Play something and
   leave it playing.

 - Connect to the Web interface (host and port chosen above) with a
   browser, and use it to list, activate, or disconnect the _Receivers_.

Once the slave _Receivers_ are associated with the _Sender_, they should stay
in this state until you change it. So you can stop/start *Songcast* on the
PC, and they will usually just follow.

An "associated" _Receiver_ is just one which plays from the same URI, it
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"'s _Receiver_ from outside the PC *Songcast* interface,
this can only confuse things.

== More detail about the Web interface

To avoid having to access the command line interface to control the
...
You can use the `scweb-standalone.py` script to manually start the
interface:
    
    python2 ./scweb-standalone.py

This will start a server on localhost, on port 8680 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):

    python2 ./scweb-standalone.py -a 0.0.0.0
...
-p can be used to specify a port.

Once started, connecting to the server from any browser should hopefully
display a reasonably self-explanatory interface.

Recent *upmpdcli* packages install the web app as a service named
*scweb*. The service is not started by default though, you need to edit
`/etc/default/scweb`.

	a/doc/scmulti.txt		b/doc/scmulti.txt
	...		...
2		2
3	General information about upmpdcli support for Songcast can be found	3	General information about upmpdcli support for Songcast can be found
4	link:sc2mpd.html[here]. This page explains how to set up a multiroom	4	link:sc2mpd.html[here]. This page explains how to set up a multiroom
5	synchronized audio system using upmpdcli and Songcast.	5	synchronized audio system using upmpdcli and Songcast.
6		6
		7	NOTE: multicast and WIFI don't mix well in many cases. If you have
		8	wireless Receivers experiencing sound drop issues, try selecting unicast in
		9	the Songcast advanced configuration panel on the desktop.
		10
7	== Multiple Receivers	11	== Multiple Receivers
8		12
9	Multiple Songcast _Receiver_ hosts can connect to the same _Sender_, so	13	Multiple Songcast _Receiver_ hosts can connect to the same _Sender_, so
10	that they will all be playing the same audio.	14	that they will all be playing the same audio. They form a group only in the
		15	sense that they play from the same URI, and are not otherwise linked.
11		16
12	The Mac and Windows Songcast apps only let you activate one	17	The Mac and Windows Songcast apps only let you activate one
13	_Receiver_ though.	18	_Receiver_ though.
14		19
15	upmpdcli now includes a small application which can list the state of	20	The upmpdcli package now includes the scctl command line utility, which
16	the local Songcast Receivers, make a Receiver play from the same URI as	21	can list the state of the local Songcast _Receivers_, make a _Receiver_
17	another one (for building multiroom groups), or return a Media Renderer	22	play from the same URI as another one (for building multi-room groups), or
18	from Receiver to normal operation.	23	return a _Media Renderer_ from _Receiver_ to normal operation.
19		24
20	The functions can be accessed either from the scctl command line utility,	25	As the Songcast application is only available on Windows or Mac desktops,
21	or from a local Web application (as Songcast is mostly used from a Windows
22	or Mac PC, it would be inconvenient to have to access the Linux command	26	it would be inconvenient to have to access the Linux command line to
23	line to control the multiroom groups).	27	control the multi-room groups, and the upmpdcli package also includes a
		28	small Web application which can be accessed from a desktop web browser to
		29	control the groups.
24		30
25	This has only be tested with upmpdcli and its link:sc2mpd.html[sc2mpd]	31	This has only be tested with upmpdcli and its link:sc2mpd.html[sc2mpd]
26	Songcast auxiliary process as Receiver implementation, but I'd guess that	32	Songcast auxiliary process as Receiver implementation, but I'd guess that
27	there is a good chance it would work with others.	33	there is a good chance it would work with others.
28		34
		35
29	== Synchronisation issues	36	== Synchronisation issues
30		37
31	The short version is: all sc2mpd instances must be configured to play	38	The short version is: all sc2mpd instances must be configured to play
32	directly to Alsa. See the link:sc2mpd.html#Configuration[configuration	39	directly to Alsa. See the link:sc2mpd.html#Configuration[configuration
33	section].	40	section].
34		41
35	Longer version: Songcast is a real-time audio stream. As the Sender and	42	Longer version: Songcast is a real-time audio stream. As the _Sender_ and
36	Receiver sample clocks (the 44.1 or 48 KHz clocks) are independant, audio	43	_Receiver_ sample clocks (the 44.1 or 48 KHz clocks) are independant, audio
37	reproduction on the two systems will slowly drift. If nothing is done,	44	reproduction on the two systems will slowly drift. If nothing is done,
38	after a time, the Receiver will have to skip samples or add a period of	45	after a time, the _Receiver_ will have to skip samples or add a period of
39	silence (depending if its clock is slower or faster), which is quite	46	silence (depending if its clock is slower or faster), which is quite
40	audible and ennoying, and will happen "from time to time", depending of how	47	audible and ennoying, and will happen "from time to time", depending of how
41	much the clocks differ.	48	much the clocks differ.
42		49
43	The only way to control this is to adjust the rate of reproduction on the	50	The only way to control this is to adjust the rate of reproduction on the
44	Receiver, which can be done in two ways:	51	_Receiver_, which can be done in two ways:
45		52
46	- Linn hardware uses timestamps embedded in the audio stream to adjust	53	- Linn hardware uses timestamps embedded in the audio stream to adjust
47	their hardware sample clock.	54	their hardware sample clock.
48	- sc2mpd in Alsa mode uses sample rate conversion to adjust the stream.	55	- sc2mpd in _`alsa`_ mode uses sample rate conversion to adjust the stream.
49		56
50	This is not specific to Songcast of course, all real time audio network	57	This is not specific to Songcast of course, all real time audio network
51	transports have to do something similar.	58	transports have to do something similar.
52		59
53	Independantly of the clock issue, all Receivers should use approximately	60	Independantly of the clock issue, all _Receivers_ should use approximately
54	the same amount of buffering for the audio to be reasonably synchronous	61	the same amount of buffering for the audio to be reasonably synchronous
55	(with no more shifts than moving around would produce anyway). This is	62	(with no more shifts than moving around would produce anyway). This is
56	impossible to achieve when going through mpd, and the second reason why	63	impossible to achieve when going through mpd, and the second reason why
57	sc2mpd must be set in Alsa mode for multiroom setups. In mpd mode, the	64	sc2mpd must be set in _`alsa`_ mode for multiroom setups. In _`mpd`_
58	receivers can be out of sync by several seconds.	65	mode, the _Receivers_ can be out of sync by several seconds.
59
60		66
61	== Setting things up	67	== Setting things up
62		68
63	- Install upmpdcli and sc2mpd on each of the _Receiver_ systems. Edit	69	- Install upmpdcli and sc2mpd on each of the _Receiver_ systems. Edit
64	`/etc/upmpdcli.conf` to set:	70	`/etc/upmpdcli.conf` to set:
65	* `friendlyname`, this is quite useful when managing several systems.	71	* `friendlyname`, this is quite useful when managing several systems.
66	* `scplaymethod` = alsa	72	* `scplaymethod` = _`alsa`_
67	* `scalsadevice`: use `aplay -L` to chose an appropriate device.	73	* `scalsadevice`: use `aplay -L` to chose an appropriate device.
68		74
69	- Activate the web interface on one of the Receivers (or on any machine	75	- Activate the web interface on one of the _Receivers_ (or on any machine
70	with upmpdcli installed actually). Edit `/etc/default/scweb` to	76	with upmpdcli installed actually). Edit `/etc/default/scweb` to
71	configure the interface (see comments in there) and start it with	77	configure the interface (see comments in there) and start it with
72	`/etc/init.d/scweb-service start`.	78	`service scweb start`.
73		79
74	- Activate a Receiver from the PC Songcast interface. Play something and	80	- Activate a _Receiver_ from the PC Songcast interface. Play something and
75	leave it playing.	81	leave it playing.
76		82
77	- Connect to the Web interface (host and port chosen above) with a	83	- Connect to the Web interface (host and port chosen above) with a
78	browser, and use it to list, activate, or disconnect the Receivers.	84	browser, and use it to list, activate, or disconnect the _Receivers_.
79		85
80	Once the slave Receivers are associated with the Sender, they should stay	86	Once the slave _Receivers_ are associated with the _Sender_, they should stay
81	in this state until you change it. So you can stop/start Songcast on the	87	in this state until you change it. So you can stop/start Songcast on the
82	PC, and they will usually just follow.	88	PC, and they will usually just follow.
83		89
84	An "associated" Receiver is just one which plays from the same URI, it	90	An "associated" _Receiver_ is just one which plays from the same URI, it
85	keeps no other relation to the "Master". Only one Receiver is a bit special	91	keeps no other relation to the "Master". Only one _Receiver_ is a bit special
86	because it is the one known from the PC, but there is no specific reason to	92	because it is the one known from the PC, but there is no specific reason to
87	use it as Master, the Master is only used to get the URI. Avoid changing	93	use it as Master, the Master is only used to get the URI. Avoid changing
88	the state of the "PC"'s Receiver from outside the PC Songcast interface,	94	the state of the "PC"'s _Receiver_ from outside the PC Songcast interface,
89	this can only confuse things.	95	this can only confuse things.
90		96
91	== More detail about the Web interface	97	== More detail about the Web interface
92		98
93	To avoid having to access the command line interface to control the	99	To avoid having to access the command line interface to control the
	...		...
103	You can use the `scweb-standalone.py` script to manually start the	109	You can use the `scweb-standalone.py` script to manually start the
104	interface:	110	interface:
105		111
106	python2 ./scweb-standalone.py	112	python2 ./scweb-standalone.py
107		113
108	This will start a server on localhost, on port 8780 by default which is	114	This will start a server on localhost, on port 8680 by default which is
109	good for testing, but not very useful. Use the -a 0.0.0.0 option to let the	115	good for testing, but not very useful. Use the -a 0.0.0.0 option to let the
110	server answer on all local addresses (or specify the address to use a	116	server answer on all local addresses (or specify the address to use a
111	specific interface):	117	specific interface):
112		118
113	python2 ./scweb-standalone.py -a 0.0.0.0	119	python2 ./scweb-standalone.py -a 0.0.0.0
	...		...
115	-p can be used to specify a port.	121	-p can be used to specify a port.
116		122
117	Once started, connecting to the server from any browser should hopefully	123	Once started, connecting to the server from any browser should hopefully
118	display a reasonably self-explanatory interface.	124	display a reasonably self-explanatory interface.
119		125
		126	Recent upmpdcli packages install the web app as a service named
		127	scweb. The service is not started by default though, you need to edit
		128	`/etc/default/scweb`.