AAX SDK  2.4.1
Avid Audio Extensions Development Kit

How to solve common issues.

Contents

Plug-In Fails to Load in Shipping Pro Tools

If your plug-in fails to load in shipping Pro Tools with the message "The following plug-ins failed to load because they are not valid 64 bit AAX plug-ins" then the most likely reason is that the plug-in does not have a valid digital signature.

Your AAX plug-ins will not be compatible with shipping versions of Pro Tools until they are digitally signed using tools provided by PACE Anti-Piracy, Inc. As an AAX developer you can receive these tools free of charge. Read the Digital signature section of the Pro Tools Guide to learn about the digital signing requirements for compatibility with Pro Tools.

Digital signature check failure error

To verify whether this failure is due to an invalid digital signature vs. some other library loading failure, check the Pro Tools log file. A failure caused by an invalid digital signature will result in log lines like the following:

Sys_PACE::GetDigitalSignature - looking for Eden dsig for path "/Applications/ProTools/Plug-Ins/DemoGain_example.aaxplugin/"
Sys_PACE::GetDigitalSignature - dsig error name /Applications/ProTools/Plug-Ins/DemoGain_example.aaxplugin/ 0
legacy Dsig check disabled??
Sys_PACE::GetDigitalSignature - did NOT get valid dsig /Applications/ProTools/Plug-Ins/DemoGain_example.aaxplugin/
Plug-In Binary "DemoGain_example.aaxplugin" failed to load with err = -7054.
Plug-In Binary "DemoGain_example.aaxplugin" 1.0 : Failed to load.

Another way to check whether a plug-in's digital signature is invalid is to test the plug-in in a Pro Tools developer build or with the DigiShell utility. If the plug-in successfully loads and runs in these tools but not in a shipping build of Pro Tools then it is very likely that the problem is in the plug-in's digital signature.

If you are having an issue running the signing tools then please check this list of the most common failure points:

  1. Bad command line arguments for wraptool
  2. An invalid developer certificate
  3. An expired developer certificate
  4. The Eden Tools license is not activated to your iLok USB key
  5. Your code signing certificate is not installed on your iLok USB key
  6. For Mac, the Xcode command line tools are not installed on your signing system
  7. The plug-in bundle itself is malformed and will not load
  8. The plug-in bundle is being modified at some point after being signed, thereby invalidating its digital signature

If a digital signature was successfully applied to an AAX plug-in at one point in the build process but now the plug-in fails to load due to a bad signature then the most likely reason is that someone or something has altered the signature or the contents of the .aaxplugin bundle thereby invalidating the signature. The most common reason for a digital signature to become invalidated is that something is changed within the .aaxplugin bundle when moving between different systems or when archiving/unarchiving.

Several things can cause this kind of signature invalidation. Here are some examples:

Note that the AAX digital signature covers the entire .aaxplugin bundle so any actions which affect the contents of this bundle in any way after signing will invalidate the bundle's digital signature.

If the failure is occurring on an isolated system then replacing the .aaxplugin which has an invalidated signature with an original, untampered copy (e.g. via a reinstall) should resolve this issue.

If the failure is occurring only one certain systems then try archiving and copying the failing plug-ins back to a system where the plug-in loads successfully then comparing the archived copy to a known successful copy to see if there are any differences to the file names or binary contents of the files within the bundle.

Plug-In Causes Audio Streaming Errors

See also
Real-time performance

The algorithm callback in audio plug-ins is executed within a complex real-time environment, often with tight deadlines for not only the plug-in itself but for other plug-ins participating in the same processing chain. The real-time threading model is managed outside of the plug-in and may be different across different plug-in hosts and formats. Sometimes, things go wrong and a deadline is missed.

 

  Processing thread utilization during a sporadic audio streaming error

Figure 1: Processing thread utilization during a sporadic audio streaming error

This can happen naturally when the system is loaded to capacity and the CPU simply does not have time to complete all of the work required by the plug-in algorithm routine before the processing deadline. Most ofen, however, audio processing errors occur in situations when there ought to be more than enough time to do all of the work required by the plug-in. As shown in the image above, the real-time threads can appear to have low CPU utilization and plenty of overhead, then suddenly a deadline is missed. What happened?

In most cases, audio engine errors occur when a single plug-in instance significantly overruns the processing deadline. The instance usually processes quickly in prior executions and does not give any indication of impending doom.

Call execution times for three plug-in instances in a chain

Figure 2: Call execution times for three plug-in instances in a chain

There are many reasons why this can happen. One excellent tool for evaluating these kinds of failures on macOS is the ktrace utility. This utility collects system calls, thread interactions, and backtraces similar to Instruments data in a simple command line tool. This can provide a detailed view of the state of the system leading up to an audio streaming error, and can be used to capture logs on any Mac system, even those without special developer tools installed. Once the tool is running there is a minimal performance impact. Avid provides a ktrace capture utility for use with Pro Tools that can trigger captures based on Pro Tools audio engine errors. You can download this tool from the AAX SDK downloads area.

Beginning in Pro Tools 2021.6, this dialog is presented when a plug-in significantly overruns its deadline

Figure 3: Beginning in Pro Tools 2021.6, this dialog is presented when a plug-in significantly overruns its deadline

Here are some of the culprits that Avid has found when investigating these kinds of performance issues using ktraces and similar utilities. Use these examples as a guide for the kinds of things to watch out for in your plug-ins, especially when you hear reports that your plug-ins may be triggering sporadic audio engine errors.

Collaboration diagram for Troubleshooting: