Nyquist

From Audacity Wiki
Jump to: navigation, search
Peter 27Dec16: Landing page under construction for Nyquist pages in process of being transferred from the Audacity Website.

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.

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.

Simple Nyquist commands may be used in Audacity's Nyquist Prompt effect, or used to write plug-ins. 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.

Contents

  1. Overview
  2. Getting Started
  3. Nyquist Programming Reference
  4. Nyquist Documentation
  5. Nyquist Plug-ins Reference
  6. 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 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.

For a full description of the Nyquist language, refer to the Nyquist Reference Manual.

There are additional features to Nyquist plug-ins that are unique to Audacity, and therefore not covered in the Nyquist Reference Manual. For information about these features, refer to the Nyquist Plug-ins Reference.


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 Nyquist Prompt... effect. Since defining "main" just to evaluate and return a simple expression is so awkward, you can simply type

return expression

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


Getting Started

Peter 19Mar18: ToDo-1 This sectio has been transferred to the Manual - but can only be deleted after 2.3.0 is released. May leave a link to the Manual.

The following are a set of three linked tutorials to help get you started with progamming in Nyquist for Audacity.


Nyquist Programming Reference

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.