From The MPEG-4 Structured Audio Book by John Lazzaro and John Wawrzynek.

Part III/1: The SASL Score Language

Sections

SASL Commands:

instr control tempo end table

Introduction

SASL (pronounced "sassil") is the score language for MP4-SA.

A SASL score is an unordered list of SASL commands. A SASL command performs a single action at a moment in time, such as changing the value of a SAOL variable or creating a new instance of a SAOL instrument.

The three examples in the tutorial in Part I introduce most of the SASL commands. The right panel has direct links to the examples.

In this chapter, we explain how a SASL score interacts with a SAOL program, and describe the five types of SASL commands. We also discuss the use of SASL commands in streaming and real-time applications of MP4-SA.

From Part I:

Example 1. Introduces the SASL instr and end commands.

Example 2. Shows how to initialize instrument parameters with the SASL instr command. Introduces the SASL tempo command.

Example 3. Shows how to label SASL instr commands. Introduces the SASL control command.

SASL Scores

A SAOL program executes by moving a simulated clock forward in time, performing calculations along the way in a synchronous fashion. A SASL score is a list of commands that trigger actions relative to the clock time.

SASL commands are one line long. The newline marks the end of the command.

A SASL command is a list of elements, separated by spaces (and for some parts of some commands, colons). These elements may be floating-point nunbers, SAOL and SASL keywords, and the instrument and variable names from the companion SAOL program.

The first number on a SASL command line indicates the trigger time for the command. The order of commands in a SASL score has no semantic meaning. Instead, the trigger times of commands in a SASL score indicate the order that the commands are executed.

Since command order has no meaning, a SASL score may span several ASCII files with no semantic loss. MP4-SA tools concatenate the score files and execute each SASL command at the appropriate time.

A SAOL program processes SASL commands at k-rate granularity. It compares the simulated clock value with the trigger times of SASL commands, and runs unexecuted commands that have a trigger time older than the current clock value.

The simulated clock has units of seconds, while command trigger time has units of beats. At each k-pass, trigger times are converted from beats to seconds, using the current value of the global tempo.

The global tempo has a default value of 60 beats per minute, or one beat per second. The core opcode settempo lets SAOL instruments change the tempo value, and the tempo command lets a SASL score change the tempo.

In the following sections, we describe the semantics of the SASL commands. In Part III/3, we present a table that shows the exact execution order of these commands in a SAOL simulation.

 

Instr Command

The SASL instr command creates a new instance of a SAOL instrument. The right panel shows the syntax of the command.

Syntax

An instr command optionally begins with a label. The SASL control command uses this label to reference the instance. The label name must obey the naming rules described in Part II/1. Multiple instr commands may use the same label name.

The first required element is the trigger time. The trigger time is a floating-point value, in units of beats, that indicates when to create the instance.

The trigger time is followed by the name of the SAOL instrument to instantiate. Following the name is a floating-point duration value that indicates how long the instance should execute.

The command ends with a list of floating-point values for initializing the instrument parameters of the new instance.

Semantics

When a SASL instr command triggers, it creates an instance of the specified SAOL instrument. See the previous section for details on when a SASL command triggers.

The instrument parameters of the new instance are set to the initialization values specified by the command. If the command has too few values, the remaining instrument parameters are set to zero.

If the duration value is -1, the instance executes indefinitely. Otherwise, the duration value indicates how long the instrument should execute, in units of beats.

At the start of each k-pass, a termination time is computed, by using the global tempo to convert the duration value from beats to seconds, and adding this value to the creation time of the instance.

If this termination time is less than or equal to the current clock time, the instance is scheduled for termination at the end of the current execution cycle.

A table in Part II/3 shows the timing of instance creation and termination in an orchestra cycle.

Instr Command Syntax:

[label :] trigger name dur p1 p2 ...



label: optional text label that 
tags the instr command for
reference by the control 
command. the text label follows 
the lexicography of SAOL names.

trigger: floating-point 
number, the starting time for 
the instance, in units of 
beats.

name: the name of the SAOL 
instrument to instantiate.

dur: floating-point number
the duration of the instance,
in units of beats. a value
of -1 indicates indefinite
duration.

p1, p2 ...: floating-point
numbers, the values of
the instrument parameters
to use during initialization.


Examples:

0.394 sawtooth 0.4 -12.3

1.203 trumpet 23.4 1 3 45.0

top: 1 square -1 

Relevent Tutorial Examples:

Example 2. Shows unlabeled instr commands, with finite durations, that are modulated by tempo changes.

Example 3. Shows labelled instr commands.

Control Command

The SASL control command changes the value of a SAOL variable. The right panel shows the syntax of the control command.

Syntax

The command begins with the trigger time, that indicates when to change the value of the SAOL variable.

The trigger time is followed by an optional label element, that refers to instances created by labelled SASL instr commands. The label name must obey the naming rules described in Part II/1.

Following the keyword control is the name of the SAOL variable to change, and the new floating-point value for the variable.

Semantics

When a control command triggers, it changes the value of a SAOL variable.

The command has different semantics, depending on the presence of the optional label element.

If no label is present, the command changes the SAOL global variable with the specified name to the new value. Both i-rate and k-rate global variables may be targeted.

If a label is present, then all instances created by SASL instr commands with that label are examined. If an instance has an imports variable with the specified name, the command changes the variable to the new value.

