Creating Nyquist Plug-ins
Contents
Creating Nyquist Plug-ins
|
Do not attempt to use Windows NotePad or wordpad or any word processor for writing or editing Nyquist code. For Windows, Notepad++ is a good, free, plain text editor. |
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 4 ;type process ;name "Fade In" (mult (ramp) *track*)
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 4 is the current version and should be used for all new code. 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. There are other optional lines that may follow. Any line that does not begin with a semicolon (;) or a dollar sign ($) are assumed to contain Nyquist code and will be executed.
Audacity has support for four types of plug-ins that can be written in Nyquist:
;type generate ;type process ;type analyze ;type tool
These correspond to the four menus that can contain plug-ins: Generate, Effect, Analyze and Tools. 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). Tools are a special type for plug-ins that do not fall into any of the other three types (more information in the Audacity wiki).
For Effect and Analyze plug-ins, Audacity sets up the Nyquist environment so that the audio the user has selected is in the variable *track* (in Nyquist before version 4, the variable S was used). 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 4
;type process
;name "Delay..."
;control decay "Decay amount" int "dB" 6 0 24
;control delay "Delay time" float "seconds" 0.5 0.0 5.0
;control count "Number of echos" int "times" 5 1 30
(defun delays (sig decay delay count)
(if (= count 0)
(cue sig)
(sim (cue sig)
(loud decay (at delay (delays sig decay delay (- count 1)))))))
(stretch-abs 1 (delays *track* (- 0 decay) delay count))
If Audacity finds at least one correctly formed “control” line, it will open a dialog to prompt the user for certain parameters to the plug-in. Each control "widget" provides a variable (a symbol) that will store the value entered by the user. Here’s what the dialog for the Delay effect shown above looks like (Windows 10):
Additional information about available widgets may be found in the Audacity wiki.
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:
(list (list 0.0 "start")
(list 30.0 "middle")
(list 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. The time value is in seconds. This style of plug-in is usually of type “analyze”.
To create region labels there needs to be two time values:
(list (list 0.0 25.0 "start")
(list 30.0 45.0 "middle")
(list 60.0 75.0 "end"))
Note that labels are allowed to overlap; 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 *track*) | returns true if *track* is an array |
| (aref *track* 0) | the first element in array *track* – the left channel |
| (aref *track* 1) | the second element in array *track* – the right channel |
| (setf my-array (make-array 2)) | makes my-array into a new array of length 2 |
| (setf (aref my-array 0) left) | makes left the first element of array my-array |
| (setf (aref my-array 1) right) | makes right the second element of array my-array |
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. Technical support is provided on the Nyquist board of the Audacity Forum (email registration required for posting).
Don’t forget to consult the documentation for more details of Lisp and Nyquist.
