Nyquist Plug-in Headers
|Plug-in Headers are specially formatted code comments placed at the top of a Nyquist plug-in script.
- Plug-in Header Format
- Header Syntax
- Required plug-in headers:
- Display Headers
- Functional Headers
- Obsolete Headers
- Control Headers
Plug-in Header Format
Plug-in headers are written as:
where keyword is the header command, and args is a list of values. For most header commands there must be the correct number of arguments.
- Nyquist plug-in headers normally begin with one single semicolon at the beginning of each line.
- Headers must be all lower-case except for quoted text (for example: "name") which may include upper-case characters.
- Malformed plug-in headers are ignored (treated as normal code comments).
- Audacity 2.3.0 adds a new style of header for plug-ins that are shipped with Audacity which provides multi-language translation support.
Translated headers begin with a dollar character ("$") rather than a semi-colon. The string to be translated is double quoted, and appears between (_ and ).
|Multi-language support for a plug-in's GUI is available only to plug-ins that are shipped with Audacity, as the translations must be compiled into Audacity's language files.
See also: Plug-in Translations.
$name (_ "Name of Effect")
All plug-in headers have the syntax:, where args are the parameters ("arguments") for the header command.
|Required plug-in headers:|
|These headers are required in all Nyquist plug-ins.|
|;nyquist plug-in||Defines the text file as a Nyquist plug-in.|
|;name "name"||Sets the name of the plug-in.|
|;type "type"||Specifies the type of plug-in.|
|;version version||Specifies the Nyquist plug-in version.|
|Display additional information about the plug-in. These headers are optional.|
|;action "text"||Description shown in progress window.|
|;author "text"||Name of plug-in developer. Shown in the "About" section of . Also used when effects are sorted by "Publisher".|
|;copyright "text"||Copyright / license notice. Shown in the "About" section of .|
|;release version||Version / release number of the plug-in. Shown in the "About" section of .|
|These headers may be used to provide additional functionality.|
|;codetype type||Specifies if the Nyquist code uses SAL or LISP syntax.|
|;debugbutton option||Specifies if the Debug button is visible.|
|;debugflags flags||Sets the debug message behavior.|
|;helpfile "path to file"||Displays abutton that links to a plug-in Help file.|
|;manpage "URL"||Displays a Audacity manual.button that links to the plug-in Help page in the|
|;maxlen integer||Sets the maximum number of samples to be processed.|
|;mergeclips integer||Specifies the clip merge behavior.|
|;preview option||Specifies the plug-inoptions.|
|;restoresplits integer||Specifies the clip split behavior.|
|These headers are no longer used by current versions of Audacity and are ignored.|
|These headers define the plug-in GUI.|
|;control <args>||The parameters (<args>) specify the type of widget and the widget's required arguments. See also: Nyquist Plug-ins Widgets|
Required plug-in headers
Tells Audacity "this is a Nyquist plug-in". This should normally be the first line as it defines the contents of the file.
Name of the plug-in as it will appear in the Audacity menu:
Note that for plug-ins to be used in Chains, the colon character ":" cannot be used (as it is a special character in the Chain text file).
If the plug-in has an interface, the name should end with three dots so as to indicate that additional user action is required before the plug-in is applied. Plug-ins that act immediately without additional user action should not have dots at the end of the name.
- A plug-in cannot appear in several Audacity menus at the same time, but it is possible to write several plug-ins with the same name and different ";type" lines. Each plug-in will then appear in the appropriate menu. Using the same name for more than one plug-in is not recommended and should generally be avoided.
|Type header||Features||Typical Role|
|;type analyze||Plug-in appears in the Audacitymenu.||
|;type generate||Plug-in appears in the Audacitymenu.||
|;type process||Plug-in appears in the Audacitymenu.||
|;type tool||Plug-in appears in the Audacitymenu.||
Tool type plug-ins are typically Nyquist Macros or plug-ins that don't fit well in any of the first three roles. They may also be combined with one of the other types:
|;type tool analyze||Appears in the Audacitymenu and behaves like an Analyze type.|
|;type tool generate||Appears in the Audacitymenu and behaves like a Generate type.|
|;type tool process||Appears in the Audacitymenu and behaves like a Process type.|
- All new plug-ins should use the most recent version number so that all current features are available. The version line is required to allow Audacity to run the plug-in correctly and prevents plug-ins with new features from being loaded in an old Audacity program that is missing required features.
|;version 1||Slider Widget|
|;version 2||Text input widget added|
|;version 3||multiple-Choice widget added|
Text to be displayed while the plug-in is working. The text string must be quoted.
Name of the plug-in Author. If this line is added, its text will appear in the Audacity Effect Menu when sorted or grouped by "Publisher". The author name string must be quoted.
;author "Name of Plug-in Author(s)"
A short statement of the copyright/license terms. For plug-ins shipped with Audacity, this must be compatible with Audacity's GPL v2 license. The copyright string must be quoted.
Recommended text for GPL v2 license:
- ;copyright "Released under terms of the GNU General Public License version 2"
Additional copyright details may be included in the plug-in code comments, but must not conflict with the terms declared in the copyright header.
;copyright "copyright text"
Displays a release version number for the plug-in in the Manage > About menu.
Plug-ins that are shipped with Audacity have a release version number equivalent to the Audacity version at the time that the plug-in was last updated.
Plug-in authors may choose whichever versioning scheme they prefer, but should ensure that later versions of the plug-in always have a later version number. If the version number has spaces, it must be enclosed in double quotes.
Any one of the following are valid (though there should be only ONE release header in a plug-in):
Declaration of code syntax. May be either lisp or sal (lower case).
- For LISP syntax plug-ins this is usually omitted, but it should always be included for SAL syntax plug-ins.
- If the code type is not declared in the Nyquist Prompt effect, Audacity attempts to deduce the correct syntax from the code.
- The code type can only be Lisp syntax or SAL. It cannot be a mix of both.
Show or hide thebutton. The default is to show the button, but for plug-ins that are shipped with Audacity, or other plug-ins that are believed to be bug free, the button may be hidden by setting this to "false" or "disabled"
|;debugflags trace|| Sets *tracenable* (LISP) or *sal-traceback* (SAL) and displays debug window if there is anything to show.
This may be useful when showing debug info is integral to what the plug-in does, or when debugging a script.
|;debugflags notrace|| Disables *tracenable* (LISP) / *sal-traceback* (SAL). This prevents the debug window from opening on error, unless the button has been pressed.
If the log. Note that disabling *tracenable* limits the debug output to only the error message with little or no additional debugging information.button has not been pressed and there is an error, the error message will be sent to Audacity's
|;debugflags compiler|| Set *sal-compiler-debug* to 'true'.
Output from the SAL compiler is printed to the debug output. This may be viewed in the Debug window if enabled (for example, by clicking the Debug button), otherwise in the Audacity log.
|;debugflags nocompiler|| Set *sal-compiler-debug* to 'false'.
Disables compiler messages from SAL. Only debug and error messages are printed to the debug output.
- debugbutton true, debugflags trace: Debug window opens if debug button pressed or if Nyquist printed to the debug window.
- debugbutton false, debugflags trace: Debug button disabled, but debug window opens if Nyquist printed to the debug window.
- debugbutton true, debugflags notrace: Debug window opens only when Debug button is pressed. If Debug button has NOT been pressed, any error messages that arise are routed to the Audacity log.
- debugflags compiler, debugflags trace: (When using SAL syntax) The Debug window always opens to display the output from the SAL compiler.
- debugflags compiler, debugflags notrace: (When using SAL syntax) The Debug window only opens to display the output from the SAL compiler if Debug button is clicked, otherwise it is printed to the Audacity log.
- debugflags nocompiler, debugflags trace: (When using SAL syntax) The Debug window always opens to display debug and/or error messages. Output from the SAL compiler is suppressed.
;helpfile path to file
The file path is relative to the plug-in search path. Normally the help file would be placed in the same location as the plug-in when it is installed. To support HTML files with images and/or media, the help file and its resources may be in a folder, and the folder included in the file path. For example, if the help file is called "my_effect.html" and it includes images, then the html file and images may be placed in a folder called "my_effect_help", and the helpfile header would be:
This is primarily intended for use by plug-ins that are shipped with Audacity. It is similar to the #helpfile helpfile header, except that it looks for the help file in the search path for Audacity's manual. For more information, see Location of Manual
Specifies the maximum number of samples to be processed in "process" or "analyze" type plug-ins. This can help the progress bar if length that will be processed is determined by the plug-in rather than by the length of selection. It could also be used as a fail-safe for plug-ins that are specifically designed for short selections. This example limits the number of samples to 1 million:
When the MAXLEN header is used, the Nyquist global variable LEN is the maximum of "length of selection in samples" and "value set by MAXLEN".
Allows Nyquist plug-ins to override Audacity's default "clip merge" behaviour. By default, when effects (including generator effects) are applied across one or more clip boundaries and the returned audio is a different length from the original selection, Audacity will add "split lines" at the ends of the returned audio. In all other cases, the returned audio is "merged" into the current audio.
This option only applies when the plug-in is applied across clip boundaries (including across "split lines").
- -1 Automatic clip merge behaviour (default)
- 0 Don't merge clips. Effects that are applied across clip boundaries will not be merged into the existing audio (there will be split lines at the ends of the returned audio) whether the returned audio is the same length as the original selection or not.
- 1 Always merge clips. The returned audio will always be merged into the existing audio (no split lines added).
;mergeclips 1See also "restoresplits".
Provides options for previewing the effect. Multiple preview options may be defined to achieve the desired behaviour.
- enabled (default). Preview is enabled.
- true Same as "enabled".
- disabled Preview is disabled. If Audacity is unable to provide a meaningful preview, then preview should be disabled. This may be required for effects that affect specific time regions within the selection.
- false Same as "disabled".
- linear Provides an optimisation for previewing multiple tracks by mixing the selected tracks before applying the Nyquist code. This optimisation is disabled by default.
- selection When previewing, the Nyquist code is applied to the entire selection (not just the length that will be previewed). Audacity's "Preview" then plays the first few seconds of the processed audio. This may be required for effects that vary over the duration of the selection.
Allows Nyquist plug-ins to override Audacity's default "split restore" behaviour. By default, when effects (including generator effects) are applied across one or more clip boundaries, Audacity will restore "split lines" at the position of the original clip boundaries.
This option only applies when the plug-in is applied across clip boundaries (including across "split lines").
- 1 Splits at clip boundaries are restored (default)
- 0 Splits at clip boundaries are not restored (clips are joined).
Note: Nyquist plug-ins are not currently able to distinguish between silence and "empty space" within the selection, so gaps between audio clips will be treated as if the empty space is an additional "silent" audio clip.
See also "mergeclips".
Obsolete plug-in headers
|These headers are obsolete and no longer used by Audacity. They should not be used in new plug-ins.
They may still be found in some old plug-ins, but are now treated by Audacity as ordinary "comments" and simply disregarded.
Description shown in progress window.
Specifies an LV2 category for the plug-in.
A single line of text to be displayed at the top border of the plug-in window. For multiple lines of text, a two-character sequence "\n" may be used within "text" to create a line break.
- Each valid "Control" header adds a widget to the GUI.
- If there are no "Control" headers, Audacity will attempt to run the effect without a GUI.
There can be several "control" lines in the plug-in header. Add one for each widget to appear in the dialog box. The ;control headers should normally be the final headers as they define variables used by the Nyquist code.
|Nyquist plug-in widgets are documented on the "Nyquist Plug-ins Widgets" page.|