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

## The NyquistIDE Program

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.

### NyquistIDE Overview

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. A special command, “Copy to Lisp,” or Control-U (Command-U on macOS) copies the selection and enters it into the input window as if it had been typed there.

### The Button Bar

There are a number of buttons with frequently-used operations. These are:

- Info – Print information about Nyquist memory utilization, including the number of free cons cells, the number of garbage collections, the total number of cons cells, the total amount of sample buffer memory, and the amount of memory in free sample buffers.
- Break – Send a break character to XLISP. This can be used to enter the debugger (the break loop) while a program is running. Resume by typing `(co)`.
- SAL/Lisp – Switch modes. The button names the mode (SAL or Lisp) you will switch to, not the current mode. For example, if you are in Lisp mode and want to type a SAL command, click the SAL button first.
- Top – Enters `(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.
- Replay – Enters `(r)` into Nyquist. This command replays the last computed sound.
- F2-F12 – Enters `(f2)` etc. into Nyquist. These commands are not built-in, and allow users to define their own custom actions.
- Browse – Equivalent to the Window:Browse menu item. (See Section Browser.)
- EQ – Equivalent to the Window:EQ menu item. (See Section Equalizer Editor.)
- EnvEdit – Equivalent to the Window:Envelope Edit menu item. (See Section Envelope Editor.)
- NewFile – Equivalent to the File:New menu item. Opens a new file editing window for creating and loading a Lisp or SAL program file.
- OpenFile – Equivalent to the File:Open menu item. Opens an existing Lisp or SAL program file for editing and loading.
- SaveFile – Equivalent to the File:Save menu item (found on the editing window's menu bar). Saves the contents of an editing window to its associated file.
- Load – Equivalent to the File:Load menu item (found on the editing window's menu bar). Performs a Save operation, then sends a command to Nyquist that loads the file as a program.
- Mark – Sends a Control-A to Nyquist. While playing a sound, this displays and records the approximate time in the audio stream. (See Section Sound File Input and Output for more detail.)

### Command Completion

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

### Extension Manager

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.

### Browser

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.

### Envelope Editor

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.

### Equalizer Editor

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.

### UPIC Editor

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 Non-Sinusoidal 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)

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