File: part16.html

package info (click to toggle)
nyquist 3.23%2Bds-1
links: PTS, VCS
area: main
in suites: trixie
size: 58,064 kB
sloc: ansic: 74,758; lisp: 18,104; java: 10,719; cpp: 6,688; sh: 171; xml: 58; makefile: 40; python: 15
file content (681 lines) | stat: -rw-r--r-- 41,805 bytes
parent folder | download | duplicates (2)
<!DOCTYPE html>
<html><head><title>Nyquist Libraries</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 = "part15.html">Previous Section</a> | <a href = "part17.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 = "185"><h2>Nyquist Libraries</h2></a><a name="index1335"></a>
<p>Nyquist is always growing with new functions. Functions that are most fundamental
are added to the core language. These functions are automatically loaded when you 
start Nyquist, and they are documented in the preceding chapters. Other functions seem
less central and are implemented as lisp files that you can load. Many 
of these functions and files are not included in the main distribution of 
Nyquist. Instead, they are extensions (see Section <a href = "part3.html#22">Extension Manager</a>).
Extensions 
are just like any other library except you must first install them with
the Extension Manager in the NyquistIDE, and each extension is in a separate
folder within the <code>lib</code> folder.</p>

<p>For example, to get statistics functions, <code>load "statistics"</code>, but to get
the phase vocoder test functions, first install the <code>pvoc</code> extension, 
and then <code>load "pvoc/phasevocoder.sal"</code>. In many cases, functions within
an extension will &ldquo;autoload,&rdquo; e.g. after you install the <code>labels</code>
extension, the first time you call <code>read-labels</code> or <code>write-labels</code>, 
<code>labels.sal</code> will be loaded automatically to define these functions, as
if the function had been loaded all along. Extensions also update the 
function call quick reference and completion feature in the NyquistIDE.</p>

<p>Many libraries are documented in one of the following
sections, but see the Extension Manager for possible new additions. Extensions
have documentation, which you can find using the Extension Manager.</p>
<a name = "186"><h3>Statistics</h3></a><a name="index1336"></a><a name="index1337"></a><a name="index1338"></a><a name="index1339"></a><a name="index1340"></a><a name="index1341"></a><a name="index1342"></a><a name="index1343"></a><a name="index1344"></a><a name="index1345"></a><a name="index1346"></a><a name="index1347"></a><a name="index1348"></a><a name="index1349"></a>
<p>The file <code>statistics.lsp</code> defines a class and functions to compute simple statistics, histograms, correlation, and some other tests. See the source code for complete details.</p>
<a name = "187"><h3>Plots</h3></a><a name="index1350"></a><a name="index1351"></a>
<p>The Nyquist IDE has a simple facility to plot signals. For more advanced plotting, you can use <code>gnuplot.sal</code> (<code>load "gnuplot.sal"</code>) to generate plots for <code>gnuplot</code>, a separate, but free program. See the source for details.</p>
<a name = "188"><h3>Labeling Audio Events, Marking Audio Times, Displaying Marked Audio Times</h3></a><a name="index1352"></a><a name="index1353"></a><a name="index1354"></a><a name="index1355"></a>
<p>The <code>labels.sal</code> program can convert lists to label files and label files to lists. Label files can be loaded along with audio in Audacity to show metadata. See the source for details.</p>
<a name = "189"><h3>Linear Regression</h3></a><a name="index1356"></a><a name="index1357"></a><a name="index1358"></a>
<p>See the <code>regression</code> extension and its <code>regression.sal</code> for
 simple linear regression functions.</p>
<a name = "190"><h3>Vector Math, Linear Algebra</h3></a><a name="index1359"></a><a name="index1360"></a><a name="index1361"></a><a name="index1362"></a><a name="index1363"></a><a name="index1364"></a><a name="index1365"></a><a name="index1366"></a><a name="index1367"></a><a name="index1368"></a><a name="index1369"></a><a name="index1370"></a><a name="index1371"></a><a name="index1372"></a>
<p>See <code>vectors.lsp</code> and <code>load "vectors"</code>
 for a simple implementation of vector arithmetic and other vector functions.
These &ldquo;vectors&rdquo; are implemented as lists, but there are functions to convert
to and from arrays.</p>
<a name = "191"><h3>JSON Input and Output</h3></a>
<p>JSON<a name="index1373"></a> is widely used in web technology, scientific
computing and many other areas. See <code>json.sal</code> and <code>load "json"</code> for a
simple implementation of JSON input and output. On input, JSON dictionaries
are represented as association lists and JSON arrays are represented as XLisp
arrays. Data can be retrieved from dictionaries using <code>json-field</code>. If
you are writing in Lisp, note that you can call <code>(sal-load "json")</code> to
load and compile <code>json.sal</code> so that you can call its functions from Lisp.</p>

<p>For output, you can either write a structure consisting of nested arrays 
and dictionaries (association lists), or you can call a sequence of functions
to, for example, begin writing an array, write each element of the array and
finish writing the array. This way, you can write JSON as the data is computed
rather than building a monolithic structure in Lisp and then writing it.</p>

<p>Note that Lisp is already able to read and write 
structured data, and if everyone used Lisp and SAL, there might not be any 
need for JSON. Nyquist scores are an example of data you can save to files in
a text format and read back in. So JSON is not recommended except for
interoperation with other non-Lisp systems.</p>
<a name = "192"><h3>Piano Synthesizer</h3></a>
<p>The piano synthesizer (library name is <code>pianosyn.lsp</code>) generates
realistic piano tones using a multiple wavetable implementation by Zheng (Geoffrey)
Hua and Jim Beauchamp, University of Illinois. Detailed
acknowledgements print when you load the file. Further information and
example code can be found in 
<code>nyquist/lib/piano/piano.htm</code><a name="index1374"></a><a name="index1375"></a>. 
There are several useful functions in this library. These functions auto-load the 
<code>pianoysn.lsp</code> file if it is not already loaded:
<dl>
<dt>
<code>piano-note(<a name="index1376"></a><a name="index1377"></a><i>duration</i>, <i>step</i>, 
<i>dynamic</i>)</code> [SAL]<br>

<code>(piano-note <i>duration</i> <i>step</i> <i>dynamic</i>)</code> [LISP]</dt>
<dd>Synthesizes a piano tone. <i>Duration</i> is the duration to the point of
key release, after which there is a rapid decay. <i>Step</i> is the pitch in half
steps, and <i>dynamic</i> is approximately equivalent to a MIDI key velocity
parameter. Use a value near 100 for a loud sound and near 10 for a soft sound.</p>
<dt><code>piano-note-2(<a name="index1378"></a><i>step</i>, <i>dynamic</i>)</code> [SAL]<br>

<code>(piano-note-2 <i>step</i> <i>dynamic</i>)</code> [LISP]</dt>
<dd>Similar to <code>piano-note</code> except the duration is nominally 1.0.<br><br>
<dt><code>piano-midi(<a name="index1379"></a><i>midi-file-name</i>)</code> [SAL]<br>

<code>(piano-midi <i>midi-file-name</i>)</code> [LISP]</dt>
<dd>Use the piano synthesizer 
to play a MIDI file. The file name (a string) is given by <i>midi-file-name</i>.<br><br>
<dt><code>piano-midi2file(<a name="index1380"></a><i>midi-file-name</i>, 
<i>sound-file-name</i>)</code> [SAL]<br>

<code>(piano-midi2file <i>midi-file-name</i> <i>sound-file-name</i>)</code> [LISP]</dt>
<dd>Use the piano synthesizer to play a MIDI file. The MIDI file
is given by <i>midi-file-name</i> and the (monophonic) result is written to the file
named <i>sound-file-name</i>.
</dd></dl><a name = "193"><h3>Dynamics Compression</h3></a>
<p>These functions in the <code>compress</code> extension
implement a compressor originally intended for noisy speech audio, but
usable in a variety of situations.
There are actually two compressors that can be used in 
series. The first, <code>compress</code>, is
a fairly standard one: it detects signal level with an RMS
detector and uses table-lookup to determine how much gain
to place on the original signal at that point. One bit of
cleverness here is that the RMS envelope is &ldquo;followed&rdquo; or
enveloped using <code>snd-follow</code>, which does look-ahead to anticipate
peaks before they happen.</p>

<p>The other interesting feature is <code>compress-map</code>, which builds 
a map in terms of compression and expansion. For speech, the recommended
procedure is to figure out the noise floor on the signal you are compressing
(for example, look at the signal where the speaker is not talking).
Use a compression map that leaves the noise alone and boosts
signals that are well above the noise floor. Alas, the <code>compress-map</code>
function is not written in these terms, so some head-scratching is
involved, but the results are quite good.</p>

<p>The second compressor is called <code>agc</code>, and it implements automatic gain
control that keeps peaks at or below 1.0. By combining <code>compress</code> and 
<code>agc</code>, you can process poorly recorded speech for playback on low-quality
speakers in noisy environments. The <code>compress</code> function modulates the 
short-term gain to to minimize the total dynamic range, keeping the speech at
a generally loud level, and the <code>agc</code> function rides the long-term gain
to set the overall level without clipping.</p>
<dl>
<dt>
<code>compress-map(<a name="index1381"></a><i>compress-ratio</i>, 
<i>compress-threshold</i>, 
<i>expand-ratio</i>, <i>expand-threshold</i>, limit: <i>limit</i>, transition: 
<i>transition</i>, verbose: <i>verbose</i>)</code> [SAL]<br>

<code>(compress-map <i>compress-ratio</i> <i>compress-threshold</i>
<i>expand-ratio</i> <i>expand-threshold</i> :limit <i>limit</i> :transition
<i>transition</i> :verbose <i>verbose</i>)</code> [LISP]</dt>
<dd>Construct
a map for the compress function. The map consists of two parts: a compression
part and an expansion part.
The intended use is to compress everything above <i>compress-threshold</i> by
<i>compress-ratio</i>, and to downward expand everything below <i>expand-threshold</i>
by <i>expand-ratio</i>.  Thresholds are in dB and ratios are dB-per-dB.
0dB corresponds to a peak amplitude of 1.0 or rms amplitude of 0.7
If the input goes above 0dB, the output can optionally be limited
by setting <code>limit:</code> (a keyword parameter) to <code>T</code>. 
This effectively changes 
the compression ratio to infinity at 0dB.  If <code>limit:</code> is <code>nil</code>
(the default), then the compression-ratio continues to apply above 0dB.<br><br>
<dt>Another keyword parameter, <code>transition:</code>, sets the amount below the
thresholds (in dB) that a smooth transition starts. The default is 0,
meaning that there is no smooth transition. The smooth transition is a
2nd-order polynomial that matches the slopes of the straight-line compression
curve and interpolates between them.<br><br>
<dt>If verbose is true (this is the default), the map is printed, showing,
for each dB value below zero of this input, what is the gain (in dB) 
indicated by the output. Only regions where the map is changing are 
printed because at lower values, the dB gain is constant.<br><br>
<dt>It is assumed that expand-threshold &lt;= compress-threshold &lt;= 0
The gain is unity at 0dB so if compression-ratio &gt; 1, then gain
will be greater than unity below 0dB.<br><br>
<dt>The result returned by this function is a sound for use in the <code>shape</code>
function. The sound maps input
dB to gain. Time 1.0 corresponds to 0dB, time 0.0 corresponds to
-100 dB, and time 2.0 corresponds to +100dB, so this is a 
100hz &ldquo;sample rate&rdquo; sound. The sound gives gain in dB.<br><br>
<dt><code>db-average(<a name="index1382"></a><i>input</i>, min: <i>mindb</i>)</code> [SAL]<br>

<code>(db-average <i>input</i> :min <i>mindb</i>)</code> [LISP]</dt>
<dd>Compute 
the average amplitude 
of <i>input</i> in dB. The result is a sound at a rate of about 40Hz based on RMS 
of <i>input</i> such that 0 (dB) corresponds to a sinusoid with a peak amplitude of 1.
This is the same dB estimate that is used in the <code>compress</code> function. If <i>mindb</i>
is specified and non-nil, the result samples below this value will be replaced by
<i>mindb</i>. For example, if you plot the <code>db-average</code> curve of an instrument with a 
range from -3 dB down to -30 dB, but silences exist at -90 dB, then most of 
the interesting values will be squeezed into the top 1/3 of a plot. Instead, if you 
specify <code>min</code> to be -30, then the interesting range will span the entire plot
(and silences will show up at -30 dB, the value of <code>min</code>).<br><br>
<dt><code>compress(<a name="index1383"></a><i>input</i>, <i>map</i>, <i>rise-time</i>, <i>fall-time</i> [, <i>lookahead</i>])</code> [SAL]<br>

<code>(compress <i>input</i> <i>map</i> <i>rise-time</i> <i>fall-time</i>
 [<i>lookahead</i>])</code> [LISP]</dt>
<dd>Compress 
<i>input</i> using <i>map</i>, a compression curve
probably generated by <code>compress-map</code> (see above). Adjustments in gain have
the given <i>rise-time</i> and <i>fall-time</i>. Lookahead tells how far ahead to look
at the signal, and is <i>rise-time</i> by default.<br><br>
<dt><code>agc(<a name="index1384"></a><a name="index1385"></a><a name="index1386"></a><i>input</i>,
<i>range</i>, <i>rise-time</i>, <i>fall-time</i> [, <i>lookahead</i>])</code> [SAL]<br>

<code>(agc <i>input</i> <i>range</i> <i>rise-time</i> <i>fall-time</i>
 [<i>lookahead</i>])</code> [LISP]</dt>
<dd>An automatic
gain control applied to <i>input</i>. The maximum gain in dB is <i>range</i>. Peaks
are attenuated to 1.0, and gain is controlled with the given <i>rise-time</i> and
<i>fall-time</i>. The look-ahead time default is <i>rise-time</i>.
</dd></dl><a name = "194"><h3>Clipping Softener</h3></a>
<p>The <code>clipsoften</code> extension was written to improve the quality of
poorly recorded speech. In recordings of speech, extreme clipping generates
harsh high frequency noise. This can sound particulary bad on small speakers
that will emphasize high frequencies. This problem can be ameliorated by 
low-pass filtering regions where clipping occurs. The effect is to dull the
harsh clipping. Intelligibility is not affected by much, and the result can
be much more pleasant on the ears. Clipping is detected simply by looking for
large signal values. Assuming 8-bit recording, this level is set to 126/127.</p>

<p>The function works by cross-fading between the normal signal and a filtered 
signal as opposed to changing filter coefficients.</p>
<dl>
<dt>
<code>soften-clipping(<a name="index1387"></a><a name="index1388"></a><i>snd</i>, 
<i>cutoff</i>)</code> [SAL]<br>

