Creating Nyquist Plug-ins
Contents
Creating Nyquist Plug-ins
Creating a plug-in for Audacity using Nyquist is as simple as creating a text file with the extension “.ny” with some Nyquist code, adding a few comments to indicate the type of plug-in, and placing the file in Audacity’s plug-ins directory. Here’s a very simple plug-in as an example:
;nyquist plug-in ;version 1 ;type process ;name "Fade In" ;action "Fading In..." (mult (ramp) s)
The first line of a Nyquist plug-in must be exactly as in the example above, and the second line must indicate a version number. Version 2 and 3 plug-ins support more widgets, but version 3 plug-ins are not supported in Audacity 1.3.3 or earlier. The next line is the type of plug-in, which is discussed below. Then comes the name of the plug-in, which is what is displayed in the menu bar, and then the “action”, which is what Audacity displays while it is busy processing the plug-in. There are other optional lines that may follow. Any line that does not begin with a semicolon (;) is assumed to contain Nyquist code and will be executed.
Audacity has support for three types of plug-ins that can be written in Nyquist:
;type generate ;type process ;type analyze
These correspond to the three menus that can contain plug-ins: Generate, Effect, and Analyze. Generate plug-ins are expected to generate new audio from scratch, Effect plug-ins (“process”) modify existing audio in-place, and Analyze plug-ins process audio but do not modify it (though they are allowed to add labels).
For Effect and Analyze plug-ins, Audacity sets up the Nyquist environment so that the audio the user has selected is in the variable s. All of the expressions in the plug-in file are executed in order, and the return value of the last expression is substituted for the selection in Audacity. If the last expression does not return audio, Audacity returns an error.
Parameter dialogs
Audacity has limited support for plug-ins showing a dialog to get parameters from the user. Here is an example of a plug-in that opens a dialog:
;nyquist plug-in
;version 1
;type process
;name "Delay..."
;action "Performing Delay Effect..."
;info "Demo effect for Nyquist by Roger Dannenberg.\nThis effect
creates a fixed number of echos." ; (should be all on one line)
;control decay "Decay amount" int "dB" 6 0 24
;control delay "Delay time" real "seconds" 0.5 0.0 5.0
;control count "Number of echos" int "times" 5 1 30
(defun delays (s decay delay count)
(if (= count 0) (cue s)
(sim (cue s)
(loud decay (at delay (delays s decay delay (- count 1)))))))
(stretch-abs 1 (delays s (- 0 decay) delay count))
If Audacity finds at least one “control” line, it will open a dialog to prompt the user for certain parameters to the plug-in. Each parameter consists of a text box and a slider, and after the user has entered each one, the final value will be stored in a Nyquist variable with a name that you specify on the “control” line. Here’s what the dialog for the Delay effect shown above looks like in Audacity for Linux:
Note that the “info” line is displayed at the top of the dialog, and that the “\n” becomes a newline. The parameters to the “control” line affect the appearance and limitations of the parameter. Each “control” line must consist of exactly the following 8 elements, in order:
- The word “control”
- The name of the control – this is the name of the Nyquist variable that will get set when the user manipulates the dialog.
- The label to the left of the control
- The type of value: either int (integer) or real.
- The label to the right of the value (usually the units like “Hz” or “dB”).
- The default/initial value of the parameter
- The minimum value of the parameter
- The maximum value of the parameter
Returning labels
Instead of returning audio, a Nyquist plug-in can instead return a list of labels. A list of labels is simply a list of time/label pairs, for example:
((0.0 "start") (30.0 "middle") (60.0 "end"))
When a plug-in returns a list of exactly this form, Audacity will create a new label track and add the labels at those positions. This style of plug-in is usually of type “analyze”.
New! Beginning with Audacity version 1.3.1, you can now optionally return both a start and an end time, like this:
((0.0 25.0 "start") (30.0 45.0 "middle") (60.0 75.0 "end"))
Note that labels are allowed to overlap in Audacity 1.3; the end time of one can be after the start time of the next.
Processing stereo tracks
Nyquist represents stereo tracks as an array of sounds (not a list). Many Nyquist functions automatically work with these arrays, but not all, so sometimes you may find it necessary to split up a stereo array, or reassemble one. Here are some useful functions:
| (arrayp s) | returns true if s is an array |
| (aref s 0) | the first element in array s – the left channel |
| (aref s 1) | the second element in array s – the right channel |
| (setf s (make-array 2)) | makes s into a new array of length 2 |
| (setf (aref s 0) left) | makes left the first element of array s |
| (setf (aref s 1) right) | makes right the second element of array s |
As a convenience, if the input to your Nyquist plug-in is stereo, but you only output a single (mono) sound, Audacity will automatically copy it to both the left and right channels.
Where to go from here
Audacity comes with some sample plug-ins that you can examine or modify as a starting point. The best way to learn Nyquist is to try it. If you’re having trouble debugging, consider downloading the standalone version of Nyquist (see the link in Part 1).
If you’re having trouble getting Nyquist to work at all, please contact us.
If you are working on Nyquist plug-in effects and would like to share them with others, or if you would like to discuss how to achieve certain effects in Nyquist, please post on the Nyquist board of the Audacity Forum or join the audacity-nyquist mailing list.
Don’t forget to consult the full Nyquist 2.37 Reference Manual for more details of Lisp and Nyquist.
