The MP4-SA Book: Part III/1: The SASL Score Language
Description: The SASL Score Language. Describes the semantics of score files, and the command lines for creating SAOL instances, modifying SAOL variables and tables, and setting tempo.
Keywords: MP4-SA, SASL, instr, command, table, tempo, end, streaming, priority, use if late

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

# Part III/1: The SASL Score Language

## Sections Introduction. SASL Scores. Triggering semantics. Instr Command. Creating instances of instruments. Control Command. Changing SAOL variables. Tempo and End Commands. Changing simulation behavior. Table Command. Updating wavetables using SASL. Streaming and SASL. Real-time flags for SASL. | ## 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. SASL commands in a score file need not appear in order of execution. The trigger time of commands in a SASL score indicate the order that the commands are executed. The first number on a SASL command line indicates indicates the trigger time for the command. A SASL score may span several ASCII files. 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 less than or equal to 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.