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 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. SAL is a language distinct from Lisp. It 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).

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

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:

- Get a pre-compiled version of the Nyquist IDE for Windows or Mac OS X. The Windows version comes packaged in an installer that installs and configures the Nyquist IDE. The Mac OS X version unpacks to a complete OS X application.
- Compile from sources. There is one set of sources for Mac, Windows, and Unix. Instructions for building applications from the sources are provided in the files `sys/win/README.txt`, `sys/mac/README.txt`, and `sys/unix/README.txt`.

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 with additional information. Additional information and instructions on installation can be found in:

- `sys/win/README.txt`
- `sys/mac/README.txt`
- `sys/unix/README.txt`

### 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 `-R`paths 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 `-W`paths 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 `-L`run-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 actual work rather than CPU seconds or wall time. One unit of run time is on the order of 10ms of CPU time (for a medium speed computer in 2014), but you can use the `GET-RUN-TIME` function to read the internal run-time counter to see how much computation you have done.

The `-M`memory-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 `-T`transcript-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 JNyqIDE, 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/demos/examples.sal`. Corresponding Lisp syntax examples are in the file `nyquist/demos/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 2^15-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.

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

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 temporarily to `*table*`.

A complete Nyquist waveform 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
        set *table* = 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 *table* = list(*table*, hz-to-step(1.0), #t)
      end

Now that we have defined a function, the last step of this example is to build the wave. The following code calls `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.

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

    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 `*table*` as a wave table.

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. See `demos/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.

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. See the code and description in `demos/scratch_tutorial.htm` for an interesting use of ring modulation to create "scratch" sounds.

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:

- Dynamics Note: these dynamics values are subject to change.

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

- Durations

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

- Pitches Pitches are based on an A4 of 440Hz. To achieve a different tuning, set `*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

- Miscellaneous

  > `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 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 all the demo descriptions. In this directory, you will find the following and more:

- Code to create atonal melodies (`demos/src/atonal-melodies.sal`).
- How to make arpeggios (`demos/arpeggiator.htm` and `demos/src/arp.sal`)
- Gong sounds by additive synthesis (`demos/pmorales/b1.lsp` and `demos/mateos/gong.lsp`)
- Risset's spectral analysis of a chord (`demos/pmorales/b2.lsp`)
- Bell sounds (`demos/pmorales/b3.lsp`, `demos/pmorales/e2.lsp`, `demos/pmorales/partial.lsp`, and `demos/mateos/bell.lsp`)
- Drum sounds by Risset (`demos/pmorales/b8.lsp`
- Shepard tones (`demos/src/shepard.lsp` and `demos/pmorales/b9.lsp`)
- Random signals (`demos/pmorales/c1.lsp`)
- Buzz with formant filters (`demos/pmorales/buzz.lsp`)
- Computing samples directly in Lisp (using Karplus-Strong and physical modelling as examples) (`demos/pmorales/d1.lsp`)
- FM Synthesis examples, including FM voices (`demos/src/fm-voices-chowning.sal`) designed by John Chowning, bell, wood drum, brass sounds, tuba sound (`demos/mateos/tuba.lsp`) and clarinet sounds (`demos/pmorales/e2.lsp`)
- Rhythmic patterns (`demos/rhythm_tutorial.htm`)
- Drum Samples and Drum Machine (`demos/plight/drum.lsp`). (See Section "Drum Machine").

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