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.
