Nyquist Plug-ins Reference

From Audacity Wiki
Jump to: navigation, search
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.
  • 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.


Contents

  1. Overview
  2. Nyquist Plug-in Header
  3. Nyquist Plug-in Widgets
  4. Global Variables
  5. Global Property Lists
  6. Stereo Tracks
  7. Return Values
  8. Playing sounds with Nyquist
  9. See Also


Overview

Nyquist is a superset of the XLISP programming language, (a dialect of LISP and supports both a LISP syntax and an alternative syntax called SAL. A general introduction to Nyquist is given on the main Nyquist page.

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


Nyquist Plug-in Header

As in most other computer languages, Nyquist supports code comments. Any line beginning with a semi-colon (";") is entirely ignored by Nyquist. Comments may also be placed at the end of a line of code by beginning the comment with a semi-colon. Nyquist ignores everything from the semi-colon to the end of the line.

In Audacity, special comments are used in Nyquist plug-ins to pass information to Audacity. As with other code comments, these are ignored entirely by Nyquist, but provide instructions to tell Audacity how to create the plug-in.


Plug-in Header Format

Plug-in headers are written as:

;keyword args

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.

Important:

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


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

Warning icon Multi-language support is available only to plug-ins that are shipped with Audacity, as the translations must be compiled into Audacity's language files.

Example:

$name (_ "Name of Effect")


These headers are required in all Nyquist plug-ins.

 ;nyquist plug-in
 ;name "name"
 ;type "type"
 ;version version

These headers may be used to provide additional functionality.

 ;action "text"
 ;author "text"
 ;codetype type
 ;control parameters
 ;copyright "text"
 ;debugbutton option
 ;debugflags flags
 ;helpfile "path to file"
 ;manpage "URL"
 ;maxlen integer
 ;mergeclips integer
 ;preview option
 ;restoresplits integer

These headers are no longer used by current versions of Audacity and are ignored.

 ;categories "text"
 ;info "text"


Required plug-in headers

nyquist plug-in

Tells Audacity "this is a Nyquist plug-in". This should normally be the first line as it defines the contents of the file.

 ;nyquist plug-in


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

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.


type

Only one ";type" line should be used.
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
;type analyze Plug-in appears in the Audacity Analyze menu:
;type generate Plug-in appears in the Audacity Generate menu:
;type process Plug-in appears in the Audacity Effect menu:


version

Use only one ";version" line.
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 header Features
;version 1 Slider Widget
;version 2 Text input widget added
;version 3 multiple-Choice widget added
;version 4


Aditional plug-in headers

action

Text to be displayed while the plug-in is working. The text string must be quoted.

 ;action "text"


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". The author name string must be quoted.

 ;author "Name of Plug-in Author(s)"


codetype

Declaration of code syntax. May be either lisp or sal. The default is Lisp syntax.

  • If the code type is not declared in a plug-in, the code is assumed to use Lisp syntax.
  • 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.
 ;codetype type

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. The ;control headers should normally be the final headers as they define variables used by the Nyquist code.

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


debugbutton

Show or hide the Debug button. 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 Debug button may be hidden by setting this to "false" or "disabled"

 ;debugbutton false

or

 ;debugbutton disabled


debugflags

The "trace" / "notrace" options should be used only for LISP code, and the "compiler" / "nocompiler" should be used only for SAL code.
debugflag options
debugflags header Description
;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 Debug button has been pressed.

If the Debug button has not been pressed and there is an error, the error message will be sent to Audacity's log. Note that disabling *tracenable* limits the debug output to only the error message with little or no additional debugging information.

;debugflags compiler Set *sal-compiler-debug* to 'false'.

Enables debug messages from SAL. If the Debug button has been pressed, debug messages are printed to the Debug window, otherwise to the Audacity log.

;debugflags nocompiler Set *sal-compiler-debug* to 'true'.

Disables debug messages from SAL. If the Debug button has been pressed, short error messages only are printed to the Debug window, otherwise to the Audacity log.


helpfile

A Help button may be added to the plug-in GUI by giving the relative path and name of a help file.

 ;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:

 ;helpfile "my_effect_help/my_effect.html"
If the help file is not found, the ? button will not appear.


manpage

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

 ;manpage URL


maxlen

Specifies the maximum number of samples to be processed. 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:

 ;maxlen 1000000


mergeclips

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


Clip Merge Options
  • -1 Automatic clip merge behaviour (default)
 ;mergeclips -1
  • 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.
 ;mergeclips 0
  • 1 Always merge clips. The returned audio will always be merged into the existing audio (no split lines added).
 ;mergeclips 1
See also "restoresplits".


preview

Provides options for previewing the effect. Multiple preview options may be defined to achieve the desired behaviour.

Preview Options
  • enabled (default). Preview is enabled.
 ;preview enabled
  • true Same as "enabled".
 ;preview true
  • 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.
 ;preview disabled
  • false Same as "disabled".
 ;preview false
  • linear Provides an optimisation for previewing multiple tracks by mixing the selected tracks before applying the Nyquist code. This optimisation is disabled by default.
 ;preview linear
  • 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.
 ;preview selection


restoresplits

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

Restore Splits Options
  • 1 Splits at clip boundaries are restored (default)
 ;restoresplits 1
  • 0 Splits at clip boundaries are not restored (clips are joined).
 ;restoresplits 0

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 may still be found in some old plug-ins, but are now treated by Audacity as ordinary "comments" and simply disregarded.


categories

Specifies an LV2 category for the plug-in.

 ;categories "text"


info

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" bay be used within "text" to create a line break.

 ;info "text"


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 float / real string float float float
;control symbol string int-text string integer integer integer
;control symbol string float-text string float float float
;control symbol string string string string - -
;control symbol string choice string integer - -


int-text and float-text were added in Audacity 2.1.2. They are ignored by earlier versions of Audacity, which may lead to an "unbound symbol" error if the plug-in is run in an old version of Audacity. These controls should not be used in plug-in versions less than version 4.
"real" (deprecated) is an alternative name for "float" and is provided as legacy support for old plug-ins.

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-widget.png

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, float or real*:
    • int - integer [FIXNUM, an XLISP whole number]
    • float (or real*) - floating point [FLONUM, an XLISP number supporting decimal places]
  • 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. As of Audacity 2.1.1, input values are validated to only allow input between minimum and maximum values.

  • The "real" keyword is deprecated. New plug-ins should use "float" as the variable type for floating point input.


Numeric Text Widget

Numeric-text-widget.png

The numeric text widget was introduced in Audacity 2.1.2.

 ;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 text box.
  • variable-type - a "number" type, either "int-text" or "float-text":
    • int-text - integer [FIXNUM, an XLISP whole number]
    • float-text - floating point [FLONUM, an XLISP number supporting decimal places]
  • text-right - text that will appear to the right of the text box.
  • initial-value - variable value at the first start of the plug-in.
  • minimum - numerical minimum variable value that will pass validation.
  • maximum - numerical maximum variable value that will pass validation.

Minimum and maximum may be numeric values or "NIL". The minimum / maximum is not defined when set as "NIL" and is limited only by the numeric limit for the number type. The valid range for numbers depends on the computer platform. Typically the limits for integers are -2147483648 to 2147483647. The limits for floating point numbers are very large.

Examples of undefined minimum / maximum:

 ;control pos "Positive Integer" int-text "text-right" initial-value 0 nil
 ;control neg "Negative Integer" int-text "text-right" initial-value nil 0
 ;control num "Any number" float-text "text-right" initial-value nil nil


String Widget (text input)

Text-widget.png

The text input widget ("string 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

Choice-widget.png

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.


Global Variables

In addition to the standard global variables defined in the Nyquist Reference Manual, Nyquist in Audacity also has global variables that relate specifically to Audacity. These additional globals are defined in the file "audacity/lib-src/libnyquist/nyx/nyx.c" in the Audacity source code.
  • *TRACK* - 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* - A variable with a list of properties relating to the file system.
  • *SYSTEM-TIME* - A variable with a list of properties relating to the system time/date.
  • *PROJECT* - A variable with a list of properties relating to the current Audacity project.
  • *SELECTION* - 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.
For more information. see the *SCRATCH* tutorial.
  • S (obsolete) - Prior to version 4 plug-ins, in process and analyze type plug-ins this was 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 - 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:

  • Lisp syntax
 (/ len *sound-srate*)
 (get-duration 1)
  • SAL syntax
 len / *sound-srate*
 get-duration(1)


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


Global Property Lists

Property lists are defined for the global variables *AUDACITY*, *PROJECT*, *SELECTION*, *SYSTEM-DIR*, *SYSTEM-TIME*, and *TRACK*.

Warning icon For information about using property lists, see the Nyquist Property List Tutorial.


*AUDACITY*

This property list was added in Audacity version 2.1.0

Value: Unbound (not defined).

Example - when Audacity's locale setting is for English, (print (get '*audacity* 'language)) will print en.
  • VERSION : [integer list] A list in the form (Audacity_version Audacity_release Audacity_revision)
 ;;Example: Print the full Audacity version for Audacity 2.1.3
 (let ((version-list (get '*audacity*' version)))
   (format nil "Audacity version ~a.~a.~a" (first version-list)(second version-list)(third version-list)))
 
 ;; Prints: Audacity version 2.1.3


*PROJECT*

Value: Unbound (not defined).

  • LABELTRACKS : [integer] The number of label tracks in the project.
  • MIDITRACKS : [integer] The number of note tracks in the project.
  • NAME : [string] The name of the current project. A project that has not been named (not yet saved) returns an empty string.
  • PROJECTS : [integer] The number of open projects.
  • RATE : [integer] The project rate in the project.
  • TIMETRACKS : [integer] The number of time tracks in the project.
  • TRACKS : [integer] The number of tracks in the project.
  • WAVETRACKS : [integer] The number of audio tracks in the project.


*SELECTION*

Value: Unbound (not defined).

  • BANDWIDTH : [float] The bandwidth of the frequency selection in octaves (Spectrogram or Spectrogram (log f) track view).
  • CENTER-HZ : [float] The centre frequency selection in Hz (Spectrogram or Spectrogram (log f) track view).
  • CHANNELS : [integer] The number of selected audio channels.
  • END : [float] The end of the selection in seconds.
  • HIGH-HZ : [float] The high frequency selection Hz (Spectrogram or Spectrogram (log f) track view).
  • LOW-HZ : [float] The low frequency selection Hz (Spectrogram or Spectrogram (log f) track view).
  • RMS : [float or array] For mono tracks, the RMS amplitude (linear scale). For stereo tracks, an array containing the RMS for each channel.
  • PEAK : [float or array] For mono tracks, the absolute peak level (linear scale). For stereo tracks, an array containing the absolute peak level for each channel. Returns 'NIL' if peak level is infinite or NaN.
  • PEAK-LEVEL : [float] The absolute peak level (linear scale). Returns 'NIL' if peak level is infinite or NaN.
  • START : [float] The start of the selection in seconds.
  • TRACKS : [integer list] A list of track numbers of selected audio tracks.


*SYSTEM-DIR*

Value: Unbound (not defined).

  • 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).
  • PLUG-IN : [string list] The Nyquist plug-in search path. This includes the directories where Audacity looks for Nyquist plug-ins, and other Nyquist related files. Not all directories are currently used and some are for legacy support only.
  • TEMP : [string] The Audacity temp directory. This is where unsaved project data is temporarily stored.


*SYSTEM-TIME*

This property list was added in Audacity version 2.1.1.

Value: A list in the form '(year, day, hours, minutes, seconds), where each list item is an integer.

Example: 5 minutes past 2pm January 1st 2018 would be the list: 2018, 1, 14, 5, 0.

(Note that "day" is a number in the range 1 to 366, counted from the start of the year).
This is the time that the Nyquist code is parsed, NOT the time it is executed. It cannot therefore be used for timing events that occur while the code is running. Possible uses for *SYSTEM-TIME* could include automatic naming of files written to disk, or for "seeding" random processes.
  • DATE : [string] The date formatted according to the current locale. Example: "dd/mm/yy".
  • DAY : [integer] Day of the month.
  • DAY-NAME : [string] The name of the day (Example: "Monday").
  • ISO-DATE : [string] The date represented in the ISO 8601 format "YYYY-MM-DD".
  • ISO-TIME : [string] The time represented in the ISO 8601 format "HH:MM:SS".
  • MONTH : [integer] The month (as an integer).
  • MONTH-NAME : [string] The name of the month (Example: "January").
  • TIME : [string] The time formatted according to the current locale. Example: "hh:mm:ss".
  • YEAR : [integer] The year (as an integer).


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

  • CHANNELS : [integer] The number of channels in the track (mono = 1, stereo = 2).
  • 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. (see below for examples)
  • END-TIME : [float] The track end time.
  • FORMAT : [integer or float] The track sample format. One of (Integer) 16, (Integer) 24, or (float) 32.
  • GAIN : [float] The value of the track Gain slider.
  • 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.
  • PAN : [float] The value of the track Pan slider.
  • RATE : [float] The track sample rate.
  • SPECTRAL-EDIT-ENABLED : [bool] Returns 'T' (true) if spectral editing is enabled, otherwise 'NIL'. Note that this is irrespective of the track view and will return 'T' if the spectral editing option for the track is enabled even if the track is not displaying a spectrogram.
  • START-TIME : [float] The track start time (note that this will often be different from the selection start time.)
  • 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" or NIL.
The VIEW property may change in future versions of Audacity, so is not recommended for public release plug-ins. During Preview, audio tracks are copied to temporary tracks which are not visible, so the returned "VIEW" value is NIL.

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


Stereo Tracks

  • If a sound from an Audacity stereo track was given to Nyquist, the *TRACK* variable contains an array of sounds.
  • To return a stereo sound to a stereo Audacity track, the Nyquist code should produce a return value that is an array of two sounds. The first element of the array being the left channel, and the second element being the right channel.
Warning icon Returning an array of sounds to a mono track is an error.

For more information about stereo tracks, see the Nyquist Stereo Track Tutorial.


Return Values

Nyquist supports many "data types", including "numbers" (integer or floating-point), "characters" (such as the letter "A", the number "4", or any other ASCII character), "strings" (text), "list" (a list of data), "array" (special kind of indexed list), and "sounds" (a sound / digital signal).

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 returned value one of the following actions will be invoked in Audacity:


Mono Sound

If a "sound" is returned, the sound will be re-inserted into the selected part of the Audacity track, (or a new track for "generate" type plug-ins). 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, the same mono sound will be inserted into both channels of the stereo track.


Multi-Channel / Stereo Sound

Nyquist handles multi-channel sounds as an array of sounds (see above). Audacity currently supports a maximum of two channels in a track (stereo). If a stereo sound is returned to a mono track, or an array of more than two sound channels to any track, an error message will be displayed. To return a stereo sound without error, a stereo track must be selected before running the Nyquist code.


String / Text

When the return value is a character or string, a dialog window will appear with the data displayed as text.


Number

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


Labels

If an appropriately formatted list is returned 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, 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.


Empty String

An empty string may be used as a "null return", which means that the plug-in returns nothing, and no error. An example use would be if you wish to process only the first selected track.

;; Example: Apply a function "process" to
;; the first selected track only.

(if (= (get '*track* 'index) 1)
    (process *track*)
    "")


Playing sounds with Nyquist

When using the Nyquist Prompt or (most) Nyquist plug-ins that have a GUI, if the plug-in returns a sound, it may be previewed using the Preview button. In addition to this, it is also possible to play sounds directly from Nyquist, using the PLAY function. The PLAY function will be executed when the plug-in code runs.

Warning icon The PLAY function is described in the Nyquist manual. The information here describes aspects that are specific to Nyquist in Audacity.

Note that the Nyquist PLAY command does not use Audacity's audio device settings. Nyquist uses the system default device for playback, and has a default buffer of 100 ms. The buffer setting may be changed with the SND-SET-LATENCY command. The actual latency values are dependent on the computer sound system and may differ from those requested by Nyquist.

To see the list of available devices when Nyquist plays, set *snd-list-device* to "true" before the play command, then use Debug button to see the output.

  (setf *snd-list-devices* t)
  (play *track*)

To select a specific output device, set *snd-device* to the index number of the device you wish to use (not all devices are valid). For example, if ALSA hw(0,0) is device 0, select it with:

  (setf *snd-device* 0)
  (setf *snd-list-devices* t)
  (play *track*)
Warning icon It is not possible to interrupt Nyquist playback. The sound will continue playing until it reaches the end, and other Audacity functions are disabled until Nyquist playback has finished.

To limit the amount of audio that will play, the length of the sound must be defined before starting playback. For example, to play the first 1 second of a selection, you could write (LISP syntax):

(play (extract-abs 0 1 *track*))

Note also that if a plug-in uses Nyquist PLAY command, using Preview will cause an error on some machines because Audacity may not be able to access the audio device while it is being used by Nyquist. For "own use" plug-ins, if you have more than one sound card, a possible workaround to enable Preview and Nyquist PLAY simultaneously, is to set the Nyquist playback device to a different device to that which Audacity uses. For public release plug-ins the Preview button should normally be disabled if Nyquist PLAY is used.


See Also


|< Nyquist