| AAX SDK 2.6.1 Avid Audio Extensions Development Kit

- Welcome
- Manual
- Classes
- Files
- Lists
- Support

Loading...
Searching...
No Matches
Plug-in type conversion
AAX SDK Manual » Additional Topics

Specification for valid conversions between plug-in types.

# About this specification

The specification on this page defines the valid AAX plug-in type conversions. An AAX host may use this specification to perform automatic type conversions. For example:

- When a session that was saved with a DSP plug-in Type is opened on a Native system the saved DSP Type should be converted to its Native counterpart.
- When a session saved with the free version of a plug-in is opened on a system that has the full version installed then the saved free Type may be converted to the full version.

# Terminology

In this specification the term "Type" refers to a specific configuration of an AAX plug-in.

Each Type is uniquely identified by a combination of five values:

- Manufacturer ID
- Product ID
- Plug-In ID
- Sample rate bit mask
- Architecture

Each Type is defined by a particular call to AAX_IComponentDescriptor::AddProcessProc_Native or AAX_IComponentDescriptor::AddProcessProc_TI in the plug-in's description method.

The Plug-In ID is defined as one of AAX_eProperty_PlugInID_Native or AAX_eProperty_PlugInID_TI.

In this specification, the format for describing an ID is:

[ ID triad + sample rate + architecture ]

Where the ID triad may be expanded to [ [Manufacturer ID] [Product ID] [Plug-In ID] ]

- Explicit values are given in plain face
- Arbitrary constant values are given in bold face
- Wildcard values are given in italics

For example:

- [ ID triad + any sample rate + Native ]
  - Defines all Type identifiers with the same ID triad and the Native architecture, regardless of sample rate.
- [ [ [Manufacturer ID] [Product ID] [any ID] ] + sample rate + Native ]
  - Defines all Type identifiers with the same Manufacturer and Product IDs, the same sample rate, and the Native architecture, but with any plug-in ID.

# Scope of this specification

For the purposes of this specification we are not concerned with AudioSuite Types. Currently these Types are never type-converted.

In theory, an AAX host may apply a "partial" type conversion by swapping between different ProcessProcs without destroying and re-building any of the plug-in's objects (data model, GUI). For the purposes of this specification we are not concerned about whether a given conversion is "partial" or "total"; all conversions are treated the same.

Plug-in conversions are also required between Types of different stem formats. In fact, the supported stem format is an integral part of a Type's unique identifier. This specification ignores the question of stem formats entirely; we assume that each Type supports all necessary stem formats for legal conversion with other Types.

In general, type swapping rules for deprecated types and related types are equivalent. See Type deprecation for more information about the differences between related and deprecated types.

# Topological constraints

- All Types included in a single AAX_ICollection must have the same Manufacturer ID
- All Types included in a single AAX_IEffectDescriptor must have the same Manufacturer ID and Product ID
- The Sample rate bit masks for two Types that share all other identifiers must be non-overlapping. I.e. `0x0 == sr_mask1 & sr_mask2`
- Two Types may not be registered that differ only in their Architecture
- Type relationships may only be defined between mutually exclusive Types. Types are mutually exclusive if:
  - Their sample rate support is non-overlapping
  - The "before" Type's ID triad is not associated with any Type in the plug-in

# Implicit conversions

The AAX host should automatically convert between Types within the following IDs:

- [ ID triad + any sample rate + Architecture ]
- [ [ [Manufacturer ID] [Product ID] [any ID] ] + sample rate + any architecture ]

These conversions occur only if both Types are included in the plug-in when the conversion is made. Consider the following scenario:

1. A session is saved including an plug-in instance with the following Type identifier: [ My ID triad + 48 kHz + TI ]
2. The plug-in is updated to a version that does not include this Type identifier, but that does include [ My ID triad + 48 kHz + Native ]
3. The session is opened on a Native system

In this scenario, if the plug-in had not been updated then an automatic conversion would occur. However, since the plug-in no longer includes the saved Type identifier, no automatic conversion occurs.

A plug-in can work around this situation by including the "old" Type identifier as a Related (or Deprecated) Type (see Explicit conversions.)

When a plug-in instance is saved after making an implicit conversion, plug-ins may be saved with the session using their new Type identifier. This is not required. For example, Pro Tools will prefer to save plug-in instances that were converted from DSP types as DSP, even if they were converted to corresponding Native types when the session was loaded onto and saved from a native Pro Tools system.

# Explicit conversions

AAX includes properties that allow a plug-in to define explicit relationships between different Types. These properties only operate on ID triads. Each property can be associated with an array of ID triads to define a one-to-one or a many-to-one association between the given ID triads and the specific Type to which the property is attached.

- AAX_eProperty_Related_DSP_Plugin_List / AAX_eProperty_Deprecated_DSP_Plugin_List
  - All of the given ID triads specify TI Types
- AAX_eProperty_Related_Native_Plugin_List / AAX_eProperty_Deprecated_Native_Plugin_List
  - All of the given ID triads specify Native Types

The AAX host should convert between related Types within the following constraints:

- [ [ [Manufacturer ID] [Related Product ID] [Related TI Plug-In ID] ] + sample rate + TI ]
  - -> [ [ [Manufacturer ID] [New Product ID | Related Product ID] [New Plug-In ID] ] + sample rate + any architecture ]
- [ [ [Manufacturer ID] [Related Product ID] [Related Native Plug-In ID] ] + sample rate + Native ]
  - -> [ [ [Manufacturer ID] [New Product ID | Related Product ID] [New Plug-In ID] ] + sample rate + any architecture ]

These conversions will occur regardless of whether the related ID triad is used for any of the Types in the plug-in.

When a plug-in instance is saved after making an explicit conversion, all plug-ins are saved with the session using their new Type identifier.

Host Compatibility Notes:
  Pro Tools versions prior to Pro Tools 12.3 do not allow explicit type conversion between types with different product ID values. Beginning in Pro Tools 12.3 both the product ID and the plug-in ID may differ between explicitly related types.

# Type deprecation

There are two varieties of explicit plug-in type association: related types and deprecated types.

Properties that create a related type association:

- AAX_eProperty_Related_Native_Plugin_List
- AAX_eProperty_Related_DSP_Plugin_List

Properties that create a deprecated type association:

- AAX_eProperty_Deprecated_Native_Plugin_List
- AAX_eProperty_Deprecated_DSP_Plugin_List
- AAX_eProperty_PlugInID_Deprecated

With a few exceptions, these two types of explicit association are treated identically. These are the ways in which deprecated plug-in type association differs from related plug-in type association:

- If plug-in types A and B are both installed, and if type A deprecates type B, then type B will be excluded from all insert lists in Pro Tools and will be made invisible to the user.
- If plug-in types A and B are both installed, and if type A deprecates type B, then instances of type B will be swapped to type A when a session containing saved instances of type B is opened.
- Upon the next session save following a swap due to a deprecated type association, the plug-in instance will be saved into the session using the ID of the new plug-in type. Therefore deprecated type swaps do not round-trip when moving between multiple systems if some of the systems have the deprecated types, but not the deprecating types, installed.

Type deprecation should only be used when a new version of an effect completely replaces an old version of the effect. For all other situations, type relationship should be used.

Host Compatibility Notes:

- Pro Tools versions before Pro Tools 12.3 treat deprecated and related type associations identically and do not support type deprecation features
- Media Composer does not support type deprecation features
- VENUE does not support type deprecation features

Collaboration diagram for Plug-in type conversion: