AAX Platform API

The AAX (Avid Audio eXtension) implementation provides complete integration with Pro Tools and other Avid hosts through the AAX SDK.

Overview

The IPlugAAX class implements the AAX API, inheriting from Avid’s AAX_CIPlugParameters class to provide seamless integration with Pro Tools’ parameter system, automation, and rendering architecture.

AAX is the native plugin format for Pro Tools 11 and later. It replaced RTAS and supports modern features like 64-bit processing, extended channel configurations, and Pro Tools HDX.

Core Classes

IPlugAAX

Defined in: IPlug/AAX/IPlugAAX.h

class IPlugAAX : public IPlugAPIBase
               , public IPlugProcessor
               , public AAX_CIPlugParameters

The main AAX plugin class, handling:

Parameter synchronization
Audio rendering with Pro Tools’ algorithm callback
State management (chunks)
MIDI I/O
Track context information

AAX_CEffectGUI_IPLUG

class AAX_CEffectGUI_IPLUG : public AAX_CEffectGUI

AAX GUI wrapper class that bridges iPlug’s editor with Pro Tools’ view system. Key Methods:

Create() - Factory method to create GUI instances
SetControlHighlightInfo() - Handles control highlighting from Pro Tools
GetViewSize() - Returns editor dimensions
ParameterUpdated() - Handles parameter updates from host

Key Methods

Host Communication

BeginInformHostOfParamChange

void BeginInformHostOfParamChange(int idx) override;

Notifies Pro Tools that a parameter gesture is beginning. Parameters:

idx - Parameter index

InformHostOfParamChange

void InformHostOfParamChange(int idx, double normalizedValue) override;

Informs Pro Tools of a parameter value change. Parameters:

idx - Parameter index
normalizedValue - Normalized parameter value (0.0 to 1.0)

EndInformHostOfParamChange

void EndInformHostOfParamChange(int idx) override;

Notifies Pro Tools that a parameter gesture has ended. Parameters:

idx - Parameter index

Editor

EditorResize

bool EditorResize(int viewWidth, int viewHeight) override;

Requests an editor size change. Parameters:

viewWidth - New width in pixels
viewHeight - New height in pixels

Returns: true if resize was accepted

Pro Tools has restrictions on when plugins can resize. Dynamic resizing during playback may not be supported in all versions.

Track Information

GetTrackName

void GetTrackName(WDL_String& str) override;

Retrieves the name of the track the plugin is inserted on. Parameters:

str - String to receive track name

Pro Tools provides detailed track context information including track name, color, and position in the session.

Processing

SetLatency

void SetLatency(int samples) override;

Sets the plugin’s processing latency. Parameters:

samples - Latency in samples

AAX latency must be declared at initialization and cannot be changed dynamically. Set latency in your plugin’s EffectInit() method.

MIDI

SendMidiMsg

bool SendMidiMsg(const IMidiMsg& msg) override;

Sends a MIDI message from the plugin to Pro Tools. Parameters:

msg - MIDI message to send

Returns: true if message was sent successfully

MIDI output requires configuring the output MIDI node in your AAX descriptor during registration.

AAX-Specific Methods

EffectInit

AAX_Result EffectInit() override;

Initializes the AAX effect. Called once when the plugin is loaded. Returns: AAX_SUCCESS on successful initialization Usage: This is where you should:

Register parameters
Configure algorithm processing IDs
Set up MIDI nodes
Declare latency

Example:

AAX_Result MyPlugin::EffectInit()
{
  AAX_Result result = IPlugAAX::EffectInit();
  
  // Additional AAX-specific initialization
  
  return result;
}

RenderAudio

void RenderAudio(
    AAX_SIPlugRenderInfo* ioRenderInfo,
    const TParamValPair* inSynchronizedParamValues[],
    int32_t inNumSynchronizedParamValues) override;

Main audio rendering callback. Parameters:

ioRenderInfo - Render context with buffers, MIDI, meters
inSynchronizedParamValues - Array of synchronized parameter changes
inNumSynchronizedParamValues - Number of parameter changes

RenderAudio runs on the Pro Tools audio thread. It must be real-time safe: no allocations, no locks, no system calls.

UpdateParameterNormalizedValue

AAX_Result UpdateParameterNormalizedValue(
    AAX_CParamID iParameterID,
    double iValue,
    AAX_EUpdateSource iSource) override;

Handles parameter updates from Pro Tools. Parameters:

iParameterID - AAX parameter ID (string)
iValue - Normalized value (0.0 to 1.0)
iSource - Update source (UI, automation, etc.)

Returns: AAX_SUCCESS on success

State Management

AAX supports chunk-based state storage for plugins with complex state or non-parameter data.

GetChunkIDFromIndex

AAX_Result GetChunkIDFromIndex(int32_t index, AAX_CTypeID* pChunkID) const override;

Returns the chunk ID for a given index. Parameters:

index - Chunk index (0-based)
pChunkID - Receives chunk type ID

Returns: AAX_SUCCESS on success

GetChunkSize

AAX_Result GetChunkSize(AAX_CTypeID chunkID, uint32_t* pChunkSize) const override;

Returns the size of a chunk. Parameters:

chunkID - Chunk type ID
pChunkSize - Receives chunk size in bytes

Returns: AAX_SUCCESS on success

GetChunk

AAX_Result GetChunk(AAX_CTypeID chunkID, AAX_SPlugInChunk* pChunk) const override;

Saves chunk data. Parameters:

chunkID - Chunk type ID
pChunk - Chunk structure to fill

Returns: AAX_SUCCESS on success

SetChunk

AAX_Result SetChunk(AAX_CTypeID chunkID, const AAX_SPlugInChunk* pChunk) override;

Restores chunk data. Parameters:

chunkID - Chunk type ID
pChunk - Chunk data to restore

Returns: AAX_SUCCESS on success

CompareActiveChunk

AAX_Result CompareActiveChunk(
    const AAX_SPlugInChunk* pChunk,
    AAX_CBoolean* pIsEqual) const override;

Compares chunk data with current state for Pro Tools’ compare light. Parameters:

pChunk - Chunk to compare
pIsEqual - Receives comparison result

Returns: AAX_SUCCESS on success

The compare light in Pro Tools indicates when the plugin’s current state differs from the saved state. Implement proper comparison for accurate feedback.

DirtyPTCompareState

void DirtyPTCompareState();

Marks the plugin state as changed for the Pro Tools compare light. Usage:

// After changing non-indexed parameters or internal state
DirtyPTCompareState();

Call this when your plugin’s state changes in a way that’s not captured by indexed parameters (e.g., custom data, imported samples, etc.).

NotificationReceived

AAX_Result NotificationReceived(
    AAX_CTypeID type,
    const void* data,
    uint32_t size) override;

Handles notifications from Pro Tools. Parameters:

type - Notification type ID
data - Notification data
size - Data size in bytes

Returns: AAX_SUCCESS on success

Configuration

AAX Setup Structure

Defined in: IPlug/AAX/IPlugAAX_Parameters.h

struct AAX_SIPlugSetupInfo
{
  // MIDI configuration
  bool mNeedsGlobalMIDI;
  const char* mGlobalMIDINodeName;
  uint32_t mGlobalMIDIEventMask;
  bool mNeedsInputMIDI;
  const char* mInputMIDINodeName;
  uint32_t mInputMIDIChannelMask;
  bool mNeedsOutputMIDI;
  const char* mOutputMIDINodeName;
  
  // Transport
  bool mNeedsTransport;
  
  // Metering
  int32_t mNumMeters;
  const AAX_CTypeID* mMeterIDs;
  
  // Audio I/O
  AAX_EStemFormat mInputStemFormat;
  AAX_EStemFormat mOutputStemFormat;
  
  // Identifiers
  AAX_CTypeID mManufacturerID;
  AAX_CTypeID mProductID;
  AAX_CTypeID mPluginID;
  
  // Configuration
  bool mCanBypass;
  int32_t mLatency;
  // ...
};

Common Stem Formats

Mono/Stereo

AAX_eStemFormat_Mono     // 1 channel
AAX_eStemFormat_Stereo   // 2 channels

Surround

AAX_eStemFormat_5_0      // 5.0 surround
AAX_eStemFormat_5_1      // 5.1 surround
AAX_eStemFormat_7_0_DTS  // 7.0 surround
AAX_eStemFormat_7_1_DTS  // 7.1 surround

Immersive

AAX_eStemFormat_7_0_2    // 7.0.2 Atmos
AAX_eStemFormat_7_1_2    // 7.1.2 Atmos
AAX_eStemFormat_Ambi_1_ACN // Ambisonics

Special

AAX_eStemFormat_INT32_IN // Aux input
AAX_eStemFormat_None     // No audio

