The NyquistIDE program combines many helpful functions and interfaces to help you get the most out of Nyquist. NyquistIDE is implemented in Java, and you will need the Java runtime system or development system installed on your computer to use NyquistIDE. The best way to learn about NyquistIDE is to just use it. This chapter introduces some of the less obvious features. If you are confused by something and you do not find the information you need here, please contact the author.
The NyquistIDE runs the command-line version of Nyquist as a subtask, so everything that works in Nyquist should work when using the NyquistIDE and vice-versa. Input to Nyquist is usually entered in the top left window of the NyquistIDE. When you type return, if the expression or statement appears to be complete, the expression you typed is sent to Nyquist. Output from Nyquist appears in a window below. You cannot type into or edit the output window text.
The normal way to use the NyquistIDE is to create or open one or more
files. You edit these files and then click the Load button. To load a
file, NyquistIDE saves the file, sets the current directory of Nyquist
to that of the file, then issues a load command to Nyquist. In
this case and several others, you may notice that NyquistIDE sends
expressions to Nyquist automatically for evaluation. You can always
see the commands and their results in the output window.
Notice that when you load a selected file window, NyquistIDE uses
setdir to change Nyquist's current directory. This helps to
keep the two programs in sync. Normally, you should keep all the files
of a project in the same directory and avoid manually changing
Nyquist's current directory (i.e. avoid calling setdir in your
code).
Arranging windows in the NyquistIDE can be time-consuming, and depending on the operating system, it is possible for a window to get into a position where you cannot drag it to a new position. The Window:Tile menu command can be used to automatically lay out windows in a rational way. There is a preference setting to determine the height of the completion list relative to the height of the output window.
Many of the key commands for editing files are standard and built into Java. In particular, Control-Z is the “undo” command, even on OS X where you would expect to use Command-Z. A special command, “Copy to Lisp,” or Control-U (Command-U on OS x)copies the selection and enters it into the input window as if it had been typed there.
There are a number of buttons with frequently-used operations. These are:
(co).(top) into Nyquist.
If the XLISP prompt is 1> or
some other integer followed by “>”, clicking the Top button
will exit the debug loop and return to the top-level prompt.(r) into Nyquist.
This command replays the last computed sound.(f2) etc. into Nyquist.
These commands are not built-in, and allow users to define their own
custom actions.To help with programming, NyquistIDE maintains a command-completion window. As you type the first letters of function names, NyquistIDE lists matching functions and their parameters in the Completion List window. If you click on an entry in this window, the displayed expression will replace the incompletely typed function name. A preference allows you to match initial letters or any substring of the complete function name. This is controlled by the “Use full search for code completion” preference.
In addition, if you right click (or under Mac OS X, hold down the Alt/Option key and click) on an entry, NyquistIDE will display documentation for the function. Documentation can come from a local copy or from the online copy (determined by the “Use online manual instead of local copy” preference). Documentation can be displayed within the NyquistIDE window or in an external browser (determined by the “Use window in NyquistIDE for help browser” preference.) Currently, the external browser option does not seem to locate documentation properly, but this should be fixed in the future.
The NyquistIDE Extension Manager is a facility to download extensions that are written in Lisp or SAL. (If you want to extend the nyquist program itself or the NyquistIDE program, you will have to write C or Java respectively and recompile. See Appendix Appendix 1: Extending Nyquist for information on writing new DSP functions, also known as unit generators.)
Selecting the Extension Manager item in the Window menu will open a window
in the NyquistIDE with a list of extensions. Each extension is stored as
a subdirectory of the lib directory, which should be on the search
path (XLISPPATH) for nyquist. A list of extensions is hosted
in a fixed location
(https://www.cs.cmu.edu/~music/nyquist/extensions/extlist.txt)
along with secure checksums to guard against malicious code.
When you install an extension, a single file is first downloaded using a URL that is obtained from the list of extensions, and the file is scanned for a header that can specify additional files to download.
Some special files may be included in an extension. autoload.lsp is
a Lisp file that is loaded automatically when nyquist is started. Nyquist
scans the subdirectories of the lib directory to find all the
autoload.lsp files. Typically, autoload.lsp files are used
to create stubs for functions in the extensions so that extension
code is mostly loaded dynamically on demand, saving time and space when
nyquist starts.
Extensions may also include nyquistwords.txt, which is a description
of functions in the extensions that is used to generate the completion list.
When an extension function appears in the completion list, it is followed by
"ext:" and the extension name, e.g. the completion item
"speed-dial(list) ext: dtmf" means that the speed-dial function is
defined in the dtmf directory. By convention, any function in the
completion list should be directly callable, with an entry in
autoload.lsp so that the function will be dynamically loaded.
To create a new extension, see the extension ext-template1 for an
example with documentation in HTML, or ext-template2 for a simple
single-file extension where the documentation consists of comments in the
SAL source file.
To submit an extension for possible publication, it is best to put the
extension file(s) in a local directory and use a customized local list of
extensions. The Nyquist Preferences includes a button where you can designate
a local file for the list of extensions. It should have the same format
as extlist.txt at the URL given above (you can simply open the URL
in your browser to see it. The extension under development
can be referenced in the extension list using a URL with the file://
protocol. For the checksum, use any value. The Extension Manager will compute
the correct checksum and display it, so you can then copy that into your
extlist.txt, click the Update button to fetch it, and try again to
install the extension.
If you click on the Browse button or use the Window:Browse menu command, NyquistIDE will display a browser window that is pre-loaded with a number of Nyquist commands to create sounds. You can adjust parameters, audition the sounds, and capture the expression that creates the sound. In many cases, the expression checks to see if necessary functions are defined, loading files if necessary before playing the sound. If you want to use a sound in your own program, you can often simplify things by explicitly loading the required file just once at the beginning of your file.
Since Nyquist now supports a mix of Lisp and SAL, you may find yourself in
the position of having code from the browser in one language while you are
working in the other. The best way to handle this is to put the code for
the sound you want into a function defined in a Lisp (.lsp) or SAL
(.sal) file. Load the file (from Lisp, use the sal-load
command to load a SAL file), and call the function from the language of
your choice.
The envelope editor allows you graphically to design and edit piece-wise linear and exponential envelopes. The editor maintains a list of envelopes and you select the one to edit or delete using the drop down list in the Saved Envelopes List area. The current envelope appears in the Graphical Envelope Editor area. You can click to add or drag points. Alternatively, you can use the Envelope Points window to select and edit any breakpoint by typing coordinates. The duration of the envelope is controlled by the Stop field in the Range area, and the vertical axis is controlled by the Min and Max fields.
When you click the Save button, all envelopes are written to Nyquist.
You can then use the envelope by treating the envelope name as a function.
For example, if you define an envelope named “fast-attack,” then you
can create the envelope within a Nyquist SAL program by writing
the expression fast-attack().
These edited envelopes are saved to a file named workspace.lsp
in
the current directory. The workspace is Nyquist's mechanism for saving
data of all kinds (see Section Workspaces). The normal way to
work with workspaces is to (1) load the workspace, i.e.
load "workspace", as soon as you start Nyquist; (2) invoke
the envelope editor to change values in the workspace; and (3) save the
workspace at any time, especially before you exit NyquistIDE. If you follow
these steps, envelopes will be preserved from session to session, and
the entire collection of envelopes will appear in the editor. Be
sure to make backups of your workspace.lsp file along with your
other project files.
The envelope editor can create linear and exponential envelopes. Use the
Type pull-down menu to select the type you want. Envelopes can be created
using default starting and ending values using pwl or pwe,
or you can specify the initial values using pwlv or pwev.
The envelope editor uses pwl or pwe if no point is explicitly
entered as the initial or final point. To create a pwlv or pwev
function, create a point and drag it to the leftmost or rightmost edge
of the graphical editing window. You will see the automatically
generated default starting or ending
point disappear from the graph.
Exponential envelopes should never decay to zero. If you enter a zero amplitude, you will see that the envelope remains at zero to the next breakpoint. To get an exponential decay to “silence,” try using an amplitude of about 0.001 (about -60dB). To enter small values like this, you can type them into the Amplitude box and click “Update Point.”
The Load button refreshes the editor from data saved in the Nyquist process. Normally, there is no need to use this because the editor automatically loads data when you open it.
The Equalizer Editor provides a graphical EQ interface for creating and
adjusting equalizers. Unlike the envelope editor, where you can type
any envelope name, equalizers are named eq-0, eq-1, etc.,
and you select the equalizer to edit using a pull-down menu. The Set
button should be use to record changes.
The UPIC Editor is inspired by the UPIC system by Iannis Xenakis at the Centre d'Edudes de Mathematique et Automatique Musicales (CEMaMu). The UPIC Editor is accessed by the “Upic Edit” menu item in the “Window” menu of the NyquistIDE. Once opened, you can draw pitch contours in the main panel by pressing the left mouse button and dragging with the mouse down. Contours represent tones in a frequency vs. time coordinate system. Any contour can be deleted by right-clicking (or shift-clicking on an Apple computer) to select the contour (indicated by the color red), and typing the Delete key.
A collection of contours can be saved to a file and later retrieved using the items in the File menu (use the File menu in the UPIC Editor window, not in the main NyquistIDE window.) The file is a SAL program in a special format that can be parsed by the UPIC Editor. The file can also be loaded into Nyquist using the File:Load menu item, or by executing a load command in Nyquist.
The panel at the top of the editor offers control over various parameters. The Name box is a Nyquist variable name. This name takes effect when you save a file from the UPIC Editor. The variable name is stored in the file so that when a UPIC Editor-generated file is loaded into Nyquist, the data is assigned to this variable name. The data is a list of contours, where each contour specifies a waveform, an envelope, and a list of time-frequency coordinates.
The next item in the panel is the Waveform box. The Waveform box names a
waveform for a contour. Default waveforms are sinusoid, triangle, and
sawtooth, but you can type in your own names. The currently selected
waveform is stored with the contour when it is created (entered by
drawing). You cannot change or edit the waveform name associated with
a contour once the contour is created, but you can always delete the
contour and replace it. The Envelope box names an envelope for a
contour. The envelope names a Nyquist function. The default, upic-env
is a trapezoid shape with an onset time and offset time of 10ms. As with
waveforms, the envelope is stored with each contour when the contour is
created and cannot be edited.
The Stop Time box gives the duration of the drawing area in seconds. The Min Freq box gives the minimum frequency (at the bottom of the drawing area), and the Max Freq box gives the maximum frequency (at the top of the drawing area). The vertical frequency axis can use a linear scale corresponding to frequency in Hertz or a logarithmic scale corresponding to semitones. The “linear” checkbox selects the linear scale. When any of these parameters (described in this paragraph and delimited by the border labeled “Range” on the control panel) is changed, you must press the Update Range button for the change to take effect.
The Background menu lets you display a grid that indicates pitch locations.
The “C's” item draws a line at C in every visible octave. E.g. middle C
is about 260 Hz, so a reference line will be drawn near 260 Hz.
Lines will be drawn around 130 Hz (an octave below middle C), and around
520 Hz (an octave above middle C), etc. The “GrandStaff” menu item
draws reference lines for each line of the grand staff commonly used
for piano music. The pitches are G2, B2, D3, F3, A3, E4, G4, B4, D5, and
F5. Finally, you can load a picture using the
Background:Load Picture... menu item. Then, the Background:Show Picture
menu item toggles whether the picture is displayed or not. This feature
allows you to trace an image. (For example, see the Sonic Self-Portrait
at http://www.cs.cmu.edu/~rbd.) You may wish to use an image editor
to lighten the image so that superimposed contours will be more visible.
Each change to the Range data, background choice, and each entry of a contour is an action that you can undo or redo with the Undo and Redo buttons.
To convert UPIC data into sound, first load upic.sal and load
a file generated by the UPIC Editor. Now, suppose the variable name
used is upicdata. You can play the data by writing
play upic(upicdata)
If you created your own names for waveforms or envelopes, you must be
sure that these exist before calling the upic function. Each
waveform must be the name of a variable which is set to a Nyquist
wave table. (See Section Waveforms for information on how
to create a wave table.) Also, each envelope must name a function with
no parameters that will return an amplitude envelope. The following is
the built-in definition for upic-env:
define function upic-env() return env(0.01, 0.01, 0.01, 1, 1, 1)
To make a custom envelope function named upic-smooth with a 0.2
second attack and a 0.3 second decay, you could write:
define function upic-smooth() return env(0.2, 0.01, 0.3, 1, 1, 1)