Technical Note TN2331

AUSampler - Controlling the Settings of the AUSampler in Real Time

A Note on Terminology:

In this document, the individual internal parts of the Sampler Audio Unit’s synthesis engine are referred to as “subcomponents”. These should not be confused with audio components or any other system within the Audio Toolbox.

Controlling the Settings of the AUSampler in Real Time
Document Revision History

Controlling the Settings of the AUSampler in Real Time

The Sampler Audio Unit supports the ability to modify the settings of its subcomponents (oscillator pitch, filter cutoff, envelope attack time, etc.) via control information supplied in real time by the host application. The control inputs of all subcomponents are designed as “summing” inputs: The overall effect of the inputs is always equal to the linear sum of all connected inputs (in whatever units the input expects). This means that each connection input added for real-time control will be combined with the existing inputs to produce the final result.

The full set of currently-connected inputs can always be examined via the INSTRUMENT CONNECTIONS panel in AU Lab’s editor for the Sampler (See Figure 1). The control input connections themselves are configured in advance as part of a preset created using AU Lab. Each connection is set up to modify the value of a particular subcomponent on a one-to-one basis. The relationship between the value at the input of the connection and the value that is sent to the subcomponent’s input is called the “mapping”. This is configurable and extremely flexible.

Figure 1  AULab Instrument Connections Panel.

There are three types of real-time connection:

Performance Parameters

Performance Parameters are a set of eight Audio Unit parameter values (1000-1007) which can be configured to modify any of the Sampler’s subcomponents. These parameters are discoverable via the kAudioUnitProperty_ParameterList property, and they default to an “unmapped” state in which they control nothing, and by default are named “Performance Parameter 1” through “Performance Parameter 8". The input range for Performance Parameters is always normalized to -1.0 to 1.0, or 0.0 to 1.0, depending on what input is being controlled.

The advantage of these parameters over the other types of input connections is that they are discoverable (via the AUParameterInfo mechanism) by host applications such as Logic Studio, so they can take full advantage of the parameter automation features of such applications. They can be created and configured using the PERFORMANCE PARAMETERS panel in AU Lab’s editor for the Sampler.

In Figure 2, two Performance Parameters have been created and given them custom names. The first of these is selected to show that the parameter is mapped to the Pan input for the Layer.

Figure 2  AULab Performance Parameters Panel.

MIDI Controller Messages

In order for the default Sampler Audio Unit (i.e., with no user preset loaded) to behave in a reasonable fashion in response to MIDI input, it is set up to use several of the standard General MIDI controller connections. Among these are controller #7 and #11 modifying gain, controller #10 modifying pan, and so forth. The input range of these messages conforms to the MIDI specification’s range of 0 to 127. The vast majority of the 128 total MIDI controller numbers are not set up by default to modify anything, and are available to use as control inputs for various Sampler subcomponents, which is useful if you have a complex preset.

Once a MIDI controller connection is configured and loaded as part of the preset, each particular subcomponent can be modified independently by sending MIDI control messages with the specific controller numbers (and values) to the Sampler via MusicDeviceMIDIEvent. Each of these connections may be created, modified, and examined using the INSTRUMENT CONNECTIONS panel in AU Lab’s editor for the Sampler.

In Figure 3 an additional connection has been created, mapping MIDI controller #55 to the Attack Time of the Layer's envelope.

Figure 3  Creating MIDI Controller Connections.

Group Scope Parameters

The Sampler Audio Unit also supports a way to send control information to any MIDI controller connection (described above) using AudioUnitSetParameter() calls rather than sending MIDI events. When parameter values are set on the Sampler using the Audio Unit Scope kAudioUnitScope_Group, the parameter change is interpreted as though the parameter ID was a MIDI controller number. For example, the code in Listing 1 will produce the same effect on a Sampler which has a connection set up for MIDI controller #55:

Listing 1  

UInt8 channel = 0;
UInt8 controllerNumber = 55;
UInt8 controllerValue = 127; /* set it to max */
                     kMidiMessage_ControlChange|channel, /* status combines the message type and channel */
                      (AudioUnitElement )channel,
                      (AudioUnitParameterValue) controllerValue,

These parameters are not externally discoverable like the Performance Parameters, but using MIDI events you can still create MIDI control data which will, when played back via the Sampler, automate the changes to the subcomponents controlled by those connections.

What Settings Can I Control in this Fashion?

Here is a list of the subcomponents and their inputs that can be controlled using connections:


Table 1  




Decibels (-96 to 0)


Percent (-0.5 to 0.5)


Table 2  





Sample Start


Sample Start Factor

Percentage of sample length (1.0 == 100%)


Table 3  





Resonance (Q)



Table 4  



Delay Time

Time Octaves**




Table 5  



Delay Time

Time Octaves**

Attack Time

Time Octaves**

Hold Time

Time Octaves**

Decay Time

Time Octaves**

Release Time

Time Octaves**

Sustain Level

Percent (1.0 == 100%)

It is important to remember that within any Sampler preset, the filters, oscillators, low frequency oscillators, and envelopes are defined at the Layer level, so presets with multiple layers have multiple independent sets of subcomponents, each of which can be controlled independently. If you open a preset with multiple layers in AU Lab’s INSTRUMENT CONNECTIONS editor, you will see the “destination” for each connection specifies both the layer number and the particular subcomponent input.

In Figure 4, a new connection is being created which will control a subcomponent in Layer 2.

Figure 4  Instrument Connections For Multiple Layers

Document Revision History


New document that discusses different methods of controlling the AUSampler audio unit in real time.