SAOL / SASL Quick Reference

This quick-reference document is intended to provide an overview of the syntax of the MPEG-4 structured audio languages. No attempt has been made to cover all of the complexities of the SAOL language, such as the rate and width semantics governing evaluation of expressions and control structures. For a full description of MPEG-4 SA please consult ISO/IEC 14496-3 sec5 available from the MPEG-4 structured audio home page: http://sound.media.mit.edu/mpeg4/

Top-level constructs

// global block:
global{ [global statements] }

// instrument definition:
instr name( [ pname1[, pname2 ...] ] )[ preset int [int ...] ]{
   [variable declarations]
[instrument statements] }

// opcode definition:
opcoderate name( [ prate p0name[, prate p1name ...] ] ){
   [variable declarations]
[opcode statements] }
// opcoderate is one of: aopcode, kopcode, iopcode, opcode
// prate is one of: asig, ksig, ivar, xsig
// formal params can be arrays and can also be table references.

// template declaration:
template< name[, name ...] > [ preset maplist ]( [ pname1[, pname2 ...] ] )
map{ ident[, ident ...] }with{ maplist }{
   [variable declarations]
[opcode statements] }

// special initialisation instrument
instr startup( ... ){ ... }
// if defined, the startup instrument is run at i-rate after global
// variables have been initialised to 0 but before global tables are
// instansiated.

Global statements

// global parameters:
srate int;// default 32000 Hz
krate int;// default 100 Hz
inchannels int;// defaults to number of input sources or 0
outchannels int;  // default 1
interp int;// 0==low, 1==hi. default low

// global variable declarations:
ivar name[, name ...]; // names can be single valued or arrays: name[length]
ksig name[, name ...]; // where length can be an int, inchannels or outchannels
table name(genroutine, size[, genparams ...]);

// bus routing, effect instruments and instrument evaluation order:
route(bus, instr1[, instr2 ...]); // routes outputs of instrs onto bus
send(instr; [instrParams]; bus1[, bus2...]);  // create instr to process busses
sequence(instr1[, instr2 ...]);// define evaluation order for instruments

Instrument variable declarations

[sharingtag] ivar name[, name ...]; // sharingtag: imports, exports, imports exports
[sharingtag] ksig name[, name ...];
asig name[, name ...];

// ivar, ksig and asig names can be single valued or arrays:
name[ int ]  // int can be a literal or inchannels or outchannels

table name(genroutine, size [, genparams ...]);  //local wavetable
sharingtag table name[, name ...];// wavetable placeholder
oparray opname[int];
tablemap name(table1[, table2 ...]);

Instrument statements

// control structures:
if( expr ){ [instrument statements] }
if( expr ){ [instrument statements] }else{ [instrument statements] }
while( expr ){ [instrument statements] }
instr name([p0, ...]) //create a new instrument instance

// signal output:
output(signal1[, signal2 ...]);
spatialize(signal, azimuth, elevation, distance);
outbus(bus, signal1[, signal2 ...]);
// note lifetime:
extend( expr );
turnoff;

// other:
lvalue = expr;  // evaluate expr and assign its value to lvalue
expr;// evaluate expression (execute opcodes etc)

Arithmetic and logical operators (in order of precedence)

!// logical negation (not)
-// arithmetic negation (unary minus)
*, /// multiplication, division
+, -// addition, subtraction
<, >, <=, >=// relational
==, !=// equality, inequality
&& // logical and
|| // logical or
expr ? expr : expr  // switch

Miscellaneous expressions

( expr ) // expression grouping
name[expr] // array or tablemap access
opcodename(expr[, expr]) // opcode call
opcodename[expr]( expr[, expr])  // oparray call

Standard names