Plugin Configuration

Set in your plugin’s config.h:

#define PLUG_TYPE 0 // 0=effect, 1=instrument
#define PLUG_MFR_ID 'Acme'
#define PLUG_UNIQUE_ID 'Plug'
#define PLUG_LATENCY 0

// AAX-specific
#define AAX_TYPE_IDS 'EFN1', 'EFN2' // Native processing IDs
#define AAX_PLUG_MFR_STR "Acme"
#define AAX_PLUG_NAME_STR "MyPlugin"
#define AAX_PLUG_CATEGORY_STR "Effect"
#define AAX_DOES_AUDIOSUITE 1

Factory Function

Create

static AAX_CEffectParameters* AAX_CALLBACK Create();

AAX factory method to create plugin instances. Returns: Pointer to new AAX_CEffectParameters instance (your plugin class) Example:

AAX_CEffectParameters* AAX_CALLBACK IPlugAAX::Create()
{
  InstanceInfo info;
  return MakePlug(info);
}

MakePlug

IPlugAAX* MakePlug(const InstanceInfo& info);

Your plugin factory function. Parameters:

info - Instance information (empty for AAX)

Returns: Pointer to plugin instance Example:

IPlugAAX* MakePlug(const InstanceInfo& info)
{
  return new MyPlugin(info, MakeConfig(kNumParams, kNumPresets));
}

Best Practices

Parameter IDs

AAX uses string-based parameter IDs. iPlug2 handles conversion automatically, but parameters use an offset of kAAXParamIdxOffset.

Chunk State

Use chunks for complex state. Always implement CompareActiveChunk() properly for the compare light to work correctly.

MIDI Setup

Configure MIDI nodes during descriptor registration, not in EffectInit(). Declare all MIDI needs upfront.

Latency

AAX latency is fixed at initialization. For variable latency algorithms, declare the maximum possible latency.

Common Issues

DSP Thread: Pro Tools’ audio callback runs on a high-priority thread. Any blocking call will cause audio dropouts or crash Pro Tools.

Parameter Updates: Parameter updates in RenderAudio must be processed sample-accurately using the synchronized parameter values.

Signing: AAX plugins must be code-signed with a certificate from Avid (PACE). Contact Avid to join the AAX developer program.

AudioSuite: Set AAX_DOES_AUDIOSUITE 1 to create an offline processing version of your plugin for Pro Tools’ AudioSuite menu.

IPlugAPIBase - Base API functionality
IPlugProcessor - Audio processing interface
Plugin Configuration - Plugin configuration options
AAX SDK Documentation - Official AAX documentation (requires developer account)

​AAX Platform API

​Overview

​Core Classes

​IPlugAAX

​AAX_CEffectGUI_IPLUG

​Key Methods

​Host Communication

​BeginInformHostOfParamChange

​InformHostOfParamChange

​EndInformHostOfParamChange

​Editor

​EditorResize

​Track Information

​GetTrackName

​Processing

​SetLatency

​MIDI

​SendMidiMsg

​AAX-Specific Methods

​EffectInit

​RenderAudio

​UpdateParameterNormalizedValue

​State Management

​GetChunkIDFromIndex

​GetChunkSize

​GetChunk

​SetChunk

​CompareActiveChunk

​DirtyPTCompareState

​NotificationReceived

​Configuration

​AAX Setup Structure

​Common Stem Formats

Mono/Stereo

Surround

Immersive

Special

​Plugin Configuration

​Factory Function

​Create

​MakePlug

​Best Practices

Parameter IDs

Chunk State

MIDI Setup

Latency

​Common Issues

​Related Documentation

AAX Platform API

Overview

Core Classes

IPlugAAX

AAX_CEffectGUI_IPLUG

Key Methods

Host Communication

BeginInformHostOfParamChange

InformHostOfParamChange

EndInformHostOfParamChange

Editor

EditorResize

Track Information

GetTrackName

Processing

SetLatency

MIDI

SendMidiMsg

AAX-Specific Methods

EffectInit

RenderAudio

UpdateParameterNormalizedValue

State Management

GetChunkIDFromIndex

GetChunkSize

GetChunk

SetChunk

CompareActiveChunk

DirtyPTCompareState

NotificationReceived

Configuration

AAX Setup Structure

Common Stem Formats

Plugin Configuration

Factory Function

Create

MakePlug

Best Practices

Common Issues

Related Documentation