Details about using AAX plug-ins in Pro Tools.

About this document

This guide discusses specific details related to using AAX plug-ins with Pro Tools, such as loading and initialization procedures, GUI hosting, and other application-specific features. This guide is not intended to provide complete documentation for the Pro Tools application. For more information about the features, functionality, and use of Pro Tools see the Pro Tools Reference Guide, available for download from the Avid web site.

This guide is a work in progress, and is extended as needed to describe different aspects of and caveats to the Pro Tools implementation of the AAX host spec.

Processing modes

Pro Tools supports three AAX processing modes: AudioSuite, AAX Native, and AAX DSP.

AudioSuite plug-ins perform non-real-time, random-access, file-based processing entirely on the host CPU.
AAX Native plug-ins perform real-time, linear, non-destructive processing entirely on the host CPU. Native plug-ins are also used by Pro Tools to perform offline rendering.
DSP plug-ins perform real-time, linear, non-destructive processing on DSP-accelerated hardware, with non-real-time tasks performed on the host CPU.

Each of these processing modes offers specific advantages and trade-offs in functionality, power, and development effort, and plug-in developers may choose to develop only for specific processing modes if the features provided by those modes are required by the plug-in.

Real-time processing

Real-time processing allows users to operate plug-ins in live signal paths or in complicated audio routing schemes when the future input data is not known.

Plug-ins operating in real-time are clients of the Pro Tools automation system, meaning that control movements can be dynamically recorded and played back with the audio track, written by hand onto the Pro Tools timeline for future playback, and/or edited by and broadcast to attached control surfaces.

To instantiate a plug-in for real-time processing in Pro Tools, click on an insert slot in the desired track and select the plug-in from the menu that appears

Native real-time processing

When an AAX plug-in is run natively, all of its components and processing elements are loaded into the host environment. The host CPU handles the plug-in's real-time audio processing as well as its data model, GUI, and other tasks.

Virtual Instruments and MIDI effects

Virtual Instruments and MIDI effects are special categories of real-time processing effects. Instead of processing audio data, these types of effects convert incoming MIDI data into output audio or MIDI data. Although a user interacts with these kinds of effects differently than with pure audio processing effects, the AAX API does not generally distinguish between them. See Plugins with MIDI support for more information.

DSP real-time processing

When an AAX plug-in is run with Avid's DSP-enabled hardware, the plug-in's real-time processing code is loaded onto the external DSP device, while the remaining plug-in modules continue to be run by the host CPU. Each DSP in this system provides dedicated processing capacity that is not shared with an OS or other processes, and therefore this architecture allows users to achieve highly reliable and deterministic low-latency processing even when many DSP plug-ins are instantiated.

Figure 1: Real-time insert slots in the Pro Tools Edit and Mix windows.

CPU reporting

To guarantee absolute reliability, AAX DSP plug-ins are required to report their worst-case performance metrics to Pro Tools. Pro Tools uses this information to ensure that each DSP in the system will be loaded with only the number of plug-ins that it can support given a worst-case processing load.

Non-real-time processing (AudioSuite)

The non-real-time AudioSuite processing mode is file-based, meaning that the results of AudioSuite processing are applied destructively to audio files (generally to new, empty files provided by Pro Tools.) AudioSuite processing can only be performed on preexisting blocks of audio.

There are two primary ways to apply AudioSuite processing in Pro Tools. The first way is to selectively apply the processing algorithm to the audio tracks and clips that are selected on the Pro Tools timeline. This is known as "destructive" processing, because the original audio track is replaced by the new processed audio track. There are no limitations governing the amount of time required to process a track in this manner.

Audio Suite plug-ins also have a second optional mode in which they can run. This is referred to as Preview mode. The Preview feature allows you to monitor the audio processing applied to a track in semi-real-time. Because this is a real-time process, it is not applicable to all types of file based processing. You may elect not to support this mode in your plug-in if its algorithm does not lend itself to real-time, linear processing. Preview mode is implemented in a non- destructive manner, as Preview mode exists for auditioning only with no actual replacement of audio data on the Pro Tools timeline.

To instantiate an AudioSuite plug-in in Pro Tools, select the plug-in from the "AudioSuite" menu in the Pro Tools application menu bar

Multichannel and Multi-Mono

Pro Tools supports various surround stem formats throughout the entire signal chain, including multi-channel processing through AAX plug-ins.

Pro Tools also allows a plug-in to function in multi-mono mode if the plug-in does not explicitly support certain channel formats. In multi-mono mode, Pro Tools instantiates a separate instance of a plug-in for every channel in the track. In this mode, plug-in controls across all channel-instances in a multi-mono collection are linked by default, though channels can be unlinked by toggling the blue link button in the plug-in header and selecting the channel whose controls you wish to modify.

For more information about multi-mono mode, please refer to the Pro Tools Reference Guide.

Requirements for AAX plug-in compatibility with Pro Tools

In addition to implementing the client-side AAX API, all Pro Tools plug-ins must:

Be installed to the AAX plug-ins directory
Use a valid file name
Be signed with a valid digital signature

Note that digital signatures for plug-ins are not required in Pro Tools Developer builds. However, you will need a Pro Tools Developer Build licence in order to run Pro Tools Developer. To obtain your licence, contact devau.nosp@m.th@a.nosp@m.vid.c.nosp@m.om.

Install directories

AAX plug-ins must be installed in the system's AAX Plug-Ins directory. See Building your plug-in installer for more information about creating a plug-in installer.

Plug-ins that are uninstalled but still present on the system are placed into the "Plug-Ins (Unused)" directory, which is located next to the Plug-Ins directory.

Pro Tools will also search for a Plug-Ins directory next to the actual Pro Tools application, and this directory will be used if present. This debug feature can be useful for testing specific plug-ins.

Plug-in name and file structure

In order to be recognized by AAE, all AAX plug-in bundles must use the ".aaxplugin" file name suffix. On macOS, the plug-in bundle must use this suffix while the binary itself does not require a suffix. On Windows, the plug-in binary (DLL) must use this suffix.

The directory structure of an AAX plug-in bundle is also important. See .aaxplugin Directory Structure in the AAX Format Specification document for more information.

Digital signature

