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.
-
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.
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
- 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.
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:
- Company name
- Company mailing address
- Contact information for your AAX development lead or team
- iLok username which you will use for your digital signing admin account
Once your request has been approved you will be contacted by PACE with further instructions for acquiring and using the digital signature toolkit.
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
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
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:
-
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
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:
-
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 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:
-
(HDX 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 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 only) Any AAX Native plug-in instance on an AUX track will be run at low latency.
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:
-
When Pro Tools is not in playback, plug-ins are sent a constant stream of "silence" via zeroed audio buffers
-
Plug-ins must process these buffers and may generate output data into them at any time
-
Processing "tails" (e.g. reverb or delay) should be applied at all times, even after playback has stopped
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:
-
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 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:
-
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:
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:
-
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 versions that support gain reduction metering 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
Pro Tools uses a plug-in's reported meter values to determine whether the plug-in may have clipped internally. Any meter that reports a value greater than 1.0 is considered to be clipped, and Pro Tools will report that the plug-in has clipped internally if any of its registered meters have clipped. This clip state is held for a length of time based on a user preference in Pro Tools.
The plug-in header has a clip light that indicates that the plug-in has clipped somewhere internally. 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. Currently, plug-in clip indicators are available in Pro Tools HD software only.
- Host Compatibility Notes:
- In Pro Tools 11 and above, the Avid Audio Engine (AAE) no longer automatically generates clipping indication for plug-ins. This is because the new engine can operate properly well beyond a unity sample value of 1.0. Thus, it is up to the plug-in itself to set and clear its clip indicators as needed.
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.
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.
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
-
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:
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 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.
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 behavior in Pro Tools 11 and Pro Tools 12 is for this option to be set to 1. In a future release of Pro Tools 12, the default for this option will be changed to 0. Therefore it is very important to test your plug-ins and make sure that they operate correctly with the option set to 0.
- Host Compatibility Notes:
- Supported in Pro Tools 12 and higher.
-
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
(Starting in Pro Tools 11)
AssertOnLoadPlugins 1
(Pro Tools 10 and earlier)
This option will trigger a dialog and pause execution just before Pro Tools begins loading plug-ins. Due to Pro Tools copy protection it may be impossible to launch Pro Tools Developer Builds directly from a debugger, and, when this is the case, this dialog provides a good point at which to attach a debugger to Pro Tools.
-
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:
-
Off
-
EQ curve
-
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 .
- Host Compatibility Notes:
- Supported in Pro Tools 12 and higher.
Figure 5: TestGetCurveData EQ graph in plug-in header.
-
RenderMissingFilesAsBlank 1
Beginning in Pro Tools 10, 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.
- Host Compatibility Notes:
- Supported in Pro Tools 12 and higher.
-
DisableCMNAssert 1
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 devse.nosp@m.rvic.nosp@m.es@av.nosp@m.id.c.nosp@m.om and we will be happy to help.
-
TestPlugInDescriptions 0
Use this DigiOption to toggle the plug-in description validation check in Pro Tools developer builds. Developer builds beginning in Pro Tools 12.8.2 will check plug-in description information when the plug-in is loaded and will present a warning dialog if the check fails. See Describe Validation section in the Description callback page for more information.
- Host Compatibility Notes:
- Supported in Pro Tools 12.6 and higher.
-
RealTimeDenormalsAreZero <int>
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 varies depending on the AAE version and on the OS: On Windows, DAZ+FZ is turned on (i.e. denormals are set to zero) in the AAE builds used in Pro Tools 11 and higher, and in the corresponding AAE builds used in Media Composer and VENUE. On Mac, DAZ+FZ is turned off by default in the AAE builds used in all releases prior to Pro Tools 12.7. Starting in Pro Tools 12.7, DAZ+FZ is turned on by default for both Mac and Windows.
- Host Compatibility Notes:
- Supported in Pro Tools 12.8.2 and higher.
-
DigiTraceWindow 1
Enable the Console window in Pro Tools which displays the application's DigiTrace output in a live stream.
- Host Compatibility Notes:
- Supported in Pro Tools 2019.XX and higher. Also supported (and enabled by default) in Pro Tools developer builds beginning with Pro Tools 2019.6.
Compatibility Notes
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:
-
The session was saved using the parameter Name A.
-
The default Name for the parameter is not A when the session is opened.
-
Either of the following:
-
The session is being opened in a version of Pro Tools prior to Pro Tools 11.1
-
The session was last saved in a version of Pro Tools prior to Pro Tools 11.1 and the parameter's ID is not A
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.