Part II/2A: Overview of Control Drivers

Sections

• Introduction.
• Example: fstr control driver. Uses the file streaming control driver to introduce the control driver concept.

Introduction

Several sfront command-line options let the user specify control information in a static way. The -sco and -sstr command line options let user specify SASL commands in an ASCII file, and the -midi and -mstr options let users specify MIDI commands via standard MIDI files. Both SASL and MIDI commands may be a part of mp4 binary files, which are specified by the -bit and -bitc options.

When any of these options are specified, sfront transforms the control information into initialization parameters for C global variables in the sa.c file. A static compilation approach lets the C compiler optimize the sa.c program in significant ways.

However, for some applications, a static approach to SASL and MIDI control data is not suitable. An important example is streaming Structured Audio files over the Internet. The mp4 file format lets users place the SASL and MIDI control information in small packets (called SA_access_units) at the end of the file (see this section of the manual to learn how to encode control information into SA_access_units). A Structured Audio decoder that can accept control data dynamically can start playing back an mp4 file once a few SA_access_unitss are received, rather than wait for the entire file to arrive.

The control driver interface is designed to support dynamic control applications such as audio streaming. The interface lets the user specify a C or C++ driver file to be included into the main sa.c file, that is capable of dynamically issuing SASL and MIDI commands at each k-cycle. In addition to providing functionality for normatively streaming Structured Audio, the control driver interface also has facilities for supporting interactive applications such as patch editors, sequencers, and hardware emulations.

Our description of control drivers is divided into three sections. In this section, we introduce the control driver architecture by describing the streaming file control driver fstr that is included in the sfront distribution. The second and third sections describe the control driver interface in detail.

Example: fstr control driver

The right panel shows how to use sfront to stream a Structured Audio binary file that has control information encoded as SA_access_units. The example uses the file streaming control driver fstr. In this section, we will use fstr to introduce the control driver concept.

The control driver fstr is invoked on the sfront command line by using the option -cin fstr. This option copies the C or C++ code contained in the file sfront/src/lib/csys/fstr.c into the sa.c file created by sfront.

Like all control drivers, the fstr control driver defines a small number of C functions, listed on the right panel. These functions are called at different points during the execution of the sa.c program:

• csys_setup(void) Called at the start of execution of the sa.c program, lets the control driver initialize its state.
• csys_newdata(void) Called once per control cycle (k-cycle). Its return value informs the main program that there are MIDI or SASL events that the driver wishes to execute this cycle.
• csys_midievent(...) Called if the csys_newdata() return value indicates that the driver wishes to send MIDI events. The actual MIDI event is returned using pointer variables in the function parameter list. The return value is used to request another call to csys_midievent(), to transfer another MIDI event in the same k-cycle.
• csys_saslevent(...) Called if the csys_newdata() return value indicates that the driver wishes to send SASL events. The actual SASL event is returned using pointer variables in the function parameter list. The return value is used to request another call to csys_saslevent(), to transfer another SASL event in the same k-cycle. The csys_saslevent() function may also be used to send special events that perform functions not included in the SASL language.
• csys_shutdown(void) Called at the end of execution of the sa.c program, lets the control driver close files and devices. If the -except option is used during sfront invocation, csys_shutdown() will be called even if the sa.c program is ending its execution prematurely due to an error condition.

In order to request MIDI and SASL events, the control driver needs to know details about the SAOL file, such as the names of instruments and variables. The next section of the control driver chapter describes the data structures and service functions that inform the SAOL program and the run-time environment.

The final section of the control driver chapter describes the calling syntax and semantics for the five functions listed above. It also describes the registration process, by which the sfront program learns the characteristics of a new control driver.

Next section: Part II/2B: Control Drivers Data Structures

Example

sfront -cin fstr -bitc t.mp4 
       -aout linux -playback
gcc -O3 sa.c -o sa
./sa


Notes:

[1] The control driver is 
specified by "-cin fstr"

[2] We use -bitc instead of
-bit to tell sfront to not
compile in the SA_access_unit
data into sa.c.

[3] We use -aout linux -playback
to tell sfront to send its audio
directly to the soundcard, instead
of its default behavior of writing
an output.wav file.

Functions in Control Drivers

/* called at program start */

int csys_setup(void);

/* called each k-cycle */

int csys_newdata(void);

/* called each kcycle that */
/* csys_newdata() requests */

int csys_saslevent( ... );
int csys_midievent( ... );

/* called at program end */

void csys_shutdown(void);