Welcome to the wonderful world of Local Area Network radio!
===========================================================

This is Radio version 2.0, patchlevel 4 (a.k.a. 2.0.4).

If you have a local area network full of workstations with audio
capabilities and at least one FM/AM radio or other audio source, you
can broadcast the audio over the network, and let other users listen
to it.

This software works for Sun Sparcs running SunOS 4.0 or 4.1, for SGI
Indigo or Personal IRIS 4D/30 or 4D/35 workstations running SGI IRIX
4.0 or 3.3.2, NeXT workstations (running version 2.1), DECstations
equipped with DEC lofi, machines running the AudioFile audio server
from DEC CRL, and HP machines with audio hardware.  At CWI, versions
of it have been in continuous use on a mix of Sun and SGI system types
for almost two years; version 1.0 (patchlevel 4) was last tested on a
NeXT.  (I've heard that the program doesn't work on NeXT 3.1; if you
fix it please send me the changes!)

Man pages for "radio" and "broadcast" are provided.

The implementation continuously transmits UDP broadcast packets of
1400 bytes each (i.e. less than six per second), which contain the
data in U-LAW format (8000 samples/second, 1 byte/sample,
logarithmically encoded).  On a typical ethernet, this uses about 1
percent of the net available bandwith.  Some loss of UDP packets is
tolerated by the receiving program (this is heard as short
interruptions of the sound).  Every now and then, a short "station
call" packet is transmitted as well, for the benefit of advanced
listening programs.

It is possible to use multiple transmission stations (each identified
by a different UDP port), and to transmit to multiple connected
subnets simultaneously (as long as the gateways let UDP broadcast
packets through).  For reasons you don't want to know, you can only
have one broadcasting and one radio process per host, except on
the SGI there may be multiple radio processes.

If you have Motif, you may be interested in the "tuner" program by
Jack Jansen.  This is a window-based interface that shows the
different broadcasting stations at your site and lets you tune your
radio process to the station of your choice.  It was posted to
comp.sources.<something> around the same time as radio 2.0.2; you can
also ftp it from site ftp.cwi.nl [192.16.184.180], file
/pub/tuner1.*.tar.Z, or from the comp.sources.unix archives.

If you missed a part of the posting of radio, you can ftp the whole
source from ftp.cwi.nl [192.16.184.180], file /pub/radio2.0.*.tar.Z.

This software is copyrighted.  See the notice at the end of this file.


Changes in 2.0 patchlevel 4
---------------------------

Fix broken info reply from broadcast (no port was filled in).

Made port numbers in info messages from radio/broadcast positive
integers.

Some new debug messages in radio.c.

Port to HP-UX by Philippe-Andre Prindeville <philipp@res.enst.fr>.
(This uses the raw interface to the hardware.  Philippe-Andre has
tried to use the AAPI library but can't get it to work properly.  If
you think you can get the AAPI version working, let me know and I'll
send you his AAPI patches.)

The following improvements are thanks to Andreas Stolcke
<stolcke@ICSI.Berkeley.EDU>:

It is now possible to have multiple broadcast processes running on the
same host; the transmission socket is no longer bound to a fixed port
(you may have to zero the control port with -c 0 if your system
doesn't have the SO_REUSEPORT socket option).

Radio -r is now implemented by filtering packets based on sender's
address rather than connecting to a fixed port.

Fixed integer overflow in broadcast -t after about 35 minutes.

Ignore tune requests to invalid port numbers.

Fixed unused variable in "bad broadcast address" error message.

Let opensock() return -1 on error.


Changes in 2.0 patchlevel 3
---------------------------

Broadcast no longer uses "-b address" to indicate the IP address to
send to; address must be passed as arguments, after all options.
Addresses have an optional :port suffix to override the port specified
with -p (or the default of 54321).

Thanks to George Neville-Neil, radio can now also be used with DEC
CRL's AudioFile server or with DEC LoFi hardware (these options
require additional software available elsewhere).  When compiled for
AudioFile, broadcast can optionally record data directly from the
server.

Bugfix when switching stations under tuner control when using
multicast.

Minor clarifications to man pages, etc.

Copyrights updated.


Changes in 2.0 patchlevel 2
---------------------------