As an added security measure against digital piracy, all AAX plug-in binaries must be digitally signed in order to run in Pro Tools. This signature step does not interfere with your existing copy protection and licensing solutions - it is simply a build step that you incorporate into your plug-in before releasing the binary.

Digital signatures are generated based on the plug-in binary and act as a guarantee against binary modification. Therefore, any build steps that modify the binary, such as symbol stripping, must be performed prior to signature generation. Digital signatures apply to the full .aaxplugin bundle, so any operation that modifies the contents of the bundle will invalidate its digital signature even if the operation does not affect the plug-in binary itself. Therefore, the generation and application of a digital signature should be the last step in any release plug-in build process. The digital signature requirement applies to Beta and Release software. This requirement does not apply to Development builds of Pro Tools or to other developer tools which can load unsigned binaries.

Note: You will need a Pro Tools Developer Build licence in order to run the Pro Tools developer builds. To obtain your licence, see the Obtain a Pro Tools Developer iLok license (and an iLok) section in the Getting Started with AAX guide.

If you are having problems with digitally signing your plug-ins see the Plug-In Fails to Load in Shipping Pro Tools section in the Troubleshooting guide.

Requesting the digital signing toolkit

The AAX digital signatures required by Pro Tools are generated using digital signing tools licensed from PACE Anti-Piracy, Inc., which acts as the certificate authority for all AAX digital signatures. To request access to these tools, send an e-mail to audiosdk@avid.com with "Pace Tools Request" in the subject. Include the following information in your request:

Company name
Admin full name
Email
Telephone number
iLok username

Once your request has been approved you will be contacted by PACE with further instructions for acquiring and using the digital signature toolkit.

What you will need

The digital signing toolkit which you will receive as an AAX developer will require a physical iLok USB key. You will also need a registered iLok user account which will be used when applying the digital signature. If your build toolchain requires hardware-free signing then you can contact PACE regarding their current offerings.

In order to successfully use the signing tools you should be familiar with the latest Gatekeeper and codesign (for Mac) and Authenticode (for Windows) digital signature schemes.

Although it is possible to use self-signed certificates for AAX digital signatures, before making your AAX plug-ins commercially available it is recommended that you acquire an Apple-issued Application Developer ID for Gatekeeper and an "Extended Verification" (EV) Authenticode certificate from a Microsoft approved certificate authority.

See the Getting Started Guide in the PACE digital signing toolkit for more information about using these tools.

Signature requirements in Pro Tools

Host Compatibility Notes:: Pro Tools requires PACE Eden digital signatures for AAX plug-ins.

Pro Tools and higher use the Eden toolset. This toolset integrates fully with platform-specific signatures, so you only need to do one post-build step using the Eden digital signing tools to sign your plug-in with both the Eden signature and the relevant Apple GateKeeper or Microsoft Authenticode signature. For more information, see the Eden digital signature toolkit documentation.

Pro Tools and higher will only accept the Eden signature; AAX plug-ins signed by earlier generations of PACE digital signing tools will not load in Pro Tools.

Optional Signature for Pro Tools AAX DSP binaries

Binary-level encryption can be added to AAX DSP algorithms. Please note that this is NOT a requirement of AAX DSP plug-ins, and serves only as an additional security measure to protect an algorithm's DLL.

For more information about signing AAX plug-ins for use with Pro Tools, please contact PACE.

Automatic signature application by PACE tools

If you already protect your plug-ins using one of the anti-piracy technologies available from PACE then you may not need to perform any additional action:

you are wrapping using PACE InterLok MasterMaker, your binaries will be automatically signed.
If you are using Fusion Hybrid without wrapping with MasterMaker, please carefully review the "Adding digital signature checks" section of the Fusion Hybrid manual.
If you are using PACE APIs (like PACE Interface or CDRM) without InterLok wrapping, please see either the latest PACEDSigTool read me or the Fusion Hybrid manual for additional details regarding digital signing.

Audio Engine Behavior and Features

Pro Tools hosts AAX plug-ins using the Avid Audio Engine (AAE). AAE implements all host-side AAX interfaces such as AAX_IController and the AAX_ICollection.

Plug-in loading and AAE initialization

When Pro Tools launches, it immediately begins loading AAE. AAE searches the system for valid AAX plug-ins, checks each plug-in's digital signature, and loads, initializes and catalogs any valid plug-in modules that it happens to find.

This initialization is performed via the plug-in's Describe implementation; once AAE loads a plug-in binary, it calls the plug-in's Describe method to retrieve (and cache) the basic configuration of the plug-in. AAE then hands this information back to Pro Tools so that Pro Tools knows what plug-ins are available and what their basic properties are. Once a complete list of plug-in descriptions has been generated, AAE can construct any plug-in's individual modules and manage its algorithm.

Plug-in configuration cacheing

AAE is pretty smart, and it knows during initialization if anything has changed within the AAE Plug-Ins folder since the last time it was run. If nothing has changed, AAE relies on plug-in descriptions that it cached during the previous launch to speed through the plug-in loading process. If, however, any plug-ins have been added, removed, or updated since the last launch, AAE loads and re-caches the description for every installed plug-in.

Note: We recommend that you always enable the AlwaysRebuildCache DigiOption during plug-in development. See Using DigiOptions for more information.

Plug-in initialization

When a new plug-in instance is created in Pro Tools, AAE performs the following steps:

The plug-in's data model component is loaded
The default state of the plug-in is set (see Default plug-in settings)
The plug-in's GUI and other host modules are loaded
The plug-in's algorithm private data state is initialized
The plug-in's algorithm is loaded and initialized
The plug-in's algorithm processing is initiated

Run-time processing behavior

The audio engine in Pro Tools includes some advanced real-time processing features that are not present in earlier versions of Pro Tools:

When certain tracks with plug-ins have been silent for a period of time or Pro Tools is not in playback, those plug-in instances are automatically deactivated to reduce processing load on the host processor
In certain situations such as playback or offline bounce where low latency is not required, Pro Tools may call AAX Native plug-ins with a larger buffer than normal.

This latter behavior is possible due to the fact that AAE uses two latency domains for plug-ins: a high-latency domain that operates over large block sizes and a low-latency domain that operates over small block sizes. Since processing at higher block sizes is generally more efficient, plug-in instances that are running in the high-latency domain generally consume less CPU cycles for their processing than instances that are running in the low-latency domain.

