mp4-sa-> the mp4-sa book-> instrument control->in SAOL

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

Part III/3: SAOL Instrument Control

Sections

In This Chapter

Statements:

instr extend turnoff

Standard Names:

cpuload dur itime time released

Introduction

In the previous chapters in Part III, we describe the SASL and MIDI commands that create and control instrument instances. In this chapter, we describe SAOL statements that support instrument control.

We describe the SAOL instr statement, that supports dynamic instance creation. An algorithmic score generator may be written directly in SAOL using this statement.

We describe several SAOL standard names for status monitoring that are useful for algorithmic score generation.

These standard names hold information such as the elapsed time since instantiation, and whether an instrument is scheduled to be terminated before the next k-pass.

We describe several SAOL statements that let instances change their status. The turnoff statement lets an instance schedule its termination, while the extend statement lets an instance delay its termination.

Finally, we present a chart that shows the complete execution timeline of a SAOL program.

The timeline shows the order of events during program startup, as well as the sequencing of events during an orchestra cycle of i-pass, k-pass, and a-pass.

Dynamic Instruments

The SAOL instr statement performs dynamic instrument instantiation, so that a parent instrument may spawn copies of a child instrument. This statement supports applications such as sequencers, arpeggiators, and algorithmic composition.

The instr statement runs at the i-rate or the k-rate, and may not be used in the global block. The right panel shows the syntax for the SAOL instr statement.

The statement syntax begins with the keyword instr, followed by the name of the child instrument to instantiate.

The parameters are i-rate or k-rate scalar expressions that control the instantiation process. All expressions evaluate to constant values before the child instrument spawns.

The dly and dur parameters control the starting time and duration for the new instance.

The remaining parameters (p1, p2 ...) are the initial values for the instrument parameters of the new instance. The number of p parameters must match the number of instrument parameters in the new instance.

dly and dur

The dur parameter specifies how long (in scorebeats) the instance should execute before terminating. If dur has a value of -1, the instance runs indefinitely.

The dly parameter specifies the length of time (in scorebeats) to delay the instantiation of the new instrument.

If the dly parameter has a value less than the k-period (1/k_rate) the instrument is created as soon as the instr statement executes. The i-pass of the new instance is run immediately, and the following rules hold for the first k-pass and a-pass of the new instance:

  • If the instanced instrument occurs earlier in the execution order than the instrument containing the instr statement, the first k-pass and a-pass for the new instance are delayed until the next orchestra cycle.
  • If the instanced instrument does not occur earlier, the k-pass and a-pass of the new instance run in the current cycle.

If the dly parameter of the instr statement has a value greater than or equal to the k-period, the new instance is not created immediately.

Instead, a start time (in scorebeats) is computed for the new instance, by adding the dly parameter to the current score time. The instance is created when the score time exceeds this start time.

Rate Semantics

The instr statement may be an i-rate or a k-rate statement. It is an i-rate statement unless one of these conditions hold, in which case it runs at k-rate:

  1. Any of its parameters are k-rate.
  2. If the instr statement is enclosed in an if, if-else, or while statement and the rate of the guard expression of the enclosing statement is k-rate. It is an error if this guard expression is a-rate.

The right panel shows examples of the rate semantics of the instr statement.

Instr Statement


instr name(dly, dur [, p1, p2 ...]); 


name: name of the instrument 
      to instantiate

dly : delay time, in scorebeats, 
      before instantiation.

dur : duration (in scorebeats) of 
      instance execution. a 
      value of -1 codes indefinite
      execution.

p1, : values for instrument 
p2, : parameters to use for
... : instantiation.

Rate Semantics


instr spawn(num) {}


instr mom() {

ivar i1, i2;
ksig k1, k2;
asig a;


// runs at i-rate

instr spawn(0, i1, i2);


// runs at k-rate

instr spawn(0, i1, k