Variables targeted by labelled control commands must be k-rate. Variables in user-defined opcodes are not reachable by labelled control commands.

The table in Part II/3 shows the timing of control command during an orchestra cycle.

Control Command Syntax:

trigger [label] control var number



trigger: the time to execute the 
control command, in units of beats.

label: optional text label that 
links the control command to an
instr command.

var: name of the SAOL variable to
change. if no label is present in
control command, changes a global
variable in the SAOL program. if
a label is present, changes an
instrument imports variable that
has no matching global variable.

number: the new value for the
variable. 


Examples:

0.102 control freq 12.0

10.23 rainbow control ampl 2


Relevent Tutorial Example:

Example 3. Shows labelled control commands that change an instrument variable, and unlabelled control commands that change a global variable.

Tempo and End Commands

The SASL tempo and end commands change the behavior of the SAOL program execution. The right panel shows the syntax for both commands.

Tempo Command

When the tempo command triggers, it changes the value of the global tempo. Tempo values in SAOL have units of beats per minute.

If multiple tempo commands trigger in a k-cycle, the command with the latest trigger time sets the new tempo value.

End Command

When the end triggers, it ends the simulation, and no further audio is produced. The end command with the earliest trigger time has precedence.

The table in Part II/3 shows the timing of tempo and end commands during an orchestra cycle.

Tempo Command Syntax

trigger tempo number



trigger: the time to execute the 
tempo command, in units of beats.

number: the new value of the tempo,
in units of beats/minute.


Examples:

0.283 tempo 130.0

0.12  tempo 4

End Command Syntax

trigger end


trigger: the time to end the 
SAOL simulation, in units of
beats.


Examples:

129.0934 end


Relevent Tutorial Example:

Example 2. Uses multiple tempo commands to modulate a melody line. Also uses the end command.

Table Command

The SASL table command acts to create wavetables in a SAOL program. The right panel shows the syntax of a table command.

Syntax

The command begins with the trigger time, that indicates when to create the SAOL table.

The keyword table is followed the name of the wavetable to create, and the wavetable generator for initializing the table. The specified generator must be one of the SAOL wavetable generators, or the special keyword destroy.

The command ends with a list of parameters to supply to the wavetable generator.

Semantics

The table command specifies a SAOL wavetable. When the command triggers, this SAOL wavetable is changed as described below.

If this wavetable is a global wavetable in the SAOL program, the contents of this wavetable are replaced by a new wavetable. The new wavetable is created by the specified generator, which is run using the specified parameters.

If the wavetable generator element is specified as the keyword destroy, the current contents of the wavetable are destroyed, and can no longer be accessed by the SAOL program.

The table in Part II/3 shows the timing of table commands during an orchestra cycle.

Future Tables

As we described in Part II/4, a SAOL instrument may declare a wavetable as imports table even if no global wavetable exists with the same name.

If the wavetable specified in the table command is not a global wavetable, the wavetable is created as a new global wavetable, or future wavetable.

The wavetable is created by the specified generator, which is run using the specified parameters.

Once the future wavetable is created, calls to instruments that import the table may legally execute, with semantics identical to global tables.

Syntax

trigger table var gen p1 p2 ...



trigger: the time to execute the 
table command, in units of beats.

var: name of the SAOL table to
change. may be a global table,
or an instrument import table
that has no matching global
table.

gen: wavetable generator to 
use to initialize the table.
see Part II/4 for the list
of wavetable generators. gen
may also be the keyword 
destroy, which destroys
any existing wavetable created
for this wavetable name.

p1, p2 ...: parameters for
the wavetable generator, 
see Part II/4 for
legal parameter lists for
the different wavetable 
generators.

Example SASL Score

5 table orig data 3 4 5 6
10 table newtable data 3 7 8 9
15 newtone 10

Companion SAOL Program

// first table line of 
// SASL score replaces
// global table orig

globals {
table orig(data, 3, 1,2,3);
}


instr newtone () {

// second line of SASL
// creates newtable.
// note that newtone
// instance is created
// after newtable is
// created

imports table newtable;

}

Streaming and SASL

In the examples in the tutorial in Part I, an ASCII file contains all the SASL commands for a performance. Some of these examples use sfront to create a binary encoding of the SAOL and SASL files. This program places all the SASL commands at the start of the file, and encodes the trigger times for all commands.

A binary MP4 encoding that has SASL commands distributed throughout the file is a better match for some applications. For example, an application for real-time audio streaming over a slow computer network could benefit from distributed SASL commands. In this case, SASL commands occuring later in the performance are not needed immediately, and may be postponed without affecting the audio output.

The MP4 binary file format has provisions for distributed SASL commands. Trigger times are optional for these commands, to support efficient encoding for real-time streaming applications over a low-latency network.

Distributed commands without timestamps are executed at the next opportunity for executing commands of its type in the execution order. Distributed commands with timestamps follow the trigger semantics described in an earlier section in this chapter.

Real-time Flags

Several flags may be added to SASL commands for real-time applications. A "*" may be added to each command, indicating that the command is a "high-priority" event that should be executed even if CPU cycles are scarce.

A "use-if-late" flag may also be added to the binary encoding of a distributed SASL command, that instructs the decoder to execute a command even if latency problems result in an MP4 data stream falling "out of sync" with real-time.

Next: Part III/2: MIDI Instrument Control

 


Copyright 1999 John Lazzaro and John Wawrzynek.