File: sndclm.html

package info (click to toggle)
snd 25.9-1
links: PTS, VCS
area: main
in suites: forky, sid
size: 44,016 kB
sloc: ansic: 291,818; lisp: 260,387; ruby: 71,134; sh: 3,293; fortran: 2,342; csh: 1,062; cpp: 294; makefile: 294; python: 87; xml: 27; javascript: 1
file content (10917 lines) | stat: -rw-r--r-- 422,747 bytes
parent folder | download | duplicates (2)
<!DOCTYPE html>

<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" >
<title>CLM</title>
<style type="text/css">
	EM.red {color:red; font-style: normal}
	EM.gen {font-weight: bold; font-style: normal}
        EM.error {color:chocolate; font-style: normal}
        EM.narg {color:chocolate; font-style: normal}
	H1 {text-align: center}
	DIV.centered {text-align: center}
	UL {list-style-type: none}
	EM.emdef {font-weight: bold; font-style: normal; padding-right: 0.2cm}
	EM.noem {font-style: normal}

	A {text-decoration:none}
	A:hover {text-decoration:underline}
	A.quiet {color:black; text-decoration:none}
	A.quiet:hover {text-decoration:underline}
	A.invisible {color:white; text-decoration:none}
	A.def {font-weight: bold; font-style: normal; text-decoration:none; text-color:black; padding-right: 0.2cm}
	A.olddef {font-style: normal; text-decoration:none; color:gray; padding-right: 0.2cm}
	EM.gray {color:gray; font-style: normal}
	EM.def {font-weight: bold; font-style: normal; text-decoration:none; text-color:black; padding-right: 0.2cm}

        TD.green {background-color: lightgreen}
	PRE.bluish {background-color: #f2f4ff}
	TD.beige {background-color: beige}
        TD.greenish {background-color: #eefdee}
        PRE.indented {padding-left: 1.0cm}
	IMG.indented {margin-left: 2.0cm}

	TH.beige {background-color: beige;
	          border: 1px solid black;
		  padding-left: 0.2cm;
		  padding-right: 0.2cm;
		  padding-top: 0.1cm;
		  padding-bottom: 0.1cm;
		  }
	TD.br {border: 1px solid lightgray;
		  padding-left: 0.2cm;
		  padding-right: 0.2cm;
		  padding-top: 0.1cm;
		  padding-bottom: 0.1cm;
	       }
	TD.hightop {padding-top: 0.5cm;
           	   }
        IMG.noborder {border: none}
	DIV.center {text-align: center}
	DIV.scheme {background-color: #f2f4ff;
	            border: 1px solid gray;
		    padding-right: 1.0cm;
		    margin-bottom: 0.2cm;
		    }
	DIV.ruby {background-color: #fbfbf0;
	            border: 1px solid gray;
		    padding-right: 1.0cm;
		    margin-bottom: 0.2cm;
		    }
	DIV.forth {background-color: #eefdee;
	            border: 1px solid gray;
		    padding-right: 1.0cm;
		    margin-bottom: 0.2cm;
		    }
	DIV.c {background-color: #f0f0f0;
	            border: 1px solid gray;
		    padding-right: 1.0cm;
		    margin-bottom: 0.2cm;
		    }
	DIV.lisp {background-color: aliceblue;
	            border: 1px solid gray;
		    padding-right: 1.0cm;
		    margin-bottom: 0.2cm;
		    }

        BODY.body {background-color: #ffffff;    /* white */
	           margin-left: 0.5cm; 
		   margin-right: 0.5cm;
                   }
        TABLE.borderspaced {margin-top: 0.5cm;
	              margin-bottom: 0.5cm;
		      margin-left: 0.5cm;
		      border: 8px solid gray;
		      }	
        TABLE.pb {margin-top: 0.1cm;
	              margin-bottom: 0.5cm;
		      margin-left: 2.0cm;
		      border: 2px solid gray;
		      padding-left: 0.2cm;
		      padding-right: 0.2cm;
		      padding-top: 0.2cm;
		      padding-bottom: 0.2cm;
		      }	
        TABLE.grayborder {margin-top: 0.5cm;
                      margin-bottom: 0.5cm;
		      margin-left: 1.0cm;
		      border: 8px solid gray;
		      padding-left: 0.1cm;
		      padding-right: 0.1cm;
		      padding-top: 0.1cm;
		      padding-bottom: 0.1cm;
	               }
        TABLE.contents {margin-top: 0.5cm;
                      margin-bottom: 0.5cm;
		      margin-left: 1.0cm;
		      border: 8px solid lightgray;
		      padding-left: 0.1cm;
		      padding-right: 0.1cm;
		      padding-top: 0.1cm;
		      padding-bottom: 0.1cm;
	               }
        TABLE.method {margin-top: 0.2cm;
                      margin-bottom: 0.5cm;
		      margin-left: 1.0cm;
		      border: 1px solid gray;
		      padding-left: 0.1cm;
		      padding-right: 0.1cm;
		      padding-top: 0.1cm;
		      padding-bottom: 0.1cm;
		      }	    
        TD.sumtitle {background-color: #eefdee;
		  border: 1px solid lightgray;
		  padding-top: 0.2cm;	
		  padding-bottom: 0.2cm;
		  text-align: center;
		  }
        TD.methodtitle {background-color: beige;
		  border: 1px solid gray;
		  padding-top: 0.2cm;	
		  padding-bottom: 0.2cm;
		  text-align: center;
		  }
        TD.inner {padding-right: 0.5cm;
	          padding-top: 0.1cm;
	         }
        TD.center {text-align: center}		 
        DIV.separator {margin-top: 40px;
	               margin-bottom: 15px;
	               border: 2px solid #00ff00; /* green */
		       background-color: #f5f5dc; /* beige */
		       padding-top: 4px;
		       width: 30%;
		      border-radius: 4px;
		      -moz-border-radius: 4px;
		      -webkit-border-radius: 4px;
		      } 
        DIV.topheader {margin-top: 10px;
	            margin-bottom: 40px;
	            border: 4px solid #00ff00; /* green */
		    background-color: #f5f5dc; /* beige */
		    font-family: 'Helvetica';
		    font-size: 30px;
		    text-align: center;
		    padding-top: 10px;
		    padding-bottom: 10px;
	           }
        DIV.header {margin-top: 50px;
	            margin-bottom: 10px;
		    font-size: 20px;
		    font-weight: bold;
	            border: 4px solid #00ff00; /* green */
		    background-color: #f5f5dc; /* beige */
		    text-align: center;
		    padding-top: 20px;
		    padding-bottom: 20px;
	           }
        DIV.innerheader {margin-top: 60px;
	            margin-bottom: 30px;
	            border: 4px solid #00ff00; /* green */
		    background-color: #eefdee; /* lightgreen */
		    padding-left: 30px;
		    width: 50%;
		    padding-top: 20px;
		    padding-bottom: 20px;
	           }
	DIV.related {text-align:center;
	             border: 1px solid lightgray;
		     margin-top: 1.0cm;
		     margin-bottom: 1.0cm;
		     padding-top: 10px;
		     padding-bottom: 10px;
		     background-color: #f0f0f0;
	            }
        DIV.inset {margin-left: 2.0cm;
	           margin-right: 2.0cm;
		   margin-top: 0.5cm;
		   margin-bottom: 0.5cm;
		   background-color: #f0f0f0;
		   padding-left: 0.25cm;
		   padding-right: 0.25cm;
		   padding-top: 0.25cm;
		   padding-bottom: 0.25cm;
		   }
        DIV.inset_inline {background-color: #f0f0f0;
	                  display: inline;
			  margin-left: 2.0cm;
		   padding-left: 0.25cm;
		   padding-right: 0.25cm;
		   padding-top: 0.25cm;
		   padding-bottom: 0.25cm;
			  }
        DIV.contentscenter {text-align: center;
		   padding-top: 0.25cm;
		   padding-bottom: 0.25cm;
                   border: 1px solid gray;
               	   }
	TD.ic {
		   padding-left: 0.5cm;
		   padding-right: 0.1cm;
		   }	
</style>


<!-- the latex stuff is always embedded in:

\documentclass{amsart}
\begin{document}
\thispagestyle{empty}
\small
\begin{displaymath}
...
\end{displaymath}
\end{document}

where the "displaymath" lines change to fit the situation


in the new (FC9) latex/pdf2png case, I need:

\documentclass[fleqn,11pt]{amsart}

\setlength\paperwidth{1500pt}
\setlength\textwidth{1200pt}

\begin{document}
...

and then in the output PDF file, set the line
/MediaBox [0 0 595.276 841.89]
to something like
/MediaBox [0 0 1595.276 841.89]
before calling pdf2png

pdf2png is in the cairo tarball (cairo/test dir)
-->

</head>
<body class="body">


<div class="topheader" id="sndclmtop">CLM</div>


<p>CLM (originally an acronym for Common Lisp Music) is a sound synthesis
package in the Music V family.  This file describes CLM as implemented in Snd,
aiming primarily at the Scheme version.
CLM is based on a set of functions known
as "generators".  These can be packaged into "instruments", and instrument calls
can be packaged into "note lists".  (These names are just convenient historical artifacts).
The main emphasis here is on the generators;
note lists and instruments are described in <a href="sndscm.html">sndscm.html</a>.
</p>


<div class="center">Bill Schottstaedt (bil@ccrma.stanford.edu)</div>


<div class="related">
related documentation: &nbsp;
<a href="snd.html">snd.html &nbsp;</a>
<a href="extsnd.html">extsnd.html &nbsp;</a>
<a href="grfsnd.html">grfsnd.html &nbsp;</a>
<a href="sndscm.html">sndscm.html &nbsp;</a>
<a href="fm.html">fm.html &nbsp;</a>
<a href="sndlib.html">sndlib.html &nbsp;</a>
<a href="s7.html">s7.html &nbsp;</a>
<a href="s7-ffi.html">s7-ffi.html &nbsp;</a>
<a href="s7-scm.html">s7-scm.html &nbsp;</a>
<a href="index.html">index.html</a>
</div>



<div class="header">Contents</div>


<table class="grayborder">

<tr><td colspan=4><div class="contentscenter"><a href="#introduction">Introduction</a></div></td></tr>

<tr><td colspan=4><div class="contentscenter"><a href="#generators">Built-in Generators</a></div></td></tr>

  <tr><td class="ic"><a href="#all-passdoc">all-pass</a></td><td class="ic">all-pass filter</td>
      <td class="ic"><a href="#nrxydoc">nrxysin</a></td><td class="ic">n scaled sines</td></tr>
  <tr><td class="ic"><a href="#asymmetric-fmdoc">asymmetric-fm</a></td><td class="ic">asymmetric fm</td>
      <td class="ic"><a href="#ncosdoc">nsin</a></td><td class="ic">n equal amplitude sines</td></tr>
  <tr><td class="ic"><a href="#combdoc">comb</a></td><td class="ic">comb filter</td>
      <td class="ic"><a href="#one-poledoc">one-pole</a></td><td class="ic">one pole filter</td></tr>
  <tr><td class="ic"><a href="#convolvedoc">convolve</a></td><td class="ic">convolution</td>
      <td class="ic"><a href="#one-poledoc">one-zero</a></td><td class="ic">one zero filter</td></tr>
  <tr><td class="ic"><a href="#delaydoc">delay</a></td><td class="ic">delay line</td>
      <td class="ic"><a href="#oscildoc">oscil</a></td><td class="ic">sine wave and FM</td></tr>
  <tr><td class="ic"><a href="#envdoc">env</a></td><td class="ic">line segment envelope</td>
      <td class="ic"><a href="#in-anydoc">out-any</a></td><td class="ic">sound output</td></tr>
  <tr><td class="ic"><a href="#filetosampledoc">file-&gt;sample</a></td><td class="ic">input sample from file</td>
      <td class="ic"><a href="#phase-vocoderdoc">phase-vocoder</a></td><td class="ic">vocoder analysis and resynthesis</td></tr>
  <tr><td class="ic"><a href="#filetoframple">file-&gt;frample</a></td><td class="ic">input frample from file</td>
      <td class="ic"><a href="#polywavedoc">polyshape and polywave</a></td><td class="ic">waveshaping</td></tr>
  <tr><td class="ic"><a href="#filterdoc">filter</a></td><td class="ic">direct form FIR/IIR filter</td>
      <td class="ic"><a href="#sawtoothdoc">pulse-train</a></td><td class="ic">pulse train</td></tr>
  <tr><td class="ic"><a href="#combdoc">filtered-comb</a></td><td class="ic">comb filter with filter on feedback</td>
      <td class="ic"><a href="#randdoc">rand, rand-interp</a></td><td class="ic">random numbers, noise</td></tr>
  <tr><td class="ic"><a href="#filterdoc">fir-filter</a></td><td class="ic">FIR filter</td>
      <td class="ic"><a href="#readindoc">readin</a></td><td class="ic">sound input</td></tr>
  <tr><td class="ic"><a href="#formantdoc">formant and firmant</a></td><td class="ic">resonance</td>
      <td class="ic"><a href="#sampletofile">sample-&gt;file</a></td><td class="ic">output sample to file</td></tr>
  <tr><td class="ic"><a href="#frampletofile">frample-&gt;file</a></td><td class="ic">output frample to file</td>
      <td class="ic"><a href="#sawtoothdoc">sawtooth-wave</a></td><td class="ic">sawtooth</td></tr>
  <tr><td class="ic"><a href="#granulatedoc">granulate</a></td><td class="ic">granular synthesis</td>
      <td class="ic"><a href="#sawtoothdoc">square-wave</a></td><td class="ic">square wave</td></tr>
  <tr><td class="ic"><a href="#filterdoc">iir-filter</a></td><td class="ic">IIR filter</td>
      <td class="ic"><a href="#srcdoc">src</a></td><td class="ic">sampling rate conversion</td></tr>
  <tr><td class="ic"><a href="#in-anydoc">in-any</a></td><td class="ic">sound file input</td>
      <td class="ic"><a href="#ssb-amdoc">ssb-am</a></td><td class="ic">single sideband amplitude modulation</td></tr>
  <tr><td class="ic"><a href="#locsigdoc">locsig</a></td><td class="ic">static sound placement</td>
      <td class="ic"><a href="#table-lookupdoc">table-lookup</a></td><td class="ic">interpolated table lookup</td></tr>
  <tr><td class="ic"><a href="#move-sounddoc">move-sound</a></td><td class="ic">sound motion</td>
      <td class="ic"><a href="#delaydoc">tap</a></td><td class="ic">delay line tap</td></tr>
  <tr><td class="ic"><a href="#moving-averagedoc">moving-average</a></td><td class="ic">moving window average</td>
      <td class="ic"><a href="#sawtoothdoc">triangle-wave</a></td><td class="ic">triangle wave</td></tr>
  <tr><td class="ic"><a href="#ncosdoc">ncos</a></td><td class="ic">n equal amplitude cosines</td>
      <td class="ic"><a href="#one-poledoc">two-pole</a></td><td class="ic">two pole filter</td></tr>
  <tr><td class="ic"><a href="#combdoc">notch</a></td><td class="ic">notch filter</td>
      <td class="ic"><a href="#one-poledoc">two-zero</a></td><td class="ic">two zero filter</td></tr>
  <tr><td class="ic"><a href="#nrxydoc">nrxycos</a></td><td class="ic">n scaled cosines</td>
      <td class="ic"><a href="#wave-traindoc">wave-train</a></td><td class="ic">wave train</td></tr>

<tr><td colspan=4><div class="contentscenter"><a href="#genericfunctions">Generic Functions</a></div></td></tr>

<tr><td colspan=4><div class="contentscenter"><a href="#othergenerators">Other Generators</a></div></td></tr>

<tr><td colspan=4><div class="contentscenter"><a href="#otherfunctions">Other Functions</a></div></td></tr>

  <tr><td class="ic"><a href="#autocorrelate">autocorrelate</a></td><td class="ic">autocorrelation</td>
      <td class="ic"><a href="#dot-product">dot-product</a></td><td class="ic">dot (scalar) product</td></tr>
  <tr><td class="ic"><a href="#amplitude-modulate">amplitude-modulate</a></td><td class="ic">sig1 * (car + sig2)</td>
      <td class="ic"><a href="#fft">fft</a></td><td class="ic">Fourier transform</td></tr>
  <tr><td class="ic"><a href="#array-interp">array-interp</a></td><td class="ic">array interpolation</td>
      <td class="ic"><a href="#make-fft-window">make-fft-window</a></td><td class="ic">various standard windows</td></tr>
  <tr><td class="ic"><a href="#contrast-enhancement">contrast-enhancement</a></td><td class="ic">modulate signal</td>
      <td class="ic"><a href="#polynomial">polynomial</a></td><td class="ic">Horner's rule</td></tr>
  <tr><td class="ic"><a href="#convolution">convolution</a></td><td class="ic">convolve signals</td>
      <td class="ic"><a href="#ring-modulate">ring-modulate</a></td><td class="ic">sig * sig</td></tr>
  <tr><td class="ic"><a href="#correlate">correlate</a></td><td class="ic">cross correlation</td>
      <td class="ic"><a href="#spectrum">spectrum</a></td><td class="ic">power spectrum of signal</td></tr>

<tr><td colspan=4><div class="contentscenter"><a href="#instruments">Instruments</a></div></td></tr>

</table>



<div class="header" id="introduction">Introduction</div>

<p>Start Snd, open the listener (choose "Show listener" in the View menu), and:
</p>

<pre class="indented">
&gt; (load "v.scm")
fm-violin
&gt; (with-sound () (fm-violin 0 1 440 .1))
"test.snd"
</pre>

<p>
If all went well, you should see a graph of the fm-violin's output.  Click the "play" button to
hear it; click "f" to see its spectrum.
</p>

<p>
In Ruby, we'd do it this way:
</p>

<pre class="indented">
&gt;load "v.rb"
true
&gt;with_sound() do fm_violin_rb(0, 1.0, 440.0, 0.1) end
#&lt;With_CLM: output: "test.snd", channels: 1, srate: 22050&gt;
</pre>

<p>and in Forth:
</p>
<pre class="indented">
snd&gt; "clm-ins.fs" file-eval
0
snd&gt; 0.0 1.0 440.0 0.1 ' fm-violin with-sound
\ filename: test.snd
</pre>


<p>In most of this document, I'll stick with Scheme as implemented by s7.  
<a href="extsnd.html">extsnd.html</a> and <a href="sndscm.html">sndscm.html</a> have numerous
Ruby and Forth examples, and I'll toss some in here as I go along.
You can save yourself a lot of typing by using two features of the listener.  First, &lt;TAB&gt; (that is, the key marked TAB) tries to complete 
the current name, so if you type "fm-&lt;TAB&gt;" the listener completes the name as "fm-violin".
And second, you can back up to a previous expression, edit it, move the cursor to the closing parenthesis, and
type &lt;RETURN&gt;, and that expression will be evaluated as if you had typed all of it in from the start. 
Needless to say, you can paste code from this file into the Snd listener.
</p>

<p>with-sound opens an output sound file, evaluates its body, closes the file, and then opens it in Snd.
If the sound is already open, with-sound replaces it with the new version. 
The body of with-sound can be any size, and can include anything that you could put in a function body.
For example, 
to get an arpeggio:</p>
<pre class="indented">
(with-sound ()
  (do ((i 0 (+ i 1)))
      ((= i 8))
    (fm-violin (* i .25) .5 (* 100 (+ i 1)) .1)))
</pre>

<p>with-sound, instruments, CLM itself are all optional, of course.  We could
do everything by hand:
</p>

<pre class="indented">
(let ((increment (/ (* 440.0 2.0 pi) 22050.0))
      (current-phase 0.0))
  (<a class=quiet href="extsnd.html#newsound">new-sound</a> "test.snd" :size 22050)
  (<a class=quiet href="extsnd.html#mapchannel">map-channel</a> (lambda (y)
 	         (let ((val (* .1 (sin current-phase))))
                   (set! current-phase (+ current-phase increment))
                   val))))
</pre>

<p>This opens a sound file (via <a href="extsnd.html#newsound">new-sound</a>) and fills it with a .1 amplitude sine wave at 440 Hz.
The "increment" calculation turns 440 Hz into a phase increment in radians (we could also use the function <a href="#hztoradians">hz-&gt;radians</a>).
The "oscil" generator keeps track of the phase increment for us, so
essentially the same thing using with-sound and oscil is:
</p>

<pre class="indented">
(with-sound ()
  (let ((osc (<a class=quiet href="#make-oscil">make-oscil</a> 440.0)))
    (do ((i 0 (+ i 1)))
        ((= i 44100))
      (<a class=quiet href="#outa">outa</a> i (* .1 (<a class=quiet href="#oscil">oscil</a> osc)) *output*))))
</pre>

<p>*output* is the file opened by with-sound, and outa is a function that adds its second
argument (the sinusoid) into the current output at the sample given by its first argument
("i" in this case).  oscil is our sinusoid generator, created by make-oscil.  You don't
need to worry about freeing the oscil; we can depend on the Scheme garbage collector to
deal with that.  All the generators are like oscil in that
each is a function that on each call returns the next sample in an infinite stream of samples.
An oscillator, for example, returns an endless sine wave, one sample
at a time.  
Each generator consists of a set of functions:  make-&lt;gen&gt; sets up the
data structure associated with the generator;
&lt;gen&gt; produces a new sample;
&lt;gen&gt;? checks whether a variable is that kind of generator.
Current generator state is accessible via various generic functions such as mus-frequency:
</p>
<pre class="indented">
(set! oscillator (<a class=quiet href="#make-oscil">make-oscil</a> :frequency 330))
</pre>
<p>prepares "oscillator" to produce a sine wave
when set in motion via</p>
<pre class="indented">
(<a class=quiet href="#oscil">oscil</a> oscillator)
</pre>

<p>
The make-&lt;gen&gt; function
takes a number of optional arguments, setting whatever state the given
generator needs to operate on.  The run-time function's first argument is
always its associated structure.  Its second argument is nearly always
something like an FM input or whatever run-time modulation might be
desired.
Frequency sweeps of all kinds (vibrato, glissando, breath
noise, FM proper) are all forms of frequency modulation.  So, in
normal usage, our oscillator looks something like:</p>
<pre class="indented">
(<a class=quiet href="#oscil">oscil</a> oscillator (+ vibrato glissando frequency-modulation))
</pre>

<p>One special aspect of each make-&lt;gen&gt; function is the way it
reads its arguments.  I use parenthesized parameters
in the function definitions to indicate that the argument names are
keywords, but the keywords themselves are optional.
Take the make-oscil call, defined as:</p>
<pre class="indented">
make-oscil (frequency 0.0) (initial-phase 0.0)
</pre>
<p>This says that make-oscil has two optional arguments, frequency (in Hz), and
initial-phase (in radians).  The keywords associated with these values are
:frequency and :initial-phase.
When make-oscil is called, it scans its arguments; if a keyword is seen, that
argument and all following arguments are passed unchanged, but if a value is
seen, the corresponding keyword is prepended in the argument list:
</p>
<pre class="indented">
(<a class=quiet href="#make-oscil">make-oscil</a> :frequency 440.0)
(<a class=quiet href="#make-oscil">make-oscil</a> :frequency 440.0 :initial-phase 0.0)
(<a class=quiet href="#make-oscil">make-oscil</a> 440.0)
(<a class=quiet href="#make-oscil">make-oscil</a> 440.0 :initial-phase 0.0)
(<a class=quiet href="#make-oscil">make-oscil</a> 440.0 0.0)
</pre>
<p>are all equivalent, but</p>
<pre class="indented">
(<a class=quiet href="#make-oscil">make-oscil</a> :frequency 440.0 0.0)
(<a class=quiet href="#make-oscil">make-oscil</a> :initial-phase 0.0 440.0)
</pre>

<p>are in error, because once we see any keyword, all the rest of the arguments have
to use keywords too (we can't reliably make any assumptions after that point about argument
ordering). 
This style of argument passing is the same as that of s7's define*, and is very similar to the "Optional
Positional and Named Parameters" extension of scheme: <a href="http://srfi.schemers.org/srfi-89/">SRFI-89</a>.
</p>

<p>Since we often want to use a given sound-producing algorithm many times (in a note list,
for example), it is convenient to package up that code into a function. Our sinewave
could be rewritten:
</p>

<pre class="indented">
(define (simp start end freq amp)
  (let ((os (<a class=quiet href="#make-oscil">make-oscil</a> freq)))
    (do ((i start (+ i 1))) 
        ((= i end))
      (<a class=quiet href="#outa">outa</a> i (* amp (<a class=quiet href="#oscil">oscil</a> os)))))) ; outa output defaults to *output* so we can omit it
</pre>

<p>Now to hear our sine wave:</p>
<pre class="indented">
(with-sound (:play #t) (simp 0 44100 330 .1))
</pre>

<p>This version of "simp" forces you to think in terms of sample numbers ("start" and "end") which
are dependent on the sampling rate.  Our first enhancement is to use seconds:
</p>

<pre class="indented">
(define (simp beg dur freq amp)
  (let ((os (<a class=quiet href="#make-oscil">make-oscil</a> freq))
        (<em class=red>start</em> (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
        (<em class=red>end</em> (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> (+ beg dur))))
    (do ((i start (+ i 1))) 
        ((= i end))
      (<a class=quiet href="#outa">outa</a> i (* amp (<a class=quiet href="#oscil">oscil</a> os))))))
</pre>

<p>Now we can use any sampling rate, and call "simp" using seconds:
</p>
<pre class="indented">
(with-sound (:srate 44100) (simp 0 1.0 440.0 0.1))
</pre>


<p>Next we turn the "simp" function into an "instrument".  An instrument is
a function that has a variety of built-in actions within with-sound.  The only change
is the word "definstrument":
</p>

<pre class="indented">
(<em class=red>definstrument</em> (simp beg dur freq amp)
  (let ((os (<a class=quiet href="#make-oscil">make-oscil</a> freq))
        (start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
        (end (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> (+ beg dur))))
    (do ((i start (+ i 1))) 
        ((= i end))
      (<a class=quiet href="#outa">outa</a> i (* amp (<a class=quiet href="#oscil">oscil</a> os))))))
</pre>

<p>Now we can simulate a telephone:
</p>

<pre class="indented">
(define (telephone start telephone-number)
  (do ((touch-tab-1 '(0 697 697 697 770 770 770 852 852 852 941 941 941))
       (touch-tab-2 '(0 1209 1336 1477 1209 1336 1477 1209 1336 1477 1209 1336 1477))
       (i 0 (+ i 1)))
      ((= i (length telephone-number)))
    (let* ((num (telephone-number i))
	   (frq1 (touch-tab-1 num))
	   (frq2 (touch-tab-2 num)))
      (<em class=red>simp</em> (+ start (* i .4)) .3 frq1 .1)
      (<em class=red>simp</em> (+ start (* i .4)) .3 frq2 .1))))

(with-sound () (telephone 0.0 '(7 2 3 4 9 7 1)))
</pre>

<p>As a last change, let's add an amplitude envelope:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (simp beg dur freq amp envelope)
  (let ((os (<a class=quiet href="#make-oscil">make-oscil</a> freq))
        (<em class=red>amp-env</em> (<a class=quiet href="#make-env">make-env</a> envelope :duration dur :scaler amp))
	(start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
        (end (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> (+ beg dur))))
    (do ((i start (+ i 1))) 
        ((= i end))
      (<a class=quiet href="#outa">outa</a> i (* (<a class=quiet href="#env">env</a> <em class=red>amp-env</em>) (<a class=quiet href="#oscil">oscil</a> os))))))
</pre>

<p>A CLM envelope is a list of (x y) break-point pairs.  The
x-axis bounds are arbitrary, but it is conventional (here at ccrma) to
go from 0 to 1.0.  The y-axis values are normally between -1.0 and
1.0, to make it easier to figure out how to apply the envelope in
various different situations.  
</p>

<pre class="indented">
(with-sound () (simp 0 2 440 .1 '(0 0  0.1 1.0  1.0 0.0)))
</pre>

<p>Add a few more oscils and envs, and you've got the fm-violin.  You can try out a generator or a patch of generators quickly by
plugging it into the following with-sound call:
</p>

<pre class="indented">
(with-sound () 
  (let ((sqr (make-square-wave 100))) ; test a square-wave generator
    (do ((i 0 (+ i 1))) 
        ((= i 10000)) 
      (outa i (square-wave sqr)))))
</pre>

<p>Many people find the syntax of "do" confusing.  It's possible to hide that
away in a macro:
</p>

<pre class="indented">
(define-macro (output beg dur . body)
  `(do ((i (seconds-&gt;samples ,beg) (+ i 1)))
       ((= i (seconds-&gt;samples (+ ,beg ,dur))))
     (outa i (begin ,@body))))

(define (simp beg dur freq amp)
  (let ((o (make-oscil freq)))
    (output beg dur (* amp (oscil o)))))

(with-sound ()
  (simp 0 1 440 .1)
  (simp .5 .5 660 .1))
</pre>

<p>It's also possible to use recursion, rather than iteration:
</p>

<pre class="indented">
(define (simp1)
  (let ((freq (hz-&gt;radians 440.0)))
    (let <em class=red>simp-loop</em> ((i 0) (x 0.0))
      (outa i (sin x)) 
      (if (&lt; i 44100)
	  (<em class=red>simp-loop</em> (+ i 1) (+ x freq))))))

(define <em class=red>simp2</em>
  (let ((freq (hz-&gt;radians 440.0)))
    (lambda* ((i 0) (x 0.0))
      (outa i (sin x))
      (if (&lt; i 44100)
	  (<em class=red>simp2</em> (+ i 1) (+ x freq))))))
</pre>

<p>but the do-loop is faster.
</p>

<!--
(define samps 44100)

(define (simp1)
  (let ((freq (hz->radians 440.0)))
    (do ((i 0 (+ i 1))
	 (x 0.0 (+ x freq)))
	((= i samps))
      (outa i (sin x)))))

(define (simp2)
  (let ((osc (make-oscil 440.0)))
    (do ((i 0 (+ i 1)))
	((= i samps))
      (outa i (oscil osc)))))

(define (simp3)
  (let ((freq (hz->radians 440.0)))
    (let simp-loop ((i 0) (x 0.0))
      (outa i (sin x))
      (if (< i samps)
	  (simp-loop (+ i 1) (+ x freq))))))

(define simp4
  (let ((freq (hz->radians 440.0)))
    (lambda* ((i 0) (x 0.0))
      (outa i (sin x))
      (if (< i samps)
	  (simp4 (+ i 1) (+ x freq))))))

(define-macro (time a) 
  `(let ((start (get-internal-real-time)))
     ,a 
     (* 1.0 (- (get-internal-real-time) start))))

(with-sound (:clipped #f)
  (format *stderr* "~,4F~%" (time (simp1)))
  (format *stderr* "~,4F~%" (time (simp2)))
  (format *stderr* "~,4F~%" (time (simp3)))
  (format *stderr* "~,4F~%" (time (simp4))))

#|
0.0044
0.0017
0.0165
0.0276
|#
-->

<!-- INDEX generators:Generators -->

<div class="header" id="generators">Generators</div>



<!--  OSCIL  -->

<div class="innerheader" id="oscildoc">oscil</div>

<pre class="indented">
<em class=def id="make-oscil">make-oscil</em> (frequency 0.0) (initial-phase 0.0)
<em class=def id="oscil">oscil</em> os (fm-input 0.0) (pm-input 0.0)
<em class=def id="oscil?">oscil?</em> os

<em class=def id="make-oscil-bank">make-oscil-bank</em> freqs phases amps stable
<em class=def id="oscil-bank">oscil-bank</em> os fms
<em class=def id="oscil-bank?">oscil-bank?</em> os
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">oscil methods</td></tr>
<tr><td class="inner"><em class=gen>mus-frequency</em></td> <td class="inner">frequency in Hz</td></tr>
<tr><td class="inner"><em class=gen>mus-phase</em></td>     <td class="inner">phase in radians</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td>    <td class="inner">1 (no set!)</td></tr>
<tr><td class="inner"><em class=gen>mus-increment</em></td> <td class="inner">frequency in radians per sample</td></tr>
</table>


<p>oscil produces a sine wave (using sin) with optional frequency change (FM).
It might be defined:
</p>

<pre class="indented">
(let ((result (sin (+ phase pm-input))))
  (set! phase (+ phase (<a class=quiet href="#hztoradians">hz-&gt;radians</a> frequency) fm-input))
  result)
</pre>
<!--  <img src="pix/sceq9.png" alt="fnm equation"> -->
<!-- LATEX: \cos \, (\omega_{c}t+B\sin \omega_{m}t)\:=\!\!\sum_{n=-\infty}^{\infty} \! \! J_{n}(B)\cos(\omega_{c} + n\omega_{m})t -->

<p>oscil's first argument is an oscil created by make-oscil.
Oscil's second argument is the 
frequency change (frequency modulation), and the third argument is the
phase change (phase modulation).
The initial-phase argument to make-oscil is in radians. You can
use <a href="#degreestoradians">degrees-&gt;radians</a> to convert from degrees to radians.
To get a cosine (as opposed to sine), set the initial-phase to (/ pi 2).
Here are examples in Scheme, Ruby, and Forth:
</p>


<table><tr><td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((gen (make-oscil 440.0)))
    (do ((i 0 (+ i 1)))
        ((= i 44100))
      (outa i (* 0.5 (oscil gen))))))
</pre>
</div>
</td></tr><tr><td>

<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  gen = make_oscil(440.0);
  44100.times do |i| 
    outa(i, 0.5 * oscil(gen), $output) 
    end
  end.output
</pre>
</div>
</td></tr><tr><td>

<div class="forth">
<pre class="indented">
lambda: ( -- )
  440.0 make-oscil { gen }
  44100 0 do
    i  gen 0 0 oscil  f2/ *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td></tr></table>

<p>One slightly confusing aspect of oscil is that glissando has to be turned into a phase-increment envelope.
This means that the frequency envelope y values should be passed through <a href="#hztoradians">hz-&gt;radians</a>:
</p>

<pre class="indented">
(define (simp start end freq amp frq-env)
  (let ((os (make-oscil freq)) 
        (frqe (<a class=quiet href="#make-env">make-env</a> frq-env :length (- (+ end 1) start) :scaler (<em class=red>hz-&gt;radians</em> freq))))
    (do ((i start (+ i 1))) 
        ((= i end))
      (<a class=quiet href="#outa">outa</a> i (* amp (oscil os (<a class=quiet href="#env">env</a> <em class=red>frqe</em>)))))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () (simp 0 10000 440 .1 '(0 0 1 1))) ; sweep up an octave
</pre>

<p>Here is an example of FM (here the <a class=quiet href="#hztoradians">hz-&gt;radians</a> business is folded into the FM index):
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (simple-fm beg dur freq amp mc-ratio index amp-env index-env)
  (let* ((start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
	 (end (+ start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
	 (cr (<em class=red>make-oscil</em> freq))                     ; carrier
         (md (<em class=red>make-oscil</em> (* freq mc-ratio)))        ; modulator
         (fm-index (<a class=quiet href="#hztoradians">hz-&gt;radians</a> (* index mc-ratio freq)))
         (ampf (<a class=quiet href="#make-env">make-env</a> (or amp-env '(0 0  .5 1  1 0)) :scaler amp :duration dur))
         (indf (<a class=quiet href="#make-env">make-env</a> (or index-env '(0 0  .5 1  1 0)) :scaler fm-index :duration dur)))
    (do ((i start (+ i 1)))
        ((= i end))
      (<a class=quiet href="#outa">outa</a> i (* (<a class=quiet href="#env">env</a> ampf) 
                 (<em class=red>oscil</em> cr (* (<a class=quiet href="#env">env</a> indf) 
                              (<em class=red>oscil</em> md))))))))

;;; (<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () (simple-fm 0 1 440 .1 2 1.0))
</pre>

<p><a href="fm.html">fm.html</a> has an introduction to FM.
FM and PM behave slightly differently during a glissando; FM is the more "natural" in that, left to its own devices,
it produces a spectrum that varies inversely with the pitch.  Compare these two cases.  Both involve a slow glissando
up an octave, FM in channel 0, and PM in channel 1.  In the first note, I fix up the FM index during the sweep to
keep the spectra steady, and in the second, I fix up the PM index.
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:channels 2)
  (let* ((dur 2.0)
	 (samps (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur))
	 (pitch 1000)
	 (modpitch 100)
	 (pm-index 4.0)
	 (fm-index (<a class=quiet href="#hztoradians">hz-&gt;radians</a> (* 4.0 modpitch))))
    (let ((car1 (make-oscil pitch))
	  (mod1 (make-oscil modpitch))
	  (car2 (make-oscil pitch))
	  (mod2 (make-oscil modpitch))
	  (frqf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1) :duration dur))
	  (ampf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 20 1 21 0) :duration dur :scaler .5)))
      (do ((i 0 (+ i 1)))
	  ((= i samps))
	(let* ((frq (<a class=quiet href="#env">env</a> frqf))
	       (rfrq (<a class=quiet href="#hztoradians">hz-&gt;radians</a> frq))
	       (amp (<a class=quiet href="#env">env</a> ampf)))
	  (<a class=quiet href="#outa">outa</a> i (* amp (oscil car1 (+ (* rfrq pitch)
					(* <em class=red>fm-index (+ 1 frq)</em> ; keep spectrum the same
					   (oscil mod1 (* rfrq modpitch)))))))
	  (<a class=quiet href="#outa">outb</a> i (* amp (oscil car2 (* rfrq pitch)
				(* <em class=red>pm-index</em> (oscil mod2 (* rfrq modpitch)))))))))
    (let ((car1 (make-oscil pitch))
	  (mod1 (make-oscil modpitch))
	  (car2 (make-oscil pitch))
	  (mod2 (make-oscil modpitch))
	  (frqf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1) :duration dur))
	  (ampf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 20 1 21 0) :duration dur :scaler .5)))
      (do ((i 0 (+ i 1)))
	  ((= i samps))
	(let* ((frq (<a class=quiet href="#env">env</a> frqf))
	       (rfrq (<a class=quiet href="#hztoradians">hz-&gt;radians</a> frq))
	       (amp (<a class=quiet href="#env">env</a> ampf)))
	  (<a class=quiet href="#outa">outa</a> (+ i samps) (* amp (oscil car1 (+ (* rfrq pitch)
						  (* <em class=red>fm-index</em>   ; let spectrum decay
						     (oscil mod1 (* rfrq modpitch)))))))
	  (<a class=quiet href="#outa">outb</a> (+ i samps) (* amp (oscil car2 (* rfrq pitch)
				          (* <em class=red>(/ pm-index (+ 1 frq))</em> (oscil mod2 (* rfrq modpitch)))))))))))
</pre>

<p>And if you read somewhere that PM can't produce a frequency shift:
</p>
<pre class="indented">
(with-sound ()
  (let ((o (make-oscil 200.0))
        (e (make-env '(0 0 1 1) :scaler 300.0 :duration 1.0)))
    (do ((i 0 (+ i 1)))
        ((= i 44100))
      (outa i (oscil o 0.0 (env e))))))
</pre>



<p>To show CLM in its various embodiments, here are the Scheme, Common Lisp, Ruby, Forth, and C versions of the bird instrument;
it produces a sinusoid with (usually very elaborate) amplitude and frequency envelopes.
</p>

<table>
<tr><td>
<div class="scheme">
<pre class="indented">
(define (scheme-bird start dur frequency freqskew amplitude freq-envelope amp-envelope)
  (let* ((gls-env (<a class=quiet href="#make-env">make-env</a> freq-envelope (<a class=quiet href="#hztoradians">hz-&gt;radians</a> freqskew) dur))
         (os (<a class=quiet href="#make-oscil">make-oscil</a> frequency))
         (amp-env (<a class=quiet href="#make-env">make-env</a> amp-envelope amplitude dur))
	 (beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> start))
	 (end (+ beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur))))
   (do ((i beg (+ i 1)))
       ((= i end))
     (<a class=quiet href="#outa">outa</a> i (* (<a class=quiet href="#env">env</a> amp-env) 
                (<a class=quiet href="#oscil">oscil</a> os (<a class=quiet href="#env">env</a> gls-env)))))))
</pre>
</div>
</td></tr><tr><td>

<div class="lisp">
<pre class="indented">
(definstrument common-lisp-bird (startime dur frequency freq-skew amplitude freq-envelope amp-envelope)
  (multiple-value-bind (beg end) (times-&gt;samples startime dur)
    (let* ((amp-env (make-env amp-envelope amplitude dur))
	   (gls-env (make-env freq-envelope (<a class=quiet href="#hztoradians">hz-&gt;radians</a> freq-skew) dur))
	   (os (make-oscil frequency)))
      (run
       (loop for i from beg to end do
	 (outa i (* (env amp-env) 
                    (oscil os (env gls-env)))))))))
</pre>
</div>
</td></tr><tr><td>

<div class="ruby">
<pre class="indented">
def ruby_bird(start, dur, freq, freqskew, amp, freq_envelope, amp_envelope)
  gls_env = make_env(:envelope, freq_envelope, :scaler, hz2radians(freqskew), :duration, dur)
  os = make_oscil(:frequency, freq)
  amp_env = make_env(:envelope, amp_envelope, :scaler, amp, :duration, dur)
  run_instrument(start, dur) do
    env(amp_env) * oscil(os, env(gls_env))
  end
end
</pre>
</div>
</td></tr><tr><td>

<div class="forth">
<pre class="indented">
instrument: forth-bird { f: start f: dur f: freq f: freq-skew f: amp freqenv ampenv -- }
    :frequency freq make-oscil { os }
    :envelope ampenv :scaler amp :duration dur make-env { ampf }
    :envelope freqenv :scaler freq-skew hz&gt;radians :duration dur make-env { gls-env }
    90e random :locsig-degree
    start dur run-instrument  ampf env  gls-env env os oscil-1  f*  end-run
    os gen-free
    ampf gen-free
    gls-env gen-free
;instrument
</pre>
</div>
</td></tr><tr><td>

<div class="c">
<pre class="indented">
void c_bird(double start, double dur, double frequency, double freqskew, double amplitude, 
	    mus_float_t *freqdata, int freqpts, mus_float_t *ampdata, int amppts, mus_any *output)
{
  mus_long_t beg, end, i;
  mus_any *amp_env, *freq_env, *osc;
  beg = start * mus_srate();
  end = start + dur * mus_srate();
  osc = mus_make_oscil(frequency, 0.0);
  amp_env = mus_make_env(ampdata, amppts, amplitude, 0.0, 1.0, dur, 0, NULL);
  freq_env = mus_make_env(freqdata, freqpts, mus_hz_to_radians(freqskew), 0.0, 1.0, dur, 0, NULL);
  for (i = beg; i &lt; end; i++)
    mus_sample_to_file(output, i, 0, 
		       mus_env(amp_env) * 
		         mus_oscil(osc, mus_env(freq_env), 0.0));
  mus_free(osc);
  mus_free(amp_env);
  mus_free(freq_env);
}
</pre>
</div>
</td></tr></table>


<p>Many of the CLM synthesis functions try to make it
faster or more convenient to produce a lot of sinusoids, but there
are times when nothing but a ton of oscils will do:
</p>


<pre class="indented">
(<a class=quiet href="sndscm.html#withsound">with-sound</a> () 
 (let* ((peaks (list  23  0.0051914    32  0.0090310    63  0.0623477    123  0.1210755    185  0.1971876
		      209  0.0033631  247  0.5797809   309  1.0000000    370  0.1713255    432  0.9351965
		      481  0.0369873  495  0.1335089   518  0.0148626    558  0.1178001    617  0.6353443
		      629  0.1462804  661  0.0208941   680  0.1739281    701  0.0260423    742  0.1203807
		      760  0.0070301  803  0.0272111   865  0.0418878    926  0.0090197    992  0.0098687
		      1174  0.00444  1298  0.0039722  2223  0.0033486   2409  0.0083675   2472  0.0100995
		      2508  0.004262 2533  0.0216248  2580  0.0047732   2596  0.0088663   2612  0.0040592
		      2657  0.005971 2679  0.0032541  2712  0.0048836   2761  0.0050938   2780  0.0098877
		      2824  0.003421 2842  0.0134356  2857  0.0050194   2904  0.0147466   2966  0.0338878
		      3015  0.004832 3027  0.0095497  3040  0.0041434   3092  0.0044802   3151  0.0038269
		      3460  0.003633 3585  0.0050849  4880  0.0042301   5121  0.0037906   5136  0.0048349
		      5158  0.004336 5192  0.0037841  5200  0.0038025   5229  0.0035555   5356  0.0045781
		      5430  0.003687 5450  0.0055170  5462  0.0057821   5660  0.0041789   5673  0.0044932
		      5695  0.007370 5748  0.0031716  5776  0.0037921   5800  0.0062308   5838  0.0034629
		      5865  0.005942 5917  0.0032254  6237  0.0046164   6360  0.0034708   6420  0.0044593
		      6552  0.005939 6569  0.0034665  6752  0.0041965   7211  0.0039695   7446  0.0031611
		      7468  0.003330 7482  0.0046322  8013  0.0034398   8102  0.0031590   8121  0.0031972
		      8169  0.003345 8186  0.0037020  8476  0.0035857   8796  0.0036703   8927  0.0042374
		      9388  0.003173 9443  0.0035844  9469  0.0053484   9527  0.0049137   9739  0.0032365
		      9853  0.004297 10481  0.0036424  10490  0.0033786  10606  0.0031366))
	(len (/ (length peaks) 2))
	(dur 10)
	(oscs (make-vector len))
	(amps (make-vector len))
	(ramps (make-vector len))
	(freqs (make-vector len))
	(vib (<a class=quiet href="#make-rand-interp">make-rand-interp</a> 50 (<a class=quiet href="#hztoradians">hz-&gt;radians</a> .01)))
	(ampf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 10 1 11 0) :duration dur :scaler .1))
	(samps (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))

   (do ((i 0 (+ i 1)))
       ((= i len))
     (set! (freqs i) (peaks (* i 2)))
     (set! (oscs i) (<em class=red>make-oscil</em> (freqs i) (random pi)))
     (set! (amps i) (peaks (+ 1 (* 2 i))))
     (set! (ramps i) (<a class=quiet href="#make-rand-interp">make-rand-interp</a> (+ 1.0 (* i (/ 20.0 len))) 
				       (* (+ .1 (* i (/ 3.0 len))) (amps i)))))
  (do ((i 0 (+ i 1)))
      ((= i samps))
    (let ((sum 0.0)
          (fm (<a class=quiet href="#rand-interp">rand-interp</a> vib)))
      (do ((k 0 (+ k 1)))
          ((= k len))
        (set! sum (+ sum (* (+ (amps k)
		               (<a class=quiet href="#rand-interp">rand-interp</a> (ramps k)))
		            (<em class=red>oscil</em> (oscs k) (* (freqs k) fm))))))
  (<a class=quiet href="#outa">outa</a> i (* (<a class=quiet href="#env">env</a> ampf) sum))))))
</pre>

<p>oscil-bank here would be faster, or <a href="#mus-chebyshev-tu-sum">mus-chebyshev-t-sum</a>:
</p>

<pre class="indented">
...
(amps (make-float-vector 10607))
(angle 0.0)
(freq (hz-&gt;radians 1.0))
...
(do ((i 0 (+ i 1))
     (k 0 (+ k 2)))
    ((= i len))
  (set! (amps (peaks k)) (peaks (+ k 1))))
...
 (outa i (* (env ampf) (<em class=red>mus-chebyshev-t-sum</em> angle amps)))
 (set! angle (+ angle freq (rand-interp vib)))
...
</pre>

<p>Here's a better example: we want to start with a sum of equal amplitude harmonically
related cosines (a sequence of spikes), and move slowly to a waveform with the same
magnitude spectrum, but with the phases chosen to minimize the peak amplitude.
</p>

<pre class="indented">
(let ((98-phases #(0.000000 -0.183194 0.674802 1.163820 -0.147489 1.666302 0.367236 0.494059 0.191339 
                   0.714980 1.719816 0.382307 1.017937 0.548019 0.342322 1.541035 0.966484 0.936993 
                   -0.115147 1.638513 1.644277 0.036575 1.852586 1.211701 1.300475 1.231282 0.026079 
 		   0.393108 1.208123 1.645585 -0.152499 0.274978 1.281084 1.674451 1.147440 0.906901 
		   1.137155 1.467770 0.851985 0.437992 0.762219 -0.417594 1.884062 1.725160 -0.230688 
		   0.764342 0.565472 0.612443 0.222826 -0.016453 1.527577 -0.045196 0.585089 0.031829 
		   0.486579 0.557276 -0.040985 1.257633 1.345950 0.061737 0.281650 -0.231535 0.620583 
		   0.504202 0.817304 -0.010580 0.584809 1.234045 0.840674 1.222939 0.685333 1.651765 
		   0.299738 1.890117 0.740013 0.044764 1.547307 0.169892 1.452239 0.352220 0.122254 
		   1.524772 1.183705 0.507801 1.419950 0.851259 0.008092 1.483245 0.608598 0.212267	
		   0.545906 0.255277 1.784889 0.270552 1.164997 -0.083981 0.200818 1.204088))
     (freq 10.0)
     (dur 5.0)
     (n 98))
  (with-sound ()
    (let ((samps (floor (* dur 44100)))
	  (1/n (/ 1.0 n))
	  (freqs (make-float-vector n))
	  (phases (make-float-vector n (* pi 0.5))))
      (do ((i 0 (+ i 1)))
	  ((= i n))
	(let ((off (/ (* pi (- 0.5 (98-phases i))) dur 44100))
	      (h (hz-&gt;radians (* freq (+ i 1)))))
	  (set! (freqs i) (+ h off))))
      (let ((ob (<em class=red>make-oscil-bank</em> freqs phases)))
        (do ((i 0 (+ i 1))) ; get rid of the distracting initial click
            ((= i 1000))
          (<em class=red>oscil-bank</em> ob))
        (do ((k 0 (+ k 1)))
	    ((= k samps))
          (outa k (* 1/n (<em class=red>oscil-bank</em> ob))))))))
</pre>



<!--
(with-sound () 
 (let* ((peaks (list  23  0.0051914    32  0.0090310    63  0.0623477    123  0.1210755    185  0.1971876
		      209  0.0033631  247  0.5797809   309  1.0000000    370  0.1713255    432  0.9351965
		      481  0.0369873  495  0.1335089   518  0.0148626    558  0.1178001    617  0.6353443
		      629  0.1462804  661  0.0208941   680  0.1739281    701  0.0260423    742  0.1203807
		      760  0.0070301  803  0.0272111   865  0.0418878    926  0.0090197    992  0.0098687
		      1174  0.00444  1298  0.0039722  2223  0.0033486   2409  0.0083675   2472  0.0100995
		      2508  0.004262 2533  0.0216248  2580  0.0047732   2596  0.0088663   2612  0.0040592
		      2657  0.005971 2679  0.0032541  2712  0.0048836   2761  0.0050938   2780  0.0098877
		      2824  0.003421 2842  0.0134356  2857  0.0050194   2904  0.0147466   2966  0.0338878
		      3015  0.004832 3027  0.0095497  3040  0.0041434   3092  0.0044802   3151  0.0038269
		      3460  0.003633 3585  0.0050849  4880  0.0042301   5121  0.0037906   5136  0.0048349
		      5158  0.004336 5192  0.0037841  5200  0.0038025   5229  0.0035555   5356  0.0045781
		      5430  0.003687 5450  0.0055170  5462  0.0057821   5660  0.0041789   5673  0.0044932
		      5695  0.007370 5748  0.0031716  5776  0.0037921   5800  0.0062308   5838  0.0034629
		      5865  0.005942 5917  0.0032254  6237  0.0046164   6360  0.0034708   6420  0.0044593
		      6552  0.005939 6569  0.0034665  6752  0.0041965   7211  0.0039695   7446  0.0031611
		      7468  0.003330 7482  0.0046322  8013  0.0034398   8102  0.0031590   8121  0.0031972
		      8169  0.003345 8186  0.0037020  8476  0.0035857   8796  0.0036703   8927  0.0042374
		      9388  0.003173 9443  0.0035844  9469  0.0053484   9527  0.0049137   9739  0.0032365
		      9853  0.004297 10481  0.0036424  10490  0.0033786  10606  0.0031366))
	(len (/ (length peaks) 2))
	(dur 10)
	(ramps (make-vector len))
	(vib (make-rand-interp 50 (hz->radians .01)))
	(ampf (make-env '(0 0 1 1 10 1 11 0) :duration dur :scaler .1))
	(samps (seconds->samples dur))
	(amps (make-float-vector 10607))
	(angle 0.0)
	(freq (hz->radians 1.0)))

   (do ((i 0 (+ i 1))
	(k 0 (+ k 2)))
       ((= i len))
     (set! (amps (peaks k)) (peaks (+ k 1))))

      (do ((i 0 (+ i 1)))
	  ((= i samps))
	(outa i (* (env ampf)
		   (mus-chebyshev-t-sum angle amps)))
	(set! angle (+ angle freq (rand-interp vib))))))
-->

<p>The last argument to make-oscil-bank, "stable", defaults to false.  If it is
true, oscil-bank can assume that the frequency, phase, and amplitude values passed to
make-oscil-bank will not change over the life of the generator.
</p>

<p>
Related generators are 
<a href="#ncos">ncos</a>, 
<a href="#nsin">nsin</a>,
<a href="#asymmetric-fm">asymmetric-fm</a>, and
<a href="#nrxydoc">nrxysin</a>.
Some instruments that use oscil are 
<a href="sndscm.html#birddoc">bird and bigbird</a>,
<a href="sndscm.html#fmviolin">fm-violin</a> (v),
<a href="sndscm.html#lbjpiano">lbj-piano</a> (clm-ins.scm), 
<a href="sndscm.html#fmvox">vox</a> (clm-ins.scm), and
<a href="sndscm.html#fmbell">fm-bell</a> (clm-ins.scm).  
Interesting extensions of oscil include the various
summation formulas in <a href="#othergenerators">generators.scm</a>.
To goof around with FM from a graphical interface, see bess.scm and bess1.scm.
</p>


<p>When oscil's frequency is high relative to the sampling rate,
the waveform it produces may not look very sinusoidal.  Here, for example, is oscil
at 440 Hz when the srate is 1000, 4000, and 16000:
</p>
<img src="pix/srates.png" alt="effect of different srates">


<!--
(set! *selected-graph-color* (make-color 1 1 1))
(set! *selected-data-color* (make-color 0 0 0))
(set! *axis-numbers-font* *tiny-font*)
(set! (x-axis-label 0 0 0) "srate: 1000")
(set! (x-axis-label 1 0 0) "srate: 4000")
(set! (x-axis-label 2 0 0) "srate: 16000")
(set! *axis-label-font* "12x24")

(with-sound (:srate 1000) ; 4000 16000
   (let ((gen (make-oscil 440.0)))
      (do ((i 0 (+ i 1)))
          ((= i 20000))
        (outa i (oscil gen)))))

-->





<!--  ENV  -->

<div class="innerheader" id="envdoc">env</div>

<pre class="indented">
<em class=def id="make-env">make-env</em> 
      envelope      ; list or float-vector of x,y break-point pairs
      (scaler 1.0)  ; scaler on every y value (before offset is added)
      duration      ; duration in seconds
      (offset 0.0)  ; value added to every y value
      base          ; type of connecting line between break-points
      end           ; end sample number (obsolete, use length)
      length        ; duration in samples

<em class=def id="env">env</em> e
<em class=def id="env?">env?</em> e

<em class=def id="env-interp">env-interp</em> x env (base 1.0) ;value of env at x
<em class=def id="env-any">env-any</em> e connecting-function
<em class=def id="envelopeinterp">envelope-interp</em> x env (base 1.0)

<em class=def id="make-pulsed-env">make-pulsed-env</em> envelope duration frequency
<em class=def id="pulsedenv">pulsed-env</em> gen (fm 0.0)
<em class=def id="pulsedenv?">pulsed-env?</em> gen
</pre>


<table class="method">
<tr><td colspan=2 class="methodtitle">env methods</td></tr>
<tr><td class="inner"><em class=gen>mus-location</em></td> <td class="inner">number of calls so far on this env</td></tr>
<tr><td class="inner"><em class=gen>mus-increment</em></td><td class="inner">base</td></tr>
<tr><td class="inner"><em class=gen>mus-data</em></td>     <td class="inner">original breakpoint list</td></tr>
<tr><td class="inner"><em class=gen>mus-scaler</em></td>   <td class="inner">scaler</td></tr>
<tr><td class="inner"><em class=gen>mus-offset</em></td>   <td class="inner">offset</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td>   <td class="inner">duration in samples</td></tr>
<tr><td class="inner"><em class=gen>mus-channels</em></td> <td class="inner">current position in the break-point list</td></tr>
</table>


<p>An envelope is a list or float-vector of break point pairs: <code>'(0 0  100 1)</code>  is
a ramp from 0 to 1 over an x-axis excursion from 0 to 100, as is <code>(float-vector 0 0 100 1)</code>.  
This data is passed
to make-env along with the scaler (multiplier)
applied to the y axis, the offset added to every y value,
and the time in samples or seconds that the x axis represents.  
make-env returns an env generator.  
env then returns the next sample of the envelope each time it is called.  
Say we want  a ramp moving from .3 to .5 during 1 second. 
</p>
<pre class="indented">
    (make-env '(0 0  100 1) :scaler .2 :offset .3 :duration 1.0)
    (make-env '(0 .3  1 .5) :duration 1.0)
</pre>
<p>
I find the second version easier to read.  The first is handy if you have a
bunch of stored envelopes.  To specify the breakpoints, you can also use the form <code>'((0 0) (100 1))</code>.
I used "scaler" decades ago because I didn't like the spelling "scalar".  According
to the OED, "scalar" goes back to the 17th century, and derives from "scala", a ladder, ultimately from
Latin.  "scaler" is also old, and refers to one who scales a mountain or a fish.  Well, I still
like "scaler" better:  We're staring at a "peak"! "gain" looks like an escapee from the EE lab.  "volume" is too specific.
Maybe "scl" or "*"?
</p>

<img src="pix/pyr.png" alt="an envelope">
<br>


<table><tr><td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((gen (make-oscil 440.0))
        (ampf (make-env '(0 0  .01 1  .25 .1 1 0)
	        :scaler 0.5
                :length 44100)))
    (do ((i 0 (+ i 1)))
        ((= i 44100))
      (outa i (* (env ampf) (oscil gen))))))
</pre>
</div>
</td></tr><tr><td>

<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  gen = make_oscil(440.0);
  ampf = make_env(
          [0, 0, 0.01, 1.0, 0.25, 0.1, 1, 0],
          :scaler, 0.5,
          :length, 44100);
  44100.times do |i| 
    outa(i, env(ampf) * oscil(gen), $output) 
    end
  end.output
</pre>
</div>
</td></tr><tr><td>

<div class="forth">
<pre class="indented">
lambda: ( -- )
  440.0 make-oscil { gen }
  '( 0 0 0.01 1 0.25 0.1 1 0 )
  :scaler 0.5 :length 44100 make-env { ampf }
  44100 0 do
    i  gen 0 0 oscil  ampf env  f* *output*  outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td></tr></table>


<p>The base argument determines how the break-points are connected.  If it is 1.0 (the
default), you get straight line segments.  If base is 0.0, you get a step
function (the envelope changes its value suddenly to the new one without any
interpolation).  Any other positive value affects the exponent of the exponential curve
connecting the points.  A base less than 1.0 gives convex curves (i.e. bowed
out), and a base greater than 1.0 gives concave curves (i.e. sagging).
If you'd rather think in terms of e^-kt, set the base to <code>(exp k)</code>. 
</p>

<img src="pix/pyr03.png" alt="base .03 choice">

<img src="pix/pyr32.png" alt="base 32 choice">


<p>
You can get a lot from a couple of envelopes:
</p>

<pre class="indented">
&gt; (load "animals.scm")
#&lt;unspecified&gt;
&gt; (with-sound (:play #t) (pacific-chorus-frog 0 .5))
"test.snd"
&gt; (with-sound (:play #t) (house-finch 0 .5))
"test.snd"
</pre>


<p>
There are several ways to get arbitrary connecting curves between the break points.
The simplest method is to treat
the output of env as the input to the connecting function.  Here's an
instrument that maps the line segments into sin x^3:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (mapenv beg dur frq amp en)
  (let* ((start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
	 (end (+ start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
	 (osc (<a class=quiet href="#make-oscil">make-oscil</a> frq))
	 (zv (<em class=red>make-env</em> <em class=red>en</em> 1.0 dur)))
   (do ((i start (+ i 1)))
       ((= i end))
     (let ((zval (<em class=red>env</em> zv))) 
       (<a class=quiet href="#outa">outa</a> i 
         (* amp 
            (sin (* 0.5 pi zval zval zval)) 
            (<a class=quiet href="#oscil">oscil</a> osc)))))))

(<a class=quiet href="sndscm.html#withsound">with-sound</a> () 
  (mapenv 0 1 440 .5 '(0 0  50 1  75 0  86 .5  100 0)))
</pre>

<img src="pix/sincube.png" alt="sin cubed envelope">


<!--
(define (fixup-axes)
  (set! *selected-data-color* (make-color 0 0 0))(set! *selected-data-color* (make-color 0 0 0))
  (set! *selected-graph-color* (make-color 1 1 1))
  (set! (x-axis-label 0 0) "sin^3 of '(0 0  50 1  75 0  86 .5  100 0)"))
-->

<p id="bellcurve">Another method is to write a function that traces out the curve you want.
J.C.Risset's bell curve is:</p>

<pre class="indented">
(define (bell-curve x)
  ;; x from 0.0 to 1.0 creates bell curve between .64e-4 and nearly 1.0
  ;; if x goes on from there, you get more bell curves; x can be
  ;; an envelope (a ramp from 0 to 1 if you want just a bell curve)
  (+ .64e-4 (* .1565 (- (exp (- 1.0 (cos (* 2 pi x)))) 1.0))))
</pre>

<p>But the most flexible method is to use <b>env-any</b>.
env-any takes the env generator that produces the underlying envelope,
and a function to "connect the dots", and returns the new envelope
applying that connecting function between the break points.
For example, say we want to square each envelope value:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (let ((e (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 2 .25 3 1 4 0) 
                     :duration 0.5)))
    (do ((i 0 (+ i 1)))
	((= i 44100))
      (<a class=quiet href="#outa">outa</a> i (<em class=red>env-any</em> e (lambda (y) (* y y)))))))

;; or connect the dots with a sinusoid:

(define (sine-env e)
  (<em class=red>env-any</em> e (lambda (y)
	       (* 0.5 (+ 1.0 (sin (+ (* -0.5 pi) 
				     (* pi y))))))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (let ((e (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 2 .25 3 1 4 0)
                     :duration 0.5)))
   (do ((i 0 (+ i 1)))
       ((= i 44100))
     (<a class=quiet href="#outa">outa</a> i (sine-env e)))))
</pre>

<img src="pix/envany.png" alt="env-any pix">


<!--
(define (fixup-axes)
  (set! *selected-data-color* (make-color 0 0 0))(set! *selected-data-color* (make-color 0 0 0))
  (set! *selected-graph-color* (make-color 1 1 1))
  (set! *axis-numbers-font* *tiny-font*)
  (set! (x-axis-label 0 0) "(env-any e (lambda (y) (* y y)))")
  (set! (x-axis-label 0 1) "(sine-env)"))
-->

<p>The env-any connecting function takes one argument, the current envelope value treated as
going between 0.0 and 1.0 between each two points.  It returns a value that is then
fitted back into the original (scaled, offset) envelope.  There are a couple more of these
functions in generators.scm, one to apply a blackman4 window between the points, and the
other to cycle through a set of exponents.
</p>


<p>
<a href="#mus-reset">mus-reset</a> of an env causes it
to start all over again from the beginning. 
mus-reset is called internally if you use mus-scaler to set an env's scaler (and similarly for offset and length).
To jump to any position in
an env, use <a href="#mus-location">mus-location</a>.
Here's a function that uses these methods to apply an envelope over and over:
</p>

<pre class="indented">
(define (strum e)
  (<a class=quiet href="extsnd.html#mapchannel">map-channel</a> (lambda (y)
		 (if (&gt; (<em class=red>mus-location</em> e) (<em class=red>mus-length</em> e)) ; mus-length = dur
		     (<em class=red>mus-reset</em> e))     ; start env again (default is to stick at the last value)
		 (* y (<a class=quiet href="#env">env</a> e)))))

;;; (strum (make-env (list 0 0 1 1 10 .6 25 .3 100 0) :length 2000))
</pre>

<p>To copy an env while changing one aspect (say
duration), it's simplest to use make-env:
</p>

<pre class="indented">
(define (change-env-dur e dur)
  (<a class=quiet href="#make-env">make-env</a> (<a class=quiet href="#mus-data">mus-data</a> e) :scaler (<a class=quiet href="#mus-scaler">mus-scaler</a> e) :offset (<a class=quiet href="#mus-offset">mus-offset</a> e) :base (<a class=quiet href="#mus-increment">mus-increment</a> e)
	    :duration dur))
</pre>

<p>make-env signals an error if the envelope breakpoints are either out of order, or an x axis value
occurs twice.  The default error handler in with-sound may not give you the information you need to
track down the offending note, even given the original envelope.  Here's one way to trap the error
and get more info (in this case, the begin time and duration of the enclosing note):
</p>

<pre class="indented">
(define* (make-env-with-catch beg dur :rest args)
  (catch 'mus-error
	 (lambda ()
	   (apply <em class=red>make-env</em> args))
	 (lambda args
	   (<a class=quiet>format</a> #t ";~A ~A: ~A~%" beg dur args))))
</pre>

<p>(envelope-interp x env base) returns value of 'env' at 'x'.
If 'base' is 0, 'env' is treated as a step function; if 'base' is 1.0 (the
default), the breakpoints of 'env' are connected by a straight line, and
any other 'base' connects the breakpoints with a kind of exponential
curve:
</p>

<pre class="indented">
&gt; (envelope-interp .1 '(0 0 1 1))
0.1
&gt; (envelope-interp .1 '(0 0 1 1) 32.0)
0.0133617278184869
&gt; (envelope-interp .1 '(0 0 1 1) .012)
0.361774730775292
</pre>

<p>The corresponding function for a CLM env generator is <a href="sndclm.html#env-interp">env-interp</a>.
If you'd rather think in terms of e^-kt, set the 'base' to (exp k).  
</p>
<div class="spacer"></div>


<p>
pulsed-env produces a repeating envelope.  <a href="#env">env</a> sticks at its last value, but pulsed-env repeats it over and over.
"duration" is the envelope duration, and "frequency" is the repeitition rate, changeable via the "fm" argument to the pulsed-env generator.
</p>
<pre class="indented">
(with-sound ()
  (let ((e (make-pulsed-env '(0 0 1 1 2 0) .01 1)) 
        (frq (make-env '(0 0 1 1) :duration 1.0 :scaler (hz-&gt;radians 50))))
    (do ((i 0 (+ i 1)))
        ((= i 44100))
      (outa i (* .5 (pulsed-env e (env frq)))))))
</pre>

<p>
An envelope applied to the amplitude of a signal is a form of amplitude modulation,
and glissando is frequency modulation.  Both cause a broadening of the spectral components:
</p>

<table><tr>
<td>
<img src="pix/ampenvspectrum.png" alt="amp env spectrum">
</td><td>
<img src="pix/frqenvspectrum.png" alt="frq env spectrum">
</td></tr>
<tr>
<td class="center"><small>truncated pyramid amplitude envelope<br>multiplied by sinusoid at 50Hz</small>
</td>
<td class="center"><small>truncated pyramid frquency envelope<br>sinusoid from 100Hz to 300Hz</small>
</td>
</tr></table>


<!--
ampenvspectrum.png:
(with-sound (:srate 10000)
  (let* ((ampf (make-env '(0 0 1 1 15 1 16 0) :duration 15))
	 (osc (make-oscil 50))
	 (samps (seconds->samples 15))
	 (start (seconds->samples 7))
	 (end (+ start samps)))
       (do ((i 0 (+ i 1)))
	   ((= i end))
	 (outa (+ i start) (* (env ampf) (oscil osc))))))

;;; GL/ data cutoff .015 dark 78 jet invert blackman10 65536 db-100
;;; x 299 1.84 y 281 .082 z 342 1.25
;;; hop 3
(set! *spectrum-end* .02)
(set! *selected-graph-color* (make-color 1 1 1))

frqenvspectrum.png:
(with-sound (:srate 10000)
  (let* ((ampf (make-env '(0 0 10 0 11 1 25 1 26 0 40 0) :duration 40 :scaler (hz->radians 200)))
	 (osc (make-oscil 100))
	 (samps (seconds->samples 40))
	 (start (seconds->samples 0))
	 (end (+ start samps)))
       (do ((i 0 (+ i 1)))
	   ((= i end))
	 (outa (+ i start) (oscil osc (env ampf))))))

65536 GL blackman10 -100 dB 
x 299 1.84 y 281 0.82 z 10 1.25
hop 3 % 0.11
jet .015 78 invert
-->

<p>The amplitude case reflects the spectrum of the amplitude envelope all by itself, translated (by multiplication)
up to the sinusoid's pitch.  The sidebands are about 1 Hz apart (the envelope takes 1 second to go linearly from 0 to 1).
Despite appearances, we hear this (are you sitting down?) as a changing amplitude, not a timbral mess.
Spectra can be tricky to interpret, and I've tried to choose parameters for this display that emphasize 
the broadening.  
</p>

<br>


<table class="method">
<tr><td class="methodtitle">Envelopes</td></tr>
<tr><td>
<p>Various operations on envelopes: 
</p>
<pre class="indented">
<a href="sndscm.html#envdoc">env.scm</a>:
add-envelopes            add two envelopes
concatenate-envelopes    concatenate a bunch of envelopes
envelope-exp             interpolate points to approximate exponential curves
envelope-interp          return the value of an envelope given the x position
envelope-last-x          return the last x value in an envelope
intergrate-envelope      return the area under an envelope
make-power-env           exponential curves with multiple exponents (see also multi-expt-env in generators.scm)
map-envelopes            apply a function to the breakpoints in two envelopes, returning a new envelope
max-envelope             return the maximum y value in an envelope (also min-envelope)
multiply-envelopes       multiply two envelopes
normalize-envelope       scale the y values of an envelope to peak at 1.0
repeat-envelope          concatenate copies of an envelope
reverse-envelope         reverse the breakpoints in an envelope
scale-envelope           scale and offset the y values of an envelope
stretch-envelope         apply attack and decay times to an envelope ("adsr", or "divenv")
window-envelope          return the portion of an envelope within given x axis bounds
</pre>
<pre>
envelope sound: <a href="extsnd.html#envchannel">env-channel</a>, <a href="extsnd.html#envsound">env-sound</a>
other enveloping functions: <a href="extsnd.html#rampchannel">ramp-channel</a>, <a href="extsnd.html#xrampchannel">xramp-channel</a>, <a href="extsnd.html#smoothchannel">smooth-channel</a>
envelope editor: <a href="snd.html#editenvelope">Edit or View and Envelope</a>
panning: place-sound in examp.scm
read sound indexed through envelope: <a href="sndscm.html#envsoundinterp">env-sound-interp</a>
repeating envelope: <a href="#pulsedenv">pulsed-env</a>
step envelope in pitch: <a href="#rxyk!cos">brassy</a> in generators.scm
</pre>
</td></tr></table>




<!--  TABLE-LOOKUP  -->

<div class="innerheader" id="table-lookupdoc">table-lookup</div>

<pre class="indented">
<em class=def id="make-table-lookup">make-table-lookup</em> 
        (frequency 0.0) ; table repetition rate in Hz
        (initial-phase 0.0)                 ; starting point in radians (pi = mid-table)
        wave                                ; a float-vector containing the signal
        (size *clm-table-size*)             ; table size if wave not specified
        (type mus-interp-linear)            ; interpolation type

<em class=def id="table-lookup">table-lookup</em> tl (fm-input 0.0)
<em class=def id="table-lookup?">table-lookup?</em> tl

<em class=def id="make-table-lookup-with-env">make-table-lookup-with-env</em> frequency env size
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">table-lookup methods</td></tr>
<tr><td class="inner"><em class=gen>mus-frequency</em></td><td class="inner">frequency in Hz</td></tr>
<tr><td class="inner"><em class=gen>mus-phase</em></td><td class="inner">phase in radians</td></tr>
<tr><td class="inner"><em class=gen>mus-data</em></td><td class="inner">wave float-vector</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">wave size (no set!)</td></tr>
<tr><td class="inner"><em class=gen>mus-interp-type</em></td><td class="inner">interpolation choice (no set!)</td></tr>
<tr><td class="inner"><em class=gen>mus-increment</em></td><td class="inner">table increment per sample</td></tr>
</table>


<p>table-lookup performs interpolating table lookup with a lookup index that moves
through the table at a speed set by make-table-lookup's "frequency" argument and table-lookup's "fm-input" argument.
That is, the waveform in the table is produced repeatedly, the repetition rate set by the frequency arguments.
Table-lookup scales its
fm-input argument to make its table size appear to be two pi.
The intention here is that table-lookup with a sinusoid in the table and a given FM signal
produces the same output as oscil with that FM signal.
The "type" argument sets the type of interpolation used: <code>mus-interp-none</code>,
<code>mus-interp-linear</code>, <code>mus-interp-lagrange</code>, or <code>mus-interp-hermite</code>.
make-table-lookup-with-env (defined in generators.scm) returns a new table-lookup generator with the envelope 'env' loaded into its table.
table-lookup might be defined:
</p>

<pre class="indented">
(let ((result (<a class=quiet href="#array-interp">array-interp</a> wave phase)))
  (set! phase (+ phase 
                 (<a class=quiet href="#hztoradians">hz-&gt;radians</a> frequency)
                 (* fm-input
                    (/ (length wave) 
                       2 pi))))
  result)
</pre>


<table>
<tr><td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((gen (make-table-lookup 440.0 :wave (partials-&gt;wave '(1 .5  2 .5)))))
    (do ((i 0 (+ i 1)))
        ((= i 44100))
      (outa i (* 0.5 (table-lookup gen))))))
</pre>
</div>
</td>
</tr><tr>
<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  gen = make_table_lookup(440.0, :wave, partials2wave([1.0, 0.5, 2.0, 0.5]));
  44100.times do |i| 
    outa(i, 0.5 * table_lookup(gen), $output) 
    end
  end.output
</pre>
</div>
</td>
</tr><tr>
<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  440.0 :wave '( 1 0.5  2 0.5 ) #f #f partials-&gt;wave make-table-lookup { gen }
  44100 0 do
    i  gen 0 table-lookup  f2/ *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>



<p>
In the past, table-lookup was often used for additive synthesis, so
there are two functions that make it easier to load up
various such waveforms:
</p>

<pre class="indented">
<em class=def id="partialstowave">partials-&gt;wave</em> synth-data wave (norm #t)
<em class=def id="phase-partialstowave">phase-partials-&gt;wave</em> synth-data wave (norm #t)
</pre>

<p>The "synth-data" argument is a list or float-vector of (partial amp) pairs: '(1 .5  2 .25)
gives a combination of a sine wave at the carrier (partial = 1) at amplitude .5, and
another at the first harmonic (partial = 2) at amplitude .25.  The partial amplitudes are
normalized to sum to a total amplitude of 1.0 unless the argument "norm"
is #f.  If the initial phases matter (they almost never do), you can use
phase-partials-&gt;wave; in this case the synth-data is a list or float-vector of (partial amp phase) triples with phases in radians.
If "wave" is not passed, these functions return a new float-vector.
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (simple-table dur)
  (let ((tab (<em class=red>make-table-lookup</em> :wave (<em class=red>partials-&gt;wave</em> '(1 .5  2 .5)))))
    (do ((i 0 (+ i 1))) ((= i dur))
      (<a class=quiet href="#outa">outa</a> i (* .3 (<em class=red>table-lookup</em> tab))))))
</pre>

<p>table-lookup can also be used as a sort of "freeze" function, looping through a sound repeatedly,
based on some previously chosen loop positions:
</p>

<pre class="indented">
(define (looper start dur sound freq amp)
  (let* ((beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> start))
         (end (+ beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
         (loop-data (<a class=quiet href="extsnd.html#mussoundloopinfo">mus-sound-loop-info</a> sound)))
    (if (or (null? loop-data)
            (&lt;= (cadr loop-data) (car loop-data)))
        (error 'no-loop-positions)
        (let* ((loop-start (car loop-data))
               (loop-length (- (+ (cadr loop-data) 1) loop-start))
               (sound-section (<a class=quiet href="#filetoarray">file-&gt;array</a> sound 0 loop-start loop-length (make-float-vector loop-length)))
               (original-loop-duration (/ loop-length (srate sound)))
               (tbl (<em class=red>make-table-lookup</em> :frequency (/ freq original-loop-duration) :wave sound-section)))
               ;; "freq" here is how fast we read (transpose) the sound &mdash; 1.0 returns the original
         (do ((i beg (+ i 1)))
             ((= i end))
           (<a class=quiet href="#outa">outa</a> i (* amp (<em class=red>table-lookup</em> tbl))))))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:srate 44100) (looper 0 10 "/home/bil/sf1/forest.aiff" 1.0 0.5))
</pre>

<p>And for total confusion, here's a table-lookup that modulates a sound where we specify the
modulation deviation in samples:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (fm-table file start dur amp read-speed modulator-freq index-in-samples)
  (let* ((beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> start))
         (end (+ beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
         (table-length (<a class=quiet href="extsnd.html#mussoundframples">mus-sound-framples</a> file))
         (tab (<em class=red>make-table-lookup</em> :frequency (/ read-speed (<a class=quiet href="extsnd.html#mussoundduration">mus-sound-duration</a> file)) 
                                 :wave (<a class=quiet href="#filetoarray">file-&gt;array</a> file 0 0 table-length (make-float-vector table-length))))
         (osc (<a class=quiet href="#make-oscil">make-oscil</a> modulator-freq))
         (index (/ (* (<a class=quiet href="#hztoradians">hz-&gt;radians</a> modulator-freq) 2 pi index-in-samples) table-length)))
   (do ((i beg (+ i 1)))
       ((= i end))
     (<a class=quiet href="#outa">outa</a> i (* amp (<em class=red>table-lookup</em> tab (* index (<a class=quiet href="#oscil">oscil</a> osc))))))))
</pre>

<p>Lessee.. there's a factor of table-length/(2*pi) in table-lookup, so that a table with a sinusoid
behaves the same as an oscil even with FM; hz-&gt;radians
adds a factor of (2*pi)/srate; so we've cancelled the internal 2*pi and table-length, and we have
an actual deviation of mfreq*2*pi*index/srate, which looks like FM; hmmm.  See <a href="#srcer">srcer</a>
below for an <a href="#src">src</a>-based way to do the same thing.
</p>

<p>
There is one annoying problem with table-lookup: noise.
Say we have a sine wave in a table with L elements, and we want to read it at a frequency of
f Hz at a sampling rate of Fs.  This requires that we read the table at locations that are multiples of
L * f / Fs.  This is ordinarily not an integer (that is, we've fallen between the
table elements).  We have no data between the elements, but we can make (plenty of)
assumptions about what ought to be there.  In the no-interpolation case (type = <code>mus-interp-none</code>), we take the floor of
the table-relative phase, returning a squared-off sine-wave:
</p>

<img src="pix/interp1.png" alt="squared-off sine spectra">

<!--
(with-sound (:srate 1000000 :channels 2) 
  (let ((gen1 (make-table-lookup 100.0 :wave (partials->wave '(1 1) (make-float-vector 100)) :type mus-interp-none))
        (sine (make-oscil 100.0)))
       (do ((i 0 (+ i 1))) 
           ((= i 1000000))
	 (let ((qsine (table-lookup gen1))
	       (tsine (oscil sine)))
	   (outa i qsine)
	   (outb i (- tsine qsine))))))

(set! *selected-graph-color* (make-color 1 1 1))
(set! *selected-data-color* (make-color 0 0 0))
(set! (x-axis-label 0 0 0) "no interpolation, table size=100, sine at 100 Hz")
(set! (x-axis-label 0 1 0) "difference between sine and squared-off sine")
(set! (x-axis-label 0 0 1) "squared-off sine spectrum: srate=1000000")
(set! (x-axis-label 0 1 1) "spectrum of the error")
(set! *axis-label-font* *axis-numbers-font*)
(set! *transform-normalization* normalize-by-sound)
(set! *graphs-horizontal* #f)
-->

<!-- 
     maxamp of sawtooth is 2pi/L (it's a max at 0 when sin x ~ x, and each phase increment is 2pi/L) 
-->

<p>
In addition to the sine at 100 Hz, we're getting lots of pairs of components, each pair centered around n * L * f, (10000 = 100 * 100 is the first),
and separated from it by f, (9900 and 10100),
and the amplitude of each pair is 1/(nL): -40 dB is 1/100 for the n=1 case.
This spectrum says "amplitude modulation" (the fast square wave times the slow sinusoid).
After scribbling a bit on the back of an envelope, we announce with a confident air that
the sawtooth error signal gives us the 1/n (it is a sum of sin nx/n), and its amplitude gives us the 1/L.
Now we try linear interpolation (<code>mus-interp-linear</code>), and get the same components as before, but
the amplitude is going (essentially) as 1.0 / (n * n * L * L).  So the interpolation
reduces the original problem by a factor of n * L:
</p>

<img src="pix/interp2.png" alt="squared-off sine spectra">

<!--
(with-sound (:srate 1000000 :channels 2) 
  (let ((gen1 (make-table-lookup 100.0 :wave (partials->wave '(1 1) (make-float-vector 100)) :type mus-interp-linear))
	(sine (make-oscil 100.0)))
       (do ((i 0 (+ i 1))) 
	   ((= i 1000000))
	 (let ((qsine (table-lookup gen1))
	       (tsine (oscil sine)))
	   (outa i qsine)
	   (outb i (- tsine qsine))))))

(set! (x-axis-label 0 0 0) "linear interpolation, table size=100, sine at 100 Hz")
(set! (x-axis-label 0 1 0) "difference between sine and interpolated sine")
(set! (x-axis-label 0 0 1) "interpolated sine spectrum: srate=1000000")
(set! (x-axis-label 0 1 1) "spectrum of the error")
-->

<p>
We can view this also as amplitude modulation:
the sinusoid at frequency f times the little blip during each table sample at frequency L * f.
Each component
is at n * L * f, as before, and split in half by the modulation.
Since L * f is normally a very high frequency, and sampling rates are not in the megahertz range (as in our examples),
these components
alias to such an extent that they look like noise, but they are noise only in the
sense that we wish they weren't there.  
</p>

<p>
The table length (L above) is the "effective" length.  If we store an nth harmonic
in the table, each period gets L/n elements (we want to avoid clicks caused by discontinuities between the first and last table elements), 
so the amplitude of the nth harmonic's noise components
is higher (by n^2) than the fundamental's.  We either have to use enormous
tables or stick to low
numbered partials.  To keep the noise components out of sight in 16-bit output (down 90 dB),
we need 180 elements per period.  So a table with a 50th harmonic has to be at least length 8192.
It's odd that the cutoff here is so similar to
the waveshaping case; a 50-th harmonic is trouble in either case.
(This leaves an opening for <a href="#ncos">ncos</a> and friends even when dynamic spectra aren't the issue).
</p>

<p>
We can try fancier interpolations.  <code>mus-interp-lagrange</code> and <code>mus-interp-hermite</code>
reduce the components (which are at the same frequencies as before) by about another factor of L.
But these interpolations are expensive and ugly.
If you're trying to produce a sum of sinusoids, use polywave &mdash; it makes a monkey out of table lookup in every case.
</p>


<!-- an earlier example showing the interpolation waveforms:

(with-sound (:channels 4 :clipped #f :statistics #t)
  (let* ((pitch 1000.0)
	 (size 64)
	 (tbl1 (make-table-lookup pitch 0.0 (partials->wave '(1 1) (make-float-vector size)) size mus-interp-none))
	 (tbl2 (make-table-lookup pitch 0.0 (partials->wave '(1 1) (make-float-vector size)) size mus-interp-linear))
	 (tbl3 (make-table-lookup pitch 0.0 (partials->wave '(1 1) (make-float-vector size)) size mus-interp-lagrange))
	 (tbl4 (make-table-lookup pitch 0.0 (partials->wave '(1 1) (make-float-vector size)) size mus-interp-hermite)))
       (do ((i 0 (+ i 1)))
	   ((= i 100000))
	 (outa i (table-lookup tbl1))
	 (outb i (table-lookup tbl2))
	 (out-any i (table-lookup tbl3) 2)
	 (out-any i (table-lookup tbl4) 3))))

(with-sound (:channels 5 :clipped #f :statistics #t)
  (let* ((pitch 2.0)
	 (size 64)
	 (wave (let ((v (make-float-vector size)))
		 (set! (v (/ size 2)) 1.0)
		 v))
	 (tbl1 (make-table-lookup pitch 0.0 wave size mus-interp-none))
	 (tbl2 (make-table-lookup pitch 0.0 wave size mus-interp-linear))
	 (tbl3 (make-table-lookup pitch 0.0 wave size mus-interp-lagrange))
	 (tbl4 (make-table-lookup pitch 0.0 wave size mus-interp-hermite))
	 (tbl5 (make-table-lookup pitch 0.0 wave size mus-interp-all-pass)))
       (do ((i 0 (+ i 1)))
	   ((= i 100000))
	 (outa i (table-lookup tbl1))
	 (outb i (table-lookup tbl2))
	 (out-any i (table-lookup tbl3) 2)
	 (out-any i (table-lookup tbl4) 3)
	 (out-any i (table-lookup tbl5) 4))))
-->


<div class="inset">
<p>table-lookup of a sine (or some facsimile thereof) probably predates Ptolemy.
One neat method of generating the table is that of Bhaskara I, AD 600, India, mentioned
in van Brummelen, "The Mathematics of the Heavens and the Earth": use the rational
approximation 4x(180-x)/(40500-x(180-x)), x in degrees, or more readably:
4x(pi-x)/(12.337-x(pi-x)), x in radians.  The maximum error is 0.00163 at x=11.54 (degrees)!
</p>
</div>

<!--
(define (bhaskara-sine x) ; x degrees
  (list (/ (* 4.0 x (- 180 x))
	   (- 40500 (* x (- 180 x))))
	(sin (degrees->radians x))
	(let* ((dx (degrees->radians x))
	       (px (- pi dx))
	       (cs (degrees->radians (degrees->radians 40500))))
	  (/ (* 4 dx px)
	     (- cs (* dx px))))
	(let ((dx (degrees->radians x)))
	  (/ (* 4 dx (- pi dx))
	     (- 12.337 (* dx (- pi dx)))))))

Ayyangar: Ganesh; same thing using n=pi/x: 16(n-1)/(5n^2-4n+4)
(define (ganesh-sine x) ; x radians
  (list (if (= x 0.0)
	    0.0
	    (let ((n (/ pi x)))
	      (/ (* 16 (- n 1))
		 (+ (* 5 n n) (* -4 n) 4))))
	(if (= x 0.0)
	    0.0
	    (let* ((n (/ pi x))
		   (n2 (* n n))
		   (n-2 (- n 2))
		   (n2-2 (* n-2 n-2)))
	      (/ (- n2 n2-2)
		 (+ n2 (/ n2-2 4)))))
	(sin x)))

(define (pade-sine x) ; x < pi/4, Martin Brown
  (list (* x (/ (- 60 (* 7 x x))
		(+ 60 (* 3 x x))))
	(sin x)))

(define (koren-sine ux) ; |ux| < pi/4, Kren and Zinaty
  (let* ((x (/ (* 4 ux) pi))
	 (x2 (* x x))
	 (a0 1805490264.6910)
	 (a1 -164384678.2275)
	 (a2    3664210.6476)
	 (a3     -28904.1402)
	 (a4         76.5690)
	 (b0 2298821602.6389)
	 (b1   27037050.1189)
	 (b2     155791.3885)
	 (b3        540.5675))
    (* x (/ (+ a0 (* x2 (+ a1 (* x2 (+ a2 (* x2 (+ a3 (* x2 a4))))))))
	    (+ b0 (* x2 (+ b1 (* x2 (+ b2 (* x2 (+ b3 x2)))))))))))
-->

<p><a href="spectr.scm">spectr.scm</a> has a steady state spectra of
several standard orchestral instruments, courtesy of James A. Moorer.
The <a href="sndscm.html#drone">drone</a> instrument in clm-ins.scm uses table-lookup for the
bagpipe drone.  <a href="sndscm.html#twotab">two-tab</a> in the same file interpolates between two tables.
See also <a href="sndscm.html#granidoc">grani</a>.
</p>




<!--  POLYWAVE, POLYSHAPE  -->

<div class="innerheader" id="polywavedoc">polywave, polyshape</div>

<pre class="indented">
<em class=def id="make-polywave">make-polywave</em> 
         (frequency 0.0) 
         (partials '(1 1))                   ; a list of harmonic numbers and their associated amplitudes
         (type mus-chebyshev-first-kind)     ; Chebyshev polynomial choice
         xcoeffs ycoeffs                     ; tn/un for tu-sum case

<em class=def id="polywave">polywave</em> w (fm 0.0)
<em class=def id="polywave?">polywave?</em> w

<em class=def id="make-polyshape">make-polyshape</em> 
        (frequency 0.0) 
        (initial-phase 0.0) 
        coeffs 
        (partials '(1 1)) 
        (kind mus-chebyshev-first-kind)

<em class=def id="polyshape">polyshape</em> w (index 1.0) (fm 0.0)
<em class=def id="polyshape?">polyshape?</em> w

<em class=def id="partialstopolynomial">partials-&gt;polynomial</em> partials (kind mus-chebyshev-first-kind)
<em class=def id="normalizepartials">normalize-partials</em> partials

<em class=def id="mus-chebyshev-tu-sum">mus-chebyshev-tu-sum</em> x t-coeffs u-coeffs
<em class=emdef>mus-chebyshev-t-sum</em> x t-coeffs
<em class=emdef>mus-chebyshev-u-sum</em> x u-coeffs
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">polywave methods</td></tr>
<tr><td class="inner"><em class=gen>mus-frequency</em></td><td class="inner">frequency in Hz</td></tr>
<tr><td class="inner"><em class=gen>mus-scaler</em></td><td class="inner">index</td></tr>
<tr><td class="inner"><em class=gen>mus-phase</em></td><td class="inner">phase in radians</td></tr>
<tr><td class="inner"><em class=gen>mus-data</em></td><td class="inner">polynomial coeffs</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">number of partials</td></tr>
<tr><td class="inner"><em class=gen>mus-increment</em></td><td class="inner">frequency in radians per sample</td></tr>
</table>

<p>
These two generators
drive a sum of scaled Chebyshev polynomials with
a cosine, creating a sort of cross between additive synthesis and FM; see
"Digital Waveshaping Synthesis" by Marc Le Brun in JAES 1979 April, vol 27, no 4, p250.
The basic idea is:
</p>

<img class="indented" src="pix/sceq16.png" alt="Cheby eqs">

<p>
We can add scaled Tns (polynomials) to get the spectrum we want, producing
in the simplest case an inexpensive additive synthesis.  We can vary the peak amplitude of the
input (cos theta) to get effects similar to those of FM. 
polyshape uses a prebuilt sum of Chebyshev polynomials,
whereas polywave uses the underlying Chebyshev recursion.  
polywave is stable and noise-free even with high partial numbers (I've tried it with 16384 harmonics).
The "partials" argument to the make function can
be either a list or a float-vector ("vct" in Ruby and Forth).
The "type" or "kind" argument determines which kind of Chebyshev polynomial
is used internally:  mus-chebyshev-first-kind (Tn) which produces a sum of cosines,
or mus-chebyshev-second-kind (Un), which produces a sum of sines.
</p>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((gen (make-polywave 440.0 :partials '(1 .5  2 .5))))
    (do ((i 0 (+ i 1)))
        ((= i 44100))
      (outa i (* 0.5 (polywave gen))))))
</pre>
</div>
</td>
</tr><tr>
<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  gen = make_polywave(440.0, :partials, [1.0, 0.5, 2.0, 0.5]);
  44100.times do |i| 
    outa(i, 0.5 * polywave(gen), $output) 
    end
  end.output
</pre>
</div>
</td>
</tr><tr>
<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  440.0 :partials '( 1 0.5 2 0.5 ) make-polywave { gen }
  44100 0 do
    i  gen 0 polywave  f2/ *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>


<!-- LATEX: sceq16
\begin{align*}
&T_{n}(\cos \theta)=\cos n\theta \\
&U_{n}(\cos \theta)=\frac{\sin(n+1) \theta}{\sin \theta}
\end{align*}

A&S 22.3.15
-->


<p>normalize-partials takes the list or float-vector of partial number and amplitudes, and
returns a float-vector with the amplitudes normalized so that their magnitudes add to 1.0. 
</p>

<pre class="indented">
&gt; (normalize-partials '(1 1 3 2 6 1))
#(1.0 0.25 3.0 0.5 6.0 0.25);
&gt; (normalize-partials (float-vector 1 .1 2 .1 3 -.2))
#(1.0 0.25 2.0 0.25 3.0 -0.5)
</pre>

<p>
partials-&gt;polynomial
takes a list or float-vector of partial numbers and amplitudes
and returns the Chebyshev polynomial coefficients that 
produce that spectrum.  These coefficients can be passed to
polyshape (the coeffs argument), or used directly by <a href="#polynomial">polynomial</a> (there are examples of both below).
</p>

<pre class="indented">
&gt; (partials-&gt;polynomial '(1 1 3 2 6 1))
#(-1.0 -5.0 18.0 8.0 -48.0 0.0 32.0)
&gt; (partials-&gt;polynomial '(1 1 3 2 6 1) mus-chebyshev-second-kind)
#(-1.0 6.0 8.0 -32.0 0.0 32.0 0.0)
&gt; (partials-&gt;polynomial (float-vector 1 .1 2 .1 3 -.2))
#(-0.1 0.7 0.2 -0.8)
</pre>

<p>mus-chebyshev-tu-sum and friends perform the same function as partials-&gt;polynomial, but
use the much more stable and accurate underlying recursion (see below for a long-winded
explanation).  They are the innards of the polywave and <a href="#polyoid">polyoid</a> generators.
The arguments are "x" (normally a phase), and one or two
float-vectors of component amplitudes.  
These functions makes it easy to do additive synthesis
with any number of harmonics (I've tried 16384), each with arbitrary
initial-phase and amplitude, and each harmonic independently changeable 
in phase and amplitude at run-time by setting a float-vector value.
</p>

<pre class="indented">
(let ((result (<a class=quiet href="#polynomial">polynomial</a> wave (cos phase))))
  (set! phase (+ phase (<a class=quiet href="#hztoradians">hz-&gt;radians</a> frequency) fm))
  result)
</pre>

<p>In its simplest use, waveshaping is additive synthesis:
</p>

<table>
<tr><td>
<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (let ((wav (<em class=red>make-polyshape</em> 
               :frequency 500.0
               :partials '(1 .5  2 .3  3 .2))))
    (do ((i 0 (+ i 1))) ((= i 40000))
      (<a class=quiet href="#outa">outa</a> i (<em class=red>polyshape</em> wav)))))
</pre>
</td>
<td>
<img src="pix/polyshape.png" alt="waveshaping">
</td>
</tr></table>

<p>Say we want every third harmonic at amplitude 1/sqrt(harmonic-number) for 5 harmonics total:
</p>


<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:clipped #f :statistics #t :play #t :scaled-to .5)
  (let ((gen (<em class=red>make-polywave</em> 200 
               (do ((harms (make-float-vector (* 5 2))) ; 5 harmonics, 2 numbers for each
                    (k 1 (+ k 3))
		    (i 0 (+ i 2)))
	           ((= i 10) harms)
	         (set! (harms i) k) ; harmonic number (k*freq)
	         (set! (harms (+ i 1)) (/ 1.0 (sqrt k)))))) ; harmonic amplitude
	(ampf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 10 1 11 0) :duration 1.0 :scaler .5)))
    (do ((i 0 (+ i 1)))
	((= i 44100))
      (<a class=quiet href="#outa">outa</a> i (* (<a class=quiet href="#env">env</a> ampf) (<em class=red>polywave</em> gen))))))
</pre>


<p>See animals.scm for many more examples along these lines.
normalize-partials makes sure that the component amplitudes (magnitudes) add to 1.0.  Its argument can be either a list or float-vector,
but it always returns a float-vector.
The <a href="sndscm.html#fmviolin">fm-violin</a> uses polyshape for the multiple FM section in some cases.
The <a href="sndscm.html#pqw">pqw</a> and <a href="sndscm.html#pqwvox">pqwvox</a> instruments use
both kinds of Chebyshev polynomials to produce single side-band spectra.
Here is a somewhat low-level example:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (pqw start dur spacing carrier partials)
  (let* ((spacing-cos (<a class=quiet href="#make-oscil">make-oscil</a> spacing (/ pi 2.0)))
	 (spacing-sin (<a class=quiet href="#make-oscil">make-oscil</a> spacing))
	 (carrier-cos (<a class=quiet href="#make-oscil">make-oscil</a> carrier (/ pi 2.0)))
	 (carrier-sin (<a class=quiet href="#make-oscil">make-oscil</a> carrier))
	 (sin-coeffs (<em class=red>partials-&gt;polynomial</em>
                       partials mus-chebyshev-second-kind))
	 (cos-coeffs (<em class=red>partials-&gt;polynomial</em>
                       partials mus-chebyshev-first-kind))
	 (beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> start))
	 (end (+ beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur))))
    (do ((i beg (+ i 1))) 
        ((= i end))
      (let ((ax (<a class=quiet href="#oscil">oscil</a> spacing-cos)))
        (<a class=quiet href="#outa">outa</a> i (- (* (<a class=quiet href="#oscil">oscil</a> carrier-sin) 
                      (<a class=quiet href="#oscil">oscil</a> spacing-sin) 
	              (<em class=red>polynomial</em> sin-coeffs ax))
	           (* (<a class=quiet href="#oscil">oscil</a> carrier-cos) 
	              (<em class=red>polynomial</em> cos-coeffs ax))))))))
</pre>

<table class="pb">
<tr><td>
<img src="pix/pqw.png" alt="pqw example">
</td></tr>
<tr><td class="br">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () (pqw 0 1 200.0 1000.0 '(2 .2  3 .3  6 .5)))
</td></tr>
</table>


<p>We can use waveshaping to make a band-limited triangle-wave:
</p>

<pre class="indented">
(define* (make-band-limited-triangle-wave (frequency 0.0) (order 1))
  (do ((freqs ())
       (i 1 (+ i 1))
       (j 1 (+ j 2)))
      ((&gt; i order)
       (<em class=red>make-polywave</em> frequency :partials (reverse freqs)))
    (set! freqs (cons (/ 1.0 j j) (cons j freqs)))))

(define* (band-limited-triangle-wave gen (fm 0.0))
  (<em class=red>polywave</em> gen fm))
</pre>

<p>Band-limited square or sawtooth waves:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (bl-saw start dur frequency order)
  (let ((norm (cond ((assoc order '((1 . 1.0) (2 . 1.3)) =) =&gt; cdr) ; these peak amps were determined empirically
                     ((&lt; order 9) 1.7)                              ;   actual limit is supposed to be pi/2 (G&amp;R 1.441)
                     (else 1.852)))                                 ;   but Gibbs phenomenon pushes it to 1.851
        (freqs ()))
    (do ((i 1 (+ i 1)))
	((&gt; i order))
      (set! freqs (cons (/ 1.0 norm i) (cons i freqs))))
    (let* ((gen (<em class=red>make-polywave</em> frequency :partials (reverse freqs) :type <em class=red>mus-chebyshev-second-kind</em>))
	   (beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> start))
	   (end (+ beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur))))
     (do ((i beg (+ i 1))) 
         ((= i end))
       (<a class=quiet href="#outa">outa</a> i (<em class=red>polywave</em> gen))))))
</pre>

<p>The "fm" argument to these generators is intended mainly for vibrato and frequency envelopes. 
If you use it for frequency modulation, you'll notice that the result is not the necessarily same as applying that
modulation to the equivalent bank of oscillators, but it is the same as (for example) applying it to an ncos
generator, or most of the other generators (table-lookup, nsin, etc).  The polynomial in cos(x) produces
a sum of cos(nx) for various "n", but if "x" is itself a sinusoid, its
effective index includes the factor of "n" (the partial number). 
This is what you want
if all the components should move together (as in vibrato).  If you need better control of the FM spectrum,
use a bank of oscils where you can set each index independently.  Here we used '(1 1 2 1 3 1) and polyshape
with sinusoidal FM with an index of 1.
</p>

<img class="indented" src="pix/polyfm.png" alt="polyshape fm">


<p>The same thing happens if you use polyshape or ncos (or whatever) as the (complex) modulating signal to an oscil
(the reverse of the situation above).
The effective index of each partial is divided by the partial number (and in ncos, for example, the output
is scaled to be -1..1, so that adds another layer of confusion). There's a longer discussion of this under
<a href="#ncosdoc">ncos</a>.
</p>

<!-- actually you get either cos(nx) or +/-cos(nx) depending on which algorithm is actually chosen
-->
<!--
(define* (fmsin beg dur freq amp mc-ratio index type)
  (let* ((start (seconds->samples beg))
         (end (+ start (seconds->samples dur)))
	 (carrier (if (= type 0)
		      (let ((oscs (make-vector 3 #f)))
			(do ((i 0 (+ i 1)))
			    ((= i 3))
			  (set! (oscs i) (make-oscil (* freq (+ i 1)))))
			oscs)
		      (if (= type 1)
			  (make-ncos freq 3)
			  (if (= type 2)
			      (make-polyshape freq :coeffs (partials->polynomial '(1 1 2 1 3 1)))
			      (if (= type 3)
				  (make-table-lookup freq :wave (partials->wave '(1 1 2 1 3 1)))
				  (if (= type 4)
				      (make-waveshape freq :partials '(1 1 2 1 3 1))
				      (if (= type 5)
					  (make-nsin freq 3)
					  (if (= type 6)
					      (make-ncos2 freq 3)
					      (if (= type 7)
						  (make-ncos4 freq 3)
						  (if (= type 8)
						  (make-nrcos freq 3 .99)
						  (if (= type 9)
						      (make-nkssb freq freq 3)
						      )))))))))))
	 (modulator (make-oscil (* freq mc-ratio)))
	 (fm-index (hz->radians (* index freq mc-ratio)))
	 (ampf (make-env '(0 0 1 1 10 1 11 0) :scaler amp :duration dur)))
    (do ((i start (+ i 1)))
	((= i end))
      (let ((md (* fm-index (oscil modulator))))
	(outa i (* (env ampf)
		   (if (= type 0)
		       (let ((sum 0.0))
			 (do ((k 0 (+ k 1)))
			     ((= k 3))
			   (set! sum (+ sum (oscil (carrier k) (* (+ k 1) md))))) ; or leave unscaled
			 (/ sum 3))
		       (if (= type 1)
			   (sum-of-cosines carrier md)
			   (if (= type 2)
			       (/ (polyshape carrier 1.0 md) 3)
			       (if (= type 3)
				   (/ (table-lookup carrier md) 3)
				   (if (= type 4)
				       (waveshape carrier 1.0 md)
				       (if (= type 5)
					   (sum-of-sines carrier md)
					   (if (= type 6)
					       (ncos2 carrier md)
					       (if (= type 7)
						   (ncos4 carrier md)
						   (if (= type 8)
						       (nrcos carrier md)
						       (if (= type 9)
							   (nkssb carrier md)
							   0.0))))))))))))))))
-->

<p>To get the FM effect of a spectrum centered around a carrier, multiply the waveshaping output by the carrier (the 0Hz term gives us the carrier):
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (let ((modulator (<em class=red>make-polyshape</em> 100.0 :partials (list 0 .4  1 .4  2 .1  3 .05  4 .05)))
	(carrier (<a class=quiet href="#make-oscil">make-oscil</a> 1000.0)))
    (do ((i 0 (+ i 1))) ((= i 20000))
      (<a class=quiet href="#outa">outa</a> i (* .5 (<a class=quiet href="#oscil">oscil</a> carrier) (<em class=red>polyshape</em> modulator))))))
</pre>


<p>The simplest way to get 
changing spectra is to interpolate between two or more sets of coefficients.
</p>

<pre class="indented">
(+ (* interp (polywave p1 ...))  ; see animals.scm for many examples
   (* (- 1.0 interp) (polywave p2 ...)))
</pre>

<p>Or use mus-chebyshev-*-sum and set the component amplitudes directly:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (let* ((dur 1.0)
	 (samps (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur))
	 (coeffs (float-vector 0.0 0.5 0.25 0.125 0.125))
	 (x 0.0)
	 (incr (<a class=quiet href="#hztoradians">hz-&gt;radians</a> 100.0))
	 (ampf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 10 1 11 0) :duration dur :scaler .5))
	 (harmf (<a class=quiet href="#make-env">make-env</a> '(0 .125 1 .25) :duration dur)))
    (do ((i 0 (+ i 1)))
	((= i samps))
      (let ((harm (<a class=quiet href="#env">env</a> harmf)))
	(set! (coeffs 3) harm)
	(set! (coeffs 4) (- .25 harm)))
      (<a class=quiet href="#outa">outa</a> i (* (<a class=quiet href="#env">env</a> ampf)
		   (<em class=red>mus-chebyshev-t-sum</em> x coeffs)))
      (set! x (+ x incr)))))
</pre>

<p>
But we can also vary 
the index (the amplitude of the cosine driving the sum of polynomials), much as in FM.
The kth partial's amplitude
at a given index, given a set h[k] of coefficients, is:
</p>

<img class="indented" src="pix/sceq43.png" alt="cheby hka calc">

<!-- LATEX:
    &h_{k}(a) = \sum_{j=0}^{\infty} \binom{p}{j} a^{p} \sum_{i=0}^{\infty} (-1)^{i}\Big(\tbinom{p+i}{i} + \tbinom{p+i-1}{i-1}\Big) h_{p+2i}(1) & p=k+2j \\
-->

<p>(This formula is implemented by <a href="sndscm.html#chebyhka">cheby-hka</a> in dsp.scm).
The function traced out by the harmonic (analogous to the role the Bessel function Jn plays in FM)
is a polynomial in the index whose order depends on the number of coefficients.  When the index is less than 1.0,
energy appears in lower harmonics even if they are not included in the index=1.0 list:
</p>

<pre class="indented">
&gt; (cheby-hka 3 0.25 (float-vector 0 0 0 0 1.0 1.0))
-0.0732421875
&gt; (cheby-hka 2 0.25 (float-vector 0 0 0 0 1.0 1.0))
-0.234375
&gt; (cheby-hka 1 0.25 (float-vector 0 0 0 0 1.0 1.0))
1.025390625
&gt; (cheby-hka 0 0.25 (float-vector 0 0 0 0 1.0 1.0))
1.5234375
</pre>

<p>
Below we sweep the index from 0.0
to 1.0 (sticking at 1.0 for a moment at the end), with a partials list of '(11 1.0 20 1.0).  These numbers were chosen to show that the even and
odd harmonics are independent:
</p>

<pre class="indented">
  (<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
    (let ((gen (<em class=red>make-polyshape</em> 100.0 :partials (list 11 1 20 1)))
	  (ampf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 20 1 21 0) :scaler .4 :length 88200))
	  (indf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 1.1 1) :length 88200)))
      (do ((i 0 (+ i 1)))
	  ((= i 88200))
        (<a class=quiet href="#outa">outa</a> i (* (<a class=quiet href="#env">env</a> ampf) (<em class=red>polyshape</em> gen (<a class=quiet href="#env">env</a> indf)))))))
</pre>

<table>
<tr><td>
<img src="pix/waver.png" alt="picture of waveshaping sweep">
</td><td>
<img src="pix/waver2.png" alt="time domain">
</td></tr>
</table>

<!--
;;; data cutoff .015 light 56 jet
;;; xangle 292 scale 1.45 yangle 0 scale .68 zangle 0 scale 1.39, % 43
-->

<p>You can see there's
another annoying "gotcha":  the DC component can be arbitrarily large.
If we don't counteract it in some way, we lose dynamic range, and we get a big click when the generator stops.
In addition (as the right graph shows, although in this case the effect is minor), the peak amplitude is dependent on the index.  We can reduce this
problem somewhat by changing the signs of the harmonics to follow the
pattern + + - -: 
</p>

<pre class="indented">
(list 1 .5  2 .25  3 -.125  4 -.125) ; squeeze the amplitude change toward index=0
</pre>

<p>but now the peak amplitude is hard to predict (it's .6242 in this example).  Perhaps <a href="sndscm.html#flattenpartials">flatten-partials</a>
would be a better choice here.
To follow an amplitude envelope despite a changing index, we can use a <a href="#moving-max">moving-max</a> generator:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (let ((gen (<em class=red>make-polyshape</em> 1000.0 :partials (list 1 .25 2 .25 3 .125 4 .125 5 .25)))
	(indf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 2 0) :duration 2.0))     ; index env
	(ampf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 2 1 3 0) :duration 2.0)) ; desired amp env
	(mx (<a class=quiet href="#moving-max">make-moving-max</a> 256))                         ; track actual current amp
	(samps (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> 2.0)))
    (do ((i 0 (+ i 1)))
	((= i samps))
      (let ((val (<em class=red>polyshape</em> gen (<a class=quiet href="#env">env</a> indf))))              ; polyshape with index env
	(<a class=quiet href="#outa">outa</a> i (/ (* (<a class=quiet href="#env">env</a> ampf) val)
		   (max 0.001 (<a class=quiet href="#moving-max">moving-max</a> mx val))))))))
</pre>

<p>The harmonic amplitude formula for the Chebyshev polynomials of the second kind is:
</p>

<img class="indented" src="pix/sceq44.png" alt="more cheby hka calcs">

<!-- LATEX:
    &h_{k}(a) = \sum_{j=0}^{\infty} \Big(\tbinom{p-1}{j} - \tbinom{p-1}{j-1}\Big) a^p \sum_{i=0}^{\infty} (-1)^{i} \tbinom{p+i-1}{i} h_{p+2i}(1) & p=k+2j \\
-->

<p>
On a related topic, if we drive the sum of Chebyshev polynomials with more than one sinusoid,
we get sum and difference tones, much as in complex FM:
</p>

<!-- LATEX t5sum:
\lefteqn{T_{5}\Big(  \frac{\cos(x) + \cos(20x)}{2}\Big) = } \\
\frac{1}{32} \big( & \cos (100x)+5 \cos (81x)+5 \cos (79x)+10 \cos (62x)+5 \cos (60x)+ \\
                   & 10 \cos (58x)+ 10 \cos (43x)-10  \cos (41x)-10 \cos (39x)+10 \cos (37x)+ \\
                   & 5 \cos (24x)-10 \cos (22x)- 10 \cos (18x)+5 \cos (16x)+ \cos (5x)+5 \cos (3x) \big)
-->

<table class="method">
<tr><td>
<div class="center">T5 driven with sinusoids at 100Hz and 2000Hz</div>
<hr>
<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (let ((pcoeffs (<em class=red>partials-&gt;polynomial</em> (float-vector 5 1)))
	(gen1 (<a class=quiet href="#make-oscil">make-oscil</a> 100.0))
	(gen2 (<a class=quiet href="#make-oscil">make-oscil</a> 2000.0)))
    (do ((i 0 (+ i 1)))
	((= i 44100))
      (<a class=quiet href="#outa">outa</a> i (<em class=red>polynomial</em> pcoeffs 
                (* 0.5 (+ (<a class=quiet href="#oscil">oscil</a> gen1)
		          (<a class=quiet href="#oscil">oscil</a> gen2))))))))
</pre>
<hr>
<div class="center"><img src="pix/t5sum.png" alt="t5"></div>
</td>
<td>
<img class="indented" src="pix/crosswave.png" alt="cross">
</td></tr></table>

<p>This kind of output is typical; I get the impression that the cross products are
much more noticeable here than in FM. 
Of course, we can take advantage of that:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:channels 2)
  (let* ((dur 2.0)
	 (samps (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur))
	 (p1 (<em class=red>make-polywave</em> 800 (list 1 .1  2 .3  3 .4 5 .2)))
	 (p2 (<em class=red>make-polywave</em> 400 (list 1 .1  2 .3  3 .4 5 .2)))
	 (interpf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1) :duration dur))
	 (p3 (<em class=red>partials-&gt;polynomial</em> (list 1 .1  2 .3  3 .4  5 .2)))
	 (g1 (<a class=quiet href="#make-oscil">make-oscil</a> 800))
	 (g2 (<a class=quiet href="#make-oscil">make-oscil</a> 400))
	 (ampf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 10 1 11 0) :duration dur)))
    (do ((i 0 (+ i 1)))
	((= i samps))
      (let ((interp (<a class=quiet href="#env">env</a> interpf))
	    (amp (<a class=quiet href="#env">env</a> ampf)))
	;; chan A: interpolate from one spectrum to the next directly
	(<a class=quiet href="#outa">outa</a> i (* amp (+ (* interp (<em class=red>polywave</em> p1))
			  (* (- 1.0 interp) (<em class=red>polywave</em> p2)))))
        ;; chan B: interpolate inside the sum of Tns!
	(<a class=quiet href="#outa">outb</a> i (* amp (<em class=red>polynomial</em> p3 (+ (* interp (<a class=quiet href="#oscil">oscil</a> g1))
					 (* (- 1.0 interp) (<a class=quiet href="#oscil">oscil</a> g2))))))))))
</pre>

<p>
If we use an arbitrary sound as the argument
to the polynomial, the output is a brightened or distorted version of the
original:
</p>

<!-- 
(The comparison in the T5 case above is between
T5(a+b) = 16(a+b)^5 - 20(a+b)^3 + 5(a+b) and the complex FM equation cos(5*(a+b))).
-->

<pre class="indented">
  (define (brighten-slightly coeffs)
    (let ((pcoeffs (partials-&gt;polynomial coeffs))
	  (mx (<a class=quiet href="extsnd.html#maxamp">maxamp</a>)))
      (<a class=quiet href="extsnd.html#mapchannel">map-channel</a>
       (lambda (y)
         (* mx (<a class=quiet href="#polynomial">polynomial</a> pcoeffs (/ y mx)))))))
</pre>

<p>but watch out for clicks from the DC component if any of the "n" in the Tn are even.
When I use this idea, I either use only odd numbered partials in the partials-&gt;polynomial list,
or add an amplitude envelope to make sure the result ends at 0.  I suppose you could also subtract out
the DC term (coeffs[0]), but I haven't tried this.
</p>

<!--
(with-sound (:channels 3 :clipped #f :statistics #t)
  (let* ((dur 1.0)
	 (samps (seconds->samples dur))
	 (coeffs (partials->polynomial '(5 1)))
	 (gen (make-oscil 100.0))
	 (gen1 (make-oscil 500.0)))
    (do ((i 0 (+ i 1)))
	((= i samps))
      (let* ((val (oscil gen))
	     (nval (oscil gen1))
	     (aval (polynomial coeffs (- 1.0 (* 2 val val))))
	     (bval (- 1.0 (* 2 nval nval)))
	     (cval (- aval bval)))
	(outa i aval)
	(outb i bval)
	(outc i cval)))))
-->

<p>If you push the polyshape generator into high harmonics (above say 30), you'll
run into numerical trouble (the polywave generator is immune to this bug).
Where does the trouble lie?
The polynomials are related to each other
via the recursion: <img src="pix/sceq17.png" alt="Cheby recurse">, so the first
few polynomials are:
</p>

<!-- LATEX:
\begin{align*}
&T_{0}(x)=1 \\
&T_{1}(x)=x \\
&T_{2}(x)=2x^{2}-1\\
&T_{3}(x)=4x^{3}-3x \\
&T_{4}(x)=8x^{4}-8x^{2}+1
\end{align*}

\begin{align*}
&U_{0}(x)=1 \\
&U_{1}(x)=2x \\
&U_{2}(x)=4x^{2}-1 \\
&U_{3}(x)=8x^{3}-4x \\
&U_{4}(x)=16x^{4}-12x^{2}+1
\end{align*}

-->

<table>
<tr>
<td><img class="indented" src="pix/sceq18.png" alt="some Chebys"></td>
<td><img class="indented" src="pix/sceq19.png" alt="more Chebys"></td>
</tr></table>

<p>The first coefficient is 2^n or 2^(n-1).  This is bad news if "n" is large because
we are expecting a bunch of huge numbers 
to add up to something in the vicinity of 0.0 or 1.0.  
If we're using 32-bit floats, the first sign of trouble comes when the order is around 26.
If you look at some of the coefficients, you'll see numbers like -129026688.000 (in the 32 bit case), which
should be -129026680.721 &mdash;  we have run out of bits in the mantissa!
With doubles
we can only push the order up to around 46. 
polywave, on the other hand, builds up the sum of sines from the underlying recursion, which is only slightly
slower than using the polynomial, and it is not bothered by these numerical problems.
I have run polywave with 16384 harmonics, and the maximum error compared to the
equivalent sum of sinusoids was around 5.0e-12.
</p>

<p>Since it is primarily used for additive synthesis, and we can always do that with oscils or table-lookup,
we might ask why we'd want polywave at all.  Leaving aside
speed (the Chebyshev computation is 10 to 20 times faster than the equivalent sum of oscils)
and memory (the defunct table-lookup based waveshape generator and table-lookup itself use a table that has to be loaded),
the main reason to use polywave is accuracy.  polywave
produces output that is as clean as the equivalent sum of oscils, whereas table-lookup 
and poor old waveshape, both of which interpolate into a sampled version of the desired function, are noisy.
To make the difference almost appalling, here are spectra comparing a sum of oscils, polyshape,
(table-lookup based) waveshape, and table-lookup. 
</p>

<img src="pix/4grfs.png" alt="compare ffts">

<!--
(with-sound (:channels 4)
  (let ((poly (make-polyshape 100.0 :partials '(1 1 8 1 16 1)))
	(wave (make-waveshape 100.0 :partials '(1 1 8 1 16 1))) ; this is normalized
	(gen1 (make-oscil 100))
	(gen2 (make-oscil 800))
	(gen3 (make-oscil 1600))
	(table (make-table-lookup 100.0 :wave (partials->wave '(1 1 8 1 16 1))))
	)
       (do ((i 0 (+ i 1)))
	   ((= i 500000))
	 (out-any i (* .3 (+ (oscil gen1) (oscil gen2) (oscil gen3))) 0)
	 (out-any i (* .3 (polyshape poly)) 1)
	 (out-any i (* .9 (waveshape wave)) 2)
	 (out-any i (* .3 (table-lookup table)) 3))))
	 
(set! (x-axis-label 0 0 1) "sum of oscils: frequency")
(set! (x-axis-label 0 1 1) "polyshape: frequency")
(set! (x-axis-label 0 2 1) "waveshape: frequency")
(set! (x-axis-label 0 3 1) "table-lookup: frequency")
-->

<div class="inset">
<p>
The table size is 512, but that almost doesn't matter; you'd have to use a table size of at least 8192
to approach the oscil and polyshape cases.  The FFT size is 1048576, with no data window ("rectangular"), and the y-axis
is in dB, going down to -120 dB.  The choice of fft window
can make a big difference; using no window, but a huge fft seems like the least confusing
way to present this result.
</p>
<p>
Notice the lower peaks in the table-lookup case.  partials-&gt;wave puts n periods of the nth harmonic
in the table, so the nth harmonic has an effective table length of table-length/n.  n * 1/n = 1, so all
our components have their first interpolation noise peak centered (in this case) around 7100 Hz ((512 * 100) mod 22050).
Since the 1600 Hz component has an effective table size of only 32 samples, it creates big sidebands at 5500 Hz
and 8700 Hz.  The 800 Hz component makes smaller peaks (by a factor of 4, since this is proportional to n^2) at
6300 Hz and 7900 Hz, and the 100 Hz
cases are at 7000 Hz and 7200 Hz (down in amplitude by 16^2).  The highest peaks are down only 60 dB.
See <a href="#table-lookup">table-lookup</a> for more discussion of interpolation noise (it's actually
amplitude modulation of the stored signal and the linear interpolating signal with severe aliasing).
</p>
<p>
The waveshaping noise is much worse because the polynomial is so 
sensitive numerically.  Here is a portion of the error signal at the point where the driving sinusoid
is at its maximum:
</p>
<img class="indented" src="pix/errorwave.png" alt="cheby error">
</div>

<!--
;;; omitted 100 component since it is clean and I couldn't get it to cancel...
(with-sound (:srate 1000000)
  (let ((wave (make-waveshape 100.0 :partials '(8 1 16 1) :size 512))
	(osc1 (make-oscil 1600.0 (* 0.5 pi))) 
	(osc2 (make-oscil 800.0 (* 0.5 pi))))
    (do ((i 0 (+ i 1)))
	((= i 1000000))
      (outa i (- (waveshape wave)
		 (* 1/2 (+ (oscil osc1) 
			   (oscil osc2))))))))
-->


<!-- this works: (make-waveshape 100.0 :partials '(1 1) :size 2)
     because the initial "polynomial" is a straight line: 
       :(mus-data (make-waveshape 100.0 :partials '(1 1) :size 2))
       #(-1.000 1.000)
     and we use array-interp to drive it with a sinusoid, so x=x!
-->

<p>
See also <a href="#polyoid">polyoid and noid</a> in generators.scm.
</p>





<!--  SAWTOOTH ETC  -->

<div class="innerheader" id="sawtoothdoc">sawtooth-wave, triangle-wave, pulse-train, square-wave</div>

<pre class="indented">
<em class=def id="make-triangle-wave">make-triangle-wave</em> (frequency 0.0) (amplitude 1.0) (initial-phase pi)
<em class=def id="triangle-wave">triangle-wave</em> s (fm 0.0)
<em class=def id="triangle-wave?">triangle-wave?</em> s

<em class=def id="make-square-wave">make-square-wave</em> (frequency 0.0) (amplitude 1.0) (initial-phase 0)
<em class=def id="square-wave">square-wave</em> s (fm  0.0)
<em class=def id="square-wave?">square-wave?</em> s

<em class=def id="make-sawtooth-wave">make-sawtooth-wave</em> (frequency 0.0) (amplitude 1.0) (initial-phase pi)
<em class=def id="sawtooth-wave">sawtooth-wave</em> s (fm 0.0)
<em class=def id="sawtooth-wave?">sawtooth-wave?</em> s

<em class=def id="make-pulse-train">make-pulse-train</em> (frequency 0.0) (amplitude 1.0) (initial-phase (* 2 pi))
<em class=def id="pulse-train">pulse-train</em> s (fm 0.0)
<em class=def id="pulse-train?">pulse-train?</em> s
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">saw-tooth and friends' methods</td></tr>
<tr><td class="inner"><em class=gen>mus-frequency</em></td><td class="inner">frequency in Hz</td></tr>
<tr><td class="inner"><em class=gen>mus-phase</em></td><td class="inner">phase in radians</td></tr>
<tr><td class="inner"><em class=gen>mus-scaler</em></td><td class="inner">amplitude arg used in make-&lt;gen&gt;</td></tr>
<tr><td class="inner"><em class=gen>mus-width</em></td><td class="inner">width of square-wave pulse (0.0 to 1.0)</td></tr>
<tr><td class="inner"><em class=gen>mus-increment</em></td><td class="inner">frequency in radians per sample</td></tr>
</table>

<p>These generators produce some standard old-timey wave forms that are still occasionally useful (well, triangle-wave
is useful; the others are silly).
One popular kind of vibrato is:
</p>

<pre class="indented">
  (+ (triangle-wave pervib) 
     (<a class=quiet href="#rand-interp">rand-interp</a> ranvib))
</pre>

<p>sawtooth-wave ramps from -1 to 1, then goes immediately back to -1.
Use a negative frequency to turn the "teeth" the other way.
To get a sawtooth from 0 to 1, you can use modulo:
</p>
<pre class="indented">
(with-sound () (do ((i 0 (+ i 1)) (x 0.0 (+ x .01))) ((= i 22050)) (outa i (modulo x 1.0))))
</pre>

<p>
triangle-wave ramps from -1 to 1, then ramps from 1 to -1.
pulse-train produces a single sample of 1.0, then zeros.
square-wave produces 1 for half a period, then 0.  All have a period
of two pi, so the "fm" argument should have an effect comparable to the
same FM applied to the same waveform in <a href="#table-lookup">table-lookup</a>.
</p>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((gen (make-triangle-wave 440.0)))
    (do ((i 0 (+ i 1)))
        ((= i 44100))
      (outa i (* 0.5 (triangle-wave gen))))))
</pre>
</div>
</td>
</tr><tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  gen = make_triangle_wave(440.0);
  44100.times do |i| 
    outa(i, 0.5 * triangle_wave(gen), $output) 
    end
  end.output
</pre>
</div>
</td>
</tr><tr>
<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  440.0 make-triangle-wave { gen }
  44100 0 do
    i  gen 0 triangle-wave  f2/ *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>


<p>To get a square-wave with control over the "duty-factor":
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (let* ((duty-factor .25) ; ratio of pulse duration to pulse period
	 (p-on (<em class=red>make-pulse-train</em> 100 0.5))
	 (p-off (<em class=red>make-pulse-train</em> 100 -0.5 (* 2 pi (- 1.0 duty-factor)))))
    (do ((sum 0.0)
         (i 0 (+ i 1)))
	((= i 44100))
      (set! sum (+ sum (<em class=red>pulse-train</em> p-on) (<em class=red>pulse-train</em> p-off)))
      (<a class=quiet href="#outa">outa</a> i sum))))
</pre>

<p>
This is the <a href="#adjustable-square-wave">adjustable-square-wave</a> generator in generators.scm.
That file also defines <a href="#adjustable-triangle-wave">adjustable-triangle-wave</a> and
<a href="#adjustable-sawtooth-wave">adjustable-sawtooth-wave</a>.
All of these generators produce non-band-limited output; if the frequency is too high, you can get foldover.
A more reasonable square-wave can be generated via
<code>(tanh (* B (sin theta)))</code>, where "B" (a float) sets how squared-off it is:
</p>

<!-- the maxima experiments are in maxima.clm -->

<table>
<tr>
<td class="br">B: 1.0</td>
<td class="br">B: 3.0</td>
<td class="br">B: 100.0</td>
</tr>
<tr>
<td class="br">
<img src="pix/tanh1.png" alt="tanh 1">
</td>
<td class="br">
<img src="pix/tanh3.png" alt="tanh 1">
</td>
<td class="br">
<img src="pix/tanh100.png" alt="tanh 1">
</td>
</tr></table>

<!-- LATEX: sceq11
 \tanh(x) = x-\frac{x^{3}}{3}+\frac{2x^{5}}{15}-\frac{17x^{7}}{315}+\frac{62x^{9}}{2835}-\frac{1382x^{11}}{155925}\cdots 

long form:

\tanh(x) = x-\frac{x^{3}}{3}+\frac{2x^{5}}{15}-\frac{17x^{7}}{315}+\frac{62x^{9}}{2835}-\frac{1382x^{11}}{155925}+\frac{21844x^{13}}{6081075}-\frac{929569x^{15}}{638512875}\cdots

\tanh(x) = x-\frac{x^{3}}{3}+\frac{2x^{5}}{15}-\frac{17x^{7}}{315}+\frac{62x^{9}}{2835}-\frac{1382x^{11}}{155925}+\frac{21844x^{13}}{6081075}-\frac{929569x^{15}}{638512875}+\frac{6404582x^{17}}{10854718875}-\frac{443861162x^{19}}{1856156927625}\cdots

-->
<!-- LATEX: sceq12
\tanh(\sin(x)) = \frac{140069}{172800} \sin(x) + \frac{13319}{241920} \sin(3x) + \frac{1973}{483840} \sin(5x) + \frac{799}{1451520} \sin(7x) - \frac{71}{7257600} \sin(9x) + \frac{691}{79833600} \sin(11x) + \cdots 
-->

<!-- LATEX: tanhsum.png
& \tanh(B \sin(x)) = \frac{\sinh(B \sin(x))}{\cosh(B \sin(x))} = \frac{2 \sum_{k=0}^{\infty} (-1)^{k} I_{2k+1}(B) \sin(2k+1)x}{\cosh(B \sin(x))}

second try:
& \tanh(B \sin(x)) = \frac{-i \sin(iB \sin(x))}{\cos(iB \sin(x))} = \frac{2 \sum_{k=0}^{\infty} (-1)^{k} I_{2k+1}(B) \sin(2k+1)x}{\cos(iB \sin(x))} = \frac{e^{2B\sin(x)} - 1}{e^{2B\sin(x)}+1}

third try:
\tanh(B \sin(x)) = \frac{-i \sin(iB \sin(x))}{\cos(iB \sin(x))} = \frac{2 \sum_{k=0}^{\infty} (-1)^{k} I_{2k+1}(B) \sin(2k+1)x}{\cos(iB \sin(x))} = \frac{e^{2B\sin(x)} - 1}{e^{2B\sin(x)}+1}

fourth try (break it in 2!!):
\tanh(B \sin(x)) = \frac{-i \sin(iB \sin(x))}{\cos(iB \sin(x))}
= \frac{2 \sum_{k=0}^{\infty} (-1)^{k} I_{2k+1}(B) \sin(2k+1)x}{\cos(iB \sin(x))} = \frac{e^{2B\sin(x)} - 1}{e^{2B\sin(x)}+1}

fifth try: do it as one, and set the "MediaBox" line in the pdf file by hand!!
\tanh(B \sin(x)) = \frac{-i \sin(iB \sin(x))}{\cos(iB \sin(x))} = \frac{2 \sum_{k=0}^{\infty} (-1)^{k} I_{2k+1}(B) \sin(2k+1)x}{\cos(iB \sin(x))} = \frac{e^{2B\sin(x)} - 1}{e^{2B\sin(x)}+1}
-->


<p>
The spectrum of tanh(sin) can be obtained by expanding tanh as a power series:
</p>

<img class="indented" src="pix/sceq11.png" alt="tanh power series">

<p>
plugging in "sin" for "x", expanding the sine powers, and collecting terms (very tedious &mdash; 
use maxima!):
</p>

<img class="indented" src="pix/sceq12.png" alt="tanh sin power series">

<p>
which is promising since a square wave is made up of odd harmonics with amplitude 1/n.
As the "B" in tanh(B sin(x)) increases above pi/2, this series doesn't apply.
</p>

<img class="indented" src="pix/tanhsum.png" alt="more tanh">

<p>but I haven't found a completion of this expansion that isn't ugly when B &gt; pi/2. 
In any case, we can check the
formula for tanh, and see that the e^-x term will vanish (in the positive x case), giving 1.0.
So we do get a square wave, but it's not band limited.  If a complex signal replaces the sin(x),
we get "intermodulation products" (sum and difference tones); this use of tanh as a soft clipper
goes way back &mdash; I don't know who invented it.
</p>

<p>If you try to make a square wave by adding harmonics at amplitude 1/n,
you run into "Gibb's phenomenon": although the sum
converges on a square wave, it does so "pointwise" &mdash; each point converges to the square wave,
but the sum always has an overshoot.  To get something that looks square, we need to round-off the
corners. 
Bill Gosper shows one mathematical
way to do this (<a href="http://www.tweedledum.com/rwg/gibbs.html">gibbs.html</a>).
We could also use <a href="sndscm.html#withmixedsound">with-mixed-sound</a> and the Mixes dialog:
</p>

<pre class="indented">
(definstrument (sine-wave start dur freq amp)
  (let* ((beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> start))
	 (end (+ beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
	 (osc (<a class=quiet href="#make-oscil">make-oscil</a> freq)))
   (do ((i beg (+ i 1))) 
       ((= i end))
     (<a class=quiet href="#outa">outa</a> i (* amp (<a class=quiet href="#oscil">oscil</a> osc))))))

(<em class=red>with-mixed-sound</em> ()
  (sine-wave 0 1 10.0 1.0)
  (sine-wave 0 1 30.0 .333)
  (sine-wave 0 1 50.0 .2)
  (sine-wave 0 1 70.0 .143))
</pre>

<p>
Now we can play with the
individual sinewave amplitudes in the Mixes dialog, seeing "in realtime" what
effect an amplitude has on the waveform.  In the graph below, we've taken the original set of four sines
and chosen amplitudes 1.16, .87, .46, .14 (these are multipliers on the original 1/n amps).
The first graph is the original waveform, the last is the result of the
amplitude changes, and the middle one shows 100 sines (it is the usual demo that
the Gibbs overshoot is not reduced by adding lots more components).
The peak amplitude should be pi/4, but the Gibbs phenomenon adds .14.
</p>

<img class="indented" src="pix/smoothsq.png" alt="reduce Gibbs">

<!--
(definstrument (sine-wave start dur freq amp)
  (let* ((beg (seconds->samples start))
	 (end (+ beg (seconds->samples dur)))
	 (osc (make-oscil freq)))
       (do ((i beg (+ i 1))) 
	   ((= i end))
	 (outa i (* amp (oscil osc))))))

(with-sound ("4-sines.snd")
  (sine-wave 0 1 10.0 1.0)
  (sine-wave 0 1 30.0 .333)
  (sine-wave 0 1 50.0 .2)
  (sine-wave 0 1 70.0 .143))

(with-sound ("100-sines.snd")
  (do ((i 1 (+ i 2)))
      ((> i 200))
    (sine-wave 0 1 (* i 10.0) (/ 1.0 i))))

(with-mixed-sound (:output "4-sines-mixed.snd")
  (sine-wave 0 1 10.0 1.0)
  (sine-wave 0 1 30.0 .333)
  (sine-wave 0 1 50.0 .2)
  (sine-wave 0 1 70.0 .143))
-->

<p>But goofing with individual amplitudes quickly becomes tiresome.  This "realtime" business
depends on luck; if we have some idea of what we're doing, we don't have to get lucky.
Since 
tanh(B sin(x)) produces a nice square wave, 
we can truncate its spectrum at the desired number of harmonics:
</p>

<pre class="indented">
(define square-wave-&gt;coeffs
  (let ((previous-results (make-vector 128 #f)))
    (lambda* (n B)
      (or (and (&lt; n 128)
	       (not B)
	       (previous-results n))
	  (let* ((coeffs (make-float-vector (* 2 n)))
		 (size (expt 2 12))
		 (rl (make-float-vector size)))
            (do ((incr (/ (* 2 pi) size))
                 (index (or B (max 1 (floor (/ n 2)))))
                 (i 0 (+ i 1))
		 (x 0.0 (+ x incr)))
	        ((= i size))
	      (set! (rl i) (<em class=red>tanh</em> (* index (<em class=red>sin</em> x))))) ; make our desired square wave
 	    (<a class=quiet href="#spectrum">spectrum</a> rl (make-float-vector size) #f 2)  ; get its spectrum
	    (do ((i 0 (+ i 1))
		 (j 0 (+ j 2)))
		((= i n))
	      (set! (coeffs j) (+ j 1))
	      (set! (coeffs (+ j 1)) (/ (* 2 (rl (+ j 1))) size)))
	    (if (and (&lt; n 128)                          ; save this set so we don't have to compute it again
		     (not B))
		(set! (previous-results n) coeffs))
	    coeffs)))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (let* ((samps (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> 1.0))
	 (wave (<a class=quiet href="#make-polywave">make-polywave</a> 100.0 
			      :partials (<em class=red>square-wave-&gt;coeffs</em> 16)
			      :type mus-chebyshev-second-kind)))
   (do ((i 0 (+ i 1)))
       ((= i samps))
     (<a class=quiet href="#outa">outa</a> i (* 0.5 (<a class=quiet href="#polywave">polywave</a> wave))))))
</pre>

<table class="method"><tr><td>
<img src="pix/tanhexs.png" alt="tanh">
</td></tr></table>


<p>See also <a href="#tanhsin">tanhsin</a> in generators.scm.
Another square-wave choice is <a href="#eoddcos">eoddcos</a> in <a href="#othergenerators">generators.scm</a>, 
based on atan; as its "r" parameter approaches 0.0, you get closer to a square wave.
Even more amusing is this algorithm (related to tanh(sin)):
</p>

<img class="indented" src="pix/sceq13.png" alt="square">

<!-- CMJ 37 4 sept 2006 p326 -->
<!-- LATEX: \frac{(c+1)^{\cos t}-(c-1)^{\cos t}}{(c+1)^{\cos t}+(c-1)^{\cos t}} -->

<pre class="indented">
(define (cossq c theta)   ; as c -&gt; 1.0+, more of a square wave (try 1.00001)
  (let* ((cs (cos theta)) ; (+ theta pi) if matching sin case (or (- ...))
	 (cm1c (expt (- c 1.0) cs))
	 (cp1c (expt (+ c 1.0) cs)))
    (/ (- cp1c cm1c)
       (+ cp1c cm1c))))  ; from "From Squares to Circles..." Lasters and Sharpe, Math Spectrum 38:2

(define (sinsq c theta) (cossq c (- theta (* 0.5 pi))))
(define (sqsq c theta) (sinsq c (- (sinsq c theta)))) ; a sharper square wave

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (let ((angle 0.0))
    (do ((i 0 (+ i 1))
	 (angle 0.0 (+ angle 0.02)))
	((= i 44100))
      (outa i (* 0.5 (+ 1.0 (sqsq 1.001 angle)))))))
</pre>

<p>And in the slightly batty category is this method which uses only nested sines:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (let ((angle 0.0) (z 1.18)
        (incr (<a class=quiet href="#hztoradians">hz-&gt;radians</a> 100.0)))
    (do ((i 0 (+ i 1)))
        ((= i 20000))
      (let ((result (* z (sin angle))))
        (do ((k 0 (+ k 1)))
            ((= k 100))  ; the limit here sets how square it is, and also the overall amplitude
          (set! result (* z (sin result))))
        (set! angle (+ angle incr))
        (<a class=quiet href="#outa">outa</a> i result)))))
</pre>


<p>The continuously variable square-wave, tanh(B sin), can be differentiated to get a variable pulse-train,
or integrated to get a variable triangle-wave.
The derivative is B * cos(x) / (cosh^2(B * sin(x))):
</p>

<pre class="indented">
(with-sound ()
  (let ((Benv (make-env '(0 .1 .1 1 .7 2 2 5) :end 10000))
        (osc (make-oscil 100)))	 
    (do ((i 0 (+ i 1)))
	((= i 10000))
      (let* ((B (env Benv))
	     (num (cos (mus-phase osc)))
	     (den (cosh (* B (oscil osc)))))
	(outa i (/ num den den))))))
</pre>

<img class="indented" src="pix/tanhsinderiv.png" alt="tanh(sin) as pulse train">


<p>
Similar, but simpler is B*cos(x)/(e^(B*cos(x)) - 1):
</p>

<pre class="indented">
(with-sound ()
  (let ((gen (make-oscil 40.0))
        (Benv (make-env '(0 .75 1 1.5 2 20) :end 10000)))
   (do ((i 0 (+ i 1)))
       ((= i 10000))
     (let* ((B (env Benv))
            (arg (* B pi (+ 1.0 (oscil gen)))))
       (outa i (/ arg (- (exp arg) 1)))))))
</pre>

<img class="indented" src="pix/xex.png" alt="another pulse train">


<p>
When we integrate tanh(B sin), the peak amp depends
on both the frequency and the "B" factor (which sets how close we get to a triangle wave):
</p>

<pre class="indented">
(with-sound ()
  (let ((gen (make-oscil 30.0))
	(Benv (make-env '(0 .1 .25 1 2 3 3 10) 
                :end 20000))
	(scl (hz-&gt;radians 30.0))
	(sum 0.0))
    (do ((i 0 (+ i 1)))
	((= i 20000))
      (let* ((B (env Benv))
	     (val (/ (* scl (max 1.0 (log B)) 
	                (tanh (* B (oscil gen)))) 
                     B)))
	(outa i (- sum 1.0))
	(set! sum (+ sum val))))))
</pre>

<img class="indented" src="pix/tanhsininteg.png" alt="tanh(sin) as triangle-wave">


<!--
(set! *selected-graph-color* (make-color 1 1 1))
(set! *selected-data-color* (make-color 0 0 0))
(set! (x-axis-label 0 0 0) "derivative of tanh(B*sin), B from .1 to 5")
(set! (x-axis-label 0 0 0) "integration of tanh(B*sin), B from .1 to 10")
-->

<p>The amplitude scaling is obviously not right (if "B" &gt; 3, it works to use (* (/ scl 1.6) (tanh (* B (oscil gen))))
and (outa i (- sum .83)), but if "B" is following an envelope, the integration makes it hard to keep everything
centered and normalized).
For sawtooth output, see also <a href="#rksin">rksin</a>.
In these generators, the "fm" argument is useful mainly for various sci-fi sound effects:
</p>

<pre class="indented">
(define (tritri start dur freq amp index mcr)
  (let* ((beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> start))
         (end (+ beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
	 (carrier (<em class=red>make-triangle-wave</em> freq))
	 (modulator (<em class=red>make-triangle-wave</em> (* mcr freq))))
   (do ((i beg (+ i 1)))
       ((= i end))
     (<a class=quiet href="#outa">outa</a> i (* amp (<em class=red>triangle-wave</em> carrier 
                    (* index (<em class=red>triangle-wave</em> modulator))))))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:srate 44100) (tritri 0 1 1000.0 0.5 0.1 0.01)) ; sci-fi laser gun
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:srate 44100) (tritri 0 1 4000.0 0.7 0.1 0.01)) ; a sparrow?
</pre>

<p>On the other hand, animals.scm uses pulse-train's fm argument to track a frequency envelope,
triggering a new peep each time the pulse goes by.
I think just about every combination of oscil/triangle-wave/sawtooth-wave/square-wave has been
used.  Even triangle-wave(square-wave) can make funny noises.  See <a href="#ncosdoc">ncos</a>
for more dicussion about using these generators as FM modulators.
</p>





<!--  NCOS, NSIN  -->

<div class="innerheader" id="ncosdoc">ncos and nsin</div>

<pre class="indented">
<em class=def id="make-ncos">make-ncos</em> (frequency 0.0) (n 1)
<em class=def id="ncos">ncos</em> nc (fm 0.0)
<em class=def id="ncos?">ncos?</em> nc

<em class=def id="make-nsin">make-nsin</em> (frequency 0.0) (n 1)
<em class=def id="nsin">nsin</em> ns (fm 0.0)
<em class=def id="nsin?">nsin?</em> ns
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">ncos methods</td></tr>
<tr><td class="inner"><em class=gen>mus-frequency</em></td><td class="inner">frequency in Hz</td></tr>
<tr><td class="inner"><em class=gen>mus-phase</em></td><td class="inner">phase in radians</td></tr>
<tr><td class="inner"><em class=gen>mus-scaler</em></td><td class="inner">(/ 1.0 cosines)</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">n or cosines arg  used in make-&lt;gen&gt;</td></tr>
<tr><td class="inner"><em class=gen>mus-increment</em></td><td class="inner">frequency in radians per sample</td></tr>
</table>

<p>ncos produces a band-limited pulse train containing
"n" cosines.  I think this was originally viewed as a way to get a speech-oriented
pulse train that would then be passed through formant filters (see pulse-voice in examp.scm).  
Set "n" to srate/2 to get a pulse-train (a single non-zero sample).  These generators are based on the Dirichlet kernel:
</p>

<!-- LATEX: \sum_{k=0}^{n}\cos kx = \frac{1}{2}\Bigg(1+\frac{\sin(n+\frac{1}{2})x}{\sin \frac{x}{2}}\Bigg) -->
<img class="indented" src="pix/sceq2.png" alt="sum of cosines">
<!--
  cos(x) + cos(2x) + ... cos(nx) = 
    (sin((n + .5)x) / (2 * sin(x / 2))) - 1/2
-->
<pre>
</pre>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((gen (make-ncos 440.0 10)))
    (do ((i 0 (+ i 1)))
        ((= i 44100))
      (outa i (* 0.5 (ncos gen))))))
</pre>
</div>
</td>

</tr><tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  gen = make_ncos(440.0, 10);
  44100.times do |i| 
    outa(i, 0.5 * ncos(gen), $output) 
    end
  end.output
</pre>
</div>
</td>

</tr><tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  440.0 10 make-ncos { gen }
  44100 0 do
    i  gen 0 ncos  f2/ *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>


<p>There are many similar formulas:
see <a href="#ncos2">ncos2</a> and friends in <a href="#othergenerators">generators.scm</a>. "Trigonometric Delights" by Eli Maor has
a derivation of the nsin formula and a neat
geometric explanation.  For a derivation of the ncos formula, see "Fourier
Analysis" by Stein and Shakarchi, or (in the formula given below) multiply the left side (the cosines) by sin(x/2), use the trig
formula 2sin(a)cos(b) = sin(b+a)-sin(b-a), and notice that all the terms in the series
cancel except the last. 
</p>


<pre class="indented">
(define (simple-soc beg dur freq amp)
  (let* ((os (<em class=red>make-ncos</em> freq 10))
         (start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
         (end (+ start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur))))
   (do ((i start (+ i 1))) ((= i end))
     (outa i (* amp (<em class=red>ncos</em> os))))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () (simple-soc 0 1 100 1.0))
</pre>

<img class="indented" src="pix/cosines.png" alt="sum of cosines example">


<p>The <a href="#sinc-train">sinc-train</a> generator (in generators.scm) is very similar to ncos.
If you use ncos as the FM modulating signal, you may be surprised and disappointed.
As the modulating signal approaches a spike (as n increases), the bulk of the energy collapses back onto the carrier:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (for-each
    (lambda (arg)
      (let ((car1 (<a class=quiet href="#make-oscil">make-oscil</a> 1000))
            (mod1 (<em class=red>make-ncos</em> 100 (cadr arg)))
            (start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> (car arg)))
            (samps (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> 1.0))
            (ampf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 20 1 21 0) 
                    :duration 1.0 :scaler .8))
            (index (<a class=quiet href="#hztoradians">hz-&gt;radians</a> (* 100 3.0))))
        (do ((i start (+ i 1)))
            ((= i (+ start samps)))
            (<a class=quiet href="#outa">outa</a> i (* (<a class=quiet href="#env">env</a> ampf)
                       (<a class=quiet href="#oscil">oscil</a> car1 (* index
                         (<em class=red>ncos</em> mod1))))))))
    '((0.0 1) (2.0 2) (4.0 4) (6.0 8) (8.0 16) (10.0 32) (12.0 64) (14.0 128))))
</pre>

<img class="indented" src="pix/ncosfm.png" alt="ncos as FM">


<!--
ncosfm.png:
jet .001 59 invert
x 317 1.53
y 237 0.65
z 0 1.28
hop 4 % 0.14
blackman2 8192
-->

<!--
pulsefm.png:
(with-sound (:channels 2)
  (let* ((car1 (make-oscil 1000))
         (mod1 (make-pulse-train 100))
         (samps (seconds->samples 1.0))
         (ampf (make-env '(0 0 1 1 20 1 21 0) :duration 1.0 :scaler .8))
	 (index (hz->radians (* 100 3.0))))
    (do ((i 0 (+ i 1)))
	((= i samps))
      (let ((amp (env ampf))
	    (fm (* index (pulse-train mod1))))
	(outa i fm)
	(outb i (* amp (oscil car1 fm)))))))

(set! *selected-graph-color* (make-color 1 1 1))
(set! *selected-data-color* (make-color 0 0 0))
(set! (show-transform-peaks 0 0) #f)
cursor 10584
(set! *axis-label-font* *axis-numbers-font*)
(set! (x-axis-label 0 0 0) "pulse train modulating signal, FM index: 3.0")
(set! (x-axis-label 0 1 0) "modulated signal")
-->

<p>If you go all the way and use a pulse-train as the FM source, you get a
large component for the carrier, and all the others are very small.
</p>

<img class="indented" src="pix/pulsefm.png" alt="pulse-train as FM">

<!-- LATEX jprod.png \prod_{i=1}^{k}J_{k_{i}}(B_{i}) -->

<!-- j0j1.png:
(with-sound (:channels 2 :srate 10000)
  (do ((x 0.0 (+ x .0001))
       (i 0 (+ i 1)))
      ((= i 40000))
    (outa i (bes-j0 x))
    (outb i (bes-j1 x))))


(set! (x-axis-label 0 0) "J0 and J1")
(set! (x-axis-label 0 1) "")
(set! *axis-label-font*"9x15")
-->


<img class="indented" src="pix/j0j1.png" alt="j0 and j1">

<pre class="indented">
(define (ncfm freq-we-want wc modfreq baseindex n)
  ;; get amplitude of "freq-we-want" given ncos as FM, 
  ;;   "wc" as carrier, "modfreq" as ncos freq,
  ;;   "baseindex" as FM-index of first harmonic, 
  ;;   "n" as number of harmonics
  (do ((harms ())
       (amps ())
       (i 1 (+ i 1)))
      ((&gt; i n)
       (<a class=quiet href="sndscm.html#fmparallelcomponent">fm-parallel-component</a> freq-we-want wc 
          (reverse harms) (reverse amps) () () #f))
    (set! harms (cons (* i modfreq) harms))
    (set! amps (cons (/ baseindex i n) amps))))
</pre>

<table class="method">
<tr><td colspan=3 class="methodtitle">4 components: (ncfm x 1000 100 3.0 4)</td></tr>
<tr><td class="br">x=1000</td><td class="br"> 0.81</td><td class="br"> 0.81 from J0(3/(4*k)) '(0 0 0 0)</td></tr>
<tr><td class="br">x=900</td><td class="br">-0.44</td><td class="br">-0.32 from J1(3/4)*J0s  '(-1 0 0 0)</td></tr>
<tr><td class="br">x=800</td><td class="br">-0.14</td><td class="br">-0.16 from J1(3/8)*J0s  '(0 -1 0 0)</td></tr>
<tr><td class="br">x=700</td><td class="br">-0.06</td><td class="br">-0.10 from J1(3/12)*J0s '(0 0 -1 0)</td></tr>
</table>

<pre>
</pre>

<table class="method">
<tr><td colspan=3 class="methodtitle">24 components: (ncfm x 1000 100 3.0 24)</td></tr>
<tr><td class="br">x=1000</td><td class="br">0.99</td><td class="br"> 0.99 from J0(3/(24*k)) '(0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0)</td></tr>
<tr><td class="br">x=900</td><td class="br">-0.06</td><td class="br">-0.06 from J1(3/24)*J0s '(-1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0)</td></tr>
<tr><td class="br">x=800</td><td class="br">-0.03</td><td class="br">-0.03 from J1(3/48)*J0s '(0 -1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0)</td></tr>
<tr><td class="br">x=700</td><td class="br">-0.02</td><td class="br">-0.02 from J1(3/96)*J0s '(0 0 -1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0)</td></tr>
</table>


<p>You can multiply the index by n to counteract the effect of the n modulators
(in the n=128 case mentioned above, the index becomes 384!).
I find it surprising how smooth the spectral evolution is in this context.
Here we sweep the index from 0 to 48 using n=16:
</p>

<table class="pb">
<tr><td>
<img src="pix/ncossweep.png" alt="ncos">
</td></tr>
<tr><td class="center">ncos (n=16) as FM, index from 0 to 48</td></tr>
</table>


<!--
(with-sound (:statistics #t)
  (let* ((dur 10.0)
	 (samps (seconds->samples dur))
	 (car1 (make-oscil 1000))
	 (mod1 (make-sum-of-cosines 16 100))
	 (ampf (make-env '(0 0 1 1 20 1 21 0) :duration dur :scaler .8))
	 (index (hz->radians (* 100 16 3.0)))
	 (indf (make-env '(0 0 1 1) :scaler index :duration dur)))
    (do ((i 0 (+ i 1)))
	((= i samps))
      (outa i (* (env ampf)
		 (oscil car1 (* (env indf)
				(sum-of-cosines mod1))))))))

4096 blackman2 100(dark) 0 cutoff invert jet
319 1.5
289 0.71
0 1.0
4 0.25
-->

<p>But if our second analysis is correct, there's nothing special about the spike waveform that ncos produces.
We only need a lot of components of decreasing effective FM index.  If we randomize the initial
phases of the n harmonically related equal amplitude sinusoids, we can minimize the peak amplitude (to reduce the
spike), 
getting waveforms and results like these:
</p>

<table class="pb">
<tr><td>
<img src="pix/nsinfm.png" alt="ncos case but random phases">
</td></tr>
<tr><td class="center">FM of sum of n sinusoids</td></tr>
</table>


<table class="pb">
<tr><td>
<img src="pix/randomsins.png" alt="ncos case but random phases">
</td></tr>
<tr><td class="center">sum of n sinusoids minimizing resemblance to pulse-train</td></tr>
</table>


<!-- same setting as above

(defgenerator (ngencos 
	       :make-wrapper (lambda (g)
			       (let ((n (g 'n))
				     (frq (g 'frequency))
				     (phases (g 'phases)))
				 (set! (g 'arr) (make-vector n 0.0))
				 (do ((i 0 (+ i 1)))
				     ((= i n))
				   (if (float-vector? phases)
				       (set! ((g 'arr) i) (make-oscil (* frq (+ i 1)) (phases i)))
				       (set! ((g 'arr) i) (make-oscil (* frq (+ i 1)) (random (* 2 pi)))))))
			       g))
  frequency (n 1) (phases #f) (arr #f) fm)


(define* (ngencos gen (fm 0.0)) ; polyoid now, I think
  (set! (gen 'fm) fm)
  (with-let gen	 
    (let ((sum 0.0))
      (do ((i 0 (+ i 1)))
	  ((= i n))
        (set! sum (+ sum (oscil (arr i) (* (+ i 1) fm)))))
      (/ sum n))))

(with-sound (:channels 1 :clipped #f)
  (for-each
    (lambda (arg)
      (let ((car1 (make-oscil 1000))
	    (norm (/ 1.0 (caddr arg)))
	    (mod1 (make-ngencos 100 (cadr arg) (cadddr arg)))
	    (start (seconds->samples (car arg)))
	    (samps (seconds->samples 1.0))
	    (ampf (make-env '(0 0 1 1 20 1 21 0) 
	            :duration 1.0 :scaler .8))
	    (index (hz->radians (* 100 3.0)))
	    (mx 0.0))
	(do ((i start (+ i 1)))
	    ((= i (+ start samps)))
	  (let ((md (ngencos mod1)))
	    (outa i (* (env ampf)
                       (oscil car1 (* index norm md))))
	    (set! mx (max mx (abs md)))
	    ))
	(snd-display ";~A ~A ~A" (cadr arg) (caddr arg) mx)))
    (list
     (list 0.0 1    1.0    (float-vector 0))
     (list 2.0 2    0.881 (float-vector 0 0))
     (list 4.0 4    0.5184 (float-vector 1.295 0.248 0.304 2.785))
     (list 6.0 8    0.393  (float-vector 4.515 1.780 4.259 1.771 1.166 0.254 1.419 2.735))
     (list 8.0 16   0.302  (float-vector 0.432 2.086 2.763 2.344 2.811 3.409 1.836 6.173 3.770 2.339 6.158 1.530 6.132 3.006 4.967 0.859))
     (list 10.0 32  0.266  (float-vector 6.208 4.197 3.109 1.718 5.050 1.317 4.334 3.778 4.936 0.069 3.025 2.115 5.060 1.286 3.499 5.191 1.822 5.985 4.384 1.394 3.453 2.579 3.031 3.255 3.834 2.621 1.390 0.717 0.409 3.370 6.042 6.052))
     (list 12.0 64  0.2124 (float-vector 4.913 5.507 5.262 1.926 4.819 3.794 0.355 1.178 4.959 1.012 3.433 2.855 2.191 4.792 3.740 1.865 5.196 1.078 4.139 5.518 3.053 3.958 3.131 6.260 2.157 4.279 2.352 4.314 1.102 5.967 3.551 2.439 5.456 4.833 5.213 3.523 3.263 2.810 0.433 0.639 2.554 3.469 2.682 4.765 0.125 3.824 1.137 6.166 0.019 2.240 4.406 4.734 5.451 6.230 4.943 4.160 3.577 5.086 2.444 0.900 1.952 2.234 4.794 3.424))
     (list 14.0 128 0.16121 (float-vector 1.531 4.987 1.847 0.632 6.101 4.309 0.517 1.910 4.921 4.949 6.040 5.611 2.831 5.338 0.891 5.388 0.599 2.677 6.248 5.592 1.977 1.794 3.572 2.638 1.903 3.083 2.412 6.125 3.799 5.619 5.949 1.241 3.044 5.395 5.865 4.846 4.899 2.267 4.537 3.979 1.783 3.826 1.325 5.278 5.799 4.977 2.066 3.029 1.036 4.606 1.691 6.079 4.957 6.138 2.603 1.111 1.335 1.765 5.767 2.730 0.702 1.122 1.628 1.848 0.712 2.338 5.099 6.249 2.009 3.379 1.653 4.831 2.245 1.831 1.113 5.462 5.533 2.944 4.376 4.734 3.285 4.361 1.015 2.100 5.022 3.269 0.796 0.317 5.244 2.613 4.609 3.415 4.454 0.228 2.025 0.216 1.785 3.599 3.207 5.019 3.591 5.138 4.333 3.005 6.208 5.296 0.763 3.741 3.446 3.962 0.204 1.715 4.054 2.402 1.455 1.842 4.637 4.427 0.536 2.700 4.289 3.066 0.574 6.106 1.472 5.793 4.294 2.287)))))
-->


<div class="inset">
<p>Compare the sound of the n=64 and n=128 cases using ncos and random phases: they sound very different
despite having the same spectrum.  We confront the burning question: given n equal amplitude
harmonically related sinusoids, what is the minimum peak amplitude? 
For my current best results, see <a href="sndscm.html#peakphasesdoc">peak-phases</a>.
</p>
</div>

<p>
If you use ncos (or nsin) as both the carrier and modulator, you get a very similar effect.  As n increases,
the ncos(wc + ncos(wm)) output gradually approaches the unmodulated ncos output &mdash; the crunch happens on each carrier component,
but most strongly on the earlier ones (the "effective index" is less on those components, as mentioned
under <a href="#polywave">polywave</a>).  
And (for some reason this makes me smile), polywave modulated by ncos behaves the same way:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (let ((modulator (<em class=red>make-ncos</em> 100 :n 128))
        (carrier (<em class=red>make-polywave</em> 1000 (list 1 .5 3 .25 6 .25))))
    (do ((i 0 (+ i 1))) 
        ((= i 20000))
      (<a class=quiet href="#outa">outa</a> i (* .5 (<em class=red>polywave</em> carrier 
                      (* (<a class=quiet href="#hztoradians">hz-&gt;radians</a> (* 3 100)) 
                         (<em class=red>ncos</em> modulator 0.0))))))))
</pre>

<p>So, a pulse-train modulated by a pulse-train is a pulse-train.
Are there any other cases where gen(wc + gen(wm)) = gen(wc)?  My first thought was rand, but that has a hidden
surprise: the modulation obscures the underlying square-wave!
</p>

<img class="indented" src="pix/randfm.png" alt="rand(rand) spectrum">

<!-- randfm.png:

(with-sound (:channels 3)
  (let* ((car1 (make-rand 1000))
         (car2 (make-rand 1000))
         (mod1 (make-rand 100))
	 (samps (seconds->samples 1.0))
	 (ampf (make-env '(0 0 1 1 20 1 21 0) :duration 1.0 :scaler .8))
	 (index (hz->radians (* 100 3.0))))
    (do ((i 0 (+ i 1)))
	((= i samps))
      (let ((amp (env ampf))
	    (fm (* index (rand mod1))))
	(outa i fm)
	(outb i (* amp (rand car2)))
	(outc i (* amp (rand car1 fm)))))))

(set! *selected-graph-color* (make-color 1 1 1))
(set! *selected-data-color* (make-color 0 0 0))
(set! (x-axis-label 0 0 1) "100Hz rand modulating signal spectrum")
(set! (x-axis-label 0 1 1) "1000Hz rand, no modulation")
(set! (x-axis-label 0 2 1) "1000Hz rand, 100Hz modulation (from chan 0), index: 3")
-->

<!--
compare ncos as FM and direct sum of cos:

(with-sound (:channels 2)
  (for-each
    (lambda (arg)
      (let* ((beg (car arg))
	     (n (cadr arg))
	     (car1 (make-oscil 1000))
	     (mod1 (make-sum-of-cosines n 100 (random pi)))
	     (start (seconds->samples beg))
	     (dur 1.0)
	     (samps (seconds->samples dur))
	     (stop (+ start samps))
	     (ampf (make-env '(0 0 1 1 20 1 21 0) :duration dur :scaler .8))
	     (index (hz->radians (* 100 3.0)))
	     (car2 (make-oscil 1000))
	     (mods (make-vector n)))
	(do ((i 0 (+ i 1)))
	    ((= i n))
	  (set! (mods i) (make-oscil (* (+ i 1) 100) (* 0.5 pi))))
	(do ((i start (+ i 1)))
	    ((= i stop))
	  (let ((amp (env ampf)))
	    (outa i (* amp (oscil car1 (* index (sum-of-cosines mod1)))))
	    (let ((sum 0.0))
	      (do ((k 0 (+ k 1)))
		  ((= k n))
		(set! sum (+ sum (oscil (mods k)))))
	      (outb i (* amp (oscil car2 (* (/ index n) sum)))))))))
    (list
     (list 0.0 1)
     (list 2.0 2)
     (list 4.0 4)
     (list 6.0 8)
     (list 8.0 16)
     (list 10.0 32)
     (list 12.0 64)
     (list 14.0 128))))
-->


<p>What FM input (to oscil, for a given index) would give the most dispersed output?  My first guess was square-wave, but looking at graphs,
I'd say rand gives it a good contest.
If you sweep ncos upwards in frequency, you'll eventually
get foldover; the generator produces its preset number of cosines no
matter what.  It is possible to vary the spectrum smoothly:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (let ((os (<em class=red>make-ncos</em> 100.0 4))
        (pow (<a class=quiet href="#make-env">make-env</a> '(0 1.0 1 30.0) :length 10000))) ; our "index" envelope in FM jargon
    (do ((i 0 (+ i 1)))
	((= i 10000))
      (let ((val (<em class=red>ncos</em> os)))
	(<a class=quiet href="#outa">outa</a> i (* (signum val) ; signum is in dsp.scm
		   (expt (abs val) (<a class=quiet href="#env">env</a> pow))))))))
</pre>

<p>This is not a very polite sound.  The same trick works on all the <a href="#ncos2">pulse-train</a> functions in generators.scm (or an oscil for that matter!), 
but perhaps a filter is a simpler approach.  There are a lot more of these "kernels" in <a href="#othergenerators">generators.scm</a>.
</p>

<table class="method">
<tr>
<td class="methodtitle">ncos2 (Fejer, n=10)</td>
<td class="methodtitle">npcos (Poussin, n=5)</td>
<td class="methodtitle">ncos4 (Jackson, n=10)</td>
</tr><tr>
<td class="br"><img src="pix/fejer.png" alt="fejer sum"></td>
<td class="br"><img src="pix/poussin.png" alt="poussin sum"></td>
<td class="br"><img src="pix/jackson.png" alt="jackson sum"></td>
</tr></table>




<p>nsin produces a sum of equal amplitude sines.  It is very similar (good and bad) to <a href="#ncos">ncos</a>.
For n greater than 10 or so, its peak amplitude occurs at approximately 3pi/4n, and is about .7245*n (that is, 8n*(sin^2(3pi/8))/3pi).
The nsin generator scales its output to be between -1 and 1 for any n.  We can use nxysin to try any initial-phase in a
sum of equal sinusoids.  The peak amp in this case varys sinusoidally from a sum of sines n * 0.7245 to a sum of cosines n * 1.0;
the peak amp is nsin-max(n) + abs(sin(initial-phase))*(1 - nsin-max(n)).  nsin is based on the conjugate Dirichlet kernel:
</p>

<!-- LATEX: \sum_{k=1}^{n}\sin kx = \frac{\sin\frac{n+1}{2}x \: \sin\frac{nx}{2}}{\sin\frac{x}{2}} -->

<img class="indented" src="pix/sceq1.png" alt="sum of sines">
<pre>
</pre>
<img class="indented" src="pix/sos.png" alt="sum of sines graphs">
<pre>
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">nsin methods</td></tr>
<tr><td class="inner"><em class=gen>mus-frequency</em></td><td class="inner">frequency in Hz</td></tr>
<tr><td class="inner"><em class=gen>mus-phase</em></td><td class="inner">phase in radians</td></tr>
<tr><td class="inner"><em class=gen>mus-scaler</em></td><td class="inner">dependent on number of sines</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">n or sines arg used in make-&lt;gen&gt;</td></tr>
<tr><td class="inner"><em class=gen>mus-increment</em></td><td class="inner">frequency in radians per sample</td></tr>
</table>

<p>
As with all the paired cos/sin generators (waveshaping, generators.scm, etc), we can vary
the initial phase by taking advantage of the trig identity:
</p>

<img class="indented" src="pix/fmeq18.png" alt="sin split">

<p>that is,
</p>

<pre class="indented">
 (+ (* (ncos nc) (sin initial-phase))
    (* (nsin ns) (cos initial-phase)))
</pre>

<p>Or vary it via an envelope at run-time:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (let ((nc (<em class=red>make-ncos</em> 500.0 6))
	(ns (<em class=red>make-nsin</em> 500.0 6))
	(phase (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1) 
                  :length 1000 :scaler (/ pi 2))))
    (do ((i 0 (+ i 1)))
	((= i 1000)) 
      (let ((angle (<a class=quiet href="#env">env</a> phase)))
	(<a class=quiet href="#outa">outa</a> i (+ (* (<em class=red>ncos</em> nc) (sin angle))
		   (* (<em class=red>nsin</em> ns) (cos angle))))))))
</pre>

<img class="indented" src="pix/varyphase.png" alt="ncos+nsin example">


<p>Compared to ncos or nsin, polywave is probably always faster and more accurate, but less convenient to set up.
Both ncos and nsin could be implemented as polynomials in cos x, just as in polyshape; in fact, ncos is
almost the same as the Chebyshev polynomial of the fourth kind. 
See also the <a href="#nrxydoc">nrxycos</a> generator, 
and <a href="#othergenerators">generators.scm</a>.
</p>


<!-- LATEX:
sceq14:
\small
\begin{align*}
&\sum_{k=0}^{n}\sin(x+ky)=\frac{\sin\Big(x+\frac{n-1}{2}y\Big)\sin\frac{ny}{2}}{\sin\frac{y}{2}} \\
&\sum_{k=0}^{n}\cos(x+ky)=\frac{\cos\Big(x+\frac{n-1}{2}y\Big)\sin\frac{ny}{2}}{\sin\frac{y}{2}} \\
&\sum_{k=0}^{2n-1}(-1)^{k}\cos(x+ky)=\frac{\sin\Big(x+\frac{2n-1}{2}y\Big)\sin ny}{\cos\frac{y}{2}} \\
&\sum_{k=0}^{n-1}(-1)^{k}\sin(x+ky)=\frac{\sin\Big(x+\frac{n-1}{2}(y+\pi)\Big)\sin\frac{n(y+\pi)}{2}}{\cos\frac{y}{2}} \\
&\sum_{k=1}^{n}\sin(2k-1)x=\frac{\sin^{2}nx}{\sin x} \\
&\sum_{k=1}^{n}\cos(2k-1)x=\frac{1}{2}\frac{\sin 2nx}{\sin x} \\
&\sum_{k=1}^{n}(-1)^{k}\cos kx=-\frac{1}{2}+\frac{(-1)^{n}\cos(\frac{2n+1}{2}x)}{2\cos\frac{x}{2}} \\
&\sum_{k=1}^{n}(-1)^{k+1}\sin(2k-1)x = (-1)^{n+1}\frac{\sin 2nx}{2\cos x} \\
&\sum_{k=1}^{n-1}k\sin kx=\frac{\sin nx}{4 \sin^{2}\frac{x}{2}} - \frac{n \cos \frac{2n-1}{2}x}{2\sin\frac{x}{2}} \\
&\sum_{k=1}^{n-1}k\cos kx=\frac{n\sin\frac{2n-1}{2}x}{2\sin\frac{x}{2}} - \frac{1-\cos nx}{4\sin^{2}\frac{x}{2}} \\
&2^{1-n} \sum_{0}^{\lfloor n/2 \rfloor} \binom{n}{k} \cos (n-2k)\theta = \cos^{n}\theta \\

sceq15:
&\sum_{k=1}^{n-1}p^{k}\sin kx=\frac{p\sin x - p^{n}\sin nx + p^{n+1}\sin(n-1)x}{1-2p\cos x+p^{2}} \\
&\sum_{k=0}^{n-1}p^{k}\cos kx=\frac{1-p\cos x - p^{n}\cos nx + p^{n+1}\cos(n-1)x}{1-2p\cos x + p^{2}} \\
&\sum_{k=1}^{\infty}p^{k}\sin kx=\frac{p\sin x}{1-2p\cos x + p^{2}} \\
&\sum_{k=0}^{\infty}p^{k}\cos kx=\frac{1-p\cos x}{1-2p\cos x + p^{2}} \\
&\sum_{k=1}^{\infty}\frac{p^{k}\sin kx}{k} = \arctan \frac{p\sin x}{1-p\cos x} \\
&\sum_{k=1}^{\infty}\frac{p^{k}\cos kx}{k} = \ln \frac{1}{\sqrt{1-2p\cos x + p^{2}}} \\
&\sum_{k=1}^{\infty}\frac{p^{2k-1}\sin(2k-1)x}{2k-1} = \frac{1}{2}\arctan \frac{2p\sin x}{1-p^{2}} \\
&\sum_{k=1}^{\infty}\frac{p^{2k-1}\cos(2k-1)x}{2k-1} = \frac{1}{4}\ln \frac{1+2p\cos x + p^{2}}{1-2p\cos x + p^{2}} \\
&\sum_{k=1}^{\infty}e^{-kt}\sin kx = \frac{1}{2}\frac{\sin x}{\cosh t - \cos x} \\
&1 + 2\sum_{k=1}^{\infty}e^{-kt}\cos kx = \frac{\sinh t}{\cosh t - \cos x} \\
&\sum_{k=0}^{\infty} \frac{(2n+2k)(2n+k-1)!}{k!}J_{2n+2k}(2z \sin \theta) = (z \sin \theta)^{2n} \\
&J_{0}^{2}\Big(\frac{z}{2}\Big)+2\sum_{k=1}^{\infty} J_{k}^{2}\Big(\frac{z}{2}\Big)\cos2k\theta = J_{0}(z \sin \theta) \\
\end{align*}


old in second col (replaced by JO cases):
&\sum_{k=1}^{\infty}\frac{p^{k}\sin kx}{k!} = e^{p\cos x}\sin(p\sin x) \\
&\sum_{k=0}^{\infty}\frac{p^{k}\cos kx}{k!} = e^{p\cos x}\cos(p\sin x) \\
rk!sin and cos

original last of first col:
&\sum_{k=1}^{\infty} \frac{\sin^{2k} x}{k} = -2 \ln \cos x & (x^{2} < \frac{pi^{2}}{4}) \\


sceq20:
\begin{align*}
&\sum_{k=0}^{\infty} p^{k} \cos(x + ky) = \frac{\cos x - p \cos(x - y)}{1 - 2p\cos y + p^{2}} \\
&\sum_{k=0}^{\infty} p^{k} \sin(x + ky) = \frac{\sin x - p \sin(x - y)}{1 - 2p\cos y + p^{2}} \\
&\sum_{k=1}^{\infty} \frac{\sin kx}{2^{k-1}} = \frac{4\sin x}{5 - 4\cos x} \\
&\sum_{k=1}^{\infty} \frac{(-1)^{k} e^{(2k-1)a} \cos(2k-1)x}{2k-1} = \frac{1}{2}\arctan \bigg(\frac{\cos x}{\sinh a}\bigg) \\
&\sum_{k=1}^{\infty} \frac{\sin nx}{n(n^{2}-4)} = -\frac{\pi}{8}\sin^{2}x \\
\end{align*}


sceq21:
\begin{align*}
&\sum_{k=0}^{\infty} \frac{a^{k}}{k!} \cos(x + ky) = e^{a \cos y} \cos (x + a \sin y) \\
&\sum_{k=0}^{\infty} \frac{a^{k}}{k!} \sin(x + ky) = e^{a \cos y} \sin (x + a \sin y) \\
&\sum_{k=0}^{\infty} \frac{a^{2k}\cos 2kx}{(2k)!} = \cosh(a \cos x) \cos (a \sin x) & (a^{2}<1) \\
&\sum_{k=1}^{\infty} \frac{a^{2k}\sin 2kx}{(2k)!} = \sinh(a \cos x) \sin (a \sin x) & (a^{2}<1) \\
&\frac{1}{a} + 2a \sum_{k=1}^{\infty} \frac{\cos kx}{a^{2}+k^{2}} = \pi \frac{\cosh a(\pi-x)}{\sinh a\pi} & (0 \leq x \leq 2\pi)\\
\end{align*}

sceq23 (old):
& \ln (1 - 2xt + t^{2})^{-1} = 2 \sum_{n=1}^{\infty} \frac{t^{n}}{n} T_{n}(x) \\
& (1 - 2xt + t^{2})^{-1} = \frac{1}{\sqrt{1 - x^{2}}} \sum_{n=0}^{\infty} t^{n} U_{n+1}(x) \\
& e^{z cos x}J_{\nu-\frac{1}{2}}(z \sin x) = \frac{\Gamma(\nu)}{\Gamma(\frac{1}{2})}(2 \sin x)^{\nu-\frac{1}{2}} \sum_{k=0}^{\infty}\frac{z^{\nu+k-\frac{1}{2}}}{\Gamma(2\nu + k)} \mathrm{C}^{\nu}_{k}(\cos x)

sceq25 old:
\sum_{n=0}^{\infty} r^{n} \sum_{k=0}^{\infty} \sin (k+1/2)\theta = \frac{(1+r)\sin(\theta / 2)}{(1-r)(1-2r\cos\theta + r^{2})}

sceq26 old:
\sum_{n=0}^{\infty} r^{n} \sum_{k=0}^{\infty} (n+1-k)\sin (k+1)\theta = \frac{\sin\theta}{(1-r)^{2}(1-2r\cos\theta + r^{2})}

sceq7: (p73)
&\sum_{k=1}^{\infty} \frac{\cos kx}{k} = -\ln \big(2 \sin \frac{x}{2}\big)  & (0\leq x \leq \pi) \\

sceq27: (p183)
1 + 2 &\sum_{n=1}^{\infty} \frac{(-a + \sqrt{a^{2} - b^{2}})^{n} \cos nx}{b^{n}} = \frac{\sqrt{a^{2} - b^{2}}}{a + b \cos x} & (b < a, a \neq 0) \\

sceq25:
&\sum_{k=1}^{\infty} k r^{k} \sin kx = \frac{r(1-r^{2})\sin x}{(1 - 2r\cos x + r^{2})^{2}}
Z 352

sceq26:
original: & \frac{8}{\pi} \sum_{k=1}^{\infty} \frac{\sin^{2}kx}{4k^{2}-1} = |\sin x|
& \frac{8}{\pi} \sum_{k=1}^{\infty} \frac{\sin^{2}kx}{4k^{2}-1} = | \sin x \, | = \frac{2}{\pi} - \frac{8}{\pi} \sum_{k=1}^{\infty} \frac{\cos 2kx}{4k^{2} - 1}

sceq31:
J_{0}(ka)J_{0}(kr) + 2 \sum_{m=1}^{\infty} J_{m}(kr)J_{m}(ka) \cos m\theta = J_{0}\Big(k \sqrt{r^{2}+a^{2}-2ar\cos \theta}\Big)

sceq32 old form (redundant):
1 + 2 \sum_{n=1}^{\infty} J_{n}(nz)\cos n(x-z\sin x) = \frac{1}{1-z\cos x}
sceq32 new form:
&2^{n} \Gamma(n) \sum_{m=0}^{\infty} (n+m)\frac{J_{n+m}(r)}{r^{n}} \frac{J_{n+m}(a)}{a^{n}} C_{m}^{n}(\cos \theta) = \frac{J_{n}\big(\sqrt{r^{2}+a^{2}-2ar\cos \theta}\big)}{\big(\sqrt{r^{2}+a^{2}-2ar\cos \theta}\big)^{n}} \\

sceq33:
\sum_{m=0}^{\infty}(m+\frac{1}{2})\frac{J_{m+\frac{1}{2}}(ka)}{\sqrt{a}} \frac{J_{m+\frac{1}{2}}(kr)}{\sqrt{r}} P_{m}(\cos \theta) = \frac{\sin\Big(k \sqrt{r^{2}+a^{2}-2ar\cos \theta}\Big)}{\pi \sqrt{r^{2}+a^{2}-2ar\cos \theta}}

Pn(cos x) is p776 A&S (P=Jacobi)

sceq34:
old form: \sum_{m=0}^{\infty} (n+m)\Big(\frac{J_{n+m}(z)}{z^{n}}\Big)^{2} C_{m}^{n}(\cos \theta) = \frac{J_{n}(2z \sin \frac{\theta}{2})}{2^{n}\Gamma(n)(2z\sin \frac{\theta}{2})}
\sum_{m=0}^{\infty} (n+m)\Big(\frac{J_{n+m}(z)}{z^{n}}\Big)^{2} \sum_{k=0}^{m} \frac{(n)_{k}(n)_{m-k}}{k!(m-k)!} \cos(m-2k)\theta = \frac{J_{n}(2z \sin \frac{\theta}{2})}{2^{n}\Gamma(n)(2z\sin \frac{\theta}{2})}


from Gray and Mathews, "A Treatise on Bessel Functions and Their Applications to Physics" p 28, 29, 92, 240
sceq36:
& J_{0}^{2}\Big(\frac{z}{2}\Big)+2\sum_{k=1}^{\infty} (-1)^{k} J_{k}^{2}\Big(\frac{z}{2}\Big)\cos2kx = J_{0}(z \cos x) \\
& 2\sum_{k=0}^{\infty} (-1)^{k} J_{k}\Big(\frac{z}{2}\Big)J_{k+1}\Big(\frac{z}{2}\Big)\cos (2k+1)x = J_{1}(z \cos x) \\

sceq37:
& Y_{0}(b)J_{0}(c) + 2 \sum_{m=1}^{\infty} Y_{m}(b)J_{m}(c) \cos m\theta = Y_{0}\Big(\sqrt{b^{2}+c^{2}-2bc\cos \theta}\Big) & (b > c)\\
& \sum_{n=0}^{\infty} \frac{r^{n}}{n!}P_{n}(\cos \theta) = e^{r \cos \theta}J_{0}(r \sin \theta) \\

from Abramowitz and Stegun, "Handbook of Mathematical Functions"
9.6.34 (p376)  (9.1.42 is the FM formula)
sceq39:
I_{0}(z) + 2 \sum_{k=1}^{\infty} I_{k}(z) \cos k\theta = e^{z \cos \theta}

sceq40: 27.8.6 (p1005)
&\sum_{n=1}^{\infty} \frac{\sin n\theta}{n^{3}} = \frac{\pi^{2}\theta}{6} - \frac{\pi \theta^{2}}{4} + \frac{\theta^{3}}{12} & (0 \leq \theta \leq 2\pi)


from Askey "Ramanujan and Hypergeometric Series" in Berndt and Rankin "Ramanujan: Essays and Surveys" p283 (the formula was found by Gauss):
   this is r2k!cos in generators.scm [sceq30.png]
&(1 - 2r \cos \theta + r^{2})^{-k} = \frac{{}_{2}F_{1}(k, k; 1; r^{2})}{2} + \sum_{n=1}^{\infty} \frac{(k)_{n}}{n!} r^{n} {}_{2}F_{1}(k, k+n; n+1; r^{2}) \cos n\theta


Montgomery and Vorhauer:
&\sum_{n=1}^{\infty} \frac{\sin \frac{k \pi}{n+1}}{\sin \frac{\pi}{n+1}} \cos k\theta = \frac{(\cos \frac{1}{2}(n+1)\theta)^{2}}{\cos \theta - \cos \frac{\pi}{n+1}}


;;; Bessel funcs as confluent hypergeometric series
&J_{n}(x) = \frac{(\frac{x}{2})^{n}}{\Gamma(n+1)} e^{-ix} \Phi(n+\frac{1}{2}, 2n+1; 2ix) \\
&I_{n}(x) = \frac{(\frac{x}{2})^{n}}{\Gamma(n+1)} e^{-x} \Phi(n+\frac{1}{2}, 2n+1; 2x) \\

from Klapper, Selected Papers on Frequency Modulation, p 156
&\sum_{n=-\infty}^{\infty} (-1)^{n} J_{2n}(x) J_{2n}(y(\omega + B \cos z)) = J_{0}( \sqrt{x^{2} + y^{2} (\omega + B\cos z)^{2}})

another kernel set: binomial coeffs G&R 1.320 etc, not different enough
-->


<table class="grayborder">
<tr><td colspan=2 class="methodtitle">various sums</td></tr>

<tr>
<td>
<img class="noborder" src="pix/sceq14.png" alt="many sums" usemap="#GR1">
<map name="GR1">
  <area shape=rect coords="0,0,300,60" href="#nxysin" alt="nxysin">
  <area shape=rect coords="0,61,300,100" href="#nxycos" alt="nxycos">
  <area shape=rect coords="0,101,300,150" href="#nxy1cos" alt="nxy1cos">
  <area shape=rect coords="0,151,300,200" href="#nxy1sin" alt="nxy1sin">
  <area shape=rect coords="0,201,300,240" href="#noddsin" alt="noddsin">
  <area shape=rect coords="0,241,300,280" href="#noddcos" alt="noddcos">
  <area shape=rect coords="0,361,300,410" href="#nkssb" alt="nkssb">
  <area shape=rect coords="0,411,300,450" href="#nkssb" alt="nkssb">
  <area shape=rect coords="0,450,300,485" href="#nchoosekcos" alt="nchoosekcos">
</map>
</td>
<td>
<img class="noborder" src="pix/sceq15.png" alt="many more sums" usemap="#GR2">
<map name="GR2">
  <area shape=rect coords="0,0,300,40" href="#nrsin" alt="nrsin">
  <area shape=rect coords="0,41,300,90" href="#nrcos" alt="nrcos">
  <area shape=rect coords="0,91,300,140" href="#rssb" alt="rssb">
  <area shape=rect coords="0,141,300,180" href="#rcos" alt="rcos">
  <area shape=rect coords="0,181,300,220" href="#rksin" alt="rksin">
  <area shape=rect coords="0,221,300,250" href="#rkcos" alt="rkcos">
  <area shape=rect coords="0,251,300,300" href="#rkoddssb" alt="rkoddssb">
  <area shape=rect coords="0,301,300,340" href="#rkoddssb" alt="rkoddssb">
  <area shape=rect coords="0,341,300,380" href="#erssb" alt="erssb">
  <area shape=rect coords="0,381,300,420" href="#ercos" alt="ercos">
  <area shape=rect coords="0,465,300,490" href="#j0evencos" alt="j0evencos">
</map>
</td>
</tr>

<tr><td colspan=2 class="sumtitle">Gradshteyn and Ryzhik, "Table of Integrals, Series, and Products", 1.341.., 1.352.., 1.447.., 1.461, 1.518, 8.516, 8.531</td></tr>

<tr><td class="hightop">
<img class="noborder" src="pix/sceq20.png" alt="more sums" usemap="#J1">
<map name="J1">
    <area shape=rect coords="0,0,300,30" href="#rxycos" alt="rxycos">
    <area shape=rect coords="0,31,300,60" href="#rxysin" alt="rxysin">
    <area shape=rect coords="0,61,300,100" href="#k2sin" alt="k2sin">
    <area shape=rect coords="0,101,300,140" href="#eoddcos" alt="eoddcos">
</map>
</td>
<td class="hightop"><img class="noborder" src="pix/sceq21.png" alt="more sums" usemap="#J2">
<map name="J2">
    <area shape=rect coords="0,0,300,30" href="#rxyk!cos" alt="rxyk!cos">
    <area shape=rect coords="0,31,300,60" href="#rxyk!cos" alt="rxyk!sin">
</map>
</td></tr>
<tr><td colspan=2 class="sumtitle">Jolley, "Summation of Series", 521 587 623 635 638 685 686 691 692 728</td></tr>

<tr><td class="hightop"><a class=invisible href="#izcos"><img src="pix/sceq39.png" alt="I(k) sum"></a></td>
<td class="hightop"><a class=invisible href="#k3sin"><img src="pix/sceq40.png" alt="n3 case"></a></td></tr>

<tr><td colspan=2 class="sumtitle">Abramowitz and Stegun, "Handbook of Mathematical Functions", 9.6.34, 27.8.6</td></tr>

<tr><td class="hightop"><a class=invisible href="#krksin"><img src="pix/sceq25.png" alt="more sums"></a></td>

<td class="hightop"><img src="pix/sceq26.png" alt="more sums"></td></tr>

<tr><td colspan=2 class="sumtitle">Zygmund, "Trigonometric Series" p34, 352</td></tr>

<tr><td class="hightop"><img src="pix/sceq7.png" alt="more sums"></td>
<td class="hightop"><a class=invisible href="#abcos"><img src="pix/sceq27.png" alt="more sums"></a></td></tr>


<tr><td colspan=2 class="sumtitle">Sansone, "Orthogonal Functions"</td></tr>

<tr><td class="hightop"><img class="noborder" src="pix/sceq36.png" alt="more sums" usemap="#GM1">
<map name="GM1">
    <area shape=rect coords="0,0,300,50" href="#j0j1cos" alt="j0j1cos">
    <area shape=rect coords="0,51,300,80" href="#j0j1cos" alt="j0j1cos">
</map>
</td>
<td class="hightop"><img class="noborder" src="pix/sceq37.png" alt="more sums" usemap="#GM2">
<map name="GM2">
    <area shape=rect coords="0,0,300,50" href="#jycos" alt="jycos">
</map>
</td></tr>

<tr><td colspan=2 class="sumtitle">Gray and Mathews, "A Treatise on Bessel Functions and Their Applications to Physics" p 28, 29, 92, 240</td></tr>

<tr>
<td class="hightop"><a class=invisible href="#jncos"><img src="pix/sceq32.png" alt="more sums"></a></td>
<td class="hightop"><a class=invisible href="#jjcos"><img src="pix/sceq31.png" alt="more sums"></a></td>
</tr><tr>
<td><a class=invisible href="#j2cos"><img src="pix/sceq34.png" alt="more sums"></a></td>
<td><a class=invisible href="#jpcos"><img src="pix/sceq33.png" alt="more sums"></a></td>
</tr><tr>

<td colspan=2 class="sumtitle">Watson, "A Treatise on the Theory of Bessel Functions": 4.82, 11.41, 17.31</td></tr>

<tr><td class="hightop"><a class=invisible href="#r2k!cos"><img src="pix/sceq30.png" alt="kosines"></a></td>
<td class="hightop">
<a class=invisible href="#n1cos"><img src="pix/sceq45.png" alt="linear cosines"></a>
</td>
</tr>
 
<tr><td class="sumtitle">Askey, "Ramanujan and Hypergeometric Series"</td>

<td class="sumtitle">Ramanujan, "On certain Arithmetical Functions"</td>
</tr>
</table>




<!-- LATEX
sceq38:
\sum_{k=-\infty}^{\infty} J_{k}(m\rho) Z_{\nu+k}(mr) e^{ik\phi} = e^{i \nu \psi}Z_{\nu}(mR)
-->

<!-- LATEX
sceq45.png
& 2n-1 + 4\sum_{k=1}^{n-1} (n-k)\cos k\theta + \cos n\theta = \cot^{2}\frac{\theta}{2}\  (1 - \cos n\theta) \\
-->

<p>
There are many formulas that produce exponentially decaying or bell-curve shaped spectra;
I think these all sound about the same, so I have included only a representative sample of them.
A couple of the formulas are special cases of the "Bessel function summation theorem", G&amp;R 8.530:
<img src="pix/sceq38.png" alt="summation formula">,
where Z stands for any of the various Bessel functions (J, Y, etc),
and R stands for the Poisson-like business (or is it Legendre?) in the square root.
Most of the formulas above are implemented as generators in <a href="#othergenerators">generators.scm</a>,
along with the single side-band cases, where possible.
Don't shy away from the sums to infinity just because you've heard shouting about "band-limited waveforms" &mdash; FM is an infinite sum:
</p>


<!-- LATEX:
\small
\begin{align*}
& \cos(B \sin x) = J_{0}(B) + 2 \sum_{k=1}^{\infty} J_{2k}(B) \cos 2kx \\
& \cos(B \cos x) = J_{0}(B) + 2 \sum_{k=1}^{\infty} (-1)^{k} J_{2k}(B) \cos 2kx \\
& \sin(B \sin x) = 2 \sum_{k=0}^{\infty} J_{2k+1}(B) \sin (2k+1)x \\
& \sin(B \cos x) = 2 \sum_{k=0}^{\infty} (-1)^{k} J_{2k+1}(B) \cos (2k+1)x \\
\end{align*}
-->


<img src="pix/fmeq49.png" alt="cos cos cases">

<img src="pix/fmeq50.png" alt="cos cos cases">

<br>
<div class="inset_inline">(Is cos(sin(x)) always greater than sin(cos(x))?)</div>







<!--  NRXYSIN and NRXYCOS  -->

<div class="innerheader" id="nrxydoc">nrxysin and nrxycos</div>

<pre class="indented">
<em class=def id="make-nrxysin">make-nrxysin</em> 
      (frequency 0.0) 
      (ratio 1.0)               ; ratio between frequency and the spacing between successive sidebands
      (n 1)                     ; number of sidebands
      (r .5)                    ; amplitude ratio between successive sidebands (-1.0 &lt; r &lt; 1.0)
<em class=def id="nrxysin">nrxysin</em> s (fm 0.0)
<em class=def id="nrxysin?">nrxysin?</em> s

<em class=def id="make-nrxycos">make-nrxycos</em> (frequency 0.0) (ratio 1.0) (n 1) (r .5)
<em class=def id="nrxycos">nrxycos</em> s (fm 0.0)
<em class=def id="nrxycos?">nrxycos?</em> s
</pre>
<br>

<table class="method">
<tr><td colspan=2 class="methodtitle">nrxysin methods</td></tr>
<tr><td class="inner"><em class=gen>mus-frequency</em></td><td class="inner">frequency in Hz</td></tr>
<tr><td class="inner"><em class=gen>mus-phase</em></td><td class="inner">phase in radians</td></tr>
<tr><td class="inner"><em class=gen>mus-scaler</em></td><td class="inner">"r" parameter; sideband scaler</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">"n" parameter</td></tr>
<tr><td class="inner"><em class=gen>mus-increment</em></td><td class="inner">frequency in radians per sample</td></tr>
<tr><td class="inner"><em class=gen>mus-offset</em></td><td class="inner">"ratio" parameter</td></tr>
</table>

<p>These three generators 
produce a kind of additive synthesis.
"n" is the number of sidebands (0 gives a sine wave), "r" is the amplitude
ratio between successive sidebands (don't set it to 1.0), and "ratio" is the ratio between the
carrier frequency and the spacing between successive sidebands.
A "ratio" of 2 gives odd-numbered harmonics for a (vaguely) clarinet-like sound.
A negative ratio puts the side-bands below the carrier.
A negative r is the same as shifting the initial phase by pi (instead of lining up
for the spike at multiples of 2*pi, the (-1)^n causes them to line up at (2k-1)*pi,
but the waveform is the same otherwise).
The basic idea is very similar to that used in the
<a href="#ncos">ncos</a> generator, but you have control of the
fall-off of the spectrum and the spacing of the partials.
Here are the underlying formulas:
</p>

<!-- sinesummation.png:
(with-sound (:clipped #f)
  (let ((gen (make-sine-summation 400.0 0.0 5 0.5)))
       (do ((i 0 (+ i 1)))
	   ((= i 30000))
	 (outa i (sine-summation gen 0.0)))))
-->

<!-- Jolley 475 is different [it runs 0 .. n-1 in our terminology, whereas Moorer's runs 0 .. n] -->

<!-- LATEX:
& \sum_{k=0}^{n} r^{k}\sin(x+ky) = \frac{\sin(x) - r\sin(x-y) - r^{n+1}\Big(\sin(x+(n+1)y) - r\sin(x+ny)\Big)}{1+r^{2}-2r\cos(y)} \\
& \sum_{k=0}^{n} r^{k}\cos(x+ky) = \frac{\cos(x) - r\cos(x-y) - r^{n+1}\Big(\cos(x+(n+1)y) - r\cos(x+ny)\Big)}{1+r^{2}-2r\cos(y)} \\
-->

<img src="pix/sceq8.png" alt="nxry formulas">

<table class="method">
<tr><td>
<img src="pix/sinesummation.png" alt="nxry formula">
</td></tr>
<tr><td class="center">nrxysin, n=5, r=0.5
</td></tr>
</table>


<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((gen (make-nrxycos 440.0 :n 10)))
    (do ((i 0 (+ i 1)))
        ((= i 44100))
      (outa i (* 0.5 (nrxycos gen))))))
</pre>
</div>
</td></tr>
<tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  gen = make_nrxycos(440.0, 1.0, 10, 0.5);
  44100.times do |i| 
    outa(i, 0.5 * nrxycos(gen), $output) 
    end
  end.output
</pre>
</div>
</td></tr>

<tr>
<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  440.0 :n 10 make-nrxycos { gen }
  44100 0 ?do
    i  gen 0 nrxycos  f2/ *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>



<p>The peak amplitude of nrxysin is hard to predict.
I think nrxysin is close to the -1.0..1.0 ideal, and won't go over 1.0.
<a href="#nrxycos">nrxycos</a> is normalized correctly.
Besides the usual FM input, you can also vary the "r" parameter (via mus-scaler) to get changing spectra.  In the
next example, we add a glissando envelope, and use the same envelope to vary "r" so that as the frequency
goes up, "r" goes down (to avoid foldover, or whatever).
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (ss beg dur freq amp (n 1) (r .5) (ratio 1.0) frqf)
  (let* ((st (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
         (nd (+ st (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
         (sgen (<em class=red>make-nrxysin</em> freq ratio n r))
         (frq-env (and frqf (<a class=quiet href="#make-env">make-env</a> frqf :scaler (<a class=quiet href="#hztoradians">hz-&gt;radians</a> freq) :duration dur)))
         (spectr-env (and frqf (<a class=quiet href="#make-env">make-env</a> frqf :duration dur)))
         (amp-env (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 2 1 3 0) :scaler amp :duration dur)))
    (do ((i st (+ i 1))) 
        ((= i nd))
      (if spectr-env
          (set! (<em class=red>mus-scaler</em> sgen) (* r (exp (- (<a class=quiet href="#env">env</a> spectr-env))))))
      (<a class=quiet href="#outa">outa</a> i (* (<a class=quiet href="#env">env</a> amp-env)
                 (<em class=red>nrxysin</em> sgen (if frq-env (<a class=quiet href="#env">env</a> frq-env) 0.0)))))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () (ss 0 1 400.0 1.0 5 0.5 1.0 '(0 0 1 2)))
</pre>

<p>"r" can also be used in the same way as an FM index, but with much simpler spectral evolution (x^n, x between -1.0 and 1.0, rather than Jn(x)).
In the graph, r is 0 at the midpoint, r goes from -1.0 to 1.0 along the horizontal axis &mdash; I forgot to label the axes.
</p>

<img class="indented" src="pix/nrxy-r.png" alt="nrxycos changing r">

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (let ((gen1 (<em class=red>make-nrxycos</em> 400 1 15 0.95))
        (indr (<a class=quiet href="#make-env">make-env</a> '(0 -1 1 1) 
                :length 80000 :scaler 0.9999)))
    (do ((i 0 (+ i 1)))
        ((= i 80000))
      (set! (<em class=red>mus-scaler</em> gen1) (env indr)) ; this sets r
      (<a class=quiet href="#outa">outa</a> i (* .5 (<em class=red>nrxycos</em> gen1 0.0))))))
</pre>



<!-- MLB's index idea is not so great:
(with-sound (:clipped #f :statistics #t)
  (let* ((dur 2.0)
         (ampf (make-env '(0 1 10 1 11 0) :duration dur :scaler .5))
	 (indf (make-env '(0 0 1 .999) :duration dur))
	 (samps (seconds->samples dur))
	 (N 60))

    (do ((i 0 (+ i 1))
	 (th 0.0 (+ th (hz->radians 1000.0))))
	((= i samps))
  
      (let* ((a .999)
	     (index (env indf))
	     (a2 (+ 1.0 (* a a)))
	     (an (expt a (+ N 1)))
	     (b 1/10)
	     (B (* b th))
	     (thB (- th B))
	     (divisor (* (- a2 (* 2 a index (cos B)))
			 (/ (- (expt a N) 1.0)
			    (- a 1.0))))
	     (val (/ (- (sin th) (* a (sin thB))
			(* an (- (sin (+ th (* (+ N 1) B))) 
				 (* a (sin (+ th (* N B)))))))
		     divisor)))
	(outa i (* (env ampf) val))))))
-->





<!--  SSB-AM  -->

<div class="innerheader" id="ssb-amdoc">ssb-am</div>

<pre class="indented">
<em class=def id="make-ssb-am">make-ssb-am</em> (frequency 0.0) (order 40)
<em class=def id="ssb-am">ssb-am</em> gen (insig 0.0) (fm 0.0)
<em class=def id="ssb-am?">ssb-am?</em> gen
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">ssb-am methods</td></tr>
<tr><td class="inner"><em class=gen>mus-frequency</em></td><td class="inner">frequency in Hz</td></tr>
<tr><td class="inner"><em class=gen>mus-phase</em></td><td class="inner">phase (of embedded sin osc) in radians</td></tr>
<tr><td class="inner"><em class=gen>mus-order</em></td><td class="inner">embedded delay line size</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">same as mus-order</td></tr>
<tr><td class="inner"><em class=gen>mus-interp-type</em></td><td class="inner"><code>mus-interp-none</code></td></tr>
<tr><td class="inner"><em class=gen>mus-xcoeff</em></td><td class="inner">FIR filter coeff</td></tr>
<tr><td class="inner"><em class=gen>mus-xcoeffs</em></td><td class="inner">embedded Hilbert transform FIR filter coeffs</td></tr>
<tr><td class="inner"><em class=gen>mus-data</em></td><td class="inner">embedded filter state</td></tr>
<tr><td class="inner"><em class=gen>mus-increment</em></td><td class="inner">frequency in radians per sample</td></tr>
</table>


<p>ssb-am provides single sideband suppressed carrier amplitude modulation, normally used for frequency shifting.
The basic notion is to shift a spectrum up or down while cancelling either the upper or lower half of the spectrum.
See <a href="sndscm.html#ssbbank">dsp.scm</a> for a number of curious possibilities (time stretch without pitch shift for example).
When this works, which it does more often than I expected, it is much better than the equivalent
phase-vocoder or granular synthesis kludges.
</p>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t :srate 44100)
  (let ((shifter (make-ssb-am 440.0 20))
	(osc (make-oscil 440.0)))
    (do ((i 0 (+ i 1)))
	((= i 44100))
      (outa i (* 0.5 (ssb-am shifter (oscil osc)))))))
</pre>
</div>
</td>
</tr><tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true, :srate, 44100) do
  shifter = make_ssb_am(440.0, 20);
  osc = make_oscil(440.0);
  44100.times do |i|
    outa(i, 0.5 * ssb_am(shifter, oscil(osc)), $output);
    end
  end.output
</pre>
</div>
</td></tr>
<tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  440.0 20 make-ssb-am { shifter }
  440.0 make-oscil { osc }
  44100 0 ?do
    i  shifter  osc 0 0 oscil  0 ssb-am f2/ *output* outa drop
  loop
; :play #t :srate 44100 with-sound drop
</pre>
</div>
</td>
</tr>
</table>


<pre class="indented">
(define* (ssb-am freq (order 40)) 
  ;; higher order = better cancellation
  (let* ((car-freq (abs freq))
	 (cos-car (<a class=quiet href="#make-oscil">make-oscil</a> car-freq (* .5 pi)))
	 (sin-car (<a class=quiet href="#make-oscil">make-oscil</a> car-freq))
	 (dly (<a class=quiet href="#make-delay">make-delay</a> order))
	 (hlb (<a class=quiet href="sndscm.html#makehilberttransform">make-hilbert-transform</a> order)))
    (<a class=quiet href="extsnd.html#mapchannel">map-channel</a> 
      (lambda (y)
        (let ((ccos (<a class=quiet href="#oscil">oscil</a> cos-car))
	      (csin (<a class=quiet href="#oscil">oscil</a> sin-car))
	      (yh (<a class=quiet href="sndscm.html#hilberttransform">hilbert-transform</a> hlb y))
  	      (yd (<a class=quiet href="#delay">delay</a> dly y)))
          (if ((&gt; freq 0.0) - +)
	       (* ccos yd)
               (* csin yh)))))))

(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (shift-pitch beg dur file freq (order 40))
  (let* ((st (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
         (nd (+ st (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
	 (gen (<em class=red>make-ssb-am</em> freq order))
	 (rd (<a class=quiet href="#make-readin">make-readin</a> file)))
    (do ((i st (+ i 1))) 
        ((= i nd))
      (<a class=quiet href="#outa">outa</a> i (<em class=red>ssb-am</em> gen (<a class=quiet href="#readin">readin</a> rd))))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () (shift-pitch 0 3 "oboe.snd" 1108.0))
</pre>


<p>
Normal amplitude modulation, cos(x) * (amp + Y(t)), where Y is some signal, 
produces the carrier (cos(x)), and symmetric sidebands at x+/-frq where frq is each spectral
component of Y.  This is just an elaboration of 
</p>

<pre class="indented">
cos(x) * (amp + cos(y)) = amp * cos(x) + 1/2(cos(x - y) + cos(x + y))
</pre>

<p>
So, the Y spectrum (the first picture below) is shifted up by cos(x) and mirrored on either side of it (the second picture below; the spectral components
on the left side are folding under 0).  In single side-band
AM, we create both the Y spectrum, and, via the hilbert transform, a version of Y in which the phases are shifted too.
Then we can add these two copies, using the phase differences to cancel one side of the symmetric
spectrum (this is the third picture below; the new spectral components are not harmonically related however).  
Once we can shift a pitch without creating its symmetric twin, we can split a spectrum
into many bands, shift each band separately, and thereby retain its original harmonic spacing (the fourth picture).
We have the original, but at a higher pitch.  If we then use <a href="#src">src</a> to convert it back to
its pre-shift pitch, we have the original, but with a different length.
We have decoupled the pitch from the duration, much as in a phase vocoder (which uses an FFT
rather than a filter bank, and an inverse FFT of the moved spectrum, rather than ssb-am).
</p>


<table class="method">
<tr>
<td><img src="pix/orig-oboe.png" alt="unaltered oboe"></td>
<td><img src="pix/am.png" alt="am oboe"></td>
<td><img src="pix/ssbam.png" alt="ssbam oboe"></td>
<td><img src="pix/ssbambank.png" alt="ssbambank oboe"></td>
</tr>
<tr>
<td class="center">original</td>
<td class="center">amplitude modulation</td>
<td class="center">ssb-am</td>
<td class="center">ssb-am bank</td>
</tr>
</table>


<p>The second picture was created from oboe.snd (the original) via:
</p>
<pre class="indented">
(let ((osc (<a class=quiet href="#make-oscil">make-oscil</a> 1000.0))) 
  (<a class=quiet href="extsnd.html#mapchannel">map-channel</a> 
    (lambda (y) 
      (* .5 (<a class=quiet href="#amplitude-modulate">amplitude-modulate</a> .01 (<a class=quiet href="#oscil">oscil</a> osc) y)))))
</pre>

<p>The third picture was created by:
</p>
<pre class="indented">
(let ((am (<em class=red>make-ssb-am</em> 1000 40))) 
  (<a class=quiet href="extsnd.html#mapchannel">map-channel</a> 
    (lambda (y) 
      (<em class=red>ssb-am</em> am y))))
</pre>

<p>
And the fourth used the ssb-am-bank function in dsp.scm rewritten here for with-sound:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (repitch beg dur sound old-freq new-freq 
                 (amp 1.0) (pairs 10) (order 40) (bw 50.0))
  (let* ((start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
         (end (+ start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
         (ssbs (make-vector pairs))
         (bands (make-vector pairs))
         (factor (/ (- new-freq old-freq) old-freq))
         (rd (<a class=quiet href="#make-readin">make-readin</a> sound)))
    (do ((i 1 (+ i 1)))
        ((&gt; i pairs))
      (let ((aff (* i old-freq))
            (bwf (* bw (+ 1.0 (/ i 2 pairs)))))
        (set! (ssbs (- i 1)) (<em class=red>make-ssb-am</em> (* i factor old-freq)))
        (set! (bands (- i 1)) (<a class=quiet href="sndscm.html#makebandpass">make-bandpass</a> (<a class=quiet href="#hztoradians">hz-&gt;radians</a> (- aff bwf)) ; bandpass is in dsp.scm
                                             (<a class=quiet href="#hztoradians">hz-&gt;radians</a> (+ aff bwf)) 
                                             order))))
    (do ((i start (+ i 1))) 
        ((= i end))
      (let ((sum 0.0)
            (y (<a class=quiet href="#readin">readin</a> rd)))
        (do ((band 0 (+ 1 band)))
            ((= band pairs))
          (set! sum (+ sum (<em class=red>ssb-am</em> (ssbs band) 
                                   (<a class=quiet href="sndscm.html#makebandpass">bandpass</a> (bands band) y)))))
        (<a class=quiet href="#outa">outa</a> i (* amp sum))))))

 (let* ((sound "oboe.snd")
        (mx (maxamp sound))
        (dur (<a class=quiet href="extsnd.html#mussoundduration">mus-sound-duration</a> sound)))
    (<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:scaled-to mx  :srate (srate sound))
      (repitch 0 dur sound 554 1000)))
</pre>


<p>If you'd like to move formants independently of the fundamental, add
or subtract integer multiples of the new fundamental from the make-ssb-am
frequency argument.  In the repitch instrument above, say we wanted to 
add a "stretch" argument to spread out or squeeze down the spectrum.
We would replace the current make-ssb-am line with:
</p>

<pre class="indented">
(set! (ssbs (- i 1)) (<em class=red>make-ssb-am</em> (+ (* i factor old-freq)
                                   (* new-freq (round (* i <em class=red>stretch</em>))))))
</pre>





<!--  WAVE-TRAIN  -->

<div class="innerheader" id="wave-traindoc">wave-train</div>

<pre class="indented">
<em class=def id="make-wave-train">make-wave-train</em> 
        (frequency 0.0) 
        (initial-phase 0.0) 
        wave 
        (size *clm-table-size*) 
        (type mus-interp-linear)

<em class=def id="wave-train">wave-train</em> w (fm 0.0)
<em class=def id="wave-train?">wave-train?</em> w

<em class=def id="make-wave-train-with-env">make-wave-train-with-env</em> frequency env size
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">wave-train methods</td></tr>
<tr><td class="inner"><em class=gen>mus-frequency</em></td><td class="inner">frequency in Hz</td></tr>
<tr><td class="inner"><em class=gen>mus-phase</em></td><td class="inner">phase in radians</td></tr>
<tr><td class="inner"><em class=gen>mus-data</em></td><td class="inner">wave array (no set!)</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">length of wave array (no set!)</td></tr>
<tr><td class="inner"><em class=gen>mus-interp-type</em></td><td class="inner">interpolation choice (no set!)</td></tr>
</table>

<p>wave-train adds a copy of its wave (a "grain" in more modern parlance) into its output at frequency times per second.
These copies can overlap or have long intervals of silence in between, so
wave train can be viewed either as an extension of pulse-train and table-lookup,
or as a primitive form of granular synthesis.
make-wave-train-with-env (defined in generators.scm) returns a new wave-train generator with the envelope 'env' loaded into its table.
</p>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((gen (make-wave-train 440.0
               :wave (let ((v (make-float-vector 64)) 
                           (g (make-ncos 400 10)))
                       (set! (mus-phase g) (* -0.5 pi))
                       (do ((i 0 (+ i 1))) 
                           ((= i 64)) 
                         (set! (v i) (ncos g))) 
                       v))))
    (do ((i 0 (+ i 1)))
        ((= i 44100))
      (outa i (* 0.5 (wave-train gen))))))
</pre>
</div>
</td>
</tr><tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  v = make_vct(64);
  g = make_ncos(400, 10);
  g.phase =  -0.5 * 3.14159;
  64.times do |i|
    v[i] = ncos(g);
    end
  gen = make_wave_train(440.0, :wave, v);
  44100.times do |i| 
    outa(i, 0.5 * wave_train(gen), $output) 
    end
  end.output
</pre>
</div>
</td>
</tr><tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  400 10 make-ncos { g }
  g -0.5 pi f* set-mus-phase drop
  64 make-vct map! g 0 ncos end-map { v }
  440.0 :wave v make-wave-train { gen }
  44100 0 do
    i  gen 0 wave-train  f2/ *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>


<img src="pix/wt.png" alt="wave-train example">

<!--
(with-sound (:clipped #f :statistics #t :scaled-to .5 :play #t)
  (let ((gen (make-wave-train 300.0 :wave (let ((v (make-float-vector 64)) 
                                                (g (make-sum-of-cosines 10 400 (* -0.5 pi)))) 
                                            (do ((i 0 (+ i 1))) 
                                                ((= i 64)) 
                                              (set! (v i) (sum-of-cosines g))) 
                                            v))))
       (do ((i 0 (+ i 1)))
           ((= i 1000))
         (outa i (wave-train gen)))))
-->

<p>
With some simple envelopes or filters, you can
use this for VOSIM and other related techniques. 
Here is a FOF instrument based loosely on fof.c of Perry Cook and the article
"Synthesis of the Singing Voice" by Bennett and Rodet in 
"Current Directions in Computer Music Research".
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (fofins beg dur frq amp vib f0 a0 f1 a1 f2 a2 ve ae)
  (let* ((start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
         (end (+ start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
         (ampf (<a class=quiet href="#make-env">make-env</a> (or ae '(0 0 25 1 75 1 100 0)) :scaler amp :duration dur))
         (frq0 (<a class=quiet href="#hztoradians">hz-&gt;radians</a> f0))
         (frq1 (<a class=quiet href="#hztoradians">hz-&gt;radians</a> f1))
         (frq2 (<a class=quiet href="#hztoradians">hz-&gt;radians</a> f2))
         (foflen (if (= *clm-srate* 22050) 100 200))
         (vibr (<a class=quiet href="#make-oscil">make-oscil</a> 6))
         (vibenv (<a class=quiet href="#make-env">make-env</a> (or ve '(0 1 100 1)) :scaler vib :duration dur))
         (win-freq (/ (* 2 pi) foflen))
         (foftab (make-float-vector foflen))
         (wt0 (<em class=red>make-wave-train</em> :wave foftab :frequency frq)))
    (do ((i 0 (+ i 1)))
        ((= i foflen))
      (set! (foftab i) ;; this is not the pulse shape used by B&amp;R
            (* (+ (* a0 (sin (* i frq0))) 
                  (* a1 (sin (* i frq1))) 
                  (* a2 (sin (* i frq2)))) 
               .5 (- 1.0 (cos (* i win-freq))))))
    (do ((i start (+ i 1)))
        ((= i end))
      (<a class=quiet href="#outa">outa</a> i (* (<a class=quiet href="#env">env</a> ampf) (<em class=red>wave-train</em> wt0 (* (<a class=quiet href="#env">env</a> vibenv) (<a class=quiet href="#oscil">oscil</a> vibr))))))))

(<a class=quiet href="sndscm.html#withsound">with-sound</a> () (fofins 0 1 270 .2 .001 730 .6 1090 .3 2440 .1)) ; "Ahh"

(<a class=quiet href="sndscm.html#withsound">with-sound</a> () ; one of JC's favorite demos
  (fofins 0 4 270 .2 0.005 730 .6 1090 .3 2440 .1 '(0 0 40 0 75 .2 100 1) 
          '(0 0 .5 1 3 .5 10 .2 20 .1 50 .1 60 .2 85 1 100 0))
  (fofins 0 4 (* 6/5 540) .2 0.005 730 .6 1090 .3 2440 .1 '(0 0 40 0 75 .2 100 1) 
          '(0 0 .5 .5 3 .25 6 .1 10 .1 50 .1 60 .2 85 1 100 0))
  (fofins 0 4 135 .2 0.005 730 .6 1090 .3 2440 .1 '(0 0 40 0 75 .2 100 1) 
          '(0 0 1 3 3 1 6 .2 10 .1 50 .1 60 .2 85 1 100 0)))
</pre>


<p>The wave-trains's wave is a float-vector accessible via mus-data.  The "fm" argument affects the frequency of
repetition.  Here is a wave-train instrument that increasingly filters its grain (the word "now", for example) 
while increasing the repetition rate.  We're also using a pulse train as a sort of internal click track,
using the same frequency envelope as the wave-train, so we have some idea when to refilter the grain.
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (when? start-time duration start-freq end-freq grain-file)
  (let* ((beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> start-time))
         (len (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> duration))
         (end (+ beg len))
         (grain-dur (<a class=quiet href="extsnd.html#mussoundduration">mus-sound-duration</a> grain-file))
         (frqf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1) :scaler (<a class=quiet href="#hztoradians">hz-&gt;radians</a> (- end-freq start-freq)) :duration duration))
         (click-track (<em class=red>make-pulse-train</em> start-freq))
         (grain-size (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> grain-dur))
         (grains (<em class=red>make-wave-train</em> :size grain-size :frequency start-freq))
         (ampf (<a class=quiet href="#make-env">make-env</a> '(0 1 1 0) :scaler .7 :offset .3 :duration duration :base 3.0))
         (grain (<em class=red>mus-data</em> grains)))
    (<a class=quiet href="#filetoarray">file-&gt;array</a> grain-file 0 0 grain-size grain)
    (let ((original-grain (copy grain)))
      (do ((i beg (+ i 1)))
          ((= i end))
        (let ((gliss (<a class=quiet href="#env">env</a> frqf)))
          (outa i (* (<a class=quiet href="#env">env</a> ampf) (<em class=red>wave-train</em> grains gliss)))
          (let ((click (<em class=red>pulse-train</em> click-track gliss)))
            (if (&gt; click 0.0)
                (let* ((scaler (max 0.1 (* 1.0 (/ (- i beg) len))))
                       (comb-len 32)
                       (c1 (<a class=quiet href="#make-comb">make-comb</a> scaler comb-len))
                       (c2 (<a class=quiet href="#make-comb">make-comb</a> scaler (floor (* comb-len .75))))
                       (c3 (<a class=quiet href="#make-comb">make-comb</a> scaler (floor (* comb-len 1.25)))))
                  (do ((k 0 (+ k 1)))
                      ((= k grain-size))
                    (let ((x (original-grain k)))
                     (set! (grain k) (+ (<a class=quiet href="#comb">comb</a> c1 x) (<a class=quiet href="#comb">comb</a> c2 x) (<a class=quiet href="#comb">comb</a> c3 x)))))))))))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () (when? 0 4 2.0 8.0 "right-now.snd"))
</pre>

<p>wave-train is built on table-lookup and shares all of its questionable aspects.  See also the <a href="#pulsedenv">pulsed-env</a>e generator
in generators.scm, used in animals.scm.  It is often simpler to use <a href="#pulse-train">pulse-train</a> as the repetition
trigger, and mus-reset to restart an envelope.  
</p>




<!--  RAND, RAND-INTERP  -->

<div class="innerheader" id="randdoc">rand, rand-interp</div>

<pre class="indented">
<em class=def id="make-rand">make-rand</em> 
        (frequency 0.0) ; frequency at which new random numbers occur
        (amplitude 1.0)                     ; numbers are between -amplitude and amplitude
        (envelope '(-1 1 1 1))              ; distribution envelope (uniform distribution is the default)
        distribution                        ; pre-computed distribution

<em class=def id="rand">rand</em> r (sweep 0.0)
<em class=def id="rand?">rand?</em> r

<em class=def id="make-rand-interp">make-rand-interp</em> 
        (frequency 0.0) 
        (amplitude 1.0)
        (envelope '(-1 1 1 1)
        distribution)

<em class=def id="rand-interp">rand-interp</em> r (sweep 0.0)
<em class=def id="rand-interp?">rand-interp?</em> r

<em class=def id="mus-random">mus-random</em> amp
<em class=def id="mus-rand-seed">mus-rand-seed</em>
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">rand and rand-interp methods</td></tr>
<tr><td class="inner"><em class=gen>mus-frequency</em></td><td class="inner">frequency in Hz</td></tr>
<tr><td class="inner"><em class=gen>mus-phase</em></td><td class="inner">phase in radians</td></tr>
<tr><td class="inner"><em class=gen>mus-scaler</em></td><td class="inner">amplitude arg used in make-&lt;gen&gt;</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">distribution table (float-vector) length</td></tr>
<tr><td class="inner"><em class=gen>mus-data</em></td><td class="inner">distribution table (float-vector), if any</td></tr>
<tr><td class="inner"><em class=gen>mus-increment</em></td><td class="inner">frequency in radians per sample</td></tr>
</table>


<p>rand produces a sequence of random numbers between -amplitude and
amplitude (a sort of step function).
rand-interp interpolates between successive
random numbers.
rand-interp could be defined as (<a class=quiet href="#moving-average">moving-average</a> agen (rand rgen)) where the
averager has the same period (length) as the rand.  
In both cases, the "envelope" argument or the "distribution" argument determines the random number distribution.
mus-random returns a random number between -amplitude and amplitude.
</p>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:channels 2 :play #t)
  (let ((ran1 (make-rand 5.0 (hz-&gt;radians 220.0)))
        (ran2 (make-rand-interp 5.0 (hz-&gt;radians 220.0)))
	(osc1 (make-oscil 440.0))
	(osc2 (make-oscil 1320.0)))
    (do ((i 0 (+ i 1)))
	((= i 88200))
      (outa i (* 0.5 (oscil osc1 (rand ran1))))
      (outb i (* 0.5 (oscil osc2 (rand-interp ran2)))))))
</pre>
</div>
</td>

</tr><tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true, :channels, 2) do
  ran1 = make_rand(5.0, hz2radians(220.0));
  ran2 = make_rand_interp(5.0, hz2radians(220.0));
  osc1 = make_oscil(440.0);  
  osc2 = make_oscil(1320.0);
  88200.times do |i|
    outa(i, 0.5 * oscil(osc1, rand(ran1)), $output);
    outb(i, 0.5 * oscil(osc2, rand_interp(ran2)), $output);
    end
  end.output
</pre>
</div>
</td>

</tr><tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  5.0 220.0 hz-&gt;radians make-rand { ran1 }
  5.0 330.0 hz-&gt;radians make-rand-interp { ran2 }
   440.0 make-oscil { osc1 }
  1320.0 make-oscil { osc2 }
  88200 0 do
    i  osc1  ran1 0 rand         0 oscil  f2/ *output* outa drop
    i  osc2  ran2 0 rand-interp  0 oscil  f2/ *output* outb drop
  loop
; :channels 2 :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>


<p>The "frequency" is the rate at which new values are produced, so it makes sense to request a frequency above srate/2.
If rand's frequency is the current srate, it produces a new random value on every sample.  
Since rand is (normally) producing a sequence of square-waves, and rand-interp a sequence of triangle-waves,
both reflect that in their spectra (spectrum y axis is in dB):
</p>

<!--
(with-sound ()
  (let ((gen (make-rand 2000)))
    (do ((i 0 (+ i 1)))
	((= i 50000))
      (outa i (* .5 (rand gen))))))

(with-sound ()
  (let ((gen (make-rand-interp 2000)))
    (do ((i 0 (+ i 1)))
	((= i 50000))
      (outa i (* .5 (rand-interp gen))))))

(with-sound ()
  (let ((gen (make-square-wave 1000)))
    (do ((i 0 (+ i 1)))
	((= i 50000))
      (outa i (* .5 (square-wave gen))))))

(with-sound ()
  (let ((gen (make-triangle-wave 1000)))
    (do ((i 0 (+ i 1)))
	((= i 50000))
      (outa i (* .5 (triangle-wave gen))))))
-->

<table class="method">
<tr>
<td><img src="pix/sqsq.png" alt="sqwave spectrum"></td><td><img src="pix/tritri.png" alt="triwave spectrum"></td>
</tr>
<tr>
<td class="center">square-wave (freq=1000)</td><td class="center">triangle-wave (freq=1000)</td>
</tr>

<tr>
<td><img src="pix/randsq.png" alt="rand spectrum"></td><td><img src="pix/randtri.png" alt="rand-interp spectrum"></td>
</tr>
<tr>
<td class="center">rand (freq=2000)</td><td class="center">rand-interp (freq=2000)</td>
</tr>
</table>


<p>There are a variety of ways to get a non-uniform random number distribution:
<code>(random (random 1.0))</code> or <code>(sin (mus-random pi))</code> are examples. Exponential distribution could be:
</p>

<pre class="indented">
(log (max .01 (random 1.0)) .01)
</pre>

<p>where the ".01"'s affect how tightly the resultant values cluster toward 0.0 &mdash;
set them to .0001, for example, to get most of the random values close to 0.0.
The central-limit theorem says that you can get closer and closer to gaussian
noise by adding rand's together.  Orfanidis in 
"Introduction to Signal Processing" says 12 calls on rand will
do perfectly well:
</p>

<pre class="indented">
(define (gaussian-noise)
  (do ((val 0.0)
       (i 0 (+ i 1))) 
      ((= i 12) (/ val 12.0))
    (set! val (+ val (random 1.0)))))
</pre>

<p>You can watch this (or any other distribution) in action via:
</p>

<pre class="indented">
(define (add-rands n)
  (let ((bins (make-vector 201 0))
	(rands (make-vector n #f)))
    (do ((i 0 (+ i 1)))
	((= i n))
      (set! (rands i) (<em class=red>make-rand</em> :frequency *clm-srate* :amplitude (/ 100 n)))
      (rand (rands i)))
    (do ((i 0 (+ i 1)))
	((= i 100000))
      (do ((sum 0.0)
	   (k 0 (+ k 1)))
	  ((= k n)
	   (let ((bin (floor (+ 100 (round sum)))))
	     (set! (bins bin) (+ (bins bin) 1))))
        (set! sum (+ sum (<em class=red>rand</em> (rands k))))))
    bins))

(let ((ind (<a class=quiet href="extsnd.html#newsound">new-sound</a> "test.snd")))
  (do ((n 1 (+ n 1)))
      ((= n 12))
    (let* ((bins (vector-&gt;float-vector (add-rands n)))
	   (pk (maxamp bins)))
      (float-vector-&gt;channel (float-vector-scale! bins (/ 1.0 pk)))
      (set! (<a class=quiet href="extsnd.html#xaxislabel">x-axis-label</a>) (<a class=quiet>format</a> #f "n: ~D" n))
      (<a class=quiet href="extsnd.html#updatetimegraph">update-time-graph</a>))))
</pre>

<p>
Another way to get different distributions is the "rejection method" in which we generate random number
pairs until we get a pair that falls within the
desired distribution; see <a href="sndscm.html#anyrandom">any-random</a> in dsp.scm.
The rand and rand-interp generators, however, use the "transformation method".
The make-rand and make-rand-interp "envelope" arguments specify
the desired distribution function; the generator takes the
inverse of the integral of this envelope, loads that into an array, and uses
<code>(array-interp (random array-size))</code>.  This gives
random numbers of any arbitrary distribution at a computational cost
equivalent to the old waveshape generator.
The x axis of the envelope sets the output range (before scaling by the "amplitude" argument), and
the y axis sets the relative weight of the corresponding x axis value.
So, the default is <code>'(-1 1 1 1)</code> which says "output numbers between -1 and 1,
each number having the same chance of being chosen".
An envelope of <code>'(0 1 1 0)</code> outputs values between 0 and 1, denser toward 0.
If you already have the distribution table (a float-vector, the result of <code>(inverse-integrate envelope)</code> for example),
you can pass it through the "distribution" argument.  Here is gaussian noise
using the "envelope" argument:
</p>

<pre class="indented">
(define (gaussian-envelope s)
  (do ((e ())
       (den (* 2.0 s s))
       (i 0 (+ i 1))
       (x -1.0 (+ x .1))
       (y -4.0 (+ y .4)))
      ((= i 21)
       (reverse e))
    (set! e (cons (exp (- (/ (* y y) den))) (cons x e)))))

(<em class=red>make-rand</em> :envelope (gaussian-envelope 1.0))
</pre>

<p>If you want a particular set of values, it's simplest to fill a float-vector with those values,
then use random as the index into the array.  Say we want 0.0, 0.5, and 1.0 at random,
but 0.5 should happen three times as often as either of the others:
</p>

<pre class="indented">
(do ((vals (float-vector 0.0 0.5 0.5 0.5 1.0))
     (i 0 (+ i 1)))
    ((= i 10))
  (<a class=quiet>format</a> () ";~A " (vals (random 5))))
</pre>

<p>These "distributions" refer to the values returned by the random number
generator, but all of them produce white noise (all frequencies are equally
likely).  
You can, of course, filter the output of rand to get a different
frequency distribution.  See, for example, <a href="#round-interp">round-interp</a> in generators.scm.
It uses a <a href="#moving-average">moving-average</a> generator to low-pass filter the output of a rand-interp
generator; the result is a rand-interp signal with rounded corners.
Orfanidis also mentions a clever way to get reasonably good 1/f noise:
sum together n rand's, where each rand is running an octave slower
than the preceding:
</p>

<pre class="indented">
(define (make-1f-noise n)
  ;; returns an array of rand's ready for the 1f-noise generator
  (do ((rans (make-vector n))
       (i 0 (+ i 1))) 
      ((= i n) rans)
    (set! (rans i) (<em class=red>make-rand</em> :frequency (/ *clm-srate* (expt 2 i))))))

(define (1f-noise rans)
  (let ((val 0.0) 
        (len (length rans)))
    (do ((i 0 (+ i 1)))
        ((= i len) (/ val len))
      (set! val (+ val (<em class=red>rand</em> (rans i)))))))
</pre>

<p>This is the <a href="#pink-noise">pink-noise</a> generator in generators.scm.
See also <a href="#green-noise">green-noise</a> &mdash; bounded brownian noise that can mimic 1/f noise in some cases.
(The brownian graph below has a different dB range, and the rand graph would be flat if we used a frequency of 44100).
</p>

<table class="method">
<tr>
<td class="center">random</td>
<td class="center">rand</td>
<td class="center">rand-interp</td>
</tr><tr>
<td><img src="pix/random.png" alt="random spectrum"></td>
<td><img src="pix/rand.png" alt="rand spectrum"></td>
<td><img src="pix/randi.png" alt="rand-interp spectrum"></td>
</tr>
<tr>
<td class="center">1/f</td>
<td class="center">brownian</td>
<td class="center">green</td>
</tr><tr>
<td><img src="pix/1f.png" alt="1/f spectrum"></td>
<td><img src="pix/brownian.png" alt="brownian spectrum"></td>
<td><img src="pix/green.png" alt="green spectrum"></td>
</tr></table>


<!-- CLM:
;; 1f.png
(with-sound ()
  (let ((noise (make-1f-noise 12)))
    (do ((i 0 (+ i 1)))
	((= i 10000))
      (outa i (1f-noise noise)))))

;; rand.png
(with-sound ()
  (let ((noise (make-rand 10000.0)))
    (do ((i 0 (+ i 1)))
	((= i 10000))
      (outa i (rand noise)))))

;; randi.png
(with-sound ()
  (let ((noise (make-rand-interp 10000.0)))
    (do ((i 0 (+ i 1)))
	((= i 10000))
      (outa i (rand-interp noise)))))

;; random.png
(with-sound ()
  (do ((i 0 (+ i 1)))
      ((= i 10000))
    (outa i (- 0.5 (random 1.0)))))

;; brownian.png
(with-sound ()
  (let ((val 0.0))
    (do ((i 0 (+ i 1)))
	((= i 10000))
      (set! val (+ val -.005 (random 0.01)))
      (outa i val))))

;; green.png
(with-sound ()
  (let ((noise (make-green-noise 10000.0 1)))
    (do ((i 0 (+ i 1)))
	((= i 10000))
      (outa i (green-noise noise 0.0)))))
-->


<p>And we can't talk about noise without mentioning fractals:</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (fractal start duration m x amp)
  ;; use formula of M J Feigenbaum
  (let* ((beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> start))
	 (end (+ beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> duration))))
    (do ((i beg (+ i 1)))
        ((= i end))
      (<a class=quiet href="#outa">outa</a> i (* amp x))
      (set! x (- 1.0 (* m x x))))))

;;; this quickly reaches a stable point for any m in[0,.75], so:
(<a class=quiet href="sndscm.html#withsound">with-sound</a> () (fractal 0 1 .5 0 .5)) 
;;; is just a short "ftt"
(<a class=quiet href="sndscm.html#withsound">with-sound</a> () (fractal 0 1 1.5 .20 .2))
</pre>

<p>With this instrument you can hear
the change over from the stable equilibria, to the period doublings,
and finally into the combination of noise and periodicity that
has made these curves famous. See appendix 2 to Ekeland's "Mathematics and the Unexpected" for more details.
Another instrument based on similar ideas is:</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (attract beg dur amp c) ; c from 1 to 10 or so
  ;; by James McCartney, from CMJ vol 21 no 3 p 6
  (let ((st (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg)))
    (do ((nd (+ st (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
         (a .2) 
         (b .2) 
         (dt .04)
         (scale (/ (* .5 amp) c))
         (x1 0.0) 
         (x -1.0) 
         (y 0.0) 
         (z 0.0)
         (i st (+ i 1)))
        ((= i nd))
     (set! x1 (- x (* dt (+ y z))))
     (set! y (+ y (* dt (+ x (* a y)))))
     (set! z (+ z (* dt (- (+ b (* x z)) (* c z)))))
     (set! x x1)
     (<a class=quiet href="#outa">outa</a> i (* scale x)))))
</pre>

<p>which gives brass-like sounds!
We can also get all the period doublings and so on from sin:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#withsound">with-sound</a> (:clipped #f :scaled-to 0.5)
  (do ((x 0.5)
       (i 0 (+ i 1)))
      ((= i 44100))
    (outa i x)
    (set! x (* 4 (sin (* pi x))))))
</pre>

<p>For an extended discussion of this case, complete with pictures of the
period doublings, see Strogatz, "Nonlinear Dynamics and Chaos". 
</p>

<p>
mus-rand-seed provides access to the seed for mus-random's random number generator:
</p>
<pre class="indented">
&gt; (set! (mus-rand-seed) 1234)
1234
&gt; (mus-random 1.0)
-0.7828369138846
&gt; (mus-random 1.0)
-0.880371093652
&gt; (set! (mus-rand-seed) 1234) ; now start again with the same sequence of numbers
1234
&gt; (mus-random 1.0)
-0.7828369138846
&gt; (mus-random 1.0)
-0.880371093652
</pre>

<p>The clm random functions discussed here are different from s7's random function.
The latter has a random-state record to guide the sequence (and uses a different
algorithm), whereas the clm functions just use an integer, mus-rand-seed.
</p>



<p>See also 
<a href="sndscm.html#ditherchannel">dither-channel</a> (dithering),
<a href="sndscm.html#maracadoc">maraca.scm</a> (physical modelling), 
<a href="sndscm.html#noisedoc">noise.scm, noise.rb</a> (a truly ancient noise-maker),
<a href="sndscm.html#anyrandom">any-random</a> (arbitrary distribution via the rejection method),
and <a href="#green-noise">green-noise</a> (bounded Brownian noise).
</p>




<!--  SIMPLE FILTERS  -->

<div class="innerheader" id="one-poledoc">one-pole, one-zero, two-pole, two-zero</div>

<pre class="indented">
 <em class=def id="make-one-pole">make-one-pole</em> a0 b1    ; b1 &lt; 0.0 gives lowpass, b1 &gt; 0.0 gives highpass
 <em class=def id="one-pole">one-pole</em> f input 
 <em class=def id="one-pole?">one-pole?</em> f

 <em class=def id="make-one-zero">make-one-zero</em> a0 a1    ; a1 &gt; 0.0 gives weak lowpass, a1 &lt; 0.0 highpass
 <em class=def id="one-zero">one-zero</em> f input 
 <em class=def id="one-zero?">one-zero?</em> f

 <em class=def id="make-two-pole">make-two-pole</em> frequency [or a0] radius [or b1] b2
 <em class=def id="two-pole">two-pole</em> f input 
 <em class=def id="two-pole?">two-pole?</em> f

 <em class=def id="make-two-zero">make-two-zero</em> frequency [or a0] radius [or a1] a2
 <em class=def id="two-zero">two-zero</em> f input 
 <em class=def id="two-zero?">two-zero?</em> f
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">simple filter methods</td></tr>
<tr><td class="inner"><em class=gen>mus-xcoeff</em></td><td class="inner">a0, a1, a2 in equations</td></tr>
<tr><td class="inner"><em class=gen>mus-ycoeff</em></td><td class="inner">b1, b2 in equations</td></tr>
<tr><td class="inner"><em class=gen>mus-order</em></td><td class="inner">1 or 2 (no set!)</td></tr>
<tr><td class="inner"><em class=gen>mus-scaler</em></td><td class="inner">two-pole and two-zero radius</td></tr>
<tr><td class="inner"><em class=gen>mus-frequency</em></td><td class="inner">two-pole and two-zero center frequency</td></tr>
</table>

<p>These are the simplest of filters. If you're curious about filters, 
Julius Smith's on-line <a href="http://www-ccrma.stanford.edu/~jos/filters/">Introduction to Digital Filters</a> is
excellent.
</p>

<pre class="indented">
one-zero  y(n) = a0 x(n) + a1 x(n-1)
one-pole  y(n) = a0 x(n) - b1 y(n-1)
two-pole  y(n) = a0 x(n) - b1 y(n-1) - b2 y(n-2)
two-zero  y(n) = a0 x(n) + a1 x(n-1) + a2 x(n-2)
</pre>

<p>
The "a0, b1" nomenclature is taken from Julius Smith's "An Introduction to Digital
Filter Theory" in Strawn "Digital Audio Signal Processing", and is different
from that used in the more general filters such as <a href="#fir-filter">fir-filter</a>.
In make-two-pole and make-two-zero you can specify either the actual
desired coefficients ("a0" and friends), or the center frequency and radius of the
filter ("frequency" and "radius").  The word "radius" refers to the unit circle,
so it should be between 0.0 and (less than) 1.0.
"frequency" should be between 0 and srate/2.  
</p>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((flt (make-two-pole 1000.0 0.999))
	(ran1 (make-rand 10000.0 .002)))
    (do ((i 0 (+ i 1)))
	((= i 44100))
      (outa i (* 0.5 (two-pole flt (rand ran1)))))))
</pre>
</div>
</td>
</tr><tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  flt = make_two_pole(1000.0, 0.999);
  ran1 = make_rand(10000.0, 0.002); 
  44100.times do |i|
    outa(i, 0.5 * two_pole(flt, rand(ran1)), $output);
    end
  end.output
</pre>
</div>
</td>
</tr><tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  1000.0 0.999 make-two-pole { flt }
  10000.0 0.002 make-rand { ran1 }
  44100 0 do
    i  flt  ran1 0 rand  two-pole  f2/ *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>


<p>We can use a one-pole filter as an "exponentially weighted moving average":
</p>

<pre class="indented">
(make-one-pole (/ 1.0 order) (/ (- order) (+ 1.0 order)))
</pre>

<p>where "order" is more or less how long an input affects the output.
The <a href="#mus-xcoeff">mus-xcoeff</a> and <a href="#mus-ycoeff">mus-ycoeff</a> functions give access to the filter coefficients.
<a href="sndscm.html#prc95doc">prc95.scm</a> uses them to make "run time"
alterations to the filters:
</p>

<pre class="indented">
(set! (mus-ycoeff p 1) (- val))     ; "p" is a one-pole filter, this is setting "b1"
(set! (mus-xcoeff p 0) (- 1.0 val)) ; this is setting "a0"
</pre>

<p>We can also use <a href="#mus-frequency">mus-frequency</a> and <a href="#mus-scaler">mus-scaler</a> (the pole "radius") as a more intuitive handle on these coefficients:
</p>

<pre class="indented">
&gt; (define p (make-two-pole :radius .9 :frequency 1000.0))
#&lt;unspecified&gt;
&gt;p
#&lt;two-pole: a0: 1.000, b1: -1.727, b2: 0.810, y1: 0.000, y2: 0.000&gt;
&gt; (mus-frequency p)
1000.00025329731
&gt; (mus-scaler p)
0.899999968210856
&gt; (set! (mus-frequency p) 2000.0)
2000.0
&gt;p
#&lt;two-pole: a0: 1.000, b1: -1.516, b2: 0.810, y1: 0.000, y2: 0.000&gt;
</pre>

<p>A quick way to see the frequency response of a filter is to drive it with a sine wave sweeping from
0 Hz to half the sampling rate; if the sound length is 0.5 seconds, you can read off the time axis
as the response at that frequency (in terms of a sampling rate of 1.0):
</p>

<pre class="indented">
(define (test-filter flt)
  (let* ((osc (<a class=quiet href="#make-oscil">make-oscil</a>))
	 (samps (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> 0.5))
	 (ramp (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1) 
                     :scaler (<a class=quiet href="#hztoradians">hz-&gt;radians</a> samps) 
                     :length samps)))
    (<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
      (do ((i 0 (+ i 1)))
	  ((= i samps))
        (<a class=quiet href="#outa">outa</a> i (flt (<a class=quiet href="#oscil">oscil</a> osc (<a class=quiet href="#env">env</a> ramp))))))))
		
(test-filter (make-one-zero 0.5 0.5))
(test-filter (make-one-pole 0.1 -0.9))
(test-filter (make-two-pole 0.1 0.1 0.9))
(test-filter (make-two-zero 0.5 0.2 0.3))
</pre>

<img class="indented" src="pix/2pole.png" alt="simple filters">



<!--
(define (test-filter flt chan)
  (let* ((osc (make-oscil 0.0))
	 (samps (seconds->samples 0.5))
	 (ramp (make-env '(0 0 1 1) :scaler (hz->radians samps) :length samps)))

      (do ((i 0 (+ i 1)))
	  ((= i samps))
        (out-any i (flt (oscil osc (env ramp))) chan))))

(with-sound (:channels 4)
  (test-filter (make-one-zero 0.5 0.5) 0)
  (test-filter (make-one-pole 0.1 -0.9) 1)
  (test-filter (make-two-pole 0.1 0.1 0.9) 2)
  (test-filter (make-two-zero 0.5 0.2 0.3) 3))

(define (fixup-axes)
  (set! *selected-data-color* (make-color 0 0 0))
  (set! *selected-graph-color* (make-color 1 1 1))
  (set! (x-axis-label 0 0) "(make-one-zero 0.5 0.5)")
  (set! (x-axis-label 0 1) "(make-one-pole 0.1 -0.9)")
  (set! (x-axis-label 0 2) "(make-two-pole 0.1 0.1 0.9)")
  (set! (x-axis-label 0 3) "(make-two-zero 0.5 0.2 0.3)"))
-->





<!--  FORMANT  -->

<div class="innerheader" id="formantdoc">formant</div>

<pre class="indented">
<em class=def id="make-formant">make-formant</em> 
      frequency   ; resonance center frequency in Hz
      radius      ; resonance width, indirectly
<em class=def id="formant">formant</em> f input center-frequency-in-radians
<em class=def id="formant?">formant?</em> f

<em class=def id="formantbank">formant-bank</em> filters input
<em class=def id="formantbankp">formant-bank?</em> f
<em class=def id="makeformantbank">make-formant-bank</em> filters amps

<em class=def id="make-firmant">make-firmant</em> frequency radius
<em class=def id="firmant">firmant</em> f input center-frequency-in-radians
<em class=def id="firmant?">firmant?</em> f

;; the next two are optimizations that I may remove
<em class=def>mus-set-formant-frequency</em> f frequency
<em class=def>mus-set-formant-radius-and-frequency</em> f radius frequency
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">formant methods</td></tr>
<tr><td class="inner"><em class=gen>mus-phase</em></td><td class="inner">formant radius</td></tr>
<tr><td class="inner"><em class=gen>mus-frequency</em></td><td class="inner">formant center frequency</td></tr>
<tr><td class="inner"><em class=gen>mus-order</em></td><td class="inner">2 (no set!)</td></tr>
</table>

<p>formant and firmant are resonators (two-pole, two-zero bandpass filters) centered at "frequency", with the bandwidth set by "radius".
</p>

<pre class="indented">
formant:
    y(n) = x(n) - 
           r * x(n-2) + 
           2 * r * cos(frq) * y(n-1) - 
           r * r * y(n-2)

firmant:
    x(n+1) = r * (x(n) - 2 * sin(frq/2) * y(n)) + input
    y(n+1) = r * (2 * sin(frq/2) * x(n+1) + y(n))
</pre>


<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((flt (make-firmant 1000.0 0.999))
	(ran1 (make-rand 10000.0 5.0)))
    (do ((i 0 (+ i 1)))
	((= i 44100))
      (outa i (* 0.5 (firmant flt (rand ran1)))))))
</pre>
</div>
</td>
</tr><tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  flt = make_firmant(1000.0, 0.999);
  ran1 = make_rand(10000.0, 5.0); 
  44100.times do |i|
    outa(i, 0.5 * firmant(flt, rand(ran1)), $output);
    end
  end.output
</pre>
</div>
</td>
</tr><tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  1000.0 0.999 make-firmant { flt }
  10000.0 5.0 make-rand { ran1 }
  44100 0 do
    i  flt  ran1 0 rand  #f firmant  f2/ *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>

<p>The formant generator is described in "A Constant-gain Digital Resonator Tuned By a Single Coefficient" by Julius
O. Smith and James B. Angell in Computer Music Journal Vol. 6 No. 4 (winter
1982) and "A note on
Constant-Gain Digital Resonators" by Ken Steiglitz, CMJ vol 18 No. 4 pp.8-10
(winter 1994).
The formant bandwidth is a function of the "radius", and its center frequency is set by "frequency".
As the radius approaches 1.0 (the unit circle), the
resonance gets narrower.
Use <a href="#mus-frequency">mus-frequency</a> to change the center frequency, and <a href="#mus-scaler">mus-scaler</a> to change the radius.
The radius can be set in terms of desired bandwidth in Hz via:
</p>
<pre class="indented">
(exp (* -0.5 (<a class=quiet href="#hztoradians">hz-&gt;radians</a> bandwidth)))
</pre>

<p>If you change the radius, the peak amplitude 
of the output changes.  
The firmant generator is the "modified coupled form" of the formant generator,
developed by Max Mathews and Julius Smith in "Methods for Synthesizing Very High Q Parametrically
Well Behaved Two Pole Filters".
Here are some graphs showing the formant and firmant filtering white noise
as we sweep either the frequency or the radius:
</p>

<img class="indented" src="pix/formant.png" alt="various formant cases">

<!--
(with-sound (:channels 4 :clipped #f :statistics #t)
  (let* ((dur 100)
	 (samps (seconds->samples dur))
	 (flta (make-formant 100 .999))
	 (fltb (make-formant 5000 .1))
	 (fltc (make-firmant 100 .999))
	 (fltd (make-firmant 5000 .1))
	 (ampf (make-env '(0 0 1 1 100 1 101 0) :duration dur))
	 (frqf (make-env '(0 100 1 10000) :scaler (hz->radians 1.0) :duration dur))
	 (rf (make-env '(0 .6 1 .999) :base .01 :duration dur)))
       (do ((i 0 (+ i 1)))
	   ((= i samps))
	 (let* ((frq (env frqf))
		(r (env rf))
		(amp (env ampf))
		(pulse (- (random 2.0) 1.0)))
	   (outa i (* amp (formant flta pulse frq)))
	   (set! (mus-scaler fltb) r)
	   (outc i (* amp (formant fltb pulse)))
	   (outb i (* amp (firmant fltc pulse frq)))
	   (outd i (* amp (firmant fltd pulse)))
	   (set! (mus-scaler fltd) r)
	   ))))

(define (fixup-axes)
  (set! *selected-data-color* (make-color 0 0 0))
  (set! *selected-graph-color* (make-color 1 1 1))
  (set! (x-axis-label 0 0 0) "formant: sweep frequency from 100 to 10000")
  (set! (x-axis-label 0 1 0) "firmant: sweep frequency from 100 to 10000")
  (set! (x-axis-label 0 0 1) "formant radius: .999")
  (set! (x-axis-label 0 1 1) "firmant radius: .999")
  (set! (x-axis-label 0 2 0) "formant: sweep radius from .6 to .999")
  (set! (x-axis-label 0 3 0) "firmant: sweep radius from .6 to .999")
  (set! (x-axis-label 0 2 1) "formant frequency: 5000")
  (set! (x-axis-label 0 3 1) "firmant frequency: 5000"))
-->

<p>formant and firmant are often used to sculpt away unwanted spectral components, or emphasize formant regions.
In animals.scm, the crow, for example, 
</p>

<pre class="indented">
(load "animals.scm")
(with-sound (:play #t) (american-crow 0 .5))
</pre>

<p>has three formant filters.  Without them, it would sound like this:
</p>

<pre class="indented">
(with-sound (:play #t) (american-crow-no-formants 0 .5))
</pre>


<p>formant generators are also commonly used in a bank of filters to provide a sort of sample-by-sample spectrum.
An example is <a href="sndscm.html#fadedoc">fade.scm</a> which has various functions for frequency domain mixing.
See also 
<a href="sndscm.html#grapheq">grapheq</a> (a non-graphic equalizer), and
<a href="sndscm.html#crosssynthesis">cross-synthesis</a>.
Here's an example that moves a set of harmonically related formants through a sound.
If "radius" is .99, you get a glass-harmonica effect; if it's less, you get more of an FM index envelope effect.
</p>


<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (move-formants start file amp radius move-env num-formants)
  (let* ((frms (make-vector num-formants))
	 (beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> start))
	 (dur (<a class=quiet href="extsnd.html#mussoundframples">mus-sound-framples</a> file))
	 (end (+ beg dur))
	 (rd (<a class=quiet href="#make-readin">make-readin</a> file))
	 (menv (<a class=quiet href="#make-env">make-env</a> move-env :length dur)))
    (let ((start-frq (<a class=quiet href="#env">env</a> menv)))
      (do ((i 0 (+ i 1)))
	  ((= i num-formants))
	(set! (frms i) (<em class=red>make-formant</em> (* (+ i 1) start-frq) radius))))
    (do ((k beg (+ k 1)))
        ((= k end))
      (let ((frq (<a class=quiet href="#env">env</a> menv))
	    (sum 0.0)
	    (inp (<a class=quiet href="#readin">readin</a> rd)))
	(do ((i 0 (+ i 1)))
	    ((= i num-formants))
	  (set! sum (+ sum (<em class=red>formant</em> (frms i) inp))))
        (outa k (* amp sum))
	(do ((i 0 (+ i 1))
	     (curfrq frq (+ curfrq frq)))
	    ((= i num-formants))
	  (if (&lt; (* 2 curfrq) *clm-srate*)
	      (set! (<em class=red>mus-frequency</em> (frms i)) curfrq)))))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () 
  (move-formants 0 "oboe.snd" 2.0 0.99 '(0 1200 1.6 2400 2 1400) 4))
</pre>

<p>make-formant-bank creates a formant-bank generator, an array of formant generators that is summed in parallel. The
explicit do loop:
</p>

<pre class="indented">
(do ((sum 0.0)  ; say we have n formant generators in the formants vector, and we're passing each a signal x
     (i 0 (+ i 1)))
    ((= i n) sum)
  (set! sum (+ sum (formant (formants i) x))))
</pre>

<p>can be replaced with:
</p>

<pre class="indented">
(let ((fb (make-formant-bank formants)))
  ...
  (formant-bank fb x))
</pre>

<p>make-formant-bank takes a vector of formant generators as its first argument.  Its optional second argument
is a float-vector of gains (amplitudes) to scale each formant's contribution to the sum.  Similarly, formant-bank's
second argument is either a real number or a float-vector.  If a float-vector, each element is treated as the input to the
corresponding formant in the bank.  (formant-bank ignores its constituent formant generator's radius and frequency
after make-formant-bank; see move-formant above for a slightly less compact workaround if you want a bank of moving formants).
</p>


<br>
<p>The clm-3 formant gain calculation was incorrect.  To translate from the old
formant to the new one, multiply the old gain by (* 2 (sin (<a class=quiet href="#hztoradians">hz-&gt;radians</a> frequency))).
</p>

<p>If you change the radius or frequency rapidly, the formant generator will either produce
clicks or overflow, but firmant gives good output.   Here's an
example that puts formant on the edge of disaster (the glitch is about to explode), but firmant plugs away happily:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:channels 2)
  (let* ((samps (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> 3))
	 (flta (<em class=red>make-formant</em> 100 .999))
	 (fltc (<em class=red>make-firmant</em> 100 .999))
	 (vibosc (<a class=quiet href="#make-oscil">make-oscil</a> 10))
	 (index (<a class=quiet href="#hztoradians">hz-&gt;radians</a> 100))
	 (click (<a class=quiet href="#make-ncos">make-ncos</a> 40 500)))
    (do ((i 0 (+ i 1)))
        ((= i samps))
      (let ((vib (* index (+ 1 (<a class=quiet href="#oscil">oscil</a> vibosc))))
            (pulse (<a class=quiet href="#ncos">ncos</a> click)))
        (<a class=quiet href="#outa">outa</a> i (* 10 (<em class=red>formant</em> flta pulse vib)))
        (<a class=quiet href="#outa">outb</a> i (* 10 (<em class=red>firmant</em> fltc pulse vib)))))))
</pre>

<img class="indented" src="pix/firmant.png" alt="firmant is happy">





<!--  FILTERS  -->

<div class="innerheader" id="filterdoc">filter, iir-filter, fir-filter</div>

<pre class="indented">
 <em class=def id="make-filter">make-filter</em> order xcoeffs ycoeffs
 <em class=def id="filter">filter</em> fl inp 
 <em class=def id="filter?">filter?</em> fl

 <em class=def id="make-fir-filter">make-fir-filter</em> order xcoeffs
 <em class=def id="fir-filter">fir-filter</em> fl inp 
 <em class=def id="fir-filter?">fir-filter?</em> fl

 <em class=def id="make-iir-filter">make-iir-filter</em> order ycoeffs
 <em class=def id="iir-filter">iir-filter</em> fl inp 
 <em class=def id="iir-filter?">iir-filter?</em> fl

 <em class=def id="make-fir-coeffs">make-fir-coeffs</em> order v
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">general filter methods</td></tr>
<tr><td class="inner"><em class=gen>mus-order</em></td><td class="inner">filter order</td></tr>
<tr><td class="inner"><em class=gen>mus-xcoeff</em></td><td class="inner">x (input) coeff</td></tr>
<tr><td class="inner"><em class=gen>mus-xcoeffs</em></td><td class="inner">x (input) coeffs</td></tr>
<tr><td class="inner"><em class=gen>mus-ycoeff</em></td><td class="inner">y (output) coeff</td></tr>
<tr><td class="inner"><em class=gen>mus-ycoeffs</em></td><td class="inner">y (output) coeffs</td></tr>
<tr><td class="inner"><em class=gen>mus-data</em></td><td class="inner">current state (input values)</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">same as mus-order</td></tr>
</table>

<p>These are general FIR/IIR filters of arbitrary order.
The "order" argument is one greater than the nominal filter
order (it is the size of the coefficient array).
The filter generator might be defined:
</p>

<pre class="indented">
  (let ((xout 0.0))
    (set! (state 0) input)
    (do ((j (- order 1) (- j 1)))
        ((= j 0))
      (set! xout (+ xout (* (xcoeffs j) (state j))))
      (set! (state 0) (- (state 0) (* (ycoeffs j) (state j))))
      (set! (state j) (state (- j 1))))
    (+ xout (* (state 0) (xcoeffs 0))))
</pre>


<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((flt (make-iir-filter 3 (float-vector 0.0 -1.978 0.998)))
	(ran1 (make-rand 10000.0 0.002)))
    (do ((i 0 (+ i 1)))
	((= i 44100))
      (outa i (* 0.5 (iir-filter flt (rand ran1)))))))
</pre>
</div>
</td>

</tr><tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  flt = make_iir_filter(3, vct(0.0, -1.978, 0.998));
  ran1 = make_rand(10000.0, 0.002); 
  44100.times do |i|
    outa(i, 0.5 * iir_filter(flt, rand(ran1)), $output);
    end
  end.output
</pre>
</div>
</td>

</tr><tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  3 vct( 0.0 -1.978 0.998 ) make-iir-filter { flt }
  10000.0 0.002 make-rand { ran1 }
  44100 0 do
    i  flt  ran1 0 rand  iir-filter  f2/ *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>

<p><a href="sndscm.html#dspdoc">dsp.scm</a> has a number of filter design functions,
and various specializations of the filter generators, including such
perennial favorites as biquad, butterworth, hilbert transform, and
notch filters. Similarly, <a href="sndscm.html#analogfilterdoc">analog-filter.scm</a> has
the usual IIR suspects: Butterworth, Chebyshev, Bessel, and Elliptic filters.
A biquad section can be implemented as:
</p>

<pre class="indented">
(define (make-biquad a0 a1 a2 b1 b2) 
  (make-filter 3 (float-vector 0.0 b1 b2)))
</pre>

<p>
The Hilbert transform can be implemented with an fir-filter:
</p>

<pre class="indented">
(define* (make-hilbert-transform (len 30))
  (let* ((arrlen (+ 1 (* 2 len)))
         (arr (make-float-vector arrlen)))
    (do ((lim (if (even? len) len (+ 1 len)))
         (i (- len) (+ i 1)))
        ((= i lim))
      (let ((k (+ i len))
            (denom (* pi i))
            (num (- 1.0 (cos (* pi i)))))
        (set! (arr k) (if (or (= num 0.0) (= i 0)) 
                          0.0
                          (* (/ num denom) 
                             (+ .54 (* .46 (cos (/ (* i pi) len)))))))))
    (<em class=red>make-fir-filter</em> arrlen arr)))

(define hilbert-transform <em class=red>fir-filter</em>)
</pre>

<p>make-fir-coeffs translates a frequency response envelope (actually, evenly spaced points in a float-vector) into the corresponding FIR filter coefficients.
The order of the filter determines how close you
get to the envelope. 
</p>

<table class="method">
<tr><td class="methodtitle">Filters</td></tr>
<tr><td>
<blockquote><small>
lowpass filter: <a href="sndscm.html#makelowpass">make-lowpass</a> in dsp.scm<br>
highpass filter: <a href="sndscm.html#makehighpass">make-highpass</a> in dsp.scm<br>
bandpass filter: <a href="sndscm.html#makebandpass">make-bandpass</a> in dsp.scm<br>
bandstop filter: <a href="sndscm.html#makebandstop">make-bandstop</a> in dsp.scm<br>
Butterworth, Chebyshev, Bessel, Elliptic filters: <a href="sndscm.html#analogfilterdoc">analog-filter.scm</a><br>
Hilbert transform: <a href="sndscm.html#makehilberttransform">make-hilbert-transform</a> in dsp.scm<br>
differentiator: <a href="sndscm.html#makedifferentiator">make-differentiator</a> in dsp.scm<br>
block DC: dc-block in prc95.scm or (make-filter 2 (float-vector 1 -1) (float-vector 0 -0.99))<br>
hum elimination: <a href="sndscm.html#IIRfilters">make-eliminate-hum</a> and <a href="sndscm.html#notchchannel">notch-channel</a> in dsp.scm<br>
hiss elimination: <a href="sndscm.html#notchoutrumbleandhiss">notch-out-rumble-and-hiss</a><br>
smoothing filters: <a href="#moving-average">moving-average</a>, <a href="#weighted-moving-average">weighted-moving-average</a>, exponentially-weighted-moving-average<br>
notch-filters: <a href="sndscm.html#notchchannel">notch-channel</a> and <a href="sndscm.html#notchselection">notch-selection</a><br>
arbitrary spectrum via FIR filter: <a href="sndscm.html#spectrumtocoeffs">spectrum-&gt;coeffs</a> in dsp.scm<br>
invert an FIR filter: <a href="sndscm.html#invertfilter">invert-filter</a> in dsp.scm<br>
filtered echo sound effect: <a href="sndscm.html#zecho">flecho</a> in examp.scm<br>
time varying filter: fltit in examp.scm<br>
draw frequency response: use the <a href="snd.html#editenvelope">envelope editor</a> or <a href="snd.html#filtercontrol">filter control</a> in control panel<br>
Moog filter: <a href="sndscm.html#moogdoc">moog.scm</a><br>
Savitzky-Golay filter: <a href="sndscm.html#sgfilter">savitzky-golay-filter</a><br>
click reduction: <a href="sndscm.html#removeclicks">remove-clicks</a>, <a href="sndscm.html#cleanchannel">clean-channel</a><br>
graphical equalizer filter bank: <a href="sndscm.html#clminsdoc">graphEq</a><br>
nonlinear (Volterra) filter: <a href="sndscm.html#volterrafilter">volterra-filter</a><br>
Kalman filter: <a href="sndscm.html#kalmanfilterchannel">kalman-filter-channel</a><br>
filter a sound: <a href="extsnd.html#filtersound">filter-sound</a>, <a href="extsnd.html#filterchannel">filter-channel</a><br>
see also convolution, physical modeling, reverb, and <a href="sndscm.html#ssffts">fft-based filtering</a><br>
</small></blockquote>
</td></tr></table>




<!--  DELAY  -->

<div class="innerheader" id="delaydoc">delay, tap</div>

<pre class="indented">
<em class=def id="make-delay">make-delay</em> 
      size                  ; delay length
      initial-contents      ; delay line's initial values (a float-vector or a list)
      (initial-element 0.0) ; delay line's initial element
      max-size              ; maximum delay size in case the delay changes 
      type                  ; interpolation type
<em class=def id="delay">delay</em> d input (pm 0.0)
<em class=def id="delay?">delay?</em> d

<em class=def id="tap">tap</em> d (offset 0)
<em class=def id="tap?">tap?</em> d
<em class=def id="delaytick">delay-tick</em> d input
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">delay methods</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">length of delay</td></tr>
<tr><td class="inner"><em class=gen>mus-order</em></td><td class="inner">same as mus-length</td></tr>
<tr><td class="inner"><em class=gen>mus-data</em></td><td class="inner">delay line itself (no set!)</td></tr>
<tr><td class="inner"><em class=gen>mus-interp-type</em></td><td class="inner">interpolation choice (no set!)</td></tr>
<tr><td class="inner"><em class=gen>mus-scaler</em></td><td class="inner">available for delay specializations</td></tr>
<tr><td class="inner"><em class=gen>mus-location</em></td><td class="inner">current delay line write position</td></tr>
</table>

<p>The delay generator is a delay line.  
The make-delay "size" argument sets the delay line length (in samples).
Input fed into a delay line reappears at the output size samples later. 
If "max-size" is specified in make-delay,
and it is larger than "size", the delay line can provide varying-length delays (including fractional amounts).
The delay generator's "pm" argument determines how far from the original "size" we are; that is,
it is difference between the length set by make-delay
and the current actual delay length, size + pm.  So, a positive "pm" corresponds to a longer
delay line.  See <a href="sndscm.html#zecho">zecho</a> in examp.scm for an example.
The make-delay "type" argument sets the interpolation type in the case of fractional delays:
mus-interp-none, mus-interp-linear, mus-interp-all-pass, 
mus-interp-lagrange, mus-interp-bezier, or mus-interp-hermite.
Delay could be defined:
</p>

<pre class="indented">
(let ((result (<a class=quiet href="#array-interp">array-interp</a> line (- loc pm))))
  (set! (line loc) input)
  (set! loc (+ 1 loc))
  (if (&lt;= size loc) (set! loc 0))
  result)
</pre>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((dly (make-delay (seconds-&gt;samples 0.5)))
        (osc1 (make-oscil 440.0))
        (osc2 (make-oscil 660.0)))
    (do ((i 0 (+ i 1)))
        ((= i 44100))
      (outa i (* 0.5 
                 (+ (oscil osc1)
                    (delay dly (oscil osc2))))))))
</pre>
</div>
</td>
</tr><tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  dly = make_delay(seconds2samples(0.5));
  osc1 = make_oscil(440.0);
  osc2 = make_oscil(660.0);
  44100.times do |i|
    outa(i, 
         0.5 * (oscil(osc1) + 
                delay(dly, oscil(osc2))), 
         $output);
    end
  end.output
</pre>
</div>
</td>
</tr><tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  0.5 seconds-&gt;samples make-delay { dly }
  440.0 make-oscil { osc1 }
  660.0 make-oscil { osc2 }
  44100 0 do
    i
    osc1 0 0 oscil
    dly  osc2 0 0 oscil  0 delay f+
    f2/ *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>

<p>
The tap function taps a delay line at a given offset from the output point.
delay-tick is a function that just puts a sample in the delay line, 'ticks' the delay forward, and
returns its "input" argument.  
See prc95.scm for examples of both of these functions.
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (echo beg dur scaler secs file)
  (let ((del (<em class=red>make-delay</em> (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> secs)))
        (rd (make-sampler 0 file)))
    (do ((i beg (+ i 1)))
        ((= i (+ beg dur)))
      (let ((inval (rd)))
        (<a class=quiet href="#outa">outa</a> i (+ inval (<em class=red>delay</em> del (* scaler (+ (<em class=red>tap</em> del) inval)))))))))

(<a class=quiet href="sndscm.html#withsound">with-sound</a> () (echo 0 60000 .5 1.0 "pistol.snd"))
</pre>

<p>The <a href="#mus-scaler">mus-scaler</a> field is available for simple extensions of the delay.  For example,
the <a href="#moving-max">moving-max</a> generator uses mus-scaler to track the current maximum sample value
in the delay line; the result is an envelope that tracks the peak amplitude in the
last "size" samples.
The <a href="#mus-location">mus-location</a> field returns the current delay line write position.
To access the delay line contents as a sliding window on the input data, use:
</p>

<pre class="indented">
(define (delay-ref dly loc)
  (float-vector-ref (mus-data dly) (modulo (+ loc (<em class=red>mus-location</em> dly)) (mus-length dly))))
</pre>

<p>
The delay generator is used in some reverbs (<a href="sndscm.html#nrev">nrev</a>), many physical
models (<a href="sndscm.html#stereoflute">stereo-flute</a>), <a href="sndscm.html#dlocsigdoc">dlocsig</a>,
chorus effects (<a href="sndscm.html#chorus">chorus</a> in dsp.scm), and flanging (<a href="sndscm.html#neweffectsdoc">new-effects</a>),
and is the basis for about a dozen extensions (comb and friends below).
</p>




<!--  COMB, NOTCH  -->

<div class="innerheader" id="combdoc">comb, notch</div>

<pre class="indented">
<em class=def id="make-comb">make-comb</em> (scaler 1.0) size initial-contents (initial-element 0.0) max-size
<em class=def id="comb">comb</em> cflt input (pm 0.0)
<em class=def id="comb?">comb?</em> cflt

<em class=def id="combbank">comb-bank</em> combs input
<em class=def id="combbankp">comb-bank?</em> object
<em class=def id="makecombbank">make-comb-bank</em> combs

<em class=def id="make-filtered-comb">make-filtered-comb</em> (scaler 1.0) size initial-contents (initial-element 0.0) max-size filter
<em class=def id="filtered-comb">filtered-comb</em> cflt input (pm 0.0)
<em class=def id="filtered-comb?">filtered-comb?</em> cflt

<em class=def id="filteredcombbank">filtered-comb-bank</em> fcombs input
<em class=def id="filteredcombbankp">filtered-comb-bank?</em> object
<em class=def id="makefilteredcombbank">make-filtered-comb-bank</em> fcombs

<em class=def id="make-notch">make-notch</em> (scaler 1.0) size initial-contents (initial-element 0.0) max-size
<em class=def id="notch">notch</em> cflt input (pm 0.0)
<em class=def id="notch?">notch?</em> cflt
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">comb, filtered-comb, and notch methods</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">length of delay</td></tr>
<tr><td class="inner"><em class=gen>mus-order</em></td><td class="inner">same as mus-length</td></tr>
<tr><td class="inner"><em class=gen>mus-data</em></td><td class="inner">delay line itself (no set!)</td></tr>
<tr><td class="inner"><em class=gen>mus-feedback</em></td><td class="inner">scaler (comb only)</td></tr>
<tr><td class="inner"><em class=gen>mus-feedforward</em></td><td class="inner">scaler (notch only)</td></tr>
<tr><td class="inner"><em class=gen>mus-interp-type</em></td><td class="inner">interpolation choice (no set!)</td></tr>
</table>

<p>The comb generator is a delay line with a scaler on the feedback.  notch
is a delay line with a scaler on the current input.
filtered-comb is a comb filter with a filter on the feedback.  
Although normally this is a <a href="#one-zero">one-zero</a> filter, it can be any CLM generator.
The make-&lt;gen&gt; "size" argument sets the length
in samples of the delay line,
and the other arguments are also handled as in <a href="#delay">delay</a>.
</p>

<pre class="indented">
comb:           y(n) = x(n - size) + scaler * y(n - size)
notch:          y(n) = x(n) * scaler  + x(n - size)
filtered-comb:  y(n) = x(n - size) + scaler * filter(y(n - size))
</pre>

<img class="indented" src="pix/comb.png" alt="sonogram of comb">

<!-- 1024 blackman2 dB jet light=1 data-cutoff around .009 invert off using the local zc (not clm-ins!): (with-sound (:srate 44100) (zc 0 2 2000 .1 100 1000 .99))
-->


<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((cmb (make-comb 0.4 (seconds-&gt;samples 0.4)))
        (osc (make-oscil 440.0))
        (ampf (make-env '(0 0 1 1 2 1 3 0) :length 4410)))
    (do ((i 0 (+ i 1)))
	((= i 88200))
      (outa i (* 0.5 (comb cmb (* (env ampf) (oscil osc))))))))
</pre>
</div>
</td>

</tr><tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  cmb = make_comb(0.4, seconds2samples(0.4));
  osc = make_oscil(440.0);
  ampf = make_env([0.0, 0.0, 1.0, 1.0, 2.0, 1.0, 3.0, 0.0], :length, 4410);
  88200.times do |i|
    outa(i, 0.5 * (comb(cmb, env(ampf) * oscil(osc))), $output);
    end
  end.output
</pre>
</div>
</td>

</tr><tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  0.4 0.4 seconds-&gt;samples make-comb { cmb }
  440.0 make-oscil { osc }
  '( 0 0 1 1 2 1 3 0 ) :length 4410 make-env { ampf }
  88200 0 do
    i
    cmb ( gen )
    ampf env  osc 0 0 oscil  f* ( val )
    0 ( pm )
    comb f2/ *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>

<p>As a rule of thumb, the decay time of the feedback is
7.0 * size / (1.0 - scaler) samples, so to get a decay of feedback-dur seconds,
</p>
<pre class="indented">
    (make-comb :size size :scaler (- 1.0 (/ (* 7.0 size) feedback-dur *clm-srate*)))
</pre>

<p>The peak gain is 1.0 / (1.0 - (abs scaler)).  The peaks (or valleys in notch's case) are evenly spaced
at *clm-srate* / size. The height (or depth) thereof is determined by scaler &mdash;
the closer to 1.0 it is, the more pronounced the dips or peaks.
See Julius Smith's "An Introduction to Digital Filter Theory" in
Strawn "Digital Audio Signal Processing", or Smith's "Music Applications of
Digital Waveguides".
The following instrument sweeps the comb filter using the pm argument:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (zc time dur freq amp length1 length2 feedback)
  (let* ((beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> time))
         (end (+ beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
         (s (<a class=quiet href="#make-pulse-train">make-pulse-train</a> :frequency freq))  ; some raspy input so we can hear the effect easily
         (d0 (<em class=red>make-comb</em> :size length1 :max-size (max length1 length2) :scaler feedback))
         (aenv (<a class=quiet href="#make-env">make-env</a> '(0 0 .1 1 .9 1 1 0) :scaler amp :duration dur))
         (zenv (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1) :scaler (- length2 length1) :base 12.0 :duration dur)))
     (do ((i beg (+ i 1))) ((= i end))
       (<a class=quiet href="#outa">outa</a> i (* (<a class=quiet href="#env">env</a> aenv) (<em class=red>comb</em> d0 (<a class=quiet href="#pulse-train">pulse-train</a> s) (<a class=quiet href="#env">env</a> zenv)))))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () 
  (zc 0 3 100 .1 20 100 .5) 
  (zc 3.5 3 100 .1 90 100 .95))
</pre>

<p>Nearly every actual use of comb filters involves a bank of them, a vector of combs
summed in parallel.  The comb-bank generator is intended for this kind of application.
make-comb-bank takes a vector of combs and returns the comb-bank generator which can
be called via comb-bank.
</p>

<pre class="indented">
(do ((sum 0.0)
     (i 0 (+ i 1)))
    ((= i n) sum)
  (set! sum (+ sum (comb (combs i) x))))
</pre>

<p>can be replaced with:
</p>

<pre class="indented">
(let ((cb (make-comb-bank combs)))
  ...
  (comb-bank cb x))
</pre>


<p>The comb filter can produce some nice effects; here's one that treats the comb filter's
delay line as the coefficients for an FIR filter:
</p>

<pre class="indented">
(define (fir+comb beg dur freq amp size)
  (let* ((start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
         (end (+ start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
         (dly (<em class=red>make-comb</em> :scaler .9 :size size)) 
         (flt (<a class=quiet href="#make-fir-filter">make-fir-filter</a> :order size :xcoeffs (<em class=red>mus-data</em> dly))) ; comb delay line as FIR coeffs
         (r (<a class=quiet href="#make-rand">make-rand</a> freq)))                                       ; feed comb with white noise
    (do ((i start (+ i 1))) 
        ((= i end)) 
      (<a class=quiet href="#outa">outa</a> i (* amp (<a class=quiet href="#fir-filter">fir-filter</a> flt (<em class=red>comb</em> dly (<a class=quiet href="#rand">rand</a> r))))))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () 
  (fir+comb 0 2 10000 .001 200)
  (fir+comb 2 2 1000 .0005 400)
  (fir+comb 4 2 3000 .001 300)
  (fir+comb 6 2 3000 .0005 1000))
</pre>

<p>Here's another that fluctuates between two sets of combs; it usually works best with voice sounds.  We use comb-bank generators:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (flux start-time file frequency combs0 combs1 (scaler 0.99) (comb-len 32))
  (let* ((beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> start-time))
         (end (+ beg (<a class=quiet href="extsnd.html#mussoundframples">mus-sound-framples</a> file)))
         (num-combs0 (length combs0))
         (num-combs1 (length combs1))
         (cmbs0 (make-vector num-combs0))
         (cmbs1 (make-vector num-combs1))
         (osc (<a class=quiet href="#make-oscil">make-oscil</a> frequency))
         (rd (<a class=quiet href="#make-readin">make-readin</a> file)))
    (do ((k 0 (+ k 1)))
        ((= k num-combs0))
      (set! (cmbs0 k)
            (<em class=red>make-comb</em> scaler 
              (floor (* comb-len (combs0 k))))))
    (do ((k 0 (+ k 1)))
        ((= k num-combs1))
      (set! (cmbs1 k)
            (<em class=red>make-comb</em> scaler 
              (floor (* comb-len (combs1 k))))))
    (let ((nc0 (<em class=red>make-comb-bank</em> cmbs0))
          (nc1 (<em class=red>make-comb-bank</em> cmbs1)))
      (do ((i beg (+ i 1)))
          ((= i end))
        (let ((interp (<a class=quiet href="#oscil">oscil</a> osc))
              (x (<a class=quiet href="#readin">readin</a> rd)))
          (<a class=quiet href="#outa">outa</a> i (+ (* interp (<em class=red>comb-bank</em> nc0 x)) 
                     (* (- 1.0 interp) (<em class=red>comb-bank</em> nc1 x)))))))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:scaled-to .5) 
  (flux 0 "oboe.snd" 10.0 '(1.0 1.25 1.5) '(1.0 1.333 1.6)) ; bowed oboe?
  (flux 2 "now.snd" 4.0 '(1.0 1.25 1.5) '(1.0 1.333 1.6 2.0 3.0))
  (flux 4 "now.snd" 1.0 '(1.0 1.25 1.5) '(1.0 1.333 1.6 2.0 3.0) 0.995 20)
  (flux 6 "now.snd" 10.0 '(1.0 1.25 1.5) '(1.0 1.333 1.6 2.0 3.0) 0.99 10)
  (flux 8 "now.snd" 10.0 '(2.0) '(1.0 1.333 1.6 2.0 3.0) 0.99 120)
  (flux 10 "fyow.snd" .50 '(1.0 2.0 1.5) '(1.0 1.333 1.6 2.0 3.0) 0.99 120))
</pre>

<p>For more comb filter examples,
see examp.scm, <a href="sndscm.html#chordalize">chordalize</a> in dsp.scm, or
any of the standard reverbs such as <a href="sndscm.html#nrev">nrev</a>.
</p>

<br> 
<p>filtered-comb is used in <a href="sndscm.html#freeverb">freeverb</a>
where a <a href="#one-zero">one-zero</a> filter is placed
in the feedback loop:
</p>

<pre class="indented">
(make-filtered-comb :size len :scaler room-decay-val :filter (make-one-zero :a0 (- 1.0 dmp) :a1 dmp))
</pre>

<p>As with the normal comb filter, the filtered-comb-bank generator sums a vector of filtered-comb
generators in parallel.
</p>




<!--  ALL-PASS  -->

<div class="innerheader" id="all-passdoc">all-pass</div>

<pre class="indented">
<em class=def id="make-all-pass">make-all-pass</em> 
        (feedback 0.0) 
        (feedforward 0.0)
        size 
        initial-contents 
        (initial-element 0.0) 
        max-size

<em class=def id="all-pass">all-pass</em> f input (pm 0.0)
<em class=def id="all-pass?">all-pass?</em> f

<em class=def id="allpassbank">all-pass-bank</em> all-passes input
<em class=def id="allpassbankp">all-pass-bank?</em> object
<em class=def id="makeallpassbank">make-all-pass-bank</em> all-passes

<em class=def id="make-one-pole-all-pass">make-one-pole-all-pass</em> size coeff
<em class=def id="one-pole-all-pass">one-pole-all-pass</em> f input 
<em class=def id="one-pole-all-pass?">one-pole-all-pass?</em> f
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">all-pass methods</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">length of delay</td></tr>
<tr><td class="inner"><em class=gen>mus-order</em></td><td class="inner">same as mus-length</td></tr>
<tr><td class="inner"><em class=gen>mus-data</em></td><td class="inner">delay line itself (no set!)</td></tr>
<tr><td class="inner"><em class=gen>mus-feedback</em></td><td class="inner">feedback scaler</td></tr>
<tr><td class="inner"><em class=gen>mus-feedforward</em></td><td class="inner">feedforward scaler</td></tr>
<tr><td class="inner"><em class=gen>mus-interp-type</em></td><td class="inner">interpolation choice (no set!)</td></tr>
</table>

<p>The all-pass or moving average comb generator is just like <a href="#comb">comb</a> but with
an added scaler on the input ("feedforward" is Julius Smith's suggested name for it).  If feedforward is 0.0, we get a
comb filter.  If both scale terms are 0.0, we get a pure delay line. 
</p>

<pre class="indented">
y(n) = feedforward * x(n) + x(n - size) + feedback * y(n - size)
</pre>


<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((alp (make-all-pass -0.4 0.4 (seconds-&gt;samples 0.4)))
        (osc (make-oscil 440.0))
        (ampf (make-env '(0 0 1 1 2 1 3 0) :length 4410)))
    (do ((i 0 (+ i 1)))
        ((= i 88200))
      (outa i (* 0.5 (all-pass alp (* (env ampf) (oscil osc))))))))
</pre>
</div>
</td>
</tr>
<tr>
<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  alp = make_all_pass(-0.4, 0.4, seconds2samples(0.4));
  osc = make_oscil(440.0);
  ampf = make_env([0.0, 0.0, 1.0, 1.0, 2.0, 1.0, 3.0, 0.0], :length, 4410);
  88200.times do |i|
    outa(i, 0.5 * (all_pass(alp, env(ampf) * oscil(osc))), $output);
    end
  end.output
</pre>
</div>
</td>
</tr>

<tr>
<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  -0.4 0.4 0.4 seconds-&gt;samples make-all-pass { alp }
  440.0 make-oscil { osc }
  '( 0 0 1 1 2 1 3 0 ) :length 4410 make-env { ampf }
  88200 0 do
    i
    alp ( gen )
    ampf env  osc 0 0 oscil  f* ( val )
    0 ( pm )
    all-pass f2/ *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>

</tr>
</table>


<p>all-pass filters are used extensively in reverberation; 
see <a href="sndscm.html#jcrevdoc">jcrev</a> or <a href="sndscm.html#nrev">nrev</a>.
To get the "all-pass" behavior, set feedback equal to -feedforward. Here's an example
(based on John Chowning's ancient reverb) that was inspired by the bleed-through you get on
old analog tapes &mdash; the reverb slightly precedes the direct signal:
</p>

<pre class="indented">
(define (later file dly rev)
  (let ((allpass1 (<em class=red>make-all-pass</em> -0.700 0.700 1051))
        (allpass2 (<em class=red>make-all-pass</em> -0.700 0.700  337))
        (allpass3 (<em class=red>make-all-pass</em> -0.700 0.700  113))
        (comb1 (make-comb 0.742 4799))
        (comb2 (make-comb 0.733 4999))
        (comb3 (make-comb 0.715 5399))
        (comb4 (make-comb 0.697 5801))
        (len (floor (+ *clm-srate* (mus-sound-framples file))))
        (rd (make-readin file))  ; the direct signal (via sound-let below)
        (d (make-delay dly)))    ; this delays the direct signal
    (do ((backup (min 4799 dly))
         (i 0 (+ i 1)))
        ((= i len))
      (let* ((inval (readin rd))
             (allpass-sum (<em class=red>all-pass</em> allpass3 
                            (<em class=red>all-pass</em> allpass2 
                              (<em class=red>all-pass</em> allpass1 
                                (* rev inval)))))
             (comb-sum 
              (+ (comb comb1 allpass-sum)
                 (comb comb2 allpass-sum)
                 (comb comb3 allpass-sum)
                 (comb comb4 allpass-sum)))
             (orig (delay d inval)))  
        (if (&gt;= i backup)
            (outa (- i backup) (+ comb-sum orig)))))))

(with-sound () 
  (sound-let ((tmp () (fm-violin 0 .1 440 .1))) 
    (later tmp 10000 .1)))
</pre>

<p>In all such applications, the all-pass filters are connected in series (each one's output is the
input to the next in the set).  To package this up in one generator, use an all-pass-bank.  An
all-pass-bank is slightly different from the other "bank" generators in that it connects the
vector of all-passes in series, rather than summing them in parallel.
Code of the form:
</p>

<pre class="indented">
(all-pass a1 (all-pass a2 input))
</pre>

<p>can be replaced with:
</p>

<pre class="indented">
(all-pass-bank (make-all-pass-bank (vector a1 a2)) input)
</pre>


<p>one-pole-all-pass is used by piano.scm:
</p>

<pre class="indented">
y(n) = x(n) + coeff * (y(n-1) - y(n))
x(n) = y(n-1)
</pre>

<p>This is repeated "size" times, with the generator input as the first y(n-1) value.
</p>




<!--  MOVING-AVERAGE. MOVING-MAX. MOVING-NORM.  -->

<div class="innerheader" id="moving-averagedoc">moving-average, moving-max, moving-norm</div>

<pre class="indented">
<em class=def id="make-moving-average">make-moving-average</em> size initial-contents (initial-element 0.0)
<em class=def id="moving-average">moving-average</em> f input
<em class=def id="moving-average?">moving-average?</em> f

<em class=def id="make-moving-max">make-moving-max</em> size initial-contents (initial-element 0.0)
<em class=def id="moving-max">moving-max</em> f input
<em class=def id="moving-max?">moving-max?</em> f

<em class=def id="make-moving-norm">make-moving-norm</em> size (scaler 1.0)
<em class=def id="moving-norm">moving-norm</em> f input
<em class=def id="moving-norm?">moving-norm?</em> f
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">moving-average methods</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">length of table</td></tr>
<tr><td class="inner"><em class=gen>mus-order</em></td><td class="inner">same as mus-length</td></tr>
<tr><td class="inner"><em class=gen>mus-data</em></td><td class="inner">table of last 'size' values</td></tr>
</table>

<p>The moving-average or moving window average generator returns the average of the last "size" values input to it.
</p>

<pre class="indented">
result = sum-of-last-n-inputs / n
</pre>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((avg (make-moving-average 4410))
	(osc (make-oscil 440.0))
	(stop (- 44100 4410)))
    (do ((i 0 (+ i 1)))
	((= i stop))
      (let ((val (oscil osc)))
	(outa i (* val (moving-average avg (abs val))))))
    (do ((i stop (+ i 1)))
	((= i 44100))
      (outa i (* (oscil osc) (moving-average avg 0.0))))))
</pre>
</div>
</td>

</tr><tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  avg = make_moving_average(4410);
  osc = make_oscil(440.0);
  stop = 44100 - 4410;
  stop.times do |i|
    val = oscil(osc);
    outa(i, val * moving_average(avg, val.abs), $output);
    end
  4410.times do |i|
    outa(stop + i, oscil(osc) * moving_average(avg, 0.0), $output);
    end
  end.output</pre>
</div>
</td>

</tr><tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  4410 make-moving-average { avg }
  440.0 make-oscil { osc }
  44100 4410 - { stop }
  0.0 { val }
  stop 0 do
    osc 0 0 oscil to val
    i  avg val fabs moving-average  val f* *output* outa drop
  loop
  44100 stop do
    i  avg 0.0 moving-average  osc 0 0 oscil f*  *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>

<p>
moving-average is used both to track rms values and to generate ramps between 0 and 1 in a "gate"
effect in new-effects.scm and in rms-envelope in env.scm.  It can also be viewed as a low-pass filter.
And 
in <a href="sndscm.html#soundstosegmentdata">sounds-&gt;segment-data</a> in examp.scm, it is used to segment a sound library.
Here is an example (from new-effects.scm) that implements a "squelch" effect,
throwing away any samples below a threshhold, and ramping between portions
that are squelched and those that are unchanged (to avoid clicks):
</p>

<pre class="indented">
(define (squelch-channel amount snd chn gate-size)  ; gate-size = ramp length and rms window length
  (let ((gate (<em class=red>make-moving-average</em> gate-size))
        (ramp (<em class=red>make-moving-average</em> gate-size :initial-element 1.0)))
    (<a class=quiet href="extsnd.html#mapchannel">map-channel</a> (lambda (y) 
                   (* y (<em class=red>moving-average</em> ramp                           ; ramp between 0 and 1
                          (if (&lt; (<em class=red>moving-average</em> gate (* y y)) amount) ; local (r)ms value
                              0.0                               ; below "amount" so squelch
                            1.0))))
                 0 #f snd chn)))
</pre>

<p>
moving-max is a specialization
of the <a href="#delay">delay</a> generator; it produces an envelope that tracks the peak amplitude of the last 'n' samples.
<code>(make-moving-max 256)</code> returns the generator (this one's window size is 256),
and <code>(moving-max gen y)</code> then returns the envelope traced out by the signal 'y'.
The <a href="sndscm.html#harmonicizer">harmonicizer</a> uses this generator to normalize an in-coming signal to 1.0
so that the Chebyshev polynomials it is driving will produce a full spectrum at all times.
Here is a similar, but simpler, example; we use the moving-max generator to track the
current peak amplitude over a small window, use that value to drive a <a href="#contrast-enhancement">contrast-enhancement</a>
generator (so that its output is always fully modulated), and rescale by the same value
upon output (to track the original sound's amplitude envelope):
</p>

<pre class="indented">
(define (intensify index)
  (let ((mx (<em class=red>make-moving-max</em>))
        (flt (<a class=quiet href="sndscm.html#makelowpass">make-lowpass</a> (* pi .1) 8))) ; smooth the maxamp signal
    (<a class=quiet href="extsnd.html#mapchannel">map-channel</a> (lambda (y)
                   (let ((amp (max .1 (<a class=quiet href="#fir-filter">fir-filter</a> flt (<em class=red>moving-max</em> mx y)))))
                     (* amp (<a class=quiet href="#contrast-enhancement">contrast-enhancement</a> (/ y amp) index)))))))
</pre>

<p>moving-norm specializes moving-max to provide automatic gain control.  It is essentially a one-pole (low-pass)
filter on the output of moving-max, inverted and multiplied by a scaler.  <code>(* input-signal (moving-norm g input-signal))</code>
is the normal usage.
</p>

<p>
See generators.scm for several related functions:
<a href="#moving-rms">moving-rms</a>, <a href="#moving-sum">moving-sum</a>, 
<a href="#moving-length">moving-length</a>, <a href="#weighted-moving-average">weighted-moving-average</a>, and 
<a href="#exponentially-weighted-moving-average">exponentially-weighted-moving-average</a>
(the latter being just a one-pole filter).
</p>




<!--  SRC  -->

<div class="innerheader" id="srcdoc">src</div>

<pre class="indented">
<em class=def id="make-src">make-src</em> input (srate 1.0) (width 5)
<em class=def id="src">src</em> s (sr-change 0.0)
<em class=def id="src?">src?</em> s
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">src methods</td></tr>
<tr><td class="inner"><em class=gen>mus-increment</em></td><td class="inner">srate arg to make-src</td></tr>
</table>

<p>The src generator performs sampling rate conversion
by convolving its input with a sinc
function.
make-src's "srate" argument is the
ratio between the old sampling rate and the new;  an srate of 2 causes the sound to be half as long, transposed up an octave.
</p>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t :srate 22050)
  (let* ((rd (make-readin "oboe.snd"))
         (len (* 2 (mus-sound-framples "oboe.snd")))
         (sr (make-src rd 0.5)))
    (do ((i 0 (+ i 1)))
        ((= i len))
      (outa i (src sr)))))
</pre>
</div>
</td>
</tr>
<tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true, :srate, 22050) do
  rd = make_readin("oboe.snd");
  len = 2 * mus_sound_framples("oboe.snd");
  sr = make_src(lambda do |dir| 
                 readin(rd) end, 0.5);
  len.times do |i|
    outa(i, src(sr), $output);
    end
  end.output
</pre>
</div>
</td>
</tr>
<tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  "oboe.snd" make-readin { rd }
  rd 0.5 make-src { sr }
  "oboe.snd" mus-sound-framples 2* ( len ) 0 do
    i  sr 0 #f src  *output* outa drop
  loop
; :play #t :srate 22050 with-sound drop
</pre>
</div>
</td>
</tr>
</table>


<p>
The "width" argument sets how many neighboring samples to convolve with the sinc function.
If you hear high-frequency artifacts in the conversion, try increasing this number;
Perry Cook's default value is 40, and I've seen cases where it needs to be 100.
It can also be set as low as 2 in some cases.
The greater the width, the slower the src generator runs.
</p>

<p>
The src generator's "sr-change"
argument is the amount to add to the current srate on a sample by sample
basis (if it's 0.0 and the original make-src srate argument was also 0.0, you get a constant output because the generator is not moving at all).  
Here's
an instrument that provides time-varying sampling rate conversion:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (simple-src start-time duration amp srt srt-env filename)
  (let* ((senv (<a class=quiet href="#make-env">make-env</a> srt-env :duration duration))
         (beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> start-time))
         (end (+ beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> duration)))
         (src-gen (<em class=red>make-src</em> :input (<a class=quiet href="#make-readin">make-readin</a> filename) :srate srt)))
     (do ((i beg (+ i 1)))
         ((= i end))
       (<a class=quiet href="#outa">outa</a> i (* amp (<em class=red>src</em> src-gen (<a class=quiet href="#env">env</a> senv)))))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () (simple-src 0 4 1.0 0.5 '(0 1 1 2) "oboe.snd"))
</pre>

<p id="srcer">src can provide an all-purpose "Forbidden Planet" sound effect:</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (srcer start-time duration amp srt fmamp fmfreq filename)
  (let* ((os (<a class=quiet href="#make-oscil">make-oscil</a> fmfreq))
         (beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> start-time))
         (end (+ beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> duration)))
         (src-gen (<em class=red>make-src</em> :input (<a class=quiet href="#make-readin">make-readin</a> filename) :srate srt)))
     (do ((i beg (+ i 1)))
         ((= i end))
       (<a class=quiet href="#outa">outa</a> i (* amp (<em class=red>src</em> src-gen (* fmamp (<a class=quiet href="#oscil">oscil</a> os))))))))

(<a class=quiet href="sndscm.html#withsound">with-sound</a> () (srcer 0 2 1.0   1 .3 20 "fyow.snd"))   
(<a class=quiet href="sndscm.html#withsound">with-sound</a> () (srcer 0 25 10.0   .01 1 10 "fyow.snd"))
(<a class=quiet href="sndscm.html#withsound">with-sound</a> () (srcer 0 2 1.0   .9 .05 60 "oboe.snd")) 
(<a class=quiet href="sndscm.html#withsound">with-sound</a> () (srcer 0 2 1.0   1.0 .5 124 "oboe.snd"))
(<a class=quiet href="sndscm.html#withsound">with-sound</a> () (srcer 0 2 10.0   .01 .2 8 "oboe.snd"))
(<a class=quiet href="sndscm.html#withsound">with-sound</a> () (srcer 0 2 1.0   1 3 20 "oboe.snd"))    
</pre>

<p>The "input" argument to make-src and the "input-function" argument
to src provide the generator with input as it is needed. 
The input function
is a function of one argument (the desired read direction, if the reader can support it), that is called each time src needs another
sample of input. Here's an example instrument that reads a file with an envelope on the src:
</p>

<pre class="indented">
(definstrument (src-change filename start-time duration file-start srcenv)
  (let* ((beg (seconds-&gt;samples start-time))
         (end (+ beg (seconds-&gt;samples duration)))
	 (loc (seconds-&gt;samples file-start))
         (src-gen (make-src :srate 0.0))
	 (e (make-env srcenv :duration duration))
	 (inp (make-file-&gt;sample filename)))
    (do ((i beg (+ i 1)))
        ((= i end))
      (outa i (src src-gen (env e) 
	        (<em class=red>lambda (dir)</em>  ; our input function
		  (set! loc (+ loc dir))
		  (ina loc inp)))))))

;;; (with-sound () (src-change "pistol.snd" 0 2 0 '(0 0.5 1 -1.5)))
</pre>

<p>
If you jump around in the input (via mus-location for example), use
<a href="#mus-reset">mus-reset</a> to clear out any lingering state before starting to read at
the new position. (src, like many other generators, has an internal buffer
of recently read samples, so a sudden jump to a new location will otherwise cause
a click).
</p>

<p>There are several other ways to resample a sound.  Some of the more interesting ones are in
dsp.scm (<a href="sndscm.html#downoct">down-oct</a>, <a href="sndscm.html#soundinterp">sound-interp</a>, 
<a href="sndscm.html#linearsrcchannel">linear-src</a>, etc).  To calculate a sound's new duration after
a time-varying src is applied, use <a href="sndscm.html#srcduration">src-duration</a>.  To scale an src
envelope so that the result has a given duration, use <a href="sndscm.html#srcfitenvelope">scr-fit-envelope</a>.
</p>





<!--  CONVOLVE  -->

<div class="innerheader" id="convolvedoc">convolve</div>

<pre class="indented">
<em class=def id="make-convolve">make-convolve</em> input filter fft-size filter-size
<em class=def id="convolve">convolve</em> gen
<em class=def id="convolve?">convolve?</em> gen

<em class=def id="convolvefiles">convolve-files</em> file1 file2 (maxamp 1.0) (output-file "tmp.snd")
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">convolve methods</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">fft size used in the convolution</td></tr>
</table>

<p>The convolve generator convolves its input with the impulse response "filter" (a float-vector).
"input" is a function of one argument that is
called whenever convolve needs input.
</p>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t :statistics #t)
  (let ((cnv (make-convolve 
              (make-readin "pistol.snd")
              (samples 0 (framples "pistol.snd") "oboe.snd"))))
    (do ((i 0 (+ i 1)))
	((= i 88200))
      (outa i (* 0.25 (convolve cnv))))))
</pre>
</div>
</td>
</tr>
<tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true, :statistics, true) do
  rd = make_readin("oboe.snd");
  flt = file2vct("pistol.snd"); # examp.rb
  cnv = make_convolve(lambda { |dir| readin(rd)}, flt);
  88200.times do |i|
    outa(i, 0.25 * convolve(cnv), $output);
    end
  end.output
</pre>
</div>
</td>
</tr>
<tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  "pistol.snd" make-readin ( rd )
  "oboe.snd" file-&gt;vct ( v ) make-convolve { cnv }
  88200 0 do
    i  cnv #f convolve  0.25 f* *output* outa drop
  loop
; :play #t :statistics #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let* ((tempfile (convolve-files "oboe.snd" 
  		   		   "pistol.snd" 0.5 
				   "convolved.snd"))
	 (len (mus-sound-framples tempfile))
	 (reader (make-readin tempfile)))
    (do ((i 0 (+ i 1)))
	((= i len))
      (outa i (readin reader)))
    (delete-file tempfile)))
</pre>
</div>
</td>
</tr>
<tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  tempfile = convolve_files("oboe.snd", 
  	                    "pistol.snd", 0.5, 
			    "convolved.snd");
  len = mus_sound_framples(tempfile);
  reader = make_readin(tempfile);
  len.times do |i|
    outa(i, readin(reader), $output);
    end
  File.unlink(tempfile)
  end.output
</pre>
</div>
</td>
</tr>
<tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  "oboe.snd" "pistol.snd" 0.5 "convolved.snd" convolve-files { tempfile }
  tempfile make-readin { reader }
  tempfile mus-sound-framples ( len ) 0 do
    i  reader readin  *output* outa drop
  loop
  tempfile file-delete
; :play #t with-sound drop
</pre>
</div>
</td>

</tr>
</table>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (convins beg dur filter file (size 128))
  (let* ((start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
         (end (+ start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
         (ff (<em class=red>make-convolve</em> :input (<a class=quiet href="#make-readin">make-readin</a> file) :fft-size size :filter filter)))
     (do ((i start (+ i 1)))
         ((= i end))
       (<a class=quiet href="#outa">outa</a> i (<em class=red>convolve</em> ff)))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () 
  (convins 0 2 (float-vector 1.0 0.5 0.25 0.125) "oboe.snd")) ; same as fir-filter with those coeffs
</pre>

<p>convolve-files handles a very common special case: convolve
two files, then normalize the result to some maxamp.  The convolve generator does not
know in advance what its maxamp will be, and when the two files are more or less
the same size, there's no real computational savings from using overlap-add (i.e.
the generator), so a one-time giant FFT saved as a temporary sound file is much
handier.  If you're particular about the format of the convolved data:
</p>

<pre class="indented">
(define* (convolve-files-&gt;aifc file1 file2 (maxamp 1.0) (output-file "test.snd"))
  (let ((outname (string-append "temp-" output-file)))
    (<em class=red>convolve-files</em> file1 file2 maxamp outname)
    (with-sound (:header-type mus-aifc :sample-type mus-bfloat)
      (let ((len (seconds-&gt;samples (mus-sound-duration outname)))
	    (reader (make-readin outname)))
        (do ((i 0 (+ i 1)))
            ((= i len))
          (outa i (readin reader)))))
    (delete-file outname)
    output-file))
</pre>

<p>The convolve generator is the modern way to add reverb.  There are impulse responses of various concert
halls floating around the web.  convolve and <a href="#fir-filter">fir-filter</a> actually perform the same mathematical operation,
but convolve uses an FFT internally, rather than a laborious dot-product.
</p>




<!--  GRANULATE  -->

<!-- INDEX grains:Granular synthesis --><em class=def id="grains"></em>

<div class="innerheader" id="granulatedoc">granulate</div>

<pre class="indented">
<em class=def id="make-granulate">make-granulate</em>   
        input
        (expansion 1.0)   ; how much to lengthen or compress the file
        (length .15)      ; length of file slices that are overlapped
        (scaler .6)       ; amplitude scaler on slices (to avoid overflows)
        (hop .05)         ; speed at which slices are repeated in output
        (ramp .4)         ; amount of slice-time spent ramping up/down
        (jitter 1.0)      ; affects spacing of successive grains
        max-size          ; internal buffer size
        edit              ; grain editing function

<em class=def id="granulate">granulate</em> e
<em class=def id="granulate?">granulate?</em> e
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">granulate methods</td></tr>
<tr><td class="inner"><em class=gen>mus-frequency</em></td><td class="inner">time (seconds) between output grains (hop)</td></tr>
<tr><td class="inner"><em class=gen>mus-ramp</em></td><td class="inner">length (samples) of grain envelope ramp segment</td></tr>
<tr><td class="inner"><em class=gen>mus-hop</em></td><td class="inner">time (samples)  between output grains (hop)</td></tr>
<tr><td class="inner"><em class=gen>mus-scaler</em></td><td class="inner">grain amp (scaler)</td></tr>
<tr><td class="inner"><em class=gen>mus-increment</em></td><td class="inner">expansion</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">grain length (samples)</td></tr>
<tr><td class="inner"><em class=gen>mus-data</em></td><td class="inner">grain samples (a float-vector)</td></tr>
<tr><td class="inner"><em class=gen>mus-location</em></td><td class="inner">granulate's local random number seed</td></tr>
</table>

<p>The granulate generator "granulates" its input (normally a sound file).  It is the poor man's way
to change the speed at which things happen in a recorded sound without
changing the pitches.  It works by slicing the input file into short
pieces, then overlapping these slices to lengthen (or shorten) the
result; this process is sometimes known as granular synthesis, and is
similar to the freeze function.  
</p>

<pre class="indented">
result = overlap add many tiny slices from input
</pre>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((grn (make-granulate (make-readin "oboe.snd") 2.0)))
    (do ((i 0 (+ i 1)))
	((= i 44100))
      (outa i (granulate grn)))))
</pre>
</div>
</td>
</tr>
<tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  rd = make_readin("oboe.snd");
  grn = make_granulate(lambda do |dir| readin(rd) end, 2.0);
  88200.times do |i|
    outa(i, granulate(grn), $output);
    end
  end.output
</pre>
</div>
</td>
</tr>
<tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  "oboe.snd" make-readin 2.0 make-granulate { grn }
  44100 0 do
    i  grn #f #f granulate  *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let* ((osc (make-oscil 440.0))
	 (sweep (make-env '(0 0 1 1) 
			  :scaler (hz-&gt;radians 440.0) 
			  :length 44100))
	 (grn (make-granulate (lambda (dir)
				(* 0.2 (oscil osc (env sweep))))
			      :expansion 2.0
			      :length .5)))
    (do ((i 0 (+ i 1)))
	((= i 88200))
      (outa i (granulate grn)))))
</pre>
</div>
</td>
</tr>
<tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  osc = make_oscil(440.0);
  sweep = make_env([0.0, 0.0, 1.0, 1.0],
                   :scaler, hz2radians(440.0),
		   :length, 44100);
  grn = make_granulate(lambda { |dir| 0.2 * oscil(osc, env(sweep))},
	               :expansion, 2.0,
	               :length, 0.5);
  88200.times do |i|
    outa(i, granulate(grn), $output);
    end
  end.output
</pre>
</div>
</td>
</tr>
<tr>

<td>
<div class="forth">
<pre class="indented">
: make-granulate-proc { osc sweep -- prc; dir self -- val }
  1 proc-create osc , sweep , ( prc )
 does> { dir self -- val }
  self @ ( osc )  self cell+ @ ( sweep ) env  0 oscil  0.2 f*
;

lambda: ( -- )
  440.0 make-oscil { osc }
  '( 0 0 1 1 ) :scaler 440.0 hz-&gt;radians :length 44100 make-env { sweep }
  osc sweep make-granulate-proc :expansion 2.0 :length 0.5 make-granulate { grn }
  88200 0 do
    i  grn #f #f granulate  *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>

<p>The duration of each slice is
"length" &mdash; the longer the slice, the more the effect resembles reverb.  The
portion of the length (on a scale from 0 to 1.0) spent on each
ramp (up or down) is set by the "ramp" argument.  It can control the smoothness of
the result of the overlaps. 
</p>

<p>The "jitter" argument sets
the accuracy with which granulate hops.  If you set it to 0 (no randomness), you can get very strong
comb filter effects, or tremolo.
The more-or-less average time between
successive segments is "hop".  
If jitter is 0.0, and hop is very small (say .01),
you're asking for trouble (a big comb filter).
If you're granulating more than one channel at a time, and want the channels to remain
in-sync, make each granulator use the same initial random number seed (via mus-location).
</p>

<p>The overall amplitude scaler on each segment is set by the
"scaler" argument; this is used to try to avoid overflows as we add
all these zillions of segments together.  "expansion"
determines the input hop in relation to the output hop; an
expansion-amount of 2.0 should more or less double the length of the
original, whereas an expansion-amount of 1.0 should return something
close to the original tempo.
"input" and "input-function" are the same as in src and convolve (functions of
one argument that return a new input sample whenever they are called by granulate).
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (granulate-sound file beg dur (orig-beg 0.0) (exp-amt 1.0))
  (let* ((f-srate (srate file))
         (f (<a class=quiet href="#make-readin">make-readin</a> file :start (round (* f-srate orig-beg))))
	 (st (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
	 (new-dur (or dur (- (<a class=quiet href="extsnd.html#mussoundduration">mus-sound-duration</a> file) orig-beg)))
	 (exA (<em class=red>make-granulate</em> :input f :expansion exp-amt))
	 (nd (+ st (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> new-dur))))
    (do ((i st (+ i 1)))
        ((= i nd))
      (<a class=quiet href="#outa">outa</a> i (<em class=red>granulate</em> exA)))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () (granulate-sound "now.snd" 0 3.0 0 2.0))
</pre>

<p>See <a href="sndscm.html#expsrc">clm-expsrc</a> in clm-ins.scm.  Here's an instrument that uses the input-function
argument to granulate.  It cause the granulation to run backwards through the file:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (grev beg dur exp-amt file file-beg)
  (let ((exA (<em class=red>make-granulate</em> :expansion exp-amt))
	(fil (<a class=quiet href="#make-filetosample">make-file-&gt;sample</a> file))
	(ctr file-beg))
    (do ((i beg (+ i 1)))
        ((= i (+ beg dur)))
      (<a class=quiet href="#outa">outa</a> i (<em class=red>granulate</em> exA
                (lambda (dir)
	          (let ((inval (<a class=quiet href="#filetosample">file-&gt;sample</a> fil ctr 0)))
	            (if (&gt; ctr 0) (set! ctr (- ctr 1)))
	            inval)))))))

(<a class=quiet href="sndscm.html#withsound">with-sound</a> () (grev 0 100000 2.0 "pistol.snd" 40000))
</pre>

<p>But it's unnecessary to write clever input functions.  It is just as fast, and much more perspicuous,
to use sound-let in cases like this.  Here's an example that takes any set of notes and calls granulate
on the result:
</p>

<pre class="indented">
(define-macro (gran-any beg dur expansion . body)
  `(<em class=red>sound-let</em> ((tmp () ,@body))
     (let* ((start (floor (* *clm-srate* ,beg)))
	    (end (+ start (* *clm-srate* ,dur)))
	    (rd (make-readin tmp))
	    (gran (<em class=red>make-granulate</em> :input rd :expansion ,expansion)))
       (do ((i start (+ i 1)))
	   ((= i end))
	 (outa i (granulate gran))))))

(with-sound () 
  (gran-any 0 2.5 4 
    (fm-violin 0 .1 440 .1) 
    (fm-violin .2 .1 660 .1) 
    (fm-violin .4 .1 880 .1)))
</pre>

<p>Any of the input-oriented generators (src, etc) can use this trick.
</p>

<p>
The "edit" argument can
be a function of one argument, the current granulate generator.  It is called just before
a grain is added into the output buffer. The current grain is accessible via mus-data.
The edit function, if any, should return the length in samples of the grain, or 0.
In the following example, we use the edit function to reverse every other grain:
</p>

<pre class="indented">
(let ((forward #t))
  (let ((grn (<em class=red>make-granulate</em> :expansion 2.0
                             :edit (lambda (g)
                                     (let ((grain (<a class=quiet href="#mus-data">mus-data</a> g))  ; current grain
                                           (len (<a class=quiet href="#mus-length">mus-length</a> g))) ; current grain length
                                       (if forward ; no change to data
                                           (set! forward #f)
                                           (begin
                                             (set! forward #t)
                                             (reverse! grain)))
                                       len))))
        (rd (<a class=quiet href="extsnd.html#makesampler">make-sampler</a> 0)))
    (<a class=quiet href="extsnd.html#mapchannel">map-channel</a> (lambda (y) (<em class=red>granulate</em> grn (lambda (dir) (rd)))))))
</pre>




<!--  PHASE-VOCODER  -->

<div class="innerheader" id="phase-vocoderdoc">phase-vocoder</div>

<pre class="indented">
<em class=def id="make-phase-vocoder">make-phase-vocoder</em> input (fft-size 512) (overlap 4) (interp 128) (pitch 1.0) analyze edit synthesize
<em class=def id="phase-vocoder">phase-vocoder</em> pv
<em class=def id="phase-vocoder?">phase-vocoder?</em> pv
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">phase-vocoder methods</td></tr>
<tr><td class="inner"><em class=gen>mus-frequency</em></td><td class="inner">pitch shift</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">fft-size</td></tr>
<tr><td class="inner"><em class=gen>mus-increment</em></td><td class="inner">interp</td></tr>
<tr><td class="inner"><em class=gen>mus-hop</em></td><td class="inner">fft-size / overlap</td></tr>
<tr><td class="inner"><em class=gen>mus-location</em></td><td class="inner">outctr (counter to next fft)</td></tr>
</table>

<p>The phase-vocoder generator performs phase-vocoder analysis and resynthesis.  The process is
split into three pieces, the analysis stage, editing of the amplitudes and phases, then the resynthesis.
Each stage has a default that is invoked if the "analyze", "edit", or "synthesize"
arguments are omitted from make-phase-vocoder or the phase-vocoder generator.  The edit and synthesize arguments are functions of one argument, the
phase-vocoder generator.  The analyze argument is a function of two arguments, the generator and
the input function. The default is to read the current input,
take an fft, get the new amplitudes and phases (as the edit
function default), then resynthesize using sines; so, the
default case returns a resynthesis of the original input.  The "interp" argument sets the time between
ffts (for time stretching, etc). 
</p>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t) ; new pitch = 2 * old
  (let ((pv (make-phase-vocoder 
             (make-readin "oboe.snd") :pitch 2.0)))
    (do ((i 0 (+ i 1)))
	((= i 44100))
      (outa i (phase-vocoder pv)))))
</pre>
</div>
</td>
</tr>
<tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  rd = make_readin("oboe.snd");
  pv = make_phase_vocoder(
         lambda do |dir| 
           readin(rd) end, :pitch, 2.0);
  88200.times do |i|
    outa(i, phase_vocoder(pv), $output);
    end
  end.output
</pre>
</div>
</td>
</tr>
<tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  "oboe.snd" make-readin :pitch 2.0 make-phase-vocoder { pv }
  44100 0 do
    i  pv #f #f #f #f phase-vocoder  *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t :srate 22050) ; new dur = 2 * old
  (let ((pv (make-phase-vocoder 
	     (make-readin "oboe.snd")
	     :interp 256)) ; 2 * 512 / 4
        ;; 512: fft size, 4: overlap, new dur: 2 * old dur
	(samps (* 2 (mus-sound-framples "oboe.snd"))))
    (do ((i 0 (+ i 1)))
	((= i samps))
      (outa i (phase-vocoder pv)))))
</pre>
</div>
</td>
</tr>
<tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true, :srate, 22050) do
  rd = make_readin("oboe.snd");
  pv = make_phase_vocoder(
	lambda do |dir| readin(rd) end,
        :interp, 2 * 512 / 4);
  samps = 2 * mus_sound_framples("oboe.snd");
  samps.times do |i|
    outa(i, phase_vocoder(pv), $output);
    end
  end.output
</pre>
</div>
</td>
</tr>
<tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  "oboe.snd" make-readin :interp 256 make-phase-vocoder { pv }
  "oboe.snd" mus-sound-framples 2* ( samps ) 0 do
    i  pv #f #f #f #f phase-vocoder  *output* outa drop
  loop
; :play #t :srate 22050 with-sound drop
</pre>
</div>
</td>
</tr>
</table>

<p>There are several functions giving access to the phase-vocoder data:
</p>

<pre class="indented">
<em class=emdef>phase-vocoder-amps</em> gen
<em class=emdef>phase-vocoder-freqs</em> gen
<em class=emdef>phase-vocoder-phases</em> gen
<em class=emdef>phase-vocoder-amp-increments</em> gen
<em class=emdef>phase-vocoder-phase-increments</em> gen
</pre>

<p>These are arrays (float-vectors) containing the spectral data the phase-vocoder uses to
reconstruct the sound.
In the next example we use all these special functions to resynthesize down an octave:
</p>

<pre class="indented">
(with-sound (:srate 22050 :statistics #t)
  (let ((pv (<em class=red>make-phase-vocoder</em>
	     (make-readin "oboe.snd")
	     512 4 128 1.0
	     #f ; no change to analysis method
	     #f ; no change to spectrum
	     (lambda (gen) ; resynthesis function
	       (float-vector-add! (phase-vocoder-amps gen) (phase-vocoder-amp-increments gen))
	       (float-vector-add! (phase-vocoder-phase-increments gen) (phase-vocoder-freqs gen))
	       (float-vector-add! (phase-vocoder-phases gen) (phase-vocoder-phase-increments gen))
	       (let ((sum 0.0)
		     (n (length (phase-vocoder-amps gen))))
		 (do ((k 0 (+ k 1)))
		     ((= k n))
		   (set! sum (+ sum (* (float-vector-ref (phase-vocoder-amps gen) k)
				       (sin (* 0.5 (float-vector-ref (phase-vocoder-phases gen) k)))))))
		 sum)))))
    (do ((i 0 (+ i 1)))
        ((= i 44100))
      (outa i (<em class=red>phase-vocoder</em> pv)))))
</pre>

<p>but, sadly, this code crawls.  It won't actually be useful until I optimize
handling of the caller's resynthesis function, but I am dragging my feet because I've never felt
that this phase-vocoder (as a generator) was the "right thing".  The first step toward something less stupid is
moving-spectrum in generators.scm.
</p>




<!--  ASYMMETRIC-FM  -->

<div class="innerheader" id="asymmetric-fmdoc">asymmetric-fm</div>

<pre class="indented">
<em class=def id="make-asymmetric-fm">make-asymmetric-fm</em> 
      (frequency 0.0) 
      (initial-phase 0.0) 
      (r 1.0)             ; amplitude ratio between successive sidebands
      (ratio 1.0)         ; ratio between carrier and sideband spacing
<em class=def id="asymmetric-fm">asymmetric-fm</em> af index (fm 0.0)
<em class=def id="asymmetric-fm?">asymmetric-fm?</em> af
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">asymmetric-fm methods</td></tr>
<tr><td class="inner"><em class=gen>mus-frequency</em></td><td class="inner">frequency in Hz</td></tr>
<tr><td class="inner"><em class=gen>mus-phase</em></td><td class="inner">phase in radians</td></tr>
<tr><td class="inner"><em class=gen>mus-scaler</em></td><td class="inner">"r" parameter; sideband scaler</td></tr>
<tr><td class="inner"><em class=gen>mus-offset</em></td><td class="inner">"ratio" parameter</td></tr>
<tr><td class="inner"><em class=gen>mus-increment</em></td><td class="inner">frequency in radians per sample</td></tr>
</table>

<p>The asymmetric-fm generator provides a way around the symmetric spectra normally produced by FM.
See  Palamin and Palamin, "A Method of Generating and Controlling Asymmetrical
Spectra" JAES vol 36, no 9, Sept 88, p671-685.  P&amp;P use sin(sin), but I'm using cos(sin) so
that we get a sum of cosines, and can therefore easily normalize the peak amplitude to -1.0..1.0.
asymmetric-fm is based on:
</p>

<!-- LATEX: 
original:
e^{(\frac{B}{2}(r-\frac{1}{r})\cos \omega_{m}t)}\sin(\omega_{c}t+\frac{B}{2}(r+\frac{1}{r})\sin \omega_{m}t)=\sum_{n=-\infty}^{\infty} r^{n}J_{n}(B)\sin(\omega_{c}t+n\omega_{m}t)
my version (for predicatable peak amp):
e^{(\frac{B}{2}(r-\frac{1}{r})\cos \omega_{m}t)}\cos(\omega_{c}t+\frac{B}{2}(r+\frac{1}{r})\sin \omega_{m}t)=\sum_{n=-\infty}^{\infty} r^{n}J_{n}(B)\cos(\omega_{c}t+n\omega_{m}t)

original:
e^{(\frac{B}{2}(r+\frac{1}{r})\cos \omega_{m}t)}\sin(\omega_{c}t+\frac{B}{2}(r-\frac{1}{r})\sin \omega_{m}t)=\sum_{n=-\infty}^{\infty} r^{n}I_{n}(B)\sin(\omega_{c}t+n\omega_{m}t)
my version:
e^{(\frac{B}{2}(r+\frac{1}{r})\cos \omega_{m}t)}\cos(\omega_{c}t+\frac{B}{2}(r-\frac{1}{r})\sin \omega_{m}t)=\sum_{n=-\infty}^{\infty} r^{n}I_{n}(B)\cos(\omega_{c}t+n\omega_{m}t)

here's the complicated case:
e^{\big( \big(\frac{B}{2}\big(r+\frac{1}{r}\big)\cos \omega_{m}t\big) - \frac{1}{2} \ln \big(I_{0}\big(B\big(r+\frac{1}{r}\big)\big)\big) \big)} \sin\big(\omega_{c}t+\frac{B}{2}\big(r-\frac{1}{r}\big)\sin \omega_{m}t\big)=\frac{1}{\sqrt{I_{0}(B(r+\frac{1}{r}))}} \sum r^{n}I_{n}(B)\sin(\omega_{c}t+n\omega_{m}t)
 -->

<img class="indented" src="pix/sceq10.png" alt="e sin"><br>
<img class="indented" src="pix/sceq22.png" alt="I form">


<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((fm (make-asymmetric-fm 440.0 0.0 0.9 0.5)))
    (do ((i 0 (+ i 1)))
	((= i 44100))
      (outa i (* 0.5 (asymmetric-fm fm 1.0))))))
</pre>
</div>
</td>
</tr>
<tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  fm = make_asymmetric_fm(440.0, 0.0, 0.9, 0.5);
  44100.times do |i|
    outa(i, 0.5 * asymmetric_fm(fm, 1.0), $output);
    end
  end.output
</pre>
</div>
</td>
</tr>
<tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  440.0 0.0 0.9 0.5 make-asymmetric-fm { fm }
  44100 0 do
    i  fm 1.0 0 asymmetric-fm  f2/ *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>

<p>"r" is the ratio between successive 
sideband amplitudes, r &lt; 0.0 or r &gt; 1.0 pushes energy above the carrier, whereas r between 0.0 and 1.0 pushes it below. (r = 1.0
gives normal FM).  The mirror image of r (around a given
carrier) is produced by -1/r.
"ratio" is the ratio between the carrier and modulator (i.e. sideband spacing). It's somewhat inconsistent
that asymmetric-fm takes "index" (the fm-index) as its second argument, but otherwise it
would be tricky to get time-varying indices.  In this instrument we sweep "r" with an envelope:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (asy beg dur freq amp index (ratio 1.0))
  (let* ((st (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
         (nd (+ st (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
         (r-env (<a class=quiet href="#make-env">make-env</a> '(0 -1 1 -20) :duration dur))
         (asyf (<em class=red>make-asymmetric-fm</em> :ratio ratio :frequency freq)))
    (do ((i st (+ i 1))) 
        ((= i nd))
      (set! (<a class=quiet href="#mus-scaler">mus-scaler</a> asyf) (<a class=quiet href="#env">env</a> r-env)) ; this sets "r"
      (<a class=quiet href="#outa">outa</a> i (* amp (<em class=red>asymmetric-fm</em> asyf index))))))
</pre>

<p>For the other kind of asymmetric-fm see generators.scm, and for asymmetric spectra via "single sideband FM" see generators.scm.
</p>



<table class="method">		    
<tr><td class="inner"><em class=def id="frampletoframple">frample-&gt;frample</em><code> mf inf outf</code></td><td>pass frample through a matrix multiply, return outf</td></tr>
</table>





<!--  FILE->SAMPLE  -->

<div class="innerheader" id="filetosampledoc">sound IO</div>

<p>Sound file IO is based on a set of file readers and writers that deal either in samples or float-vectors.
The six functions are file-&gt;sample, sample-&gt;file, file-&gt;frample, frample-&gt;file, array-&gt;file, and file-&gt;array.
The name "array" is used here, rather than "float-vector" for historical reasons (the CL version of CLM predates
Snd by many years).
These functions are then packaged up in more convenient forms as in-any, out-any, locsig, readin, etc.
Within with-sound, the variable *output* is bound to the with-sound output file via a sample-&gt;file
object.
</p>


<pre class="indented">
<em class=def id="make-filetosample">make-file-&gt;sample</em> name (buffer-size 8192)
<em class=def id="make-sampletofile">make-sample-&gt;file</em> name (chans 1) (format mus-lfloat) (type mus-next) comment
<em class=def id="filetosample?">file-&gt;sample?</em> obj
<em class=def id="sampletofile?">sample-&gt;file?</em> obj
<em class=def id="filetosample">file-&gt;sample</em> obj samp chan
<em class=def id="sampletofile">sample-&gt;file</em> obj samp chan val
<em class=def id="continue-sampletofile">continue-sample-&gt;file</em> file

<em class=def id="make-filetoframple">make-file-&gt;frample</em> name (buffer-size 8192)
<em class=def id="make-frampletofile">make-frample-&gt;file</em> name (chans 1) (format mus-lfloat) (type mus-next) comment
<em class=def id="frampletofile?">frample-&gt;file?</em> obj
<em class=def id="filetoframple?">file-&gt;frample?</em> obj
<em class=def id="filetoframple">file-&gt;frample</em> obj samp outf
<em class=def id="frampletofile">frample-&gt;file</em> obj samp val
<em class=def id="continue-frampletofile">continue-frample-&gt;file</em> file

<em class=def id="filetoarray">file-&gt;array</em> file channel beg dur array
<em class=def id="arraytofile">array-&gt;file</em> file data len srate channels

<em class=def id="mus-input?">mus-input?</em> obj
<em class=def id="mus-output?">mus-output?</em> obj
<em class=def id="mus-close">mus-close</em> obj
<em class=def id="*output*">*output*</em>
<em class=def id="*reverb*">*reverb*</em>
<em class=def id="musfilebuffersize">mus-file-buffer-size</em> (also known as *clm-file-buffer-size*)
</pre>


<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:channels 2)
  ;; swap channels of stereo file
  (let ((input (make-file-&gt;frample "stereo.snd"))
	(len (mus-sound-framples "stereo.snd"))
	(frample (make-float-vector 2)))
    (do ((i 0 (+ i 1)))
	((= i len))
      (file-&gt;frample input i frample)
      (let ((val (frample 0)))
	(set! (frample 0) (frample 1))
	(set! (frample 1) val))
      (frample-&gt;file *output* i frample))))
</pre>
</div>
</td>

</tr><tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:channels, 2) do
  input = make_file2frample("stereo.snd");
  len = mus_sound_framples("stereo.snd");
  frample = make_frample(2);
  len.times do |i|
    file2frample(input, i, frample);
    val = frample_ref(frample, 0);
    frample_set!(frample, 0, frample_ref(frample, 1));
    frample_set!(frample, 1, val);
    frample2file($output, i, frample);
    end
  end.output
</pre>
</div>
</td>

</tr><tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  "stereo.snd" make-file-&gt;frample { input }
  2 make-frample { frm }
  "stereo.snd" mus-sound-framples ( len ) 0 do
    input i frm file-&gt;frample ( frm ) 1 frample-ref ( val1 )
    frm 0 frample-ref ( val0 ) frm 1 rot frample-set! drop
    ( val1 ) frm 0 rot frample-set! drop
    *output* i frm frample-&gt;file drop
  loop
; :channels 2 :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>


<p>file-&gt;sample writes a sample to a file, frample-&gt;file writes a frample, file-&gt;sample reads a sample
from a file, and file-&gt;frample reads a frample.
continue-frample-&gt;file and continue-sample-&gt;file reopen an existing file to continue adding sound data to it.
mus-output? returns #t is its argument is some sort of file writing generator, and mus-input? returns #t if its 
argument is a file reader.  
In make-file-&gt;sample and make-file-&gt;frample, the buffer-size defaults to *clm-file-buffer-size*.
There are many examples of these functions in snd-test.scm, and clm-ins.scm.
Here is one that uses file-&gt;sample to mix in a sound file (there are a zillion other ways to do this):
</p>

<pre class="indented">
(define (simple-f2s beg dur amp file)
  (let* ((start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
         (end (+ start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
         (fil (<em class=red>make-file-&gt;sample</em> file)))
    (do ((ctr 0) 
         (i start (+ i 1))) ((= i end))
      (<a class=quiet href="#out-any">out-any</a> i (* amp (<em class=red>file-&gt;sample</em> fil ctr 0)) 0)
      (set! ctr (+ 1 ctr)))))
</pre>

<p>mus-close flushes any pending output and closes the output stream 'obj'.
This is normally done for you by with-sound, but if you have your own
output streams,
and you forget to call mus-close, the GC will eventually do it for you.
</p>





<!--  READIN  -->

<div class="innerheader" id="readindoc">readin</div>

<pre class="indented">
 <em class=def id="make-readin">make-readin</em> file (channel 0) (start 0) (direction 1) size
 <em class=def id="readin">readin</em> rd
 <em class=def id="readin?">readin?</em> rd
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">readin methods</td></tr>
<tr><td class="inner"><em class=gen>mus-channel</em></td><td class="inner">channel arg to make-readin (no set!)</td></tr>
<tr><td class="inner"><em class=gen>mus-location</em></td><td class="inner">current location in file</td></tr>
<tr><td class="inner"><em class=gen>mus-increment</em></td><td class="inner">sample increment (direction arg to make-readin)</td></tr>
<tr><td class="inner"><em class=gen>mus-file-name</em></td><td class="inner">name of file associated with gen</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">number of framples in file associated with gen</td></tr>
</table>

<p>readin returns successive samples from a file; it is an elaboration of file-&gt;sample that keeps track of the
current read location and channel number for you.
Its "file" argument is the input file's name.
"start" is the frample at which to start reading the input file. 
"channel" is which channel to read (0-based).
"size" is the read buffer size in samples.  It defaults to *clm-file-buffer-size*.
</p>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((reader (make-readin "oboe.snd")))
    (do ((i 0 (+ i 1)))
        ((= i 44100))
      (outa i (* 2.0 (readin reader))))))
</pre>
</div>
</td>
</tr><tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  reader = make_readin("oboe.snd");
  44100.times do |i|
   outa(i, 2.0 * readin(reader), 
        $output);
   end
  end.output
</pre>
</div>
</td>
</tr><tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  "oboe.snd" make-readin { reader }
  44100 0 do
    i  reader readin  f2/ *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>


<p>Here is an instrument that applies an envelope to a sound file using
readin and <a href="#env">env</a>:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (env-sound file beg (amp 1.0) (amp-env '(0 1 100 1)))
  (let* ((st (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
         (dur (<a class=quiet href="extsnd.html#mussoundduration">mus-sound-duration</a> file))
         (rev-amount .01)
         (rdA (<em class=red>make-readin</em> file))
         (ampf (<a class=quiet href="#make-env">make-env</a> amp-env amp dur))
         (nd (+ st (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur))))
     (do ((i st (+ i 1)))
         ((= i nd))
       (let ((outval (* (<a class=quiet href="#env">env</a> ampf) (<em class=red>readin</em> rdA))))
           (<a class=quiet href="#outa">outa</a> i outval)
         (if <a class=quiet>*reverb*</a> 
           (<a class=quiet href="#outa">outa</a> i (* outval rev-amount) <a class=quiet>*reverb*</a>))))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () (env-sound "oboe.snd" 0 1.0 '(0 0 1 1 2 1 3 0)))
</pre>




<!--  IN-ANY, OUT-ANY  -->

<div class="innerheader" id="in-anydoc">in-any, out-any</div>

<pre class="indented">
<em class=def id="out-any">out-any</em> loc data channel (output *output*)
<em class=def id="outa">outa</em> loc data (output *output*)
<em class=emdef>outb</em> loc data (output *output*)
<em class=emdef>outc</em> loc data (output *output*)
<em class=emdef>outd</em> loc data (output *output*)
<em class=def id="outbank">out-bank</em> gens loc input

<em class=def id="in-any">in-any</em> loc channel input
<em class=def id="ina">ina</em> loc input
<em class=def id="inb">inb</em> loc input
</pre>

<p>These are the "generic" input and output functions.
out-any adds its "data" argument (a sound sample) into the "output" object at sample
position "loc".  
The "output" argument can be a vector as well as the more usual frample-&gt;file object.
or any output-capable CLM generator.
In with-sound, the current output is *output* and the reverb output is *reverb*.
outa is the same as out-any with a channel of 0.  It is not an error to try to write to a channel that doesn't exist;
the function just returns.
</p>

<p>in-any returns the sample at position "loc" in
"input".  ina is the same as in-any with a channel of 0.
As in out-any and friends, the "input" argument can be a file-&gt;frample object, or a vector.
</p>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((infile (make-file-&gt;sample "oboe.snd")))
    (do ((i 0 (+ i 1)))
        ((= i 44100))
      (out-any i (in-any i 0 infile) 0))))
</pre>
</div>
</td>
</tr><tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  infile = make_file2sample("oboe.snd");
  44100.times do |i|
    out_any(i, in_any(i, 0, infile), 0, $output);
    end
  end.output
</pre>
</div>
</td>
</tr><tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  "oboe.snd" make-file-&gt;sample { infile }
  44100 0 do
    i  i 0 infile in-any  0 *output* out-any drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>
</tr>
</table>


<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (simple-ina beg dur amp file)
  (let* ((start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
         (end (+ start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
         (fil (<em class=red>make-file-&gt;sample</em> file)))
     (do ((i start (+ i 1)))
         ((= i end))
       (<a class=quiet href="#outa">outa</a> i 
         (* amp (<em class=red>in-any</em> i 0 fil)))))) ; same as (<em class=red>ina</em> i fil)

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () (simple-ina 0 1 .5 "oboe.snd"))
</pre>

<p>To write from <a href="sndscm.html#wsdoc">with-sound</a> to a vector, rather than a file,
use its :output argument:
</p>

<pre class="indented">
(with-sound (<em class=red>:output</em> (make-float-vector 44100)) ; this sets *output*, the default output location
   (<a class=quiet href="sndscm.html#vdoc">fm-violin</a> 0 1 440 .1))
</pre>


<p>If *output* is a function, it should take 3 arguments, the sample number, current output value, and channel.
</p>

<pre class="indented">
(let ((avg 0.0)
      (samps 0))
  (with-sound (<em class=red>:output</em> (lambda (frample val chan) ; get the average of all the samples
                         (set! avg (+ avg val))
                         (set! samps (+ 1 samps))
                	 val))
    (do ((i 0 (+ i 1)))
	((&gt; i 10))
      (<em class=red>outa</em> i (* i .1))))
  (/ avg samps))

;; returns 0.5
</pre>

<p>Similarly, if in-any's "input" argument is a function, it takes the input location (sample number), and channel (0-based).
</p>

<pre class="indented">
(let ((input (<a class=quiet href="#make-readin">make-readin</a> "oboe.snd" :start 1000)))
  (with-sound ((make-float-vector 10))
    (do ((i 0 (+ i 1)))
	((= i 10))
      (<em class=red>outa</em> i (<em class=red>ina</em> i (lambda (loc chn)
		       (<a class=quiet href="#readin">readin</a> input)))))))
</pre>

<pre class="indented">
(let ((outv (make-float-vector 10)))
  (with-sound ()
     (do ((i 0 (+ i 1)))
         ((= i 10))
      (outa i (* i .1) (lambda (loc val chan)
	 	         (set! (outv loc) val)))))
  outv) ; this is equivalent to using :output (make-float-vector 10) as a with-sound argument
</pre>





<!--  LOCSIG  -->

<!-- INDEX make-locsig:Sound placement -->
<div class="innerheader" id="locsigdoc">locsig</div>

<pre class="indented">
 <em class=def id="make-locsig">make-locsig</em> 
        (degree 0.0)
        (distance 1.0) 
	(reverb 0.0)       ; reverb amount
        (output *output*)  ; output generator or location
	(revout *reverb*)  ; reverb output generator or location
        (channels (channels output))
	(type mus-interp-linear)
 <em class=def id="locsig">locsig</em> loc i in-sig
 <em class=def id="locsig?">locsig?</em> loc

 <em class=def id="locsig-ref">locsig-ref</em> loc chan
 <em class=def id="locsig-set!">locsig-set!</em> loc chan val
 <em class=def id="locsig-reverb-ref">locsig-reverb-ref</em> loc chan
 <em class=def id="locsig-reverb-set!">locsig-reverb-set!</em> loc chan val

 <em class=def id="move-locsig">move-locsig</em> loc degree distance
 <em class=def id="locsig-type">locsig-type</em> ()
</pre>

<table class="method">
<tr><td colspan=2 class="methodtitle">locsig methods</td></tr>
<tr><td class="inner"><em class=gen>mus-data</em></td><td class="inner">output scalers (a float-vector)</td></tr>
<tr><td class="inner"><em class=gen>mus-xcoeff</em></td><td class="inner">reverb scaler</td></tr>
<tr><td class="inner"><em class=gen>mus-xcoeffs</em></td><td class="inner">reverb scalers (a float-vector)</td></tr>
<tr><td class="inner"><em class=gen>mus-channels</em></td><td class="inner">output channels</td></tr>
<tr><td class="inner"><em class=gen>mus-length</em></td><td class="inner">output channels</td></tr>
</table>

<p>locsig places a sound in 
an N-channel circle of speakers
by scaling the respective channel amplitudes
("that old trick <em>never</em> works"). It normally replaces <a href="#outa">out-any</a>.
"reverb" determines how much of
the direct signal gets sent to the reverberator.  "distance" tries to
imitate a distance cue by fooling with the relative amounts of direct and
reverberated signal (independent of the "reverb" argument).  The distance should
be greater than or equal to 1.0.  
"type" (returned by the function locsig-type) can be <code>mus-interp-linear</code> (the default) or <code>mus-interp-sinusoidal</code>.
The mus-interp-sinusoidal
case uses sin and cos to set the respective channel amplitudes (this is reported to
help with the "hole-in-the-middle" problem).
The "output" argument can be a vector as well as a frample-&gt;file generator.
</p>


<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t :channels 2)
  (let ((loc (make-locsig 60.0))
	(osc (make-oscil 440.0)))
    (do ((i 0 (+ i 1)))
	((= i 44100))
      (locsig loc i 
              (* 0.5 (oscil osc))))))
</pre>
</div>
</td>
</tr><tr>
<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true, :channels, 2) do
  loc = make_locsig(60.0, :output, $output);
  osc = make_oscil(440.0);
  44100.times do |i|
    locsig(loc, i, 0.5 * oscil(osc));
    end
  end.output
</pre>
</div>
</td>
</tr><tr>
<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  60.0 make-locsig { loc }
  440.0 make-oscil { osc }
  44100 0 do
    loc i  osc 0 0 oscil f2/  locsig drop
  loop
; :play #t :channels 2 with-sound drop
</pre>
</div>
</td>
</tr>
</table>

<p>Locsig can send output to any number of channels.
If channels &gt; 2, the speakers are assumed to be evenly spaced in
a circle.
You can use locsig-set! to override the placement decisions.
To have full output to both channels,</p>

<pre class="indented">
(locsig-set! loc 0 1.0) 
(locsig-set! loc 1 1.0)
</pre>

<p>Here is an instrument that has envelopes on the distance and degrees, and optionally reverberates a file:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (space file onset duration (distance-env '(0 1 100 10)) (amplitude-env '(0 1 100 1))
		     (degree-env '(0 45 50 0 100 90)) (reverb-amount .05))
  (let* ((beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> onset))
	 (end (+ beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> duration)))
         (loc (<em class=red>make-locsig</em> :degree 0 :distance 1 :reverb reverb-amount))
         (rdA (<a class=quiet href="#make-readin">make-readin</a> :file file))
         (dist-env (<a class=quiet href="#make-env">make-env</a> distance-env :duration duration))
         (amp-env (<a class=quiet href="#make-env">make-env</a> amplitude-env :duration duration))
         (deg-env (<a class=quiet href="#make-env">make-env</a> degree-env :scaler (/ 1.0 90.0) :duration duration))
         (dist-scaler 0.0))
    (do ((i beg (+ i 1)))
        ((= i end))
      (let ((rdval (* (<a class=quiet href="#readin">readin</a> rdA) (<a class=quiet href="#env">env</a> amp-env)))
            (degval (<a class=quiet href="#env">env</a> deg-env)))
        (set! dist-scaler (/ (<a class=quiet href="#env">env</a> dist-env)))
        (locsig-set! loc 0 (* (- 1.0 degval) dist-scaler))
        (if (&gt; (channels <a class=quiet>*output*</a>) 1)
            (locsig-set! loc 1 (* degval dist-scaler)))
        (if <a class=quiet>*reverb*</a> 
            (locsig-reverb-set! loc 0 (* reverb-amount (sqrt dist-scaler))))
        (<em class=red>locsig</em> loc i rdval)))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:reverb jc-reverb :channels 2) 
  (space "pistol.snd" 0 3 :distance-env '(0 1 1 2) :degree-env '(0 0 1 90)))
</pre>

<p>For a moving sound
source, see either move-locsig, Fernando Lopez Lezcano's <a class=def href="http://ccrma.stanford.edu/~nando/clm/dlocsig/index.html">dlocsig</a>,
or <a href="#flocsig">flocsig</a> (flanged locsig) in generators.scm.
Here is an example of move-locsig:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:channels 4)
  (let ((loc (<em class=red>make-locsig</em>))
	(osc (<a class=quiet href="#make-oscil">make-oscil</a> 440.0))
	(j 0))
    (do ((i 0 (+ i 1)))
        ((= i 360))
      (do ((k 0 (+ k 1)))
          ((= k 1000))
        (let ((sig (* .5 (<a class=quiet href="#oscil">oscil</a> osc))))
          (<em class=red>locsig</em> loc j sig)
          (set! j (+ j 1))))
      (<em class=red>move-locsig</em> loc (* 1.0 i) 1.0))))
</pre>

<table>
<tr>
<td><img class="indented" src="pix/circle.png" alt="move-locsig example"></td>
<td><img class="indented" src="pix/locsine.png" alt="move-locsig example"></td>
</tr><tr>
<td class="center">linear interp</td>
<td class="center">sinusoidal interp</td>
</tr></table>

<p>The interaction of outa, locsig, and *reverb* seems to be causing confusion, so here are some
simple examples:
</p>

<pre class="indented">
(load "nrev.scm")

(define (simp start end freq amp)
  (let ((os (make-oscil freq)))
    (do ((i start (+ i 1))) 
        ((= i end))
      (let ((output (* amp (oscil os))))
	(outa i output)
	(if *reverb* (outa i (* output .1) *reverb*))))))

; (with-sound () (simp 0 44100 440 .1))            ; no reverb
; (with-sound (:reverb nrev) (simp 0 44100 440 .1)); reverb


(define (locsimp start end freq amp)
  (let ((os (make-oscil freq))
	(loc (make-locsig :reverb .1)))
    (do ((i start (+ i 1))) 
        ((= i end))
      (locsig loc i (* amp (oscil os))))))

; (with-sound () (locsimp 0 44100 440 .1))            ; no reverb
; (with-sound (:reverb nrev) (locsimp 0 44100 440 .1)); reverb
</pre>




<!--  MOVE-SOUND  -->

<div class="innerheader" id="move-sounddoc">move-sound</div>

<pre class="indented">
<em class=def id="make-move-sound">make-move-sound</em> dlocs-list (output *output*) (revout *reverb*)
<em class=def id="move-sound">move-sound</em> dloc i in-sig
<em class=def id="move-sound?">move-sound?</em> dloc
</pre>

<p>move-sound is intended as the run-time portion of <a href="sndscm.html#dlocsigdoc">dlocsig</a>.  make-dlocsig
creates a move-sound structure, passing it to the move-sound generator inside the
dlocsig macro.  All the necessary data is packaged up in a list:
</p>

<pre class="indented">
(list
  (start 0)               ; absolute sample number at which samples first reach the listener
  (end 0)                 ; absolute sample number of end of input samples
  (out-channels 0)        ; number of output channels in soundfile
  (rev-channels 0)        ; number of reverb channels in soundfile
  path                    ; interpolated delay line for doppler
  delay                   ; tap doppler env
  rev                     ; reverberation amount
  out-delays              ; delay lines for output channels that have additional delays
  gains                   ; gain envelopes, one for each output channel
  rev-gains               ; reverb gain envelopes, one for each reverb channel
  out-map)                ; mapping of speakers to output channels
</pre>
<p>Here's an instrument that uses this generator to pan a sound through four channels:
</p>

<pre class="indented">
(define (simple-dloc beg dur freq amp)
  (let* ((os (<a class=quiet href="#make-oscil">make-oscil</a> freq))
         (start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> beg))
         (end (+ start (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur)))
         (loc (<em class=red>make-move-sound</em> (list start end 4 0
                                              (<a class=quiet href="#make-delay">make-delay</a> 12) 
                                     (<a class=quiet href="#make-env">make-env</a> '(0 0 10 1) :length dur)
                                     #f
                                     (make-vector 4 #f)
                                     (vector (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 2 0 3 0 4 0) :duration dur)
                                             (<a class=quiet href="#make-env">make-env</a> '(0 0 1 0 2 1 3 0 4 0) :duration dur)
                                             (<a class=quiet href="#make-env">make-env</a> '(0 0 1 0 2 0 3 1 4 0) :duration dur)
                                             (<a class=quiet href="#make-env">make-env</a> '(0 0 1 0 2 0 3 0 4 1) :duration dur))
                                     #f
                                     (vector 0 1 2 3)))))
    (do ((i start (+ i 1)))
        ((= i end))
      (<em class=red>move-sound</em> loc i (* amp (<a class=quiet href="#oscil">oscil</a> os))))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:channels 4) (simple-dloc 0 2 440 .5))
</pre>



<div class="header" id="genericfunctions">Generic functions</div>

<!--  GENERIC FUNCTIONS  -->


<p>Besides the 30 or so built-in generators, there are around 100 others defined in generators.scm. If we
required separate functions for each generator for access to the generator internal state (current phase, for example),
we'd end up with hundreds, or even thousands of accessors.  Instead, 
all the generators respond to a set of "generic" functions.  mus-frequency, for example, tries to return (or set) a generator's
frequency, for any generator that has some sort of frequency field.
The generic functions are:
</p>

<table class="method">
<tr><td><em class=def id="mus-channel">mus-channel</em></td><td>channel being read/written</td></tr>
<tr><td><em class=def id="mus-channels">mus-channels</em></td><td>channels open</td></tr>
<tr><td><em class=def id="mus-copy">mus-copy</em></td><td>copy a generator</td></tr>
<tr><td><em class=def id="mus-data">mus-data</em></td><td>float-vector of data</td></tr>
<tr><td><em class=def id="mus-describe">mus-describe</em></td><td>description of current state</td></tr>
<tr><td><em class=def id="mus-feedback">mus-feedback</em></td><td>feedback coefficient</td></tr>
<tr><td><em class=def id="mus-feedforward">mus-feedforward</em></td><td>feedforward coefficient</td></tr>
<tr><td><em class=def id="mus-file-name">mus-file-name</em></td><td>file being read/written</td></tr>
<tr><td><em class=def id="mus-frequency">mus-frequency</em></td><td>frequency (Hz)</td></tr>
<tr><td><em class=def id="mus-hop">mus-hop</em></td><td>hop size for block processing</td></tr>
<tr><td><em class=def id="mus-increment">mus-increment</em></td><td>various increments</td></tr>
<tr><td><em class=def id="mus-interp-type">mus-interp-type</em></td><td>interpolation type (mus-interp-linear, etc)</td></tr>
<tr><td><em class=def id="mus-length">mus-length</em></td><td>data length</td></tr>
<tr><td><em class=def id="mus-location">mus-location</em></td><td>sample location for reads/writes</td></tr>
<tr><td><em class=def id="mus-name">mus-name</em></td><td>generator name ("oscil")</td></tr>
<tr><td><em class=def id="mus-offset">mus-offset</em></td><td>envelope offset</td></tr>
<tr><td><em class=def id="mus-order">mus-order</em></td><td>filter order</td></tr>
<tr><td><em class=def id="mus-phase">mus-phase</em></td><td>phase (radians)</td></tr>
<tr><td><em class=def id="mus-ramp">mus-ramp</em></td><td>granulate grain envelope ramp setting</td></tr>
<tr><td><em class=def id="mus-reset">mus-reset</em></td><td>set gen to default starting state</td></tr>
<tr><td><em class=def id="mus-run">mus-run</em></td><td>run any generator</td></tr>
<tr><td><em class=def id="mus-scaler">mus-scaler</em></td><td>scaler, normally on an amplitude</td></tr>
<tr><td><em class=def id="mus-width">mus-width</em></td><td>width of interpolation tables, etc</td></tr>
<tr><td><em class=def id="mus-xcoeff">mus-xcoeff</em></td><td>x (input) coefficient</td></tr>
<tr><td><em class=def id="mus-xcoeffs">mus-xcoeffs</em></td><td>float-vector of x (input) coefficients</td></tr>
<tr><td><em class=def id="mus-ycoeff">mus-ycoeff</em></td><td>y (output, feedback) coefficient</td></tr>
<tr><td><em class=def id="mus-ycoeffs">mus-ycoeffs</em></td><td>float-vector of y (feedback) coefficients</td></tr>
</table>

<p>Many of these are settable:
<code>(set! (mus-frequency osc1) 440.0)</code>
sets osc1's phase increment to (<a class=quiet href="#hztoradians">hz-&gt;radians</a> 440.0). 
When I have a cold, I sometimes use the following function to see how high I can hear; count
the audible tones and multiply by 1000:
</p>

<pre class="indented">
(define (quick-check)
  (<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () 
    (let ((gen (<a class=quiet href="#make-oscil">make-oscil</a> 1000))) 
      (do ((i 0 (+ i 1))) 
          ((= i 400000))
        (if (= (modulo i 20000) 0) 
            (set! (<em class=red>mus-frequency</em> gen) (+ 1000 (/ i 20))))
        (<a class=quiet href="#outa">outa</a> i (* .5 (<a class=quiet href="#oscil">oscil</a> gen)))))))
</pre>

<p>Another example is run-with-fm-and-pm in generators.scm which applies phase modulation (as well as
the default frequency modulation) to any generator:
</p>

<pre class="indented">
(define (run-with-fm-and-pm gen fm pm)
  (set! (<em class=red>mus-phase</em> gen) (+ (<em class=red>mus-phase</em> gen) pm))
  (let ((result (<em class=red>mus-run</em> gen fm 0.0)))
    (set! (<em class=red>mus-phase</em> gen) (- (<em class=red>mus-phase</em> gen) pm))
    result))
</pre>

<p>
<em class=def id="musgeneratorp">mus-generator?</em> returns #t if its argument is
a generator.
A generator defined via <a href="#defgenerator">defgenerator</a> can also take part in these methods.
</p>




<div class="header" id="othergenerators">Other generators</div>

<!--  OTHER GENERATORS  -->

<p>(this section is work in progress...)
</p>

<p>There are dozens of generators scattered around the *.scm files that come with Snd.  Some that come to mind:
</p>

<pre class="indented">
analog-filter.scm:
    filter: <a class=quiet href="sndscm.html#analogfilterdoc">butterworth-lowpass|highpass|bandpass|bandstop</a>, 
            <a class=quiet href="sndscm.html#analogfilterdoc">chebyshev-lowpass|highpass|bandpass|bandstop</a>, 
            <a class=quiet href="sndscm.html#analogfilterdoc">inverse-chebyshev-lowpass|highpass|bandpass|bandstop</a>, 
            <a class=quiet href="sndscm.html#analogfilterdoc">elliptic-lowpass|highpass|bandpass|bandstop</a>,
            <a class=quiet href="sndscm.html#analogfilterdoc">bessel-lowpass|highpass|bandpass|bandstop</a>

clm-ins.scm:
    <a class=quiet href="sndscm.html#rmsgain">rms gain balance</a>

dsp.scm:
    fir-filter: <a class=quiet href="sndscm.html#hilberttransform">hilbert-transform</a>, 
                <a class=quiet href="sndscm.html#makehighpass">highpass, lowpass, bandpass, bandstop</a>, 
                <a class=quiet href="sndscm.html#makedifferentiator">differentiator</a>,
                <a class=quiet href="sndscm.html#makespencerfilter">make-spencer-filter</a>, 
                <a class=quiet href="sndscm.html#sgfilter">savitzky-golay-filter</a>
   
    filter: <a class=quiet href="sndscm.html#makebutter">butter-high-pass, butter-low-pass, butter-band-pass, butter-band-reject</a>, 
            <a class=quiet href="sndscm.html#makebiquad">biquad</a>,
            <a class=quiet href="sndscm.html#IIRfilters">iir-low-pass, iir-high-pass, iir-band-pass, iir-band-stop, peaking</a>,
            <a class=quiet href="sndscm.html#makebutter">butter-lp, butter-hp, butter-bp, butter-bs</a>
   
    <a class=quiet href="sndscm.html#volterrafilter">volterra-filter</a>

env.scm:
    <a class=quiet href="sndscm.html#powerenv">power-env</a> (and many env makers/modifiers)

extensions.scm:
    <a class=quiet href="sndscm.html#envexptchannel">env-expt-channel</a> (and many related env modifiers)

examp.scm:
    <a class=quiet href="sndscm.html#makeramp">ramp</a>, 
    <a class=quiet href="sndscm.html#soundinterp">sound-interp</a>

moog.scm:
    <a class=quiet href="sndscm.html#moogfilter">moog-filter</a>

prc95.scm:
    <a class=quiet href="sndscm.html#prc95doc">reed, bowtable, jettable, onep, lip, dc-block, delaya, delayl</a>

zip.scm:
    <a class=quiet href="sndscm.html#zipper">zipper</a>
</pre>

<p>In this section, we concentrate on the generators defined in generators.scm.  Nearly all of them respond to the
generic functions mus-name, mus-reset, mus-describe, mus-frequency, mus-scaler, mus-offset, mus-phase, and mus-order.
The parameters are generally "frequency", "n" (the number of sidebands), "r" (the ratio between successive sideband
amplitudes), and "ratio" (the ratio between the
frequency and the spacing between successive sidebands).
</p>

<div class="separator"></div>

<pre class="indented">
<em class=def id="make-polyoid">make-polyoid</em> 
         (frequency 0.0) 
         (partial-amps-and-phases '(1 1 0.0))   ; a list of harmonic numbers, their associated amplitudes, and their initial-phases

<em class=def id="polyoid">polyoid</em> w (fm 0.0)
<em class=def id="polyoid?">polyoid?</em> w

<em class=def id="polyoidenv">polyoid-env</em> w fm amps phases

<em class=def id="make-noid">make-noid</em> (frequency 0.0) (n 1) phases
<em class=def id="noid">noid</em> w (fm 0.0)
</pre>

<p>polyoid combines the first and second Chebyshev polynomials to provide
a sum of sinusoids each with arbitrary amplitude and initial-phase.
noid is a wrapper for polyoid that sets up n equal amplitude components, a generalization
of <a href="#ncosdoc">ncos and nsin</a>.
noid's phase argument can be a float-vector, <code>'min-peak</code>, <code>'max-peak</code>, or omitted (#f).
If omitted, the phases are set to random numbers between 0 and 2 pi; if
a float-vector, the float-vector's values are used as the phases; if 'max-peak, all phases are set
to pi/2 (ncos essentially &mdash; use <code>(make-float-vector n)</code> to get nsin);
and if 'min-peak, the minimum peak amplitude phases in <a href="sndscm.html#peakphasesdoc">peak-phases.scm</a> are used.
In the 'min-peak and 'max-peak cases, noid's output is normalized to fall between -1.0 and 1.0.
polyoid-env is an extension of polyoid that takes envelopes to control the amplitude and phase of each
harmonic.
</p>

<img src="pix/noidchoices.png" alt="noid choices">

<!--
  run -horizontal
  (do ((i 0 (+ i 1)))
      ((= i 4))
    (with-sound (:clipped #f :output (string-append "test-noid-" (number->string i) ".snd"))
      (let ((samps 44100)
            (gen (make-noid 100.0 32 (if (= i 0) 'max-peak
                                         (if (= i 1) (make-float-vector 32)
                                	     (if (= i 2) #f
						 'min-peak))))))
	(do ((i 0 (+ i 1)))
	    ((= i samps))
	  (outa i (noid gen 0.0))))))
-->

<p>We can use the <a href="sndscm.html#peakphasesdoc">peak-phases.scm</a> phases to reduce the "spikiness" of the waveform with any
set of components and component amplitudes.  We could, for example, change noid to use
</p>

<pre class="indented">
(set! (amps (+ j 1)) (/ (expt r (- i 1)) norm))
</pre>

<p>where "r" is the ratio between successive component amplitude: "nroid"?
This is not as pointless as it might at first appear.  Many of these waveforms actually
sound different, despite having the same (magnitude) spectrum; the minimum peak
version usually sounds raspier, and in the limit it can sound like white noise!
</p>

<!--
(with-sound (:clipped #f)
  (let* ((dur 2.0)
	 (samps (seconds->samples dur))
	 (gen1 (make-noid 40.0 128 'max-peak))
	 (gen2 (make-noid 40.0 128 'min-peak))
	 (ampf (make-env '(0 0 .1 1 1 1 2 .25 3 .25) :scaler 0.5 :duration dur))
	 (indf (make-env '(0 0 1 0 2 1 3 1) :duration dur)))
    (do ((i 0 (+ i 1)))
	((= i samps))
      (let ((ind (env indf)))
	(outa i (* (env ampf)
		   (+ (* ind 
			 (noid gen2 0.0))
		      (* (- 1.0 ind) 
			 (noid gen1 0.0)))))))))
-->

<!--
<img class="indented" src="noid2.png">
-->

<p>Check out the n=1024 case:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () 
  (let ((samps 44100)
	(gen (<em class=red>make-noid</em> 10.0 1024 'min-peak)))
    (do ((i 0 (+ i 1)))
	((= i samps))
      (<a class=quiet href="#outa">outa</a> i (* 0.5 (<em class=red>noid</em> gen 0.0))))))
</pre>

<div class="separator"></div>

<pre class="indented">
<em class=def id="make-asyfm">make-asyfm</em> (frequency 0.0) (ratio 1.0) (r 1.0) (index 1.0)
<em class=def id="asyfmJ">asyfm-J</em> gen (fm 0.0)
<em class=def id="asyfmI">asyfm-I</em> gen (fm 0.0)
<em class=def id="asyfm?">asyfm?</em> gen
</pre>

<p>These two generators produce the two flavors of asymmetric-fm.  asyfm-J is the same as the built-in asymmetric generator;
asyfm-I is the modified Bessel function version (the second formula in the <a href="#asymmetric-fm">asymmetric-fm</a> section).
</p>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-fmssb">make-fmssb</em> (frequency 0.0) (ratio 1.0) (index 1.0)
<em class=def id="fmssb">fmssb</em> gen (fm 0.0)
<em class=def id="fmssb?">fmssb?</em> gen
</pre>

<p>This generator produces the "gapped" spectra mentioned in <a href="fm.html">fm.html</a>. It is used extensively in the
various "imaginary machines".  Also included in this section of generators.scm is fpmc, an instrument
that performs FM with a complex index (complex in the sense of complex numbers). 
</p>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-blackman">make-blackman</em> frequency n ; 1 &lt;= n &lt;= 10
<em class=def id="blackman">blackman</em> gen (fm 0.0)
<em class=def id="blackman?">blackman?</em> gen
</pre>

<p>
This produces a Blackman-Harris sum of cosines of order 'n'.  It could be viewed as a special case of pulsed-env, or
as yet another "kernel" along the lines of <a href="#ncos">ncos</a>.
</p>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-sinc-train">make-sinc-train</em> frequency (n 1)
<em class=def id="sinc-train">sinc-train</em> gen (fm 0.0)
<em class=def id="sinc-train?">sinc-train?</em> gen
</pre>

<p>
This produces a sinc-train ((sin x)/x) with n components.  It is very similar to <a href="#ncos">ncos</a>.
</p>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-pink-noise">make-pink-noise</em> (n 1)
<em class=def id="pink-noise">pink-noise</em> gen
<em class=def id="pink-noise?">pink-noise?</em> gen
</pre>

<p>
This produces a reasonable approximation to 1/f noise, also known as pink-noise. 'n' sets the number of octaves used (starting at the high end);
12 is the recommended choice.  (If n=1, you get white noise).
</p>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-brown-noise">make-brown-noise</em> frequency (amplitude 1.0)
<em class=def id="brown-noise">brown-noise</em> gen
<em class=def id="brown-noise?">brown-noise?</em> gen
</pre>

<p>
This produces (unbounded) brownian noise.  'amplitude' sets the maximum size of individual jumps.
</p>
<div class="separator"></div>

<pre class="indented">
<em class=def id="make-green-noise">make-green-noise</em> (frequency 0.0) (amplitude 1.0) (low -1.0) (high 1.0)
<em class=def id="green-noise">green-noise</em> gen (fm 0.0)
<em class=def id="green-noise?">green-noise?</em> gen

<em class=def id="make-green-noise-interp">make-green-noise-interp</em> (frequency 0.0) (amplitude 1.0) (low -1.0) (high 1.0)
<em class=def id="green-noise-interp">green-noise-interp</em> gen (fm 0.0)
<em class=def id="green-noise-interp?">green-noise-interp?</em> gen
</pre>

<p>These two generators produce bounded brownian noise; "green-noise" was Michael McNabb's name for it.
Unlike CLM's <a href="#rand">rand</a> or <a href="#rand-interp">rand-interp</a> which
produce white noise centered around 0.0, green-noise wanders around, bouncing off its bounds
every now and then.  This produces a noise that can be similar to pink noise (see some graphs under <a href="#rand">rand</a>).
My informal explanation is that each time we bounce off an edge, we're transferring energy
from a low frequency into some higher frequency.  It is still brownian noise however.
The 'amplitude' argument controls how large individual steps can be; 'low' and 'high' set
the overall output bounds; 'frequency' controls how often a new random number is chosen.
Here's an instrument that fuzzes up its amplitude envelope a bit using green noise:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (green3 start dur freq amp amp-env noise-freq noise-width noise-max-step)
  (let* ((grn (<em class=red>make-green-noise-interp</em> :frequency noise-freq 
                                       :amplitude noise-max-step 
                                       :high (* 0.5 noise-width) :low (* -0.5 noise-width)))
	 (osc (<a class=quiet href="#make-oscil">make-oscil</a> freq))
	 (e (<a class=quiet href="#make-env">make-env</a> amp-env :scaler amp :duration dur))
	 (beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> start))
	 (end (+ beg (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur))))
    (do ((i beg (+ i 1)))
        ((= i end))
      (<a class=quiet href="#outa">outa</a> i (* (<a class=quiet href="#env">env</a> e) 
	         (+ 1.0 (<em class=red>green-noise-interp</em> grn))
		 (<a class=quiet href="#oscil">oscil</a> osc))))))

(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> () 
  (green3 0 2.0 440 .5 '(0 0 1 1 2 1 3 0) 100 .2 .02))
</pre>

<div class="separator"></div>

<pre class="indented">
<em class=def id="make-adjustable-square-wave">make-adjustable-square-wave</em> frequency (duty-factor 0.5) (amplitude 1.0)
<em class=def id="adjustable-square-wave">adjustable-square-wave</em> gen (fm 0.0)
<em class=def id="adjustable-square-wave?">adjustable-square-wave?</em> gen

<em class=def id="make-adjustable-triangle-wave">make-adjustable-triangle-wave</em> frequency (duty-factor 0.5) (amplitude 1.0)
<em class=def id="adjustable-triangle-wave">adjustable-triangle-wave</em> gen (fm 0.0)
<em class=def id="adjustable-triangle-wave?">adjustable-triangle-wave?</em> gen

<em class=def id="make-adjustable-sawtooth-wave">make-adjustable-sawtooth-wave</em> frequency (duty-factor 0.5) (amplitude 1.0)
<em class=def id="adjustable-sawtooth-wave">adjustable-sawtooth-wave</em> gen (fm 0.0)
<em class=def id="adjustable-sawtooth-wave?">adjustable-sawtooth-wave?</em> gen
</pre>

<p>
adjustable-square-wave produces a square-wave with optional "duty-factor" (ratio of pulse duration to pulse period).
The other two are similar, producing triangle and sawtooth waves.  There is also an adjustable-oscil.
Use mus-scaler to set the duty-factor at run-time.
</p>

<img class="indented" src="pix/adjustable.png" alt="mus-scaler adjusts">

<!-- adjustable.png:

(with-sound (:channels 4)
  (let* ((fsamps 500)
	 (freq (radians->hz (/ 1.0 fsamps)))
	 (sq (make-adjustable-square-wave freq 0.01))
	 (sw (make-adjustable-sawtooth-wave freq 0.01))
	 (tr (make-adjustable-triangle-wave freq 0.01))
	 (os (make-adjustable-oscil freq 0.01))
	 (pl (make-pulse-train freq))
	 (dur 1.0)
	 (samps (seconds->samples dur))
	 (ampf (make-env '(0 0 1 1 100 1 101 0) :duration dur))
	 (adjf (make-env '(0 .01 1 .99) :duration dur)))
    (do ((i 0 (+ i 1)))
	((= i samps))
      (let ((amp (env ampf))
	    (adj (env adjf))
	    (trigger (pulse-train pl)))

	(if (> trigger 0.1)
	    (begin
	      (set! (mus-scaler sq) adj)
	      (set! (mus-scaler sw) adj)
	      (set! (mus-scaler tr) adj)
	      (set! (mus-scaler os) adj)))

	(outa i (* amp (adjustable-square-wave sq)))
	(outb i (* amp (adjustable-sawtooth-wave sw)))
	(outc i (* amp (adjustable-triangle-wave tr)))
	(outd i (* amp (adjustable-oscil os)))
	))
    ))

(set! *selected-graph-color* (make-color 1 1 1))
(set! *selected-data-color* (make-color 0 0 0))
(set! (x-axis-label 0 0) "adjustable-square-wave, duty-factor from .01 to .99")
(set! (x-axis-label 0 1) "adjustable-sawtooth-wave")
(set! (x-axis-label 0 2) "adjustable-triangle-wave")
(set! (x-axis-label 0 3) "adjustable-oscil")
(set! *axis-numbers-font* *tiny-font*)
(set! *axis-label-font* "10x20")
-->

<p>A similar trick can make, for example, a squared-off triangle-wave:
</p>
<pre class="indented">
(gen (<a class=quiet href="#make-triangle-wave">make-triangle-wave</a> 200.0 :amplitude 4)) ; amp sets slope
...
(outa i (max -1.0 (min 1.0 (<a class=quiet href="#triangle-wave">triangle-wave</a> gen))))
</pre>

<div class="separator"></div>


<pre class="indented">
<em class=def id="make-round-interp">make-round-interp</em> frequency n amplitude
<em class=def id="round-interp">round-interp</em> gen (fm 0.0)
<em class=def id="round-interp?">round-interp?</em> gen
</pre>

<p>
This is a <a href="#rand-interp">rand-interp</a> generator feeding a <a href="#moving-average">moving-average</a> generator.  "n" is the length of the moving-average;
the higher "n", the more low-passed the output.
</p>
<img class="indented" src="pix/roundinterp.png" alt="round-interp">

<!--
(with-sound (:channels 5)
  (let ((gen0 (make-round-interp 100 1))
	(gen1 (make-round-interp 100 10))
	(gen2 (make-round-interp 100 100))
	(gen3 (make-round-interp 100 1000))
	(gen4 (make-round-interp 100 10000)))
       (do ((i 0 (+ i 1)))
	   ((= i 100000))
	 (out-any i (round-interp gen0) 0)
	 (out-any i (round-interp gen1) 1)
	 (out-any i (round-interp gen2) 2)
	 (out-any i (round-interp gen3) 3)
	 (out-any i (round-interp gen4) 4))))

(set! (x-axis-label 0 0) "round-interp, n=1")
(set! (x-axis-label 0 1) "round-interp, n=10")
(set! (x-axis-label 0 2) "round-interp, n=100")
(set! (x-axis-label 0 3) "round-interp, n=1000")
(set! (x-axis-label 0 4) "round-interp, n=10000")
(set! *axis-label-font* "-*-times-medium-r-normal-*-20-*-*-*-*-*-*-*")
-->

<div class="separator"></div>


<pre class="indented">
<A class=def>make-moving-sum</A> (n 128)
<em class=def id="moving-sum">moving-sum</em> gen y
<A class=def>moving-sum?</A> gen

<A class=def>make-moving-rms</A> (n 128)
<em class=def id="moving-rms">moving-rms</em> gen y
<A class=def>moving-rms?</A> gen

<A class=def>make-moving-length</A> (n 128)
<em class=def id="moving-length">moving-length</em> gen y
<A class=def>moving-length?</A> gen

<A class=def>make-weighted-moving-average</A> n
<em class=def id="weighted-moving-average">weighted-moving-average</em> gen y
<A class=def>weighted-moving-average?</A> gen

<A class=def>make-exponentially-weighted-moving-average</A> n
<em class=def id="exponentially-weighted-moving-average">exponentially-weighted-moving-average</em> gen y
<A class=def>exponentially-weighted-moving-average?</A> gen
</pre>

<p>
The "moving" generators are specializations of the <a href="#moving-average">moving-average</a>
generator.  moving-sum keeps the ongoing sum of absolute values, moving-length the square root of the sum
of squares, and moving-rms the square root of the sum of squares divided by the size.
moving-rms is used in <a href="sndscm.html#overlayrmsenv">overlay-rms-env</a> in draw.scm.
weighted-moving-average weights the
table entries by 1/n.  Similarly exponentially-weighted-moving-average applies exponential weights (it is
actually just a one-pole filter &mdash; this generator wins the "longest-name-for-simplest-effect" award).
Also defined, but not tested, is moving-variance; in the same mold, but not defined, are things like moving-inner-product and moving-distance.
</p>



<!-- bessel functions -->
<div class="innerheader">Bessel functions</div>

<pre class="indented">
<em class=def id="make-bess">make-bess</em> (frequency 0.0) (n 0)
<em class=def id="bess">bess</em> gen (fm 0.0)
<em class=def id="bess?">bess?</em> gen
</pre>

<!-- LATEX: & J_{n}(x) = \frac{a}{\sqrt{x}}\sin(x+\delta) + \frac{r_{n}(x)}{x^{\frac{3}{2}}} \\ -->

<p>bess produces the nth Bessel function.  The generator output is scaled to have a maximum of 1.0,
so bess's output is not the same as the raw bessel function value returned by <a href="extsnd.html#besj0">bes-jn</a>.
The "frequency" argument actually makes sense here because the Bessel functions
are close to damped sinusoids after their initial hesitation:
</p>
<img class="indented" src="pix/sceq24.png" alt="Jn">
<p>
where the variables other than x remain bounded as x increases.  This explains, in a sketchy way, why Jn(cos) and Jn(Jn)
behave like FM.  To see how close these are to FM, compare the expansion of J0(sin) with FM's cos(sin):
</p>

<!-- LATEX:
sceq35:
& J_{0}(B \sin x) = J_{0}^{2}\Big(\frac{B}{2}\Big)+2\sum_{k=1}^{\infty} J_{k}^{2}\Big(\frac{B}{2}\Big)\cos2kx \\
& \cos(B \sin x) = J_{0}(B) + 2 \sum_{k=1}^{\infty} J_{2k}(B) \cos 2kx \\
-->

<img class="indented" src="pix/sceq35.png" alt="J(sin) and cos(sin)">

<p>Except for jpcos, the rest of the generators in this section suffer a similar fate.  From a waveshaping perspective,
we're using a sinusoid, or a modulated sinusoid, to index into the near-zero portion of a Bessel
function, and the result is sadly reminiscent of standard FM.  But they're such pretty formulas;
I must be missing something.
</p>


<div class="separator"></div>

<pre class="indented">
<em class=def id="make-j0evencos">make-j0evencos</em> (frequency 0.0) (index 1.0)
<em class=def id="j0evencos">j0evencos</em> gen (fm 0.0)
<em class=def id="j0evencos?">j0evencos?</em> gen
</pre>

<p>j0evencos produces the J0(index * sin(x)) case mentioned above (with the DC component subtracted out).
If you sweep the index, the bandwidth is the same as in normal FM (J2k(B) is about 3log(k)*Jk(B/2)^2),
but the B/2 factor causes
the individual component amplitudes to follow the Bessel functions half as fast. 
So j0evencos produces a spectral sweep that is like FM's but smoother.
</p>

<img class="indented" src="pix/j0fm.png" alt="compare FM and j0evencos">

<img class="indented" src="pix/j0jfm.png" alt="compare FM and j0evencos">


<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:channels 2)
  (let* ((dur 1.0)
         (end (<a class=quiet href="#secondstosamples">seconds-&gt;samples</a> dur))
         (jmd (<em class=red>make-j0evencos</em> 200.0))
	 (fmd (<a class=quiet href="#make-oscil">make-oscil</a> 200.0))
         (ampf (<a class=quiet href="#make-env">make-env</a> '(0 0  1 1  20 1  21 0) :scaler 0.5 :duration dur))
         (indf (<a class=quiet href="#make-env">make-env</a> '(0 0  1 20) :duration dur)))
    (do ((i 0 (+ i 1)))
	((= i end))
      (let ((ind (<a class=quiet href="#env">env</a> indf))
	    (vol (<a class=quiet href="#env">env</a> ampf)))
	(set! (<em class=red>jmd 'index</em>) ind)
	(<a class=quiet href="#outa">outa</a> i (* vol (- (cos (* ind (<a class=quiet href="#oscil">oscil</a> fmd))) 
                          (<a class=quiet href="extsnd.html#besj0">bes-j0</a> ind)))) ; subtract out DC (see cos(B sin x) above)
	(<a class=quiet href="#out-any">outb</a> i (* vol (<em class=red>j0evencos</em> jmd)))))))
</pre>

<!--
snd -horizontal

(define* (fm beg dur freq amp mc-ratio index (index-env '(0 1 100 1)))
  (let* ((start (seconds->samples beg))
         (end (+ start (seconds->samples dur)))
         (md (make-oscil (* freq mc-ratio)))
         (ampf (make-env '(0 0 1 1 20 1 21 0) :scaler amp :duration dur)) 
         (indf (make-env index-env :scaler index :duration dur)))
       (do ((i start (+ i 1)))
	   ((= i end))
	 (let ((ind (env indf)))
	   (outa i (* (env ampf)  
		      (- (cos (* ind (oscil md)))
			 (bes-j0 ind))))))))

(with-sound ("test.snd") (fm 0 1.0 2000.0 0.5 .1 20.0 '(0 0 1 1)))

(define* (jfm beg dur freq amp mc-ratio index (index-env '(0 1 100 1)))
  (let* ((start (seconds->samples beg))
         (end (+ start (seconds->samples dur)))
         (md (make-j0evencos (* freq mc-ratio)))
         (ampf (make-env '(0 0 1 1 20 1 21 0) :scaler amp :duration dur)) 
         (indf (make-env index-env :scaler index :duration dur)))
       (do ((i start (+ i 1)))
	   ((= i end))
	 (set! (md 'index) (env indf))
	 (outa i (* (env ampf)
                    (j0evencos md))))))

(with-sound ("test1.snd") (jfm 0 1.0 2000.0 0.5 .1 20.0 '(0 0 1 1)))

x 314 1.36
y 327 .4
z 0 1.9
4 0.24
blackman6 2048

(set! *selected-graph-color* (make-color 1 1 1))
-->
<div class="separator"></div>

<pre class="indented">
<em class=def id="make-j0j1cos">make-j0j1cos</em> (frequency 0.0) (index 0.0)
<em class=def id="j0j1cos">j0j1cos</em> gen fm
<em class=def id="j0j1cos?">j0j1cos?</em> gen
</pre>

<img class="indented" src="pix/sceq36.png" alt="j0j1 formulsa">

<p>
This uses J0(index * cos(x)) + J1(index * cos(x)) to produce a full set of cosines.  It is not yet normalized correctly,
and is very similar to normal FM.
</p>

<div class="separator"></div>

<pre class="indented">
<em class=def id="make-izcos">make-izcos</em> (frequency 0.0) (r 1.0)
<em class=def id="izcos">izcos</em> gen (fm 0.0)
<em class=def id="izcos?">izcos?</em> gen
</pre>

<img class="indented" src="pix/sceq39.png" alt="I(k) sum">

<p>This produces a sum of cosines scaled by In(r), again very similar to normal FM.
</p>

<div class="separator"></div>

<pre class="indented">
<em class=def id="make-jjcos">make-jjcos</em> (frequency 0.0) (r 0.5) (a 1.0) (k 1.0)
<em class=def id="jjcos">jjcos</em> gen (fm 0.0)
<em class=def id="jjcos?">jjcos?</em> gen

<em class=def id="make-j2cos">make-j2cos</em> (frequency 0.0) (r 0.5) (n 1)
<em class=def id="j2cos">j2cos</em> gen (fm 0.0)
<em class=def id="j2cos?">j2cos?</em> gen

<em class=def id="make-jpcos">make-jpcos</em> (frequency 0.0) (r 0.5) (a 0.0) (k 1.0)
<em class=def id="jpcos">jpcos</em> gen (fm 0.0)
<em class=def id="jpcos?">jpcos?</em> gen

<em class=def id="make-jncos">make-jncos</em> (frequency 0.0) (r 0.5) (a 1.0) (n 0)
<em class=def id="jncos">jncos</em> gen (fm 0.0)
<em class=def id="jncos?">jncos?</em> gen
</pre>

<p>These produce a sum of cosines scaled by a product of Bessel functions; in a sense, there are two, or maybe three "indices".
Normalization is handled correctly at least for jpcos.  Of the four, jpcos seems the most interesting.  "a" should not equal "r";
in general as a and r approach 1.0, the spectrum approaches "k" components, sometimes in a highly convoluted manner.
</p>

<table>
<tr><td>jjcos:</td><td><img class="indented" src="pix/sceq31.png" alt="more sums"></td></tr>
<tr><td>j2cos:</td><td><img class="indented" src="pix/sceq34.png" alt="more sums"></td></tr>
<tr><td>jpcos:</td><td><img class="indented" src="pix/sceq33.png" alt="more sums"></td></tr>
<tr><td>jncos:</td><td><img class="indented" src="pix/sceq32.png" alt="more sums"></td></tr>
</table>

<div class="separator"></div>

<pre class="indented">
<em class=def id="make-jycos">make-jycos</em> (frequency 0.0) (r 1.0) (a 1.0)
<em class=def id="jycos">jycos</em> gen (fm 0.0)
<em class=def id="jycos?">jycos?</em> gen
</pre>

<p>This uses bes-y0 to produce components scaled by Yn(r)*Jn(a).  bes-y0(0) is -inf, so a^2 + r^2 should be greater than 2ar,
and r should be greater than 0.0.  Tricky to use.  (If you get an inf or a NaN from division by zero or whatever in Scheme,
both the time and frequency graphs will be unhappy).
</p>





<!-- finite sums -->
<div class="innerheader">finite sums</div>

<p>These generators produce a set of n sinusoids.
With a bit of bother, 
they could be done with polywave.  I don't
think there would be any difference, even taking FM into account. 
</p>

<pre class="indented">
<em class=def id="make-nssb">make-nssb</em> (frequency 0.0) (ratio 1.0) (n 1)
<em class=def id="nssb">nssb</em> gen (fm 0.0)
<em class=def id="nssb?">nssb?</em> gen
</pre>

<p>nssb is the single side-band version of ncos and nsin.  It is very similar to <a href="#nxysin">nxysin</a> and <a href="#nxycos">nxycos</a>.
</p>

<div class="separator"></div>

<pre class="indented">
<em class=emdef>make-ncos2</em> (frequency 0.0) (n 1)
<em class=emdef id="ncos2">ncos2</em> gen (fm 0.0)
<em class=def id="ncos2?">ncos2?</em> gen
</pre>

<p>This is the Fejer kernel.  The i-th harmonic amplitude is (n-i)/(n+1).
</p>

<!-- LATEX: &\frac{\sin^{2} \frac{1}{2}nx}{\sin^{2} \frac{1}{2}x} = \frac{n}{2} + \sum_{k=1}^{n-1} (n-k)\cos kx -->

<img class="indented" src="pix/sceq23.png" alt="sum of cosines">
<div class="separator"></div>

<pre class="indented">
<em class=emdef>make-ncos4</em> (frequency 0.0) (n 1)
<em class=emdef>ncos4</em> gen (fm 0.0)
<em class=def id="ncos4?">ncos4?</em> gen
</pre>

<p>This is the Jackson kernel, the square of ncos2.
</p>

<!-- LATEX: &\Bigg(\frac{\sin(n+\frac{1}{2})x}{\sin \frac{x}{2}}\Bigg)^{4} -->
<!-- pointless...
<img class="indented" src="pix/sceq24.png" alt="sum of cosines">
-->



<pre class="indented">
<em class=emdef>make-npcos</em> (frequency 0.0) (n 1)
<em class=emdef>npcos</em> gen (fm 0.0)
<em class=def id="npcos?">npcos?</em> gen
</pre>

<p>This is the Poussin kernel, a combination of two ncos2 generators, one at "n" subtracted from twice another at 2n+1.
</p>


<pre class="indented">
<em class=def id="make-n1cos">make-n1cos</em> (frequency 0.0) (n 1)
<em class=def id="n1cos">n1cos</em> gen (fm 0.0)
<em class=def id="n1cos?">n1cos?</em> gen
</pre>

<p>Another spikey waveform, very similar to ncos2 above.
</p>

<img class="indented" src="pix/sceq45.png" alt="linear cosines">
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-nxycos">make-nxycos</em> (frequency 0.0) (ratio 1.0) (n 1)
<em class=def id="nxycos">nxycos</em> gen (fm 0.0)
<em class=def id="nxycos?">nxycos?</em> gen

<em class=def id="make-nxysin">make-nxysin</em> (frequency 0.0) (ratio 1.0) (n 1)
<em class=def id="nxysin">nxysin</em> gen (fm 0.0)
<em class=def id="nxysin?">nxysin?</em> gen

<em class=def id="make-nxy1cos">make-nxy1cos</em> (frequency 0.0) (ratio 1.0) (n 1)
<em class=def id="nxy1cos">nxy1cos</em> gen (fm 0.0)
<em class=def id="nxy1cos?">nxy1cos?</em> gen

<em class=def id="make-nxy1sin">make-nxy1sin</em> (frequency 0.0) (ratio 1.0) (n 1)
<em class=def id="nxy1sin">nxy1sin</em> gen (fm 0.0)
<em class=def id="nxy1sin?">nxy1sin?</em> gen
</pre>

<p>These produce a sum of "n" sinsoids starting at "frequency", spaced by "ratio".  Since "frequency" can be treated
as the carrier, there's no point in an ssb version.  nxy1cos is the same as nxycos, but every other
component is multiplied by -1, and "n" produces 2n components.
Normalization in the "sin" cases is tricky.  If ratio is 1, we can use nsin's normalization, and if ratio = 2, noddsin's,
but otherwise nxysin currently uses 1/n.  This ensures that the generator output is always between -1 and 1,
but in some cases (mainly involving low "n" and simple "ratio"), the output might not be full amplitude.  nxy1sin is
even trickier, so it divides by "n".
</p>

<div class="separator"></div>

<pre class="indented">
<em class=def id="make-noddcos">make-noddcos</em> (frequency 0.0) (n 1)
<em class=def id="noddcos">noddcos</em> gen (fm 0.0)
<em class=def id="noddcos?">noddcos?</em> gen

<em class=def id="make-noddsin">make-noddsin</em> (frequency 0.0) (n 1)
<em class=def id="noddsin">noddsin</em> gen (fm 0.0)
<em class=def id="noddsin?">noddsin?</em> gen

<em class=def id="make-noddssb">make-noddssb</em> (frequency 0.0) (ratio 1.0) (n 1)
<em class=def id="noddssb">noddssb</em> gen (fm 0.0)
<em class=def id="noddssb?">noddssb?</em> gen
</pre>


<!-- LATEX: &\sum_{k=1}^{n}\cos(2k-1)x=\frac{1}{2}\frac{\sin 2nx}{\sin x} \\ -->

<p>These produce the sum of "n" equal amplitude odd-numbered sinusoids:
</p>

<img class="indented" src="pix/sceq29.png" alt="sum of cosines">

<!-- LATEX: &\sum_{k=1}^{n}\sin(2k-1)x=\frac{\sin^{2}nx}{\sin x} \\ -->

<img class="indented" src="pix/sceq28.png" alt="sum of sines">

<p>The corresponding "even" case is the same as ncos with twice the frequency.  noddsin produces a somewhat clarinet-like tone:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:play #t)
  (let ((gen (<em class=red>make-noddsin</em> 300 :n 3))
	(ampf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 2 1 3 0) :length 40000 :scaler .5)))
     (do ((i 0 (+ i 1)))
         ((= i 40000))
       (<a class=quiet href="#outa">outa</a> i (* (<a class=quiet href="#env">env</a> ampf) (<em class=red>noddsin</em> gen))))))
</pre>

<p>noddsin normalization is the same as nsin.  The peak happens half as far from the 0 crossing as in nsin (3pi/(4n) for nsin, 
and 3pi/(8n) for noddsin (assuming large n)), and its amplitude is 8n*sin^2(3pi/8)/(3pi), just as in nsin.  The noddsin generator scales its output
by the inverse of this, so it is always between -1 and 1.
</p>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-nrcos">make-nrcos</em> (frequency 0.0) (n 1) (r 0.5)             ; -1.0 &lt; r &lt; 1.0
<em class=def id="nrcos">nrcos</em> gen (fm 0.0)
<em class=def id="nrcos?">nrcos?</em> gen

<em class=def id="make-nrsin">make-nrsin</em> (frequency 0.0) (n 1) (r 0.5)             ; -1.0 &lt; r &lt; 1.0
<em class=def id="nrsin">nrsin</em> gen (fm 0.0)
<em class=def id="nrsin?">nrsin?</em> gen

<em class=def id="make-nrssb">make-nrssb</em> (frequency 0.0) (ratio 1.0) (n 1) (r 0.5) ; 0.0 &lt;= r &lt; 1.0
<em class=def id="nrssb">nrssb</em> gen (fm 0.0)
<em class=def id="nrssbinterp">nrssb-interp</em> gen fm interp
<em class=def id="nrssb?">nrssb?</em> gen
</pre>

<p>These produce the sum of "n" sinusoids, with successive sinusoids scaled by "r"; the nth component has amplitude r^n.
nrsin is just a wrapper for <a href="#nrxysin">nrxysin</a>, and the other two are obviously variants of <a href="#nrxycos">nrxycos</a>.
In the nrssb-interp generator, the "interp" argument interpolates between the upper (interp=1.0) and lower (interp=-1.0) side bands.
</p>

<p>The instrument lutish uses nrcos: <code>lutish beg dur freq amp</code>:
</p>

<pre class="indented">
    (<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:play #t)
      (do ((i 0 (+ i 1)))
          ((= i 10))
        (lutish (* i .1) 2 (* 100 (+ i 1)) .05)))
</pre>

<p>The instrument oboish uses nrssb: <code>oboish beg dur freq amp amp-env</code>:
</p>

<pre class="indented">
    (<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:play #t)
      (do ((i 0 (+ i 1)))
          ((= i 10))
        (oboish (* i .3) .4 (+ 100 (* 50 i)) .05 '(0 0 1 1 2 1 3 0))))
</pre>

<p>organish also uses nrssb: <code>organish beg dur freq amp fm-index amp-env</code>:
</p>

<pre class="indented">
    (<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:play #t)
      (do ((i 0 (+ i 1)))
          ((= i 10))
        (organish (* i .3) .4 (+ 100 (* 50 i)) .5 1.0 #f)))
</pre>

<div class="separator"></div>


<pre class="indented">
<em class=def id="make-nkssb">make-nkssb</em> (frequency 0.0) (ratio 1.0) (n 1)
<em class=def id="nkssb">nkssb</em> gen (fm 0.0)
<em class=def id="nkssbinterp">nkssb-interp</em> gen fm interp
<em class=def id="nkssb?">nkssb?</em> gen
</pre>

<p>This generator produces the single side-band version of the sum of "n" sinusoids, where the nth component has amplitude n.
In the nkssb-interp generator, the "interp" argument interpolates between the upper and lower side bands.
The instrument nkssber uses nkssb-interp:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:play #t)
  (nkssber 0 1 1000 100 5 5 0.5)
  (nkssber 1 2 600 100 4 1 0.5)
  (nkssber 3 2 1000 540 3 3 0.5)
  (nkssber 5 4 300 120 2 0.25 0.5)
  (nkssber 9 1 30 4 40 0.5 0.5)
  (nkssber 10 1 20 6 80 0.5 0.5))
</pre>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-nsincos">make-nsincos</em> (frequency 0.0) (n 1)
<em class=def id="nsincos">nsincos</em> gen (fm 0.0)
<em class=def id="nsincos?">nsincos?</em> gen
</pre>

<p>This generator produces a sum of n cosines scaled by sin(k*pi/(n+1))/sin(pi/(n+1)).
</p>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-nchoosekcos">make-nchoosekcos</em> (frequency 0.0) (ratio 1.0) (n 1)
<em class=def id="nchoosekcos">nchoosekcos</em> gen (fm 0.0)
<em class=def id="nchoosekcos?">nchoosekcos?</em> gen
</pre>

<p>This generator produces a sum of n cosines scaled by the binomial coefficients.  If n is even, the last term is halved.
All these "finite sum" generators are a bit inflexible, and sound more or less the same.  One (desperate) countermeasure
is amplitude modulation:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> ()
  (let ((modulator (<em class=red>make-nchoosekcos</em> 100.0 1.0 4))
	(carrier (<a class=quiet href="#make-nrcos">make-nrcos</a> 2000.0 :n 3 :r .5)))
    (do ((i 0 (+ i 1))) ((= i 20000))
      (<a class=quiet href="#outa">outa</a> i (* .5 (<a class=quiet href="#nrcos">nrcos</a> carrier) 
                    (<em class=red>nchoosekcos</em> modulator))))))
</pre>

<img src="pix/nkcos.png" alt="am nchoosekcos">




<!-- infinite sums -->
<div class="innerheader">infinite sums</div>

<pre class="indented">
<em class=def id="make-rcos">make-rcos</em> (frequency 0.0) (r 0.5) ; -1.0 &lt; r &lt; 1.0
<em class=def id="rcos">rcos</em> gen (fm 0.0)
<em class=def id="rcos?">rcos?</em> gen

<em class=def id="make-rssb">make-rssb</em> (frequency 0.0) (ratio 1.0) (r 0.5) ; -1.0 &lt; r &lt; 1.0
<em class=def id="rssb">rssb</em> gen (fm 0.0)
<em class=def id="rssbinterp">rssb-interp</em> gen fm interp
<em class=def id="rssb?">rssb?</em> gen

<em class=def id="make-rxycos">make-rxycos</em> (frequency 0.0) (ratio 1.0) (r 0.5) ; -1.0 &lt; r &lt; 1.0
<em class=def id="rxycos">rxycos</em> gen (fm 0.0)
<em class=def id="rxycos?">rxycos?</em> gen

<em class=def id="make-rxysin">make-rxysin</em> (frequency 0.0) (ratio 1.0) (r 0.5) ; -1.0 &lt; r &lt; 1.0
<em class=def id="rxysin">rxysin</em> gen (fm 0.0)
<em class=def id="rxysin?">rxysin?</em> gen
</pre>

<p>These generators produce an infinite sum of sinusoids, each successive component scaled by "r" (so the nth component has amplitude r^n).
The bump instrument uses rssb-interp: <code>bump beg dur freq amp f0 f1 f2</code>:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:play #t)
  (do ((k 0 (+ k 1))) 
      ((= k 10))
    (bump (* 0.4 k) 1 (* 16.3 (expt 2.0 (+ 3 (/ k 12)))) .5 520 1190 2390))
  (do ((k 0 (+ k 1))) 
      ((= k 10))
    (let* ((freq (* 16.3 (expt 2.0 (+ 3 (/ k 12)))))
	   (scl (sqrt (/ freq 120))))
      (bump (+ 4 (* 0.4 k)) 1 freq  .5 (* scl 520) (* scl 1190) (* scl 2390)))))
</pre>

<p>As with all the "infinite sums" generators, aliasing is a major concern.  We can use the following
relatively conservative function to find the highest safe "r" given the current fundamental and sampling rate:
</p>

<pre class="indented">
(define (safe-r-max freq srate) ; the safe-rxycos generator in generators.scm has this built-in
  (expt .001 (/ 1.0 (floor (/ srate 3 freq)))))
</pre>


<p>
If you go over that value, be prepared for some very unintuitive behavior!  For example,
at an srate of 44100:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:channels 2)
  (let ((gen1 (<em class=red>make-rcos</em> 1050 0.99))
        ;; r=.6 or so is the safe max
	(gen2 (<em class=red>make-rcos</em> 1048 0.99)))
    (do ((i 0 (+ i 1)))
	((= i 88200))
      (<a class=quiet href="#outa">outa</a> i (<em class=red>rcos</em> gen1))
      (<a class=quiet href="#outa">outb</a> i (<em class=red>rcos</em> gen2)))))
</pre>

<p>In the first case, all the aliased harmonics line up perfectly with the
unaliased ones because 21*1050 is 22050, but in the second case,
we get (for example) the strong 84 Hz component because the 42nd harmonic
which falls at 44100 - 42*1048 = 84 still has an amplitude of 0.99^42 = .66!
</p>

<img class="indented" src="pix/rcos.png" alt="rcos aliased">

<p>Another artifact of aliasing is that at some frequencies, 
for example at 100 Hz, and a sampling rate of 44100, if r is -0.99 and the initial phase is 0.5*pi, or if r is 0.99 and the initial phase is 1.5*pi, the peak amp
is only 0.6639.  Finally(?),
there's a sharp discontinuity (a click) as you sweep r through 0.0.  As in nrxycos, the waveforms produced by r and -r
are the same, but there's an overall phase difference of pi.  
</p>

<p>Other notes: the output of rssb is not normalized, nor is rxysin.
</p>

<!--
(set! (x-axis-label 0 0 0) "rcos freq=1050 r=.99")
(set! (x-axis-label 0 1 0) "rcos freq=1048 r=.99")
(set! *axis-label-font* "9x15")
-->

<div class="separator"></div>


<pre class="indented">
<em class=def id="make-ercos">make-ercos</em> (frequency 0.0) (r 0.5) ; r &gt; 0.0
<em class=def id="ercos">ercos</em> gen (fm 0.0)
<em class=def id="ercos?">ercos?</em> gen

<em class=def id="make-erssb">make-erssb</em> (frequency 0.0) (ratio 1.0) (r 0.5)
<em class=def id="erssb">erssb</em> gen (fm 0.0)
<em class=def id="erssb?">erssb?</em> gen
</pre>

<p>These produce a sum of sinusoids, each scaled by e^(-kr), a special case of rcos.  Our safe (minimum) "r" here becomes <code>(/ (log 0.001) (floor (/ srate (* -3 freq))))</code>.
The ercoser instrument uses ercos:
<code>ercoser beg dur freq amp r</code>:
</p>

<pre class="indented">
    (<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:play #t)
      (ercoser 0 1 100 .5 0.1))
</pre>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-eoddcos">make-eoddcos</em> (frequency 0.0) (r 0.5)
<em class=def id="eoddcos">eoddcos</em> gen (fm 0.0)
<em class=def id="eoddcos?">eoddcos?</em> gen
</pre>

<p>This produces a sum of odd harmonics, each scaled by e^r(2k-1)/(2k-1).  As "r" approches 0.0, this approaches a square wave.
</p>

<pre class="indented">
    (<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:play #t)
      (let ((gen1 (<em class=red>make-eoddcos</em> 400.0 :r 0.0))
	    (gen2 (<a class=quiet href="#make-oscil">make-oscil</a> 400.0))
	    (a-env (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1) :length 10000)))
        (do ((i 0 (+ i 1)))
	    ((= i 10000))
	  (set! (gen1 'r) (<a class=quiet href="#env">env</a> a-env))
 	  (<a class=quiet href="#outa">outa</a> i (* .5 (<em class=red>eoddcos</em> gen1 (* .1 (<a class=quiet href="#oscil">oscil</a> gen2))))))))
</pre>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-rkcos">make-rkcos</em> (frequency 0.0) (r 0.5) ; -1.0 &lt; r &lt; 1.0
<em class=def id="rkcos">rkcos</em> gen (fm 0.0)
<em class=def id="rkcos?">rkcos?</em> gen

<em class=def id="make-rksin">make-rksin</em> (frequency 0.0) (r 0.5) ; -1.0 &lt; r &lt; 1.0
<em class=def id="rksin">rksin</em> gen (fm 0.0)
<em class=def id="rksin?">rksin?</em> gen

<em class=def id="make-rkssb">make-rkssb</em> (frequency 0.0) (ratio 1.0) (r 0.5) ; -1.0 &lt; r &lt; 1.0
<em class=def id="rkssb">rkssb</em> gen (fm 0.0)
<em class=def id="rkssb?">rkssb?</em> gen
</pre>

<!--
(with-sound ("r7.snd")
  (let ((gen (make-rksin 100.0 :r .7)))
    (do ((i 0 (+ i 1)))
        ((= i 44100))
      (outa i (* 0.5 (rksin gen))))))
-->

<p>These produce a sum of sinusoids scaled by (r^k)/k.  As r approaches 1.0 or -1.0, rksin approaches a sawtooth.  
</p>

<img src="pix/rksin3.png" alt="sawtooths">

<p>As with rcos, we
can calculate the safe maximum r, given the current srate and frequency (this function is perhaps too cautious...):
</p>

<pre class="indented">
    (define (safe-rk-max freq srate)
      (let ((topk (floor (/ srate (* 3 freq)))))
        (min 0.999999 (expt (* .001 topk) (/ 1.0 topk)))))
</pre>

<p>Similar to rkcos is (expt (asin (sqrt (oscil x))) 2).
rksin and rkcos provide a nice demonstration of how insensitive the ear is to phase.  These two waveforms look different, but
have the same timbre. The sawtooth sounds louder to me, despite having the same peak amplitude.
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:channels 2)
  (let ((gen1 (<em class=red>make-rkcos</em> 200.0 :r 0.9))
        (gen2 (<em class=red>make-rksin</em> 200.0 :r 0.9)))
    (do ((i 0 (+ i 1)))
	((= i 100000))
      (<a class=quiet href="#outa">outa</a> i (* .95 (<em class=red>rkcos</em> gen1)))
      (<a class=quiet href="#outa">outb</a> i (* .95 (<em class=red>rksin</em> gen2))))))

&gt; (channel-rms 0 0) ; from dsp.scm
0.305301097090353
&gt; (channel-rms 0 1)
0.627769794744852
</pre>

<img class="indented" src="pix/rksin.png" alt="sin vs cos">

<p>We might conclude that the RMS value gives the perceived amplitude, but
in the next case, the RMS values are the same, and the peak amplitudes
differ by a factor of 3.  I think the one with the higher peak amplitude sounds louder.
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:channels 2)
  (let ((gen1 (<a class=quiet href="#make-adjustable-square-wave">make-adjustable-square-wave</a> 400 
	        :duty-factor .75 :amplitude .25))
	(gen2 (<a class=quiet href="#make-adjustable-square-wave">make-adjustable-square-wave</a> 400 
                :duty-factor .11 :amplitude .75))
	(flt1 (<a class=quiet href="#make-moving-average">make-moving-average</a> 10))
	(flt2 (<a class=quiet href="#make-moving-average">make-moving-average</a> 10)))
    (do ((i 0 (+ i 1)))
	((= i 50000))
      (<a class=quiet href="#outa">outa</a> i (<a class=quiet href="#moving-average">moving-average</a> flt1 
                (<a class=quiet href="#adjustable-square-wave">adjustable-square-wave</a> gen1)))
      (<a class=quiet href="#outa">outb</a> i (<a class=quiet href="#moving-average">moving-average</a> flt2 
                (<a class=quiet href="#adjustable-square-wave">adjustable-square-wave</a> gen2))))))
</pre>

<img class="indented" src="pix/rmspk.png" alt="rms vs peak">


<p>Since clipping is a disaster, we focus on peak amplitudes in the generators.
</p>


<!--
(set! *selected-graph-color* (make-color 1 1 1))
(set! *selected-data-color* (make-color 0 0 0))

(set! (x-axis-label 0 0) "rkcos, r=.9")
(set! (x-axis-label 0 1) "rksin, r=.9")
(set! *axis-label-font* "9x15")

(set! (x-axis-label 0 0) "rms: .21, peak amp: .25")
(set! (x-axis-label 0 1) "rms: .21, peak amp: .75")
-->

<div class="separator"></div>


<pre class="indented">
<em class=def id="make-rk!cos">make-rk!cos</em> (frequency 0.0) (r 0.5)  ; rk!cos is a special case of rxyk!cos
<em class=def id="rk!cos">rk!cos</em> gen (fm 0.0)
<em class=def id="rk!cos?">rk!cos?</em> gen

<em class=def id="make-rk!ssb">make-rk!ssb</em> (frequency 0.0) (ratio 1.0) (r 0.5)
<em class=def id="rk!ssb">rk!ssb</em> gen (fm 0.0)
<em class=def id="rk!ssb?">rk!ssb?</em> gen

<em class=def id="make-rxyk!cos">make-rxyk!cos</em> (frequency 0.0) (ratio 1.0) (r 0.5)
<em class=def id="rxyk!cos">rxyk!cos</em> gen (fm 0.0)
<em class=def id="rxyk!cos?">rxyk!cos?</em> gen

<em class=def id="make-rxyk!sin">make-rxyk!sin</em> (frequency 0.0) (ratio 1.0) (r 0.5)
<em class=def id="rxyk!sin">rxyk!sin</em> gen (fm 0.0)
<em class=def id="rxyk!sin?">rxyk!sin?</em> gen
</pre>


<!-- LATEX: for rk!cos
&\sum_{k=1}^{\infty}\frac{p^{k}\sin kx}{k!} = e^{p\cos x}\sin(p\sin x) \\
&\sum_{k=0}^{\infty}\frac{p^{k}\cos kx}{k!} = e^{p\cos x}\cos(p\sin x) \\
-->

<p>These produce a sum of sinusoids scaled by (r^k)/k!.  
The k! denominator dominates eventually, so r * ratio * frequency is approximately the spectral center
(the ratio between successive harmonic amplitudes is (r^(k+1)/(k+1)!)/(r^k/k!) = r/(k+1), which
becomes less than 1.0 at k=r).
For example, in the graph on the right, the frequency is 100 and r is 30, so the center of the spectrum is around 3kHz.
Negative "r" gives the same spectrum as positive, but the waveform's initial-phase is shifted by pi.
The (very) safe maximum "r" is:
</p>

<pre class="indented">
  (define (safe-rk!-max freq srate)
    (let ((topk (floor (/ srate 3 freq))))
      (expt (* .001 (factorial topk)) (/ 1.0 topk))))
                  ;; factorial is in numerics.scm
</pre>

<img src="pix/rkbang.png" alt="rk!cos spectrum">


<p>As in other such cases, varying "r" gives changing spectra.  You can sweep r through 0 smoothly except in rk!cos where you'll get a click.
Coupled with the fm argument, these generators provide an extension of multi-carrier FM, similar in effect to the "leap-frog" FM voice.
Here is a use of rk!cos to make a bird twitter:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:play #t :scaled-to .5)
  (do ((k 0 (+ k 1)))
      ((= k 6))
    (let ((gen (<em class=red>make-rk!cos</em> 3000.0 :r 0.6)) 
          (ampf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1 2 1 3 0) :length 3000))
	  (frqf (<a class=quiet href="#make-env">make-env</a> '(0 0 1 1) :base .1 :scaler (<a class=quiet href="#hztoradians">hz-&gt;radians</a> 2000) :length 3000)))
     (do ((i 0 (+ i 1)))
         ((= i 3000)) 
       (<a class=quiet href="#outa">outa</a> (+ i (* k 4000)) 
             (* (<a class=quiet href="#env">env</a> ampf) 
	        (<em class=red>rk!cos</em> gen (<a class=quiet href="#env">env</a> frqf))))))))
</pre>

<p>The instrument bouncy uses rk!ssb: <code>bouncy beg dur freq amp (bounce-freq 5) (bounce-amp 20)</code>
</p>

<pre class="indented">
    (<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:play #t)
      (bouncy 0 2 200 .5 3 2))
</pre>

<p>brassy (also in generators.scm) uses rxyk!cos, but it is more of an experiment with envelopes than spectra.
It takes a gliss envelope and turns it into a series of quick jumps between harmonics, handling both the
pitch and the index ("r") of the rxyk!cos generator.  The effect is vaguely brass-like.
</p>

<div class="separator"></div>


<pre class="indented">
<em class=def id="make-r2k!cos">make-r2k!cos</em> (frequency 0.0) (r 0.5) (k 0.0)
<em class=def id="r2k!cos">r2k!cos</em> gen (fm 0.0)
<em class=def id="r2k!cos?">r2k!cos?</em> gen
</pre>

<p>
This generator produces a sum of cosines with a complicated-looking formula for
the component amplitudes.  It's actually pretty simple, as this graph shows.
The "F" notation stands for a hypergeometric series, a generalization
of sinusoids and Bessel functions.  
</p>

<!-- LATEX: sceq30:
  &(1 - 2r \cos \theta + r^{2})^{-k} = \frac{1}{2} {}_{2}F_{1}(k, k; 1; r^{2}) + \sum_{n=1}^{\infty} \frac{(k)_{n}}{n!} r^{n} {}_{2}F_{1}(k, k+n; n+1; r^{2}) \cos n\theta
-->


<img class="indented" src="pix/sceq30.png" alt="sum of sines">
<br>
<img class="indented" src="pix/r2kfactcos.png" alt="r2k!cos spectra">


<!-- r2kfactcos.png:

(with-sound (:clipped #f :statistics #t :play #t :scaled-to .5)
  (let* ((gen (make-r2k!cos 440.0 :r 0.65 :k 3.0)) 
	 (dur 2.0)
	 (samps (seconds->samples dur))
	 (indf (make-env '(0 0 1 1) :duration dur :scaler 10.0 :offset 1))
	 (ampf (make-env '(0 0 1 1 20 1 21 0) :duration dur))
	 )
       (do ((i 0 (+ i 1)))
	   ((= i samps))
	 (set! (r2k!cos-k gen) (env indf))
	 (outa i (* (env ampf)
		    (r2k!cos gen))))))

dark 3 rainbow .001 not inverted
2048 blackman2
x 311 1.67
y 281 0.94
z 350 1.30
hop 3
(spectrum-end 0 0) 0.544793281259146

-->

<p>Negative "r" gives the same output as the corresponding positive "r", and 
there is sometimes a lot of DC.  Despite appearances, as r increases beyond 1.0,
the spectrum collapses back towards the fundamental.  (I think that r and 1/r produce the same spectrum).
Aliasing can be a problem,
especially when r is close to 1.
The instruments pianoy and pianoy1 use r2k!cos: <code>pianoy beg dur freq amp</code>, and 
<code>pianoy1 beg dur freq amp (bounce-freq 5) (bounce-amp 20)</code>:
</p>

<pre class="indented">
    (<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:play #t)
      (pianoy 0 3 100 .5))

    (<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:play #t)
      (pianoy1 0 4 200 .5 1 .1))
</pre>

<p>pianoy2 combines r2k!cos with fmssb to try to get closer to the hammer sound:
</p>

<pre class="indented">
    (<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:play #t) 
      (pianoy2 0 1 100 .5))
</pre>

<div class="separator"></div>


<pre class="indented">
<em class=def id="make-rkoddssb">make-rkoddssb</em> (frequency 0.0) (ratio 1.0) (r 0.5) ; -1.0 &lt; r &lt; 1.0
<em class=def id="rkoddssb">rkoddssb</em> gen (fm 0.0)
<em class=def id="rkoddssb?">rkoddssb?</em> gen
</pre>

<p>This produces a sum of odd-numbered harmonics scaled by (r^(2k-1))/(2k-1).  This kind of spectrum is usually
called "clarinet-like".
Negative r gives the
same output as positive. The (not very)
safe maximum r is:
</p>

<pre class="indented">
  (define (safe-rkodd-max-r freq srate)
    (let ((k2-1 (- (* 2 (floor (/ srate 3 freq))) 1)))
      (expt (* .001 k2-1) (/ 1.0 k2-1))))
</pre>


<p>The instrument stringy uses rkoddssb and rcos: <code>stringy beg dur freq amp</code>:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:play #t)
  (do ((i 0 (+ i 1)))
      ((= i 10))
    (stringy (* i .3) .3 (+ 200 (* 100 i)) .5)))
</pre>

<p>glassy also uses rkoddssb: <code>glassy beg dur freq amp</code>:
</p>

<pre class="indented">
(<a class=quiet href="sndscm.html#wsdoc">with-sound</a> (:play #t)
  (do ((i 0 (+ i 1)))
      ((= i 10))
    (glassy (* i .3) .1 (+ 400 (* 100 i)) .5)))
</pre>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-k2sin">make-k2sin</em> (frequency 0.0)
<em class=def id="k2sin">k2sin</em> gen (fm 0.0)
<em class=def id="k2sin?">k2sin?</em> gen

<em class=def id="make-k2cos">make-k2cos</em> (frequency 0.0)
<em class=def id="k2cos">k2cos</em> gen (fm 0.0)
<em class=def id="k2cos?">k2cos?</em> gen

<em class=def id="make-k2ssb">make-k2ssb</em> (frequency 0.0) (ratio 1.0)
<em class=def id="k2ssb">k2ssb</em> gen (fm 0.0)
<em class=def id="k2ssb?">k2ssb?</em> gen
</pre>

<p>These produce a sum of sinusoids scaled by 1/(2^k).
</p>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-k3sin">make-k3sin</em> (frequency 0.0)
<em class=def id="k3sin">k3sin</em> gen fm
<em class=def id="k3sin?">k3sin?</em> gen
</pre>

<p>This produces a sum of sines scaled by 1.0/(k^3).
</p>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-krksin">make-krksin</em> (frequency 0.0) (r 0.5)
<em class=def id="krksin">krksin</em> gen (fm 0.0)
<em class=def id="krksin?">krksin?</em> gen
</pre>

<img class="indented" src="pix/sceq25.png" alt="sum of sines">
<div class="separator"></div>

<p>This produces a sum of sinusoids scaled by kr^k.  Its output is not normalized.  I think the formula
given assumes that r is less than 1.0, and in that case, the safe maximum r is given by:
</p>

<pre class="indented">
  (define (safe-krk-max-r freq srate)
    (let ((topk (floor (/ srate 3 freq))))
      (expt (/ .001 topk) (/ 1.0 topk))))
</pre>

<p>However, r can be greater than 1.0 without causing any trouble, and behaves in that case much like r2k!cos &mdash; as it increases, the spectrum collapses;
I think r in that case is equivalent to 1/r.
The only value to avoid is 1.0.
</p>

<div class="separator"></div>


<pre class="indented">
<em class=def id="make-abcos">make-abcos</em> (frequency 0.0) (a 0.5) (b 0.25)
<em class=def id="abcos">abcos</em> gen (fm 0.0)
<em class=def id="abcos?">abcos?</em> gen

<em class=def id="make-absin">make-absin</em> (frequency 0.0) (a 0.5) (b 0.25)
<em class=def id="absin">absin</em> gen (fm 0.0)
<em class=def id="absin?">absin?</em> gen
</pre>

<p>These produce a sum of sinusoids scaled as follows:
</p>

<img class="indented" src="pix/sceq27.png" alt="sum of sines">
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-r2k2cos">make-r2k2cos</em> (frequency 0.0) (r 0.5)
<em class=def id="r2k2cos">r2k2cos</em> gen (fm 0.0)
<em class=def id="r2k2cos?">r2k2cos?</em> gen
</pre>

<p>This produces a sum of cosines, each scaled by 1/(r^2+k^2).  r shouldn't be 0, but otherwise it almost doesn't matter what it is &mdash;
this is not a very flexible generator!
</p>

<p>There are a dozen or so other generators defined in generators.scm, but most are close
variants of those given above.
</p>

<div class="separator"></div>


<pre class="indented">
<em class=def id="make-tanhsin">make-tanhsin</em> (frequency 0.0) (r 1.0) (initial-phase 0.0)
<em class=def id="tanhsin">tanhsin</em> gen (fm 0.0)
<em class=def id="tanhsin?">tanhsin?</em> gen
</pre>

<p>This produces tanh(r * sin(x)) which approaches a square wave as "r" increases.
</p>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-moving-fft">make-moving-fft</em> (input #f) (n 512) (hop 128)
<em class=def id="moving-fft">moving-fft</em> gen
<em class=def id="moving-fft?">moving-fft?</em> gen
</pre>

<p>moving-fft provides a sample-by-sample FFT (magnitudes and phases) of its
input (currently assumed to be a readin generator).  
mus-xcoeffs returns the magnitudes, mus-ycoeffs returns the phases, and mus-data returns the current input block.
We could mimic the fft display window in the "lisp graph" via:
</p>

<pre class="indented">
(let ((ft (<em class=red>make-moving-fft</em> (make-readin "oboe.snd")))
      (data (make-float-vector 256)))
  (set! (lisp-graph?) #t)
  (do ((i 0 (+ i 1)))
      ((= i 10000))
    (<em class=red>moving-fft</em> ft)
    (float-vector-subseq (mus-xcoeffs ft) 0 255 data)
    (graph data "fft" 0.0 11025.0 0.0 0.1 0 0 #t)))
</pre>
<div class="separator"></div>

<pre class="indented">
<em class=def id="make-moving-spectrum">make-moving-spectrum</em> (input #f) (n 512) (hop 128)
<em class=def id="moving-spectrum">moving-spectrum</em> gen
<em class=def id="moving-spectrum?">moving-spectrum?</em> gen
</pre>

<p>moving-spectrum provides a sample-by-sample spectrum (amplitudes, frequencies, and current phases) of its
input (currently assumed to be a readin generator).  It is identical to the first (analysis) portion of
the phase-vocoder generator (see test-sv in generators.scm for details).  To access the current amps and so on,
use (gen 'amps), (gen 'phases), and (gen 'freqs).
</p>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-moving-autocorrelation">make-moving-autocorrelation</em> (input #f) (n 512) (hop 128)
<em class=def id="moving-autocorrelation">moving-autocorrelation</em> gen
<em class=def id="moving-autocorrelation?">moving-autocorrelation?</em> gen
</pre>

<p>moving-autocorrelation provides the autocorrelation of the last 'n' samples every 'hop' samples.
The samples come from 'input' (currently assumed to be a readin generator). The output is accessible
via mus-data.
</p>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-moving-pitch">make-moving-pitch</em> (input #f) (n 512) (hop 128)
<em class=def id="moving-pitch">moving-pitch</em> gen
<em class=def id="moving-pitch?">moving-pitch?</em> gen
</pre>

<p>moving-pitch provides the current pitch of its input, recalculated (via moving-autocorrelation) every 'hop' samples.
</p>

<pre class="indented">
(let ((rd (make-readin "oboe.snd"))
      (cur-srate (srate "oboe.snd")))
  (let-temporarily ((*clm-srate* cur-srate))
    (let ((scn (<em class=red>make-moving-pitch</em> rd))
	  (last-pitch 0.0)
	  (pitch 0.0))
      (do ((i 0 (+ i 1)))
	  ((= i 22050))
        (set! last-pitch pitch)
        (set! pitch (<em class=red>moving-pitch</em> scn))
        (if (not (= last-pitch pitch))
	    (format () "~A: ~A~%" (* 1.0 (/ i cur-srate)) pitch))))))
</pre>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-moving-scentroid">make-moving-scentroid</em> (dbfloor -40.0) (rfreq 100.0) (size 4096)
<em class=def id="moving-scentroid">moving-scentroid</em> gen
<em class=def id="moving-scentroid?">moving-scentroid?</em> gen
</pre>

<p>moving-scentroid provides a generator that mimics Bret Battey's scentroid instrument (in dsp.scm or scentroid.ins).
</p>
<div class="separator"></div>


<pre class="indented">
<em class=def id="make-flocsig">make-flocsig</em> (reverb-amount 0.0) (frequency 1.0) (amplitude 2.0) offset
<em class=def id="flocsig">flocsig</em> gen i val
<em class=def id="flocsig?">flocsig?</em> gen
</pre>

<p>flocsig is a version of locsig that adds changing delays between the channels (flanging).  
The delay amount is set by a rand-interp centered around 'offset', moving as many as 'amplitude'
samples (this also affects signal placement), and moving at a speed set by 'frequency'.
Currently flocsig assumes stereo output and stereo reverb output.
This generator is trying to open up the space in the same manner that flanging does, but
hopefully unobtrusively.  Here is an example, including a stereo reverb:
</p>

<pre class="indented">
(definstrument (jcrev2)
  (let* ((allpass11 (make-all-pass -0.700 0.700 1051))
	 (allpass21 (make-all-pass -0.700 0.700  337))
	 (allpass31 (make-all-pass -0.700 0.700  113))
	 (comb11 (make-comb 0.742 4799))
	 (comb21 (make-comb 0.733 4999))
	 (comb31 (make-comb 0.715 5399))
	 (comb41 (make-comb 0.697 5801))
	 (outdel11 (make-delay (seconds-&gt;samples .01)))
				
	 (allpass12 (make-all-pass -0.700 0.700 1051))
	 (allpass22 (make-all-pass -0.700 0.700  337))
	 (allpass32 (make-all-pass -0.700 0.700  113))
	 (comb12 (make-comb 0.742 4799))
	 (comb22 (make-comb 0.733 4999))
	 (comb32 (make-comb 0.715 5399))
	 (comb42 (make-comb 0.697 5801))
	 (outdel12 (make-delay (seconds-&gt;samples .01)))
						       
	 (len (floor (+ *clm-srate* (framples *reverb*)))))
    
    (do ((i 0 (+ i 1)))
	((= i len))
      (let* ((allpass-sum (all-pass allpass31 
				    (all-pass allpass21 
					      (all-pass allpass11 
							(ina i *reverb*)))))
	     (comb-sum (+ (comb comb11 allpass-sum)
			  (comb comb21 allpass-sum)
			  (comb comb31 allpass-sum)
			  (comb comb41 allpass-sum))))
	(outa i (delay outdel11 comb-sum)))
      
      (let* ((allpass-sum (all-pass allpass32 
				    (all-pass allpass22 
					      (all-pass allpass12 
							(inb i *reverb*)))))
	     (comb-sum (+ (comb comb12 allpass-sum)
			  (comb comb22 allpass-sum)
			  (comb comb32 allpass-sum)
			  (comb comb42 allpass-sum))))
	(outb i (delay outdel12 comb-sum))))))

(definstrument (simp beg dur (amp 0.5) (freq 440.0) (ramp 2.0) (rfreq 1.0) offset)
  (let* ((os (make-pulse-train freq))
	 (floc (<em class=red>make-flocsig</em> :reverb-amount 0.1
			     :frequency rfreq
			     :amplitude ramp
			     :offset offset))
	 (start (seconds-&gt;samples beg))
	 (end (+ start (seconds-&gt;samples dur))))
    (do ((i start (+ i 1))) 
        ((= i end))
      (<em class=red>flocsig</em> floc i (* amp (pulse-train os))))))

(with-sound (:channels 2 :reverb-channels 2 :reverb jcrev2) 
  (simp 0 1))
</pre>




<!-- defgenerator -->
<div class="innerheader">defgenerator</div>

<pre class="indented">
<em class=def id="defgenerator">defgenerator</em> name fields
</pre>

<p>defgenerator defines a generator.  Its syntax is modelled after Common Lisp's defstruct.
It sets up
a structure, an environment with slots that you can get and set.
It also defines a "make"
function to create an instance of the environment, and a predicate for it. 
Here is a way to define oscil using defgenerator:
</p>

<pre class="indented">
(<em class=red>defgenerator</em> osc freq phase)

;;; make-osc creates an osc, and osc? returns #t if passed an osc.
;;; Once we have an osc (an environment with "freq" and "phase" locals)
;;;   we can either use with-let, or refer to the local variables
;;;   directly via (gen 'freq) and (gen 'phase).

(define (osc gen fm)                ; our new generator
  (let ((result (sin (gen 'phase))))
    (set! (gen 'phase) (+ (gen 'phase) (gen 'freq) fm))
    result))

;;; now we can use the osc generator in an instrument:

(<a class=quiet href="sndscm.html#definstrument">definstrument</a> (osc-fm beg dur freq amp mc-ratio fm-index)
  (let* ((start (<a class=quiet href="sndclm.html#secondstosamples">seconds-&gt;samples</a> beg))
	 (end (+ start (<a class=quiet href="sndclm.html#secondstosamples">seconds-&gt;samples</a> dur)))
	 (carrier (<em class=red>make-osc</em> (<a class=quiet href="sndclm.html#hztoradians">hz-&gt;radians</a> freq)))
	 (modulator (<em class=red>make-osc</em> (<a class=quiet href="sndclm.html#hztoradians">hz-&gt;radians</a> (* mc-ratio freq))))
	 (index (<a class=quiet href="sndclm.html#hztoradians">hz-&gt;radians</a> (* freq mc-ratio fm-index))))
    (do ((i start (+ i 1)))
        ((= i end))
      (<a class=quiet href="sndclm.html#outa">outa</a> i (* amp (<em class=red>osc</em> carrier (* index (<em class=red>osc</em> modulator 0.0))))))))

(with-sound () (osc-fm 0 1 440 .1 1 1))
</pre>

<p>
The first argument to defgenerator is the new object's name, and the rest are the fields of that object.
Each field has a name and an optional initial value which defaults to 0.0.
The "make" function (make-osc in our example) uses define* with
the field names and initial values as the optional keys.  So make-osc above is declared (by the
defgenerator macro) as:
</p>

<pre class="indented">
(define* (make-osc (freq 0.0) (phase 0.0)) ...)
</pre>

<p>which we can invoke in various ways, e.g.:
</p>

<pre class="indented">
(make-osc 440)
(make-osc :phase (/ pi 2) :freq 440)
(make-osc 440 :phase 0.0)
</pre>

<p>The defgenerator "name" parameter can also be a list; in this case the first element is the actual generator name.  The
next elements are <code>:make-wrapper</code> followed by a function of one argument
(the default object normally returned by defgenerator), and <code>:methods</code>, followed
by a list of the methods the generator responds to.  The make wrapper function can 
make any changes it pleases, then return the fixed-up generator.  For example, in our
"osc" generator, we had to remember to change frequency in Hz to radians; we can use the
wrapper to handle that:
</p>

<pre class="indented">
(defgenerator 
  (osc <em class=red>:make-wrapper</em> (lambda (gen)
                       (set! (gen 'freq) (<a class=quiet href="sndclm.html#hztoradians">hz-&gt;radians</a> (gen 'freq)))
                       gen))
        (freq 0.0) (phase 0.0))
</pre>

<p>and now the make process in the instrument can be simplified to:
</p>

<pre class="indented">
...
(carrier (make-osc freq))
(modulator (make-osc (* mc-ratio freq)))
...
</pre>

<p>If you want the struct to take part in the <a href="sndclm.html#genericfunctions">generic function</a> facility
in CLM, add the desired methods as an association list with the keyword :methods:
</p>

<pre class="indented">
(defgenerator (osc :make-wrapper
		     (lambda (gen)
		       (set! (gen 'freq) (<a class=quiet href="sndclm.html#hztoradians">hz-&gt;radians</a> (gen 'freq)))
		       gen)
		   <em class=red>:methods</em>
		     (list
		      (cons 'mus-frequency 
                            (dilambda
			      (lambda (g) (<a class=quiet href="sndclm.html#hztoradians">radians-&gt;hz</a> (g 'freq)))
			      (lambda (g val) (set! (g 'freq) (<a class=quiet href="sndclm.html#hztoradians">hz-&gt;radians</a> val)))))
		      (cons 'mus-phase 
                            (dilambda		          
			      (lambda (g) (g 'phase))
			      (lambda (g val) (set! (g 'phase) val))))
		      
		      (cons 'mus-describe 
			    (lambda (g) (<a class=quiet>format</a> #f "osc freq: ~A, phase: ~A" 
					  (mus-frequency g) 
					  (mus-phase g))))))
  freq phase)
</pre>

<p>The make-wrapper might more accurately be called an after-method; it is
evaluated at the end of the automatically-created make function.  All the
fields have been set at that point either by arguments to the make function,
or from the default values given in the defgenerator declaration.  The make
function returns whatever
the make-wrapper function returns, so you almost always want to return the "gen" argument.
There are many examples in generators.scm.
</p>




<!--  FUNCTIONS  -->

<div class="header" id="otherfunctions">Other functions</div>

<p>There are several functions closely tied to the generators and instruments.
</p>

<table class="method">
<tr><td><em class=def id="hztoradians">hz-&gt;radians</em><code> freq</code></td><td>convert freq to radians per sample (using *clm-srate*): (freq * 2 * pi) / srate</td></tr>
<tr><td><em class=def id="radianstohz">radians-&gt;hz</em><code> rads</code></td><td>convert rads to Hz (using *clm-srate*): (rads * srate) / (2 * pi)</td></tr>
<tr><td><em class=def id="dbtolinear">db-&gt;linear</em><code> dB</code></td><td>convert dB to linear value: 10^(dB/20)</td></tr>
<tr><td><em class=def id="lineartodb">linear-&gt;db</em><code> val</code></td><td>convert val to dB: 20 * log(x) / log(10)</td></tr>
<tr><td><em class=def id="timestosamples">times-&gt;samples</em><code> start duration</code></td><td>convert start and duration from seconds to samples (beg+dur in latter case)</td></tr>
<tr><td><em class=def id="samplestoseconds">samples-&gt;seconds</em><code> samps</code></td><td>convert samples to seconds (using *clm-srate*): samps / srate</td></tr>
<tr><td><em class=def id="secondstosamples">seconds-&gt;samples</em><code> secs</code></td><td>convert seconds to samples (using *clm-srate*): secs * srate</td></tr>
<tr><td><em class=def id="degreestoradians">degrees-&gt;radians</em><code> degs</code></td><td>convert degrees to radians: (degs * 2 * pi) / 360</td></tr>
<tr><td><em class=def id="radianstodegrees">radians-&gt;degrees</em><code> rads</code></td><td>convert radians to degrees: (rads * 360) / (2 * pi)</td></tr>
<tr><td><em class=def id="mussrate">mus-srate</em></td><td>sampling rate in with-sound (better known as *clm-srate*)</td></tr>
<tr><td><em class=def id="oddweight">odd-weight</em><code> x</code></td><td>return a number between 0.0 (x is even) and 1.0 (x is odd)</td></tr>
<tr><td><em class=def id="evenweight">even-weight</em><code> x</code></td><td>return a number between 0.0 (x is odd) and 1.0 (x is even)</td></tr>
<tr><td><em class=def id="oddmultiple">odd-multiple</em><code> x y</code></td><td>return y times the nearest odd integer to x</td></tr>
<tr><td><em class=def id="evenmultiple">even-multiple</em><code> x y</code></td><td>return y times the nearest even integer to x</td></tr>
</table>

<p>
hz-&gt;radians
converts its argument to radians/sample (for any situation where a
frequency is used as an amplitude &mdash; glissando or FM).
</p>
<blockquote>
<p>
<code>freq-in-hz * 2 * pi</code> gives us the number of radians traversed per
second; we then divide by the number of samples per second to get the
radians per sample; in dimensional terms: (radians/sec) /
(sample/sec) = radians/sample.  We need this conversion whenever a
frequency-related value is being accessed on every sample, as
an increment of a phase variable.  
</p></blockquote>

<pre class="indented">
&gt; *clm-srate*
44100.0

&gt; (hz-&gt;radians 440.0)
0.0626893772144902
&gt; (/ (* 440.0 2 pi) 44100.0)
0.0626893772144902

&gt; (linear-&gt;db .1)
-20.0

&gt; (times-&gt;samples 1.0 2.0)
(44100 132300)
&gt; (seconds-&gt;samples 2.0)
88200
&gt; (samples-&gt;seconds 44100)
1.0

&gt; (degrees-&gt;radians 45)
0.785398163397448
&gt; (radians-&gt;degrees (/ pi 4))
45.0
</pre>


<div class="separator"></div>


<pre class="indented">
<em class=def id="musfloatequalfudgefactor">mus-float-equal-fudge-factor</em> (also known as *mus-float-equal-fudge-factor*)
</pre>

<p>This function sets how far apart generator float-vector elements can be and still be considered equal in equal?
</p>

<pre class="indented">
&gt; *mus-float-equal-fudge-factor*
1.0e-7
&gt; (define v1 (float-vector .1 .1 .101))
#&lt;unspecified&gt;
&gt; (define v2 (float-vector .1 .1 .1))
#&lt;unspecified&gt;
&gt; (equal? v1 v2)
#f
&gt; (set! *mus-float-equal-fudge-factor* .01)
1.0e-7 ; set! returns the previous value
&gt; (equal? v1 v2)
#t
</pre>


<div class="separator"></div>

<pre class="indented">
<em class=def id="musarrayprintlength">mus-array-print-length</em> (also known as *mus-array-print-length*)
</pre>

<p>
This function determines how many float-vector elements are printed by mus-describe.
</p>



<!--  POLYNOMIAL  -->

<div class="innerheader">polynomial</div>


<pre class="indented">
<em class=def id="polynomial">polynomial</em> coeffs x
</pre>

<p>The polynomial function evaluates a polynomial, defined by giving its coefficients,
at the point "x".
"coeffs" is a vector of coefficients where
coeffs[0] is the constant term, and so on. 
</p>

<pre class="indented">
&gt; (polynomial (float-vector 0.0 1.0) 2.0) ; x
2.0
&gt; (polynomial (float-vector 1.0 2.0 3.0) 2.0) ; 3x*x + 2x + 1
17.0
</pre>

<p>
<a href="sndscm.html#polydoc">poly.scm</a> has a variety of polynomial-related functions.
Abramowitz and Stegun, "A Handbook of Mathematical Functions" is a
treasure-trove of interesting polynomials.
</p>


<!--  ARRAY-INTERP  -->

<div class="innerheader">array-interp, dot-product</div>

<pre class="indented">
<em class=def id="array-interp">array-interp</em> fn x size
<em class=def id="dot-product">dot-product</em> in1 in2
<em class=def id="edot-product">edot-product</em> freq data
<em class=def id="mus-interpolate">mus-interpolate</em> type x v size y1
</pre>

<p>array-interp interpolates in the array "fn" at the point "x".  It underlies the <a href="#table-lookup">table-lookup</a>
generator, among others.  Here's array-interp as a "compander":
</p>

<pre class="indented">
(define compand-table (float-vector -1.0 -0.96 -0.90 -0.82 -0.72 -0.60 -0.45 -0.25 
                            0.0 0.25 0.45 0.60 0.72 0.82 0.90 0.96 1.0))

(<a class=quiet href="extsnd.html#mapchannel">map-channel</a>
  (lambda (inval)
    (let ((index (+ 8.0 (* 8.0 inval))))
      (<em class=red>array-interp</em> compand-table index 17))))
</pre>


<p><a href="sndscm.html#soundinterp">sound-interp</a> in examp.scm fills an array with an entire sound,
then uses array-interp to read it.
</p>

<p>
dot-product is the usual "inner product" or "scalar product" (a name that should be banned from polite society).
We could define our own FIR filter using dot-product:
</p>

<pre class="indented">
(define (make-fr-filter coeffs)
  (list coeffs (make-float-vector (length coeffs))))

(define (fr-filter flt x)
  (let* ((coeffs (car flt))
	 (xs (cadr flt))
	 (xlen (length xs)))
    (float-vector-move! xs (- xlen 1) (- xlen 2) #t)
    (set! (xs 0) x)
    (<em class=red>dot-product</em> coeffs xs xlen)))
</pre>


<p>
edot-product returns the complex dot-product of the "data" argument (a vector) with <code>(exp (* freq i))</code>.
Here, "i" goes from 0 to data's size - 1.
"freq" and the elements of "data" can be complex, as can the return value.  See <a href="sndscm.html#stretchsoundviadft">stretch-sound-via-dft</a>
for an example.
</p>


<p>
mus-interpolate is the function used whenever table lookup interpolation is requested, as in
<a href="#delay">delay</a> or <a href="#wave-train">wave-train</a>. 
The "type" argument is one of the interpolation types (<code>mus-interp-linear</code>, for example).
</p>



<!--  CONTRAST-ENHANCEMENT  -->

<div class="innerheader">contrast-enhancement</div>

<pre class="indented">
<em class=def id="contrast-enhancement">contrast-enhancement</em> in-samp (fm-index 1.0)
</pre>

<p>contrast-enhancement passes its input to sin as a kind of phase modulation.
</p>

<pre class="indented">
(sin (+ (* input pi 0.5)
        (* index (sin (* input pi 2)))))
</pre>

<p>
This brightens the
input, helping it cut through a huge mix.
A similar (slightly simpler) effect is:
</p>

<pre class="indented">
(let ((mx (maxamp))) 
  (<a class=quiet href="extsnd.html#mapchannel">map-channel</a> 
    (lambda (y) 
      (* mx (sin (/ (* pi y) mx))))))
</pre>

<p>This modulates the sound but keeps the output maxamp the same as the input.
See <a href="#moving-max">moving-max</a> for a similar function that does this kind of scaling throughout the sound,
resulting in a steady modulation, rather than an intensification of just the peaks.
And a sort of converse is <a href="sndscm.html#soundinterp">sound-interp</a>.
</p>



<!--  AMPLITUDE-MODULATE  -->

<div class="innerheader">ring-modulate, amplitude-modulate</div>

<pre class="indented">
<em class=def id="ring-modulate">ring-modulate</em> in1 in2                  ; returns <code>(* in1 in2)</code>
<em class=def id="amplitude-modulate">amplitude-modulate</em> am-carrier in1 in2  ; returns <code>(* in1 (+ am-carrier in2))</code>
</pre>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
(with-sound (:play #t)
  (let ((osc1 (make-oscil 440.0))
	(osc2 (make-oscil 220.0)))
    (do ((i 0 (+ i 1)))
	((= i 44100))
      (outa i (* 0.5 (amplitude-modulate 0.3 (oscil osc1) (oscil osc2)))))))
</pre>
</div>
</td>

</tr><tr>

<td>
<div class="ruby">
<pre class="indented">
with_sound(:play, true) do
  osc1 = make_oscil(440.0);
  osc2 = make_oscil(220.0);
  44100.times do |i|
    outa(i, 0.5 * amplitude_modulate(0.3, oscil(osc1), oscil(osc2)), $output);
    end
  end.output
</pre>
</div>
</td>

</tr><tr>

<td>
<div class="forth">
<pre class="indented">
lambda: ( -- )
  440.0 make-oscil { osc1 }
  220.0 make-oscil { osc2 }
  44100 0 do
    i
    0.3            ( car )
    osc1 0 0 oscil ( in1 )
    osc2 0 0 oscil ( in2 ) amplitude-modulate  f2/ *output* outa drop
  loop
; :play #t with-sound drop
</pre>
</div>
</td>

</tr>
</table>


<p>ring-modulation is sometimes called "double-sideband-suppressed-carrier" modulation &mdash;
that is, amplitude modulation with the carrier omitted (set to 0.0 above).
The nomenclature here is a bit confusing &mdash; I can't remember now why I used
these names; think of "carrier" as "carrier amplitude" and "in1" as "carrier". Normal amplitude modulation using this function is:
</p>

<pre class="indented">
(define carrier (<a class=quiet href="#make-oscil">make-oscil</a> carrier-freq (* .5 pi)))
...
(amplitude-modulate 1.0 (<a class=quiet href="#oscil">oscil</a> carrier) signal)
</pre>

<p>Both of these functions take advantage of the "Modulation Theorem"; since
multiplying a signal by e^(iwt) translates its spectrum by w /
two pi Hz, multiplying by a sinusoid splits its spectrum into two equal parts
translated up and down by w/(two pi) Hz:
</p>

<img class="indented" src="pix/fmeq8.png" alt="coscos and sinsin">

<p>Waveshaping (via the Chebyshev polynomials) is an elaboration of AM.  For example, cos^2x is amplitude modulation of cos x
with itself, splitting into cos2x and cos0x.  T2 (that is, 2cos^2x - 1) then subtracts the cos0x term to return cos2x.
</p>
<p>
The upper sidebands may foldover (alias); if it's a problem, low-pass filter the inputs (surely no CLM user needs that silly reminder!).
</p>




<!--  FFT  -->

<div class="innerheader">FFT (fourier transform)</div>

<pre class="indented">
<em class=def id="fft">mus-fft</em> rdat idat fftsize sign
<em class=def id="make-fft-window">make-fft-window</em> type size (beta 0.0) (alpha 0.0)
<em class=def id="rectangulartopolar">rectangular-&gt;polar</em> rdat idat
<em class=def id="rectangulartomagnitudes">rectangular-&gt;magnitudes</em> rdat idat
<em class=def id="polartorectangular">polar-&gt;rectangular</em> rdat idat
<em class=def id="spectrum">spectrum</em> rdat idat window norm-type
<em class=def id="convolution">convolution</em> rdat idat size
<em class=def id="autocorrelate">autocorrelate</em> data
<em class=def id="correlate">correlate</em> data1 data2
</pre>

<p>mus-fft, spectrum, and convolution are the standard functions used everywhere.
fft is the Fourier transform, convolution convolves its arguments, and spectrum
returns '(magnitude (rectangular-&gt;polar (fft))).  The results are in dB (if "norm-type" is 0),
or linear and normalized to 1.0 ("norm-type" = 1), or linear unnormalized.
The name "mus-fft" is used to distuinguish clm's fft routine from Snd's; the
only difference is that mus-fft includes the fft length as an argument, whereas
<a href="extsnd.html#fft">fft</a> does not.  Here we use mus-fft to low-pass filter a sound:
</p>

<pre class="indented">
(let* ((len (mus-sound-framples "oboe.snd"))
       (fsize (expt 2 (ceiling (log len 2))))
       (rdata (make-float-vector fsize))
       (idata (make-float-vector fsize)))
  (file-&gt;array "oboe.snd" 0 0 len rdata)
  (<em class=red>mus-fft</em> rdata idata fsize 1)
  (let ((fsize2 (/ fsize 2))
        (cutoff (round (/ fsize 10))))
    (do ((i cutoff (+ i 1))
         (j (- fsize 1) (- j 1)))
        ((= i fsize2))
      (set! (rdata i) 0.0)
      (set! (idata i) 0.0)
      (set! (rdata j) 0.0)
      (set! (idata j) 0.0)))
  (<em class=red>mus-fft</em> rdata idata fsize -1)
  (array-&gt;file "test.snd" 
	       (float-vector-scale! rdata (/ 1.0 fsize)) 
	       len 
	       (srate "oboe.snd") 
	       1)
  (let ((previous-case (find-sound "test.snd")))
    (if (sound? previous-case)
	(close-sound previous-case)))
  (open-sound "test.snd"))
</pre>


<p>make-fft-window can return many of the standard windows including:
</p>

<pre class="indented">
bartlett-hann-window     bartlett-window        blackman2-window       blackman3-window
blackman4-window         bohman-window          cauchy-window          connes-window       
dolph-chebyshev-window   exponential-window     flat-top-window        gaussian-window     
hamming-window           hann-poisson-window    hann-window            kaiser-window
parzen-window            poisson-window         rectangular-window     riemann-window      
samaraki-window          tukey-window           ultraspherical-window  welch-window        
blackman5-window         blackman6-window       blackman7-window       blackman8-window       
blackman9-window         blackman10-window      rv2-window             rv3-window
rv4-window               mlt-sine-window        papoulis-window        dpss-window
sinc-window
</pre>

<p>rectangular-&gt;polar and polar-&gt;rectangular change how we view the FFT data: in polar or rectangular coordinates.
rectangular-&gt;magnitudes is the same as rectangular-&gt;polar, but only calculates the magnitudes.
autocorrelate performs an (in place) autocorrelation of 'data' (a float-vector).  See <a href="#moving-pitch">moving-pitch</a> in generators.scm, 
or <a href="sndscm.html#rubberdoc">rubber.scm</a>.
correlate performs an in-place cross-correlation of data1 and data2 (see, for example, <a href="sndscm.html#snddiffdoc">snddiff</a>).
</p>


<table class="method">
<tr><td class="methodtitle">FFTs</td></tr><tr><td>
<blockquote><small>
Hartley transform in Scheme: <a href="sndscm.html#dht">dht</a><br>
Spectral edit dialog: <a href="snd.html#editenvelope">Envelope Editor</a><br>
fft-based filter: <a href="sndscm.html#fftedit">fft-edit</a>, <a href="sndscm.html#fftenvedit">fft-env-edit</a>, <a href="sndscm.html#fftenvinterp">fft-env-interp</a>, <a href="sndscm.html#fftsquelch">fft-squelch</a>, <a href="sndscm.html#fftcancel">fft-cancel</a><br>
phase-vocoder: <a href="#phase-vocoder">phase-vocoder</a>. <a href="sndscm.html#pvocdoc">pvoc</a><br>
transposition via fft: <a href="sndscm.html#downoct">down-oct</a><br>
phase rotation via fft: <a href="sndscm.html#zerophase">zero-phase, rotate-phase</a><br>
duration change via autocorrelation: <a href="sndscm.html#rubberdoc">rubber-sound</a><br>
smoothing via fft: <a href="sndscm.html#fftsmoother">fft-smoother</a><br>
cross-synthesis: <a href="sndscm.html#crosssynthesis">cross-synthesis</a><br>
voiced-&gt;unvoiced effect: <a href="sndscm.html#voicedtounvoiced">voiced-&gt;unvoiced</a><br>
noise reduction: <a href="sndscm.html#cleanchannel">clean-channel</a>, <a href="sndscm.html#clminsdoc">anoi</a><br>
spectral modeling: <a href="sndscm.html#clminsdoc">pins</a><br>
polynomial approach to spectral multiplies (convolution): <a href="sndscm.html#spectralpolynomial">spectral-polynomial</a><br>
More transforms: <a href="sndscm.html#fractionalfouriertransform">fractional-fourier-transform</a>, <a href="sndscm.html#ztransform">z-transform</a> in dsp.scm<br>
bark, mel, erb scale display: <a href="sndscm.html#displaybarkfft">display-bark-fft</a><br>
apply function to spectrum, inverse fft: <a href="sndscm.html#filterfft">filter-fft</a><br>
</small></blockquote>
</td></tr></table>



<div class="header" id="instruments">Instruments</div>

<p>It's hard to decide what's an "instrument" in this context, but I think I'll treat
it as something that can be called as a note in a notelist (in with-sound) and
generate its own sound.
There are hundreds of instruments scattered around the documentation, and most of the
<a href="extsnd.html#mapchannel">map-channel</a> functions can be recast as instruments.
There are also several that represent "classic" computer music instruments; they
are listed here, documented in sndscm.html, and tested (via sample runs) in
test 23 in snd-test.
</p>


<table class="borderspaced">
<tr>
<th class="beige">instrument</th>
<th class="beige">function</th>
<th class="beige">CL</th>
<th class="beige">Scheme</th>
<th class="beige">Ruby</th>
<th class="beige">Forth</th>
</tr>
<tr><td class="br">complete-add</td>      
    <td class="br">additive synthesis</td>
    <td class="br">add.ins</td>
    <td></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">addflts</td>
    <td class="br">filters</td>
    <td class="br">addflt.ins</td> 
        <td class="br"><a href="dsp.scm">dsp.scm</a></td>
	<td class="br"><a href="dsp.rb">dsp.rb</a></td>
    <td></td>
    </tr>

<tr><td class="br">add-sound</td>
    <td class="br">mix in a sound file</td>
    <td class="br">addsnd.ins</td>
    <td></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">bullfrog et al</td>
    <td class="br">many animals (frogs, insects, birds)</td>
    <td class="br"></td>
    <td class="br"><a href="animals.scm">animals.scm</a></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">anoi</td>
    <td class="br">noise reduction</td>
    <td class="br">anoi.ins</td>
        <td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
        <td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
        <td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">autoc</td>
    <td class="br">pitch estimation (Bret Battey)</td>
    <td class="br">autoc.ins</td>
    <td></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">badd</td>
    <td class="br">fancier additive synthesis (Doug Fulton)</td>
    <td class="br">badd.ins</td>
    <td></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">bandedwg</td>               
    <td class="br">Juan Reyes banded waveguide instrument</td>      
    <td class="br">bandedwg.ins</td>      
	<td class="br"><a href="bandedwg.cms">bandedwg.cms</a></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">fm-bell</td>
    <td class="br">fm bell sounds (Michael McNabb)</td>
    <td class="br">bell.ins</td>
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">bigbird</td>
    <td class="br">waveshaping</td>
    <td class="br">bigbird.ins</td>
	<td class="br"><a href="bird.scm">bird.scm</a></td>
	<td class="br"><a href="bird.rb">bird.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs, bird.fs</a></td>
    </tr>

<tr><td class="br">singbowl</td>               
    <td class="br">Juan Reyes Tibetan bowl instrument</td>      
    <td class="br">bowl.ins</td>      
	<td class="br"><a href="bowl.cms">bowl.cms</a></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">canter</td>            
    <td class="br">fm bagpipes (Peter Commons)</td>      
    <td class="br">canter.ins</td>
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">cellon</td>            
    <td class="br">feedback fm (Stanislaw Krupowicz)</td>      
    <td class="br">cellon.ins</td>    
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">cnvrev</td>            
    <td class="br">convolution (aimed at reverb)</td>      
    <td class="br">cnv.ins</td>
    <td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">moving sounds</td>     
    <td class="br">sound movement (Fernando Lopez-Lezcano)</td>      
    <td class="br">dlocsig.lisp</td> 
	<td class="br"><a href="dlocsig.scm">dlocsig.scm</a></td>
        <td class="br"><a href="dlocsig.rb">dlocsig.rb</a></td>
    <td></td>
    </tr>

<tr><td class="br">drone</td>             
    <td class="br">additive synthesis (bag.clm) (Peter Commons)</td>      
    <td class="br">drone.ins</td>      
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">expandn</td>             
    <td class="br">granular synthesis (Michael Klingbeil)</td>      
    <td class="br">expandn.ins</td>      
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">granulate-sound</td>   
    <td class="br">examples granular synthesis</td>      
    <td class="br">expsrc.ins</td>    
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">cross-fade</td>        
    <td class="br">cross-fades in the frequency domain</td>      
    <td class="br">fade.ins</td>        
	<td class="br"><a href="fade.scm">fade.scm</a></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">filter-sound</td>      
    <td class="br">filter a sound file</td>      
    <td class="br">fltsnd.ins</td>    
	<td class="br"><a href="dsp.scm">dsp.scm</a></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">stereo-flute</td>      
    <td class="br">physical model of a flute (Nicky Hind)</td>      
    <td class="br">flute.ins</td>      
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">fm examples</td>       
    <td class="br">fm bell, gong, drum (Paul Weineke, Jan Mattox)</td>      
    <td class="br">fmex.ins</td>        
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">Jezar's reverb</td>    
    <td class="br">fancy reverb (Jezar Wakefield)</td>      
    <td class="br">freeverb.ins</td> 
	<td class="br"><a href="freeverb.scm">freeverb.scm</a></td>
	<td class="br"><a href="freeverb.rb">freeverb.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">fofins</td>
    <td class="br">FOF synthesis</td>
    <td class="br"><a href="#wave-train">sndclm.html</a></td> 
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">fullmix</td>           
    <td class="br">a mixer</td>      
    <td class="br">fullmix.ins</td>  
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">grani</td>             
    <td class="br">granular synthesis (Fernando Lopez-Lezcano)</td>      
    <td class="br">grani.ins</td>      
	<td class="br"><a href="grani.scm">grani.scm</a></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">grapheq</td>           
    <td class="br">graphic equalizer (Marco Trevisani)</td>      
    <td class="br">grapheq.ins</td>  
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">fm-insect</td>         
    <td class="br">fm</td>      
    <td class="br">insect.ins</td>    
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
    <td></td>
    </tr>

<tr><td class="br">jc-reverb</td>         
    <td class="br">a reverberator (see also jlrev)</td>      
    <td class="br">jcrev.ins</td>      
	<td class="br"><a href="jcrev.scm">jcrev.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">fm-voice</td>          
    <td class="br">fm voice (John Chowning)</td>      
    <td class="br">jcvoi.ins</td>     
    <td class="br"><a href="jcvoi.scm">jcvoi.scm </a></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">kiprev</td>            
    <td class="br">a fancier reverberator (Kip Sheeline)</td>      
    <td class="br">kiprev.ins</td>    
    <td></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">lbj-piano</td>         
    <td class="br">additive synthesis piano (Doug Fulton)</td>      
    <td class="br">lbjPiano.ins</td> 
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">rotates</td>               
    <td class="br">Juan Reyes Leslie instrument</td>      
    <td class="br">leslie.ins</td>      
	<td class="br"><a href="leslie.cms">leslie.cms</a></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">maraca</td>            
    <td class="br">Perry Cook's maraca physical models</td>      
    <td class="br">maraca.ins</td>    
	<td class="br"><a href="maraca.scm">maraca.scm</a></td>
	<td class="br"><a href="maraca.rb">maraca.rb</a></td>
    <td></td>
    </tr>

<tr><td class="br">maxfilter</td>         
    <td class="br">Juan Reyes modular synthesis</td>      
    <td class="br">maxf.ins</td>        
	<td class="br"><a href="maxf.scm">maxf.scm</a></td>
	<td class="br"><a href="maxf.rb">maxf.rb</a></td>
    <td></td>
    </tr>

<tr><td class="br">mlb-voice</td>         
    <td class="br">fm voice (Marc LeBrun)</td>      
    <td class="br">mlbvoi.ins</td>
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">moog filters</td>      
    <td class="br">Moog filters (Fernando Lopez-Lezcano)</td>      
    <td class="br">moog.lisp</td>      
	<td class="br"><a href="moog.scm">moog.scm</a></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">fm-noise</td>          
    <td class="br">noise maker</td>      
    <td class="br">noise.ins</td>      
	<td class="br"><a href="noise.scm">noise.scm</a></td>
	<td class="br"><a href="noise.rb">noise.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">nrev</td>              
    <td class="br">a popular reverberator (Michael McNabb)</td>      
    <td class="br">nrev.ins</td>        
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">one-cut</td>           
    <td class="br">"cut and paste" (Fernando Lopez-Lezcano)</td>      
    <td class="br">one-cut.ins</td>  
    <td></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">p</td>                 
    <td class="br">Scott van Duyne's piano physical model</td>      
    <td class="br">piano.ins</td>      
	<td class="br"><a href="piano.scm">piano.scm</a></td>
	<td class="br"><a href="piano.rb">piano.rb</a></td>
    <td></td>
    </tr>

<tr><td class="br">pluck</td>             
    <td class="br">Karplus-Strong synthesis (David Jaffe)</td>      
    <td class="br">pluck.ins</td>      
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">pqw</td>               
    <td class="br">waveshaping</td>      
    <td class="br">pqw.ins</td>          
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>	
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">pqw-vox</td>           
    <td class="br">waveshaping voice</td>      
    <td class="br">pqwvox.ins</td>    
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">physical models</td>   
    <td class="br">physical modelling (Perry Cook)</td>      
    <td class="br">prc-toolkit95.lisp</td>
	<td class="br"><a href="prc95.scm">prc95.scm</a></td>
	<td class="br"><a href="prc95.rb">prc95.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">various ins</td>       
    <td class="br">from Perry Cook's Synthesis Toolkit</td>      
    <td class="br">prc96.ins</td>      
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">pvoc</td>              
    <td class="br">phase vocoder (Michael Klingbeil)</td>      
    <td class="br">pvoc.ins</td>        
	<td class="br"><a href="pvoc.scm">pvoc.scm</a></td>
	<td class="br"><a href="pvoc.rb">pvoc.rb</a></td>
    <td></td>
    </tr>

<tr><td class="br">resflt</td>            
    <td class="br">filters (Xavier Serra, Richard Karpen)</td>      
    <td class="br">resflt.ins</td>    
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">reson</td>             
    <td class="br">fm formants (John Chowning)</td>      
    <td class="br">reson.ins</td>      
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">ring-modulate</td>     
    <td class="br">ring-modulation of sounds (Craig Sapp)</td>      
    <td class="br">ring-modulate.ins</td>
	<td class="br"><a href="examp.scm">examp.scm</a></td>
	<td class="br"><a href="examp.rb">examp.rb</a></td>
    <td></td>
    </tr>

<tr><td class="br">rmsenv</td>            
    <td class="br">rms envelope of sound (Bret Battey)</td>      
    <td class="br">rmsenv.ins</td>    
    <td></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">pins</td>              
    <td class="br">spectral modelling</td>      
    <td class="br">san.ins</td>          
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">scanned</td>           
    <td class="br">Juan Reyes scanned synthesis instrument</td>      
    <td class="br">scanned.ins</td>  
	<td class="br"><a href="dsp.scm">dsp.scm</a></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">scentroid</td>         
    <td class="br">spectral scentroid envelope (Bret Battey)</td>      
    <td class="br">scentroid.ins</td> 
	<td class="br"><a href="dsp.scm">dsp.scm</a></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">shepard</td>            
    <td class="br">Shepard tones (Juan Reyes)</td>      
    <td class="br">shepard.ins</td>    
	<td class="br"><a href="sndscm.html#wsdoc">sndscm.html</a></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">singer</td>            
    <td class="br">Perry Cook's vocal tract physical model</td>      
    <td class="br">singer.ins</td>    
	<td class="br"><a href="singer.scm">singer.scm</a></td>
	<td class="br"><a href="singer.rb">singer.rb</a></td>
    <td></td>
    </tr>

<tr><td class="br">sndwarp</td>           
    <td class="br">Csound-like sndwarp generator (Bret Battey)</td>      
    <td class="br">sndwarp.ins</td>   
	<td class="br"><a href="sndwarp.scm">sndwarp.scm</a></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">stochastic</td>        
    <td class="br">Bill Sack's stochastic synthesis implementation</td>      
    <td class="br">stochastic.ins</td><td class="br"><a href="stochastic.scm">stochastic.scm</a></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">bow</td>               
    <td class="br">Juan Reyes bowed string physical model</td>      
    <td class="br">strad.ins</td>      
	<td class="br"><a href="strad.scm">strad.scm</a></td>
	<td class="br"><a href="strad.rb">strad.rb</a></td>
    <td></td>
    </tr>

<tr><td class="br">track-rms</td>         
    <td class="br">rms envelope of sound file (Michael Edwards)</td>      
    <td class="br">track-rms.ins</td>        
    <td></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">fm-trumpet</td>        
    <td class="br">fm trumpet (Dexter Morrill)</td>      
    <td class="br">trp.ins</td>          
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">various ins</td>       
    <td class="br">granular synthesis, formants, etc</td>      
    <td class="br">ugex.ins</td>        
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
    <td></td>
    </tr>

<tr><td class="br">fm-violin</td>         
    <td class="br">fm violin (fmviolin.clm, popi.clm)</td>      
    <td class="br">v.ins</td>              
	<td class="br"><a href="v.scm">v.scm</a></td>
	<td class="br"><a href="v.rb">v.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">vowel</td>             
    <td class="br">vowels (Michelle Daniels)</td>      
    <td class="br">vowel.ins</td>      
    <td></td>
    <td></td>
    <td></td>
    </tr>

<tr><td class="br">vox</td>               
    <td class="br">fm voice (cream.clm)</td>      
    <td class="br">vox.ins</td>          
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">zc, zn</td>            
    <td class="br">interpolating delays</td>      
    <td class="br">zd.ins</td>            
	<td class="br"><a href="clm-ins.scm">clm-ins.scm</a></td>
	<td class="br"><a href="clm-ins.rb">clm-ins.rb</a></td>
	<td class="br"><a href="clm-ins.fs">clm-ins.fs</a></td>
    </tr>

<tr><td class="br">zipper</td>            
    <td class="br">The 'digital zipper' effect.</td>      
    <td class="br">zipper.ins</td>    
	<td class="br"><a href="zip.scm">zip.scm</a></td>
	<td class="br"><a href="zip.rb">zip.rb</a></td>
    <td></td>
    </tr>

</table>

<p>
If you develop
an interesting instrument that you're willing to share, please send it to me
(bil@ccrma.stanford.edu). 
<a href="sndscm.html#definstrument">definstrument</a>, the individual instruments, and <a href="sndscm.html#wsdoc">with-sound</a> are documented in 
<a href="sndscm.html">sndscm.html</a>.
</p>


<div class="related">
related documentation: &nbsp;
<a href="snd.html">snd.html &nbsp;</a>
<a href="extsnd.html">extsnd.html &nbsp;</a>
<a href="grfsnd.html">grfsnd.html &nbsp;</a>
<a href="sndscm.html">sndscm.html &nbsp;</a>
<a href="fm.html">fm.html &nbsp;</a>
<a href="sndlib.html">sndlib.html &nbsp;</a>
<a href="s7.html">s7.html &nbsp;</a>
<a href="index.html">index.html</a>
</div>

</body></html>