Nyquist Plug-ins Reference

This page offers a detailed look at the structure and syntax of Nyquist Plug-ins. It is intended for people who wish to write their own plug-ins. If you are looking for extra Nyquist plug-ins to use, see Nyquist Plug-ins.

Related article(s): Digital Audio Technology Nyquist Audio Programming - "How to" and other explanatory articles Nyquist 3.02 Reference Manual - the latest Nyquist Manual (mostly using SAL syntax) Nyquist 2.37 Reference Manual - the latest version entirely using LISP syntax Please note: Nyquist supports both a LISP syntax and a more conventional syntax called SAL. You can choose a manual from a link above based on which syntax you are using. SAL only works in Audacity 1.3.8 or later.

If you are especially interested in Nyquist in Audacity, we highly recommend subscribing to our Audacity forum, which has a section specifically for matters relating to Nyquist.

The Audacity Nyquist Interface is implemented in the following files in the Audacity source code:

• audacity/src/effects/nyquist/Nyquist.cpp

• audacity/lib-src/libnyquist/nyx.c

Overview

Nyquist plug-ins are simple text files ending with the filename extension ".ny". When Audacity starts, it looks in a plug-ins directory for files and automatically adds the effects it finds there to the Audacity menus. The plug-ins can be written in either LISP or SAL syntax. When the user selects the plug-in from the menu, Audacity causes the Nyquist language runtime system (built into Audacity) to run the plug-in code to process or generate audio. You can also compute strings to display to the user or compute labels to be shown on a new label track.

Before running the plug-in, Audacity parses some of the plug-in text looking for specially formatted comments that describe "widgets" -- controls that the user can use to set parameters for the effect. For example, your plug-in can display a slider to control volume or filter frequency. Values from the widgets are passed through global variables to the plug-in.

For a full description of the plug-in language, read the Nyquist Reference Manual. There are, however, some details of how plug-in code is processed that is unique to Audacity plug-ins and therefore not covered in the Nyquist manual. The main thing to know is that the variable *TRACK* in version 4 or later syntax (S in earlier versions) is the selected sound. This is probably the main input to your effect. The second thing to know is how sound is returned from Nyquist to Audacity.

SAL syntax is inherently command oriented. A SAL plug-in should consist of a sequence of SAL commands including define commands to define variables and functions. There must be a function definition for main. After performing the commands in sequence, Audacity calls main (with no parameters). The value returned from main is the result of the plug-in (normally this should be a sound).

One exception to this is the Nyquist Prompt... effect. Since defining main just to evaluate and return a simple expression is so awkward, you can simply type

 return expression

Normally, this is not a legal statement as a top-level command in SAL, but in Nyquist Prompt..., special processing embeds the return statement into a declaration of function main, which is then called. This trick also works for regular plug-ins, but defining main is the preferred style.

For LISP syntax plug-ins, Lisp expressions are read and evaluated one-at-a-time. The value returned by the last expression is the result of the plug-in. The same semantics applies to the Nyquist Prompt... effect. There is only one "Nyquist Prompt" for both SAL and LISP syntax. Audacity looks for the first non-space character that is not part of a comment. If it is an open paren "(", then the code is assumed to be LISP; otherwise, SAL is assumed.

The "Nyquist Prompt" effect is not equivalent to plug-ins because Audacity processes the plug-in header information from plug-in files, but the "Nyquist Prompt" effect ignores them (they are just comments).

Nyquist is a superset of the XLISP programming language and as such is limited to single-byte ASCII characters. The results of using characters outside the range of ASCII 32 to 126 in Nyquist plug-ins are unspecified. While the use of characters outside of this range may work satisfactorily for personal use on some operating systems, plug-ins for public distribution must currently be written using only standard characters (ASCII characters 32 to 126). This applies to plug-in code, comments and string data.

Nyquist Plug-in Header

Important: In the Nyquist plug-in header there must be only one single semicolon at the beginning of each line because these lines are parsed by Audacity.

