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.
To use Nyquist, you should have a basic knowledge of Lisp. An excellent text by Touretzky is recommended (Touretzky 1984). Appendix "XLISP: An Object-oriented Lisp" is the reference manual for XLISP, of which Nyquist is a superset. Starting with Version 3, Nyquist supports a variant of SAL, which is also available in Common Music. Since there are some differences, 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.
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 (
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.
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.
You can cut and paste text into Nyquist, but for serious work, you will want to use the Lisp
Using SAL, you can type
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
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, try the
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
file
Our first example makes and plays a sound:
Note: when Nyquist plays a sound, it scales the signal by 2^(15)-1 and (by default) converts to a 16-bit integer format. A signal like
The function
A complete Nyquist waveform is a list consisting of a sound, a pitch,
and
Now that we have defined a function, the last step of this example is to
build the wave. The following code calls
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.
play seq(my-note(c4, i), my-note(d4, i), my-note(f4, i),
my-note(g4, i), my-note(d4, q))
The
Sequences can also be constructed using the
Figure 1: An envelope generated by the
; try it out:
;
play env-note(c4)
In the next example, The stretch operator (
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).
; 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.
;
Installation
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.
sys/win/README.txt
, sys/mac/README.txt
, and
sys/unix/README.txt
.
http://sourceforge.net/projects/nyquist
). The latest
source code can be obtained via Subversion (svn) using the following:
svn co https://nyquist.svn.sourceforge.net/svnroot/nyquist/trunk nyquist
or by checking out nyquist using a graphical interface svn client such as
TortoiseSVN for Windows.
Using NyquistIDE
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".
Using SAL
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 (sal)
.
Helpful Hints
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 JNyqIDE, the interactive development environment rather than a console window.)
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 file.
define function l () load "myfile.lsp"
and then
exec l()
to (re)load the file.
sal-mode.el
) included with the Common Music distribution, which you can find on the Web at sourceforge.net
.
:print t
option of the load
command. 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.
Using Lisp
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 exit
to
get a Lisp prompt (>
). Commands can be entered manually by typing
into the upper left text box in NyquistIDE.
Examples
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.
nyquist/demos/examples.sal
. Corresponding Lisp syntax
examples are in the file nyquist/demos/examples.lsp
.
;; Making a sound.
play osc(60) ; generate a loud sine wave
This example is about the simplest way to create a sound with Nyquist. The
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 parameter 60
designates a
pitch of middle C. (Pitch specification will be described in greater detail
later.) The result of the osc
function is a sound. To hear a sound,
you must use the 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 typing:
exec r()
This (r)
function is a general way to "replay" the last thing written by play
.
(osc 60)
, which ranges from +1 to -1, will play as a full-scale 16-bit audio signal.
Waveforms
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 oscillator
will be used to compute the harmonics.
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 +
) to
create a waveform which is bound temporarily to *table*
.
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
pitch numbers.
The list of sound, pitch, and T
is formed in the last line of
mkwave
: since build-harmonic
computes signals with a duration
of one second, the fundamental is 1 Hz, and the hz-to-step
function
converts to pitch (in units of steps) as required.
define function mkwave()
begin
set *table* = 0.5 * build-harmonic(1.0, 2048) +
0.25 * build-harmonic(2.0, 2048) +
0.125 * build-harmonic(3.0, 2048) +
0.0625 * build-harmonic(4.0, 2048)
set *table* = list(*table*, hz-to-step(1.0), #t)
end
mkwave
the first time the code is executed (loaded from a file). The second time, the variable *mkwave*
will be true, so mkwave
will not be invoked:
if ! fboundp(quote(*mkwave*)) then
begin
exec mkwave()
set *mkwave* = #t
end
Wavetables
When Nyquist starts, several waveforms are created and stored in global variables for convenience. They are: *sine-table*
, *saw-table*
, and *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 wave table 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 *saw-table*
and *tri-table*
a try.
Sequences
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 begin
and
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, *table*)
Here, my-note
is defined to take pitch and duration as parameters;
it calls osc
to do the work of generating a waveform, using
*table*
as a wave 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, i
(for
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.
at
transformation to
specify time offsets. See
sequence_example.htm
demos, sequence
for more examples and explanation.
Envelopes
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.
env
function.
; 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)
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. See
the code and description in
demos/scratch_tutorial.htm
for an
interesting use of ring modulation to create "scratch" sounds.
~
)
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))
Piece-wise Linear Functions
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 pwl
. Since pwl
is used in some examples later on, we will take a look at pwl
now. The 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:
; symetric rise to 10 (at time 1) and fall back to 0 (at time 2):
;
pwl(1, 10, 2)
Predefined Constants
For convenience and readability, Nyquist pre-defines some constants, mostly
based on the notation of the Adagio score language, as follows:
lppp = -12.0 (dB)
lpp = -9.0
lp = -6.0
lmp = -3.0
lmf = 3.0
lf = 6.0
lff = 9.0
lfff = 12.0
dB0 = 1.00
dB1 = 1.122
dB10 = 3.1623
s = Sixteenth = 0.25
i = eIghth = 0.5
q = Quarter = 1.0
h = Half = 2.0
w = Whole = 4.0
sd, id, qd, hd, wd = dotted durations.
st, it, qt, ht, wt = triplet durations.
*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 A4
will 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
ny:all
= "all the samples" (i.e. a big number) = 1000000000
More Examples
More examples can be found in the directory demos
, part of the standard
Nyquist release. In this directory, you will find the following and more:
demos/pmorales/b1.lsp
and demos/mateos/gong.lsp
demos/pmorales/b2.lsp
)
demos/pmorales/b3.lsp
, demos/pmorales/e2.lsp
, demos/pmorales/partial.lsp
, and demos/mateos/bell.lsp
)
demos/pmorales/b8.lsp
demos/shepard.lsp
and demos/pmorales/b9.lsp
)
demos/pmorales/c1.lsp
)
demos/pmorales/buzz.lsp
demos/pmorales/d1.lsp
demos/mateos/tuba.lsp
and clarinet sounds (demos/pmorales/e2.lsp
demos/rhythm_tutorial.htm
demos/plight/drum.lsp
.
Previous Section | Next Section | Table of Contents | Index | Title Page