Dplug AAX Guide

How to make AAX plug-ins with Dplug?

This write-up describes the steps required to release an AAX plug-in using Dplug.

First consider if you really want to do it. AAX is designed for established plug-in makers. If customers aren't breathing under your neck already, perhaps it won't be a fruitful move.

Step 1. Getting access to dplug-aax

You can't ever release AAX plug-ins without Avid's approval.

dplug-aax is the AAX plug-in client for Dplug. It's basically a D translation of AAXLibrary.

Since Dplug get new users that don't always contribute or even state whom they work for, you should expect a lot of scrutiny before getting access to dplug-aax. This is our only chance for Dplug to not get taken advantage of.

In order to get access to the dplug-aax package, you'll have to prove you had access to the AAX SDK and accepted its license. Send email to contact@auburnsounds.com with contact information, who will forward to Avid Developer Relations. Your email is processed manually. This process was decided with Avid.

This certainly doesn't mean Avid will allow you to release AAX plug-ins, only that you are able to access the AAX plugin client for Dplug. This agreement puts you under NDA for everything AAX related.

Step 2. Checkout

Checkout the dplug-aax repositery somewhere near your private plugins checkout.

Step 3. Modifying dub.json

Add a dplug-aax path-based dependency in your plugin's dub.json

    "dependencies":
    {
        "dplug-aax": { "path": "../dplug-aax" }
    }

Step 4. AAX Configuration

Add a configuration with a name starting with AAX in your plugin project

        {
            "name": "AAX",
            "versions": ["AAX"],
            "targetType": "dynamicLibrary",
            "lflags-osx-ldc": [ "-exported_symbols_list", "module-aax.lst", "-dead_strip" ]
        },

You can find module-aax.lst in the given example in the dplug-aax repositery.

Step 5. AAX Entry points

If you use mixin(pluginEntryPoints!MyPluginClient); you don't have anything to do.

Else, add the AAX entry points in your main source file:

    version(AAX)
    {
        import dplug.aax;
        mixin(AAXEntryPoint!MyClient);
    }

Step 6. Building with dplug-build

Build with the right configuration:

$ dplug-build -c AAX

You should be able to run the result using a Pro Tools® Developer version (at this point you need a working iLok with such a licence).

Step 7. Code Signing

AAX plug-ins must be codesigned to run in the regular Pro Tools®.

• PACE signing: once PACE grants you access to PACE Eden, you can start signing your AAX plug-ins with wraptool. wraptool should be in your PATH environment variable, so that dplug-build finds it. In EDEN v5, wrap toolcan be found in /Applications/PACEAntiPiracy/Eden/Fusion/Versions/5/bin.

  $ sudo ln -s /Applications/PACEAntiPiracy/Eden/Fusion/Versions/5/bin/wraptool /usr/local/bin/wraptool

• Update your plugin.json to use PACE-specific keys like in the included msencode example. This requires you to fill up product and "wrap configurations" in the PACE Central website. PACE Central is only accessible when cliking on a button in your iLok Licence Manager UI.

  Create the needed keys with the required information, so that dplug-build can generate code-signed AAX plug-ins. dplug-build will assist you making this file. 3 of these keys are specific to PACE, but the other 3 are also needed for making an installer.

  Put this into plugin.json:

      "iLokAccount": "enter here your iLok account",
      "iLokPassword": "enter here your iLok password, or !PROMPT",
  
      "keyFile-windows": "enter here your certificate .pfx file",
      "keyPassword-windows": "enter here your certificate private key password, or !PROMPT",
      OR
      "developerIdentity-windows": "Cloud signing. Enter here your certicate name in the Certificate Manager certmgr.msc"
      "certThumbprint-windows": "20 byte footprint that you can find in certmgr.msc",
  
      "developerIdentity-osx": "enter here your Apple Dev ID for Mac, such as \"H7DW761TY2\" (use your own)",
      "wrapConfigGUID": "enter here the desired PACE Central wrap configuration GUID"

  IT IS HIGHLY RECOMMENDED THAT YOU DON'T USE CLEAR-TEXT PASSWORDS IN PLUGIN.JSON.

• Because getting certified is long, on Windows you can create a self-signed temporary certificate with the SSL.com manager software. Don't use it for final builds.

• Important: Again, to release plugins made with dplug-aax, you must be authorized by Avid to release AAX plugins.

This step is largely outside the domain of Dplug.

Appendix A. Unsupported features

• AAX page tables
• sidechain inputs
• ambisonics
• "preview" parameter
• offline detection

Appendix B. Practical one-button debugging of AAX with VisualD

1. Generate a AAX bundle layout with dplug-build -a x86_64
2. Generate a VisualD project for 64-bit
3. Tweak the linker output to match the plugin's binary
4. Tweak the command line executable to match the absolute path of a test in AAX tools (eg: aaxval.test.load_unload.exe)
5. Tweak the command-line arguments to match the requirements for this test, typically providing a --bundle_path with proper escaping
6. To be able to see the msencode example plug-in in Protools, you need to create a stereo track.

Appendix C. More difficult: debugging in Pro Tools® with the Visual Studio debugger

A ReadMe.txt file comes with each Pro Tools developer build. It will have the latest list of known bugs and workarounds for debugging.

1. Have your iLok ready and filled with a Pro Tools® license from Avid.
2. Build the plug-in in AAX and copy it to the Protools Plug-Ins folder.
3. Eventually remove any other plugins or use a custom folder, since some have debugger checks
4. You must attach to the Protools executable, not launch it from VS. Use "Attach to process" in the Visual Studio menu.
5. (optional) Use the options "PauseDuringLaunchToAttachDebugger" in a file named "DigiOptionsFile.txt" next to the main executable

Appendix D. About preset extraction

• Important in order to extract AAX presets from binary, dplug-build should be built as a 64-bit program. Else the plug-in won't have presets.

        $ cd /path/to/Dplug/tools/dplug-build; dub -a x86_64

Supported Pro Tools® versions: 11 or superior.

You can make 32-bit AAX plug-ins for Pro Tools® 10, (with a 32-bit dplug-build for presets) however it is still untested.

FAQ

How do I install my .p12 certificate on Windows?

You don't have to in order to release AAX. Just make it available as a path from plugin.json.