Nyquist
The page title is a "working title", I'm open to suggestions for a revised title.
- Peter 28Dec16: No longer a working title and not really mutable as I have this afternoon fixed up a large number of links in the manual to come to this page with this name.
Nyquist was written by Roger B. Dannenberg at Carnegie Mellon University, with support from Yamaha Corporation and IBM, and was intended to be used as a complete programming language for audio synthesis and analysis, with support for MIDI, audio recording and playback, file I/O, object-oriented programming, profiling, debugging and more. It is named after Harry Nyquist.
|
Contents
- Overview
- Getting Started
- Nyquist Programming Reference
- Nyquist Documentation
- Nyquist Plug-ins Reference
- Existing Nyquist plug-ins available for download
Overview
Nyquist is a relatively simple but powerful scripting language with good documentation.
As an extension of XLisp, Nyquist is limited to single-byte ASCII characters. The results of using characters outside the range of ASCII 32 to 126 in Nyquist plug-ins are unspecified. While the use of characters outside of this range may work satisfactorily for personal use on some operating systems, plug-ins for public distribution should be written using only standard characters (ASCII characters 32 to 126). This applies to plug-in code, comments and string data.
The standalone version of Nyquist is available from the Carnegie Mellon University Computer Music Project.
Plug-ins
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 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 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.
For a full description of the Nyquist language, refer to the Nyquist Reference Manual.
LISP Syntax
The Nyquist programming language is an extension of XLISP, which is one of a large family of LISP languages. Thus the native code style is the same as other Lisp languages; "fully parenthesized prefix notation". Lisp code is based on a list of "s-expressions". Each expression in Lisp begins with an open parenthesis "(", followed by the function symbol, followed by a list of 0 or more arguments (parameters), and ending with a close parenthesis ")". For example, to add two numbers, we use the function symbol "+", and the arguments are the two numbers that we wish to add:
| (+ 3 5) |
For more information about Nyquist programming with Lisp syntax, see the Introduction to Nyquist and Lisp Programming page.
SAL Syntax
SAL is an alternative way to write Nyquist code, which may feel more familiar to C/C++ developers than Nyquist's LISP syntax. 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 effect. Since defining "main" just to evaluate and return a simple expression is so awkward, you can simply type
| return expression |
Normally, this is not a legal statement as a top-level command in SAL, but in , 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.
Getting Started
The following are a set of three linked tutorials to help get you started with progamming in Nyquist for Audacity.
Nyquist Programming Reference
- Nyquist Audio Programming - Introduction to programming with Nyquist.
For information about writing Nyquist plug-ins for Audacity, see: Nyquist Plug-ins Reference
Nyquist Documentation
This page is intended primarily for people that wish to write Nyquist plug-ins or gain an insight into how Nyquist is used in Audacity.
For users that only want to download Nyquist plug-ins please see below.
Nyquist Plug-ins Reference
This page offers a detailed look at the structure and syntax of Nyquist Plug-ins. It is intended for people who wish to write their own plug-ins.
If you are looking for extra Nyquist plug-ins to use, see below.
Existing Nyquist plug-ins available for download
This section is about existing Nyquist plug-ins that are ready and available for you to download and use in Audacity.