Pro Tools may swap plug-in instances back and forth between these two domains at run-time and uses a set of rules designed to optimize the system's CPU resources while at the same time providing the best and most responsive user experience in every situation. These rules are different depending on whether the system is using an HDX card as its playback engine.

Here are some of the specific rules that are followed by the current versions of Pro Tools at the time of this writing. These rules are subject to change from release to release:

(HDX classic and Native) If there is any live audio or MIDI feeding into the plug-in's track and if the track is sending audio to an active output then all plug-in instances on the track will be run at low latency.
(HDX classic only) If any AAX DSP plug-in instances are present in the signal path that feeds an AAX Native plug-in instance then the AAX Native plug-in will be run at low latency.
(HDX classic only) Any AAX Native plug-in instance on an AUX track will be run at low latency.

For a full list of compatibility and feature differences between different AAX plug-in hosts, see Host Support.

Deterministic Plug-in Automation

Native and DSP plug-ins will receive automation changes in a deterministic manner. Each time the transport is played, automation events will be delivered to the plug-in for processing at the same moment on the timeline. Note that this does not mean automation is sample-accurate with respect to where the automation breakpoints are placed in the timeline, but rather that the timing will be the same between transport runs.

Offline Bounce

Pro Tools supports faster-than-real-time offline bounce for all sessions. All plug-ins with AAX Native types are supported. For AAX DSP plugins, the offline bounce process will temporarily convert those to their corresponding AAX Native types to complete the bounce. Because offline bounce is faster-than-real-time, audio processing callbacks will occur as fast as the algorithm will allow for. For this and other reasons, your algorithms should never depend on wall-clock time for features such as LFO, delay time, etc. Instead, all algorithms should always base time calculations on sample time so that the output will still be correct even if the algorithm is being called from an offline bounce.

The Hybrid Engine and AAX DSP

Pro Tools HDX and Pro Tools Carbon systems support the Hybrid Engine, which optimizes system latency by splitting the Pro Tools mix topology between native and DSP processors. When the Hybrid Engine is in use, Pro Tools tracks are configured as either DSP Mode or Native Mode. All AAX effect instances on a DSP Mode track are switched to their AAX DSP type. Plug-ins that do not support AAX DSP are de-activated while the track is in DSP Mode.Pro Tools HDX also supports a Classic mode. In this mode, the user chooses whether each plug-in instance will be AAX Native or AAX DSP.

AAX Hybrid Plug-ins

Pro Tools also supports AAX Hybrid plug-ins, which can have both a Native and a DSP algorithm processing component. Audio-rate data can also be shared between the two processing components, which allows you to split your algorithm up into low-latency and high-latency contexts for better efficiency and to enable plug-ins such as convolution reverbs, spectrum analyzers, and other similar architectures.

Note: AAX Hybrid is only supported by Pro Tools HDX when running in Classic mode. See PT-257213 for more information.

Basic plug-in operation

Configuration management

Each Effect in an AAX plug-in may contain multiple configurations. Pro Tools automatically determines the appropriate plug-in configuration for each Effect insert at run time based on the insert's required sample rate, channel width, and processing mode (Native of DSP.) Under some circumstances, the configuration requirements for an Effect insert may change at run-time. Here are some examples:

When a width-changing plug-in (e.g. mono-to-stereo) is instantiated on a track then all of the following inserts must be converted to the new stem format
When a user imports session data between sessions at different sample rates then all of the imported plug-ins must be converted from the old sample rate to the new sample rate
When a user opens a session that contains deprecated effects, they must be replaced by the corresponding installed effects

Whenever a new configuration is required, Pro Tools automatically determines whether one is available that meets the new requirements and, if it is, swaps in a new plug-in instance using a copy of the previous configuration's settings.

In order for Pro Tools to deterministically select the appropriate Effect configuration to load in any given scenario, each of the configurations that are registered in the Effect must be described with distinct and mutually exclusive compatibility requirements.

Plug-in activation and deactivation

In Pro Tools, real-time plug-in inserts can be either active or inactive. Inactive plug-ins are not instantiated and are entirely removed from the processing chain, though they are still saved with the session and maintain a placeholder in their track's insert list for easy activation at a later point.

Active plug-ins may be de-activated manually by the user or automatically by Pro Tools. Plug-ins may be loaded as inactive when a plug-in that has been saved in a session has been uninstalled and is no longer available, when a required plug-in configuration is not available, or at any other time when a particular plug-in instance cannot be loaded.

Plug-in bypass

AAX plug-ins must implement a Master Bypass parameter, which is controlled via the "Bypass" button in the Pro Tools plug-in window header. While bypassed, the plug-in must not apply any processing to the audio that is passed to it (except delay, see below.) The plug-in may choose to smoothly transition into and out of bypass however it chooses.

Any algorithmic delay that a plug-in incurs during normal operation must be maintained by the plug-in during bypass. For more information about this requirement, see Automatic Delay Compensation.

Presets and settings management

Pro Tools includes a plug-in preset management system that can be accessed from the plug-in window header. With this system, users can save plug-in settings to disk and load the settings later to restore the plug-in's configuration.

Preset files can be bundled with an AAX plug-in to demonstrate a variety of uses for the plug-in or as recommended settings for different situations, and, as a plug-in developer, you are encouraged to provide a large selection of pre-configured presets along with your AAX plug-ins. See Create factory presets for more information about bundling presets with your plug-in.

Aside from user preset management, there are many cases when the state of a plug-in must be captured or restored by AAE. For example, AAE must restore plug-in settings when a session is loaded and when converting a plug-in between different configurations.

The plug-in preset menu

Plug-in presets are available to the user via the Plug-In Settings menu in the Pro Tools plug-in window header. This menu supports nesting presets into sub-folders, which provides a convenient way to categorize and organize large sets of presets. In addition, users may save custom presets and add these custom presets to the menu.

Figure 2: The Plug-In Settings menu in the Pro Tools plug-in window header

The preset menu in the Pro Tools plug-in header is built from the following two directories:

Session file/../Plug-In Settings
User Library root/Plug-In Settings

The default setting for the User Library root directory is ~/Documents/Pro Tools on macOS, but the user can change this setting in the Pro Tools preferences.

Factory presets

Pro Tools supports automatic installation of plug-in presets. AAX plug-ins should include a set of presets in the following directory within the .aaxplugin:

MyPlugIn.aaxplugin/Contents/Factory Presets/MyPlugInPackage/

Where MyPlugInPackage is the plug-in's longest Package Name with 16 characters or fewer.

On Pro Tools launch, all installed AAX plug-in settings are copied from the .aaxplugin bundles' "Factory Presets" folders into the User Library directory (see above.)

Note: Since the User Library root directory is a customizable setting, you should never install presets directly onto a user's system. If you require a central repository of settings on the system that is under control of your installer then you should handle these settings as external resources. You can use custom settings chunks in the plug-in's "Factory Presets" .tfx files to redirect your plug-in to read the appropriate installed resources.

Default plug-in settings

When the first instance of an effect is made active in a session, Pro Tools queries the instance's state and stores this data as the effect's "factory default" preset. This preset is cached by Pro Tools and will be set on each subsequent instance of the plug-in with the same configuration

The plug-in's factory default settings are stored on disk in a temporary file location that is specific to the user. Pro Tools looks for the factory default settings file for a plug-in each time an instance of the plug-in goes from an inactive state to an active state, including when the instance is first created. If there is no factory default settings file on disk then Pro Tools will create it using the plug-in's current settings.

All factory default settings files are deleted during the Pro Tools shutdown procedure. Therefore, under normal operation, these files will be refreshed with each launch of Pro Tools.

Note: If the Pro Tools shutdown procedure is not completing, for example if you regularly terminate Pro Tools from a debugger, then the plug-in factory default settings files will not be deleted automatically.

When a session is loaded Pro Tools will perform the following steps on each plug-in instance:

Instantiate the plug-in and create a AAX_IEffectParameters object
Look for the cached factory default settings file in the file system
If the factory default settings file is not found, query the plug-in for its current settings and create the factory default settings file using these settings
Set the instance's default settings based on the settings stored in the cached factory default file
Send the instance a AAX_eNotificationEvent_SessionBeingOpened notification
Set the saved settings from the session

The Compare Light

The plug-in window header in Pro Tools includes a "Compare" button, the Compare Light control. This control allows the user to compare the current state of the plug-in with the last preset that was loaded, or the plug-in's default settings if no other preset has yet been loaded.

Pro Tools polls each displayed plug-in periodically to determine whether or not its state matches the currently loaded preset. While the state matches, the Compare Light is inactive and unlit. As soon as the plug-in's state differs from the preset, the Compare Light becomes active and is highlighted.

When the Compare Light is active, the user may click on it to cache the current plug-in settings and temporarily swap in the last preset that was loaded. Clicking on the Compare Light a second time will restore the cached plug-in settings.

The specific operation of the Compare Light is determined by the plug-in's implementation of AAX_IEffectParameters. To determine the correct state for a plug-in's compare light, Pro Tools makes regular calls to AAX_IEffectParameters::GetNumberOfChanges() from a callback timer. If this method's aValueP parameter has changed since the last time the plug-in was queried then Pro Tools proceeds to call CompareActiveChunk(). If CompareActiveChunk() returns with isEqual==false then the Compare Light will be lit, otherwise the light will be dimmed.

Basic chunk handling

All of these situations use the same basic settings management infrastructure in Pro Tools, which uses the "chunk" API of AAX_IEffectParameters to retrieve arbitrary blocks of data from the plug-in (to retrieve a preset) and send the same block back to the plug-in (to set a preset.)

When retrieving a preset from a plug-in, Pro Tools first asks for the size of the plug-in's settings chunk(s). Pro Tools then provides the plug-in with a pre-allocated buffer of memory into which the plug-in may store its settings information using any format that it chooses.

When Pro Tools needs to restore the plug-in to this preset state, it sends a copy of this data back to the plug-in. The plug-in must interpret this data and set its internal state to match the preset.

Modifier key behavior

In order for users to have a consistent experience, all AAX plug-ins should provide standard modifier key behaviors as described in this section. These operations are demonstrated by all Avid plug-ins in Pro Tools, and you can experiment with Avid's AAX plug-ins to demonstrate the correct plug-in modifier key behavior.

The following modifier key combinations must be handled explicitly by the plug-in:

macOS Keys	Windows Keys	Expected Behavior
Command-click	Control-click	Adjust the parameter's value with fine control, for continuous controller widgets
Option-click	Alt-click	Return the parameter's value to default^*
Shift-click	Shift-click	Link parameters across all channels, if applicable
^*Set-to-default may also be handled directly by the host, depending on the host version (see below).

In addition to these events, there are also specific behaviors which Pro Tools and other AAX hosts provide for certain key combinations in plug-in GUIs. For example, Pro Tools provides the following modifier key behavior overrides:

macOS Keys	Windows Keys	Expected Behavior
Command-Control-click Command-Right click	Control-Start-click Control-Right click	Show parameter automation lane in the Pro Tools Edit Window, if automation is enabled for the parameter
Command-Option-Control-click Command-Option-Right click	Control-Alt-Start-click Control-Alt-Right click	Activate pop-up menu for automation

Other AAX plug-in hosts implement different host-managed behavior for modifier key combinations, and additional host-managed key combinations may be added to any AAX host in the future. For example, Pro Tools adds host-managed support for setting plug-in parameters to their default values.

In order to allow the AAX host to handle these operations, a plug-in must always call the handler methods in AAX_IViewContainer before handling any mouse events in its own GUI. It is important to call these methods for all mouse events, in case additional handlers are added to future versions of the host or the plug-in is run in a new AAX host with a different set of handled modifier key combinations.

See the AAX_IViewContainer class documentation for more information about passing mouse events to the AAX host.

Optional plug-in features

Pro Tools plug-ins offer users a rich set of integrated features. To make sure your plug-ins integrate into users' expected Pro Tools workflows, where applicable you should implement all of the features presented in this chapter.

For more information about any of these features in Pro Tools, see the latest Pro Tools Reference Guide.

Audio management features

Sidechain input

If applicable, plug-ins may choose to enable sidechain inputs. If a sidechain is enabled, a menu is added to the plug-in's header that allows the user to choose an interface or bus as the sidechain, or "key input". For AudioSuite, the user can only use an existing audio track as the sidechain input. Once enabled, the plug-in will be able to access sidechain input just like any other input signal.

Auxiliary Output Stems

