AUv3 Dynamic Parameter Tree

Objective

The purpose of this document is to provide AUv3 host developers with guidance to ensure their apps work seamlessly with AUv3 plug-ins that dynamically modify their parameter trees.

Background

macOS 10.11 and iOS 9 introduced the AUv3 (Audio Unit Extension) APIs, along with the AUParameterTree object. This object enables AUv3 plug-ins to dynamically update their parameter trees by adding or removing parameters based on the current context. This significantly enhances the user experience by ensuring users only interact with relevant parameters. For instance, when mapping or automating a plug-in parameter in the host, users don’t have to navigate through irrelevant or generically named parameters that differ from the plug-in UI.

However, most plug-ins have static parameter trees aligned with their static UI, and many DAWs initially did not handle dynamic parameter trees well. Over time, many hosts have addressed this limitation, and some plug-ins have started adopting dynamic trees. Mela has supported dynamic parameter trees since version 4.0. Unfortunately, some mainstream DAWs still do not fully support this feature, leading to issues such as broken parameter mapping or automation.

These limitations often result in bug reports from users who believe there’s an issue with Mela. This document aims to assist host developers in resolving such problems.

Simple Test

Here’s a straightforward way to check if your DAW supports dynamic parameter trees:

1. Download Mela from the App Store.
2. Instantiate Mela as an instrument AUv3 plug-in in your host.
3. Load the Default preset.
4. Automate or map a parameter, such as the Filter module’s Frequency parameter.
5. Verify that the automation or parameter mapping works as expected.
6. Reload the Default preset.
7. Check if the automation or parameter mapping for the Filter’s Frequency parameter still works.

If the automation or mapping breaks, it indicates that the host is holding onto an outdated instance of the AUParameterTree object.

For hosts that pass this test, you can try Mela with:

• BAM
• Logic Pro for iPad and macOS
• AUM

I find BAM’s implementation to be the most robust. Logic Pro still has the usual Logic weirdnesses.

Technical Details

If your app already hosts AUv3 plug-ins, you are likely using the AUParameterTree object via the parameterTree property of the AUAudioUnit object.

To support dynamic parameter trees:

1. Install a KVO (Key-Value Observing) observer on the parameterTree property.
2. Respond to notifications when the AUv3 updates its parameter tree.

The parameter tree objects are immutable, and the AUv3 can replace the tree at any time. Therefore, your app should handle such updates dynamically. Continuing to use an outdated AUParameterTree instance will result in broken automation or parameter control.

When saving parameter mappings in project files, use the AUParameter’s keyPath property instead of the address property. For instance, Mela guarantees that the keyPath values of module parameters remain consistent even when modules are rearranged within a preset. However, parameter addresses may change due to internal implementation.

From the AUParameter.h header file:

class: AUParameterTree

brief: The top level group node, representing all of an audio unit’s parameters.

discussion:

An audio unit’s parameters are organized into a tree containing groups and parameters. Groups may be nested.

The tree is KVO-compliant. For example, if the tree contains a group named “LFO” , containing a parameter named rate, then “LFO.rate” refers to that parameter object, and “LFO.rate.value” refers to that parameter’s value.

An audio unit may choose to dynamically rearrange the tree. When doing so, it must issue a KVO notification on the audio unit’s parameterTree property. The tree’s elements are mostly immutable (except for values and implementor hooks); the only way to modify them is to publish a new tree.

Summary

• Install a KVO observer on the parameterTree property.
• Use the keyPath property to track AUv3 parameters reliably.

While the API links are provided, refer to the header files for more detailed documentation.

Contact

I hope you find this document helpful. If you spot any errors, need additional information, or require assistance debugging the parameter tree APIs, feel free to get in touch.