Performance testing using Macro Trace

From Audacity Development Manual
Jump to: navigation, search
Macro Trace: is provided primarily for the use of Audacity Quality Assurance for performance testing and as such remains a deliberately hidden feature. Normal users though, who venture this far, are also able to use this facility.
There is a moonphase issue whereby sometimes Macro Trace will not log the timings when using a release version of Audacity.

It always seems to work on unreleased alpha and beta test builds that you can get from GitHub.

Enabling Macro Trace

To enable Macro Trace just put EnableMacroTracing=1 as the first line in your audacity.cfg file in the Audacity settings folder before launching Audacity.

There is no menu command or preferences setting to effect this. This is how this feature is kept hidden, an easter egg.

Tip Location of the Audacity settings folder (normally a "hidden" folder):
  • Windows: C:\Users\<your username>\Appdata\Roaming\audacity
  • macOS: <your username>/Library/Application Support/audacity
  • Linux: please see Audacity settings
Instead of editing audacity.cfg you can place this line at the start of your macro:

SetPreference:Name="/EnableMacroTracing" Reload="0" Value="1"

Log file

In order to get examinable output from your macro you will need to add a Save Log command to the end of your macro.

By default the Save Log command uses the log.txt file in your Audacity setings folder and note that this become lastlog.txt when you exit/close Audacity.

Tip You can, if you wish, edit the Save Log command parameters in your macro to save the log file to a custom location and name of your choice.

Clearing the log

This is an optional step but it just clears the lastlog.txt file in your Audacity settings folder before logging the times for the subsequent Macro commands and thus helps to keep the log brief and more readable, more usable.

To use this add the command Clear Log to your Macro, before the functionality performance testing lines.

Alternatively you can just delete the current lastlog.txt from your Audacity settings folder.

Run the Macro and examine the log

You can then just run the Macro on a project or files. You will need to exit the Macro and close Audacity to cause the lastlog.txt file to be written.

Macro Trace will write the time that each Macro command took to the lastlog.txt file in the Audacity settings folder.

A Simple Macro example

This example shows a simple Macro to measure the performance of Amplify versus Normalize,

run on a stereo project that is already open:

The configuration file

Enable Macro Tracing.png

The Macro

Amplify v Normalize Macro.png

The resultant timings in the lastlog.txt file

Amplify v Normalize timings.png
The Poll and Yield figures are primarily intended for use by developers.

They show the overhead Audacity has for running the operation in the UI thread, the amount of time Audacity spent processing system events, such as mouse clicks and progress bar updates.