.\" Copyright (c) 2003 Dave Phillips
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
.\" USA.
.\"
.TH Nyquist 1 "November 2003"
.SH NAME
Nyquist - A computer programming language for software sound synthesis and music composition
.SH SYNOPSIS
.BI "ny [" OPTIONS "]"
.SH DESCRIPTION
.B Nyquist
is a language designed for digital sound synthesis and computer-assisted music composition.
It is based upon the
.B XLISP
implementation of the 
.B LISP
programming language.
.B Nyquist
is similar to other software synthesis languages such as 
.B Csound 
and
.B cmusic.
Like programs written in those languages
.B Nyquist
programs invoke and arrange various audio synthesis functions which are employed
by musically useful algorithms and control structures, but instrument design and 
scoring syntax are completely integrated in
.B Nyquist.

.TP
.B Example:
.I ;; Make and play a sound

(play (osc 60))

This one-line program will call a
.B Nyquist
oscillator function to create a default sine wave with a default amplitude of 1.0 (normalized) and a pitch value of 60 (MIDI note number for middle C).
The output from the oscillator is then sent to the system sound hardware for realtime play starting at the default delta-time of 0
and lasting for a default duration of 1 second.

.TP
.B Example:
.I ;; Create an instrument, play a scale with it

(defun note (pitch dur) 
  (osc pitch dur *table*))

(play (seq (note c4 i) 
           (note d4 i) 
           (note e4 i) 
           (note f4 i) 
           (note g4 i)
           (note a4 i)
           (note b4 i)
           (note c5 q))) 

This program first defines a
.I note
function that receives two parameters,
.I pitch
and
.I dur
(duration), and sends them to an oscillator.
The oscillator applies the given pitch and duration to the waveform defined in the 
.I *table*
global variable. The default waveform is a sine with an amplitude of 1.

The
.I seq
function then sends a sequence of
.I note
statements to the
.I play
function for realtime audio output.
In this example the pitch is indicated in a note-name/octave pair.
Duration is expressed in symbols for conventional musical rhythmic units, i.e., 
.I i
stands for an eighth note (quaver) and
.I q
stands for a quarter note (crotchet).

.B Nyquist
programs may be entered line by line at the program prompt
or they can be saved and loaded as files.

.SH OPTIONS
.TP 10
.BI "-l " "filename.lsp"
Load a
.B Nyquist
program file, typically (but not necessarily) with an extension of
.I .lsp.

.SH FILES
Examples and tutorial files are located in the
.I $NYQUIST_HOME/demos
directory.

HTML documentation is located in the
.I $NYQUIST_HOME/doc
directory.

.SH BUGS
Possibly, maybe, perhaps. If you find any please report them to the authors.

.SH TODO
See the todo.txt file in the
.B Nyquist
top-level directory for the current TODO list.

.SH AUTHOR
.B Nyquist
is written by Roger B. Dannenberg <dannenberg@cs.cmu.edu>.
.B XLISP
is written by David Betz <dbetz@xlisper.mv.com>.

.SH COPYRIGHT
Copyright and license information for 
.B Nyquist:

Copyright 2000-2002, by Roger B. Dannenberg. All rights reserved.

Copyright and license information for 
.B XLISP:

Copyright 1984-2002, by David Michael Betz. All rights reserved.

See the license.txt file in the
.B Nyquist
top-level directory for complete licensing details.