<code>(soften-clipping <i>snd</i> <i>cutoff</i>)</code> [LISP]</dt>
<dd>Filter the loud regions of a signal where clipping is likely
to have generated additional high frequencies. The input signal is <i>snd</i>
and <i>cutoff</i> is the filter cutoff frequency
(4 kHz is recommended for speech).
</dd></dl><a name = "195"><h3>Graphical Equalizer</h3></a>
<p>The library 
(<code>load "grapheq.lsp"</code>) works with the NyquistIDE's Equalizer window
(see Section <a href = "part3.html#25">Equalizer Editor</a>, but 
this library can be used directly in Nyquist programs for multi-band equalizers.
This implementation uses
Nyquist's <code>eq-band</code> function to split the incoming signal into different
frequency bands. Bands are spaced geometrically, e.g. each band could be one
octave, meaning that each successive band has twice the bandwidth. An interesting
possibility is using computed control functions to make the equalization change
over time.</p>
<dl>
<dt>
<code>nband-range(<a name="index1389"></a><a name="index1390"></a><a name="index1391"></a><i>input</i>, <i>gains</i>, <i>lowf</i>, <i>highf</i>)</code> [SAL]<br>

<code>(nband-range <i>input</i> <i>gains</i> <i>lowf</i> <i>highf</i>)</code> [LISP]</dt>
<dd>A graphical equalizer applied to 
<i>input</i> (a <code>SOUND</code>). The gain controls and number of bands is given by <i>gains</i>, an
ARRAY of <code>SOUND</code>s (in other words, a Nyquist multichannel <code>SOUND</code>). Any sound in the
array may be replaced by a <code>FLONUM</code>. The bands are
geometrically equally spaced from the lowest frequency <i>lowf</i> to the
highest frequency <i>highf</i> (both are <code>FLONUM</code>s).<br><br>
<dt><code>nband(<a name="index1392"></a><i>input</i>, <i>gains</i>)</code> [SAL]<br>

<code>(nband <i>input</i> <i>gains</i>)</code> [LISP]</dt>
<dd>A graphical equalizer, identical 
to <code>nband-range</code> with a range of 20 to 20,000 Hz.
</dd></dl><a name = "196"><h3>Sound Reversal</h3></a>
<p>The <code>reverse</code> extension implements functions to play sounds in reverse.
<dl>
<dt>
<code>s-reverse(<a name="index1393"></a><a name="index1394"></a><a name="index1395"></a><a name="index1396"></a><i>snd</i>)</code> [SAL]<br>

<code>(s-reverse <i>snd</i>)</code> [LISP]</dt>
<dd>Reverses <i>snd</i> (a <code>SOUND</code>). Sound must be shorter
than <code>*max-reverse-samples*</code>, which is currently initialized to 
25 million samples. Reversal allocates about 4 bytes per sample. This function
uses XLISP in the inner sample loop, so do not be surprised if it calls the 
garbage collector a lot and runs slowly. The result starts at the starting
time given by the current environment (not necessarily the starting time 
of <i>snd</i>). If <i>snd</i> has multiple channels, a multiple channel, 
reversed sound is returned.</p>
<dt><code>s-read-reverse(<a name="index1397"></a><a name="index1398"></a><i>filename</i>, time-offset: <i>offset</i>, srate: <i>sr</i>, dur: <i>dur</i>, nchans: <i>chans</i>, format: <i>format</i>, mode: <i>mode</i>, bits: <i>n</i>, swap: <i>flag</i>)</code> [SAL]<br>

<code>(s-read-reverse <i>filename</i> :time-offset <i>offset</i>
 :srate <i>sr</i> :dur <i>dur</i> :nchans <i>chans</i> :format <i>format</i> :mode <i>mode</i> 
:bits <i>n</i> :swap <i>flag</i>)</code> [LISP]</dt>
<dd>This function is 
identical to <code>s-read</code> (see Section <a href = "part8.html#100">Sound File Input and Output</a>), except it reads 
the indicated samples in reverse. Like
<code>s-reverse</code> (see above), it uses XLISP in the inner loop, so it is slow.
Unlike <code>s-reverse</code>, <code>s-read-reverse</code> uses a fixed amount of 
memory that is independent of how many samples are computed. Multiple channels
are handled. 
</dd></dl><a name = "197"><h3>Time Delay Functions</h3></a>
<p>The <code>time-delay-fns.lsp</code> library implements chorus, phaser, and 
flange effects.</p>
<dl>
<dt>
<code>phaser(<a name="index1399"></a><a name="index1400"></a><i>snd</i>)</code> [SAL]<br>

<code>(phaser <i>snd</i>)</code> [LISP]</dt>
<dd>A phaser effect
applied to <i>snd</i> (a <code>SOUND</code>). There are no parameters, 
but feel free to modify the source code of this one-liner.<br><br>
<dt><code>flange(<a name="index1401"></a><a name="index1402"></a><a name="index1403"></a><i>snd</i>)</code> [SAL]<br>

<code>(flange <i>snd</i>)</code> [LISP]</dt>
<dd>A flange effect
applied to <i>snd</i>. To vary the rate and other parameters, see the source code.<br><br>
<dt><code>stereo-chorus(<a name="index1404"></a><a name="index1405"></a><i>snd</i>, delay: <i>delay</i>, depth: <i>depth</i>, rate1: <i>rate1</i>, rate2: <i>rate2</i> saturation: <i>saturation</i>)</code> [SAL]<br>

<code>(stereo-chorus <i>snd</i> :delay <i>delay</i> :depth <i>depth</i>
:rate1 <i>rate1</i> :rate2 <i>rate2</i> :saturation <i>saturation</i>)</code> [LISP]</dt>
<dd>A chorus effect 
applied to <i>snd</i>,
a <code>SOUND</code> (monophonic). The output is a stereo sound with out-of-phase chorus effects applied separately for the left and right channels. See the <code>chorus</code> function below for a description of the optional parameters. The <i>rate1</i> and <i>rate2</i> parameters are <i>rate</i> parameters for the left and right channels.<br><br>
<dt><code>chorus(<a name="index1406"></a><a name="index1407"></a><i>snd</i>, delay: <i>delay</i>, depth: <i>depth</i>, rate: <i>rate</i>, saturation: <i>saturation</i>, phase: <i>phase</i>)</code> [SAL]<br>

<code>(chorus <i>snd</i> :delay <i>delay</i> :depth <i>depth</i> :rate <i>rate</i> :saturation <i>saturation</i> :phase <i>phase</i>)</code> [LISP]</dt>
<dd>A chorus effect applied to <i>snd</i>. All parameters may be arrays
as usual. The chorus is implemented as a variable delay 
modulated by a sinusoid shifted by <i>phase</i> degrees (a <code>FLONUM</code>) oscillating
at <i>rate</i> Hz (a <code>FLONUM</code>). The sinusoid is 
scaled by <i>depth</i> (a <code>FLONUM</code>. The delayed signal is mixed
with the original, and <i>saturation</i> (a <code>FLONUM</code>) gives the fraction of 
the delayed signal
(from 0 to 1) in the mix. 
Default values are <i>delay</i> 0.03, <i>depth</i> 0.003, <i>rate</i> 0.3, 
<i>saturation</i> 1.0, and <i>phase</i> 0.0 (degrees).
</dd></dl><a name = "198"><h3>Multiple Band Effects</h3></a><a name="index1408"></a><a name="index1409"></a>
<p>The <code>bandfx</code> extension implements several effects based on multiple
frequency bands. The idea is to separate a signal into different frequency
bands, apply a slightly different effect to each band, and sum the effected
bands back together to form the result. This file includes its own set of
examples. After loading the file, try <code>f2()</code>, <code>f3()</code>, <code>f4()</code>,
and <code>f5()</code> to hear them.
Further discussion and examples can be found in 
<code>nyquist/lib/bandfx/bandfx.lsp</code><a name="index1410"></a>. </p>

<p>There is much room for expansion and experimentation with this
library. Other effects might include distortion in certain bands (for
example, there are commercial effects that add distortion to low
frequencies to enhance the sound of the bass), separating bands into
different channels for stereo or multichannel effects, adding
frequency-dependent reverb, and performing dynamic compression,
limiting, or noise gate functions on each band. There are also
opportunities for cross-synthesis: using the content of bands
extracted from one signal to modify the bands of another. The simplest
of these would be to apply amplitude envelopes of one sound to
another. Please contact us (dannenberg@cs.cmu.edu) if you are
interested in working on this library.</p>
<dl>
<dt>
<code>apply-banded-delay(<a name="index1411"></a><a name="index1412"></a><i>s</i>, <i>lowp</i>, <i>highp</i>, <i>num-bands</i>, <i>lowd</i>, <i>highd</i>, <i>fb</i>, <i>wet</i>)</code> [SAL]<br>

<code>(apply-banded-delay <i>s</i> <i>lowp</i> <i>highp</i> <i>num-bands</i> <i>lowd</i> <i>highd</i> <i>fb</i> <i>wet</i>)</code> [LISP]</dt>
<dd>Separates
input <code>SOUND</code> <i>s</i> into <code>FIXNUM</code> <i>num-bands</i> bands from a
low frequency of <i>lowp</i> to a high frequency of <i>highp</i> (these are
<code>FLONUMS</code> that specify steps, not Hz), and applies a delay to
each band. The delay for the lowest band is given by the <code>FLONUM</code>
<i>lowd</i> (in seconds) and the delay for the highest band is given by
the <code>FLONUM</code> <i>highd</i>. The delays for other bands are linearly
interpolated between these values. Each delay has feedback gain
controlled by <code>FLONUM</code> <i>fb</i>. The delayed bands are scaled by
<code>FLONUM</code> <i>wet</i>, and the original sound is scaled by 1 -
<i>wet</i>. All are summed to form the result, a <code>SOUND</code>.<br><br>
<dt><code>apply-banded-bass-boost(<a name="index1413"></a><a name="index1414"></a><i>s</i>, <i>lowp</i>, <i>highp</i>, <i>num-bands</i>, <i>num-boost</i>, <i>gain</i>)</code> [SAL]<br>

<code>(apply-banded-bass-boost <i>s</i> <i>lowp</i> <i>highp</i> <i>num-bands</i> <i>num-boost</i> <i>gain</i>)</code> [LISP]</dt>
<dd>Applies a boost to low frequencies.
Separates input <code>SOUND</code> <i>s</i> into <code>FIXNUM</code> <i>num-bands</i>
bands from a low frequency of <i>lowp</i> to a high frequency of
<i>highp</i> (these are <code>FLONUMS</code> that specify steps, not Hz), and
scales the lowest <i>num-boost</i> (a <code>FIXNUM</code>) bands by <i>gain</i>, a
<code>FLONUM</code>. The bands are summed to form the result, a
<code>SOUND</code>.<br><br>
<dt><code>apply-banded-treble-boost(<a name="index1415"></a><a name="index1416"></a><i>s</i>, <i>lowp</i>, <i>highp</i>, <i>num-bands</i>, <i>num-boost</i>, <i>gain</i>)</code> [SAL]<br>

<code>(apply-banded-treble-boost <i>s</i> <i>lowp</i> <i>highp</i> <i>num-bands</i> <i>num-boost</i> <i>gain</i>)</code> [LISP]</dt>
<dd>Applies a boost to 
high frequencies. Separates input <code>SOUND</code> <i>s</i> into
<code>FIXNUM</code> <i>num-bands</i> bands from a low frequency of <i>lowp</i> to
a high frequency of <i>highp</i> (these are <code>FLONUMS</code> that specify
steps, not Hz), and scales the highest <i>num-boost</i> (a <code>FIXNUM</code>)
bands by <i>gain</i>, a <code>FLONUM</code>. The bands are summed to form the
result, a <code>SOUND</code>.  </dd></dl><a name = "199"><h3>Granular Synthesis</h3></a> 
<p>Some granular synthesis functions are implemented in the
<code>gran</code> extension. There are many variations and control
schemes one could adopt for granular synthesis, so it is impossible to
create a single universal granular synthesis function. One of the
advantages of Nyquist is the integration of control and synthesis
functions, and users are encouraged to build their own granular
synthesis functions incorporating their own control schemes. The
<code>gran.lsp</code> file includes many comments and is intended to be a
useful starting point. Another possibility is to construct a score
with an event for each grain. Estimate a few hundred bytes per score
event (obviously, size depends on the number of parameters) and avoid
using all of your computer's memory.</p>
<dl>
<dt>
<code>sf-granulate(<a name="index1417"></a><a name="index1418"></a><i>filename</i>, <i>grain-dur</i>, <i>grain-dev</i>, <i>ioi</i>, <i>ioi-dev</i>, <i>pitch-dev</i>, [<i>file-start</i>, <i>file-end</i>])</code> [SAL]<br>

<code>(sf-granulate <i>filename</i> <i>grain-dur</i> <i>grain-dev</i> <i>ioi</i>
<i>ioi-dev</i> <i>pitch-dev</i> [<i>file-start</i> <i>file-end</i>])</code> [LISP]</dt>
<dd>Granular synthesis 
using a sound file
named <i>filename</i> as the source for grains. Grains are extracted from
a sound file named by <i>filename</i> by stepping through the file in equal
increments. Each grain duration is the 
sum of <i>grain-dur</i> and a random number from 0 to <i>grain-dev</i>. Grains are 
then multiplied by a raised cosine smoothing window and resampled at a ratio
between 1.0 and <i>pitch-dev</i>. If <i>pitch-dev</i> is greater than one, grains are
stretched and the pitch (if any) goes down. If <i>pitch-dev</i> is less than one,
grains are shortened and the pitch goes up. Grains are then output
with an 
inter-onset interval between successive grains (which may overlap) 
determined by the sum of
<i>ioi</i> and a random number from 0 to <i>ioi-dev</i>. 
The duration of the resulting sound is determined by
the stretch factor (not by the sound file). The number of grains is
the total sound duration (determined by the stretch factor)
divided by the mean inter-onset interval, 
which is <i>ioi</i> + <i>ioi-dev</i> * 0.5. 
The grains are taken from equally-spaced starting points in <i>filename</i>,
and depending on grain size and number, the grains may or may not overlap.
The output duration will simply be the sum of the inter-onset intervals
and the duration of the last grain. If <i>ioi-dev</i> is non-zero, the
output duration will vary, but the expected value of the duration is
the stretch factor.
To achieve a rich granular synthesis effect, it is often a good idea to
sum four or more copies of <code>sf-granulate</code> together. (See the <code>gran-test</code>
function in <code>gran.lsp</code>.)
</dd></dl><a name = "200"><h3>Chowning FM Voices</h3></a>
<p>John Chowning developed voice synthesis methods using FM to simulate 
resonances for his 1981 composition "Phone." He later recreated the
synthesis algorithms in Max, and Jorge Sastre ported these to SAL. 
See <code>fm-voices-chowning</code> extension and documentation for more details.</p>
<a name = "201"><h3>Atonal Melody Composition</h3></a>
<p>Jorge Sastre contributed the <code>atonal-melodies</code> extension
that generates atonal melodies. You can find links to an example
score and audio file in the code and also at
<code>http://algocompbook.com/examples.html</code>.</p>
<a name = "202"><h3>MIDI Utilities</h3></a>
<p>The <code>midishow.lsp</code> library has functions that can print the contents of MIDI
files. This intended as a debugging aid.</p>
<dl>
<dt>
<code>midi-show-file(<a name="index1419"></a><a name="index1420"></a><a name="index1421"></a><i>file-name</i>)</code> [SAL]<br>

<code>(midi-show-file <i>file-name</i>)</code> [LISP]</dt>
<dd>Print the contents of a MIDI file to the console.<br><br>
<dt><code>midi-show(<a name="index1422"></a><i>the-seq</i> [, <i>out-file</i>])</code> [SAL]<br>

<code>(midi-show <i>the-seq</i> [<i>out-file</i>])</code> [LISP]</dt>
<dd>Print the
contents of the sequence <i>the-seq</i> to the file <i>out-file</i> (whose default value
is the console.)
</dd></dl><a name = "203"><h3>Reverberation</h3></a>
<p>The <code>reverb.lsp</code> library implements artificial reverberation.</p>
<dl>
<dt>
<code>reverb(<a name="index1423"></a><a name="index1424"></a><i>snd</i>, 
<i>time</i>)</code> [SAL]<br>

<code>(reverb <i>snd</i> <i>time</i>)</code> [LISP]</dt>
<dd>Artificial reverberation applied to <i>snd</i> with a decay time of
<i>time</i>.
</dd></dl><a name = "204"><h3>DTMF Encoding</h3></a><a name="index1425"></a><a name="index1426"></a>
<p>The <code>dtmf</code> extension implements DTMF encoding. DTMF is the 
&ldquo;touch tone&rdquo; code used by telephones.</p>
<dl>
<dt>
<code>dtmf-tone(<a name="index1427"></a><i>key</i>, <i>len</i>, <i>space</i>)</code> [SAL]<br>

<code>(dtmf-tone <i>key</i> <i>len</i> <i>space</i>)</code> [LISP]</dt>
<dd>Generate a
single DTMF tone. The <i>key</i> parameter is either a digit (a <code>FIXNUM</code>
from 0 through 9) or the atom <code>STAR</code> or <code>POUND</code>. The duration of
the done is given by <i>len</i> (a <code>FLONUM</code>) and the tone is followed by
silence of duration <i>space</i> (a <code>FLONUM</code>).<br><br>
<dt><code>speed-dial(<a name="index1428"></a><i>thelist</i>)</code> [SAL]<br>

<code>(speed-dial <i>thelist</i>)</code> [LISP]</dt>
<dd>Generates a sequence
of DTMF tones using the keys in <i>thelist</i> (a <code>LIST</code> of keys as
described above under <code>dtmf-tone</code>). The duration of each tone is 0.2
seconds, and the space between tones is 0.1 second. Use <code>stretch</code> to
change the &ldquo;dialing&rdquo; speed.
</dd></dl><a name = "205"><h3>Dolby Surround(R), Stereo and Spatialization Effects</h3></a><a name="index1429"></a><a name="index1430"></a><a name="index1431"></a><a name="index1432"></a>
<p>The <code>spatial</code> extension implements various functions for stereo
manipulation and spatialization. It also includes some functions for
Dolby Pro-Logic panning, which encodes left, right, center, and surround 
channels into stereo. The stereo signal can then be played through
a Dolby decoder to drive a surround speaker array. This library has
a somewhat simplified encoder, so you should certainly test the
output. Consider using a high-end encoder for critical work. There
are a number of functions in <code>spatial.lsp</code> for testing. See the
source code and extension documentation for more information.</p>
<dl>
<dt>
<code>stereoize(<a name="index1433"></a><a name="index1434"></a><a name="index1435"></a><i>snd</i>)</code> [SAL]<br>

<code>(stereoize <i>snd</i>)</code> [LISP]</dt>
<dd>Convert a mono sound, <i>snd</i>, to stereo. Four bands of 
equalization and some delay are used to create a stereo effect.<br><br>
<dt><code>widen(<a name="index1436"></a><a name="index1437"></a><i>snd</i>, <i>amt</i>)</code> [SAL]<br>

<code>(widen <i>snd</i> <i>amt</i>)</code> [LISP]</dt>
<dd>Artificially
widen the stereo field in <i>snd</i>, a two-channel sound. The amount of widening
is <i>amt</i>, which varies from 0 (<i>snd</i> is unchanged) to 1 (maximum widening).
The <i>amt</i> can be a <code>SOUND</code> or a number.<br><br>
<dt><code>span(<a name="index1438"></a><a name="index1439"></a><a name="index1440"></a><a name="index1441"></a><i>snd</i>, <i>amt</i>)</code> [SAL]<br>

<code>(span <i>snd</i> <i>amt</i>)</code> [LISP]</dt>
<dd>Pan the virtual center channel of a stereo sound, <i>snd</i>,
by <i>amt</i>, where 0 pans all the way to the left, while 1 pans all the way 
to the right. The <i>amt</i> can be a <code>SOUND</code> or a number.<br><br>
<dt><code>swapchannels(<a name="index1442"></a><a name="index1443"></a><a name="index1444"></a><i>snd</i>)</code> [SAL]<br>

<code>(swapchannels <i>snd</i>)</code> [LISP]</dt>
<dd>Swap left and right channels in <i>snd</i>, a stereo sound.<br><br>
<dt><code>prologic(<a name="index1445"></a><a name="index1446"></a><a name="index1447"></a><i>l</i>, <i>c</i>, 
<i>r</i>, <i>s</i>)</code> [SAL]<br>

<code>(prologic <i>l</i> <i>c</i> <i>r</i> <i>s</i>)</code> [LISP]</dt>
<dd>Encode four monaural <code>SOUND</code>s representing the front-left,
front-center, front-right, and rear channels, respectively. 
The return value is a stereo sound, which is a Dolby-encoded mix of the
four input sounds. <br><br>
<dt><code>pl-left(<a name="index1448"></a><i>snd</i>)</code> [SAL]<br>

<code>(pl-left <i>snd</i>)</code> [LISP]</dt>
<dd>Produce a Dolby-encoded (stereo)
signal with <i>snd</i>, a <code>SOUND</code>, encoded as the front left channel.<br><br>
<dt><code>pl-center(<a name="index1449"></a><i>snd</i>)</code> [SAL]<br>

<code>(pl-center <i>snd</i>)</code> [LISP]</dt>
<dd>Produce a Dolby-encoded (stereo)
signal with <i>snd</i>, a <code>SOUND</code>, encoded as the front center channel.<br><br>
<dt><code>pl-right(<a name="index1450"></a><i>snd</i>)</code> [SAL]<br>

<code>(pl-right <i>snd</i>)</code> [LISP]</dt>
<dd>Produce a Dolby-encoded (stereo)
signal with <i>snd</i>, a <code>SOUND</code>, encoded as the front right channel.<br><br>
<dt><code>pl-rear(<a name="index1451"></a><i>snd</i>)</code> [SAL]<br>

<code>(pl-rear <i>snd</i>)</code> [LISP]</dt>
<dd>Produce a Dolby-encoded (stereo)
signal with <i>snd</i>, a <code>SOUND</code>, encoded as the rear, or surround, channel.<br><br>
<dt><code>pl-pan2d(<a name="index1452"></a><i>snd</i>, <i>x</i>, <i>y</i>)</code> [SAL]<br>

<code>(pl-pan2d <i>snd</i> <i>x</i> <i>y</i>)</code> [LISP]</dt>
<dd>Comparable to Nyquist's
existing pan function, <code>pl-pan2d</code> provides not only left-to-right
panning, but front-to-back panning as well. The function
accepts three parameters: <i>snd</i> is the (monophonic) input <code>SOUND</code>, 
<i>x</i> is a left-to-right position, and <i>y</i> is a front-to-back position.
Both position parameters may be numbers or <code>SOUND</code>s. An <i>x</i> value 
of 0 means left, and 1 means right. Intermediate values map linearly
between these extremes. Similarly, a <i>y</i> value of 0 causes the sound
to play entirely through the front speakers(s), while 1 causes it to play
entirely through the rear. Intermediate values map linearly.
Note that, although there are usually two rear speakers in Pro-Logic systems,
they are both driven by the same signal. Therefore any sound that is
panned totally to the rear will be played over both rear speakers. For
example, it is not possible to play a sound exclusively through the 
rear left speaker.<br><br>
<dt><code>pl-position(<a name="index1453"></a><i>snd</i>, <i>x</i>, <i>y</i>, <i>config</i>)</code> [SAL]<br>

<code>(pl-position <i>snd</i> <i>x</i> <i>y</i> <i>config</i>)</code> [LISP]</dt>
<dd>The
position function builds upon speaker panning to allow more abstract
placement of sounds. Like <code>pl-pan2d</code>, it accepts a (monaural) input
sound as well as left-to-right (<i>x</i>) and front-to-back (<i>y</i>) coordinates,
which may be <code>FLONUM</code>s or <code>SOUND</code>s. A fourth parameter <i>config</i> 
specifies the distance from listeners to the speakers (in meters). Current
settings assume this to be constant for all speakers, but this assumption 
can be changed easily (see comments in the code for more detail).
There are several important differences between <code>pl-position</code> and 
<code>pl-pan2d</code>. First, <code>pl-position</code> uses a Cartesian coordinate 
system that allows x and y coordinates outside of the
range (0, 1). This model assumes a listener position of (0,0). Each speaker
has a predefined position as well. The input sound's position,
relative to the listener, is given by the vector (<i>x</i>,<i>y</i>).<br><br>
<dt><code>pl-doppler(<a name="index1454"></a><a name="index1455"></a><i>snd</i>, 
<i>r</i>)</code> [SAL]<br>

<code>(pl-doppler <i>snd</i> <i>r</i>)</code> [LISP]</dt>
<dd>Pitch-shift moving sounds according to the equation: <i>fr</i> =
<i>f0</i>((<i>c</i>+<i>vr</i>)/<i>c</i>), where <i>fr</i> is the output frequency, 
<i>f0</i> is the emitted (source) 
frequency, <i>c</i> is the speed of sound (assumed to be 344.31 m/s), and 
<i>vr</i> is the speed at which the emitter approaches the receiver. (<i>vr</i>
is the first derivative of parameter <i>r</i>, the distance from the listener
in meters.
</dd></dl><a name = "206"><h3>Drum Machine</h3></a><a name="index1456"></a>
<p>The drum machine software in the <code>plight</code> extension
deserves further explanation. There is documentation associated
with the extension and available in the NyquistIDE Extension Manager.
To use the software, install the extension and load the code by evaluating:
</p>
<pre>
load "plight/drum.lsp"
exec load-props-file(strcat(*plight-drum-path*, 
                            "beats.props"))
exec create-drum-patches()
exec create-patterns()
</pre>

<p></p>

<p>Drum sounds and patterns are specified in the <code>beats.props</code> file (or
whatever name you give to <code>load-props-file</code>). This file
contains two types of specifications. First, there are sound file specifications.
Sound files are located by a line of the form:
</p>
<pre>
set sound-directory = "kit/"
</pre>

<p>
This gives the name of the sound file directory, relative to the 
<code>beats.props</code> file. Then, for each sound file, there should be a line of
the form:
</p>
<pre>
track.2.5 = big-tom-5.wav
</pre>

<p>
This says that on track 2, a velocity value of 5 means to play the sound file
<code>big-tom-5.wav</code>. (Tracks and velocity values are described below.) 
The <code>beats.props</code> file contains specifications for all the sound files
in <code>nyquist/lib/plight/plight/kit</code> using 8 tracks. If you make your own specifications
file, tracks should be numbered consecutively from 1, and velocities should be
in the range of 1 to 9.</p>

<p>The second set of specifications is of beat patterns. A beat pattern is given
by a line in the following form:
</p>
<pre>
beats.5 = 2--32--43-4-5---
</pre>

<p>
The number after <code>beats</code> is just a pattern number. Each pattern
is given a unique number. After the equal sign, the digits and dashes are
velocity values where a dash means &ldquo;no sound.&rdquo; Beat patterns should be
numbered consecutively from 1.</p>

<p>Once data is loaded, there are several functions to access drum patterns and 
create drum sounds (described below). The <code>nyquist/lib/plight/plight/drums.lsp</code> file
contains an example function <code>plight-drum-example</code> to play some drums.
There is also the file <code>nyquist/lib/plight/beats.props</code> to serve as an
example of how to specify sound files and beat patterns.</p>
<dl>
<dt>
<code>drum(<a name="index1457"></a><i>tracknum</i>, <i>patternnum</i>, <i>bpm</i>)</code> [SAL]<br>

<code>(drum <i>tracknum</i> <i>patternnum</i> <i>bpm</i>)</code> [LISP]</dt>
<dd>Create
a sound by playing drums sounds associated with track <i>tracknum</i> (a 
FIXNUM) using pattern <i>patternnum</i>. The tempo is given by <i>bpm</i> in
beats per minute. Normally patterns are a sequence of sixteenth notes, so
the tempo is in <i>sixteenth notes per minute</i>. For example,
if <i>patternnum</i> is 10,
then use the pattern specified for <code>beats.10</code>. If the third character
of this pattern is 3 and <i>tracknum</i> is 5, then on the third beat, play
the soundfile assigned to <code>track.5.3</code>. This function returns a <code>SOUND</code>.<br><br>
<dt><code>drum-loop(<a name="index1458"></a><i>snd</i>, <i>duration</i>, <i>numtimes</i>)</code> [SAL]<br>

<code>(drum-loop <i>snd</i> <i>duration</i> <i>numtimes</i>)</code> [LISP]</dt>
<dd>Repeat the sound given by <i>snd</i> <i>numtimes</i> times. The repetitions occur at a time offset of <i>duration</i>, regardless of the actual duration of <i>snd</i>. A <code>SOUND</code> is returned.<br><br>
<dt><code>length-of-beat(<a name="index1459"></a><i>bpm</i>)</code> [SAL]<br>

<code>(length-of-beat <i>bpm</i>)</code> [LISP]</dt>
<dd>Given a tempo of 
<i>bpm</i>, return the duration of the beat in seconds. Note that this software
has no real notion of beat. A &ldquo;beat&rdquo; is just the duration of each character
in the beat pattern strings. This function returns a <code>FLONUM</code>.
</dd></dl>

<p></p>

<p></p>

<p></p>

<p></p>


<hr>
<a href = "part15.html">Previous Section</a> | <a href = "part17.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>