AAX SDK  2.4.1
Avid Audio Extensions Development Kit

How to manage metering data for AAX plug-ins.

Overview of metering in AAX

AAX provides a host-managed metering system for plug-ins. The host buffers, thins, and applies ballistics to each of the plug-in's meters. When the plug-in GUI retrieves this processed data, it receives the exact same information that is displayed on control surfaces and other metering devices.

Adding meters to an Effect

Meters are added to an algorithm Component in Describe using AAX_IComponentDescriptor::AddMeters(). The resulting meter context field will be populated with an array of meter "tap" values, one for each of the Component's meters.

Customizing meter behavior

Using the Effect Descriptor, each meter in the Effect may optionally be associated with a property map that applies a particular set of display properties to the meter. These are the properties that may be set on a meter:

Note that, because meter properties are added at the Effect level, it is not possible to describe different meter property configurations for different algorithms in the same Effect.

Reporting meter values

Meter values are reported by the algorithm using one "tap" per channel per buffer. For each tap, the algorithm must report the maximum metered sample value for each processing buffer.

Meter tap values can be interpreted as the maximum value of the meter per buffer, on a scale of [0.0 1.0]. In all cases the plug-in's meter position should be normalized between 0 and 1, where 0 is no gain reduction. For example:

Gain-reduction meter values should report peak gain reduction, not RMS or other algorithms, and may use any normalization mapping (e.g. linear, exponential) which is desired. Ideally the gain-reduction metering UI in the host and on attached control surfaces will match the Peak gain redution metering in the plug-in's GUI.

Legacy Porting Notes:
The gain-reduction meter handling for AAX plug-ins is different from that for RTAS/TDM plug-ins. AAX plug-ins must invert their gain-reduction meter values manually before reporting these values from the audio processing callback. The AAX host will always thin reported meter data using a "max" operation, and will later invert gain-reduction meter values before they are available to the plug-in GUI or to control surfaces.

Displaying meter values

The meter values that are reported to the system from the algorithm are available, in buffered and (optionally) ballistics-smoothed form, from AAX_IController . The meter values returned from methods such as GetCurrentMeterValue() and GetMeterPeakValue() are the same values used by the system when displaying plug-in meters on control surfaces, and when a plug-in clears the peak value using ClearMeterPeakValue() this change will likewise be reflected throughout the system.

The literal values provided by these methods can be interpreted as the distance from "rest" that the meter must travel to represent the current value, again on a scale of [0.0 1.0]. Note that this is not necessarily equivalent to the semantics of the meter's reported values in the algorithm:

These values are independent of meter orientation: an input or output meter that is oriented with AAX_eMeterOrientation_TopRight will still use 0.0 as its "at rest" position, and likewise a gain-reduction meter that is oriented with AAX_eMeterOrientation_BottomLeft will still use 1.0.

Alternatives

For advanced metering applications a single tap value may not be sufficient. To transmit more detailed information from the algorithm to its other components, a plug-in must use the Direct Data interface.

Collaboration diagram for Plug-in meters: