Notes on the sockmon input plugin:
==================================

(These notes valid at Thu Jul  1 21:57:31 BST 1999 - hopefully at least
some of this will be out of date soon... )

This plugin allows you to listen to a stream of audio data, via a socket
or similar interface.

Currently supported methods are:

i)   FIFO
ii)  UNIX socket
iii) TCPIP socket
iv)  ESD monitor socket

***Note: UNIX sockets are not yet tested, FIFO is only tested on Linux, and ESD
and TCP are only tested on a single Linux box (ie, not over network).

The FIFO and UNIX socket methods are accessed by attempting to load a file
in the normal way.  Sockmon will recognise that the file is a socket or a
FIFO, claim to the rest of alsaplayer that it can probably deal with it,
and if no other module claims that it can deal better it will open a
connection to the file and try to read the resulting data stream.

The data will currently be assumed to be 44.1 Khz 16 Bit Stereo Linear audio
data - this needs to be made configurable at a later date.  (For now, you
might need to pass data through sox before sending it to alsaplayer...)

The TCPIP and ESD methods require a special "filename" parameter, which has
the host (and optional port number, specified by suffixing the hostname with
":<port number>") to connect to encoded within it.

These parameters have the forms:
	\001\001\001<hostname> for TCPIP connections
	\001\001\002<hostname> for ESD connections

The data received from a TCPIP socket will currently be assumed to be
44.1 Khz 16 Bit Stereo Linear audio data, as for UNIX sockets.  Again, this
needs to be made configurable at a later date.

The connection to ESD will also be made using 44.1 Khz 16 Bit Stereo format,
but this will be negotiated with ESD so the user shouldn't need to worry about
it.  It could still do with being configurable, in order to reduce network
traffic, etc...


Varispeed and streamed data
===========================

There is an obvious conflict between the concept of having a stream of data
being read in order, and the ability that AlsaPlayer has to play back data
at variable rates, including backwards.

This is dealt with by sockmon having a large buffer (currently set at 10Mb -
about 1 minute - must be configurable later) which it stores the data which
has been read already in.  The data in this buffer can be played back at any
given rate, or the position within the buffer skipped around.


Real time streamed data
=======================

There are actually two types of streamed data:

i)  Non real time, where the next piece of data can be read at any time, but
    the data can only be read in order (Example 1 below is an example of this)

ii) Real time, where the pieces of data must be read at the same speed as
    they are created.
    
    There are actually two sub-cases here, depending on whether the latency
    between the data being generated and played is important or not:

    A network radio broadcast is a case where the latency is not important
    (it doesn't matter if it takes a few seconds for the sound to be
    generated as long as the delay is constant).

    Example 2 below is a case where the latency is important. 

The current implementation works well for non-real-time streamed data, but
terribly for real-time.  (Data will be lost if the output speed is slower,
or the output position is skipped around using the position slider, since
data is only requested from the socket when it is needed.)

It would be desirable to have the option to have a separate thread reading
data into the buffer as soon as it became available, to properly support
real-time streaming of data.  This is certainly feasible.

It would also be desirable to have the option to reduce the internal
buffering in AlsaPlayer's core for lower latency streamed data.
This is going to be trickier...


Examples of use
===============

i)   FIFO method, being used to play a mod file with mikmod.

	cd /tmp
	mkfifo music.raw
	mikmod -d 3 <modfile name>
		  ^ - This number will vary for different installations.
		  Determine it by doing mikmod -l and choosing the number
		  corresponding to "Raw disk writer (music.raw)"

     Then just open /tmp/music.raw in alsaplayer - it should play.

ii)  ESD method, being used to listen to the output of an Enlightened Sound
     Daemon on a remote machine.

     Note: There will be a considerable delay between sound being played on
     the remote host and by AlsaPlayer - a part of this is unavoidable due
     to network latency, but much of it is due to excessive buffering in
     AlsaPlayer (great for coping with CPU spikes when playing back mpeg
     data, but not so good in this situation).

	On host1:

		Start esd using "esd -tcp -public" or similar.

	On host2:

		Open a connection to ESD on host1 in AlsaPlayer, by opening
		"\001\001\002host1" in AlsaPlayer.
		(Currently you'll have to compile this in to AlsaPlayer
		 in function Main.cpp:sock_cb() - want a nice dialog box...)

	On host1:

		Play sound through esd using "esdcat test.wav" or similar.

The UNIX socket and TCPIP socket methods don't have such easy examples -
I can only think of custom situations where they might be useful.

iii) The TCPIP option might be used with netcat to pass audio data over a
     network without needing ESD.

	On host1:

		cat song.raw | nc -l -p 7001

	On host2:

		Open "\001\001\001host1:7001" in AlsaPlayer.
		(Currently you'll have to compile this in to AlsaPlayer
		 in function Main.cpp:sock_cb() - want a nice dialog box...)

iv)  UNIX sockets - havn't got an example for these yet, but could be used in
     a similar way to Example iii), if you have a program like netcat which
     supports UNIX sockets.

v)   (This is a silly one...)  ESD method, listening to local ESD daemon

	Start esd on localhost, with "esd -public".

	Start alsaplayer with the "-o esd" option.

	Tell alsaplayer to monitor the ESD daemon using the "Monitor socket"
	pop up option (default is currently to connect to a local ESD).

	Play something on the local ESD, with "esddsp splay test.mp3" or
	similar.

	Listen to the chaos.  Especially if you fiddle with the speed setting.
	Highly amusing...  (Though this is a good test of the code, too.
	It does work as expected for me...)

--Richard Boulton