Broadcast can now also read 16-bit linear samples from standard input,
as this is more appropriate for ADPCM encoding (see below).  Use the
-l option.  There is a program, recordlinear, which outputs such
samples, for the SGI only.

On the SGI, radio's cleanup handler (invoked when it receives a TERM
or INTR signal) resets the output volume only if it was set with the
-v option.  It resets nothing at all if the program was currently
paused by a tuner.

There is now a default multicast address, from the unofficial range.
(This only has meaning for SGI users and for users of a hacked SunOS
version which supports multicast.)

Data packets now have a 2-byte header, which is compatible with IVS,
INRIA's video and audio conferencing system, and allows us to support
different encoding schemes.  (The control packet format is unchanged,
compatibility with IVS is not a point here.)  Currently supported
encodings are:

- PCM_64 (pulse-code modulation; in fact, plain u-law as before);

- ADPCM_32 (Adaptive Delta PCM, which takes only 32 kbit/sec with only
  a slight loss in quality);

- ADPCM_32_W_STATE, which is the same as ADPCM_32 but adds three bytes
  of state for the encoder to reduce noise (this format is not
  understood by IVS).

The default encoding used by broadcast is PCM_64; use the "-a" option
to use ADPCM_32_W_STATE, or "-A" for ADPCM_32.  The radio program
recognizes the encoding from the data packet header and so it does not
need an option to select the encoding.

Changes by Alexander Dupuy <dupuy@tiemann.cs.columbia.edu> (thank you
Alexander!):

