Difference between revisions of "Nyquist Plug-ins Reference"

From Audacity Wiki
Jump to: navigation, search
(Mac OS X: Updated instructions for Xcode IDE)
(Plug-in Header Example: Remove obsolete ;action header from example.)
 
(188 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Introrel|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]].|[[:Category:Digital Audio Technology|Digital Audio Technology]]
+
{{Intro|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.|
*[[Nyquist Audio Programming]] - "How to" and other explanatory articles
+
*If you are looking for extra Nyquist plug-ins to use, see [[Nyquist Plug-ins]].
*[http://www.cs.cmu.edu/~rbd/doc/nyquist/ Nyquist 3.02 Reference Manual]
+
*If you are especially interested in Nyquist in Audacity, we highly recommend subscribing to our [https://forum.audacityteam.org/ Audacity forum], which has a section specifically for matters relating to Nyquist.}}
*[http://www.audacity-forum.de/download/edgar/nyquist/nyquist-doc/xlisp/xlisp-index.htm XLISP 2.0 Manual]
 
  
{{Hint|1=Nyquist is based on XLISP, (a dialect of [https://en.wikipedia.org/wiki/Lisp_%28programming_language%29 LISP] and supports both a LISP syntax and an alternative syntax called SAL. LISP syntax is more commonly used in Nyquist plug-ins for Audacity, though users that have experience with C-like languages may find SAL more familiar.}}
+
__NOTOC__
}}
+
==Contents==
 +
#[[#overview|Overview]]
 +
#[[#header|Nyquist Plug-in Header]]
 +
#[[#widgets|Nyquist Plug-in Widgets]]
 +
#[[#selections|Tracks and Selections]]
 +
#[[#globals|Global and Reserved Variables]]
 +
#[[#property_lists|Global Property Lists]]
 +
#[[#Return Values|Return Values]]
 +
#[[#play|Playing sounds with Nyquist]]
 +
#[[#Plug-in_Translations|Plug-in Translations]]
 +
#[[#See Also|See Also]]
  
{{Hint|1=If you are especially interested in Nyquist in Audacity, we highly recommend subscribing to our [http://forum.audacityteam.org/ Audacity forum], which has a section specifically for matters relating to Nyquist.}}
 
  
{{ednote|1='''Steve 26Oct15:''' [[ToDo-2]] The images on this page need updating to current Windows screenshots}}
+
<div id="overview"></div>
  
__TOC__
+
==Overview==
 +
Nyquist is a superset of the XLISP programming language, (a dialect of LISP and supports both a [[Nyquist#lisp|LISP syntax]] and an alternative syntax called [[Nyquist#sal|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:
 
The Audacity Nyquist Interface is implemented in the following files in the Audacity source code:
 
 
* audacity/src/effects/nyquist/Nyquist.cpp
 
* audacity/src/effects/nyquist/Nyquist.cpp
 
 
* audacity/lib-src/libnyquist/nyx.c
 
* audacity/lib-src/libnyquist/nyx.c
  
 +
Nyquist is in many ways a separate program from Audacity (and is also available as a [https://www.cs.cmu.edu/~music/nyquist/ standalone programming language]). Nyquist is embedded in Audacity as a software [https://en.wikipedia.org/wiki/Library_(computing) library] that may be called from the main Audacity application to provide additional functionality, most notably as "plug-ins".
  
== Overview ==
+
When a Nyquist plug-in is selected from one of Audacity's menus, Audacity locates the plug-in script (the ".NY" file), starts a Nyquist session and passes the Nyquist code to be interpreted by the Nyquist library. Nyquist then attempts to run the program. The result of running the Nyquist script is returned to Audacity.
Nyquist plug-ins are simple text files ending with the file name 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 {{Menu|Nyquist Prompt...}} effect. Since defining "'''main'''" just to evaluate and return a simple expression is so awkward, you can simply type
 
  return <i>expression</i>
 
Normally, this is not a legal statement as a top-level command in SAL, but in {{Menu|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 {{Menu|Nyquist Prompt...}} effect. There is only one "Nyquist Prompt" for both SAL and LISP syntax. Audacity looks for the first character that is not a space or part of a comment. If it is an open paren "(", then the code is assumed to be LISP; otherwise, SAL is assumed.
 
  
{{ednote|Update this in due course when 2.1.0 is obsolete}}
+
<div id="header"></div>
From version 2.1.1, the Nyquist Prompt effect can interpret header comments and produce a plug-in of the defined type on the fly. By  default the plug-in is a [[#type_process|process type]], though other type may be created by including the appropriate [[#Required_plug-in_header_lines|header]]. In older versions of Audacity 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 [http://en.wikipedia.org/wiki/Ascii 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 ==
 
== Nyquist Plug-in Header ==
 +
{{intro|1=As in most other computer languages, Nyquist supports [https://en.wikipedia.org/wiki/Comment_(computer_programming) 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.|2=
  
{{Hint|1='''Important''':
+
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.}}
*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.
 
*Headers must be all lower-case except for quoted text (for example: "''name''") which may include upper-case characters.}}
 
  
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.
+
===Plug-in Header Example===
 +
In this example (derived from the [https://manual.audacityteam.org/man/high_pass_filter.html High-Pass Filter] effect), the first four lines make up the essential headers that are required in all Nyquist plug-ins.
 +
* {{inlineCode|;nyquist plug-in}} : This header tells Audacity that this file is a Nyquist plug-in.
 +
* {{inlineCode|;version 4}} : This header specifies that this is a "4th generation" plug-in.
 +
* {{inlineCode|;type process}} : This header defines the plug-in as a "process" (''Effect'') type.
 +
* {{inlineCode|;name "High-Pass Filter"}} : This header tells Audacity the name of the plug-in.
 +
<pre>
 +
;nyquist plug-in
 +
;version 4
 +
;type process
 +
;name "High-Pass Filter"
 +
;preview linear
 +
;manpage "High-Pass_Filter"
 +
;debugbutton disabled
 +
;author "Dominic Mazzoni"
 +
;release 3.0.2
 +
;copyright "Released under terms of the GNU General Public License version 2 or later."
  
*'''Essential plug-in headers:'''
+
;control frequency "Frequency (Hz)" float-text "" 1000 0 nil
These headers are required in all Nyquist  plug-ins.
+
</pre>
  ;nyquist plug-in
+
The other headers enable various options and properties, including the plug-in's controls.
  ;name "''name''"
+
{{advice|Full descriptions of all plug-in headers are provide on the [[Nyquist_Plug-in_Headers|Nyquist Plug-in Headers]] page.}}
  ;type "''type''"
 
  ;version ''version''
 
*'''Aditional headers:'''
 
These headers may be used to provide additional functionality.
 
  ;action "''text''"
 
  ;author "''text''"
 
  ;codetype ''type''
 
  ;copyright "''text''"
 
  ;debugflags ''flags''
 
  ;maxlen ''integer''
 
  ;mergeclips ''integer''
 
  ;preview ''option''
 
  ;restoresplits ''integer''
 
  ;control ''parameters''
 
*'''Deprecated headers:'''
 
These headers are no longer used by current versions of Audacity and are ignored.
 
  ;categories "''text''"
 
  ;info "''text''"
 
  
 +
<div id="widgets"></div>
  
=== Required plug-in headers ===
+
== Nyquist Plug-in Widgets ==
 
+
{{intro|1=Nyquist plug-ins support a range of "widgets", which are control elements for a graphical user interface (GUI). These elements are unique to Nyquist in Audacity.|2=
==== nyquist plug-in ====
+
The GUI is created by Audacity when a plug-in contains one or more widget header commands.}}
Tells Audacity "this is a Nyquist plug-in". This should normally be the first line as it defines the contents of the file.
+
As with other plug-in headers, they begin with a semicolon (;) and are ignored by Nyquist, except that the variable name of the widget is initialized with a value and made available to Nyquist. This means that Nyquist can access the value that has been set in the widget as the value of the variable specified in the widget header.
  ;nyquist plug-in
+
{{note|The "Text widget" is an exception to the above at it is for display purposes only and does not set a value.}}
 
 
 
 
==== 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 [http://manual.audacityteam.org/o/man/chains_for_batch_processing_and_effects_automation.html 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 ====
 
{{Hint|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.}}
 
===== type analyze =====
 
Plug-in appears in the Audacity {{Menu|Analyze}} menu:
 
  ;type analyze
 
 
 
===== type generate =====
 
Plug-in appears in the Audacity {{Menu|Generate}} menu:
 
  ;type generate
 
 
 
===== type process =====
 
Plug-in appears in the Audacity {{Menu|Effect}} menu:
 
  ;type process
 
 
 
 
 
==== version ====
 
{{Hint|Use only one ";version" line. New plug-ins should 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 new features from being loaded in an old Audacity program that is missing required features.}}
 
===== 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 [[Nyquist_Plug-ins_Reference#Nyquist_Variables|global variables]] were added in Audacity 2.1.0 to pass additional information from Audacity to Nyquist.
 
*New optional plug-in headers:
 
These headers are ignored by versions of Audacity that are older than the version stated.
 
** ''';author''' and ''';copyright''' were added in Audacity 2.1.0.
 
** ''';preview''', ''';mergeclips''' and ''';restoresplits''' were added in Audacity 2.1.1.
 
** ''';maxlen''' was added in Audacity  2.1.2.
 
  ;version 4
 
 
 
 
 
=== Aditional plug-in headers ===
 
 
 
==== action ====
 
Text to be displayed while the plug-in is working:
 
  ;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".
 
  ;author
 
 
 
 
 
==== codetype ====
 
 
 
===== 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|Nyquist Plug-in Widgets]] below. The ;control headers should normally be the final headers as they define variables used by the Nyquist code.
 
  ;control <i>parameters</i>
 
 
 
 
 
==== copyright ====
 
A short statement of the copyright/license terms. For plug-ins shipped with Audacity, this must be compatible with Audacity's [http://www.gnu.org/licenses/old-licenses/gpl-2.0.html GPL v2] license. Recommended text for GPL v2 license:
 
:<nowiki>;copyright "Released under terms of the GNU General Public License version 2"</nowiki>
 
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 <i>flags</i>
 
{{Hint|'''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.}}
 
 
 
 
 
==== 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").'''
 
 
 
{{Hint|1='''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 "[[Nyquist_Plug-ins_Reference#restoresplits|restoresplits]]".
 
}}
 
 
 
 
 
==== preview ====
 
Provides options for previewing the effect. Multiple preview options may be defined to achieve the desired behaviour.
 
{{Hint|'''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").'''
+
Each widget begins with "''';control'''", and is followed by a number of parameters, one of which defines the ''type'' of widget. There are currently nine widget types, though not all of them are available for old versions of Audacity.
{{Hint|'''Restore Splits Options'''
 
* '''1''' Splits at clip boundaries are restored (default)
 
  ;restoresplits 1
 
  
* '''0''' Splits at clip boundaries are not restored (clips are joined).
+
When a plug-in is launched, Audacity searches the plug-in '''.NY''' file for valid headers. Every ";control" line that is found gets parsed by Audacity into several tokens, where each token is separated by spaces. If the tokens match one of the defined patterns, then Audacity adds the widget to the GUI, otherwise they are ignored.
  ;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 "[[Nyquist_Plug-ins_Reference#mergeclips|mergeclips]]".
 
}}
 
 
 
=== Deprecated plug-in headers ===
 
 
==== categories ====
 
Specifies an [[LV2 Support#2008-06-04: Category support working|LV2 category]] for the plug-in. This header is ignored by current versions of Audacity.
 
  ;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. This header is ignored by current versions of Audacity.
 
  ;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:
 
 
{| class="wikitable"
 
{| class="wikitable"
|+ Syntax for ;control lines
+
|+ Syntax for widgets
 
!;control !! var-name !! text-left !! widget-type !! text-right !! initial-value !! minimum !! maximum
 
!;control !! var-name !! text-left !! widget-type !! text-right !! initial-value !! minimum !! maximum
 
|-
 
|-
|;control || <i>symbol</i> || <i>string</i> || int || <i>string</i> || <i>integer</i> || <i>integer</i> || <i>integer</i>
+
|;control || <i>symbol</i> || <i>string</i> || '''int''' || <i>string</i> || <i>integer</i> || <i>integer</i> || <i>integer</i>
 
|-
 
|-
|;control || <i>symbol</i> || <i>string</i> || float / real || <i>string</i> || <i>float</i> || <i>float</i> || <i>float</i>
+
|;control || <i>symbol</i> || <i>string</i> || '''float''' (real) || <i>string</i> || <i>float</i> || <i>float</i> || <i>float</i>
 
|-
 
|-
|;control || <i>symbol</i> || <i>string</i> || int-text || <i>string</i> || <i>integer</i> || <i>integer</i> || <i>integer</i>
+
|;control || <i>symbol</i> || <i>string</i> || '''int-text''' || <i>string</i> || <i>integer</i> || <i>integer / NIL</i> || <i>integer / NIL</i>
 
|-
 
|-
|;control || <i>symbol</i> || <i>string</i> || float-text || <i>string</i> || <i>float</i> || <i>float</i> || <i>float</i>
+
|;control || <i>symbol</i> || <i>string</i> || '''float-text''' || <i>string</i> || <i>float</i> || <i>float / NIL</i> || <i>float / NIL</i>
 
|-
 
|-
|;control || <i>symbol</i> || <i>string</i> || string || <i>string</i> || <i>string</i> || - || -
+
|;control || <i>symbol</i> || <i>string</i> || '''string''' || <i>string</i> || <i>string</i> || - || -
 
|-
 
|-
|;control || <i>symbol</i> || <i>string</i> || choice || <i>string</i> || <i>integer</i> || - || -
+
|;control || <i>symbol</i> || <i>string</i> || '''choice''' || <i>string</i> || <i>integer</i> || - || -
 +
|-
 +
|;control || <i>symbol</i> || <i>string</i> || '''time''' || <i>string</i> || <i>float</i> || <i>float / NIL</i> || <i>float / NIL</i>
 +
|-
 +
|;control || <i>symbol</i> || <i>string</i> || '''file''' || <i>string</i> || <i>string</i> || <i>string</i> || <i>string</i>
 +
|-
 +
|;control || - || - || '''text''' || <i>string</i> || - || - || -
 
|}
 
|}
  
{{Note|'''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.}}
+
{{Note|"'''real'''" (deprecated) is an alternative name for "float" and is provided as legacy support for old plug-ins. It should  not be used in new code.}}
{{Note|"'''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.
+
''Italic'' words in the table denote data types. Because tokens are separated by whitepace, strings containing whitespace must be written within quotation marks.
  
=== Slider Widget ===
+
This image displays all nine widget types in Audacity 2.3.1 on Windows 10
  
[[Image:slider-widget.png]]
+
[[File:Nyquist-plug-in-widgets.png]]
  
Slider widgets are supported in all Audacity Nyquist plug-in versions.
+
{{Note|Older versions of Audacity may not support all of these controls, which may lead to an "unbound symbol" error. Plug-in users are encouraged to use the current version of Audacity, to ensure that they can benefit from all of the latest features.}}
  
  ;control <i>variable-name</i> "<i>text-left</i>" <i>variable-type</i> "<i>text-right</i>" <i>initial-value</i> <i>minimum</i> <i>maximum</i>
+
The following code may be run in the [https://manual.audacityteam.org/man/nyquist_prompt.html Nyquist Prompt] of Audacity 2.3.1 or later, and produces the GUI shown above:
  
* ''variable-name'' - a Lisp symbol.
+
  ;version 4
* ''text-left'' - text that will appear to the left of the slider.
+
  ;name "Plug-in Widgets"
* ''variable-type'' - a "number" type, either int, float or real*:
+
 
** int - integer [FIXNUM, an XLISP whole number]
+
  ;control filename "File Button widget" file "" "" "" "open"
** float (or real*) - floating point [FLONUM, an XLISP number supporting decimal places]
+
  ;control number-sw "Slider widget" float "(float)" 50 0 100
* ''text-right'' - text that will appear to the right of the slider.
+
  ;control integer-sw "Slider widget" int "(integer)" 50 0 100
* ''initial-value'' - variable value [and slider position] at the first start of the plug-in.
+
  ;control number-nt "Numeric Text widget" float-text "(float)" 50 0 100
* ''minimum'' - numerical variable value when the slider is moved to the left border.
+
  ;control integer-nt "Numeric Text widget" int-text "(integer)" 50 0 100
* ''maximum'' - numerical variable value when the slider is moved to the right border.
+
  ;control string-var "String widget" string "text right" "default string"
 +
  ;control text "Text widget [string]"
 +
  ;control duration "Time widget" time "text right" 30 nil nil
 +
 
 +
  (format nil
 +
          "File Selected: ~s~%~
 +
          Floating point slider: ~s~%~
 +
          Integer slider: ~s~%~
 +
          Floating point text: ~s~%~
 +
          Integer text: ~s~%~
 +
          String: ~s~%~
 +
          (Text widget does not return a value)~%~
 +
          Duration: ~s (seconds)"
 +
          filename
 +
          number-sw
 +
          integer-sw
 +
          number-nt
 +
          integer-nt
 +
          string-var
 +
          duration)
  
The variable value [the slider position] can be referenced by the variable name in the plug-in code.
+
The detailed syntax for each widget type is described on the [[Nyquist Plug-ins Widgets]] page.
  
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.
+
<div id="selections"></div>
  
=== Numeric Text Widget ===
+
== Tracks and Selections ==
 +
{{intro|1= Audacity passes information about the current Audacity session to the Nyquist interpreter, along with the Nyquist code. Typically, when the code runs, it acts on data that has been passed from Audacity, which often includes the selected audio data, and returns data back to Audacity. Here we shall look at the ways that audio data is passed from Audacity to Nyquist, and from Nyquist back to Audacity.}}
  
{{ednote|1='''Steve 26Oct15:''' [[ToDo-1]] Image required.
+
=== Passing Selected Audio to Nyquist ===
 +
For [[#type_process|process]] and [[#analyze|analyze]] type plug-ins, Nyquist runs the plug-in code on each selected track in turn. The audio data is passed from Audacity to Nyquist as a variable called '''*TRACK*''' (the asterisks are part of the name).
  
The following code will generate the required GUI:
+
* For mono tracks, the value of *TRACK* is a "sound" (which is a Nyquist [https://en.wikipedia.org/wiki/Data_type data type]).
 +
* For stereo tracks, the value of *TRACK* is an "array". An array is a special kind of ordered list. The array has two elements, both of which are "sounds". The first element holds audio data from the left channel, and the second element hold data from the right channel.
  
<code>;name "float-text widget"</code>
+
The selected audio is only available to "process" and "analyze" type plug-ins (including the compound types "tool process" and "tool analyze").
<code>;control test "text-left" float-text "text-right" 33 0 100</code>}}
 
  
The numeric text widget was introduced in Audacity 2.1.2.
+
=== Time and Durations ===
 +
The way that time and durations are handled depends on the type of plug-in.
  
  ;control <i>variable-name</i> "<i>text-left</i>" variable-type "<i>text-right</i>" initial-value minimum maximum
+
For [[#type_process|process]] and [[#analyze|analyze]] type plug-ins, the start time of the selection is seen as "time = 0", and the length of the selection is seen as one unit of time. The absolute 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)
  
* ''variable-name'' - a Lisp symbol.
+
{{Hint|1='''NOTE''': <p>'''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 [[#type_process|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.</p><p>
* ''text-left'' - text that will appear to the left of the text box.
+
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 [[#type_generate|generate]] type effect will produce a tone of duration 3.5 seconds.</p>}}
* ''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.
+
For [[#generate|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 [[#.2ASELECTION.2A|*SELECTION*]] '''START''' and '''END''' properties may be used ([[#version 4|version 4]] plug-ins or later).
  
'''Examples of undefined minimum / maximum:'''
+
When generating sounds with a 'generate' type plug-in, durations in Nyquist represent seconds. For example, to generate a 2.5 second sine tone, you could write:
 +
<pre>
 +
;type generate
 +
(osc 60 2.5)
 +
</pre>
 +
but if the same code is used in a 'process' type plug-in, the generated tone will be 2.5 x the duration of the track selection:
 +
<pre>
 +
;type process
 +
(osc 60 2.5)
 +
</pre>
 +
If a duration in seconds is required in a 'process' type plug-in, this may be done using the [http://www.cs.cmu.edu/~rbd/doc/nyquist/part8.html#index583 ABS-ENV] command:
 +
<pre>
 +
;type process
 +
(abs-env (osc 60 2.5))
 +
</pre>
 +
The above examples may be run in the [https://manual.audacityteam.org/man/nyquist_prompt.html Nyquist Prompt].
  
  ;control <i>pos</i> "<i>Positive Integer</i>" int-text "<i>text-right</i>" initial-value 0 nil
+
<div id="globals"></div>
  ;control <i>neg</i> "<i>Negative Integer</i>" int-text "<i>text-right</i>" initial-value nil 0
 
  ;control <i>num</i> "<i>Any number</i>" float-text "<i>text-right</i>" initial-value nil nil
 
  
=== Text Input Widget ===
+
== Global Variables and Reserved Variable Names ==
 +
{{intro|1=In addition to the standard global variables defined in the [http://www.cs.cmu.edu/~rbd/doc/nyquist/part9.html Nyquist Reference Manual], Nyquist in Audacity also has global variables that relate specifically to Audacity. Listed here are a few common standard Nyquist globals, and global variables that are relevant to Nyquist in Audacity.}}
  
[[Image:text-widget.png]]
+
* '''[http://www.cs.cmu.edu/~rbd/doc/nyquist/part9.html#index844 *CONTROL-SRATE*]''' : [float] The sample frequency of the control signals (such as those created by [http://www.cs.cmu.edu/~rbd/doc/nyquist/part8.html#index389 piecewise approximations]. By default 1/20 of the sample rate of the track.
  
The text input widget is supported in plug-ins version 2 or above.  
+
*'''*DECIMAL-SEPARATOR*''' : [char] A comma character (#\') or dot character (#\.) depending on the language selected in [https://manual.audacityteam.org/man/interface_preferences.html Audacity's Preferences].
  
  ;control <i>variable-name</i> "<i>text-left</i>" string "<i>text-right</i>" "<i>initial-string</i>"
+
*'''*FILE-SEPARATOR*''' : [char] The character that separates directories in a path, e.g. "/" (#\/) for Unix, ":" (#\:) for Mac, and "\" (#\\) for Win32.
  
* ''variable-name'' - a Lisp symbol.
+
* '''LEN''' : [int] The number of samples contained in the selected Audacity sound.
  
* ''text-left'' - text that will appear to the left of the text input field.
+
* '''*LOCALE*''' : [list] This is variable name is reserved for [[#Translation_for_third_part_effects|translation strings]].
  
* ''text-right'' - text that will appear to the right of the text input field.
+
* '''*PREVIEWP*''' : [bool] True when previewing an effect, otherwise false.
  
* ''initial-string'' - the string will appear inside the text field.
+
* '''*RUNTIME-PATH*''' : [string] Path to Nyquist .lsp files.
  
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.
+
* '''*PROJECT*''' : A variable with a list of properties relating to the current Audacity project.
  
Examples how to use the text input widget can be found in the source code of the Apropos Plug-in.
+
* '''S''' (obsolete) : [sound or array of two sounds] Prior to version 4 plug-ins, in [[#type_process|process]] and [[#type_analyze|analyze]] type plug-ins this was the Audacity sound [the selected part of the Audacity audio track]. In [[#type_generate|generate]] type plug-ins "S" is the [http://www.cs.cmu.edu/~rbd/doc/nyquist/part11.html Adagio notation] for a ''quarter note'' (float value 0.25).
  
 +
* '''[http://www.cs.cmu.edu/~rbd/doc/nyquist/part2.html#index53 S]''' : [http://www.cs.cmu.edu/~rbd/doc/nyquist/part11.html Adagio notation]. [float] A ''quarter note'' (float value 0.25).
  
=== Multiple-Choice Widget ===
+
* '''[[Nyquist_*SCRATCH*_Tutorial|*SCRATCH*]]''' : [any] a symbol whose value and property list are preserved from one effect invocation to the next.
 +
:For more information. see the [[Nyquist_*SCRATCH*_Tutorial|*SCRATCH* tutorial]].
  
[[Image:choice-widget.png]]
+
* '''*SELECTION*''' : A variable with a list of properties relating to the current selection.
  
The multiple choice input widget is supported in plug-ins version 3 or above.  
+
* '''[http://www.cs.cmu.edu/~rbd/doc/nyquist/part9.html#index868 *SOUND-SRATE*]''' : [float] The sample frequency of the selected track audio.
  
  ;control <i>variable-name</i> "<i>text-left</i>" choice "<i>string-1,string-2,...</i>" <i>initial-value</i>
+
* '''*SYSTEM-DIR*''' : A variable with a list of properties relating to the file system.
  
* ''variable-name'' - a Lisp symbol.
+
* '''*SYSTEM-TIME*''' : A variable with a list of properties relating to the system time/date.
  
* ''text-left'' - text that will appear to the left of the multiple-choice list.
+
* '''*TRACK*''' : [sound or array of sounds] 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.
  
* ''string-1,...'' - for every string an entry in a list to choose from will be produced.
+
* '''[http://www.cs.cmu.edu/~rbd/doc/nyquist/part4.html#index144 *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.
  
* ''initial-value'' - the number of the list entry that will be displayed as the default choice at the first start of the plug-in.
+
{{Hint|1= Other global variables provided by Nyquist can be found in the [http://www.cs.cmu.edu/~rbd/doc/nyquist/indx.html Nyquist manual index].}}
  
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.
+
<div id="property_lists"></div>
  
== Nyquist Variables ==
+
== Global Property Lists ==
 +
Property lists are defined for the global variables *AUDACITY*, *PROJECT*, *SELECTION*, *SYSTEM-DIR*, *SYSTEM-TIME*, and *TRACK*.
 +
{{advice|For examples using property lists, see the [[Nyquist Property List Tutorial]].}}
  
The variables given from Audacity to Nyquist are defined in the file "audacity/lib-src/libnyquist/nyx/nyx.c" in the Audacity source code.
+
<div id="audacity"></div>
 +
=== *AUDACITY* ===
 +
This property list was added in Audacity version 2.1.0
  
The following variables are given from Audacity to Nyquist:
+
'''Value:''' Unbound (not defined).
 +
* '''LANGUAGE''' : [string] The country code for the language set in [http://manual.audacityteam.org/man/interface_preferences.html#display Audacity Preferences].
 +
:  Example - when Audacity's locale setting is for English, {{InlineCode|1=(print (get '*audacity* 'language))}} will print {{InlineCode|1=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
  
* '''*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.
+
<div id="project"></div>
 +
=== *PROJECT* ===
 +
'''Value:''' Unbound (not defined).
  
* '''*SYSTEM-DIR*''' (version 4) - A variable with a list of properties relating to the file system.
+
*'''LABELTRACKS''' : [integer] The number of label tracks in the project.
 
+
*'''MIDITRACKS''' : [integer] The number of note tracks in the project.
* '''*SYSTEM-TIME*''' (version 4) - A variable with a list of properties relating to the system time/date.
+
*'''NAME''' : [string] The name of the current project. A project that has not been named (not yet saved) returns an empty string.
 +
*'''PREVIEW-DURATION''' : [float] The [https://manual.audacityteam.org/man/playback_preferences.html Effects Preview Length] set in Audacity preferences.
 +
*'''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.
  
* '''*PROJECT*''' (version 4) - A variable with a list of properties relating to the current Audacity project.
+
<div id="selection"></div>
 
 
* '''*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 [[#type_process|process]] and [[#type_analyze|analyze]] type plug-ins this is the Audacity sound [the selected part of the Audacity audio track]. In [[#type_generate|generate]] type plug-ins "S" is the [http://www.cs.cmu.edu/~rbd/doc/nyquist/part11.html Adagio notation] for a ''quarter note'' (float value 0.25).
 
* '''S''' (version 4) - [http://www.cs.cmu.edu/~rbd/doc/nyquist/part11.html 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 [http://www.cs.cmu.edu/~rbd/doc/nyquist/part8.html#index389 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.
 
 
 
{{Hint|1= Other global variables provided by Nyquist can be found in the [http://www.cs.cmu.edu/~rbd/doc/nyquist/ Nyquist manual].}}
 
 
 
 
 
For [[#type_process|process]] and [[#analyze|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''
 
 
 
{{Hint|1='''NOTE''': <p>'''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 [[#type_process|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.</p><p>
 
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 [[#type_generate|generate]] type effect will produce a tone of duration 3.5 seconds.</p>}}
 
 
 
For [[#generate|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 [[#.2ASELECTION.2A|*SELECTION*]] '''START''' and '''END''' properties may be used ([[#version 4|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.1.0 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|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" or NIL.
 
{{Note|This 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.}}
 
*'''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* ===
 
=== *SELECTION* ===
'''Value:''' Unbound.
+
'''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 [https://manual.audacityteam.org/man/glossary.html#rms 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 [https://en.wikipedia.org/wiki/NaN 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.
 
*'''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.
 
*'''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.
 
  
 +
<div id="system-dir"></div>
 
=== *SYSTEM-DIR* ===
 
=== *SYSTEM-DIR* ===
'''Value:''' Unbound.
+
'''Value:''' Unbound (not defined).
  
 
*'''BASE''' : [string] The Audacity installation directory.
 
*'''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.
 
*'''DATA''' : [string] The Audacity data directory. This is where the audacity.cfg, plug-inregistry.cfg and EQCurves.xml files are located.
 +
*'''DOCUMENTS''' [string] The system default documents directory.
 
*'''HELP''' : [string] The installation directory for the Audacity Manual (note that the Manual may not exist).
 
*'''HELP''' : [string] The installation directory for the Audacity Manual (note that the Manual may not exist).
 +
*'''HOME''' : [string] The current user's "[https://en.wikipedia.org/wiki/Home_directory home]" directory.
 +
*'''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.
 +
*'''SYS-TEMP''' : [string] The system temp directory.
 
*'''TEMP''' : [string] The Audacity temp directory. This is where unsaved project data is temporarily stored.
 
*'''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.
+
*'''USER-PLUG-IN''' : [string] The default path for user plug-ins.
 +
 
 +
<div id="system-time"></div>
  
 
=== *SYSTEM-TIME* ===
 
=== *SYSTEM-TIME* ===
Line 520: Line 305:
  
 
* '''DATE''' : [string] The date formatted according to the current locale. Example: "dd/mm/yy".
 
* '''DATE''' : [string] The date formatted according to the current locale. Example: "dd/mm/yy".
* '''TIME''' : [string] The time formatted according to the current locale. Example: "hh:mm:ss".
+
* '''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-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".
 
* '''ISO-TIME''' : [string] The time represented in the ISO 8601 format "HH:MM:SS".
* '''YEAR''' : [integer] The year (as an integer).
 
* '''DAY''' : [integer] Day of the month.
 
 
* '''MONTH''' : [integer] The month (as an integer).
 
* '''MONTH''' : [integer] The month (as an integer).
 
* '''MONTH-NAME''' : [string] The name of the month (Example: "January").
 
* '''MONTH-NAME''' : [string] The name of the month (Example: "January").
* '''DAY-NAME''' : [string] The name of the day (Example: "Monday").
+
* '''TIME''' : [string] The time formatted according to the current locale. Example: "hh:mm:ss".
 +
* '''YEAR''' : [integer] The year (as an integer).
  
== The *SCRATCH* Symbol ==
+
<div id="track"></div>
(version 3 or above - Audacity 1.3.9 or later)
+
=== *TRACK* ===
 +
'''Value:''' The ''sound'' from a selected mono audio track, or an array of two sounds from a selected stereo track (see the [[Nyquist_Stereo_Track_Tutorial|Nyquist Stereo Track Tutorial]]).
  
'''*SCRATCH*''' is a global symbol, which is not deleted in-between plug-in runs.
+
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).
  
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.
+
*'''CHANNELS''' : [integer] The number of channels in the track (mono = 1, stereo = 2).
 +
*'''CLIPS''' : [list or array] For mono tracks, a list of start and end time of each audio clip. For stereo tracks, an array containing a list of clips for each channel.
 +
{{note|1=Due to a limitation in Nyquist, the "clips" property can hold a maximum of 1000 start / end times.
 +
: If an audio channel contains more than 1000 clips, the first 1000 will be listed, and the 1001th item will be NIL.
 +
: See [https://manual.audacityteam.org/man/nyquist_macros.html#AUD-GET-INFO AUD-GET-INFO] for an alternative way to get clip times that will work with 1000's of clips.}}
 +
*'''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 [https://manual.audacityteam.org/man/spectrograms_preferences.html#Enable_Spectral_Selection 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 or list] The track view. Only applies to audio tracks.
 +
:* A single track view returns one of "Waveform", "Spectrogram" or NIL. [https://manual.audacityteam.org/man/multi_view.html Multi-View] returns a list of strings or NIL.
 +
:* Multi-view returns the upper view as the first element, and the lower view as the second (either "Waveform" or "Spectrogram"). Both normal "Waveform" and "Waveform (dB)" return the string "Waveform".
 +
:*Prior to Audacity 2.4.x : [string] One of: "Waveform", "Waveform (dB)", "Spectrogram" or NIL.
 +
{{Note|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.}}
  
To pass data from plug-in "effectX-partA" to "effectX-partB":
+
== Return Values ==
  
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). ]
+
Nyquist supports many ''"data types''", including "numbers" (integer or floating-point), "characters" (such as the letter "A", the number "4", or any other [https://en.wikipedia.org/wiki/ASCII ASCII character]), "strings" (text), "[https://en.wikipedia.org/wiki/List_(abstract_data_type) list]" (a list of data), "[https://en.wikipedia.org/wiki/Array_data_type array]" (special kind of indexed list), and "sounds" (a sound / digital signal).
  
2. "effectX-partA" should delete any old property value:
+
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:
  
  exec remprop(quote(*SCRATCH*), quote(effectx)) ;; in SAL
+
===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.
  
  (remprop '*SCRATCH* 'effectx) ;; in LISP
+
===Multi-Channel / Stereo Sound===
 +
Nyquist handles multi-channel sounds as an ''array'' of ''sounds''. The first element of the array is the left channel, and the second element is the right channel. Audacity currently supports a maximum of two channels in a track (stereo).
 +
{{advice|1=Returning an array of sounds to a mono track is an error.
 +
:''To return a stereo sound without error, a stereo track must be selected before running the Nyquist code.''}}
 +
{{note|1=For more information about stereo tracks, see the [[Nyquist Stereo Track Tutorial]].}}
  
3. "effectX-partA" should compute a new property value '''v''' and save it:
+
===String / Text===
 +
When the return value is a ''character'' or ''string'', a dialog window will appear with the data displayed as text.
  
  exec putprop(quote(*SCRATCH*), v, quote(effectx)) ;; in SAL
+
===Number===
 +
A dialog window will appear with the number displayed as text.
  
  (putprop '*SCRATCH* v 'effectx) ;; in LISP
+
===Labels===  
 
+
If an appropriately formatted list is returned to Audacity, a label track will be created below the audio track(s).
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:
 
For point labels the format is:
Line 636: Line 371:
 
* "string" - a string to be displayed in the label's text field.
 
* "string" - a string to be displayed in the label's text field.
  
For region labels (Audacity 1.3) each label list must contain two <i>int-or-float</i> elements, one for the start and one for the end of the label region.
+
For region labels, each label list must contain two <i>int-or-float</i> elements, one for the start and one for the end of the label region.
 
   ((''number'' ''number'' "''string''") (''number'' ''number'' "''string''") ... )
 
   ((''number'' ''number'' "''string''") (''number'' ''number'' "''string''") ... )
{{Hint|1=Audacity will always place returned audio or labels relative to the start of the [http://manual.audacityteam.org/man/Audacity_Selection selection] and not the start of the [http://manual.audacityteam.org/man/Timeline Timeline].}}
+
{{Hint|1=Audacity will always place returned audio or labels relative to the start of the [https://manual.audacityteam.org/man/Audacity_Selection selection] and not the start of the [https://manual.audacityteam.org/man/Timeline Timeline].}}
  
== Math Functions ==
+
===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.
 +
<pre>;; Example: Apply a function "process" to
 +
;; the first selected track only.
  
n-th power of x:
+
(if (= (get '*track* 'index) 1)
 +
    (process *track*)
 +
    "")</pre>
  
  power(x, n) ;; in SAL
 
  (power x n) ;; in LISP
 
 
 
n-th root of a number:
 
  
  power(x, 1.0 / n) ;; in SAL
+
<div id="play"></div>
  (power x (/ 1.0 n)) ;; in LISP
 
  
n-th root of a sound s:
+
== Playing sounds with Nyquist ==
  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:
+
When using the [https://manual.audacityteam.org/man/nyquist_prompt.html Nyquist Prompt] or (most) Nyquist plug-ins that have a [https://en.wikipedia.org/wiki/Graphical_user_interface GUI], if the plug-in returns a sound, it may be previewed using the {{button|Preview}} button. In addition to this, it is also possible to play sounds directly from Nyquist, using the [http://www.cs.cmu.edu/~rbd/doc/nyquist/part8.html#index626 PLAY] function. The PLAY function will be executed when the plug-in code runs.
  return s-exp(s-log(x) * s-recip(n))  ;; in SAL
+
{{advice|The PLAY function is described in the [http://www.cs.cmu.edu/~rbd/doc/nyquist/part8.html#index626 Nyquist manual]. The information here describes aspects that are specific to Nyquist in Audacity.}}
  (s-exp (mult (s-log x) (s-recip n))) ;; in LISP
+
Note that the Nyquist PLAY command does not use Audacity's [http://manual.audacityteam.org/man/devices_preferences.html 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 [http://www.cs.cmu.edu/~rbd/doc/nyquist/part8.html#index340 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 {{button|Debug}} button to see the output.
 +
  (setf *snd-list-devices* t)
 +
  (play *track*)
  
== Nyquist Workbench ==
+
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*)
 +
{{alert|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):
 +
<pre>(play (extract-abs 0 1 *track*))</pre>
  
The Nyquist Workbench gives the ability to run arbitrary Nyquist code in Audacity from a graphical IDE. When enabled, Nyquist Workbench can be found at the bottom of the View Menu.  
+
Note also that if a plug-in uses Nyquist PLAY command, using {{button|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 {{button|Preview}} button should normally be [[#preview|disabled]] if Nyquist PLAY is used.
  
[[Image:nyquist-workbench.png]]
 
  
 +
== Plug-in Translations ==
 +
{{intro|Nyquist plug-ins provide two mechanisms for translation into the language specified in [https://manual.audacityteam.org/man/interface_preferences.html Audacity preferences].
  
The Nyquist Workbench is an Audacity [http://wiki.audacityteam.org/wiki/Experimental_Modules experimental module] though at one time it was available as standalone source code.  
+
One method is exclusively for plug-ins that are shipped by default with Audacity and requires compiling Audacity from source, plus several other steps involving [https://www.gnu.org/software/gettext/ gettext]. Unfortunately this method is not documented, so only a brief description is provided here.
  
<div id="download_workbench"></div> 
+
The other method may be used by plug-in developers for their "third party" plug-ins, but can be used only for returned strings and not for the main plug-in interface.}}
=== Ready built module for Windows and Mac OS X ===
 
For the [http://audacityteam.org/download/ Audacity 2.1.2 release], you can download a ready-built Nyquist workbench module as follows:
 
*[[media:Nyquist_Workbench_for_Audacity_2.1.2_on_Windows.zip|mod-nyq-bench.dll for Windows]]
 
  
*[[media:Nyquist_Workbench_for_Audacity_2.1.2_on_Mac.zip|mod-nyq-bench.so for Mac OS X]]
+
=== Translation for shipped effects ===
Place the extracted "modules" folder containing the mod-nyq-bench file into the folder where Audacity is installed. Then enable the module in [http://manual.audacityteam.org/o/man/modules_preferences.html Modules Preferences] and restart Audacity.  
+
Header comments in translated plug-ins begin with a dollar "$" character rather than the usual semicolon ";" character. The strings to be translated are then wrapped in a function that has a one character name "_" (underscore).
  
<div id="compile_workbench"></div>
+
'''Example:'''
=== Compiling Nyquist Workbench ===
+
In the [https://manual.audacityteam.org/man/adjustable_fade.html Adjustable Fade] effect, the [[#name|Name]] header is changed from:
For GNU/Linux (and for the other platforms if you are compiling the latest Audacity code), 
+
  ;name "Adjustable Fade"
Nyquist Workbench is included in the Audacity HEAD [https://github.com/audacity/audacity source code] at \lib-src\mod-nyq-bench. Follow the steps below for your operating system to compile Audacity and then compile Nyquist Workbench.
+
to:
{{advice|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.}}
+
  $name (_ "Adjustable Fade")
  
==== Windows ====
+
''';control''' lines become '''$control'''.
 +
As with other translated headers, the '''$''' symbol replaces the normal semicolon. The line is ignored by Nyquist as a ''comment'', but is visible to Audacity for translation and for creating a [[#widgets|widget]].
  
<ol>
+
The options in [[Nyquist_Plug-ins_Widgets#Multiple-Choice_Widget|Multiple-choice widgets]] may be translated. For example:
<li> If this is your first time compiling Audacity, read the introductory yellow panel at the top of [[Developing On Windows]] so as to install the correct version of Microsoft Visual Studio.  
+
  ;control var (_ "Translated left text") choice ((_ "Yes") (_ "No")) 0
<li> Build Audacity according to [https://github.com/audacity/audacity/blob/master/win/compile.txt win/compile.txt] in the source code. If you are reopening Visual Studio to build Nyquist Workbench, open "audacity.sln" and choose "Debug" or "Release" configuration according to which configuration of Audacity you already built.
+
{{alert|The above example is not safe to use. See the "Limitations" section below.}}
<li> In the "Solution Explorer" panel, right-click '''Solution 'audacity''''.
 
<li> Choose {{menu|Add > Existing Project...}}, browse to the \lib-src\mod-nyq-bench folder then select and open <span style="white-space: nowrap;"> '''mod-nyq-bench.vcxproj'''.</span>
 
<li> Right-click the new '''mod-nyq-bench''' entry in the Solution Explorer tree and choose "Build".
 
<li> After building, a post-build event copies the compiled "mod-nyq-bench.dll" file to <span style="white-space: nowrap;">{{path|\win\Debug\modules}}</span> or <span style="white-space: nowrap;">{{path|\win\Release\modules}} as appropriate.</span>
 
<li> Next time you build Audacity, mod-nyq-bench should be rebuilt automatically. 
 
</ol>
 
  
==== Mac OS X ====
 
  
Follow /mac/Build.txt to patch and build wxWidgets.  
+
'''Macros and portability:'''
 +
To allow portability of settings and macros, choices may include a non-translated form of each choice. The non-translated form is used by Macros but is not normally visible to users.
 +
  ;control var (_ "Translated left text") choice (("Label1" (_ "Translated Label 1")) ("Label2" (_ "Translated Label 2"))) 0
  
Using '''xcodebuild''', the steps below assume you will build Release configuration of Audacity but you can build Debug configuration instead by replacing "Release" with "Debug" in the steps.
 
<ol><li>Clone or unzip the [https://github.com/audacity/audacity Audacity sources at GitHub].
 
<li>Change into the "mac" directory in the Audacity sources. For example if you unzipped the sources the command might be:
 
{{code|cd /Users/joe/Downloads/audacity-master/mac}}<br>
 
<li>Run the installation scripts to build Audacity and install it to /private/tmp/Audacity.dst/Audacity: 
 
{{code|xcodebuild -configuration Release install}} <br>
 
<li>Build mod-nyq-bench.so and install it at /private/tmp/Audacity.dst/Audacity/modules 
 
{{code|xcodebuild -configuration Release install -target mod-nyq-bench}}<br>
 
<li>Launch Audacity, enable mod-nyq-bench in [http://manual.audacityteam.org/o/man/modules_preferences.html Modules Preferences] then restart Audacity. 
 
</ol>
 
  
If you use the '''Xcode IDE''', build Audacity by selecting "Audacity - Release" or "Audacity - Debug" from the Toolbar or {{menu|Product > Scheme}} menu. Then from the same toolbar or menu, select "Nyquist Workbench Module - Release" or "Nyquist Workbench Module - Debug" according to which configuration of Audacity you built, then build the module.
+
'''Other user visible strings:'''
 +
Other strings that are visible to users are marked for translation using the "underscore" function. An example from the Adjustable Fade plug-in:
 +
  (format nil (_ "~aPercentage values cannot be negative.") err)
  
==== GNU/Linux ====
 
{{ednote|1='''Gale 26May15:''' [[ToDo-2]] Placeholder to adjust step 6 if [http://bugzilla.audacityteam.org/show_bug.cgi?id=978 Bug 978] is fixed.}}
 
  
<ol>
+
====Limitations:====
<li>Type "./configure " in the top level of the directory containing the Audacity source code:
+
Control characters like '''\n''' (new line), '''\t''' (tab) are not supported. The workaround is to use Lisp format directives instead:
{{code|./configure}}
+
*'''Bad''' (does not work correctly):
<p></p>
+
  (print (_ "Line one.\nLine two."))
<li> If configure completes successfully, type:
+
*'''Good''':
{{code|make}}
+
   (print (format nil (_ "Line one.~%Line two.")))
If you are having problems at either of the above steps, try the [[CompilingAudacityForBeginners|Compiling Audacity Step by Step Guide]]. 
 
<li>If 'make' completes successfully, type:
 
{{code|sudo make install}}
 
which by default installs Audacity to "/usr/local/share/audacity".
 
<li> Change to the mod-nyq-bench directory in lib-src:  
 
{{code|cd lib-src/mod-nyq-bench}}
 
<p></p>
 
<li>Compile Nyquist Workbench. In the mod-nyq-bench directory, type:
 
{{code|make}}
 
After "make" has finished, mod-nyq-bench.so will be in the ".libs" directory inside the mod-nyq-bench directory.
 
<li>The sudo make install command installs the mod-nyq-bench libs at /usr/local/lib/mod-nyq-bench, but Audacity currently does not see them there. As a workaround, use the following command to copy the mod-nyq-bench libs into /usr/local/share/audacity/modules:   
 
{{code|sudo cp -r .libs /usr/local/share/audacity/modules}}</ol>
 
<ul><ul><li><p>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:</p>
 
{{code|mkdir -p ~/.audacity-files/modules}}
 
<p>then copy the entire contents of the ".libs" folder into that "modules" directory. Audacity will find it there irrespective of the location of the Audacity installation directory.</p></ul></ul>
 
  
===Loading/Enabling mod-nyq-bench===
+
Note that translations may contain Unicode characters that are not supported by Nyquist. It is therefore important that any translated strings that need to be ''machine readable'' (such as Multiple-Choice widget options) '''''should''''' also have a non-translated form.
After first building mod-nyq-bench you will need to launch Audacity then enable mod-nyq-bench in Modules Preferences. Set the control for mod-nyq-bench to "Enable" and restart Audacity then the "Nyquist Workbench" item will be visible at the bottom of View Menu.
+
  ;control var (_ "Translated left text") choice (("Label1" (_ "Translated Label 1")) ("Label2" (_ "Translated Label 2"))) 0
  
Note that if you build some earlier versions of Audacity than HEAD, for example the 2.1.0 release tarball, there are no Modules Preferences. 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.
+
=== Translation for third party effects ===
  
===Rebuilding Audacity and Nyquist Workbench===
+
{{advice|It is not currently possible to provide translations for a third party plug-in's main interface, unless the name is the same as a translated Nyquist plug-in that is already shipped with Audacity. It is highly recommended to NOT reuse the same name as a shipped plug-in for a third party plug-in.}}
When you update your Audacity source code tree and rebuild Audacity on a subsequent day, you must also rebuild mod-nyq-bench. This happens automatically on Windows if you add mod-nyq-bench to the Audacity solution as described [[#Windows|above]]. On Mac OS X and GNU/Linux:
 
* 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"&nbsp;'' 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"&nbsp;'' before rebuilding the module.
 
  
== Nyquist Apropos Plug-in ==
+
Translations may be provided for return value messages and debug messages. To do this, the string must be marked for translation by wrapping it in the "underscore" function. The translation must also be provided in a specially formatted list variable '''*locale*'''.
  
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.
+
The format for the *locale* list is: {{InlineCode|1=(LIST (language-list) [(language-list) ...]) }}
  
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].
+
where "language-list" is a list in the form: {{inlineCode|1=(LIST country-code (translations)) }}
  
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 {{Menu|Generate}} menu, then open {{Menu|Effect > Nyquist Prompt...}} [doesn't work without a selected audio track] and copy the following line into the "Nyquist Prompt" text input field:
+
and the "translations" are list in the form: {{inlineCode|1=(LIST (List "string" "translation") [(List "string" "translation")...])  }}
  
  (print (fboundp 'snd-abs))
+
* The *locale* list may contain any number of "language-list" elements, where each language-list is a list of two strings.
 +
* The first element of each "language-list" is the country code (for example "en" or "fr"),
 +
* The second item of each "language-list" is a list of translation pairs.
 +
* A "translation pair" is a list containing the default string (usually in English) and the translated string (in the language specified by the country code).
  
Important: now please click "Debug" instead of the "OK" button.
+
A working example may be found in the [https://github.com/audacity/audacity/blob/master/plug-ins/rms.ny RMS effect].
  
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:
+
== See Also ==
 
+
*[https://manual.audacityteam.org/man/nyquist.html Nyquist] in the Audacity manual
* T - meaning "true", function is implemented
+
*[[:Category:Digital Audio Technology|Digital Audio Technology]]
 
+
*[[Nyquist Audio Programming]] - "How to" and other explanatory articles
* NIL - meaning "false", function is not implemented
+
*[http://www.cs.cmu.edu/~rbd/doc/nyquist/ Nyquist 3.02 Reference Manual]
 
+
*[http://www.audacity-forum.de/download/edgar/nyquist/nyquist-doc/xlisp/xlisp-index.htm XLISP 2.0 Manual]
I had typed this so often in the past that I have written an Audacity Nyquist "Apropos" Plug-in:
 
 
 
'''Download''':  [http://www.audacity-forum.de/download/edgar/nyquist/nyquist-doc/devel/apropos/apropos.ny 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 {{Menu|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":
 
 
 
[[Image:appropos-window.png]]
 
 
 
Note: with no search pattern [empty field], the plug-in matches all symbol names.
 
 
 
{{Hint|'''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:
 
 
 
[[Image:appropos-message.png]]
 
 
 
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:
 
 
 
[[Image:appropos-output.png]]
 
 
 
== Bugs ==
 
Details of current bugs that affect Nyquist in Audacity are listed on [http://bugzilla.audacityteam.org/buglist.cgi?keywords=nyquist&resolution=--- Bugzilla].
 
  
  
[[Category:Digital Audio Technology]] [[Category:Nyquist]]
+
[[Nyquist|'''|<''' Nyquist]]
 +
[[Category:Digital Audio Technology]] [[Category:Nyquist]] [[Category:Nyquist:Reference]]

Latest revision as of 11:52, 8 July 2022

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. Tracks and Selections
  5. Global and Reserved Variables
  6. Global Property Lists
  7. Return Values
  8. Playing sounds with Nyquist
  9. Plug-in Translations
  10. 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 is in many ways a separate program from Audacity (and is also available as a standalone programming language). Nyquist is embedded in Audacity as a software library that may be called from the main Audacity application to provide additional functionality, most notably as "plug-ins".

When a Nyquist plug-in is selected from one of Audacity's menus, Audacity locates the plug-in script (the ".NY" file), starts a Nyquist session and passes the Nyquist code to be interpreted by the Nyquist library. Nyquist then attempts to run the program. The result of running the Nyquist script is returned to Audacity.

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 Example

In this example (derived from the High-Pass Filter effect), the first four lines make up the essential headers that are required in all Nyquist plug-ins.

  • ;nyquist plug-in : This header tells Audacity that this file is a Nyquist plug-in.
  • ;version 4 : This header specifies that this is a "4th generation" plug-in.
  • ;type process : This header defines the plug-in as a "process" (Effect) type.
  • ;name "High-Pass Filter" : This header tells Audacity the name of the plug-in.
;nyquist plug-in
;version 4
;type process
;name "High-Pass Filter"
;preview linear
;manpage "High-Pass_Filter"
;debugbutton disabled
;author "Dominic Mazzoni"
;release 3.0.2
;copyright "Released under terms of the GNU General Public License version 2 or later."

;control frequency "Frequency (Hz)" float-text "" 1000 0 nil

The other headers enable various options and properties, including the plug-in's controls.

Warning icon Full descriptions of all plug-in headers are provide on the Nyquist Plug-in Headers page.

Nyquist Plug-in Widgets

Nyquist plug-ins support a range of "widgets", which are control elements for a graphical user interface (GUI). These elements are unique to Nyquist in Audacity.
The GUI is created by Audacity when a plug-in contains one or more widget header commands.

As with other plug-in headers, they begin with a semicolon (;) and are ignored by Nyquist, except that the variable name of the widget is initialized with a value and made available to Nyquist. This means that Nyquist can access the value that has been set in the widget as the value of the variable specified in the widget header.

The "Text widget" is an exception to the above at it is for display purposes only and does not set a value.

Each widget begins with ";control", and is followed by a number of parameters, one of which defines the type of widget. There are currently nine widget types, though not all of them are available for old versions of Audacity.

When a plug-in is launched, Audacity searches the plug-in .NY file for valid headers. Every ";control" line that is found gets parsed by Audacity into several tokens, where each token is separated by spaces. If the tokens match one of the defined patterns, then Audacity adds the widget to the GUI, otherwise they are ignored.

Syntax for widgets
;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 / NIL integer / NIL
;control symbol string float-text string float float / NIL float / NIL
;control symbol string string string string - -
;control symbol string choice string integer - -
;control symbol string time string float float / NIL float / NIL
;control symbol string file string string string string
;control - - text string - - -


"real" (deprecated) is an alternative name for "float" and is provided as legacy support for old plug-ins. It should not be used in new code.

Italic words in the table denote data types. Because tokens are separated by whitepace, strings containing whitespace must be written within quotation marks.

This image displays all nine widget types in Audacity 2.3.1 on Windows 10

Nyquist-plug-in-widgets.png


Older versions of Audacity may not support all of these controls, which may lead to an "unbound symbol" error. Plug-in users are encouraged to use the current version of Audacity, to ensure that they can benefit from all of the latest features.

The following code may be run in the Nyquist Prompt of Audacity 2.3.1 or later, and produces the GUI shown above:

 ;version 4
 ;name "Plug-in Widgets"
 
 ;control filename "File Button widget" file "" "" "" "open"
 ;control number-sw "Slider widget" float "(float)" 50 0 100
 ;control integer-sw "Slider widget" int "(integer)" 50 0 100
 ;control number-nt "Numeric Text widget" float-text "(float)" 50 0 100
 ;control integer-nt "Numeric Text widget" int-text "(integer)" 50 0 100
 ;control string-var "String widget" string "text right" "default string"
 ;control text "Text widget [string]"
 ;control duration "Time widget" time "text right" 30 nil nil
 
 (format nil
         "File Selected: ~s~%~
         Floating point slider: ~s~%~
         Integer slider: ~s~%~
         Floating point text: ~s~%~
         Integer text: ~s~%~
         String: ~s~%~
         (Text widget does not return a value)~%~
         Duration: ~s (seconds)"
         filename
         number-sw
         integer-sw
         number-nt
         integer-nt
         string-var
         duration)

The detailed syntax for each widget type is described on the Nyquist Plug-ins Widgets page.


Tracks and Selections

Audacity passes information about the current Audacity session to the Nyquist interpreter, along with the Nyquist code. Typically, when the code runs, it acts on data that has been passed from Audacity, which often includes the selected audio data, and returns data back to Audacity. Here we shall look at the ways that audio data is passed from Audacity to Nyquist, and from Nyquist back to Audacity.

Passing Selected Audio to Nyquist

For process and analyze type plug-ins, Nyquist runs the plug-in code on each selected track in turn. The audio data is passed from Audacity to Nyquist as a variable called *TRACK* (the asterisks are part of the name).

  • For mono tracks, the value of *TRACK* is a "sound" (which is a Nyquist data type).
  • For stereo tracks, the value of *TRACK* is an "array". An array is a special kind of ordered list. The array has two elements, both of which are "sounds". The first element holds audio data from the left channel, and the second element hold data from the right channel.

The selected audio is only available to "process" and "analyze" type plug-ins (including the compound types "tool process" and "tool analyze").

Time and Durations

The way that time and durations are handled depends on the type of plug-in.

For process and analyze type plug-ins, the start time of the selection is seen as "time = 0", and the length of the selection is seen as one unit of time. The absolute 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).

When generating sounds with a 'generate' type plug-in, durations in Nyquist represent seconds. For example, to generate a 2.5 second sine tone, you could write:

;type generate
(osc 60 2.5)

but if the same code is used in a 'process' type plug-in, the generated tone will be 2.5 x the duration of the track selection:

;type process
(osc 60 2.5)

If a duration in seconds is required in a 'process' type plug-in, this may be done using the ABS-ENV command:

;type process
(abs-env (osc 60 2.5))

The above examples may be run in the Nyquist Prompt.

Global Variables and Reserved Variable Names

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. Listed here are a few common standard Nyquist globals, and global variables that are relevant to Nyquist in Audacity.
  • *DECIMAL-SEPARATOR* : [char] A comma character (#\') or dot character (#\.) depending on the language selected in Audacity's Preferences.
  • *FILE-SEPARATOR* : [char] The character that separates directories in a path, e.g. "/" (#\/) for Unix, ":" (#\:) for Mac, and "\" (#\\) for Win32.
  • LEN : [int] The number of samples contained in the selected Audacity sound.
  • *PREVIEWP* : [bool] True when previewing an effect, otherwise false.
  • *RUNTIME-PATH* : [string] Path to Nyquist .lsp files.
  • *PROJECT* : A variable with a list of properties relating to the current Audacity project.
  • S (obsolete) : [sound or array of two sounds] 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).
  • *SCRATCH* : [any] a symbol whose value and property list are preserved from one effect invocation to the next.
For more information. see the *SCRATCH* tutorial.
  • *SELECTION* : A variable with a list of properties relating to the current selection.
  • *SOUND-SRATE* : [float] The sample frequency of the selected track audio.
  • *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.
  • *TRACK* : [sound or array of sounds] 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.
  • *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.


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


Global Property Lists

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

Warning icon For examples 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.
  • PREVIEW-DURATION : [float] The Effects Preview Length set in Audacity preferences.
  • 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.
  • DOCUMENTS [string] The system default documents directory.
  • HELP : [string] The installation directory for the Audacity Manual (note that the Manual may not exist).
  • HOME : [string] The current user's "home" directory.
  • 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.
  • SYS-TEMP : [string] The system temp directory.
  • TEMP : [string] The Audacity temp directory. This is where unsaved project data is temporarily stored.
  • USER-PLUG-IN : [string] The default path for user plug-ins.

*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 2022 would be the list: 2022, 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 the Nyquist Stereo Track Tutorial).

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 start and end time of each audio clip. For stereo tracks, an array containing a list of clips for each channel.
Due to a limitation in Nyquist, the "clips" property can hold a maximum of 1000 start / end times.
If an audio channel contains more than 1000 clips, the first 1000 will be listed, and the 1001th item will be NIL.
See AUD-GET-INFO for an alternative way to get clip times that will work with 1000's of clips.
  • 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 or list] The track view. Only applies to audio tracks.
  • A single track view returns one of "Waveform", "Spectrogram" or NIL. Multi-View returns a list of strings or NIL.
  • Multi-view returns the upper view as the first element, and the lower view as the second (either "Waveform" or "Spectrogram"). Both normal "Waveform" and "Waveform (dB)" return the string "Waveform".
  • Prior to Audacity 2.4.x : [string] 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.

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. The first element of the array is the left channel, and the second element is the right channel. Audacity currently supports a maximum of two channels in a track (stereo).

Warning icon Returning an array of sounds to a mono track is an error.
To return a stereo sound without error, a stereo track must be selected before running the Nyquist code.
For more information about stereo tracks, see the Nyquist Stereo Track Tutorial.

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.


Plug-in Translations

Nyquist plug-ins provide two mechanisms for translation into the language specified in Audacity preferences.

One method is exclusively for plug-ins that are shipped by default with Audacity and requires compiling Audacity from source, plus several other steps involving gettext. Unfortunately this method is not documented, so only a brief description is provided here.

The other method may be used by plug-in developers for their "third party" plug-ins, but can be used only for returned strings and not for the main plug-in interface.

Translation for shipped effects

Header comments in translated plug-ins begin with a dollar "$" character rather than the usual semicolon ";" character. The strings to be translated are then wrapped in a function that has a one character name "_" (underscore).

Example: In the Adjustable Fade effect, the Name header is changed from:

 ;name "Adjustable Fade"

to:

 $name (_ "Adjustable Fade")

;control lines become $control. As with other translated headers, the $ symbol replaces the normal semicolon. The line is ignored by Nyquist as a comment, but is visible to Audacity for translation and for creating a widget.

The options in Multiple-choice widgets may be translated. For example:

 ;control var (_ "Translated left text") choice ((_ "Yes") (_ "No")) 0
Warning icon The above example is not safe to use. See the "Limitations" section below.


Macros and portability: To allow portability of settings and macros, choices may include a non-translated form of each choice. The non-translated form is used by Macros but is not normally visible to users.

 ;control var (_ "Translated left text") choice (("Label1" (_ "Translated Label 1")) ("Label2" (_ "Translated Label 2"))) 0


Other user visible strings: Other strings that are visible to users are marked for translation using the "underscore" function. An example from the Adjustable Fade plug-in:

 (format nil (_ "~aPercentage values cannot be negative.") err)


Limitations:

Control characters like \n (new line), \t (tab) are not supported. The workaround is to use Lisp format directives instead:

  • Bad (does not work correctly):
 (print (_ "Line one.\nLine two."))
  • Good:
 (print (format nil (_ "Line one.~%Line two.")))

Note that translations may contain Unicode characters that are not supported by Nyquist. It is therefore important that any translated strings that need to be machine readable (such as Multiple-Choice widget options) should also have a non-translated form.

 ;control var (_ "Translated left text") choice (("Label1" (_ "Translated Label 1")) ("Label2" (_ "Translated Label 2"))) 0

Translation for third party effects

Warning icon It is not currently possible to provide translations for a third party plug-in's main interface, unless the name is the same as a translated Nyquist plug-in that is already shipped with Audacity. It is highly recommended to NOT reuse the same name as a shipped plug-in for a third party plug-in.

Translations may be provided for return value messages and debug messages. To do this, the string must be marked for translation by wrapping it in the "underscore" function. The translation must also be provided in a specially formatted list variable *locale*.

The format for the *locale* list is: (LIST (language-list) [(language-list) ...])

where "language-list" is a list in the form: (LIST country-code (translations))

and the "translations" are list in the form: (LIST (List "string" "translation") [(List "string" "translation")...])

  • The *locale* list may contain any number of "language-list" elements, where each language-list is a list of two strings.
  • The first element of each "language-list" is the country code (for example "en" or "fr"),
  • The second item of each "language-list" is a list of translation pairs.
  • A "translation pair" is a list containing the default string (usually in English) and the translated string (in the language specified by the country code).

A working example may be found in the RMS effect.

See Also


|< Nyquist