AF Release Notes and Installation Instructions
Please read this thoroughly before installing AF for the first time.
This is the table of contents for the release notes and installation
instructions for AF3R1.
- Abstract
- Introduction
- What is new in this Release?
- Installation Overview
- Building and Installing the Release
- Testing the Release
- Contrib
- Device Driver Information
- DSP Port Devices
- Errata for this Release
- Future Work
- Acknowledgements
- Mailing Lists
- Related Product Information
- Summary
The AudioFile (AF) System is a network-transparent audio server and
client library originally developed for supporting LoFi audio hardware at
Digital Equipment Corporation's Cambridge Research Laboratory. The AF
distribution contains source code for audio servers, clients, and client
library that support several audio devices and platforms.
The AF System is a device-independent network-transparent audio server.
With AudioFile, multiple audio applications can run simultaneously,
sharing access to the actual audio hardware.
Network transparency means that application programs can run on machines
scattered throughout the network. Because AF permits applications to be
device-independent, applications need not be rewritten to work with new
audio hardware. AF does for sound what the X Window System does for text
and graphics.
Development of AF began in 1989 at Digital Equipment Corporation's
Cambridge Research Laboratory, but it builds on ideas from earlier work.
We originally envisioned AF as a server to support all the capabilities
of the CRL LoFi
audio hardware (LoFi became the product known as DECaudio) running on the
DECstation 5000 workstation, but we soon began adding support for a
variety of other platforms and audio hardware.
This distribution of AF includes device drivers for several audio
devices, server code for a number of platforms, a programming API and
library, out-of-the-box core applications, and a number of "contributed"
applications. The key difference between the core and contributed
applications is that the many of the contrib clients also depend on the
Tcl/Tk graphics toolkits distributed by the University of California. The
Tcl/Tk FTP site is located at
ftp.cs.berkeley.edu:ucb/tcl.
With AF, it is easy to incorporate audio into applications. Simple "play"
and "record" applications are included, or you can write your own using
the AF API and client library. AF allows applications to generate and
process audio in real-time but it also permits more leisurely
applications. AF is quite resistant to the vaguaries of scheduling and
operating systems that can make handling audio difficult. We have
successfully used AF for both trivial applications (audio BIFF) and
complex applications (real-time teleconferencing, speech synthesis and
recognition.) AF may not be appropriate for all purposes, but we have
found it to be a versatile and effective tool.
We believe that AF is highly portable, and that it should be
straightforward to add additional support for other systems equipped with
audio hardware.
AF is distributed in source form, with a copyright allowing unrestricted
use similar to the terms in the X Window System copyright (see the Copyright notice included with the
kit.)
We would like to encourage other organizations to add support to AF for
additional platforms, operating systems, and devices, and to contribute
additional applications.
Further information on AF is available in our USENIX paper and
in a CRL
Technical Report.
Servers
This distribution of AF includes server support for Digital Alpha AXP
systems running OSF/1, Digital RISC systems running Ultrix, SGI Indigo
systems running IRX 4.0.5, and Sun Microsystems SPARCstations running
SunOS 4.1.1 and 4.1.3. The servers support audio hardware ranging from
the built-in CODEC audio on SPARCstations and Personal DECstations to 48
KHz stereo audio using the DECaudio TURBOchannel module. In addition,
server support is present for telephone access devices such as DECaudio.
This lists all known audio hardware systems that AF has been modified to
support.
- OSF/1 for Alpha
-
- Ultrix/RISC
-
- SGI Irix
-
- Asgi manages the audio hardware on Indigo.
- SunOS
-
- Asparc manages the base-board audio hardware on Sparcstations.
- SparcStation 10 dda support coming soon.
It should be possible to add support to AF for other Unix workstations
with audio hardware.
API
The distribution includes C language bindings to the protocol that make
it easy to write distributed audio applications.
Clients
This distribution includes a number of core applications for recording,
playback, telephone control, device control, and access control.
"Contrib" Clients
The distribution includes a number of contributed applications including
an audio file browser, an FFT spectrogram display, and multicast network
audio service.
- The core distribution uses a less restrictive copyright similar to the
terms in the MIT X Window System copyright.
- To build this release of AF, you must use a compiler that supports
function prototypes. AF3R1 no longer includes the
NeedFunctionPrototypes
macro to conditionally remove
prototypes during compilation.
- Includes all known bug fixes (thanks to all of you who reported
problems and/or provided fixes) including several that were not provided
as patches to AF2R2.
- New protocol revision.
- Uses our official AF TCP port number.
- Includes a few new clients, including tkPlay, a Tk based simple GUI to
aplay which is a good candidate for your Mosaic showaudio command.
- Includes automatic datatype conversion via an encoding type attribute
on a per AC basis. Supports most simple datatypes as well as some
compressed formats (IMA, GSM, etc.) See the aplay source as an example
of a client using this feature.
- Includes a sampling rate and sample format conversion client and
supporting library code. See aconvert in the contrib hierarchy.
- Includes a few higher level interfaces in AFlib supporting file I/O
using Sox (Tektronix).
- Hypertext documentation suitable for viewing with Mosaic.
- Server support for the Microsoft Sound Board on the Alpha PC.
- Server support for the J300 Sound and Motion board on Alpha workstations.
- Server support for SGI Indigo courtesy of Guido van Rossum, CWI.
- Includes extension code courtesy of Wes Whitnah, Tektronix.
- This kit defaults to installing into the /usr/local hierarchy. Should
enable most sites to simply unpack the kit and perform the make
World step.
- There is Sparc 10 AF support, however we do not yet have the sources.
Watch the mailing list for details.
- No doubt I have left things off this list...
The remainder of this document contains information and instructions for
use in building and installing this release in your local environment.
The information in this document assumes that you have already created a
local audio hierarchy by unpacking the source kit and following the steps
in README-V3.
The software in this release is divided into two distributions: one for
the core server and library software (located in the directory
tree ./AF) and one for device drivers (located in the directory
tree ./devices.) You will need roughly 6 Megabytes to hold the
software kit and an additional 8 Megabytes for building the release.
Steps to build this release include customizing the build rules according
to directory conventions at your local site followed by a few make
build commands. This section contains the directions for the steps to
modify the build rules then build and install this release.
The AF kit has been successfully built and tested on Ultrix/RISC 4.2,
4.2a, and 4.3 systems, DEC OSF/1 Alpha V1.2, V1.3, and 2.0 systems, as
well as IRIX 4.0.5 and SunOS 4.1.3 systems. Please consult the Errata section (below) for a description of
known build issues with this release.
Almost all Makefiles in the core software hierarchy are generated
automatically by a utility called imake. The program combines
machine-independent descriptions (called Imakefiles) of targets to
be built with machine-dependent sets of parameters. Initial versions of
all of the Makefiles are included.
Another utility, called makedepend, is used to generate
Makefile dependencies for C language files.
Sample Makefiles are provided, although you are strongly urged to
use imake and makedepend so that your software works across
releases. For your own applications, the amkmf script in
AF/util/scripts can be used to build a Makefile from an
Imakefile once the core has been built and installed.
Configuring the AF Release
- As you follow these instructions, replace each occurrence of
<audio_root> with the pathname to the root of the newly created
hierarchy and replace each occurrence of <build_root> with
the pathname to the root of the corresponding architecture dependent
symbolic link tree. If you do not create architecture dependent symbolic
link trees, then <audio_root> and
<build_root> are interchangeable.
The configuration files for imake are located in the directory
./AF/config. Makefiles are created from a template file
named Imake.tmpl, a machine-specific .cf file, and a
site-specific site.def file. With only a few exceptions,
configuration parameters are cpp symbols that may be defined on a
per-server basis or for all servers in a given site. The template file
should not be modified.
Site-specific configurations should be described in the file
site.def using the following syntax:
-
#ifndef BuildParameter
#define BuildParameter site-specific-value
#endif
The default parameters used by ./AF/config/site.def are:
- BinDir
- This is the installation directory for binary programs.
- ManDirectoryRoot
- This is used to specify the location where manual pages are to be
installed.
The man pages will be installed in the man{1-8}
subdirectories of MANDIR.
- UsrLibDir
- This is the installation directory for libraries.
- IncRoot
- Header files will be installed in this location.
The default locations in site.def for AF3 have been changed and now use
/usr/local/ which tends to be the most common installation location. We
have included site.def.crl if you wish to use the same default
installation target directories that were used in AF2R2.
As shipped, the configuration files will cause each server supported on a
given operating system to be built. If you wish to limit the build to a
smaller set of servers, you need to customize the appropriate platform
configuration file,
and undefine the unwanted servers.
Building for Debugging
If you wish to build the release with debugging options turned on,
you will need to modify the appropriate .cf file for your system.
You might choose to define the following,
#define ServerCDebugFlags -g
#define DefaultCDebugFlags -g
Alternatively, you can define CDEBUGFLAGS in any individual
Imakefile to enable debugging for specific pieces of the AF
distribution.
Ultrix/RISC Specific Information
We ship the configuration file for Ultrix/RISC,
ultrix.cf, with the DECnet
library specified as an extra library. If you do not have DECnet
installed, simply comment out this line in the configuration file. It is
only necessary to include this library as an extra library, in general,
if your X libraries were built with DECnet support included.
-
#define ExtraLibraries -ldnet
If you plan to use Ultrix 4.3a or later, you should include -oldc
as a switch for DefaultCCOptions definition in the ultrix.cf file. AF does not build
properly when using the newest Ultrix/RISC compiler shipped with 4.3a and
later.
SunOS Specific Information
For properly installing and using the SPARC portion of the AF release you
must be sure to have installed the supplied audio driver and environment
that comes with SunOS 4.1.1 or later. Follow the instructions there for
getting that low level support in place. Once this is done you can then
follow the directions supplied with AF in both the README-V3 document and
this document with the following additional comments:
-
It is necessary to install /usr/demo/SOUND supplied with SunOS 4.1.x.
- You will need to use a compiler that supports function prototypes, for
example gcc. You can get a gcc kit from gatekeeper.dec.com but
consider other GNU mirror sites that might be "closer" or you can go to
the source at prep.ai.mit.edu:/pub/gnu.
-
Edit Makefile.ini . Comment out the first BOOTSTRAPCFLAGS line by placing
a '#' as the first character of the line. Remove the '#' from the second
BOOTSTRAPCFLAGS line and delete everything past the '=' sign, leaving
-
BOOTSTRAPCFLAGS =
-
Edit site.def. Because AFR3 will not compile with the native Sun
compiler, you must use GNU or some other ANSI-compliant compiler. Here are
the lines to add after the "SET THESE PARAMETERS FIRST" comment for GNU
(version 2.4.5):
-
#define HasGcc YES
-
#define CcCmd gcc -DNOSTDHDRS -fstrength-reduce -fpcc-struct-return
Installation Summary
There are several Makefile targets that are generally implemented.
These targets are,
- Makefile
- This causes the Makefile in the current directory to be
rebuilt from its Imakefile source.
- Makefiles
- This causes all Makefile targets in the hierarchy to be rebuilt from
their Imakefile sources.
- clean
- Building this target causes all temporary and derived files to be removed.
- depend
- Will build the dependency rules using the makedepend utility.
This target is generally implemented in the ./AF area only.
- all
- make all will build the defined targets in the current hierarchy.
- install
- make install will install the defined targets in the current hierarchy.
- install.man
- make install.man will install the defined manual pages
in the current hierarchy.
For example, a make clean will perform the clean target action in
the current directory and all subdirectories defined by the existing
Makefiles.
Detailed Build Steps
To install this release of the AF System, you will need to:
-
Finish reading these Release Notes, then return to step 2.
- If you plan to compile the release on more than one machine and have a
distributed file system, you may wish to use the script
./AF/util/scripts/lndir.sh to create symbolic link trees on each
of the target machines. This allows all of the platforms on which you
wish to run AF to share a single set of sources. In either case, the
phrase build tree will be used to refer to the directory tree in
which you are compiling (to distinguish it from the source tree
which contains the actual files).
- Install device drivers as necessary. Pointers to the device specific
driver setld kits are contained in the release notes (below.)
- Check site.def and modify according to your local site
preferences. This file contain the default definitions for BinDir,
UsrLibDir, ManDirectory, and IncRoot. These are also
the most likely definitions that will require changes for a new
installation.
- BinDir
- UsrLibDir
- ManDirectoryRoot
- IncRoot
This step is described in more detail in the section Configuring the
Release(above.)
You might also wish to check the imake configuration parameters in
./AF/config/imakemdep.h and
./AF/config/Imake.tmpl In
general, you will not need to modify these two files.
- Extension code is included in this version of AF. A sample extension
can be configured by adding the following definition to your
site.def or system configuration (*.cf) file.
-
#define ExtensionDefines -DAFTIME
- Look at the platform configuration file for your system. There may be
a line in it that sets a make variable named
BootstrapCFlags. Currently, the configuration files osf.cf,
ultrix.cf, sun.cf, and sgi.cf do not set this variable. If you don't
find such a variable, you can use the following commands to start the
build:
-
% cd <build_root>/AF
% make World >& make.world &
If you do find the variable, you should append that definition to the make
command line, using the make variable BOOTSTRAPCFLAGS. This is used
by imake to set particular cpp symbols for all compiles.
This step will rebuild all of the Makefiles and execute a make -k
all to compile everything in the core distribution. A World build will
take about 10 minutes depending upon system type and file system
location.
- When the make is done, check the log file for any problems.
There should be no errors.
- If you are satisfied that everything has built correctly and you
already have existing audio device driver support installed, you may test
the various programs (server, atest, atime, aevents, aplay etc.) to
verify the operation of the server and device driver. See Testing the Release (below) for further
information.
- If you have previously installed an AF release, you might want to make
backup copies of your old AF header files, binaries, libraries, etc.
- Install the AF targets by,
-
# cd <build_root>/AF
# make install >& make.install
You will either have to do this as root, or have write access to the
appropriate directories.
- If you would like to install the manual pages, type the following at
the top of the build tree:
-
# cd <build_root>/AF
# make install.man
- Make sure that all AF users have the installed binary directory,
BinDir, in their search paths. Also, you may wish to append the
installed man page directory to your MANPATH environment variable.
Release 3 of Version 1 of the AF System should now be ready to use.
Start the appropriate AF server in <build_root>/AF/server/
according to the one of the following manual pages:
Next, try executing some of the AF clients.
- aevents
- Logs all supported events to stdout. (For example, if you have a LoFi,
start aevents and call the phone number for the phone line that is
connected to the module.)
- ahost
- Allows you to control access to your the AF server by other hosts.
- ahs
- Hookswitch control client for LoFi.
- alsatoms
- This client lists the interned atoms.
- apass
- An example client that communicates with two AF servers and manages the
time jitter in the audio devices. This client reads samples from the
input audio server and writes them to the output server with a specified
delay between input and output.
- aphone
- A simple phone dialing application for LoFi.
- aplay
- A play sound file client. There are a few example sound clips in
<audio_root>/sound_files.
- aprop
- Displays properties in an AF server.
- arecord
- Records audio samples from an audio device.
- aset
- Sets and queries various audio devices settings in a server.
We include some additional AF clients in the ./AF/contrib/clients
hierarchy. Clients in this hierarchy may depend upon some external piece
of software. For example, some clients use the Tcl/Tk X toolkit
developed by John Ousterhout at Berkeley.
The Tcl/Tk distribution is available via Internet anonymous FTP from
ftp.cs.berkeley.edu:/ucb/tcl
The 7.2/3.5 distribution of Tcl/Tk has been tested on Ultrix/RISC and
Alpha/OSF. We recommend that you retrieve and install this software to
gain access to several other example AF client applications.
The following are CRL provided client applications that are located in
the ./AF/contrib/clients hierarchy. These clients are not built by
default.
- abrowse
- A Tk based sound file directory browser application.
- aconvert
- A sample rate and sample format conversion utility. Also, see
the libaconvert.a library in the contrib hierarchy.
- adial
- A Tk based phone dialer for LoFI.
- afft
- Real-time FFT displayer. Based on Tk.
- afxctl
- Controls the inputs and outputs and gain of the audio devices in the server.
Also logs AF events.
- atest
- Sends NoOp protocol requests to the server and logs that fact to stdout.
- atime
- Requests an audio device time and logs the time to stdout.
- axset
- A Tk based audio device control panel.
Similar functions as supported by afxctl.
- radio
- Contains a program to multi-cast an audio source and the companion
program to listen to the multi-cast source.
- tkPlay
- A Tk based GUI to aplay. Preferred usage is as the "showaudio" equivalent
for browsing the WWW.
- xplay
- A Motif based audio sound file browser.
- xpow
- Displays the power level of the recorded audio on the specified audio
device.
Building Contrib
The simplest way to build the contrib tree is to type the following
commands,
-
% cd <build_root>/AF/contrib
% make Makefile Makefiles clean depend all
and as root,
-
# cd <build_root>/AF/contrib
# make install install.man
This sequence will build the library and clients in the contrib
hierarchy before installing all appropiate targets.
If you do not have some of the external dependencies installed, you may
have to be more selective about how you build the contrib clients.
We provide device driver kits for DEC OSF/1 Alpha AXP workstation
base board audio , LoFi, and Personal DECstation base board audio
devices. These kits are in setld format.
Alpha Base-Board Audio Device (/dev/streams/bba)
The audio server for the Alpha AXP workstations are dependent upon the
bba audio device driver. Information on how to install the device driver
for the base board audio can be found in:
- OSF/1 Alpha
- <audio_root>/devices/axp/driver/README
The bba driver in this AF kit is for OSF/1 Alpha workstations
running V1.2 (the first official external release) only. If you are
running V1.3 or later, you merely need to add the appropriate bba
configuration line to you systems config file. The bba driver is already
included in the base system on V1.3. Do not install the driver from the
AF kit if your are running OSF/1 V1.3 or later.
Alpha (Jensen) Microsoft Sound Card (/dev/msb)
The audio server for the Microsoft Sound Card (Alpha PCs) are dependent
upon the msb audio device driver. Information on how to install the
device driver for the msb audio can be found in:
- OSF/1 Alpha
- <audio_root>/devices/axp150/msb/README.msb
If you have already installed the msb driver shipped with the Beta
test version of AF3R1 then you must deinstall the field test driver and
install the version shipped with this kit. Otherwise you may notice
system hangs.
LoFi (DECaudio) TURBOchannel Audio Device (/dev/lofi)
Information on how to install the device driver for
LoFi (a.k.a. DECaudio) can be found in:
- Ultrix/RISC
- <audio_root>/devices/lofi/driver/mips.src/lofi.4
- OSF/1 Alpha
- <audio_root>/devices/lofi/driver/alpha.src/README
<audio_root>/devices/lofi/driver/alpha.src/lofi.7
Personal DECstation Base-Board Audio Device (/dev/bba)
The audio server for the Personal DECstation audio device is dependent
upon the /dev/bba device driver. Information on how to install the
device driver for the Personal DECstation audio can be found in:
- Ultrix/RISC
- <audio_root>/devices/maxine/driver/mips.src/bba.4
The LoFi audio device has an external DSP port compatible with the
DSP port on NeXT computers. We have done some minimal testing of our LoFi
server with the following DSP port devices:
- Ariel Pro-Port (Model 656)
- Ariel Digital Microphone (DM-N)
- Applied Speech Technologies AST A/D16
- Protocol Change
- Now at AF Version 3 Release 1.
- Multiple Devices
- A single server does not yet support more than one physical device
(e.g., LoFi) in the same machine. Much of the structure to support this
is there, but some work must still be done. It is possible to run
multiple servers on a single host, however, thus allowing clients to
access multiple LoFi devices on a given machine.
- setld
- If you need to install a device driver from this kit, be sure to invoke
the setld command from the source tree and not the corresponding
symbolic link tree (if it exists). setld will not succeed if you
invoke it from the link tree.
- DSP56K
- We do not provide the DSP tools in this distribution. If you wish to do
development of DSP56001 code on LoFi, contact Motorola or any other
manufacturer of code development software for the DSP56001 processor. The
source files for the DSP56001 used by the LoFi and J-Video server are
included. The audio servers expect to read the lod file format
images.
Right now, the various audio channels supported by a server are
assigned integer device numbers in approximately random order. There
should be a more symbolic way to talk about "the local loudspeaker" or "the
telephone".
It should be possible to reconfigure the DSP port interface on DECaudio
dynamically, rather than only at server initialization time.
Right now we have separate servers for each audio device on a particular
machine. A single server should be able to support all configured devices.
A single server should be able to support multiple devices of the same kind
as well. This is not a design issue, just implementation.
On Alpha/OSF we should be able to dynamically link to the POSIX real-time
library and use it to good advantage.
If you retrieved and installed the companion AF kit,
AF2R2-other.tar, you will have a few sample Hi-Fi sound files in
<audio_root>/sound_files/xan*. The audio examples are excerpts
from the piece Xanadu by Joseph T. Kung. It was realized using
Barry Vercoe's Csound during a computer music course run by Prof. Vercoe
at the MIT Media Lab's Music and Cognition Group in December 1988. The
companion kit contains 16, 44.1, and 48 KHz versions of Xanadu.
Guido van Rossum contributed device dependent code for SGI Indigo.
Wes Whitnah contributed extension code, AFsox library,
and several bug fixes.
We have established a mailing list, af@crl.dec.com, for general
discussions about AF. To be added to or removed from this mailing list,
please send mail to, af-request@crl.dec.com
You may report problems with the AF software by sending mail to
af-bugs@crl.dec.com. Please be specific as possible when
describing the problem and include source code for a small test case if
possible. Also, state your current patch revision (as found in
./patchlevel.h).
You can obtain information on Digital's products through the
Digital Information W3 server.
We hope you enjoy this AF release.
See this file for Copyright information.
af-bugs@crl.dec.com