Previous Section | Next Section | Table of Contents | Index | Title Page

Introduction and Overview

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 macOS, 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.

Installation

Nyquist is a C++ program intended to run under various operating systems including Unix, macOS, 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. Java from Oracle is recommended, e.g. Java SE Development Kit 17. 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.

Troubleshooting

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:

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.

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.

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).

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.

Command Line

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-TIME function 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.

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 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 file.

Using SAL, you can type 

define function l () load "myfile.lsp"

and then 

exec l()

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 sourceforge.net.

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, try the :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.

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.

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 nyquist/lib/examples.sal. Corresponding Lisp syntax examples are in the file nyquist/lib/examples.lsp.

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. 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.

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 (osc 60), which ranges from +1 to -1, will play as a full-scale 16-bit audio signal.

Non-Sinusoidal 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 special function, build-harmonic is used to compute the harmonics, but it is just a convenient wrapper for the primitive function snd-sine.

The 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 +) to create a waveform which is bound to local variable wave.

A complete Nyquist wavetable specification is a list consisting of a sound, a pitch, and 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
    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 variable *mkwave* will be set, so mkwave will not be invoked: 

if ! boundp(quote(*mkwave*)) then
  begin
    exec mkwave()
    set *mkwave* = #t
  end

Using 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 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 *saw-table* and *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.

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, *mytable*)

play seq(my-note(c4, i), my-note(d4, i), my-note(f4, i), 
         my-note(g4, i), my-note(d4, q))

Here, my-note is defined to take pitch and duration as parameters; it calls 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, *table* is used, but here we specify our new table *mytable*.

The 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.

Sequences can also be constructed using the at transformation to specify time offsets.

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.



Figure 1: An envelope generated by the 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)

; 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).

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: 

; 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.
;

Predefined Constants

For convenience and readability, Nyquist pre-defines some constants, mostly based on the notation of the Adagio score language, as follows:

More Examples

More examples can be found in the directory demos, part of the standard Nyquist release. In the Apple OS X version of Nyquist, the demos and 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.

The file 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:

Previous Section | Next Section | Table of Contents | Index | Title Page