| mp4-sa-> the mp4-sa book-> instrument control->the SASL score language |
Sections
|
SASL Commands: |
IntroductionSASL (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 ScoresA 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 CommandThe SASL instr command creates a new instance of a SAOL instrument. The right panel shows the syntax of the command. SyntaxAn 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. SemanticsWhen 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 CommandThe SASL control command changes the value of a SAOL variable. The right panel shows the syntax of the control command. SyntaxThe 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. SemanticsWhen 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 CommandsThe SASL tempo and end commands change the behavior of the SAOL program execution. The right panel shows the syntax for both commands. Tempo CommandWhen 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 CommandWhen 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 Syntaxtrigger 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 Syntaxtrigger 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 CommandThe SASL table command acts to create wavetables in a SAOL program. The right panel shows the syntax of a table command. SyntaxThe 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. SemanticsThe 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 TablesAs 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. |
Syntaxtrigger 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 Score5 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 SASLIn 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 FlagsSeveral 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. |
|
| mp4-sa-> the mp4-sa book-> instrument control->the SASL score language |