Overview of APRL
Quick Index
- This page has an overview of what APRL is and what it's good for.
- The Using APRL Page describes how to
run APRL.
- The Commands Page is a complete reference
on the APRL opcode set.
- The C Code Page describes how to add
your own C functions to APRL.
- There will soon be a directory of example programs.
- The ToDo list describes the various aspects
of APRL that we haven't done yet, but hope to soon.
- The Changes page keeps a log of the
changes that happen to the actual sources.

APRL is an object-oriented language built in C, C++, and Tcl. It consists
of a real-time scheduling system and a specification
language for defining a signal
processing network to operate on audio data.
While you don't have to know much about Tcl to get started with APRL,
you can use Tcl and the Tk toolkit to augment APRL's capabilities
immensely and build many clever applications.
If you don't know Tcl already, a good introduction is the book
Tcl and the Tk Toolkit by John Ousterhout.
Basic Description
APRL programs have to do two major things: they have to create
a signal processing network, and they have to run data through that
network.
The basic data structure in APRL is the sound processing object .
Objects get linked together to form a signal processing network, and
come in four basic types:
- Source objects produce data streams. Some source objects are
live audio input, sound files, and random-number generators.
- Sink objects use data streams to produce output. Some
sinks do things like produce sound from the DAC, or display a graph on
the screen.
- Pipe objects take a data stream as an input, and produce
a new one as an output, generally modifying it in some way. Examples of pipes
are filters, differentiators, and power calculators. Most of the objects
in an APRL program are pipes.
- Combiner objects take two data streams and merge them
into one, for example by adding them together.
In addition to these four kinds of objects, there are two special kinds
of objects:
- User-procedure objects allow C code to be linked in to
an APRL program.
- Every APRL program has exactly one scheduler object . The
scheduler synchronizes the operations of all the other objects in the
program.
A Small Example Program
Here is an example of a small APRL program, which we will examine line
by line.
scheduler s
audiosrc as -sampleRate 11025
bpfilter bpf -centerFreq 440 -input as
rms pwr -sampleRate 100
dB . -ref 0.01
wavesink .ws1 -scale 0.05
pack .ws1
proc run {} {
s step
after 10 {run}
}
run
The effect of this program is to calculate the power of the live
audio signal in a narrow band centered on 440 Hz (the 'A' above middle
'C'), and display the power in a graph on the screen.
- scheduler s
The scheduler opcode creates a scheduler object. We name
it s in this example.
- audiosrc sound -sampleRate 11025
The audiosrc opcode creates a source object which takes its input
from the live audio feed of the SGI. The Audio Control Panel can be
used to switch this between Mic, CD, or other sorts of live Input.
In this example, we are sampling at 11025 Hz, and we
name the source sound.
- bpfilter bpf -centerFreq 440 -input sound
The bpfilter opcode creates a pipe object which
band-pass filters its input. We have connected the output of the
live audio source, sound, to the input of this pipe, and we
call the pipe bpf.
- rms pwr -sampleRate 100
The rms opcode creates a pipe object which calculates the
rms power of its input. In this example, we have not specified an input
object, so the last object created (bpf) is used by default.
Notice that this object produces an output which is at a different
sampling rate (100 Hz) than its input (11025 Hz).
- dB . -ref 0.01
dB is a pipe which converts a linear power value to a
decibel level.
The '-ref' parameter specifies that a linear value of 0.01 should be
converted to 0 dB. We use '.' as the name of the object to indicate
that a name is not needed. Again, it uses the output from
the previous object, pwr, as the input.
- wavesink .ws1 -scale 0.05
The wavesink opcode creates a sink object which displays
a signal on the screen. The 'scale' specifies a multiplier for the
input to convert it into a 0:1 range. The resulting object is
called .ws1; the initial dot indicates that it is a Tk display
object. Again, we we use the output from the previous, unnamed,
dB pipe as the input. Note that all of the previous commands
could have been connected in this fashion; the names sound,
bpf, and pwr are not actually needed.
- pack .ws1
pack is a Tk command which puts the display object .ws1
on the screen.
- proc run {}
We are defining a new Tcl command and calling it run.
- s step
We send a 'step' message to the scheduler object s. This causes
the scheduler to execute all of the objects in the network for a little
while.
- after 10 {run}
We register a request with the main Tk event loop to execute the
run command again after a brief delay (nominally 10 milliseconds).
This allows the current command to finish, and the other tasks (such
as screen updates) to take place before executing the next step of the
signal processing. Using a more intuitively appealing "while {1} " loop
would never return control to the event loop, preventing
graphical output and user interface interaction.
- run
Executes the run procedure, causing the signal processing
network to activate.
Go on to the APRL commands page.
Go back to the APRL page.
eds@media.mit.edu
MIT Media Lab Perceptual Computing Section
$Header: /ti/http/projects/aprl/RCS/overview.html,v 1.2 95/02/26 19:01:14 dpwe Exp $