Contents
Audacity audio editor includes a version of the Nyquist programming language. With a few exceptions, Nyquist in Audacity is the same as the stand-alone Nyquist programming language. A few Nyquist functions have been intentionally omitted from Audacity’s version, either for safety, or because they cannot be supported within the Audacity framework. Audacity’s version of Nyquist also has a few additional extensions that are only applicable to running Nyquist within Audacity.
The simplest way to run Nyquist code within Audacity is to enter the code in Audacity’s Nyquist Prompt tool. When code is run in the Nyquist Prompt, the value returned by the code is sent back to Audacity, and if of a supported type, Audacity will render the result. Returning an unsupported type produces an error. The Nyquist Prompt can be very useful for running short snippets of Nyquist Code.
For running more complex Nyquist code, it is often more convenient to create a reusable Nyquist script which may be installed as a plug-in effect. This requires that the script includes special comments to tell Audacity to wrap the code with a plug-in interface. These special comments are called plug-in headers.
Nyquist supports many “data types”, including “numbers” (integer or floating-point), “characters” (such as the letter “A”, the number “4”, or any other ASCII character), “strings” (text), “list” (a list of data), “array” (special kind of indexed list), and “sounds” (a sound / digital signal).
The result of the last computation within the plug-in code (the return value) will be given back from Nyquist to Audacity. According to the data type of the returned value one of the following actions will be invoked in Audacity:
If a sound is returned, the sound will be re-inserted into the selected part of the Audacity track, (or a new track for “generate” type plug-ins). If the returned sound is shorter or longer than the original sound, the selection will be reduced or augmented. If a mono sound is returned to a stereo track, the same mono sound will be inserted into both channels of the stereo track.
Nyquist handles multi-channel sounds as an array of sounds. The first element of the array is the left channel, and the second element is the right channel. Audacity currently supports a maximum of two channels in a track (stereo).
To return a stereo sound without error, a stereo track must be selected before running the Nyquist code. Returning an array of sounds to a mono track is an error.
For more information about stereo tracks, see the Nyquist Stereo Track Tutorial.
When the return value is a character or string, a dialog window will appear with the data displayed as text.
When the return value is a number, a dialog window will appear with the number displayed as text.
(Audacity only)
If an appropriately formatted list is returned to Audacity, a label track will be created below the audio track(s).
For point labels the format is:
((number "string") (number "string") ... )
Where:
For region labels the format is:
((number number "string") (number number "string") ... )
Where the numbers are the start and end times of the region.
Audacity places returned audio or labels relative to the start of the selection, not the start of the Timeline.
(Audacity only)
Audacity treats an empty string as a no-op or “null return”. It means that the plug-in returns nothing, and no error. This is particularly useful when writing Nyquist Macros.
Any data types that are not explicitly supported return types are unsupported. When a Nyquist plug-in returns an unsupported data type, this should be considered to be an error / bug.
Unsupported return types include:
t (True) and NIL (False) produce silent errors.In Audacity, special comments are used in Nyquist plug-ins to pass information to Audacity. As with other code comments, these are ignored entirely by Nyquist, but provide instructions to tell Audacity how to create the plug-in.
Details may be found here: Nyquist Plug-in Headers
Nyquist is able to send Scripting Commands to Audacity. Note that these are exactly the same commands as are used for creating Audacity Macros and scripting with Python. A Nyquist plug-in that modifies the project using scripting commands (rather than processing in Nyquist) is called a Nyquist Macro.
Nyquist is case-insensitive (symbols are converted to upper-case internally, so for example list, List and LIST are
all identical. However, there are at least a couple of gotchas.
;; a double-quoted string
"This_is_Case_Sensitive"
;; a quoted symbol, converted internally to 'NOT_CASE_SENSITIVE
'Not_CaSe_sEnSiTiVe
For Nyquist and XLISP, the convention is to write code in lower-case.
An exception to this in Nyquist plug-ins is to use upper-case for global constants. The rationale for this is described in Audacity Issue 4438.