AAX SDK  2.4.1
Avid Audio Extensions Development Kit

Details about using AAX plug-ins in Pro Tools.

Contents

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.
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.

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.
 
  Real-time insert slots in the Pro Tools Edit and Mix windows
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:
  1. Be installed to the AAX plug-ins directory
  2. Use a valid file name
  3. Be signed with a valid digital signature
    Note
    Digital signatures for plug-ins are not required in Pro Tools developer builds

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 OS X, 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.
Note
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.
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 partners@avid.com with "Pace Tools Request" in the subject. Include the following information in your request:
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 11
Host Compatibility Notes:
Pro Tools 11 requires PACE Eden digital signatures for AAX plug-ins.
Pro Tools 11 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 11 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 11.
Signature requirements in Pro Tools 10
Host Compatibility Notes:
Pro Tools 10 requires either PACE DSig or Eden digital signatures for AAX plug-ins.
For compatibility with Pro Tools 10, AAX plug-ins must be digitally signed using PACEDSigTool.
Pro Tools 10.3.5 and above also support the new Eden signatures from PACE, so that universal binaries can be shipped which target both Pro Tools 11 or later and Pro Tools 10.3.5 or later.
Optional Signature for Pro Tools AAX DSP binaries
Host Compatibility Notes:
As of Pro Tools 10.2, support has been added to allow binary-level encryption of 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 10, 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:

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:
  1. The plug-in's data model component is loaded
  2. The default state of the plug-in is set (see Default plug-in settings)
  3. The plug-in's GUI and other host modules are loaded
  4. The plug-in's algorithm private data state is initialized
  5. The plug-in's algorithm is loaded and initialized
  6. The plug-in's algorithm processing is initiated

Run-time processing behavior

Pro Tools 11

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

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 11 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 11 at the time of this writing. These rules are subject to change from release to release:
Pro Tools 10
In Pro Tools 10, the audio engine is constantly running. Real-time plug-in instances are active from the moment they are created until they are removed from the session, regardless of audio playback, routing, or other run-time state changes. This design carries some implications for plug-in behavior in Pro Tools 10:
Note that, during looped playback, processing from the end of the loop carries seamlessly to the beginning of the loop - the plug-in's state is not reset at the loop point.

New to Pro Tools 11

In addition to the real-time processing changes mentioned above, several other relevant features were added to the audio engine in Pro Tools 11.
For a full list of compatibility and feature differences between different AAX plug-in hosts, see Host Support.

Deterministic Plug-in Automation

Starting in Pro Tools 11, 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.

Deprecated and Related Plug-in Lists

To help ease the transition for users to 64-bit, Pro Tools 11 includes support for deprecated and related plug-in types. This allows you to associate any legacy plug-ins with new AAX plug-in types so that Pro Tools can automatically convert sessions with older plug-ins to the new types.

Offline Bounce

Pro Tools now 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.

AAX Hybrid Plug-ins

Pro Tools 11 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.

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:
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.
The Plug-In Settings menu in the Pro Tools plug-in window header
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:
The default setting for the User Library root directory is ~/Documents/Pro Tools on OS X, but the user can change this setting in the Pro Tools preferences.

Factory presets

Starting in Pro Tools 10.3.6, 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:
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:
  1. Instantiate the plug-in and create a AAX_IEffectParameters object
  2. Look for the cached factory default settings file in the file system
  3. 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
  4. Set the instance's default settings based on the settings stored in the cached factory default file
  5. Send the instance a AAX_eNotificationEvent_SessionBeingOpened notification
  6. 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:
OS X 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:
OS X 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 beginning in Pro Tools 12.0.1.
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:
If a plug-in is going to utilize the AOS feature, it will be responsible for a few details that are summarized below:

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.

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

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
Input modes
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
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.

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 10 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.

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 TI 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

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 OS X, place this file next to the Pro Tools.app bundle and on Windows place it next to the Pro Tools executable.
In recent versions of Pro Tools, 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.
DigiOption activation notice in the Pro Tools splash screen
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

Compatibility Notes

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

Changing parameter names

Name changes for automatable plug-in parameters are only supported starting in Pro Tools 11.1. This applies both to changing a parameter Name at runtime with AAX_IParameter::SetName() and to changing a parameter Name between different versions of the plug-in.
Versions of Pro Tools prior to Pro Tools 11.1 will not be able to load automation data for a parameter whose Name has been changed. If any of your plug-in's automatable parameters' Names change, you must document that the plug-in is not supported in any Pro Tools versions prior to Pro Tools 11.1.
Specifically, automation data for a parameter will be lost if the following conditions occur:
In addition, any parameter whose Name has changed will not appear as automatable (its automation lanes will disappear and it will not appear in the plug-in's automation list) if a session last saved in Pro Tools 11.1 is opened in an earlier version of Pro Tools. In this situation the automation data for the parameter may still be available, and may be restored if the session is later re-opened in Pro Tools 11.1.
Collaboration diagram for Pro Tools Guide: