AAX SDK  2.4.1
Avid Audio Extensions Development Kit
Media Composer Guide

Details about using AAX plug-ins in Media Composer.

Contents

About this document

This guide discusses specific details related to using AAX plug-ins with Media Composer, such as loading and initialization procedures, GUI hosting, and other application-specific features.
For more information about the features, functionality, and use of Media Composer see the Media Composer user documentation.

Processing modes

Media Composer supports AAX plug-ins in two processing modes: AudioSuite and AAX Native
AAX plug-in processing in Media Composer is managed by specific Tools. Each of these Tools can be accessed using the "Tools" menu in the Media Composer application.

Non-real-time processing (AudioSuite)

Use the AudioSuite Tool to perform AudioSuite processing in Media Composer. The AudioSuite Tool applies an effect to a clip in the timeline of the record monitor.
Specific AudioSuite plug-ins appear in the Plug-In Selection menu in the AudioSuite window.
Note
Unlike Pro Tools, the effect to clip relationship is remembered along with the effect parameters used. Parameters to the effects can be changed at a later time, and at any time the effect can be re-rendered with the saved effect parameters. Therefore it is very important for AudioSuite plug-ins to maintain compatibility between instances, versions, and systems in order to function properly in Media Composer workflows. See Preset management for more information.
Media Composer supports two AudioSuite processing modes:
By default, the AudioSuite window displays the controls for applying a plug-in to a clip in the Timeline. When you drag a master clip into the window, the window expands to display additional parameters for working with master clips.

Applying an AudioSuite Plug-in to a Clip in the Timeline

The following illustration shows the default layout of the AudioSuite window:
The AudioSuite window
Figure 1: The AudioSuite window
To apply an AudioSuite plug-in to a clip in the Timeline:
  1. Open the AudioSuite window by doing one of the following:
    • Select Tools > AudioSuite
    • If an audio tool is already open, click the Effect Mode Selector menu and select AudioSuite
  2. Use the Track Selection Menu button to select the tracks that you want to modify.
    • When you select an item from this menu, the system selects or deselects the corresponding track in the Timeline
    • To select multiple tracks, press the Shift key while you select additional tracks from the Track Selection menu. Plus signs (+) mark the additional tracks and indicate that the effect is applied to more than one track.
  3. Click the Plug-In Selection menu, and select a plug-in
  4. Click the Activate Current Plug-In button. This opens a dialog box associated with the plug-in.
From the AudioSuite dialog box, you may make any necessary adjustments to the plug-in and Preview the effect in real-time.

AudioSuite Master Clip Mode

Drag a Master Clip into the AudioSuite Tool to engage AudioSuite Master Clip Mode. This mode supports all AudioSuite effects, including those that change the width or length of the effected clip. A new Master Clip is generated for each AudioSuite processing pass applied in this mode.
In Master Clip Mode, the AudioSuite window will be expanded to display additional controls. You can also click the Display/Hide Master Clip Controls button to display or hide the additional parameters.
The following operations are available in Master Clip Mode:
For more information about processing in Master Clip Mode, see the Media Composer user documentation.

Restrictions on AudioSuite processing

Real-time processing

Use the Audio Track Effect Tool to perform real-time processing in Media Composer. Audio Track Effects appear in the Audio tab of the Effect Palette, as well as in the menus of the Audio Track inserts in the Audio Mixer Window and the Timeline Track Control Panel.
Real-time AAX processing in Media Composer is analogous to the track inserts feature in Pro Tools. For more information about track inserts in Pro Tools, see the Real-time processing section in the Pro Tools Guide.

Creating and accessing real-time plug-in instances

To insert a plug-in effect on a track in Media Composer, select the track where you want to apply the effect, which insert location you want to use on the track, and the specific effect you want to add to your sequence.
You can also insert a plug-in track effect by dragging an Audio Track Effect template from a bin to your sequence.
To insert an Audio Track Effect plug-in from the Timeline

Right-click the Record Track button or the Track Control panel for the track where you want to apply the insert and select AAX Effects [track number] > Insert [a-e] > [insert].

To insert an Audio Track Effect plug-in using the insert button
  1. Click an Audio Effect insert button in the Track Control panel for the track where you want to apply the insert. This opens the Audio Track Effect tool.
  2. Click the Select Effect button, and select an Audio Track Effect plug-in effect. Audio Track Effect Tool
    Figure 1: Select an insert in the Audio Track Effect Tool
To insert an plug-in using the Effect Palette
  1. In the Project window, click the Effects tab. This opens the Effect Palette. Effect Palette
    Figure 2: The Effect Palette
  2. Click the Audio tab.
  3. Click an effect category, select the effect you want, and drag it to the segment or to the Audio Track Effect insert button where you want to apply the insert. This opens the Select Insert dialog box. Select Insert dialog
    Figure 3: The Select Insert dialog box
    Note
    You can only insert mono effects on a mono track, stereo effects on a stereo track, and surround sound effects on a surround sound track.
  4. Do one of the following:
    • If you want to add a new insert, click an [Empty] insert button.
    • If you want to replace an existing insert, click the appropriate insert button.
    The plug-in effect is inserted in the track to which you dragged the effect icon.
To edit an existing Audio Track Effect Plug-In

After you insert an Audio Track Effect plug-in on an audio track, you can access the plug-in controls by using the Track Control panel or the Audio Track Effect tool.

Audio Track Effect plug-in inserts in the Track Control panel
Figure 4: Audio Track Effect plug-in inserts in the Track Control panel

Audio Track Effect tool

Figure 5: Audio Track Effect tool: Select Track, Select Insert, and Select Effect buttons (left), Bypass button (center), and Save Effect button (right)
When you select an insert button in the Track Control panel or an effect in the Audio Track Effect tool, the controls for the plug-in appear in the Audio Track Effect tool window.
The Compressor/Limiter Dyn 3 plug-in window
Figure 6: The Compressor/Limiter Dyn 3 plug-in window displayed in the Audio Track Effect tool dialog box
You can also open the tool by selecting Tools > Audio Track Effect Tool or right-clicking the Record Track button for the track where you want to edit an insert and selecting Audio Track Effect tool. You can use the buttons in the tool to select a specific insert to edit.
To save changes to a plug-in's settings, do one of the following:

Using Audio Track Effect Templates

If you apply an Audio Track effect and make a set of adjustments to it, you can quickly recreate the same sound on other tracks in your sequence or project. You can save an Audio Track effect with its parameter settings to a bin as an effect template. You can then apply the template to other audio tracks at any time.
You can apply an Audio Track effect template with all its parameters directly to an Audio Track Effect insert button in the Track Selection panel or to clips in the Timeline.
To save an Audio Track Effect as a template

Do one of the following:

A new track effect template appears in the bin, containing the parameter setting information for the effect. The new effect template is identified in the bin by an effect icon. By default, your Avid editing application names the template by the plug-in name.
To apply an Audio Track Effect template to an audio track

Do one of the following:

This applies the effect to the track.

Compatibility requirements

Media Composer supports 64-bit AAX Native plug-ins beginning in Media Composer 8.1. There are no Media Composer versions that support 32-bit AAX plug-ins, and Media Composer does not currently support AAX DSP plug-ins.
In addition to implementing the client-side AAX API for a supported platform, Media Composer AAX plug-ins must:
  1. Be installed to the AAX plug-ins directory
  2. Use a valid file name

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.
Host Compatibility Notes:
Some early versions of Media Composer 8 do not search the system plug-ins directory recursively. If your plug-ins are installed into a sub-directory beneath this main directory then they will not be loaded by the affected versions of Media Composer.
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.
Media Composer will also search for a Plug-Ins directory next to the actual Media Composer 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.

AAX feature support in Media Composer

Media Composer supports many of the same AAX features as Pro Tools. However, some features are not available in Media Composer, and other features are managed differently between the two applications. This section describes how Media Composer handles various optional AAX features.

Processing configurations

Sample rates

Media Composer operates at sample rates of 32000, 44100, 48000, 88200, 96000 Hz, as well as each rate's film pulldown version scaled by a ratio of 1000/1001: approximately 31968, 40959, 47952, 88111, 95904 Hz.

Note
The AAX API does not currently provide a selector for 32 kHz sample rate support
Track formats

Media Composer supports only four track formats:

Effects will only see these track formats on input.
Note
Plug-ins that support width-changing configurations between supported and unsupported track formats are not compatible with Media Composer
Channel ordering for plug-ins in Media Composer is identical to the channel ordering in Pro Tools. The channel ordering presentation to users may vary from the channel ordering that is used when sending audio buffers to Pro Tools; Media Composer re-orders channels to Pro Tools order prior to presenting the audio to the effect.

