User Interface
In addition to processing audio, an AudioUnit plug-in may present a control interface to the user inside the host. The host provides a configuration button for each plug-in instance; the user the button to bring up the control interface window.
For example, the interface of a high-pass plug-in may include an on-screen slider to vary the filter cut-off frequency. A control screen for this plug-in is shown below.
An AudioUnit defines its user interface by declaring floating-point parameters during initialization.
For each parameter (for example, the cut-off frequency parameter of a high-pass filter plug-in), the plug-in tells the host the parameter name ("Cut-Off"), its units ("Hz"), its preferred user interface ("a slider with a logarithmic taper"), and the parameter's minimum ("1 Hz"), maximum ("300 Hz") and default values ("80 Hz").
A host creates a simple (a.k.a generic) user interface for a plug-in, by drawing a user-interface control on the screen for each parameter. The host sends an updated parameter value to the plug-in whenever the user moves a slider. Parameters are also the mechanism AudioUnits user for persistent state -- when a host saves a user project, it saves the current parameter values for each plug-in.
SAOL programmers specify the parameters for a plug-in's user interface by declaring ksig variables in the global block that follow a special naming convention. Ancillary variable declarations define the user-interface appearance of each parameter. The naming conventions for these SAOL variables are defined on the right panel.
On each k-cycle, the values of SAOL global ksig variables associated with AudioUnit user-interface parameters are updated to reflect user activity in the host. By importing these global variables, SAOL instrs can change their behavior based on real-time user input. The variable updates follow the same semantics as SASL updates of global variables.
If SAOL program code updates a variable that is associated with a AudioUnit user-interface parameter, the new data appears in the AudioUnit user-interface screen. The naming convention supports display user-interface elements, so that the user-interface can display parameter values (without offering a way for the user to change the parameter values).
Parameter Naming Conventions
AudioUnit parameters are SAOL ksig scalar variables defined in the global block. Variable must begin with aup_, followed by the parameter name. In the user interface, underscores in the name are presented as spaces, and case is preserved. The name must not use the strings _factory, _idx, _unit, _slider, _menu, _checkbox, and _pinfo. SAOL programs read the aup_name variable to learn the current value of a parameter.
The user-interface control for a parameter aup_name may be
specified by declaring a ksig scalar variable with a particular
naming convention. This variable exists to code information in its
name -- the run-time value of the variable has no special
significance to the sfront engine. The examples below define the
naming convention:
// sliders
ksig aup_name_slider; // linear taper
ksig aup_name_slider_log; // other tapers
ksig aup_name_slider_cuberoot;
ksig aup_name_slider_squareroot;
ksig aup_name_slider_linear;
ksig aup_name_slider_squarelaw;
ksig aup_name_slider_cubic;
ksig aup_name_slider_exp;
// checkbox -- parameter value should be 0 or 1
ksig aup_name_checkbox;
// n-choice menu -- parameter values 0, 1, .. n-1
// To learn more about menus, see this example
ksig aup_name_menu;
// display a value in the user interface
ksig aup_name_display_number; // print numeral
ksig aup_name_display_checkbox; // dim checkbox
ksig aup_name_display_menu; // print a menu label
In a similar fashion, the unit label that appears next to a slider
may be specified with variables of the form:
// name1 unit shown as "Hz"
ksig aup_name1_unit_Hz;
// name2 unit shown as "Cycles Per Second"
ksig aup_name2_unit_Cycles_Per_Second;
Units are ignored for menus and checkboxes.
The range and default value for a parameter aup_name is defined by a SAOL table aup_name_pinfo. The three elements of this table specify the minimum, default, and maximum values of the parameter.
The parameter variable in the example control window is defined as:
global {
// A parameter to be shown in AudioUnit user interface
ksig aup_Cut_Off; // underscores become spaces in UI
// Sets the user-interface widget for each parameter
ksig aup_Cut_Off_slider_log;
// Sets the unit to display next to the slider
ksig aup_Cut_Off_unit_Hz;
// Parameter info min default max
table aup_Cut_Off_pinfo(data, 3, 1, 80, 300);
}