Makefile: added a sunos4.1.2 target for our hacked version of 4.1.2 with
	  multicasts (a better name would be sun4.1-multi, since multicasting
	  is not standard in 4.1.2 (maybe in Solaris 2.0?).

broadcast.c: add a -m (multicast ttl) option, which sets the multicast ttl to
	     control the range over which multicast packets are forwarded.
	     this is necessary if you want multi-subnet multicasts.

broadcast.c: use $HOME/.CD and $HOME/.CDlog as default playfiles - this is a
	     bit more portable, as most sites will try to make sure that
	     users' home directories are accessible via the same path name on
	     all machines.  It still fails (for .CDlog) when that is not true.
	   
broadcast.c: if compiled with DEFMCAST defined as a valid multicast address
radio.c:     and HAVE_MCAST defined, broadcast and radio programs will default
	     to the multicast address DEFMCAST instead of broadcast.

broadcast.c: increase the maximum size of control packets to 512 bytes, to
radio.c:     support longer song titles (including artist and track title)
	     which WorkMan typically generates.  Note that radio is also
	     changed to use a larger control packet size, since it uses the
	     length of incoming packets to determine whether they are control
	     or data  (this is arguably a bug).

radio.c: attempt hostname lookup on -m (multicast) address argument, since it
	 is possible to put multicast addresses in /etc/hosts, NIS, and even,
	 with a bit of work, DNS.

broadcast.man: updated to reflect user-visible changes to the broadcast and
radio.man:     radio programs.


Changes in 2.0 patchlevel 1
---------------------------

On the sun and sgi, radio tries to open a connection to the X server
(specified by the $DISPLAY environment variable) and every now and
then makes a small request to exercise the connection.  This ensures
that if the user logs out, radio will quit.  If no connection to the X
server can be made, these checks are not made and a warning is printed
that reminds the user to kill radio when logging out.

The usage message is more informative.

The new option '-t' (tee) sends output to both stdout and the audio
device.  Thanks to Scott Hazen Mueller for suggesting this.

The experimental option '-m mcastgrp' (for SGI only) specifies a
multicast group.  By multicasting instead of broadcasting, you can
reduce the load on hosts that aren't listening (see the man page).


Changes since version 1.0 patchlevel 4
--------------------------------------

(Skip to the next section if you aren't already using version 1.0 of
radio.)

The source structure has been changed -- all files are in one
directory now.

More Python programs have been provided, and the existing ones have
been improved.  (Translations to C will be accepted and may end up in
a future distribution -- here's your chance to gain world popularity!)

Building for the Sun now requires an explicit choice between sun4.0
and sun4.1 -- "make sun" no longer works.

The radio program can now be "paused" by a separate tuner program.
This means you don't have to kill the radio process if you want a few
minutes of silence.

The broadcast program now broadcasts "station call" messages to a
fixed port twice a minute, as a service to more sophisticated tuner
programs.  The Python program "stations.py" can be used to display
these station calls (in a primitive manner).

The broadcast program now implements silence suppression: if the input
is silent longer than 20 seconds it stops transmitting packets,
keeping network overhead low.  (You may have to tweak the level -- our
typical "silent" input is rather noisy, so we set the livel rather
high.)

Many minor changes and bugfixes.


Building and installing
-----------------------

For SunOS 4.1 or higher (assuming the audio library is in
/usr/demo/SOUND), type "make sun4.1".  For SGI IRIX, type "make sgi".
For the NeXT, type "make next".  This should produce binaries for
"radio" and "broadcast".  For the SGI it also produces binaries
"recordulaw" and "playulaw"; for the NeXT, it also builds "sndulaw".
Read the Makefile for details -- it's pretty trivial.

(For SunOS 4.0, you may try "make sun4.0" instead.  This does not make
the assumption that the audio library is in /usr/demo/SOUND.  Edit the
Makefile if necessary to accomodate other locations.)

For SGI IRIX, the Makefile builds the "recordulaw" and "playulaw"
programs.  "recordulaw" uses the IRIX audio library to sample the
audio input and convert it to U-LAW format.  "playulaw" does the
reverse (it is not actually used but provided as a convenience).  The
audio library is available on IRIS 4.0 and on IRIS 3.3.2 or higher.

For a DECStation with LoFi hardware, you need to fetch either the LoFi
library by George Neville-Neil <gnn@cs.utwente.nl> (based on code by
DEC CRL) or the DEC CRL AudioFile software distribution.  LoFiLib is
available for ftp from pegasus.cs.utwente.nl in
/pub/audio/libminilofi.tar.Z.  AudioFile is available for ftp from
crl.dec.com in /pub/DEC/AF/AF2R2.tar.Z.  Also get the patches from the
same directory.  AudioFile runs on several different kinds of
hardware, including almost all DEC hardware.  It is one or more orders
of magnitude bigger than LoFiLib.

To build for LoFiLib, build LoFiLib first (there is a README in there
detailing that process).  Edit the variable LOFI in the Makefile here
to point to the LoFiLib directory.  Then do "make lofi".

To build with AudioFile, build the AudioFile client library and server
first.  Edit the variable AF in the Makefile here to point to the root
of the AudioFile tree; or edit the variables AFINCLUDES and AFLIBDIRS
to point to the installed include files and libraries respectively.
Then do "make audiofile".

Install the "radio" program on a convenient public place (where
potential listeners can find it, e.g., /usr/local/bin); install
"broadcast" on a convenient place for yourself (assuming you're the
one doing transmissions).  The "recordulaw" or "sndulaw" programs, if
needed, should be installed together with "broadcast".  On an SGI
system you may install "playulaw" if you like.


Usage -- transmissions
----------------------

(See the man page for broadcast for more details.)

To start transmissions on Sun Sparcs, run this command (probably in
the background, once you've debugged your audio setup):

	broadcast -p port </dev/audio

You must connect a mono audio source to the machine using a standard
cable provided by Sun.  Control the input gain with [x_]gaintool
(e.g., /usr/demo/SOUND/x_gaintool).


This command start transmissions on SGI IRIX:

	recordulaw | broadcast -p port

Connect a stereo audio source to the machine using a standard walkman
jack.  If you're using an early personal Iris, check that you have
audio hardware and software installed -- the output from hinv will
tell you this.


On the NeXT you start transmissions as follows:

	sndulaw | broadcast -p port

This takes input from the microphone; you may also connect an audio
source to the microphone input (probably needs some attenuation to get
the impedance right).


On Audio File you start transmissions as follows:

	broadcast -s -p port


By default this broadcasts on the local ethernet.  You can specify one
or more arguments to broadcast, passing it explicit IP broadcast
addresses (last byte 0 or 255, depending on local convention).  You can
specify your local IP net or another net; the latter only works if
your gateways pass UDP broadcasts through (at CWI it works).

Note: each transmitter must choose a unique port number.  The default
is 54321; other suitable ports are 54322, 54323, and so on.


Usage -- reception
------------------

(See the man page for radio for more details.)

To listen to transmissions on either system:

	radio -p port

This sends the data directly to the audio output device (speaker or
headphones).  It is also possible to get the ULAW audio data on
standard output with the -f option ("filter").

The -v option sets the output volume (on a scale from 0 to 100).  To
change the volume later on a Sun Sparc, use [x_]gaintool (at CWI:
/usr/demo/SOUND/x_gaintool).  On an SGI, use "apanel".


Bells 'n whistles
-----------------

Some Python programs are distributed together with radio.  Python is
an object-oriented prototyping language that I developed partly
because I wanted to write system hacks without having to resort to C
or Perl.  Free source and documentation for the Python interpreter is
available by anonymous ftp from various file servers, in particular
ftp.cwi.nl (in the Netherlands) and wuarchive.wustl.edu (in the US).

The Python program "ttytuner.py" (by Jack Jansen) can be used to
control the port that radio listens to.  Note that this allows anybody
on the world to control your radio, in principle.  If you don't want
this, you can pass the -s flag (secure), which turns off the control
port altogether.  By convention, the tuner program assumes that every
user who performs transmissions has two files "CD" and "CDlog" in
their home directory giving program information (this is actually a
bad idea, since it requires that the listener and the broadcaster
share the same file name space for user's home directories, but it
saves a lot of complication in the broadcast program).  Jack has also
written a window-oriented tuner (using Motif) -- write to jack@cwi.nl
for source.

The Python program "checkradio.py" (after an idea of Behr de Ruiter)
continually checks and displays what one or more stations are
transmitting.  Arguments are port numbers (default is the default port
to which radio is listening).  When the "-t" option is given, it
prints the reports on stdandard output.  Without this option, it must
be running on an SGI machine and uses only one port number argument.
This goes in the background and opens a tiny window in which it
displays the title of the program being transmitted (as glanced from
the sender's CD file).  The window's background color varies from
bright yellow to dark red as the CD file gets older.  When the
transmission stops the window goes away altogether, to pop up only
when it is resumed.

The Python program "stations.py" waits for incoming station call
messages (transmitted regularly by "broadcast") and prints essential
info from them on stdout.

The Python program "nielsen.py" implements a rudimentary way of
finding out who's listening to what.  Pass it a "-w" option to list
the users on each host where it finds a listener.  You must then be
able to log in to that host remotely (with rlogin or rsh) without
typing your password.

There is also one Perl program, just to show that you don't need to be
entirely helpless if you don't have Python nor Motif:

The Perl program "stations.pl" listens for and prints essential
information about stations.  Extension to the functionality if
"stations.py" is left as an exercise to the reader.


Author
------

The author of this software is:

Guido van Rossum
CWI, dept. CST
Kruislaan 413
1098 SJ  Amsterdam
The Netherlands

E-mail (Internet)  :  Guido.van.Rossum@cwi.nl (guido@cwi.nl)
E-mail (X.400)     :  G=Guido;S=van.Rossum;O=cwi;PRMD=surf;ADMD=400net;C=nl

The "libst" U-LAW conversion library is written and copyrighted by Jef
Poskanzer.

If you port this software to other systems or have useful additions
(like translations of Python programs to C), I'd like to hear from
you.


Acknowledgements
----------------

I would like the following contributors for pieces of code and/or
documentation:

Toerless Eckert for the -n, -l, -r and -t options to radio

Paul Friedman for the -v option

Axel Belinfante for starting the man pages

Reimer A. Mellin for the NeXT port

Jack Jansen for the tuner programs and for many discussions about
possible features

Behr de Ruiter for the idea for the checkradio program


Copyright notice
----------------

Copyright 1991, 1992, 1993 by Stichting Mathematisch Centrum,
Amsterdam, The Netherlands.

                        All Rights Reserved

Permission to use, copy, modify, and distribute this software and its 
documentation for any purpose and without fee is hereby granted, 
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in 
supporting documentation, and that the names of Stichting Mathematisch
Centrum or CWI not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior permission.

STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.