Pro Tools has the capability to show and route multiple "auxiliary" outputs from a plug-in to other tracks. These are known as Auxiliary Output Stems (AOS), a stem referring to one set of outputs. A stereo stem contains two outputs, left and right, and a mono stem contains one output. The outputs will appear in the input assignment pop-up menu of each track under the category "plug-in".

Some notes regarding this feature:

Only mono and stereo stems are available as auxiliary outputs.
The aux outputs cannot be added and removed from the system dynamically though they can be made inactive by the user. The total number of aux outputs, stem types, names, paths, and ordering are defined only once by the plug-in.
Plug-in aux outputs are not available from the sidechain input popup menu in other plug-ins. Users will not see the "plug-in" submenu when clicking on a plug-in sidechain popup.
There cannot be any multi-mono multi-output plug-ins. If a mono plug-in instance offers multiple outputs it cannot support multi-mono.

If a plug-in is going to utilize the AOS feature, it will be responsible for a few details that are summarized below:

Aux Output Paths
The plug-in is responsible for the definition of valid aux output paths. This definition includes the total number of outputs, the desired order of stereo and mono paths. Pro Tools will query each plug-in for available valid paths and populate its track input selector popup menus accordingly.
Aux Output Path Order
The plug-in is responsible for specifying the type and name of each of its aux output paths. A plug-in decides whether the aux outputs are all stereo, all mono, "X" stereo outputs followed by "Y" mono outputs, or some other combination. Pro Tools lists each output in the order given by the plug-in. If mono and stereo paths are interleaved the input popup menu of the mono tracks keeps that order and breaks the stereo paths into their respective left and right sides using ".L" and ".R" suffixes.
Aux Output Names
A plug-in is responsible for giving meaningful names to aux outputs. Names are only defined once, so they will stick. At the very least, individual outputs should be labeled "Output xx", where "xx" is the aux output number as it is defined in the plug-in. The output name should also include the words "mono" and "stereo" to support when users are looking for an output with a specific stem format.
Aux Output Numbering
The plug-in is responsible for defining the lowest available aux output number. Plug-ins should base this number on the width of the plug-in's main outputs. For example, when using a stereo instance of a sampler the first aux output should be #3, when using a 5.1 instance of the sampler the first aux output should be #7, etc. This is to keep the numbering scheme inside of the plug-in and in Pro Tools consistent. From the perspective of Pro Tools, plug-ins typically enumerate all available outputs and do not differentiate between main and aux outputs. The first "N" outputs are used for the main outputs, and all the remaining outputs are available for aux output paths.
Separate Multi-Output Plug-in Process Type
Plug-in developers are encouraged to offer both "regular" and "multi-output" versions/types of any multi-output capable plug-in. We strongly suggest this to conserve resources and to keep the user's workspace as uncluttered as possible. Users can choose to use the regular version/type for plug-ins they don't need aux outputs for. Multi-output versions can be created as separate process types so that there need not be separate binaries. Such additional process types will be listed in the plug-in menu next to their regular version siblings. They should be nominally distinguished by appending phrases like "multi-output" to the plug-in name, for example.

Note
When moving sessions between different PT systems, multi-output process types will NOT be automatically converted to regular process types if multi-output types are not available.
No Multi-Mono Implementations
A plug-in is responsible for not having multi-mono enabled if it utilizes auxiliary outputs stems. Auxiliary output stems will not work in multi-mono enabled plug-ins. Multi-mono is automatically disabled for AOS in the Effect Layer.

External metering and internal clip

Pro Tools may use the meter values reported by a plug-in for display on attached control surfaces and other external plug-in views. In general, the behavior of a plug-in meter on these devices will depend on the meter's properties as registered in Describe. The meter behavior may also depend on the plug-in's registered category. See Plug-in meters for more information about how to register your plug-in's meters.

Gain reduction metering
Pro Tools supports gain reduction metering and will display an inverted gain reduction meter next to each plug-in insert and also next to the track's main meter in the Pro Tools Mix and Edit windows.

All registered plug-in gain reduction meters are used by the Pro Tools gain-reduction metering UI. The plug-in gain reduction meters in the Pro Tools Mix and Edit windows will combine metering data for all gain-reduction meters of the same type (Compressor/Limiter or Expander/Gate) in the plug-in:
- For plug-ins with multiple gain-reduction meters of the same type, the minimum (most gain-reduced) meter value for the current buffer will be used
- For multi-mono plug-ins, the minimum meter value across all of the per-channel mono instances will be used
Pro Tools can be set up to display Compressor/Limiter, Expander/Gate, or both types of metering data in these displays via Preferences > Metering > Display > Gain Reduction Meter Type. If both types are used, the displayed meter level is simply the sum of the selected values for each type.

The track gain-reduction meter displays the sum of all the track's inserts' gain reductions, using the same rules as above.
Plug-in internal clipping
The plug-in header has a clip light that indicates that the plug-in has reported that is has clipped somewhere internally. It is up to the plug-in itself to set and clear its clip indicators as needed. Additionally, plug-ins that have clipped internally will appear in red on the insert, even if the plug-in window is not open. This allows users to see at a glance where clipping has occurred in their mix.

Automatic Delay Compensation

Automatic Delay Compensation maintains time-alignment between tracks that have plug-ins with differing algorithmic delays, tracks with different mixing paths, tracks that are split off and recombined within the mixer, and tracks with hardware inserts. To maintain time alignment, Pro Tools adds the exact amount of delay to each track necessary to make that particular track's delay equal to the delay of the track that has the longest delay.

In order to be compensated correctly, AAX plug-ins must report any algorithmic delay that they incur. This delay may be reported in the plug-in's description, and may also be changed at run-time.

Automatic Delay Compensation Notes

Currently, Pro Tools will not update its delay compensation settings while Pro Tools is in playback, so a plug-in that dynamically changes its delay settings at run-time should either prevent any algorithmic delay updates during playback or give a visual indication to the user when the delay that it applies and the delay that Pro Tools is compensating for different delay settings.
Pro Tools does not update delay compensation settings when plug-ins go into and out of bypass, and does not automatically maintain bypass audio buffers for delayed plug-ins. It is therefore required that all plug-ins incur the same amount of delay when bypassed as during normal operation.
Automatic Delay Compensation is not applied during offline (AudioSuite) processing for plug-ins which use the Host Processor interface. If your Host Processor plug-in incurs algorithmic delay then you must incorporate audio lookahead via the Host Processor interface's random timeline access API.
Given the many routing possibilities in Pro Tools, the Automatic Delay Compensation feature involves some subtleties that may not be immediately apparent or intuitive. For more information about this feature, we strongly recommend that you review the relevant chapters in the Pro Tools Reference Guide.

Plug-in categories

The plug-in menus in Pro Tools are hierarchical and by default are organized by category. These general categories represent common plug-in functions like EQ, dynamics, reverb, etc. Plug-ins may report one or more of these categories in order to be placed into the proper menu. For a complete list of plug-in categories available, refer to the AAX_EPlugInCategory enum.

Some features, such as control surface center-section mappings, are only available to plug-ins that report a particular category, so it is important for plug-ins to report the correct set of categories.

Advanced non-real-time processing

AudioSuite processing allows AAX plug-in to operate on audio in a non-real-time manner. AudioSuite plug-ins will appear in the AudioSuite menu in Pro Tools. By default, any AAX-Native plug-in will appear in the menu as long as an AAX_eProperty_PlugInID_AudioSuite property is defined alongside the corresponding AAX_eProperty_PlugInID_Native ID. However, to make use of extended AudioSuite features such as non-real-time sample access, the Analysis pass, a separate entry method subclassed from the AAX_CHostProcessor implementation in the SDK should be used.

AudioSuite processing modes

Pro Tools includes a number of different AudioSuite processing modes, each of which changes the precise behavior of an AudioSuite processing event.

Output modes

Overwrite files Output audio destructively overwrites the selected audio files on disk
Create individual files Individual new files are created for each processed clip
Create continuous file A single new file is created with data from the full processing pass

Input modes

Clip by clip
Entire selection

The plug-in may optionally disable the "clip by clip" processing mode if continuous input data is required, by using the property AAX_eProperty_ContinuousOnly.

Channel modes

Mono mode Each selected channel is processed as an individual mono audio stream
Multi-input mode Selected channels are sent to the plug-in in multi-channel streams

Multi-input mode is only valid with the "entire selection" input mode, since the "clip by clip" input mode requires that each clip be processed individually as a standalone audio channel.

The plug-in may optionally disable "mono mode" processing if its algorithm is only valid for multi-channel input, by defining the AAX_eProperty_MultiInputModeOnly property.

Analysis

AudioSuite plug-ins support and optional Analysis pass, which allows a plug-in to access the incoming audio before the actual Render pass starts. When Analysis is defined with either AAX_eProperty_OptionalAnalysis or AAX_eProperty_RequiresAnalysis, an Analyze button will appear in the plug-in footer in the GUI.

An analysis pass is useful for collecting pitch, spectrum, loudness, noise threshold, or other data that will help the user set up parameters based on the audio content being processed.

Reverse

A "reverse" feature is available for Reverb and Delay AudioSuite plug-ins. This effect will reverse the source audio, apply the AudioSuite plug-in processing, and re-reverse the source audio back to its original orientation, thereby applying the AudioSuite effect in reverse.

Reverse replaces the Analysis pass in the Pro Tools UI, so AudioSuite plug-ins in these categories do not receive a user-triggered analysis pass.

Random-access and non-linear processing

The generation of output samples by an AudioSuite Process must occur linearly and incrementally; however, the source of input samples may optionally be randomly accessed from the entire selected track. This enables many advanced processing capabilities such as whole-file analysis, audio reverse effects, and timeline-level modifications such as expanding, contracting, or shifting the processed region.

In order to prevent invalid data from being randomly accessed, the "overwrite files" processing mode is disabled for plug-ins that use random-access processing.

AudioSuite Handles

By default, when processing audio segments with an AudioSuite plug-in, Pro Tools will also process an extra region before and after the selected audio. These extra regions will be trimmed out of the selected.

The reason for this feature is so that the user has some room to expand the resulting audio clip (for fades or other reasons). However, certain AudioSuite plug-ins will operate more intuitively if these handles are not processed (such as delay, reverb, loudness normalization, and other plug-in types). To disable extended handle processing, set the AAX_eProperty_DisableHandles property to true.

Extended features

AAX-AudioSuite plug-ins also have several other optional features including custom progress dialogs, reverse mode, and side-chains. For a complete reference of supported AudioSuite-related properties, refer to the properties between AAX_eProperty_AudiosuitePropsBase and AAX_eProperty_MaxASProp found in Interfaces\AAX_Properties.h.

Using the Pro Tools Scripting SDK with AAX

The Pro Tools Scripting SDK provides a way to control various aspects of Pro Tools. AAX plug-ins may incorporate the Pro Tools Scripting SDK in order to control Pro Tools in ways that are not possible through AAX alone.

The Pro Tools Scripting SDK requires a PTSL connection to be established with Pro Tools. When establishing a PTSL connection from within an AAX plug-in, the connection request must be made using a non-main application thread. Spawn a new thread from within your AAX plug-in to perform all PTSL connection requests and Pro Tools Scripting SDK commands.

Plugins with MIDI support

In most cases, users are able to route MIDI arbitrarily in Pro Tools. Plugin MIDI outputs and inputs are available as MIDI sources and destinations and are available at other routing points such as MIDI track input selectors. AAX plugins with MIDI inputs and outputs can be instantiated just like other real-time effects. AAX MIDI processing and audio processing are not mutually exclusive.

For more information about MIDI in AAX, see MIDI

Pro Tools includes special handling for two common categories of plugins that process MIDI data: Virtual Instruments and MIDI effects

Virtual Instruments convert MIDI data into audio data. To define a Virtual Instrument, include AAX_ePlugInCategory_SWGenerators in the effect's category property.
MIDI effects manipulate MIDI data in real time. To define an AAX MIDI effect, include AAX_EPlugInCategory_MIDIEffect in the effect's category property. See below for more information about MIDI effects.

Pro Tools supports MIDI processing in real time effects only. Virtual Instruments and MIDI effects should not register as AudioSuite plugins.

Instrument tracks

Pro Tools Instrument tracks apply some special rules for MIDI connections. An Instrument track's MIDI input and MIDI playlist are connected to the first MIDI input node of the first Virtual Instrument insert on the track. Instrument tracks also connect chains of MIDI effects together, and include special features for managing inputs and outputs of these chains.

