Creating Nyquist Plugins

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 plugin 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 plugin, and placing the file in Audacity's Plug-Ins directory. Here's a very simple plugin as an example:

;nyquist plug-in 
;version 4 
;type process 
;name "Fade In" 
(mult (ramp) *track*)

The first line of a Nyquist plugin 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 plugin, which is discussed below. Then comes the name of the plugin, 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 plugins that can be written in Nyquist:

;type generate 
;type process 
;type analyze 
;type tool

These correspond to the four menus that can contain plugins: Generate, Effect, Analyze and Tools. Generate plugins are expected to generate new audio from scratch, Effect plugins modify existing audio in-place, and Analyze plugins process audio but do not modify it (though they are allowed to add labels). Tools are a special type for plugins that do not fall into any of the other three types (more information in the Audacity Support site).

For Effect and Analyze plugins, 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 plugin 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 plugins showing a dialog to get parameters from the user. Here is an example of a plugin 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 plugin. Each control "widget" provides a variable (a symbol) that will store the value entered by the user. Here is what the dialog for the Delay effect shown above looks like (Windows 10):

Returning labels

Instead of returning audio, a Nyquist plugin 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 plugin 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 plugin 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* \xe2\x80\x93 the left channel
`(aref track 1)`	the second element in array *track* \xe2\x80\x93 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 plugin is stereo, but you only output a single (mono) sound, Audacity will automatically copy it to both the left and right channels.