1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
|
<!DOCTYPE html>
<html><head><title>The NyquistIDE Program</title>
<link rel="stylesheet" type="text/css" href="nyquiststyle.css">
<link rel="icon" href="nyquist-icon.png" />
<link rel="shortcut icon" href="nyquist-icon.png" />
</head>
<body bgcolor="ffffff">
<a href = "part2.html">Previous Section</a> | <a href = "part4.html">Next Section</a> | <a href = "title.html#toc">Table of Contents</a> | <a href = "indx.html">Index</a> | <a href = "title.html">Title Page</a>
<hr>
<a name = "18"><h2>The NyquistIDE Program</h2></a>
<p>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.</p>
<a name = "19"><h3>NyquistIDE Overview</h3></a>
<p>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.</p>
<p>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 <code>load</code> 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.</p>
<p>Notice that when you load a selected file window, NyquistIDE uses
<code>setdir</code> 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 <code>setdir</code> in your
code).</p>
<p>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.</p>
<p>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.</p>
<a name = "20"><h3>The Button Bar</h3></a><a name="index110"></a>
<p>There are a number of buttons with frequently-used operations. These are:
<ul>
<li>
Info – <a name="index111"></a>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.</li>
<li>Break – <a name="index112"></a>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 <code>(co)</code>.</li>
<li>SAL/Lisp – <a name="index113"></a><a name="index114"></a>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.</li>
<li>Top – <a name="index115"></a>Enters <code>(top)</code> into Nyquist.
If the XLISP prompt is <code>1></code> or
some other integer followed by “<code>></code>”, clicking the Top button
will exit the debug loop and return to the top-level prompt.</li>
<li>Replay – <a name="index116"></a>Enters <code>(r)</code> into Nyquist.
This command replays the last computed sound.</li>
<li>F2-F12 – <a name="index117"></a>Enters <code>(f2)</code> etc. into Nyquist.
These commands are not built-in, and allow users to define their own
custom actions.</li>
<li>Browse – <a name="index118"></a>Equivalent to the Window:Browse
menu item. (See Section <a href = "#23">Browser</a>.)</li>
<li>EQ – <a name="index119"></a>Equivalent to the Window:EQ menu item.
(See Section <a href = "#25">Equalizer Editor</a>.)</li>
<li>EnvEdit – <a name="index120"></a>Equivalent to the Window:Envelope Edit
menu item. (See Section <a href = "#24">Envelope Editor</a>.)</li>
<li>NewFile – <a name="index121"></a>Equivalent to the File:New menu
item. Opens a new file editing window for creating and
loading a Lisp or SAL program file.</li>
<li>OpenFile – <a name="index122"></a>Equivalent to the File:Open menu
item. Opens an existing Lisp or SAL program file for editing and loading.</li>
<li>SaveFile – <a name="index123"></a>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.</li>
<li>Load – <a name="index124"></a>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.</li>
<li>Mark – <a name="index125"></a>Sends a Control-A to Nyquist. While
playing a sound, this displays and records the approximate time in the
audio stream. (See Section <a href = "part8.html#100">Sound File Input and Output</a> for more detail.)
</li></ul></p>
<a name = "21"><h3>Command Completion</h3></a>
<p>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.</p>
<p>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.</p>
<a name = "22"><h3>Extension Manager</h3></a>
<p>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 <a href = "part17.html#207">Appendix 1: Extending Nyquist</a> for information on writing new
DSP functions, also known as unit generators.)</p>
<p>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 <code>lib</code> directory, which should be on the search
path (<code>XLISPPATH</code>) for <code>nyquist</code>. A list of extensions is hosted
in a fixed location
(<code>https://www.cs.cmu.edu/~music/nyquist/extensions/extlist.txt</code>)
along with secure checksums to guard against malicious code.</p>
<p>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.</p>
<p>Some special files may be included in an extension. <code>autoload.lsp</code> is
a Lisp file that is loaded automatically when nyquist is started. Nyquist
scans the subdirectories of the <code>lib</code> directory to find all the
<code>autoload.lsp</code> files. Typically, <code>autoload.lsp</code> 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.</p>
<p>Extensions may also include <code>nyquistwords.txt</code>, 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 <code>speed-dial</code> function is
defined in the <code>dtmf</code> directory. By convention, any function in the
completion list should be directly callable, with an entry in
<code>autoload.lsp</code> so that the function will be dynamically loaded.</p>
<p>To create a new extension, see the extension <code>ext-template1</code> for an
example with documentation in HTML, or <code>ext-template2</code> for a simple
single-file extension where the documentation consists of comments in the
SAL source file. </p>
<p>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 <code>extlist.txt</code> 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 <code>file://</code>
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
<code>extlist.txt</code>, click the Update button to fetch it, and try again to
install the extension.</p>
<a name = "23"><h3>Browser</h3></a><a name="index126"></a><a name="index127"></a>
<p>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.</p>
<p>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 (<code>.lsp</code>) or SAL
(<code>.sal</code>) file. Load the file (from Lisp, use the <code>sal-load</code>
command to load a SAL file), and call the function from the language of
your choice.</p>
<a name = "24"><h3>Envelope Editor</h3></a><a name="index128"></a><a name="index129"></a><a name="index130"></a>
<p>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.</p>
<p>When you click the Save button, <i>all</i> 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 <code>fast-attack()</code>.</p>
<p>These edited envelopes are saved to a file named <code>workspace.lsp</code>
<a name="index131"></a> in
the current directory. The workspace is Nyquist's mechanism for saving
data of all kinds (see Section <a href = "part15.html#183">Workspaces</a>). The normal way to
work with workspaces is to (1) load the workspace, i.e.
<code>load "workspace"</code>, 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 <code>workspace.lsp</code> file along with your
other project files.</p>
<p>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 <code>pwl</code> or <code>pwe</code>,
or you can specify the initial values using <code>pwlv</code> or <code>pwev</code>.
The envelope editor uses <code>pwl</code> or <code>pwe</code> if no point is explicitly
entered as the initial or final point. To create a <code>pwlv</code> or <code>pwev</code>
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.</p>
<p>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.”</p>
<p>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.</p>
<a name = "25"><h3>Equalizer Editor</h3></a><a name="index132"></a><a name="index133"></a>
<p>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 <code>eq-0</code>, <code>eq-1</code>, etc.,
and you select the equalizer to edit using a pull-down menu. The <code>Set</code>
button should be use to record changes. </p>
<a name = "26"><h3>UPIC Editor</h3></a><a name="index134"></a><a name="index135"></a><a name="index136"></a>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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, <code>upic-env</code>
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.</p>
<p>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 <i>any</i> 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.</p>
<p>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 <code>http://www.cs.cmu.edu/~rbd</code>.) You may wish to use an image editor
to lighten the image so that superimposed contours will be more visible.</p>
<p>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.</p>
<p>To convert UPIC data into sound, first load <code>upic.sal</code> and load
a file generated by the UPIC Editor. Now, suppose the variable name
used is <code>upicdata</code>. You can play the data by writing
</p>
<pre>
play upic(upicdata)
</pre>
<p>
If you created your own names for waveforms or envelopes, you must be
sure that these exist before calling the <code>upic</code> function. Each
waveform must be the name of a variable which is set to a Nyquist
wave table. (See Section <a href = "part2.html#11">Non-Sinusoidal Waveforms</a> 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 <code>upic-env</code>:
</p>
<pre>
define function upic-env()
return env(0.01, 0.01, 0.01, 1, 1, 1)
</pre>
<p>
To make a custom envelope function named <code>upic-smooth</code> with a 0.2
second attack and a 0.3 second decay, you could write:
</p>
<pre>
define function upic-smooth()
return env(0.2, 0.01, 0.3, 1, 1, 1)
</pre>
<p></p>
<hr>
<a href = "part2.html">Previous Section</a> | <a href = "part4.html">Next Section</a> | <a href = "title.html#toc">Table of Contents</a> | <a href = "indx.html">Index</a> | <a href = "title.html">Title Page</a>
</body></html>
|