Because inserts on Instrument tracks process both audio and MIDI, the audio format of Virtual Instrument and other effects on Instrument tracks will determine whether the effect is shown in the track's insert lists. Virtual Instruments should register component descriptions for all supported multichannel formats. This will ensure that the instrument shows in the MIDI plug-ins menu on all Instrument tracks regardless of the track's audio format.

For more information about Pro Tools Instrument tracks, Virtual Instruments, and MIDI effect chaining, see the Pro Tools Reference Guide.

MIDI effects and MIDI insert chains

By manipulating MIDI data in real time as it flows through a processing chain, MIDI Effects allow users to apply insert effects to MIDI data just like adding effects to audio data.

To function as a MIDI effect, an effect should define both a MIDI input port and a MIDI output port. When chaining MIDI effects on an Instrument track, Pro Tools will connect incoming MIDI to the first channel of the plugin's first MIDI input node and will connect the first channel of the plugin's first MIDI output node to the next effect in the chain.

MIDI effects that use the AAX_EPlugInCategory_MIDIEffect category will appear in a MIDI plug-ins menu that is separate from the other real-time insert lists on Instrument tracks. This category can also trigger other special handling of the effect in Pro Tools, such as disabling dynamic plugin processing.

Because MIDI effects are also standard AAX inserts, it is possible to process both audio and MIDI. Multi-mono processing is not allowed for MIDI effects since there is only one MIDI channel to process even on multi-channel Instrument tracks. Therefore, even if a MIDI effect's audio processing is only a pass-through, the effect should register component descriptions for all multichannel formats. This will ensure that the product shows in the MIDI plug-ins menu on all Instrument tracks regardless of the track's audio format.

Debugging AAX plug-ins

Debugging within Pro Tools

Shipping versions of Pro Tools do not support attaching a debugger. This is to prevent malicious users from compromising Pro Tools security as well as the security of third-party plug-ins.

As an AAX plug-in developer, you are granted access to debuggable "developer build" versions of Pro Tools to help your development efforts. Some Pro Tools developer builds are feature-limited; for example, developer builds of Pro Tools do not allow saving or exporting sessions.

The easiest way to debug plug-ins within Pro Tools is to start up Pro Tools, open a session, attach your debugger, and then instantiate your plug-in. This order seems to work the best for most users. If you need to debug the initial host query of your plug-in at Pro Tools start, it is possible to launch Pro Tools from within your debugger. However, this method is sometimes known to cause problems with certain debuggers.

AAX plug-in developers are also able to download pre-release and beta versions of upcoming Pro Tools releases. For now, these pre-release versions are not debuggable, but that is expected to change in the future as we work to make a unified debuggable pre-release installer available for upcoming Pro Tools versions.

Both debuggable and pre-release versions are available for download as part of the AAX SDK Toolkit on the My Toolkits and Downloads page at avid.com. In order to use developer and pre-release builds, you will need special licences which you must request from devau.nosp@m.th@a.nosp@m.vid.c.nosp@m.om.

DigiShell

DigiShell is a software tool that provides a general framework for running tests on Avid audio hardware. As a command-line application, DigiShell may be driven as part of a standard, automated test suite for maximum test coverage. The latest DigiShell tools may be downloaded as part of the AAX SDK Toolkit on the My Toolkits and Downloads page at avid.com.

More information about DSH in general and about loading and testing plug-ins in DSH can be found in DSH Guide.

DigiTrace

All Avid AAX hosts provide tracing functionality based on Avid's DigiTrace tool. DigiTrace is a library that provides high-performance logging and tracing capabilities to Pro Tools and its components, including plug-ins. More information about DigiTrace can be found on Avid's audio developer website.

To enable trace logging for AAX plug-ins, use the AAX_TRACE macro defined in AAX_Assert.h. A separate macro, AAX_ASSERT, is also available to signal run-time errors. These macros are both cross-platform and will function whether the algorithm is running on the TI or on the host.

For more information about DigiTrace, see DigiTrace Guide.

Tracing requirements

The AAX_ASSERT and AAX_TRACE macros are debug-only and will not provide tracing output from release builds of your plug-in. AAX_TRACE_RELEASE may be used for tracing in both debug and release configurations. These macros require that the DTF_AAXPLUGINS facility to your DigiTrace configuration file. You can toggle this facility to enable or disable AAX algorithm-level tracing. For details on setting up tracing on AAX TI plug-ins, please refer to the HDX DSP Guide.

Troubleshooting common AAX plug-in failures

Pro Tools presents a "Move Unauthorized Plug-ins" dialog after attempting to launch with my plug-ins installed, and the plug-ins do not appear in the Pro Tools insert menus

This error indicates that Pro Tools was not able to load the plug-in binary for some reason. The error indicates a copy protection failure since that is by far the most common reason for users to encounter this kind of error in released plug-ins, but any other error that prevents the plug-in DLL from loading in Pro Tools may also cause this error message.

This error does not indicate a failure when checking the plug-in's digital signature. A digital signature failure would generate a different error message that would specifically mention the plug-in's signature.

The DTF_AAXHOST DigiTrace facility provides additional information about AAX plug-in load errors.

One common cause of DLL loading failures is a failure to dynamically link to other required libraries. In this case, the DTF_AAXHOST tracing will indicate something like the following:
- ```
AAXH_CEffectFactory::ParseDLL – exception thrown(The specified module could not be found. (126) while loading "MyPlugIn.aaxplugin")
```
This exception indicates that some DLL upon which the plug-in depends is not present in the system. This is most commonly due to dynamic linking to CRT libs, but it could also be caused by any other DLL dependency.

Using DigiOptions

DigiOptions provide a way to override the standard Pro Tools configuration. These options are designed to assist with testing and development of Pro Tools, and they are often useful during plug-in development as well.

To configure DigiOptions, place a plain-text file named DigiOptionsFile.txt next to the Pro Tools application. On macOS, place this file next to the Pro Tools.app bundle and on Windows place it next to the Pro Tools executable.

A red notice will appear in the Pro Tools splash screen and in the application About Box indicating when DigiOptions are enabled in the build.

Figure 3: DigiOption activation notice in the Pro Tools splash screen.

Note: If suffixes are hidden on your OS then be careful that you do not accidentally give the file an incorrect name such as DigiOptionsFile.txt.txt.

Useful DigiOptions

Note: Support for these options may vary from release to release

AlwaysRebuildCache 1
This option forces Pro Tools to re-load all installed plug-ins each time the application is launched. This can be very useful during development, since some plug-in updates during development will not result in an updated plug-in binary or an updated modification date for the top-level .aaxplugin bundle.

Note
If you have changed your plug-in's ID values during development and if you encounter AAE error -20038 when your plug-in is loaded then Pro Tools may be using a cache of the outdated plug-in ID. Use the AlwaysRebuildCache DigiOption or launch Pro Tools once without your plug-in installed to clear this state.
NeverUnloadPlugInBundles <int>
Enable plug-in bundle unloading. The default value for this option is 0. In order to test your plug-ins and make sure that they operate correctly this option must be set to 0.
LogInterruptDataEveryNSeconds <int>
LogInterruptDataEveryNSeconds_HL <int>
These options enable regular DigiTrace performance logging from the low-latency and high-latency real-time audio render threads in the Avid Audio Engine. For example, LogInterruptDataEveryNSeconds_HL 2 would trigger a performance log for the high-latency render thread every two seconds. For more information about performance logging in AAE see Real-time AAE performance logging with DigiTrace.
PauseDuringLaunchToAttachDebugger 1
DisplayHostPlugInLatency 1
Display information about the plug-in's processing domain and dynamic processing status in the Pro Tools plug-in window header.

Figure 4: DisplayHostPlugInLatency info in plug-in header.
TestGetCurveData <0, 1, 2>
Display the plug-in's curve data as a plot in the Pro Tools plug-in window header. Possible values are:
1. Off
2. EQ curve
3. Gain reduction curve
Warning
The implementations of this test curve and the actual curve data shown on Avid control surfaces are different. In particular, the display in Pro Tools is updated regularly at idle time, whereas the curve on a control surface is only updated when certain parameter changes occur (see PTSW-195316 / PT-218485). The graph point interpolation, range, and sample points are also not exactly equivalent to the values used on an actual control surface, so you should not expect the curve shown in the debug view in Pro Tools to exactly match what would appear to users. After performing early prototyping of your curve data using the TestGetCurveData DigiOption you are strongly encouraged to use either the S6 Surfulator software or the Pro Tools | Control app to test and refine the plug-in's curve data in a real-world environment.

For more information about graph curves see EQ and Dynamics Curve Displays .

Figure 5: TestGetCurveData EQ graph in plug-in header.
RenderMissingFilesAsBlank 1
This option may be used to automatically render test tones into audio clips with missing source media. The test tones are rendered with different frequencies and magnitudes. This option can be useful when troubleshooting using a session file provided by an end user, since session-specific issues are rarely dependent on the source media, but may depend on there being some signal present in the session. This option requires that the Avid Signal Generator plug-in is installed.
44100_Rate <int>
48000_Rate <int>
Set the new base sample rate for each set of sample rate multiples. Can be useful for simulating sample rate pull-up by up to +5% (e.g. 44100_Rate 45000 in DigiOptions.txt.) The 44100_Rate option affects 44100, 88200, and 176400 Hz rates, while the 48000_Rate option affects 48000, 96000, and 192000 Hz rates.
EnablePlugInHotSwap 1
Note
This option is currently non-functional for AAX plug-ins Pro Tools. See PTSW-188653 / PT-218451

This option will allow Pro Tools to recognize changes to your plug-in during run-time. This allows you to re-compile and load your updated plug-in without re-launching Pro Tools. The following conditions must be true in order to enable hot-swapping between versions of your plug-in:
- There cannot be any instances of the plug-in currently in Pro Tools.
- Both EnablePlugInHotSwap 1 and AlwaysRebuildCache 1 must be set.
WinDLLErrorMode <int>
Set the Windows error mode during DLL loading and unloading. The value of this option will be set as the uMode for a call to the SetErrorMode Windows API during DLL loading and unloading.

This option can be useful when debugging plug-in load errors on Windows, for example errors that cause a "The following Plug-Ins failed to load because no valid authorization could be found” dialog to appear during Pro Tools launch. </LI> <LI> <DIV CLASS="SectionHead"> <TT>DisableCMNAssert 1</TT></DIV> Disable assert dialogs in Pro Tools. Use this option if your Pro Tools debugging sessions are being interrupted or terminated due to assert failures in the app. Note that Pro Tools asserts may be triggered by your plug-ins; you should always investigate any assert that you see to determine whether it is being caused by a plug-in. If you need information about any Pro Tools asserts, post a question here on the %AAX developer forums or write to us at <a href="avid..nosp@m.deve.nosp@m.loper.nosp@m..ser.nosp@m.vices.nosp@m.@avi.nosp@m.d.com">avid.developer.services@avid.com</a> and we will be happy to help. </LI> <LI> <DIV CLASS="SectionHead"> <TT>TestPlugInDescriptions 0</TT></DIV> Use this DigiOption to toggle the plug-in description validation check in Pro Tools developer builds. Developer builds will check plug-in description information when the plug-in is loaded and will present a warning dialog if the check fails. See \ref describe_validation section in the \ref CommonInterface_Describe page for more information. </LI> <LI> <DIV CLASS="SectionHead"> <TT>RealTimeDenormalsAreZero <int></TT></DIV> Use this DigiOption to toggle the default denormal handling policy of the AAE real-time processing threads. A value of 1 means that DAZ+FZ will be enabled for all %AAX real-time processing threads unless explicitly changed using thread-specific primitives, while a value of 0 means that DAZ+FZ will be disabled unless explicitly changed. The default state of the DAZ+FZ flags for AAE real-time processing threads is turned on by default. </LI> <LI> <DIV CLASS="SectionHead"> <TT>DigiTraceWindow 1</TT></DIV> Enable the Console window in Pro Tools which displays the application's \ref AAX_DigiTrace_Guide "DigiTrace" output in a live stream. \xrefitem compatibility_notes 12. </LI> </UL> </DIV> <DIV CLASS="section">

Compatibility Notes

See Host Support and Known Issues in Pro Tools for additional details regarding Pro Tools compatibility

Collaboration diagram for Pro Tools Guide:

Contents