Preset management

Media Composer stores plug-in presets in several locations within the app. Presets may be stored and accessed through the following workflows:
The storage of AudioSuite presets with clips in Media Composer is very different from Pro Tools. To ensure compatibility with Media Composer, it is very important that any AudioSuite effect can be re-rendered from the source media at any time.

Plug-in preset compatibility and persistance

It is always important to design AAX plug-in preset data in a way that will be compatible across different systems and at different points in time. This is particularly true when designing an AAX plug-in to be compatible with Media Composer.
Media Composer sequences carrying presets can be exported as AAF, and these sequences may be moved freely between Media Composer systems on different operating systems and platforms. Therefore, it is important that plug-in preset data is not platform specific. A plug-in loaded in any given Media Composer system must be able to successfully read, parse, and apply preset information that was created on a different system.
Presets also persist for a long time in sequences, so preset information should be formatted in a way that newer plug-ins can read older version's data, and older versions can read newer version's data.
In addition, Media Composer 8.4 and higher can access factory presets and user-created presets interoperably with Pro Tools. A user can save a preset in one application, and access it in the other.
These preset compatibility considerations also apply to plug-ins carried over from legacy plug-in formats such as TDM/RTAS. Media Composer 8.1 and higher (with 64-bit AAX support) will match plug-in IDs when loading sequence data saved with Media Composer 7 and below, which use older plug-in formats. The same system is used for matching plug-in IDs when moving presets between different versions of Pro Tools, and between Pro Tools and Media Composer: in all cases, a preset saved for a particular plug-in ID must be compatible with all other plug-ins that use that ID, regardless of the plug-in format.

Plug-in preset data comparison

Media Composer's rendered AudioSuite effect feature relies on a comparison of plug-in settings chunk data. Unlike in Pro Tools, this operation uses direct data comparison rather than AAX_IEffectParameters::CompareActiveChunk(). Therefore, Media Composer compatibility and proper operation of AudioSuite rendering in Media Composer depends on the plug-in having fully consistent AAX preset contents from one run to the next.
Two specific areas where problems can occur are:
Both of these can result in differences between settings chunks representing the same plug-in state, which causes Media Composer to perpetually re-render the plug-in.
The problem of uninitialized memory is obvious. Given a particular plug-in state, Media Composer expects that any retrieved settings chunk will contain matching data regardless of when the chunk is retrieved. When the chunk contains uninitialized data this data does not match between different retrieved chunks. The fix, of course, is to make sure the entire chunk is initialized, for example by setting the entire chunk to zeroes before filling in the data.
The problem of floating point values is more subtle. Depending on the plug-in's parameter implementation, floating point values may be slightly different in the lowest-order bits when set onto the plug-in as part of an incoming chunk and when subsequently read out. When this occurs, Media Composer sees a mismatch in the chunk data, which causes the AudioSuite plug-in to unexpectedly be seen as requiring a new render.
AAX plug-in developers will need to avoid both of these conditions in order to maintain compatibility with Media Composer's AudioSuite effect rendering model.

Unsupported features

The following AAX features are not supported by Media Composer. Plug-ins that require these features will not be compatible with Media Composer. If your plug-ins use these features for advanced functionality but not for basic operation then you should document this restriction for Media Composer users.

Additional feature support notes

Additional Information

Audio Engine features and behavior

Media Composer shares the same audio engine as Pro Tools (AAE) and both applications share the same advanced audio processing features. However, some aspects of plug-in operation are different between the two apps.
Here are some important notes regarding how Media Composer handles plug-in instances within the audio engine:
For more detailed information about how AAE handles plug-in loading and processing, see Audio Engine Behavior and Features in the Pro Tools Guide.

Debugging AAX plug-ins in Media Composer

Media Composer does not support attaching a debugger in order to debug plug-ins while they are loaded within the app. In addition, Avid does not currently provide debuggable "developer build" versions of Media Composer. You must therefore rely on logging information for debugging your plug-ins in Media Composer, or debug your plug-ins using other AAX hosts such as a Pro Tools development build or the DigiShell command-line environment.
For more information about debugging in Pro Tools and DigiShell, see Debugging AAX plug-ins in the Pro Tools Guide.
Collaboration diagram for Media Composer Guide: