Audacity Nyquist Prompt: Test Custom LISP Code

The Nyquist Prompt in Audacity is a built-in programming interface that allows users to write, test, and execute custom digital signal processing algorithms directly within the software. Powered by Nyquist—a sound synthesis and analysis language derived from XLISP—this tool bridges the gap between manual audio editing and automated audio programming. This article explains what the Nyquist Prompt is, how it operates inside Audacity, and how to use it to evaluate custom LISP code without packaging full plugins.

What is the Nyquist Prompt?

The Nyquist Prompt is an integrated utility located in Audacity's Tools or Effect menu (depending on the Audacity version). It acts as a live interpreter for Nyquist, an audio-centric extension of the LISP programming family developed by Roger Dannenberg.

Rather than writing external scripts, saving them as .ny plugin files, and restarting or reloading plugins in Audacity, developers and sound designers can use the prompt as a scratchpad. It accepts LISP syntax (as well as SAL, an alternative ALGOL-like syntax) to manipulate the selected audio waveform, generate new audio, or create label tracks.

How the Nyquist Prompt Interacts with Audio

When you execute code in the Nyquist Prompt, Audacity passes the currently selected audio track into the interpreter as a special variable:

• *track*: In modern versions of Audacity, *track* represents the selected audio data. For mono tracks, it is a sound object; for stereo tracks, it is an array of two sound objects.
• Evaluation: The Nyquist interpreter executes the code block from top to bottom.
• Return Values: What Audacity does with the result depends on the data type returned by your LISP expression:
  • Returning a sound object replaces the selected audio on the timeline.
  • Returning text or numbers displays a dialog box showing the output string (useful for measurements or analysis).
  • Returning a list of time-formatted data generates an Audacity label track.

Testing Custom LISP Code Step-by-Step

Testing custom LISP code inside Audacity follows a straightforward workflow:

1. Select Audio: Highlight the audio region on your timeline that you want to process. If you plan to generate sound from scratch, you can create an empty track or select a region to specify the duration.
2. Open the Prompt: Navigate to Tools > Nyquist Prompt (or Effect > Nyquist Prompt).
3. Input LISP Expressions: Write or paste your LISP code into the text field.
   • A basic volume amplification example:

     (mult *track* 0.5)

     (This multiplies the selected audio sample values by 0.5, halving its amplitude.)
   • A basic tone generation example:

     (hzosc 440)

     (This generates a standard 440 Hz sine wave for the duration of the selection.)
4. Run or Debug:
   • Click OK or Apply to execute the code and alter the project timeline.
   • Click the Debug button instead of OK to capture print statements and error traces. If your LISP code fails or encounters syntax errors, the Debug window displays the XLISP error stack, making it an essential feature for troubleshooting logic errors, mismatched parentheses, or incorrect variable bindings.

Benefits for Plugin Development

The Nyquist Prompt provides an immediate feedback loop for audio developers. Creating native C++ plugins for Audacity requires a full compilation chain, and even developing standard Nyquist plugins requires managing header metadata and file directories. The Nyquist Prompt eliminates this friction, allowing developers to prototype filters, granular synthesis routines, automated editing macros, and statistical audio analysis tools directly inside the host environment. Once the LISP code functions reliably in the prompt, it can easily be saved into a .ny file with standard plug-in headers for broader distribution.