Nyquist is a language for sound synthesis and music composition. Unlike score languages that tend to deal only with events, or signal processing languages that tend to deal only with signals and synthesis, Nyquist handles both in a single integrated system. Nyquist is also flexible and easy to use because it is based on an interactive Lisp interpreter.
With Nyquist, you can design instruments by combining functions (much as you would using the orchestra languages of Music V, cmusic, or Csound). You can call upon these instruments and generate a sound just by typing a simple expression. You can combine simple expressions into complex ones to create a whole composition.
Nyquist runs under Linux, Apple Mac OS X, Microsoft Windows NT, 2000, XP, and Vista, and it produces sound files or directly generates audio. Recent versions have also run on AIX, NeXT, SGI, DEC pmax, and Sun Sparc machines. (Makefiles for many of these are included, but out-of-date). Let me know if you have problems with any of these machines.
The core language of Nyquist is Lisp. Nyquist extends Lisp for sound synthesis and processing. Starting with Version 3, Nyquist supports a variant of SAL syntax. SAL is a language distinct from Lisp, but it can be translated to Lisp and SAL and Lisp programs can be combined. SAL was introduced in Rick Taube's Common Music system. Since there are some differences between Nyquist and Common Music, one should generally call this implementation “Nyquist SAL;” however, in this manual, I will just call it “SAL.” SAL offers most of the capabilities of Lisp, but it uses an Algol-like syntax that may be more familiar to programmers with experience in Java, C, Basic, etc. An introduction to SAL is in Mary Simoni and Roger B. Dannenberg, Algorithmic Composition: A Guide to Composing Music with Nyquist (Simoni and Dannenberg 2013). To learn about Lisp, an excellent text by Touretzky is recommended (Touretzky 1984). Appendix Appendix 3: XLISP: An Object-oriented Lisp is the reference manual for XLISP, of which Nyquist is a superset.
Nyquist is a C++ program intended to run under various operating systems including Unix, Mac OS X, and Windows. Nyquist is based on Lisp, but it includes its own Lisp interpreter (a modified version of XLISP), so you do not need to install some other Lisp to run Nyquist. Other Lisp systems are not compatible with Nyquist.
Most Nyquist users run Nyquist under the Nyquist IDE, which is written in Java and depends on the Java runtime system. Most systems already have Java, but if you do not, you will need to install it. When you install the Nyquist IDE, you will automatically get Nyquist and a set of runtime libraries.
There are generally two ways to install Nyquist:
You can download source code and precompiled versions from the Nyquist project
on SourceForge (
http://sourceforge.net/projects/nyquist). The latest
source code can be obtained via Subversion (svn) using the following:
svn co svn://svn.code.sf.net/p/nyquist/code/trunk/nyquist nyquist
or by checking out nyquist using a graphical interface svn client such as TortoiseSVN for Windows.
All versions of Nyquist includes a Readme.txt file in the top-level
nyquist directory with general information.
Additional information and instructions on installation
can be found in:
The program named NyquistIDE is an “integrated development environment” for Nyquist. When you run NyquistIDE, it starts the Nyquist program and displays all Nyquist output in a window. NyquistIDE helps you by providing a Lisp and SAL editor, hints for command completion and function parameters, some graphical interfaces for editing envelopes and graphical equalizers, and a panel of buttons for common operations. A more complete description of NyquistIDE is in Chapter The NyquistIDE Program.
For now, all you really need to know is that you can enter Nyquist commands by typing into the upper left window. When you type return, the expression you typed is sent to Nyquist, and the results appear in the window below. You can edit files by clicking on the New File or Open File buttons. After editing some text, you can load the text into Nyquist by clicking the Load button. NyquistIDE always saves the file first; then it tells Nyquist to load the file. You will be prompted for a file name the first time you load a new file.
SAL mode means that Nyquist reads and evaluates SAL commands rather
than Lisp. The SAL mode prompt is "
SAL> " while the Lisp mode
prompt is "
> ". When Nyquist starts it normally enters SAL
mode automatically, but certain errors may exit SAL mode. You can
reenter SAL mode by typing the Lisp expression
In SAL mode, you type commands in the SAL programming language. Nyquist reads the commands, compiles them into Lisp, and evaluates the commands. Commands can be entered manually by typing into the upper left text box in NyquistIDE.
When run from the command line, Nyquist (usually the command is ny) looks for some options and some files to load. There are several options.
The -Rpaths option gives Nyquist a list of paths (separated by semicolons) to directories where Nyquist is allowed to read files. Files in any subdirectories of the listed directories can also be read, along with the directories themselves. This option can be used to restrict access to files.
The -Wpaths option gives Nyquist a list of paths (separated by semicolons) to directories where Nyquist is allowed to write files (including sound files). If -W is used, Nyquist will not open audio output to play sounds and will not allow access to Open Sound Control. This option can be used to protect files from accidentally malicious code. (If you are truly worried about Nyquist code, you should run Nyquist in a virtual machine or other isolated machine. It is unlikely that Nyquist is secure from all attacks.)The -Lrun-time-limit option gives Nyquist a run time limit. If the limit is exceeded, Nyquist prints an error message and exits. The time is based on Lisp expression evaluations rather than CPU seconds or wall time or even execution time involved in printing or signal processing. One unit of run time is on the order of 10ms of CPU time (for a medium speed computer in 2019), but depending on what you are computing, a unit of run time can vary from 60ms to 1.5ms. You can use the
GET-RUN-TIMEfunction to read the internal run-time counter to see how much computation you have done in the same units.The -Mmemory-limit option gives Nyquist a memory limit. If the limit (in megabytes) is exceeded, Nyquist prints an error message and exits. The limit includes all XLISP data (cons cells, strings, etc.) plus sample blocks and tables allocated for signal processing.
The -Ttranscript-file-name option copies console output to a transcript file.
The -V option sets verbose mode. If set, any files specified on the command line to be loaded are loaded with the verbose option.
Additionally, the command line can name files to be loaded. Nyquist begins by loading init.lsp, which by default is in the nyquist/runtime directory. This file loads all the standard Nyquist functions. After that, Nyquist will load any other files named on the command line.
Finally, Nyquist expects to find search paths in the XLISPPATH environment variable (or for Windows, see installation instructions; the path is saved in the Windows Registry). Normally, you must set XLISPPATH for Nyquist to find init.lsp and the definitions of most Nyquist functions. Be sure you have system.lsp in nyquist/runtime. Part of the installation process copies the appropriate system.lsp from nyquist/sys/* to nyquist/runtime where it can be found and loaded by init.lsp.
Under Win95 and Win98, the console sometimes locks up. Activating another window and then reactivating the Nyquist window should unlock the output. (We suggest you use NyquistIDE, the interactive development environment rather than a console window.)
You can cut and paste text into Nyquist, but for serious work, you
will want to use the Lisp
load command. To save even more time,
write a function to load your working file, e.g.
(defun l ()
(load "myfile.lsp")). Then you can type
(l) to (re)load your
Using SAL, you can type
define function l () load "myfile.lsp"
to (re)load the file.
The Emacs editor is free GNU software and will help you balance
parentheses if you use Lisp mode. In fact, you can run nyquist
(without the IDE) as a subprocess to Emacs. A helful discussion is
at //http://www.audacity-forum.de/download/edgar/nyquist/nyquist-doc/examples/emacs/main.html. If
you use Emacs, there is also a SAL mode (the file is
sal-mode.el) included with the Common Music distribution, which
you can find on the Web at
The NyquistIDE also runs Nyquist as a subprocess and has built-in Lisp
and SAL editors. If your editor does not help you balance parentheses,
you may find yourself counting parens and searching for unbalanced
expressions. If you are confused or desperate and using Lisp syntax,
:print t option of the
load function. By looking
at the expressions printed, you should be able to tell where the last
unbalanced expression starts. Alternatively, type
(file-sexprs) and type the lisp file name at the prompt. This
function will read and print expressions from the file, reporting an
error when an extra paren or end-of-file is reached unexpectedly.
Lisp mode means that Nyquist reads and evaluates Nyquist expressions in
Lisp syntax. Since Nyquist is build on a Lisp interpreter, this is the
“native” or machine language of Nyquist, and certain errors and functions
may break out of the SAL interpreter, leaving you with a prompt for a Lisp
expression. Alternatively, you can exit SAL simply by typing
get a Lisp prompt (
> ). Commands can be entered manually by typing
into the upper left text box in NyquistIDE.
We will begin with some simple Nyquist programs. Throughout the manual, we will assume SAL mode and give examples in SAL, but it should be emphasized that all of these examples can be performed using Lisp syntax. See Section Interoperability of SAL and XLISP on the relationship between SAL and Lisp.
Detailed explanations of the functions used in these examples will be
presented in later chapters, so at this point, you should just read these
examples to get a sense of how Nyquist is used and what it can do. The
details will come later. Most of these examples can be found in the
nyquist/lib/examples.sal. Corresponding Lisp syntax
examples are in the file
Our first example makes and plays a sound:
;; Making a sound. play osc(60) ; generate a loud sine wave
This example is about the simplest way to create a sound with Nyquist.
osc function generates a sound using a table-lookup
oscillator. There are a number of optional parameters, but the
default is to compute a sinusoid with an amplitude of 1.0. The
60 designates a pitch of middle C. (Pitch
specification will be described in greater detail later.) The result
osc function is a sound. To hear a sound, you must use
play command, which plays the file through the machine's
D/A converters. It also writes a soundfile in case the computation
cannot keep up with real time. You can then (re)play the file by
(r) function is a general way to “replay” the last thing written by
Note: when Nyquist plays a sound, it scales the signal by
215-1 and (by default)
converts to a 16-bit integer format. A signal like
which ranges from +1 to -1, will play as a full-scale 16-bit audio
Our next example will be presented in several steps. The goal is to create a
sound using a
wavetable consisting of several harmonics as opposed to a simple sinusoid.
In order to build a table, we will use a function that computes a single
harmonic and add harmonics to form a wavetable. An special function,
build-harmonic is used to compute the harmonics, but it is just a
convenient wrapper for the primitive function
mkwave calls upon
build-harmonic to generate a total of four
harmonics with amplitudes 0.5, 0.25, 0.125, and 0.0625.
These are scaled and added (using
create a waveform which is bound to local variable
A complete Nyquist wavetable specification
is a list consisting of a sound, a pitch,
T, indicating a periodic waveform. The pitch gives the
nominal pitch of the sound. (This is implicit in a single cycle wave
table, but a sampled sound may have many periods of the fundamental.)
Pitch is expressed in half-steps, where middle C is 60 steps, as in MIDI
The list of sound, pitch, and
T is formed in the last line of
build-harmonic computes signals with a duration
of one second, the fundamental is 1 Hz, and the
converts to pitch (in units of steps) as required.
define function mkwave() begin with wave = 0.5 * build-harmonic(1, 2048) + 0.25 * build-harmonic(2, 2048) + 0.125 * build-harmonic(3, 2048) + 0.0625 * build-harmonic(4, 2048) set *mytable* = list(wave, hz-to-step(1.0), #t) end
Now that we have defined a function, the next step of this example is
to build the wavetable. The following code calls
mkwave the first
time the code is executed (loaded from a file). The second time, the
*mkwave* will be set, so
mkwave will not be
if ! boundp(quote(*mkwave*)) then begin exec mkwave() set *mkwave* = #t end
When Nyquist starts, several waveforms are created and stored in
global variables for convenience. They are:
*tri-table*, implementing sinusoid,
sawtooth, and triangle waves, respectively. The variable
*table* is initialized to
*sine-table*, and it is
*table* that forms the default wavetable for many Nyquist
oscillator behaviors. If you want a proper, band-limited waveform, you
should construct it yourself, but if you do not understand this
sentence and/or you do not mind a bit of aliasing, give
*tri-table* a try.
Note that in Lisp and SAL, global variables often start and end with asterisks (*). These are not special syntax, they just happen to be legal characters for names, and their use is purely a convention.
Finally, we define
my-note to use the waveform,
and play several notes in a simple score. Note that the function
my-note has only one command (a
return command), so it
is not necessary to use
end. These are only
necessary when the function body consists of a sequence of statements:
define function my-note(pitch, dur) return osc(pitch, dur, *mytable*) play seq(my-note(c4, i), my-note(d4, i), my-note(f4, i), my-note(g4, i), my-note(d4, q))
my-note is defined to take pitch and duration as parameters;
osc to do the work of generating a waveform, using
*mytable* as a wave table. In earlier examples, we saw
osc with only two parameters. In that case,
used, but here we specify our new table
seq function is used to invoke a sequence of behaviors. Each
note is started at the time the previous note finishes. The parameters to
my-note are predefined in Nyquist:
c4 is middle C,
eIghth note) is 0.5, and
q (for Quarter note) is 1.0. See Section
Predefined Constants for a complete description. The result is the sum of
all the computed sounds.
Sequences can also be constructed using the
at transformation to
specify time offsets.
The next example will illustrate the use of envelopes. In Nyquist,
envelopes are just ordinary sounds (although they normally have a low sample
rate). An envelope is applied to another sound by
multiplication using the
mult function. The code shows
the definition of
env-note, defined in terms of the
note function in the previous example. In
env-note, a 4-phase
envelope is generated using the
env function, which is
illustrated in Figure 1.
Figure 1: An envelope generated by the
; env-note produces an enveloped note. The duration ; defaults to 1.0, but stretch can be used to change ; the duration. ; Uses my-note, defined above. ; define function env-note(p) return my-note(p, 1.0) * env(0.05, 0.1, 0.5, 1.0, 0.5, 0.4) ; try it out: ; play env-note(c4)
While this example shows a smooth envelope multiplied by an audio signal, you can also multiply audio signals to achieve what is often called ring modulation.
In the next example, The stretch operator (
is used to modify durations:
; now use stretch to play different durations ; play seq(seq(env-note(c4), env-note(d4)) ~ 0.25, seq(env-note(f4), env-note(g4)) ~ 0.5, env-note(c4))
In addition to stretch, there are a number of transformations supported by Nyquist, and transformations of abstract behaviors is perhaps the fundamental idea behind Nyquist. Chapter Behavioral Abstraction is devoted to explaining this concept, and further elaboration can be found elsewhere (Dannenberg and Frayley 1989).
It is often convenient to construct signals in Nyquist using a list of
(time, value) breakpoints which are linearly interpolated to form a smooth
signal. Envelopes created by
env are a special case of the more
general piece-wise linear functions created by
is used in some examples later on, we will take a look at
pwl function takes a list of parameters which denote (time,
value) pairs. There is an implicit initial (time, value) pair of (0, 0),
and an implicit final value of 0. There should always be an odd number of
parameters, since the final value (but not the final time) is implicit.
Here are some examples:
; symmetric rise to 10 (at time 1) and fall back to 0 (at time 2): ; pwl(1, 10, 2)
; a square pulse of height 10 and duration 5. ; Note that the first pair (0, 10) overrides the default initial ; point of (0, 0). Also, there are two points specified at time 5: ; (5, 10) and (5, 0). (The last 0 is implicit). The conflict is ; automatically resolved by pushing the (5, 10) breakpoint back to ; the previous sample, so the actual time will be 5 - 1/sr, where ; sr is the sample rate. ; pwl(0, 10, 5, 10, 5)
; a constant function with the value zero over the time interval ; 0 to 3.5. This is a very degenerate form of pwl. Recall that there ; is an implicit initial point at (0, 0) and a final implicit value of ; 0, so this is really specifying two breakpoints: (0, 0) and (3.5, 0): ; pwl(3.5)
; a linear ramp from 0 to 10 and duration 1. ; Note the ramp returns to zero at time 1. As with the square pulse ; above, the breakpoint (1, 10) is pushed back to the previous sample. ; pwl(1, 10, 1)
; If you really want a linear ramp to reach its final value at the ; specified time, you need to make a signal that is one sample longer. ; The RAMP function does this: ; ramp(10) ; ramp from 0 to 10 with duration 1 + one sample period ; ; RAMP is based on PWL; it is defined in nyquist.lsp. ;
For convenience and readability, Nyquist pre-defines some constants, mostly based on the notation of the Adagio score language, as follows:
*A4-Hertz*to the desired frequency for A4, and call
(set-pitch-names). This will recompute the names listed below with a different tuning. In all cases, the pitch value 69.0 corresponds exactly to 440Hz, but fractional values are allowed, so for example, if you set
*A4-Hertz*to 444 (Hz), then the symbol
A4will be bound to 69.1567, and
C4(middle C), which is normally 60.0, will be 60.1567.
c0 = 12.0
cs0, df0 = 13.0
d0 = 14.0
ds0, ef0 = 15.0
e0 = 16.0
f0 = 17.0
fs0, gf0 = 18.0
g0 = 19.0
gs0, af0 = 20.0
a0 = 21.0
as0, bf0 = 22.0
b0 = 23.0
c1 ... b1 = 24.0 ... 35.0
c2 ... b2 = 36.0 ... 47.0
c3 ... b3 = 48.0 ... 59.0
c4 ... b4 = 60.0 ... 71.0
c5 ... b5 = 72.0 ... 83.0
c6 ... b6 = 84.0 ... 95.0
c7 ... b7 = 96.0 ... 107.0
c8 ... b8 = 108.0 ... 119.0
More examples can be found in the directory
demos, part of the standard
Nyquist release. In the Apple OS X version of Nyquist, the
doc directories are inside the NyquistIDE
application bundle. To make it easier to access these hidden files,
the NyquistIDE installs links to these directories the first time you
run it. The links will be in the same directory as the NyquistIDE itself.
demos/index.htm is an index to many examples and demonstrations.
Many examples are now Nyquist Extensions which can be downloaded by the
NyquistIDE using the Window : Extension Manager menu item.
Here are some highlights of what is available:
nyquist/lib/fm-voices-chowning/fm-voices-chowning.sal) designed by John Chowning, tuba sound (
nyquist/lib/mateos/tuba.lsp), and see
nyquist/lib/pmorales/e2.lspfor examples of FM bell, wood drum, brass sounds, and clarinet sounds.
nyquist/lib/plight/drum.lsp). (See Section Drum Machine).