k_rate// control rate in Hz
s_rate// sampling rate in Hz
inchan// number of channels of input to current instrument
outchan// number of channels of output by current instrument (see DCOR2.10)
time// instantiation time of current note
dur// duration of note or -1 if unknown
itime// elapsed time of note in seconds
MIDIctrl[128]// MIDI controllers for current instrument channel
MIDItouch// polyphonic aftertouch for current note
MIDIbend// pitch bend for current instrument channel
channel// extended MIDI channel of current note
preset// preset of current note
input[inchannels]// input signal(s) provided by the send instruction
inGroup[inchannels]// grouping of input signals to current note
released// 1 if note is about to be destroyed, otherwise 0
cpuload// approximate cpu usage of current note
position[3]// BIFS scene graph node position
direction[3]// BIFS scene graph node direction
listenerPosition[3]// BIFS scene graph listener position
listenerDirection[3]  // BIFS scene graph listener direction
minFront, maxFront// radiation pattern of soundNode see ISO/IEC 14496-1 c9
minBack, maxBack// radiation pattern of soundNode see ISO/IEC 14496-1 c9
params[128]// params of BIFS AudioFX node

Mathematical Functions

opcode int(xsig x)
opcode frac(xsig x)
opcode dbamp(xsig x)
opcode ampdb(xsig x)
opcode abs(xsig x)
opcode sgn(xsig x)
opcode exp(xsig x)
opcode log(xsig x)
opcode sqrt(xsig x)
opcode sin(xsig x)
opcode cos(xsig x)
opcode atan(xsig x)
opcode pow(xsig x, xsig y)
opcode log10(xsig x)
opcode asin(xsig x)
opcode acos(xsig x)
opcode ceil(xsig x)
opcode floor(xsig x)
opcode min(xsig x1[, xsig ...])
opcode max(xsig x1[, xsig ...])

Pitch Converters

opcode gettune()
kopcode settune(ksig x)
opcode octpch(xsig x)
opcode pchoct(xsig x)
opcode cpspch(xsig x)
opcode pchcps(xsig x)
opcode cpsoct(xsig x)
opcode octcps(asig x)
opcode midipch(asig x)
opcode pchmidi(asig x)
opcode midioct(asig x)
opcode octmidi(xsig x)
opcode midicps(xsig x)
opcode cpsmidi(xsig x)

Tempo Functions

opcode gettempo([xsig dummy])
kpcode settempo(ksig x)

Noise generators

iopcode irand(ivar p)
kopcode krand(ksig p)
aopcode arand(asig p)
iopcode ilinrand(ivar p1, ivar p2)
kopcode klinrand(ksig p1, ksig p2)
aopcode alinrand(asig p1, asig p2)
iopcode iexprand(ivar p1)
kopcode kexprand(ksig p1)
aopcode aexprand(asig p1)
kopcode kpoissonrand(ksig p1)
aopcode apoissonrand(asig p1)
iopcode igaussrand(ivar mean, ivar var)
kopcode kgaussrand(ksig mean, ksig var)
aopcode agaussrand(asig mean, asig var)

Table operations

opcode ftlen(table t)
opcode ftloop(table t)
opcode ftloopend(table t)
opcode ftsr(table t)
opcode ftbasecps(table t)
kopcode ftsetloop(table t, ksig x)
kopcode ftsetend(table t, ksig x)
kopcode ftsetbase(table t, ksig x)
opcode tableread(table t, xsig index)
opcode tablewrite(table t, xsig index, xsig val)

Table based generators

aopcode oscil(table t, sig freq[, ivar loops])
aopcode loscil(table t, sig freq[, ivar basefreq, ivar loopstart, ivar loopend])
aopcode doscil(table t)
kopcode koscil(table t, ksig freq[, ivar loops])

Signal generators

kopcode kline(ivar x1, ivar dur1, ivar x2[, ivar dur2, ivar x3, ...])
kopcode aline(ivar x1, ivar dur1, ivar x2[, ivar dur2, ivar x3, ...])
kopcode kexpon(ivar x1, ivar dur1, ivar x2[, ivar dur2, ivar x3, ...])
aopcode aexpon(ivar x1, ivar dur1, ivar x2[, ivar dur2, ivar x3, ...])
kopcode kphasor(ksig cps)
aopcode aphasor(asig cps)
aopcode pluck(asig cps, ivar buflen, table init, ksig atten, ksig smoothrate)
aopcode buzz(asig cps, ksig nharm, ksig lowharm, ksig rolloff)
aopcode grain(table wave, table env, ksig density, ksig freq, ksig amp, ksig dur, ksig time, ksig phase)

Filters

kopcode port(ksig ctrl, ksig htime)
aopcode hipass(asig input, ksig cut)
aopcode lopass(asig input, ksig cut)
aopcode bandpass(asig input, ksig cf, ksig bw)
aopcode bandstop(asig input, ksig cf, ksig bw)
aopcode biquad(asig input, ivar b0, ivar b1, ivar b2, ivar a1, ivar a2)
aopcode allpass(asig input, ivar time, ivar gain)
aopcode comb(asig input, ivar time, ivar gain)
aopcode fir(asig input, ksig b0[, ksig b1, ksig b2, ksig ...])
aopcode iir(asig input, ksig b0[, ksig a1, ksig b1, ksig a2, ksig b2, ksig ...])
aopcode firt(asig input, table t[, ksig order])
aopcode iirt(asig input, table a, table b, ksig order)

Spectral analysis

specialop fft(asig input, table re, table im[, ivar len, ivar shift, ivar size, table win])
aopcode ifft(table re, table im[, ivar len, ivar shift, ivar size, table win])

Gain control

specialop rms(asig x[, ivar length])
aopcode gain(asig x, ksig gain[, ivar length])
aopcode balance(asig x, asig ref[, ivar length])
aopcode compressor(asig x, asig comp, ksig thresh, ksig loknee, ksig hiknee, ksig ratio, ksig att, ksig rel, isig look)

Sample conversion

specialop decimate(asig input)
asig upsamp(ksig input[, table win])
specialop downsamp(asig input[, table win])
opcode samphold(sig input, ksig gate)
specialop sblock(asig x, table t)

Delays

aopcode delay(asig x, ivar t)
aopcode delay1(asig x)
aopcode fracdelay(ksig method[, xsig p1, xsig p2])

Effects

aopcode reverb(asig x, ivar f0[, ivar r0, ivar f1, ivar r1, ivar ...])
aopcode chorus(asig x, ksig rate, ksig depth)
aopcode flange(asig x, ksig rate, ksig depth)
kopcode fx_speedc(ivar speed_control_factor)
iopcode speedt(table in, table out, ivar factor)

Core wavetable generators

table name(sample, size, which[, skip])
table name(data, size, p1, p2, p3, ...)
table name(random, size, dist, p1[, p2])
table name(step, size, x1, y1, x2, y2, ...)
table name(lineseg, size, x1, y1, x2, y2, ...)
table name(expseg, size, x1, y1, x2, y2, ...)
table name(cubicseg, size, infl1, y1, x1, y2, infl2, y3, ...)
table name(spline, size, x1, y1, k2, x2, y2, k3, ...)
table name(polynomial, size, xmin, xmax, a0, a1, a2, ...)
table name(window, size, type[, p])
table name(harm, size, f1, f2, f3, ...)
table name(harm_phase, size, f1, ph1, f2, ph2, ...)
table name(periodic, size, p1, f1, ph1, p2, f2, ph2, ...)
table name(buzz, size, nharm, lowharm, rolloff)
table name(concat, size, ft1, ft2, ...)
table name(empty, size)

SASL syntax

// note that the optional * at the beginning of a score line indicates that the
// event is a ‘high priority’ event.

// instrument instansiation:
[*] [label :] time instrname duration [float ...]

// control value update:
[*] time [label] control varname value

// tempo change:
[*] time tempo value

// table creation / update (genname can be destroy)
[*] time table gwtname genroutine size [genparams]

// end of score:
end