The Nyquist Lisp interpreter as well as the Nyquist SAL compiler in contrast recognize everything after the first semicolon up to the end of the line as a comment and just simply ignores it. So in the Nyquist code, below the plug-in header, comments can also be started with several semicolons in a row.

 ;nyquist plug-in
 ;version version
 ;type type
 ;name "name"
 ;action "text"
 ;preview option
 ;categories "text"
 ;author "text"
 ;copyright "text"
 ;info "text"
 ;control parameters
 ;codetype type
 ;debugflags flags

The "preview", "categories", "author", "copyright", "info", "control", "codetype", and "debugflags" lines are optional for operation of Audacity and can be omitted.

Required plug-in header lines

nyquist plug-in

Tells Audacity "this is a Nyquist plug-in":

 ;nyquist plug-in

version 1

Only the Slider widget is supported:

 ;version 1

version 2

The Text input widget was added in Audacity 1.2:

 ;version 2

version 3

The multiple-Choice widget was added in Audacity 1.3:

 ;version 3

version 4

• Additional global variables were added in Audacity 2.0.7 to pass additional information from Audacity to Nyquist.
• New optional plug-in headers: ;author and ;copyright were added in Audacity 2.0.7 but are also valid in plug-in versions 1 to 3.

 ;version 4

Use only one ";version" line. New plug-ins should generally use the version with the highest 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 brand-new features from being loaded in an old Audacity program that is missing required features.

type generate

Plug-in appears in the Audacity Generate menu:

 ;type generate

type process

Plug-in appears in the Audacity Effect menu:

 ;type process

type analyze

Plug-in appears in the Audacity Analyze menu:

 ;type analyze

Only one ";type" line is needed. 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 but with different ";type" lines, which then will appear under the same name in different Audacity menus. But please do this only if you really need it.

name

Name of the plug-in as it will appear in the Audacity menu:

 ;name "name"

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).

action

Text to be displayed while the plug-in is working:

 ;action "text"

Optional plug-in header lines

author

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".

 ;author

categories

LV2 categories, see Categories below.

 ;categories "text"

Categories

LV2 categories were introduced in Audacity 1.3.6 as part of "Google Summer of Code 2008".

Categories were unpopular with the majority of users because of the extra navigation involved to reach the effects, and were withdrawn in from 1.3.7 onwards. Categories will not be re-introduced until it is provided with a way by which the user can turn the grouping on and off in the interface.

So, the "categories" header line is currently optional.

codetype lisp

The syntax of the plug-in is Lisp. This is the default if the "codetype" line is missing:

 ;codetype lisp

codetype sal

The syntax of the plug-in is SAL. The default is "lisp".

 ;codetype sal

control

Define a plug-in widget. There can be several "control" lines in the plug-in header. Add one for each widget to appear in the dialog box -- see Nyquist Plug-in Widgets below:

 ;control parameters

copyright

A short statement of the copyright/license terms. For plug-ins shipped with Audacity, this must be compatible with Audacity's GPL v2 license. 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 here.

 ;copyright

debugflags

See Internal Debug Options below:

 ;debugflags flags

Internal Debug Options

There is an optional "debugflags" line available, which skips the plug-in window and directly executes the plug-in code, so if a "debugflags" line is found in the plug-in header no user-interaction is possible.

Set *tracenable* to true. The plug-in behaves as if the "Debug" button was clicked by the user. This is the default:

 ;debugflags trace

Set *tracenable* to 'false'. The plug-in behaves as if the 'OK' button was clicked by the user:

 ;debugflags notrace
 	

Set *sal-compiler-debug* to true. This prints the compiler's translation of SAL to LISP before evaluating the translated code:

 ;debugflags compiler

Set *sal-compiler-debug* to 'false'. This is the default.

 ;debugflags nocompiler

In the Nyquist Workbench, the "compiler" and "nocompiler" debugflags control whether the generated Lisp code from the SAL compiler will be sent to "stdout" or to the output window in the Nyquist Workbench.

info

Text to be displayed at the top border of the plug-in window:

 ;info "text"

A two-character sequence "\n" within "text" causes a line break. It is not possible to "quote" a line break in the plug-in code with a backslash '\' at the end of the line. In the plug-in header, the text in the "action" and "info" lines must be written in one single line.

preview

Process type plug-ins may be given a preview button by including this header:

 ;preview enabled

An alternative (functionally identical) version of this header is:

 ;preview true

This should only be used in plug-ins where the preview will accurately match the effect that will be produced by applying the effect.

Preview may be used in process or generate type effects. Note that Preview applies the plug-in code to a mix of the selected tracks and not to the tracks individually.

Nyquist Plug-in Widgets

Every ";control" line gets parsed by Audacity into several tokens, where each token is separated by one or several whitespaces:

Syntax for ;control lines

;control	var-name	text-left	widget-type	text-right	initial-value	minimum	maximum
;control	symbol	string	int	string	integer	integer	integer
;control	symbol	string	real	string	float	float	float
;control	symbol	string	string	string	string	-	-
;control	symbol	string	choice	string	integer	-	-

Italic words in the table denote data types. Because tokens are separated by whitepace, strings containing whitespace must be written within quotation marks. Do not try to memorize this table, use it as a reference. The detailed syntax for each widget type is described in the following sections.

Slider Widget

Slider widgets are supported in all Audacity Nyquist plug-in versions.

 ;control variable-name "text-left" variable-type "text-right" initial-value minimum maximum

• variable-name - a Lisp symbol.
• text-left - text that will appear to the left of the slider.
• variable-type - a "number" type, either int or real:
  • int - integer [FIXNUM, an XLISP number without a dot]
  • real - floating point [FLONUM, an XLISP number with a dot]
• text-right - text that will appear to the right of the slider.
• initial-value - variable value [and slider position] at the first start of the plug-in.
• minimum - numerical variable value when the slider is moved to the left border.
• maximum - numerical variable value when the slider is moved to the right border.

The variable value [the slider position] can be referenced by the variable name in the plug-in code.

A text input box to the left of the slider allows the user to type in a value via the keyboard. Note that typed input is validated only against the data type (integer or floating point) and it is up to the plug-in programmer to catch values typed in by the user that are outside of the slider range.

Text Input Widget

The text input widget is supported in plug-ins version 2 or above.

 ;control variable-name "text-left" string "text-right" "initial-string"

• variable-name - a Lisp symbol.

• text-left - text that will appear to the left of the text input field.

• text-right - text that will appear to the right of the text input field.

• initial-string - the string will appear inside the text field.

The text typed in by the user in the text field of the plug-in window can be referred as a string variable from within the plug-in code. All string characters are valid, though care must be taken with escape characters if the string is to be evaluated.

Examples how to use the text input widget can be found in the source code of the Apropos Plug-in.

Multiple-Choice Widget

The multiple choice input widget is supported in plug-ins version 3 or above.

 ;control variable-name "text-left" choice "string-1,string-2,..." initial-value

• variable-name - a Lisp symbol.

• text-left - text that will appear to the left of the multiple-choice list.

• string-1,... - for every string an entry in a list to choose from will be produced.

• initial-value - the number of the list entry that will be displayed as the default choice at the first start of the plug-in.

The list entries string-1, string-2, etc. are internally represented by integer numbers. The first, top-most list entry string-1 will be represented by the number 0. The list entry chosen by the user can be determined by the integer value of the variable from within the plug-in code.

Examples how to use the 'choice' widget can be found in the source code of the Apropos Plug-in.

Nyquist Variables

The variables given from Audacity to Nyquist are defined in the file "audacity/lib-src/libnyquist/nyx/nyx.c" in the Audacity source code.

The following variables are given from Audacity to Nyquist:

• *TRACK* (version 4) - the Audacity sound [the selected part of the Audacity audio track]. The *TRACK* variable also has a list of "properties" that pass additional information to Nyquist.

• *SYSTEM-DIR* (version 4) - A variable with a list of properties relating to the file system.

• *PROJECT* (version 4) - A variable with a list of properties relating to the current Audacity project.

• *SELECTION* (version 4) - A variable with a list of properties relating to the current selection.

• *SCRATCH* - a symbol whose value and property list are preserved from one effect invocation to the next.

• S (version 1, 2, 3) - In process and analyze type plug-ins this is the Audacity sound [the selected part of the Audacity audio track]. In generate type plug-ins "S" is the Adagio notation for a quarter note (float value 0.25).
• S (version 4) - Adagio notation. A quarter note (float value 0.25).

