APRL commands


Contents


Introduction

This is a complete list of the Tcl commands defined by APRL to create signal processing objects. They all take the form:

opcode name [-opt val [-opt2 val ...]]

where opcode is the object-creating command, name is the name of the new signal processing object, and opt and val are pairs of configuration options.

Creating an object has several effects. Firstly, a new signal processing module is created and added to the global scheduler (which must have been created already with the scheduler command). Secondly, if that module generates a signal output (i.e. unless it is a `sink' object), it registers that output stream against name in the source lookup table. It also updates a global record of the most-recently created stream source which is used for default inputs to modules for which no explicit input is specified.

Thirdly, it creates a new Tcl command, name which can be used for further interaction with that object. (This is modeled after the `object-oriented' approach recommended by Dr. Ousterhout in his book on Tcl). The new command can be used to change the configuration options, for instance:

name config -input source

will change the input stream to the object name to come from the object source. In further keeping with the Tk style of object- orientation, the "cget" command is also specified. Thus, to query the name of the current input source for a particular object, one enters:

name cget -input

.. which would be expected to return source if the preceding command had been executed.


Sources

Source objects introduce a new signal stream, thus, every chain of signal processing objects must start with a source object. Currently, this stream may originate from the live audio input (e.g. a microphone), from a sound file stored on disk, or from a spontaneous noise source.

Source objects

Common source commands

All source objects accept the following commands.

Sinks

Sinks are processing objects that take a single input stream. A pure sink does not generate any output stream, thus its name does not refer to any data source (and cannot be used as an input). Processing chains, being data-flow, can end anywhere, but a chain that leads to a sink isn't going any further (although other objects may connect to the same stream that the sink is using as input, and take it somewhere else). Currently sinks take a stream and write it to real-time output, save it to a soundfile, or display it on the screen.

Sink objects

Common sink configuration options


Pipe objects

A pipe is, both notionally and in terms of its implementation, the combination of a sink (input) and a source (output), presumably with some processing inbetween. As such, they inherit the configuration options and commands of sources and sinks as described above.

Objects

Common pipe configuration options

Common pipe commands

The other commands accepted by pipe objects all refer to the output part of the pipe, which behaves like any other data stream source.

Combiners

Combiners take two inputs to generate a single output. (The second input is specified by the -in2 option, see configuration options below). Common examples are the dyadic functions of algebra. Since there are so many of these, it was worth making them into a separate type, rather than trying to generalize pipes to multiple inputs.

Although not currently supported, the intention is to allow both inputs to a combiner to be data sources, literal constants or Tcl variables. It would even be feasible to allow combiners to combine inputs with different sampling rates - probably by linearly interpolating the slower of the two. At the moment, APRL bails unceremoniously if you try to connect inputs of different sampling rates to the same combiner.

Combiner objects

Common combiner configuration options

Common combiner commands

The other commands accepted by combiner objects all refer to the output part of the pipe, which behaves like any other data stream source.

Display commands

See also the wavesink object.

Objects


Other commands

The scheduler

Before definining any signal processing objects, it is necessary to define a scheduler object. All the signal processing objects are registered with the scheduler, which then arranges to call them in the right order.

The scheduler is also created as a new Tcl `object' command, so it is possible to have more than one scheduler in existence; however, we haven't thought of any good uses for this, so it is not fully supported (you can't specify to which scheduler a given object belongs).

The scheduler object is created by the following command:

scheduler sched [-timestep step] [-nowtime time] [-command cmd] [-docmd do]

The new scheduler sched will attempt to compute step second's worth of data at each invocation (default 0.1). It will start at time time, in case there are sources (such as perhaps a future version of soundfsrc) that respond to the absolute value of the current time.

If cmd is set to a string and do is non-zero (it is zero by default), then cmd will be evaluated by the tcl interpreter after each update of the signal processing network in response to a step command. The default value is:

after 10 { %s step }

which causes the scheduler to run autonomously once do is set. In the command string, %s is replaced by the name of the scheduler (as in the default string), and %t is replaced by the time in seconds up to which the signal processing network has just been completed. Other commands (such as updating timelines or other screen elements) can be usefully included in the command string.

Specific commands

sched step

causes the scheduler to calculate another block of time, update its idea of nowtime, and execute the command string if the docmd option is set.


Go on to the C Code Page .

Go back to the APRL Page .


DAn Ellis <dpwe@media.mit.edu>
MIT Media Lab Perceptual Computing

$Header: /ti/http/projects/aprl/RCS/commands.html,v 1.8 1996/02/07 00:17:55 dpwe Exp $