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

Installation

Nyquist is a C program intended to run under various operating systems including Unix, MacOS, and Windows.

Unix Installation

For Unix systems, Nyquist is distributed as a compressed tar file named nyqsrc3nn.zip, where nn is the version number (e.g. v3.01 was in nyqsrc301.zip). To install Nyquist, copy nyqsrc3nn.zip to the directory on your machine where you would like to install Nyquist, and type:
gunzip nyqsrc3nn.zip
cd nyquist
ln -s sys/unix/linux/Makefile Makefile
setenv XLISPPATH `pwd`/runtime:`pwd`/lib
make
The first line creates a nyquist directory and some subdirectories. The second line (cd) changes directories to the new nyquist directory. The third line makes a link from the top-level directory to the Makefile for your system. In place of linux in sys/unix/linux/Makefile, you should substitute your system type. Current systems are next, pmax, rs6k, sgi, linux, and sparc. The setenv command tells Nyquist where to search for lisp files to be loaded when a file is not found in the current directory. The runtime directory should always be on your XLISPPATH when you run Nyquist, so you may want to set XLISPPATH in your shell startup file, e.g. .cshrc. Assuming the make completes successfully, you can run Nyquist as follows:
./ny
When you get the prompt, you may begin typing expressions such as the ones in the following "Examples" section.

One you establish that Nyquist (ny) is working from the command line, you should try using jNyqIDE, the Java-based Nyquist development environment. First, make jny executable (do this only once when you install Nyquist):

chmod +x jny
Then try running jNyqIDE by typing:
./jny
If the jNyqIDE window does not appear, make sure you have Java installed (if not, you probably already encountered errors when you ran make). You can also try recompiling the Java files:
cd jnyqide
javac *.java
cd ..

Note: With Linux and the Macintosh OS X, jNyqIDE defines the environment passed to Nyquist. If you set XLISPPATH as shown above, it will be passed along to Nyquist under jNyqIDE. If not, a default XLISPPATH will have the lib and runtime directories only. This does not apply to Windows because even though the environment is there, the Windows version of Nyquist reads the XLISPPATH from the Registry.

You can also specify the search path by creating the file nyquist/xlisppath, which should have colon-separated paths on a single line of text. This file will override the environment variable XLISPPATH.

It is good to have USER in the environment with your user ID. This string is used to construct some file names. jNyqIDE will look for it in the environment. You can also specify your user ID using the file nyquist/user, but if you have a shared installation of Nyquist, this will not be very useful.

Note: Nyquist looks for the file init.lsp in the current directory. If you look in the init.lsp in runtime, you will notice two things. First, init.lsp loads nyquist.lsp from the Nyquist directory, and second, init.lsp loads system.lsp which in turn defines the macro play. You may have to modify system.lsp to invoke the right programs on your machine.

Win32 Installation

The Win32 version of Nyquist is packaged as a compiled (runtime) system in an executable installer. A source version is also available (the same source download is for Win32, Mac OS X, and Linux). The source version is intended for developers who want to recompile Nyquist. The contents of the source archive are extracted to the C:\nyquist directory, but you can put it anywhere you like. You can then open the workspace file, nyquist.sln, using Microsoft Visual C++. You can build and run the command line version of Nyquist from within Visual C++. There is a batch file, comp-ide.bat, for bulding the Nyquist IDE. This requires the Java SDK from Sun Microsystems.

The runtime version contain everything you need to run Nyquist, including the executable, examples, and documentation, packaged as an executable installer program. After executing the installer, just find Nyquist in your Start menu to run it. You may begin typing expressions such as the ones in the following "Examples" section.

Optional: Nyquist needs to know where to find the standard runtime files. The location of runtime files must be stored in the Registry. The installers create a registry entry, but if you move Nyquist or deal with different versions, you can edit the Registry manually as follows:

What if Nyquist functions are undefined?
If you do not have administrative privileges for your machine, the installer may fail to set up the Registry entry that Nyquist uses to find initialization files. In this case, Nyquist will run a lisp interpreter, but many Nyquist functions will not be defined. If you can log in as administrator, do it and reinstall Nyquist. If you do not have permission, you can still run Nyquist as follows:

Create a file named init.lsp in the same directory as Nyquist.exe (the default location is C:\Program Files\Nyquist, but you may have installed it in some other location.) Put the following text in init.lsp:


(setf *search-path* "C:/Program Files/Nyquist/runtime,C:/Program Files/Nyquist/lib")
(load "C:/Program Files/Nyquist/runtime/init.lsp")

Note: in the three places where you see C:/Program Files/Nyquist, insert the full path where Nyquist is actually installed. Use forward slashes (/) rather than back slashes (\) to separate directories. For example, if Nyquist is installed at D:\rbd\nyquist, then init.lsp should contain:

(setf *search-path* "D:/rbd/nyquist/runtime,D:/rbd/nyquist/lib")
(load "d:/rbd/nyquist/runtime/init.lsp")

The variable *search-path*, if defined, is used in place of the registry to determine search paths for files.

SystemRoot
(Ignore this paragraph if you are not planning to use Open Sound Control under Windows.) If Nyquist prints an error message and quits when you enable Open Sound Control (using osc-enable), check to see if you have an environment variable SystemRoot, e.g. type set to a command prompt and look for the value of SystemRoot. The normal value is C:\windows. If the value is something else, you should put the environment entry, for example:
SystemRoot="D:\windows"
into a file named systemroot (no extension). Put this file in your nyquist directory. When you run jNyqIDE, it will look for this file and pass the contents as an environment variable to Nyquist. The Nyquist process needs this to open a UDP socket, which is needed for Open Sound Control.

The "java is not recognized" Error
Sometimes, Nyquist will run directly from the installer, but then it will not start from the Windows Start menu. You can try running the nyquist/jnyqide.bat program from a Windows shell. If that fails, and you see an error similar to "java is not recognized as in internal or external command error", the problem may be that paths are not set up properly to allow the Windows shell to find java. Right click on "My Computer" on the Windows desktop and select "Properties." Under the "Advanced" tap, press the "Environment Variables" button, and look for PATH under "System Variables." Make sure the Java bin directory is on the path. If it is not, you will have to find your installation of Java and add the appropriate directory to the PATH variable, e.g. "C:\Program Files\Java\jdk1.6.0\bin."

MacOS X Installation

The OS X version of Nyquist is very similar to the Linux version, but it is developed using Xcode, Apple's programming environment. With a little work, you can use the Linux installation instructions to compile Nyquist, but it might be simpler to just open the Xcode project that is included in the Nyquist sources.

You can also download a pre-compiled version of Nyquist for the Mac. Just download nyqosx2xx.tgz to the desktop and open it to extract the folder <tt>nyqosx2xx</tt>. (Again, "2xx" refers to the current version number, e.g. v2.31 would be named with "231".) Open the folder to find a Mac Application named jNyqIDE and a directory named <tt>nyquist/doc</tt>. Documentation is in the <tt>nyquist/doc</tt> directory.

The file <tt>jNyqIDE.app/Contents/Resources/Java/ny</tt> is the command line executable (if you should need it). To run from the command line, you will need to set the XLISPPATH environment variable as with Linux. On the topic of the XLISPPATH, note that this variable is set by jNyqIDE when running with that application, overriding any other value. You can extend the search path by creating the file xlisppath in the same directory as the nyquist executable ny. The xlisppath file should have colon-separated paths on a single line of text.

Using jNyqIDE

The program named jNyqIDE is an "integrated development environment" for Nyquist. When you run jNyqIDE, it starts the Nyquist program and displays all Nyquist output in a window. jNyqIDE 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 jNyqIDE is in Chapter "The jNyqIDE 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. jNyqIDE 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 jNyqIDE.

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 jNyqIDE 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 :print t option o fthe 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 jNyqIDE.

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

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 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:
; symetric 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 this directory, you will find the following and more:


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