• LEN - the number of samples contained in the Audacity sound.

• *SOUND-SRATE* - the sample frequency of the Audacity track.

• *CONTROL-SRATE* - the sample frequency of the control signals (such as those created by piecewise approximations. By default 1/20 of the sample rate of the track.

• *WARP* - information that communicates start-time and duration to Nyquist functions. In Audacity, the start-time is always considered to be zero (regardless of the actual start time of the selection) and the duration indicates the duration of the selection. *warp* should not normally be accessed directly.

• *FILE-SEPARATOR* - The character that separates directories in a path, e.g. "/" for Unix, ":" for Mac, and "\" for Win32.

Other global variables provided by Nyquist can be found in the Nyquist manual.

For process and analyze type plug-ins, the length of the sound in seconds can be computed one of the following ways:

 (/ len *sound-srate*) ; in LISP
 (get-duration 1) ; in LISP

 len / *sound-srate* ; in SAL
 get-duration(1) ; in SAL

NOTE:

get-duration answers the question: "If a behavior has a nominal duration of 1, how long will it be after warping it according to the Nyquist environment?" Since many built-in behaviors like OSC and LFO have nominal durations of 1, In process effects, Audacity sets up the environment (including *warp*) to stretch them by the selection's duration. Otherwise, if you wrote (OSC C4), the result would have a duration of one second instead of the duration of the selection.

In 'generate' effects, this does not happen, so the length specified by the effect is the length that is produced. For example, if you write (OSC C4 3.5), a generate type effect will produce a tone of duration 3.5 seconds.

For generate type plug-ins, the length of the selection (if there is a selection) is usually ignored by Nyquist. However, if for some reason the length of the selection needs to be known, then *SELECTION* START and END properties may be used (version 4 plug-ins or later).

Variables and Property Lists

In general terms, a variable is a symbol which contains a value. The symbol can be any valid name, and its value may be changed (hence "variable"). In Nyquist, the value may be of any data type (for example, a number, a character, or even a sound) and may be changed from one data type to another. Unlike some programming languages, variables do not need to be declared before use - they can just be set, and then they exist.

Setting the value of a symbol "binds" the value to the symbol. A symbol that has no value (not even "nil") is said to be "unbound".

In addition to the value of a symbol, we can also attach properties. This is a way of associating a list of items, each with their own value, to a single variable. Each item is called a key or indicator, and we can give each key a value. This list of items is called a "property list" (or plist for short).

To get the value of a property, we use the GET command.

When getting the value of a property, we do NOT want to evaluate either the variable (symbol) or the key symbol, so we must "quote" both symbols to prevent evaluation.

 (GET 'varaiable-name 'property-name) ; Lisp syntax

 set v = get(quote(varaiable-name ), quote(property-name)) ; SAL syntax

As an example, if we have a variable called *TRACK* (which we do in version 4 plug-ins), and it has a property called NAME (which it does), then we can "get" the value of that property with:

 (GET '*TRACK* 'NAME) ; Lisp

 return get(quote(*TRACK*), quote(NAME)) ; SAL

Version 4 Property Lists

In version 4 plug-ins, property lists are defined for the global variables *TRACK*, *SELECTION*, *PROJECT* and *SYSTEM-DIR*. Version 4 plug-ins require Audacity 2.0.7 or later.

*TRACK*

Value: The sound from a selected mono audio track, or an array of two sounds from a selected stereo track (see Stereo Tracks below).

Properties of *TRACK* all relate to the track that is being processed. Currently Nyquist only processes audio tracks. When multiple tracks are selected, Nyquist processes each audio track in turn (top to bottom).

• INDEX : [Integer] A counter that increments for each track processed. On processing the first track, the value is "1".
• NAME : [String] The name of the track.
• TYPE : [String] The type of track. One of: "wave", "midi", "label", "time". Currently only "wave" (audio tracks) are processed by Nyquist plug-ins.
• VIEW : [String] The track view. Only applies to audio tracks. One of: "Waveform", "Waveform (dB)", "Spectrogram", "Spectrogram (log f)", "Pitch (EAC)".
• CHANNELS : [Integer] The number of channels in the track (mono = 1, stereo = 2).
• START-TIME : [Float] The track start time (note that this will often be different from the selection start time.)
• END-TIME : [Float] The track end time.
• GAIN : [Float] The value of the track Gain slider.
• PAN : [Float] The value of the track Pan slider.
• RATE : [Float] The track sample rate.
• FORMAT : [Integer or Float] The track sample format. One of (Integer) 16, (Integer) 24, or (float) 32.
• CLIPS : [List or Array] For mono tracks, a list of "clips", where each clip is a list containing the start and end time of the clip. For stereo tracks, an array containing a list of clips for each channel.

 ;;Example of *TRACK* CLIP data for a mono track [Lisp]
 (setf track-clips (get '*track* 'clips))
 (print (first track-clips)) ; prints the first clip as (list start-time end-time)

 ;;Example of *TRACK* CLIP data for a stereo track [Lisp]
 (setf track-clips (get '*track* 'clips))
 (setf left-channel (aref track-clips 0)) ; the list of clips in the left channel
 (print (first left-channel)) ; prints the first clip in the left channel as (list start-time end-time)

*SELECTION*

Value: Unbound.

• START : [float] The start of the selection in seconds.
• END : [float] The end of the selection in seconds.
• TRACKS : [integer list] A list of track numbers of selected audio tracks.
• CHANNELS : [integer] The number of selected audio channels.
• LOW-HZ : [float] The low frequency selection Hz (Spectrogram or Spectrogram (log f) track view).
• CENTER-HZ : [float] The centre frequency selection in Hz (Spectrogram or Spectrogram (log f) track view).
• HIGH-HZ : [float] The high frequency selection Hz (Spectrogram or Spectrogram (log f) track view).
• BANDWIDTH : [float] The bandwidth of the frequency selection in octaves (Spectrogram or Spectrogram (log f) track view).
• PEAK-LEVEL : [float] The absolute peak level (linear scale).

*PROJECT*

Value: Unbound.

• RATE : [integer] The project rate in the project.
• TRACKS : [integer] The number of tracks in the project.
• WAVETRACKS : [integer] The number of audio tracks in the project.
• LABELTRACKS : [integer] The number of label tracks in the project.
• MIDITRACKS : [integer] The number of note tracks in the project.
• TIMETRACKS : [integer] The number of time tracks in the project.

*SYSTEM-DIR*

Value: Unbound.

• BASE : [string] The Audacity installation directory.
• DATA : [string] The Audacity data directory. This is where the audacity.cfg, plug-inregistry.cfg and EQCurves.xml files are located.
• HELP : [string] The installation directory for the Audacity Manual (note that the Manual may not exist).
• TEMP : [string] The Audacity temp directory. This is where unsaved project data is temporarily stored.
• PLUG-IN : [string list] A list of directories where Audacity looks for Nyquist plug-ins.

The *SCRATCH* Symbol

(version 3 or above - Audacity 1.3.9 or later)

*SCRATCH* is a global symbol, which is not deleted in-between plug-in runs.

It provides a way for information to survive from one invocation of a plug-in to the next. However, you should not rely on the "value" of *SCRATCH* beyond a single invocation of a plug-in as it could be overwritten by another plug-in. It is better to use property lists of *SCRATCH*. That way, you get a whole name space rather than a single variable name, and with careful naming of the property keys, name collisions can be avoided.

To pass data from plug-in "effectX-partA" to "effectX-partB":

1. Assign a property name based on the effect name, e.g.: 'EFFECTX [or in SAL, which does not support the single-quote notation of LISP, write QUOTE(EFFECTX). ]

2. "effectX-partA" should delete any old property value:

 exec remprop(quote(*SCRATCH*), quote(effectx)) ;; in SAL

 (remprop '*SCRATCH* 'effectx) ;; in LISP

3. "effectX-partA" should compute a new property value v and save it:

 exec putprop(quote(*SCRATCH*), v, quote(effectx)) ;; in SAL

 (putprop '*SCRATCH* v 'effectx) ;; in LISP

4. "effectX-partB" should access the property using:

 set v = get(quote(*SCRATCH*), quote(effectx)) ;; in SAL

 (get '*SCRATCH* 'effectx) ;; in LISP

5. When "effectX-partB" finishes, it should remove the property:

 exec remprop(quote(*SCRATCH*), quote(effectx)) ;; in SAL

 (remprop '*SCRATCH* 'effectx) ;; in LISP

But there may be cases where you do some analysis and want to use the analysis data multiple times. You might even have multiple analysis plug-ins operating on different inputs to collect data to feed into a plug-in with multiple inputs. In this case, which might be quite common, you should not call REMPROP(), but this has the problem of leaving data on the *SCRATCH* property list indefinitely.

In cases where *SCRATCH* data is not deleted immediately after use, and where there is the potential to leave large amounts of memory there, there should be another effect, e.g. "effectX-partCleanup", that simply calls:

 exec remprop(quote(*SCRATCH*), quote(effectx)) ;; in SAL

 (remprop '*SCRATCH* 'effectx) ;; in LISP

allowing the user to explicitly free up any data stored on the 'EFFECTX property. It would be reasonable to omit the "effectX-partCleanup" effect if the data stored on the property list has a maximum size of, say, 10KB. The problem we want to avoid is properties with unbounded size getting left in the heap until Audacity is restarted.

Stereo Tracks

If a sound from an Audacity stereo track was given to Nyquist, the s variable contains an array of sounds. Because all Nyquist "snd-..." low-level functions only can process mono signals, to use such a function, the s array first must be split into single mono signals and afterwards be re-combined into an array before it is given back to Audacity.

In Sal, one could write:

 if arrayp(s) then
   return vector(snd-function(s[0]), snd-function(s[1]))
 else
   return snd-function(s)

Or in LISP, one could write:

 (if (arrayp s)
     (vector
       (snd-function (aref s 0))   ; left stereo channel
       (snd-function (aref s 1)))  ; right stereo channel
     (snd-function s))             ; mono signal

• (arrayp s) - tests if 's' is an array

• (vector ... ) - re-combines the two mono signals into a stereo signal. A "vector" is an one-dimensional array

• (aref s 0) - the left stereo channel [the 0-th slot of the array]

• (aref s 1 - the right stereo channel [the 1-st slot of the array]

Important: The Nyquist interface within Audacity can handle a maximum of two channels simultaneously [Audacity stereo tracks]. If in Audacity more than one audio track were selected, each of the selected tracks will be given sequentially, one after the other, with a maximum of two channels simultaneously [stereo] to Nyquist for processing. It is not possible with Nyquist in Audacity e.g. to copy audio signals from one Audacity track into another track [Audacity 1.3.9, November 2009].

multichan-expand

In the "nyquist.lsp" file in the Audacity "nyquist" sub-directory there is a function "multichan-expand" defined that simplifies the handling of multi-channel sounds [e.g. stereo tracks]:

 (multichan-expand function &rest arguments)

So the "arrayp" constuct from above can also be written:

 return multichan-expand(quote(snd-function), s) ;; in SAL

 (multichan-expand #'snd-function s) ;; in LISP

This looks a bit more cryptic and reads less intelligibly [to some], but it can help to clean up the code in long-winded audio processing functions.

Return Values

The result of the last computation within the plug-in code will be given back from Nyquist to Audacity. According to the data type of the Nyquist return value one of the following actions will be invoked in Audacity:

Sound: The sound will be re-inserted into the selected part of the Audacity track. 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, so in both channels of the stereo track the same mono sound will be inserted. If a stereo sound is returned to a mono track, an error message will be displayed.

String: A dialog window will appear with the string being displayed as text.

Number: A dialog window will appear with the number being displayed as text.

List: If a specially formatted list is given back to Audacity, a label track will be created below the audio track(s).

For point labels the format is:

 ((number "string") (number "string") ... )

The list to create a label track must contain one or more lists, each of which must have:

• number - (an integer or float) is the time in seconds from the beginning of the Audacity selection, where the label will appear.
• "string" - a string to be displayed in the label's text field.

For region labels (Audacity 1.3) each label list must contain two int-or-float elements, one for the start and one for the end of the label region.

 ((number number "string") (number number "string") ... )

Audacity will always place returned audio or labels relative to the start of the selection and not the start of the Timeline.

Math Functions

n-th power of x:

 power(x, n) ;; in SAL
 (power x n) ;; in LISP
 

n-th root of a number:

 power(x, 1.0 / n) ;; in SAL
 (power x (/ 1.0 n)) ;; in LISP 

n-th root of a sound s:

 return s-exp(s-log(s) * (1.0 / n)) ;; in SAL
 (s-exp (mult (s-log s) (/ 1.0 n))) ;; in LISP

n-th root with two sounds x and n:

 return s-exp(s-log(x) * s-recip(n))  ;; in SAL
 (s-exp (mult (s-log x) (s-recip n))) ;; in LISP

Nyquist Workbench

The Nyquist Workbench gives the ability to run arbitrary Nyquist code in Audacity from a graphical IDE.

The Nyquist Workbench is an Audacity module, previously available as standalone source code from http://audacity.homerow.net/index.php?dir=modules%2F.

Nyquist Workbench is included in the Audacity HEAD source code at \lib-src\mod-nyq-bench and has now moved from the Tools menu to the View menu.

It is necessary to compile the mod-nyq-bench module on the same date as Audacity. Otherwise the version string check will stop the module loading.

Linux

The following steps are correct for Linux as of July 2013 building from the Audacity HEAD development code.

1. Type "./configure " in the Audacity source code directory:

 ./configure

2. If configure completes successfully, compile Audacity. In the Audacity source code directory type:

 make

If you are having problems at either of the above points, try the Compiling Audacity Step by Step Guide.

3. If 'make' completes successfully, still in the Audacity source code directory, type:

 sudo make install

which by default installs Audacity to "/usr/local/share/audacity".

4. Open /lib-src/mod-nyq-bench/Makefile and set the required AUDACITY_DIR variable at the top of the Makefile to the base of your Audacity source code directory, for example:

 AUDACITY_DIR ?= /home/edgar/downloads/audacity

5. After saving the changes in the Makefile, compile the Nyquist Workbench. In the Nyquist Workbench directory type:

 make

After "make" has finished you should see a message like:

 NyqBench.so has been copied to /home/edgar/downloads/audacity/modules

6. On Linux, the Audacity "make install" does not copy the "modules" directory, so change to the base of your Audacity source code directory, then type:

 sudo cp -r modules /usr/local/share/audacity

This copies the "modules" directory with its complete contents from the Audacity source code directory to "/usr/local/share/audacity/modules". If you installed Audacity other than to /usr/local/share/audacity, point the copy command to that directory. Alternatively, you could create an "~/.audacity-files/modules" directory:

 mkdir -p ~/.audacity-files/modules

then move or copy "NyqBench.so" into that "modules" directory where Audacity will find it irrespective of the location of the Audacity installation directory.

Mac OS X

This information assumes you have already followed Building On Mac and is correct as of July 2013.

1. It is not currently possible to build mod-nyq-bench at the command-line using the Makefile. Therefore it is suggested that you build both Audacity and mod-nyq-bench in the Xcode IDE. First, build Audacity using the Xcode IDE.
2. Next, in the "Groups & Files" column in Xcode, expand "Targets" and select "mod-nyq-bench". Right-click over the selection and choose Build "mod-nyq-bench" . Alternatively from the dropdown box top left, under the "Active Target" list, click on "mod-nyq-bench" (don't change the "Active Configuration"), then click the "Build" icon.
3. Assuming you built Release Static configuration, separate PPC and i386 builds of mod-nyq-bench.so will be built in their own folder inside
   <path to Audacity build>/mac/build/Audacity.build/Release Static/mod-nyq-bench.build/Objects-normal.

   However the build process uses lipo to create a single universal binary mod-nyq-bench.so in
   <path to audacity build>/mac/build/Release Static/modules.

   This universal binary is the module Audacity will load.

Loading/Enabling mod-nyq-bench

As of 2.0.7-alpha (r13379, 02 October 2014), after first building mod-nyq-bench you will need to launch Audacity then enable mod-nyq-bench in Modules Preferences. Set the control to "Enable" and restart Audacity then the "Nyquist Workbench" item will be visible at the bottom of View Menu.

From r12363 (16 June 2013) until r13378, each time you launch Audacity you will be asked if you want to load mod-nyq-bench. If you choose "yes" and the build of mod-nyq-bench matches with the version string of Audacity, you should then have an additional "Nyquist Workbench" entry at the bottom of the "View" Menu.

Gale 02Oct14: Not clear yet if the below is the same as r13379, that is if an enabled mod-nyq-bench must be rebuilt if you rebuild Audacity post r13379 tomorrow.

Prior to r12363, when you launched Audacity after a first build of mod-nyq-bench, you had to enable the module in a Modules Preferences, then if so enabled Audacity would load mod-nyq-bench on next launch if it was matched with the Audacity version string.

Rebuilding Audacity and Nyquist Workbench

When you update your Audacity source code tree and rebuild Audacity on a subsequent day, you must also rebuild mod-nyq-bench.

• It is recommended to run "make clean" or "make distclean" before configuring and building Audacity.
  • In Xcode on Mac, select "Audacity" under "Targets" and choose Clean "Audacity"  before rebuilding Audacity.
• After building Audacity, change to the Nyquist Workbench directory, type "make clean" to remove NyqBench.so and NyqBench.o, then type "make" to rebuild NyqBench.so.
  • In Xcode on Mac, select "mod-nyq-bench" under "Targets" and choose Clean "mod-nyq-bench"  before rebuilding the module.

Nyquist Apropos Plug-in

Because not all functions, documented in the Nyquist manual, are implemented in Audacity and also not even all Nyquist functions are documented in the Nyquist manual [Lisp is a "programmable programming language", only functions which are considered as stable are documented], it is often helpful to have a tool to find out whether a particular Nyquist function is implemented or not.

Basically only Nyquist functions beginning with "snd-..." are implemented in C within the Nyquist interpreter [in the Nyquist manual they are called 'low-level' functions], while all other Nyquist functions are implemented in the Lisp files within the Audacity "nyquist" sub-directory and can be changed, improved and extended with no need to re-compile Audacity [as long as no C-implemented Nyquist "low-level" function is needed which is not included with Nyquist in Audacity].

All Nyquist/XLISP symbols [e.g. all variable and function names] are stored in the XLISP *obarray*. To find out from within Audacity, whether a particular function is implemented or not, you can e.g. first create and select a "dummy" audio track with any generator from the Audacity Generate menu, then open Effect > Nyquist Prompt... [doesn't work without a selected audio track] and copy the following line into the "Nyquist Prompt" text input field:

 (print (fboundp 'snd-abs))

Important: now please click "Debug" instead of the "OK" button.

First a dialog appears telling you: "Nyquist did not return audio" [or similar]. In this dialog, click the "OK" button. Then another dialog "Nyquist output" appears with the result of the "print" function:

• T - meaning "true", function is implemented

• NIL - meaning "false", function is not implemented

I had typed this so often in the past that I have written an Audacity Nyquist "Apropos" Plug-in:

Download: Apropos-Plug-in

Right-Click on the plug-in link, choose "save target as", and save the file "apropos.ny" file in the Audacity "Plug-Ins" sub-directory. After a re-start of Audacity you can find the "Apropos" Plug-in in the Generate menu, the only menu that works without a "dummy" audio track.

The "Apropos" Plug-in offers a pattern search through the Nyquist/XLISP *obarray*. You can also choose between "Functions only", "Variables only" and "All symbols":

Note: with no search pattern [empty field], the plug-in matches all symbol names.

Important: As written in the plug-in window, please press "Debug" instead of the "OK" button, otherwise you will not see the results.

First appears a dialog that reminds me that I have forgotten to press the "Debug" button:

In the first dialog above, just klick the "OK" button. Afterwards, but only if you have clicked the "Debug" button in the plug-in window, appears the window with the results, sorted in alphabetical order:

Bugs

Details of current bugs that affect Nyquist in Audacity are listed on Bugzilla.