File: extsnd.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 (14223 lines) | stat: -rw-r--r-- 497,104 bytes
parent folder | download | duplicates (2)
<!DOCTYPE html>

<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" >
<title>Snd Customization and Extension</title>
<style>
	EM.red {color:red; font-style: normal}
        EM.error {color:chocolate; font-style: normal}

	H1 {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}

	EM.def {font-weight: bold; font-style: normal; text-decoration:none; padding-right: 0.2cm}

        TD.green {background-color: lightgreen}
	TD.bluish {background-color: #f2f4ff}
	TD.beige {background-color: beige}
        TD.greenish {background-color: #eefdee}

        PRE.indented {padding-left: 1.0cm}
        IMG.indented {padding-left: 1.0cm}
        IMG.noborder {border: none}

	DIV.center {text-align: center}
        BODY.body {background-color: #ffffff;    /* white */
	           margin-left: 0.5cm; 
		   margin-right: 0.5cm;
                   }
        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.innermostheader {margin-top: 30px;
	            margin-bottom: 10px;
	            border: 1px solid lightgray;
		    background-color: #f0f0f0;
		    padding-left: 30px;
		    width: 30%;
		    padding-top: 10px;
		    padding-bottom: 10px;
	           }
	DIV.related {text-align:center;
	             border: 1px solid lightgray;
		     margin-bottom: 1.0cm;
		     margin-top: 1.0cm;
		     padding-top: 10px;
		     padding-bottom: 10px;
		     background-color: #f0f0f0;
	            }
        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.method {margin-top: 0.5cm;
                      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;
		      }	    
        TH.title {background-color: lightgreen;
		  border: 1px solid gray;
		  padding-top: 0.2cm;	
		  padding-bottom: 0.2cm;
		  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.scheme1 {background-color: #f2f4ff;
	            border: 1px solid lightgray;
		    padding-right: 0.1cm;
		    padding-left: 0.25cm;
		    margin-bottom: 0.2cm;
		    }
	DIV.ruby1 {background-color: #fbfbf0;
	            border: 1px solid lightgray;
		    padding-right: 0.1cm;
		    padding-left: 0.25cm;
		    margin-bottom: 0.2cm;
		    }
	DIV.forth1 {background-color: #eefdee;
	            border: 1px solid lightgray;
		    padding-right: 0.1cm;
		    padding-left: 0.25cm;
		    margin-bottom: 0.2cm;
		    }
        DIV.spacer {margin-top: 1.0cm;
	           }
        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;
		      } 
        #contents_table tbody tr:nth-child(odd) { background-color: #f2f4ff; }
</style>
</head>

<body class="body">

<div class="topheader" id="extsndcontents">Snd Customization and Extension</div>

<div class="related">
related documentation: &nbsp;
<a href="snd.html">snd.html &nbsp;</a>
<a href="grfsnd.html">grfsnd.html &nbsp;</a>
<a href="sndscm.html">sndscm.html &nbsp;</a>
<a href="sndclm.html">sndclm.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>


<table>
<tr><th>this file:</th><th>grfsnd.html:</th><th></th></tr>
<tr><td>
<ul>
<li><a href="#lisplistener">Introduction</a>
<li><a href="#etc">Snd Programming</a>
  <ul>
  <li><a href="#behavior">Customizing Snd's behavior</a>
    <ul>
    <li><a href="#sndglobalvars">Global variables</a>
    <li><a href="#sndgenericfuncs">Generic functions</a>
    <li><a href="#sndhooks">Hooks</a>
    </ul>
  <li><a href="#sndobjects">Snd's objects</a>
    <ul>
    <li><a href="#samplers">Samplers</a>
    <li><a href="#Floatvectors">Float-vectors, vcts</a>
    <li><a href="#extsndlib">Sndlib</a>
    <li><a href="#sndmarks">Marks</a>
    <li><a href="#sndmixes">Mixes</a>
    <li><a href="#sndregions">Regions and Selections</a>
    <li><a href="#sndsounds">Sounds and channels</a>
      <ul>
        <li><a href="#customcontrols">the control panel</a>
        <li><a href="#editlists">edit lists</a>
      </ul>
    <li><a href="#sndtransforms">Transforms</a>
    <li><a href="#snddialogs">Dialogs and Other Widgets</a>
    <li><a href="#sndmisc">Miscellaneous functions</a>
    <li><a href="#sndconstants">Constants</a>
    <li><a href="#snderrors">Errors and Debugging</a>
    </ul>
  <li><a href="#appearance">Customizing Snd's appearance</a>
    <ul>
    <li><a href="#colors">Colors</a>
    <li><a href="#fonts">Fonts</a>
    <li><a href="#graphics">Graphics</a>
    </ul>
  </ul>
</ul>
</td><td>

<ul>
<li><a href="grfsnd.html#startup">Snd Startup</a>
  <ul>
  <li><a href="grfsnd.html#sndswitches">Snd invocation flags</a>
  <li><a href="grfsnd.html#sndinitfile">The initialization file</a>
  <li><a href="grfsnd.html#sndconfigurationswitches">Configuration choices</a>
  <li><a href="grfsnd.html#sndenvvars">Environment variables</a>
  </ul>
<li><a href="grfsnd.html#snddynamic">Runtime modules and external programs</a>
  <ul>
  <li><a href="grfsnd.html#emacssnd">Snd as an Emacs subjob</a>
  <li><a href="grfsnd.html#dynamic">Dynamically loaded modules</a>
  <li><a href="grfsnd.html#sndwithclm">Snd and CLM</a>
  <li><a href="grfsnd.html#sndwithcm">Snd and Common Music</a>
  <li><a href="grfsnd.html#sndwithmotif">Snd and Motif</a>
  <li><a href="grfsnd.html#sndwithnogui">Snd with no GUI</a>
  <li><a href="grfsnd.html#sndandruby">Snd with Ruby</a>
  <li><a href="grfsnd.html#sndandforth">Snd with Forth</a>
  <li><a href="grfsnd.html#sndands7">Snd with s7</a>
  <li><a href="grfsnd.html#sndandladspa">Snd and LADSPA plugins</a>
  <li><a href="grfsnd.html#sndandalsa">Snd and ALSA</a>
  <li><a href="grfsnd.html#sndandjack">Snd and Jack</a>
  <li><a href="grfsnd.html#sndandgl">Snd and OpenGL</a>
  <li><a href="grfsnd.html#sndandgsl">Snd and GSL</a>
  <li><a href="grfsnd.html#sndandgmp">multiprecision arithmetic</a>
  </ul>
  <li><a href="grfsnd.html#otherstuff">Other stuff</a>
<li><a href="index.html">Index</a>
</ul>

</td><td>
<img src="pix/rr2.png" alt="setting switches">
</td></tr></table>



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

<p>Snd is a highly customizable, extensible program.
I've tried to bring out to the extension language nearly every portion
of Snd, both the signal-processing functions and
much of the user interface.  You can, for example,
add your own menu choices, editing operations, 
or graphing alternatives.
Nearly everything in Snd can be set in an initialization
file, loaded at any time from a text file of program code, or specified in a <a href="snd.html#savedstate">saved state</a> file.
It can also be set 
via inter-process communication or from stdin
from any other program (CLM and Emacs in particular),
embedded in a keyboard macro, or typed in the
listener.
</p>

<p>
The syntax used throughout this documentation is Scheme (a form of lisp) as implemented by s7.
You can also use Ruby or Forth, but need to make various minor <a href="grfsnd.html#sndandruby">changes</a>.
I'm slowly adding parallel Forth and Ruby examples.
</p>

<p>
The easiest way to get acquainted
with this aspect of Snd is to open the listener
(via the View:Open listener menu option), and type
experiments in its window.  Its prompt is "&gt;". So,
say we've opened the listener.
</p>

<table>
<tr><th>Scheme</th><th>Ruby</th><th>Forth</th></tr>

<tr><td><div class="scheme1"><pre>
&gt; (+ 1 2)
3
</pre></div></td><td><div class="ruby1"><pre>
&gt;1+2
3
</pre></div></td><td><div class="forth1"><pre>
&gt;1 2 +
3
</pre></div></td></tr>

<tr><td><div class="scheme1"><pre>
&gt; (open-sound "oboe.snd")
#&lt;sound 0&gt;
</pre></div></td><td><div class="ruby1"><pre>
&gt;open_sound("oboe.snd")
0
</pre></div></td><td><div class="forth1"><pre>
&gt;"oboe.snd" open-sound
0
</pre></div></td></tr>

<tr><td><div class="scheme1"><pre>
&gt; (auto-resize)
#t
</pre></div></td><td><div class="ruby1"><pre>
&gt;auto_resize
true
</pre></div></td><td><div class="forth1"><pre>
&gt;auto-resize
#t
</pre></div></td></tr>



<tr><td><div class="scheme1"><pre>
&gt; (set! (auto-resize) #f)
#f
</pre></div></td><td><div class="ruby1"><pre>
&gt;set_auto_resize false
false
</pre></div></td><td><div class="forth1"><pre>
&gt;#f set-auto-resize
#f
</pre></div></td></tr>

<tr><td><div class="scheme1"><pre>
&gt; (set! (x-bounds) '(0.0 1.0))
(0.0 1.0)
</pre></div></td><td><div class="ruby1"><pre>
&gt;set_x_bounds([0.0, 1.0])
0.01.0
</pre></div></td><td><div class="forth1"><pre>
&gt;'( 0.0 1.0 ) set-x-bounds
'( 0.0 1.0 )
</pre></div></td></tr>

<tr><td><div class="scheme1"><pre>
&gt; (load "bird.scm")
make-birds
</pre></div></td><td><div class="ruby1"><pre>
&gt;load "bird.rb"
true
</pre></div></td><td><div class="forth1"><pre>
&gt;"bird.fs" file-eval
0
</pre></div></td></tr>

<tr><td><div class="scheme1"><pre>
&gt; (map-channel (lambda (y) (* y 2)))
0
</pre></div></td><td><div class="ruby1"><pre>
&gt;map_channel(lambda do |y| y * 2 end)
-0.0015869140625
</pre></div></td><td><div class="forth1"><pre>
&gt;lambda: &lt;{ y }&gt; y 2.0 f* ; map-channel
-0.00158691
</pre></div></td></tr>

<tr><td><div class="scheme1"><pre>
&gt; (define (plus a b) (+ a b))
plus
</pre></div></td><td><div class="ruby1"><pre>
&gt;def plus(a, b) a+b end

</pre></div></td><td><div class="forth1"><pre>
&gt;: plus ( a b -- sum ) { a b } a b + ;
nil
</pre></div></td></tr>

<tr><td><div class="scheme1"><pre>
&gt; (set! (basic-color) (make-color 1 0 0))
(Pixel 16711680)
</pre></div></td><td><div class="ruby1"><pre>
&gt;set_basic_color make_color(1, 0, 0)
[:Pixel, 16711680]
</pre></div></td><td><div class="forth1"><pre>
&gt;1 0 0 make-color set-basic-color
#&lt;XmRaw: Pixel 0x9d3b430&gt;
</pre></div></td></tr>
</table>


<p>Another quick way to check out the extension language is to go to the
Preferences dialog (in the Options menu), choose some items, then
save them.  The saved file (~/.snd_prefs_s7 for example) is a text file, a program in the current
extension language, that initializes Snd to use whatever items you chose.
</p>



<div class="header" id="etc">Snd Programming</div>

<p>Snd is organized as a list of sounds, each with a list of channels,
each channel containing lists of edits, marks, mixes, etc.
There are other objects such as colors, 
and regions; the currently active region is
called the selection.  I originally presented all the
functions and variables in an enormous alphabetical
list, but that finally became unmanageable.  In the following
sections, each of the basic entities is treated in a separate
section with cross-references where needed.  The <a href="index.html">index</a>
provides alphabetical entry.</p>

<p>There are many examples in <a href="sndscm.html#exampdoc">examp.scm, examp.rb, examp.fs</a>, 
and <a href="sndscm.html#sndtestdoc">snd-test.scm</a>. 
Extensions to Snd can be found in:
</p>

<table class="grayborder"><tr><td>
<table id="contents_table">
<tbody>
<tr><td><a href="sndscm.html#analogfilterdoc">analog-filter</a></td>
    <td>standard IIR filters</td></tr>

<tr><td><a href="sndscm.html#animalsdoc">animals</a></td>
    <td>a bunch of animals</td></tr>

<tr><td><a href="sndscm.html#autosavedoc">autosave</a></td>
    <td>auto-save (edit backup) support</td></tr>

<tr><td><a href="sndscm.html#bessdoc">bess</a></td>
    <td>FM demo</td></tr>

<tr><td><a href="sndscm.html#binaryiodoc">binary-io</a></td>
    <td>binary files</td></tr>

<tr><td><a href="sndscm.html#birddoc">bird</a></td>
    <td>North-American birds</td></tr>

<tr><td><a href="sndscm.html#cleandoc">clean</a></td>
    <td>noise reduction</td></tr>

<tr><td><a href="sndscm.html#clminsdoc">clm-ins, clm23</a></td>
    <td>various CLM instruments</td></tr>

<tr><td><a href="sndscm.html#dlocsigdoc">dlocsig</a></td>
    <td>moving sounds (Michael Scholz)</td></tr>

<tr><td><a href="sndscm.html#drawdoc">draw</a></td>
    <td>graphics additions</td></tr>

<tr><td><a href="sndscm.html#dspdoc">dsp</a></td>
    <td>various DSP-related procedures</td></tr>

<tr><td><a href="sndscm.html#envdoc">env</a></td>
    <td>envelope functions</td></tr>

<tr><td><a href="sndscm.html#enveddoc">enved</a></td>
    <td>envelope editor</td></tr>

<tr><td><a href="sndscm.html#exampdoc">examp</a></td>
    <td>many examples</td></tr>

<tr><td><a href="sndscm.html#extensionsdoc">extensions</a></td>
    <td>various generally useful Snd extensions</td></tr>

<tr><td><a href="sndscm.html#fadedoc">fade</a></td>
    <td>frequency-domain cross-fades</td></tr>

<tr><td><a href="sndscm.html#freeverbdoc">freeverb</a></td>
    <td>a reverb</td></tr>

<tr><td><a href="sndclm.html#othergenerators">generators</a></td>
    <td>a bunch of generators</td></tr>

<tr><td><a href="sndscm.html#granidoc">grani</a></td>
    <td>CLM's grani (Fernando Lopez-Lezcano and Mike Scholz)</td></tr>

<tr><td><a href="sndscm.html#heartdoc">heart</a></td>
    <td>use Snd with non-sound (arbitrary range) data</td></tr>

<tr><td><a href="sndscm.html#hooksdoc">hooks</a></td>
    <td >functions related to hooks</td></tr>

<tr><td><a href="sndscm.html#indexdoc">index</a></td>
    <td>snd-help extension</td></tr>

<tr><td><a href="sndscm.html#dotemacs">inf-snd.el, DotEmacs</a></td>
    <td>Emacs subjob support (Michael Scholz, Fernando Lopez-Lezcano)</td></tr>

<tr><td><a href="sndscm.html#jcrevdoc">jcrev</a></td>
    <td>John Chowning's ancient reverb</td></tr>

<tr><td><a href="sndscm.html#lintdoc">lint</a></td>
    <td>a lint program for scheme</td></tr>

<tr><td><a href="sndscm.html#maracadoc">maraca</a></td>
    <td>Perry Cook's maraca physical model</td></tr>

<tr><td><a href="sndscm.html#marksdoc">marks</a></td>
    <td>functions related to marks</td></tr>

<tr><td><a href="sndscm.html#maxfdoc">maxf</a></td>
    <td>Max Mathews resonator</td></tr>

<tr><td><a href="sndscm.html#menusdoc">menus</a></td>
    <td>additional menus</td></tr>

<tr><td><a href="sndscm.html#mixdoc">mix</a></td>
    <td>functions related to mixes</td></tr>

<tr><td><a href="sndscm.html#moogdoc">moog</a></td>
    <td>Moog filter</td></tr>

<tr><td><a href="sndscm.html#musglyphs">musglyphs</a></td>
    <td>Music notation symbols (from CMN)</td></tr>

<tr><td><a href="sndscm.html#nbdoc">nb</a></td>
    <td>Popup File info etc</td></tr>

<tr><td><a href="sndscm.html#noisedoc">noise</a></td>
    <td>noise maker</td></tr>

<tr><td><a href="sndscm.html#numericsdoc">numerics</a></td>
    <td>various numerical functions</td></tr>

<tr><td><a href="sndscm.html#peakphasesdoc">peak-phases</a></td>
    <td>phases for the unpulse-train</td></tr>

<tr><td><a href="sndscm.html#pianodoc">piano</a></td>
    <td>piano physical model</td></tr>

<tr><td><a href="sndscm.html#playdoc">play</a></td>
    <td>play-related functions</td></tr>

<tr><td><a href="sndscm.html#polydoc">poly</a></td>
    <td>polynomial-related stuff</td></tr>

<tr><td><a href="sndscm.html#prc95doc">prc95</a></td>
    <td>Perry Cook's physical model examples</td></tr>

<tr><td><a href="sndscm.html#pvocdoc">pvoc</a></td>
    <td>phase-vocoder</td></tr>

<tr><td><a href="sndscm.html#rgbdoc">rgb</a></td>
    <td>color names</td></tr>

<tr><td><a href="sndscm.html#rubberdoc">rubber</a></td>
    <td>rubber-sound</td></tr>

<tr><td><a href="sndscm.html#selectiondoc">selection</a></td>
    <td>functions acting on the current selection</td></tr>

<tr><td><a href="sndscm.html#singerdoc">singer</a></td>
    <td>Perry Cook's vocal-tract physical model</td></tr>

<tr><td><a href="sndscm.html#sndolddoc">snd15.scm</a></td>
    <td>Backwards compatibility</td></tr>

<tr><td><a href="sndscm.html#snddiffdoc">snddiff</a></td>
    <td>sound difference detection</td></tr>

<tr><td><a href="sndscm.html#sndgldoc">snd-gl</a></td>
    <td>OpenGL examples (gl.c)</td></tr>

<tr><td><a href="sndscm.html#sndmotifdoc">snd-motif, snd-xm</a></td>
    <td>Motif module (xm.c)</td></tr>

<tr><td><a href="sndscm.html#sndtestdoc">snd-test</a></td>
    <td>Snd regression tests</td></tr>

<tr><td><a href="sndscm.html#sndwarpdoc">sndwarp</a></td>
    <td>Bret Battey's sndwarp instrument</td></tr>

<tr><td><a href="sndscm.html#spectrdoc">spectr</a></td>
    <td>instrument steady state spectra</td></tr>

<tr><td><a href="sndscm.html#stochasticdoc">stochastic</a></td>
    <td>Bill Sack's dynamic stochastic synthesis</td></tr>

<tr><td><a href="sndscm.html#straddoc">strad</a></td>
    <td>string physical model (from CLM)</td></tr>

<tr><td><a href="sndscm.html#tankrevdoc">tankrev</a></td>
    <td>Jon Dattorro's plate reverb (Anders Vinjar)</td></tr>

<tr><td><a href="sndscm.html#vdoc">v</a></td>
    <td>fm-violin</td></tr>

<tr><td><a href="sndscm.html#wsdoc">ws</a></td>
    <td>with-sound</td></tr>

<tr><td><a href="sndscm.html#zipdoc">zip</a></td>
    <td>the zipper (the anti-cross-fader)</td></tr>
</tbody>
</table>
</td></tr></table>


<div class="header" id="behavior">Customizing Snd's behavior</div>

<p>Most of Snd's behavior can be customized.  For example,
when a sound is saved, some people want to be warned if
a pre-existing sound is about to be destroyed; others (Snd's
author included) grumble "just do it".  There are two ways
this kind of situation is handled in Snd; through global variables and hooks.
A hook is a list of callbacks invoked whenever its associated
event happens.  When Snd exits, for example, any functions found
on the <a href="#beforeexithook">before-exit-hook</a> list are evaluated; if any of them returns #t,
Snd does not exit.</p>

<pre class="indented">
(define (unsaved-edits? lst)
  (and (pair? lst)
       (if (&gt; (car (<a class=quiet href="#edits">edits</a> (car lst))) 0)
	   (begin
	     (<a class=quiet href="#statusreport">status-report</a> "there are unsaved edits")
	     #t)
	   (unsaved-edits? (cdr lst)))))

(hook-push <em class=red>before-exit-hook</em> 
  (lambda (hook) 
    (set! (hook 'result) (unsaved-edits? (<a class=quiet href="#sounds">sounds</a>)))))
</pre>

<p>Now when Snd is told to exit, it checks before-exit-hook, runs
unsaved-edits?, and if the latter returns #t, if prints
a worried message in the status area, and refuses to
exit.  Similar hooks customize actions such as closing
a sound (<a href="#closehook">close-hook</a>), clicking a mark (<a href="#markclickhook">mark-click-hook</a>),
pressing a key (<a href="#keypresshook">key-press-hook</a>), and so on.</p>



<div class="header" id="sndglobalvars">Global variables</div>

<p>The global variables handle various customizations that aren't callback-oriented.
For example, 
as sounds come and go, Snd's overall size may change (this is
partly determined by the window manager, but is also
up to Snd).  Many people find this distracting &mdash; they would rather that the
overall window stick to one size.  The Snd variable associated
with this is "auto-resize"; it can be accessed as:
</p>
<pre class="indented">
  Scheme: *auto-resize* or (auto-resize)
  Ruby:   auto_resize()
  Forth:  auto-resize
</pre>
<p>and set via:</p>
<pre class="indented">
  Scheme: (set! *auto-resize* #f) or (set! (auto-resize) #f)
  Ruby:   set_auto_resize(false)
  Forth:  #f set-auto-resize
</pre>
<p>
I originally wanted a variable like auto-resize to look like a variable in source files, but 
in those bygone days (1996), that was not possible:  I had to use a dumb "procedure-with-setter" instead.
So you'd sigh and access auto-resize by calling it as a function: <code>(set! (auto-resize) #t)</code>.
Now in s7, the same thing is also named *auto-resize*, but it's finally a variable,
so you can use <code>(set! *auto-resize* #t)</code>.  The documentation of course
is out of date, and mostly uses the old form.  In any case,
the statement (set! *auto-resize* #f) can be placed in your ~/.snd initialization file
to make it the default setting for your version of Snd, or placed
in a separate file of Scheme code and loaded at any time via the load
function. </p>

<p>The functions affecting Snd's overall behavior are given below; in s7 there is
also the variable of the same name, but with "*" around it: *auto-resize*.
</p>

<div class="spacer"></div>

<!-- ask-about-unsaved-edits -->
<pre class="indented">
<em class=def id="askaboutunsavededits">ask-about-unsaved-edits</em> (default: #f)
</pre>

<p>If ask-about-unsaved-edits is #t, Snd worries about unsaved edits when a sound is about to be closed.
Otherwise Snd just closes the sound, flushing any unsaved edits.
<code>(set! (ask-about-unsaved-edits) #t)</code>
</p>
<div class="spacer"></div>


<!-- ask-before-overwrite -->
<pre class="indented">
<em class=def id="askbeforeoverwrite">ask-before-overwrite</em> (default: #f)
</pre>

<p>ask-before-overwrite determines whether Snd asks before overwriting an existing file:
<code>(set! (ask-before-overwrite) #t)</code>
</p>
<div class="spacer"></div>


<!-- auto-resize -->
<pre class="indented">
<em class=def id="autoresize">auto-resize</em> (default: #t in Motif
</pre>

<p>auto-resize determines whether the Snd window should be resized
when a sound is opened or closed.
</p>
<div class="spacer"></div>


<!-- auto-update -->
<pre class="indented">
<em class=def id="autoupdate">auto-update</em> (default: #f)
</pre>

<p>auto-update determines whether Snd should <a href="snd.html#updatefile">update</a> a file automatically 
if it (the file) changes on disk due to some other process.
If Snd's view of a sound doesn't match the on-disk version of the sound, 
a warning is posted that there are two conflicting versions of the sound.
</p>
<div class="spacer"></div>


<!-- auto-update-interval -->
<pre class="indented">
<em class=def id="autoupdateinterval">auto-update-interval</em> (default: 60)
</pre>

<p>This is the time (in seconds) between background checks for a changed file on 
disk (see <a href="#autoupdate">auto-update</a>). If auto-update-interval is 0.0, the auto-update background process 
is turned off.
</p>
<div class="spacer"></div>


<!-- clipping -->
<pre class="indented">
<em class=def id="clipping">clipping</em> (default: #f)
</pre>

<p>If clipping is #t, output values are clipped to fit the current sndlib sample
representation's notion of -1.0 to just less than 1.0.  The default (#f)
can cause wrap-around (if writing integer sound data) which makes the out-of-range values very obvious.
To control this action more closely, use <a href="#cliphook">clip-hook</a>.
To get completely confused, see <a href="#musclipping">mus-clipping</a> and <a href="#musfileclipping">mus-file-clipping</a>:
this has become as messed up as the sampling rate settings!
</p>
<div class="spacer"></div>


<!-- cursor-location-offset -->
<pre class="indented">
<em class=def id="cursorlocationoffset">cursor-location-offset</em> (default: 0.05)
</pre>

<p>cursor-location-offset is the offset in samples between Snd's notion of the location of the tracking cursor
(<a href="#withtrackingcursor">with-tracking-cursor</a> in Snd jargon) and the actual (DAC-relative) location.
Since, in general, Snd can't tell how many samples of buffering there are between itself
and the speakers (audio cards have varying amounts), its notion of where to place the
tracking cursor can be wrong by an almost arbitrary amount.  If you have some idea
of the buffering amount, you can correct this error via cursor-location-offset.
</p>
<div class="spacer"></div>


<!-- cursor-update-interval -->
<pre class="indented">
<em class=def id="cursorupdateinterval">cursor-update-interval</em> (default: 0.05)
</pre>

<p>This is the time in seconds between 
cursor redisplays if playing a sound with <a href="#withtrackingcursor">with-tracking-cursor</a> #t.  
If this number is too small, you may clicks during playback.
</p>
<div class="spacer"></div>


<!-- dac-combines-channels -->
<pre class="indented">
<em class=def id="dacfolding">dac-combines-channels</em> (default: #t)
</pre>

<p>If dac-combines-channels is #t, and the current sound has more channels than are
supported by the available audio hardware, Snd mixes the extra channels into the available channels during audio output.
This provides a way to hear 4-channel sounds when you only have a stereo audio card.
If dac-combines-channels is #f, extra channels are not played.
</p>
<div class="spacer"></div>


<!-- dac-size -->
<pre class="indented">
<em class=def id="dacsize">dac-size</em> (default: 256)
</pre>

<p>dac-size is the audio output buffer size;  it is not always meaningful.  See <a href="sndscm.html#playwithenvs">play-with-envs</a> in enved.scm.
When you change the control panel settings during playback, the snappiness of the
response is set, to some extent, by the dac-size.  The default of 256 gives a stair-case effect in many
cases, whereas 2048 is smoother.  This also affects the resampling smoothness of playback while dragging the
mark play triangle.  Some audio choices, ALSA in particular, may ignore dac-size.
</p>
<div class="spacer"></div>


<!-- default-output-chans -->
<pre class="indented">
<em class=def id="defaultoutputchans">default-output-chans</em> (default: 1)
</pre>

<p>default-output-chans is the default number of channels when a new or temporary file is created, 
or a save dialog is opened.
</p>
<div class="spacer"></div>


<!-- default-output-header-type -->
<pre class="indented">
<em class=def id="defaultoutputheadertype">default-output-header-type</em> (default: mus-next)
</pre>

<p>This is the default header type when a new file is created, 
or a save dialog is opened. (The default, mus-next, stands for the NeXT/Sun sound file header).
The available output header-types are:
</p>

<pre>
    mus-next mus-aifc mus-riff mus-rf64 mus-nist mus-raw mus-ircam mus-aiff 
    mus-soundfont mus-bicsf mus-voc mus-svx mus-caff
</pre>

<div class="spacer"></div>


<!-- default-output-sample-type -->
<pre class="indented">
<em class=def id="defaultoutputsampletype">default-output-sample-type</em> (default: mus-bfloat)
</pre>

<p>default-output-sample-type is the default sample type when a new or temporary file is created, 
or a save dialog is opened. (The default, mus-bfloat, is from sndlib, standing for 32-bit big-endian floating point data).  
Use <a href="#musoutformat">mus-out-format</a> for fastest IO.
The available output sample types are (b=big-endian, l=little, u=unsigned, short=16 bits, byte=8 bits, int = 32 bits):
</p>

<pre>
    mus-bshort  mus-lshort mus-mulaw  mus-alaw   mus-byte   mus-ubyte   mus-bfloat
    mus-lfloat  mus-bint   mus-lint   mus-b24int mus-l24int mus-bdouble mus-ldouble
    mus-ubshort mus-ulshort
</pre>

<p>There are also "unscaled" versions of the floating point types, and "normalized" versions of the integers.
</p>
<div class="spacer"></div>


<!-- default-output-srate -->
<pre class="indented">
<em class=def id="defaultoutputsrate">default-output-srate</em> (default: 44100)
</pre>

<p>This is the default sampling rate when a new or temporary file is created, 
or a save dialog is opened.  It also sets the default CLM srate (*clm-srate* in ws.scm),
so all CLM generators use it outside with-sound.
</p>
<div class="spacer"></div>


<!-- eps-bottom-margin -->
<pre class="indented">
<em class=def id="epsbottommargin">eps-bottom-margin</em> (default: 0.0)
</pre>

<p>eps-bottom-margin is the bottom margin used in snd.eps, created by the File:Print dialog, or the <a href="#graphtops">graph-&gt;ps</a> function.
PostScript units are 1/72 of an inch (a "point" in printer jargon); 
an inch is 2.54 cm:
</p>

<table>
<tr>
<td>
<div class="scheme">
<pre class="indented">
Scheme:

(define (inches-to-ps inches) 
  (* inches 72))

(define (cm-to-ps cm) 
  (* cm (/ 72.0 2.54)))
</pre>
</div>
</td>
<td>
<div class="ruby">
<pre class="indented">
Ruby:
def inches_to_ps(inches) 
  inches * 72 
end
def cm_to_ps(cm) 
  cm * 72.0 / 2.54 
end
</pre>
</div>
</td>
<td>
<div class="forth">
<pre class="indented">
Forth:
: inches-to-ps { inches } 
  inches 72 f* 
;
: cm-to-ps { cm } 
  cm 2.54 f/ 72 f* 
;
</pre>
</div>
</td></tr></table>

<p>In the resulting .eps file, you'll find a concat statement near the 
top of the file; the first and fourth numbers are scale factors on 
the entire graph, the fifth is the left margin, and the sixth is the 
bottom margin.
</p>
<div class="spacer"></div>


<!-- eps-file -->
<pre class="indented">
<em class=def id="epsfile">eps-file</em> (default: "snd.eps")
</pre>

<p>This is the default name of the Postscript file produced by the File:Print dialog, or the <a href="#graphtops">graph-&gt;ps</a> function.
</p>
<div class="spacer"></div>


<!-- eps-left-margin -->
<pre class="indented">
<em class=def id="epsleftmargin">eps-left-margin</em> (default: 0.0)
</pre>

<p>eps-left-margin is the left margin used in snd.eps, created by the File:Print dialog, or the <a href="#graphtops">graph-&gt;ps</a> function.
</p>
<div class="spacer"></div>


<!-- eps-size -->
<pre class="indented">
<em class=def id="epssize">eps-size</em> (default: 1.0)
</pre>

<p>eps-size is the scaler used to set the overall picture size in snd.eps, 
created by the File:Print dialog, or the <a href="#graphtops">graph-&gt;ps</a> function,
</p>
<div class="spacer"></div>


<!-- graph-cursor -->
<pre class="indented">
<em class=def id="graphcursor">graph-cursor</em> (default: XC_crosshair (34))
</pre>

<p>graph-cursor is the kind of cursor displayed following the mouse in the data graph.
It can be any of the cursors provided by X: <code>(set! (graph-cursor) 22)</code>.
The X/Motif cursors are declared in /usr/include/X11/cursorfont.h or some such file.
Some useful choices are:
</p>

<pre class="indented">
    Motif         value

XC_center_ptr      22
XC_cross           30
XC_crosshair       34
XC_left_ptr        68
XC_plus            90
XC_right_ptr       94
XC_tcross         130
XC_xterm          152
</pre>

<div class="spacer"></div>



<!-- html-dir -->
<pre class="indented">
<em class=def id="htmldir">html-dir</em> (default: ".")
</pre>

<p>html-dir is the directory to search for documentation if an HTML reader is in use.
See the function html in index.scm.
</p>
<div class="spacer"></div>



<!-- html-program -->
<pre class="indented">
<em class=def id="htmlprogram">html-program</em> (default: "firefox")
</pre>

<p>This is the program to use to read HTML files.
On the Mac, you need to give the full path to the executable image: "/Applications/Safari.app/Contents/MacOS/Safari".
See the function html in index.scm.
</p>
<div class="spacer"></div>


<!-- initial-beg -->
<pre class="indented">
<em class=def id="initialbeg">initial-beg</em> (default: 0.0)
</pre>

<p>initial-beg is the start point (in seconds) of the initial graph of a sound.
</p>
<div class="spacer"></div>


<!-- initial-dur -->
<pre class="indented">
<em class=def id="initialdur">initial-dur</em> (default: 0.1)
</pre>

<p>initial-dur is the duration (in seconds) of the initial graph of a sound.
</p>
<div class="spacer"></div>


<!-- just-sounds -->
<pre class="indented">
<em class=def id="justsounds">just-sounds</em> (default: #t)
</pre>

<p>If just-sounds is #t,
the file lists displayed by the file selection dialogs are filtered to show just
sound files (see <a href="#addsoundfileextension">add-sound-file-extension</a>).
</p>
<div class="spacer"></div>


<!-- ladspa-dir -->
<pre class="indented">
<em class=def id="ladspadir">ladspa-dir</em> (default: #f)
</pre>

<p>LADSPA is a way of managing plug-ins in Linux.  I consider it very old-fashioned, but 
there are a bunch of ladspa libraries, and they're easy to load. so...
ladspa-dir is the
name of the directory to search for LADSPA plugin libraries (it can override or replace LADSPA_PATH).
See <a href="grfsnd.html#sndandladspa">Snd and LADSPA</a>.
</p>
<div class="spacer"></div>


<!-- log-freq-start -->
<pre class="indented">
<em class=def id="logfreqstart">log-freq-start</em> (default: 32.0)
</pre>

<p>log-freq-start is the start (lowest) frequency used in the log freq display (ffts).  Since the log display emphasizes the lower
frequencies, but the lowest are all inaudible, it seemed more informative to squash the lowest 30Hz or so
into a single point (0 Hz) on the log freq graphs; otherwise the audible data starts about 1/4 of the way 
down the x axis, wasting valuable screen space!  But it also seemed a bother to have to set/reset the
<a href="#spectrumstart">spectrum-start</a> variable every time you wanted to flip between log and linear
displays.  log-freq-start to the rescue?  For other ideas along these lines, see <a href="sndscm.html#displaybarkfft">display-bark-fft</a>.
</p>
<div class="spacer"></div>


<!-- max-regions -->
<pre class="indented">
<em class=def id="maxregions">max-regions</em> (default: 16)
</pre>

<p>This sets the maximum size of the region list, the number of regions that are accessible.
</p>
<div class="spacer"></div>


<!-- mus-max-malloc -->
<pre class="indented">
<em class=def id="musmaxmalloc">mus-max-malloc</em> (default: 67108864)
</pre>

<p>This sets the maximum memory allocation (in bytes).
In s7, you can use the variable *mus-max-malloc* instead.
</p>
<div class="spacer"></div>


<!-- mus-max-table-size -->
<pre class="indented">
<em class=def id="musmaxtablesize">mus-max-table-size</em> (default: 20971520)
</pre>

<p>This sets the maximum table size (delay line length in samples, etc).
In s7, you can use the variable *mus-max-table-size* instead.
</p>
<div class="spacer"></div>


<!-- mus-sound-path -->
<pre class="indented">
<em class=def id="mussoundpath">mus-sound-path</em> (default: ())
</pre>

<p>This is the list of directories searched for an incompletely specified sound file.
The current directory is always searched first.
</p>
<div class="spacer"></div>


<!-- open-file-dialog-directory -->
<pre class="indented">
<em class=def id="openfiledialogdirectory">open-file-dialog-directory</em> (default: ".")
</pre>

<p>open-file-dialog-directory is the name of the initial open file dialog directory (normally ".").
</p>
<div class="spacer"></div>


<!-- peak-env-dir -->
<pre class="indented">
<em class=def id="peakenvdir">peak-env-dir</em> (default: #f)
</pre>

<p>peak-env-dir is the directory to use for peak env files; if it is #f (the default), the peak-env machinery is turned off.
If the peak-env-dir is writable, Snd saves an overview of the sound data in that directory to speed up
the initial graph display the next time you open that sound.
</p>
<div class="spacer"></div>


<!-- play-arrow-size -->
<pre class="indented">
<em class=def id="playarrowsize">play-arrow-size</em> (default: 10)
</pre>

<p>This is the size of the triangular arrow that handles click-to-play duties for the cursor, marks, mixes, and the selection.
</p>
<div class="spacer"></div>


<!-- print-length -->
<pre class="indented">
<em class=def id="printlength">print-length</em> (default: 12)
</pre>

<p>For objects such as float-vectors, print-length sets the number of elements printed.
In s7, this also sets (*s7* 'print-length).
</p>

<pre class="indented">
&gt; (set! (print-length) 3)
3
&gt; (make-float-vector 10 .1)
#(0.1 0.1 0.1 ...)
</pre>
<div class="spacer"></div>


<!-- remember-sound-state -->
<pre class="indented">
<em class=def id="remembersoundstate">remember-sound-state</em> (default: #f)
</pre>

<p>If remember-sound-state is #t, Snd saves most of a sound's display state when it is closed,
and if that same sound is later re-opened, restores the previous state.
</p>
<div class="spacer"></div>


<!-- save-dir -->
<pre class="indented">
<em class=def id="savedir">save-dir</em> (default: #f)
</pre>

<p>save-dir is the name of the directory for saved-state files.  
These files are written when you call <a href="#savestate">save-state</a> or
choose the Options:Save session menu item.  If any of the current sounds has
an edit that requires saved data, it is written as a separate sound file, and
that file is reloaded automatically when you restart the saved session.  To keep such
files safe, or at least separate from others, you can set up separate
directory for them.
</p>
<div class="spacer"></div>


<!-- save-state-file -->
<pre class="indented">
<em class=def id="savestatefile">save-state-file</em> (default: "saved-snd.scm")
</pre>

<p>This is the <a href="snd.html#savedstate">saved state</a> file name.
</p>
<div class="spacer"></div>


<!-- search-procedure -->
<pre class="indented">
<em class=def id="searchprocedure">search-procedure</em>
</pre>

<p>This is the search procedure used by the find dialog or C-s if none is otherwise specified.
</p>

<pre class="indented">
(set! (<a class=quiet href="#searchprocedure">search-procedure</a>) (lambda (y) (&gt; y .1)))
</pre>
<div class="spacer"></div>


<!-- selection-creates-region -->
<pre class="indented">
<em class=def id="selectioncreatesregion">selection-creates-region</em> (default: #t)
</pre>

<p>If selection-creates-region is #t, a region is created whenever a selection is made.  If you're editing very large sounds
and using selections, the region temp files can use up a lot of disk space (and the time to write
them); if you're not using regions anyway, this switch can turn them off.
</p>
<div class="spacer"></div>


<!-- show-full-duration -->
<pre class="indented">
<em class=def id="showfullduration">show-full-duration</em> (default: #f)
</pre>

<p>If show-full-duration is #t, Snd displays the entire sound when it is first opened.
</p>
<div class="spacer"></div>


<!-- show-full-range -->
<pre class="indented">
<em class=def id="showfullrange">show-full-range</em> (default: #f)
</pre>

<p>If show-full-range is #t, Snd makes sure the sound's graph y bounds can accommodate the
entire range of sample values.  This is especially useful when you're working with sounds
that go beyond the normal -1.0 to 1.0 range.
</p>
<div class="spacer"></div>


<!-- show-indices -->
<pre class="indented">
<em class=def id="showindices">show-indices</em> (default: #f)
</pre>

<p>If show-indices is #t, each sound's name is preceded by its index in the sound pane.
</p>
<div class="spacer"></div>


<!-- show-selection-transform -->
<pre class="indented">
<em class=def id="showselectiontransform">show-selection-transform</em> (default: #f)
</pre>

<p>If show-selection-transform is #t, Snd displays the transform of the current active selection, if any.
The sonogram and spectrogram displays ignore this flag because they assume their time axis
matches that of the time domain graph.
</p>
<div class="spacer"></div>


<!-- sinc-width -->
<pre class="indented">
<em class=def id="sincwidth">sinc-width</em> (default: 10)
</pre>

<p>sinc-width is the width in samples of the sampling rate conversion sinc interpolation.
The higher this number, the better the src low-pass filter, but the slower
src runs.  If you use too low a setting, you can sometimes hear high 
frequency whistles leaking through. To hear these on purpose, make 
a sine wave at (say) 55 Hz, then <code>(<a class=quiet href="#srcsound">src-sound</a> '(0 3 1 1))</code>
with sinc-width at 4.
</p>
<div class="spacer"></div>


<!-- sync-style -->
<pre class="indented">
<em class=def id="syncstyle">sync-style</em> (default: sync-by-sound)
</pre>

<p>sync-style determines how sounds and their channels are sync'd together when they are
opened.  sync-none means that no sounds, and no channels are tied together;
sync-all causes everything to be tied together; sync-by-sound, the default, causes individual sounds to
be separate, but if they have more than one channel, all the channels are tied together.
</p>
<div class="spacer"></div>


<!-- temp-dir -->
<pre class="indented">
<em class=def id="tempdir">temp-dir</em> (default: #f)
</pre>

<p>temp-dir is the directory to use for temporary files; if it is #f, Snd uses whatever the system default is, usually "/tmp" or "/var/tmp".  
See also <a href="#sndtempnam">snd-tempnam</a>.
</p>
<div class="spacer"></div>


<!-- window-height -->
<pre class="indented">
<em class=def id="windowheight">window-height</em> (default: 0)
</pre>

<p>window-height is the current Snd window height in pixels.
This is the same as
</p>

<pre class="indented">
Scheme: (cadr (<a class=quiet href="#widgetsize">widget-size</a> (cadr (<a class=quiet href="#mainwidgets">main-widgets</a>))))
Ruby:   widget_size(main_widgets.cadr).cadr
Forth:  main-widgets cadr widget-size cadr
</pre>

<p>except at startup when the window-height function and friends defer the assignment until after the main widgets
have been created.  If Snd becomes confused about screen size, it can make its main window so large that
you can't get at any of the decorations for resizing the window; in this emergency you can
<code>(set! (window-height) 300)</code> or some such number.
</p>
<div class="spacer"></div>


<!-- window-width -->
<pre class="indented">
<em class=def id="windowwidth">window-width</em> (default: 0)
</pre>

<p>This is the current Snd window width in pixels.
</p>
<div class="spacer"></div>


<!-- window-x -->
<pre class="indented">
<em class=def id="windowx">window-x</em> (default: -1)
</pre>

<p>This is the current Snd window left side position in pixels (-1 means unset).
This is (usually) the same as
<code>(car (<a class=quiet href="#widgetposition">widget-position</a> (cadr (<a class=quiet href="#mainwidgets">main-widgets</a>))))</code>.
</p>
<div class="spacer"></div>


<!-- window-y -->
<pre class="indented">
<em class=def id="windowy">window-y</em> (default: -1)
</pre>

<p>This is the current Snd window upper side position in pixels (X numbering starts at 0 at the top, -1 means unset).
</p>
<div class="spacer"></div>


<!-- with-background-processes -->
<pre class="indented">
<em class=def id="withbackgroundprocesses">with-background-processes</em> (default: #t)
</pre>

<p>with-background-processes determines whether Snd should use background (idle time) processes for ffts and so forth. 
It is intended primarily for auto-testing.
</p>
<div class="spacer"></div>


<!-- with-file-monitor -->
<pre class="indented">
<em class=def id="withfilemonitor">with-file-monitor</em> (default: #t)
</pre>

<p>If with-file-monitor is #t, the file alteration monitor is active.  There are still bugs
in this library that can cause Snd to hang &mdash; I haven't tracked down what the problem is yet; in the meantime,
set this switch to #f to disable the monitor. 
</p>
<div class="spacer"></div>


<!-- with-inset-graph -->
<pre class="indented">
<em class=def id="withinsetgraph">with-inset-graph</em> (default: #f)
</pre>

<p>If with-inset-graph is #t, a small graph is
added to the upper right corner showing the overall current sound and where the current window fits in it.
This information is implicit in the x axis zoom and position sliders, but a redundant graph doesn't hurt.  If you click in that graph,
the cursor is moved to the clicked point.  
</p>

<img class="indented" src="pix/uppergrf.png" alt="with-inset-graph">
<div class="spacer"></div>


<!-- with-interrupts -->
<pre class="indented">
<em class=def id="withinterrupts">with-interrupts</em> (default: #t)
</pre>

<p>If with-interrupts is true, the Snd listener (in Motif) adds a check for GUI activity to each
computation called from the listener.  This makes it possible to stop an infinite loop, or use the
user interface while some long computation is running, but it also slows down that computation.
To get the maximum performance, set this flag to false (#f).
</p>
<div class="spacer"></div>


<!-- with-menu-icons -->
<pre class="indented">
<em class=def id="withmenuicons">with-menu-icons</em> (default: #t)
</pre>

<p>with-menu-icons determines whether some menus display icons beside the item labels.
</p>
<div class="spacer"></div>



<!-- with-pointer-focus -->
<pre class="indented">
<em class=def id="withpointerfocus">with-pointer-focus</em> (default: #f)
</pre>

<p>If with-pointer-focus is #t, whatever text or graph widget is underneath the mouse cursor is activated
(this is sometimes known as "point-to-focus" mode).
</p>
<div class="spacer"></div>


<!-- with-relative-panes -->
<pre class="indented">
<em class=def id="withrelativepanes">with-relative-panes</em> (default: #t)
</pre>

<p>If with-relative-panes is #t in the Motif
version of Snd, a multichannel sound tries to retain the relative channel graph sizes
when the outer sash (the overall sound size sash) changes.
Mono sounds and the listener are not affected (perhaps they should be?).
</p>
<div class="spacer"></div>


<!-- with-smpte-label -->
<pre class="indented">
<em class=def id="withsmptelabel">with-smpte-label</em> (default: #f)
</pre>

<p>with-smpte-label shows the current SMPTE frame number in a box
in the upper left corner of the graph (see the picture above under add-mark-pane).
</p>
<div class="spacer"></div>


<!-- with-toolbar -->
<pre class="indented">
<em class=def id="withtoolbar">with-toolbar</em> (default: #f (motif))
</pre>

<p>with-toolbar places a toolbar at the top of the Snd window, just under the main menu.
</p>

<img class="indented" src="pix/toolbar.png" alt="with-toolbar picture">
<div class="spacer"></div>


<!-- with-tooltips -->
<pre class="indented">
<em class=def id="withtooltips">with-tooltips</em> (default: #t)
</pre>

<p>Set with-tooltips to #f to turn off tooltips.
</p>
<div class="spacer"></div>



<!-- with-tracking-cursor -->
<pre class="indented">
<em class=def id="withtrackingcursor">with-tracking-cursor</em> (default: #f)
</pre>

<p id="trackingcursors">This is #t if the cursor always follows along in the sound during playback.  If it is #f, 
you get the tracking cursor displayed only when you ask for it (via control-click of the
play button, for example).  At the end of the play, the default is to return to the original (starting)
cursor position.  If you want the cursor to stay where it is, set with-tracking-cursor to :track-and-stay
(#t = :track-and-return).
</p>

<p>
The interval (in seconds) between cursor updates is set by <a href="#cursorupdateinterval">cursor-update-interval</a>
which defaults to 0.05.  The accuracy of the cursor in reflecting the sound coming out the speakers
depends on the amount of buffering in your audio system.  If Snd's displayed location is off,
set <a href="#cursorlocationoffset">cursor-location-offset</a> to reflect the number of samples
of buffering you think you probably have.  A positive cursor-location-offset delays the cursor's 
apparent progress (if playing forwards). 
</p>

<!-- INDEX trackingcursors:Tracking cursors -->

<TABLE class="method">
<tr><th class="title">tracking cursor</th></tr>
<tr><td>
<blockquote><small>
play from the current cursor position with a tracking cursor:  <a href="#pfc">pfc</a><br>
display tracking cursor as a full height vertical line: <a href="#trackingcursorstyle">tracking-cursor-style</a><br>
track play once: control-click 'play'. (You can add a mark at the current tracking cursor location during the play with C-m)<br>
leave the cursor at the final position after tracking play: (set! *with-tracking-cursor* :track-and-stay)<br>
tracking cursor accuracy: <a href="#cursorlocationoffset">cursor-location-offset</a><br>
tracking cursor updating: <a href="#cursorupdateinterval">cursor-update-interval</a><br>
</small></blockquote>
</td></tr></TABLE>

<div class="spacer"></div>




<!-- zoom-focus-style -->
<pre class="indented">
<em class=def id="zoomfocusstyle">zoom-focus-style</em> (default: zoom-focus-active)
</pre>

<p>This determines what a zoom action focuses (centers) on. The choices are 
zoom-focus-left, zoom-focus-right, zoom-focus-active, zoom-focus-middle,
or a function of 6 arguments.  The function should return the new window left edge as a float.
Its arguments are the current sound, channel number, zoom slider value (0.0 to 1.0), time domain window left and right
edges in seconds, and the current total x axis size (seconds) corresponding to a slider value
of 1.0.
</p>

<pre class="indented">
(set! (zoom-focus-style) (lambda (snd chn zx x0 x1 range) (- x1 (* zx range))))
</pre>

<p>mimics zoom-focus-right.  zoom-focus-active tries to focus on some object in the view: the cursor, a mix or mark, etc.
See also <a href="snd.html#zoomoption">Zoom options</a>.
</p>





<!--  GENERIC FUNCTIONS  -->

<div class="header" id="sndgenericfuncs">Generic functions</div>

<p>Several functions in Snd are "generic" in the sense that they can handle a wide
variety of objects.  The length function, for example, applies to strings and vectors,
as well as lists.  Objects specific to Snd include sounds, the selection, mixes, marks,
samplers, regions, and players, all of which should be compared with equal?, not eq?.
</p>

<div class="spacer"></div>


<!-- channels -->
<!-- INDEX genericchannels:channels (generic) -->
<pre class="indented">
<em class=def>channels</em> obj
</pre>

<p id="genericchannels">channels handles strings (<a href="#mussoundchans">mus-sound-chans</a>), 
<a href="#regionchans">region-chans</a>, 
the current selection (<a href="#selectionchans">selection-chans</a>),
<a href="sndclm.html#genericfunctions">mus-channels</a>,
<a href="#sndmixes">mixes</a>, <a href="#Floatvectors">float-vectors</a>, and vectors (always 1 channel), and 
<a href="#sndsounds">sounds</a> (as objects or as integers).
</p>
<div class="spacer"></div>


<!-- copy -->
<!-- INDEX genericcopy:copy (generic) -->
<pre class="indented">
<em class=def>copy</em> obj
</pre>

<p id="genericcopy">copy returns a copy of its argument.
It works with strings, lists, vectors, hash tables, float-vectors, sounds, the current selection, mixes, marks,
bignums, and the non-gmp random state objects.
</p>
<div class="spacer"></div>


<!-- file-name -->
<!-- INDEX genericfilename:file-name (generic) -->
<pre class="indented">
<em class=def>file-name</em> obj
</pre>

<p id="genericfilename">filename can replace <a href="#musexpandfilename">mus-expand-filename</a>, 
<a href="sndclm.html#genericfunctions">mus-file-name</a>, and (s7 scheme's) port-filename,
as well as handling mixes, regions, samplers, and the regular sound-oriented <a href="#filename">file-name</a>.
</p>
<div class="spacer"></div>


<!-- fill! -->
<!-- INDEX genericfill:fill! (generic) -->
<pre class="indented">
<em class=def>fill!</em> obj val
</pre>

<p id="genericfill">fill! fills obj with val (s7 only).
fill! works with strings, vectors, hash-tables, float-vectors, lists, sounds, and the selection.
</p>
<div class="spacer"></div>


<!-- framples -->
<!-- INDEX genericframples:framples (generic) -->
<pre class="indented">
<em class=def>framples</em> obj chn edpos
</pre>

<p id="genericframples">framples returns the number of "framples" in an object, that is,
the number of samples per channel (a frample is a set of samples, representing
each channel's value at a given sampling instant, a "sample frame" or a "frame of samples"
in old time terminology).
</p>
<p>
The framples function overlaps
the <a href="#genericlength">length</a> function, but length of a string is string-length, whereas framples of a string
treats the string as a sound file name and returns <a href="#mussoundframples">mus-sound-framples</a>.  framples can replace
<a href="#mussoundframples">mus-sound-framples</a>, <a href="sndclm.html#genericfunctions">mus-length</a>, 
<a href="#mixlength">mix-length</a>, 
<a href="#regionframples">region-framples</a>, <a href="#selectionframples">selection-framples</a>,
and the regular <a href="#framples">framples</a> function that handles sound objects and integers as sound indices.
</p>
<div class="spacer"></div>


<!-- length -->
<!-- INDEX genericlength:length (generic) -->
<pre class="indented">
<em class=def>length</em> obj
</pre>

<p id="genericlength">length handles list length, string-length, vector-length, 
<a href="#framples">framples</a> (sound length), <a href="#colormapsize">colormap-size</a>,
<a href="sndclm.html#genericfunctions">mus-length</a> (generators),
<a href="#mixlength">mix-length</a>, <a href="#transformsize">transform-size</a>,
<a href="#selectionframples">selection-framples</a>,
and <a href="#regionframples">region-framples</a>.
</p>
<div class="spacer"></div>


<!-- maxamp -->
<!-- INDEX genericmaxamp:maxamp (generic) -->
<pre class="indented">
<em class=def>maxamp</em> obj chn
</pre>

<p id="genericmaxamp">maxamp can handle a sound (via the regular <a href="#maxamp">maxamp</a> function),
string (treated as a sound file name, <a href="#mussoundmaxamp">mus-sound-maxamp</a>),
generator (maxamp of the mus-data float-vector, if any),
float-vector,
region (<a href="#regionmaxamp">region-maxamp</a>),
the current selection (<a href="#selectionmaxamp">selection-maxamp</a>),
vector, list, or mix object.
</p>
<div class="spacer"></div>


<!-- play -->
<!-- INDEX genericplay:play (generic) -->
<pre class="indented">
<em class=def>play</em> object :start :end :channel :edit-position :out-channel :with-sync :wait :stop :srate :channels
</pre>

<p id="genericplay">play plays an object. 
The object can be a string (sound filename), a sound object or index, a mix, a region, the selection object, #f, a procedure, or a player.
Not all the keyword arguments apply in all cases, though I hope to fill in the table of possibilities eventually.
The full documentation is currently under <a href="#play">play</a>.
</p>
<div class="spacer"></div>


<!-- srate -->
<!-- INDEX genericsrate:srate (generic) -->
<pre class="indented">
<em class=def>srate</em> obj
</pre>

<p id="genericsrate">srate handles strings (treated as file names: <a href="#mussoundsrate">mus-sound-srate</a>), 
regions (<a href="#regionsrate">region-srate</a>), the selection (<a href="#selectionsrate">selection-srate</a>),
and <a href="#sndsounds">sounds</a> (as objects or as integers).
</p>
<div class="spacer"></div>


<!-- sync -->
<!-- INDEX genericsync:sync (generic) -->
<pre class="indented">
<em class=def>sync</em> obj
</pre>

<p id="genericsync">sync accesses the '<a href="#sync">sync</a>' field of a sound, mark, or mix.
</p>




<!--  HOOKS  -->
<!-- INDEX sndhooks:Hooks -->

<div class="header" id="sndhooks">Hooks</div>

<p>When some user-interface action takes place, code is called that responds to that action;
these functions are sometimes called callbacks; the variable that holds a list of such
callbacks is known as a hook.  
For example, the hook that is checked when you click the sound's name in the status area is
name-click-hook.  We can cause that action to print "hi":</p>

<pre class="indented">
Scheme: (hook-push <a class=quiet href="#nameclickhook">name-click-hook</a> (lambda (hook) (<a class=quiet href="#sndprint">snd-print</a> "hi") (set! (hook 'result) #t)))
Ruby:   $name_click_hook.add_hook!("print") do |snd| snd_print("hi"); true end
Forth:  name-click-hook lambda: &lt;{ snd }&gt; "hi" snd-print drop #t ; add-hook!
</pre>

<p>The Scheme hook function is slightly different from the Forth and Ruby cases.  For about 15 years, Snd used Guile-style
hooks which are essentially a list of functions, each called with the hook arguments ('snd' above).  But now Scheme hooks
are functions that have three internal lists of functions.  The internal functions (the things we add to hook-functions, for example)
take the hook's internal environment as their only argument ('hook' above), and then access the actual hook arguments
via <code>(hook name)</code>.  So, the examples are confusing because the situation is confused!  To move between the
versions, match the Forth/Ruby argument name to the Scheme hook variable, so the function argument 'snd in Forth/Ruby
is <code>(hook 'snd)</code> in Scheme.
</p>

<p>In Ruby and Forth, but not in Scheme,
if there is more than one function attached to a hook, some of the hooks
"or" the functions together; that is they
run through the list of functions, and if any function returns something other than #f, the
hook invocation eventually returns the last such non-#f value.  A few hooks are "cascade"
hooks; that is, each function gets the result of the previous function, and
the final function's value is returned.
In other
cases the result returned by the hook is the result of the last function in the list.
Whatever the hook combination choice, all the functions on the hook list are run
on each invocation.  
</p>

<p>In Scheme, all functions are run, each takes one argument, the hook environment, and any return values are ignored.  It is
up to the individual functions to track <code>(hook 'result)</code> if intermediate results matter.
</p>

<p>There are several basic actions that involve a bunch of hooks.  Here is a schematic view of
some of these sequences.
</p>

<pre>
    Open filename
        bad header?: <a class=quiet href="#badheaderhook">bad-header-hook</a> &mdash; can cancel request
        no header?:  <a class=quiet href="#openrawsoundhook">open-raw-sound-hook</a> &mdash; can cancel request
        file ok: 
             <a class=quiet href="#openhook">open-hook</a> &mdash; can change filename
             file opened (no data read yet)
                 <a class=quiet href="#duringopenhook">during-open-hook</a> (can set prescaling etc)
             data read, no graphics yet
             <a class=quiet href="#afteropenhook">after-open-hook</a>
             <a class=quiet href="#initialgraphhook">initial-graph-hook</a>
    
    
    Save current sound
        <a class=quiet href="#beforesaveashook">before-save-as-hook</a> &mdash; can cancel the request or set its output parameters
        <a class=quiet href="#savehook">save-hook</a>
            sound saved
              if any sample is clipped during save, <a class=quiet href="#cliphook">clip-hook</a>
        <a class=quiet href="#aftersaveashook">after-save-as-hook</a>


    Play sound
        when a play request occurs: <a class=quiet href="#startplayinghook">start-playing-hook</a> &mdash; can cancel the request, also <a class=quiet href="#startplayingselectionhook">start-playing-selection-hook</a>
            (any number of sounds can be playing at once)
        as each sound ends: <a class=quiet href="#stopplayinghook">stop-playing-hook</a>, <a class=quiet href="#stopplayingselectionhook">stop-playing-selection-hook</a>
    

    Close sound
        <a class=quiet href="#beforeclosehook">before-close-hook</a> &mdash; can cancel close
        <a class=quiet href="#closehook">close-hook</a> (sound is still open)
        sound closed
    
    
    Save current Snd ("session") state
        <a class=quiet href="#savestatehook">save-state-hook</a> &mdash; can change output filename (crummy name is an historical artifact)
        output save-state file opened
            <a class=quiet href="#beforesavestatehook">before-save-state-hook</a>
            Snd saves its state
            <a class=quiet href="#aftersavestatehook">after-save-state-hook</a>
        output closed
    
    
    Exit Snd
        <a class=quiet href="#beforeexithook">before-exit-hook</a> &mdash; can cancel exit request
        <a class=quiet href="#exithook">exit-hook</a>
        Snd cleans up and exits
</pre>


<p>Here's the Ruby version of some of the hook-related functions:
</p>

<pre class="indented">
$var_hook.remove_hook!("proc_name")
$var_hook.reset_hook!
$var_hook.run_hook do |prc| prc.call(1, 2, 3) end
$var_hook.call(1, 2, 3)   # calls all procedures
    
require 'hooks'
$var_hook.show            # prints the code of the procedure(s)
$va_hook.to_a
</pre>

<p>And some Forth examples, taken from Mike Scholz's documentation:
</p>

<pre class="indented">
open-hook ' open-buffer 1 make-proc add-hook!
open-hook "open-buffer" remove-hook!
open-hook reset-hook!
open-hook hook-&gt;list
    
2 "A simple hook." create-hook my-new-hook
my-new-hook ' + 2 make-proc add-hook!
my-new-hook '( 2 3 ) run-hook
help my-new-hook             
</pre>

<p>These hooks are extremely easy to add; if there's some user-interface action
you'd like to specialize in some way, send me a note. 
hooks.scm has snd-hooks and reset-all-hooks, as well as other
useful hook-related functions.  
</p>

<p>
In the following list of hooks, the arguments after the hook name refer to the arguments to the functions invoked by
the hook (in Ruby and Forth).  That is, after-apply-controls-hook (snd) means that the functions on the
<a class=quiet href="#afterapplycontrolshook">after-apply-controls-hook</a> list each take one argument, a sound.  In Scheme, they refer to the hook variables accessible in the hook environment via <code>(hook 'snd)</code>, for example.
</p>

<div class="spacer"></div>


<!-- after-apply-controls-hook -->
<pre class="indented">
<em class=def id="afterapplycontrolshook">after-apply-controls-hook</em> (snd)
</pre>

<p>This hook is called when <a href="#applycontrols">apply-controls</a> finishes.  
<a href="sndscm.html#addampcontrols">add-amp-controls</a> in snd-motif.scm uses this hook to
reset any added amplitude sliders to 1.0.
</p>
<div class="spacer"></div>


<!-- after-graph-hook -->
<pre class="indented">
<em class=def id="aftergraphhook">after-graph-hook</em> (snd chn)
</pre>

<p>This hook is called after a graph is updated or redisplayed.
Use it to add your own finishing touches to the display; if added earlier they risk
being erased by Snd as it redraws graphs.
</p>
<div class="spacer"></div>


<!-- after-lisp-graph-hook -->
<pre class="indented">
<em class=def id="afterlispgraphhook">after-lisp-graph-hook</em> (snd chn)
</pre>

<p>This hook is called after a "lisp" graph is updated or redisplayed.  The <a href="#lispgraphhook">lisp-graph-hook</a> functions
are called before the actual graph is displayed, so if you want to add to a graph in some way, you need to
use after-lisp-graph-hook.
<a href="sndscm.html#displaybarkfft">display-bark-fft</a> in dsp.scm uses it to draw the x axis labels and
ticks for various frequency scales.
</p>
<div class="spacer"></div>


<!-- after-open-hook -->
<pre class="indented">
<em class=def id="afteropenhook">after-open-hook</em> (snd)
</pre>

<p>This hook is called just before a newly opened sound's window is displayed.
It provides a way to set various sound-specific defaults.  
For example, the following causes Snd to default to locally 
sync'd channels (that is, each sound's channels are sync'd 
together but are independent of any other sound), united channels (all chans in one graph), 
and filled graphs (not line segments or dots, etc):
</p>

<pre class="indented">
(hook-push <em class=red>after-open-hook</em>
  (lambda (hook)
    (let ((snd (hook 'snd)))
      (if (&gt; (<a class=quiet href="#channels">channels</a> snd) 1)
          (begin
            (set! (<a class=quiet href="#sync">sync</a> snd) (+ 1 (sync-max)))
            (set! (<a class=quiet href="#channelstyle">channel-style</a> snd) <a class=quiet href="#channelstyle">channels-combined</a>)
            (set! (<a class=quiet href="#graphstyle">graph-style</a> snd) <a class=quiet href="#graphstyle">graph-filled</a>))))))
</pre>

<p>See also
enved.scm, and various examples in snd-motif.scm.
</p>
<div class="spacer"></div>



<!-- after-save-as-hook -->
<pre class="indented">
<em class=def id="aftersaveashook">after-save-as-hook</em> (snd name dialog)
</pre>

<p>This hook is called after File:Save as.  ('snd = sound index, 'name = full filename, 'dialog = #t if called from a dialog).
</p>
<div class="spacer"></div>



<!-- after-save-state-hook -->
<pre class="indented">
<em class=def id="aftersavestatehook">after-save-state-hook</em> (name)
</pre>

<p>This hook is called after Snd has saved its state (<a href="#savestate">save-state</a>).  'name is the (otherwise complete) saved state
program (a filename).  See <a href="sndscm.html#wssavestate">ws-save-state</a> in ws.scm.  It uses this sequence:
</p>

<pre class="indented">
(let ((fd (open-output-file filename "a"))) ; "a" = append
  (format fd "~%~%;;; from ws.scm~%")
  ...
  (close-output-port fd))
</pre>
<div class="spacer"></div>


<!-- after-transform-hook -->
<pre class="indented">
<em class=def id="aftertransformhook">after-transform-hook</em> (snd chn scaler)
</pre>

<p id="fftpeak">This hook is called just after an FFT (or spectrum) is calculated.
</p>

<pre class="indented">
(define (report-fft-peak snd chn)
  (if (and (<a class=quiet href="#transformgraphp">transform-graph?</a>) 
           (= (<a class=quiet href="#transformgraphtype">transform-graph-type</a>) <a class=quiet href="#transformgraphtype">graph-once</a>))
      (<a class=quiet href="#statusreport">status-report</a> 
        (number-&gt;string (/ (* 2 (maxamp (transform-&gt;float-vector snd chn)))
                           (<a class=quiet href="#transformsize">transform-size</a> snd chn))))))

(hook-push <em class=red>after-transform-hook</em> 
  (lambda (hook) 
    (report-fft-peak (hook 'snd) (hook 'chn))))
</pre>
<div class="spacer"></div>


<!-- bad-header-hook -->
<pre class="indented">
<em class=def id="badheaderhook">bad-header-hook</em> (name)
</pre>

<p>This hook is called if a file has a bogus-looking header (that is, 
a header with what appear to be bad values such as a negative number of channels). 
If the hook returns #t, Snd does not try to open the file.
</p>

<pre class="indented">
(hook-push bad-header-hook 
  (lambda (hook) 
    (set! (hook 'result) #t))) ; don't open bogus-looking files
</pre>

<p>If no header is found, <a href="#openrawsoundhook">open-raw-sound-hook</a> is invoked instead ("raw" = "headerless").
</p>
<div class="spacer"></div>


<!-- before-close-hook -->
<pre class="indented">
<em class=def id="beforeclosehook">before-close-hook</em> (snd) 
</pre>

<p>This hook is called when a file is about to be closed.  If the hook returns #t, the file is not closed.
</p>
<div class="spacer"></div>


<!-- before-exit-hook -->
<pre class="indented">
<em class=def id="beforeexithook">before-exit-hook</em> ()
</pre>

<p>This hook is called upon a request to exit Snd.
If the hook returns #t, Snd does not exit. 
</p>
<div class="spacer"></div>


<!-- before-save-as-hook -->
<pre class="indented">
<em class=def id="beforesaveashook">before-save-as-hook</em> (snd name selection sampling-rate sample-type header-type comment)
</pre>

<p>This hook is called before <a href="#savesoundas">save-sound-as</a> or File:Save as.  
If the hook returns #t, the
save is not performed.  This hook provides a way to do last minute fixups (srate conversion for example)
just before a sound is saved.  The arguments to the hook function describe the requested attributes of the saved sound;
'snd' is the to-be-saved sound's index; 'name' is the output file's name; 'selection' is #t if
we're saving the selection.
</p>

<pre class="indented">
(hook-push <em class=red>before-save-as-hook</em>
  (lambda (hook)
    (let ((index (hook 'snd))
          (filename (hook 'name))
          (sr (hook 'sampling-rate))
          (dformat (hook 'sample-type))
          (htype (hook 'header-type))
          (comment (hook 'comment)))
      (if (not (= sr (srate index)))
          (let ((chns (channels index)))
            (do ((i 0 (+ i 1)))
                ((= i chns))
              (src-channel (* 1.0 (/ (srate index) sr)) 0 #f index i))
            (save-sound-as filename index :header-type htype :sample-type dformat :srate sr :comment comment)
            (do ((i 0 (+ i 1)))
                ((= i chns))
              (undo 1 index i))
            (set! (hook 'result) #t)))))) ; tell Snd that the sound is already saved
</pre>
<div class="spacer"></div>


<!-- before-save-state-hook -->
<pre class="indented">
<em class=def id="beforesavestatehook">before-save-state-hook</em> (name)
</pre>

<p>This hook is called before Snd saves its state (<a href="#savestate">save-state</a>).  'name' is the saved state
file.  If the hook returns #t, the save state file is opened in append mode (rather than create/truncate),
so you can write preliminary stuff via this hook, then instruct Snd not to clobber it during the save process.
</p>

<pre class="indented">
(hook-push <em class=red>before-save-state-hook</em>
  (lambda (hook) 
    (call-with-output-file (hook 'name)
      (lambda (p)
        (<a class=quiet>format</a> p ";this comment will be at the top of the saved state file.~%~%")))
    (set! (hook 'result) #t)))
</pre>
<div class="spacer"></div>


<!-- before-transform-hook -->
<pre class="indented">
<em class=def id="beforetransformhook">before-transform-hook</em> (snd chn)
</pre>

<p>This hook is called just before an FFT (or spectrum) is calculated.  If the hook returns 
an integer, that value is used as the starting point (sample number) of the fft.  Normally,
the fft starts from the left window edge.  To have it start at mid-window:
</p>

<pre class="indented">
(hook-push <em class=red>before-transform-hook</em>
  (lambda (hook)        ; 0.5 * (left + right) = midpoint
    (set! (hook 'result) 
          (round (* 0.5 (+ (<a class=quiet href="#rightsample">right-sample</a> (hook 'snd) (hook 'chn)) 
                           (<a class=quiet href="#leftsample">left-sample</a> (hook 'snd) (hook 'chn))))))))
</pre>

<p>The following 
somewhat brute-force code shows a way to have the fft reflect the position 
of a moving mark:
</p>

<pre class="indented">
(let ((fft-position #f))
  (hook-push <em class=red>before-transform-hook</em> 
    (lambda (hook) 
      (set! (hook 'result) fft-position)))
  (hook-push <a class=quiet href="#markdraghook">mark-drag-hook</a> 
    (lambda (hook)
      (set! fft-position (<a class=quiet href="#marksample">mark-sample</a> (hook 'id)))
      (<a class=quiet href="#updatetransformgraph">update-transform-graph</a>))))
</pre>
<div class="spacer"></div>



<!-- clip-hook -->
<pre class="indented">
<em class=def id="cliphook">clip-hook</em> (val) 
</pre>

<p>This hook is called whenever a sample is about to be clipped while writing out a sound file. 
The hook can return the new value.
</p>
<div class="spacer"></div>



<!-- close-hook -->
<pre class="indented">
<em class=def id="closehook">close-hook</em> (snd)
</pre>

<p>This hook is called when a file is closed (before the actual close, so the index 'snd' is still valid).
</p>

<pre class="indented">
(hook-push <em class=red>close-hook</em>
  (lambda (hook) 
    (play "wood16.wav")))
</pre>
<div class="spacer"></div>


<!-- color-hook -->
<pre class="indented">
<em class=def id="colorhook">color-hook</em> () 
</pre>

<p>This hook is called whenever one of the variables associated with the color dialog changes.  
</p>
<div class="spacer"></div>



<!-- draw-mark-hook -->
<pre class="indented">
<em class=def id="drawmarkhook">draw-mark-hook</em> (id)
</pre>

<p>This hook is called before a mark is drawn. If the hook returns #t, the mark is not drawn.  
<a href="sndscm.html#marksynccolor">mark-sync-color</a>
in snd-motif.scm uses this hook to draw sync'd marks in some other color than the current <a href="#markcolor">mark-color</a>.
</p>
<div class="spacer"></div>


<!-- draw-mix-hook -->
<pre class="indented">
<em class=def id="drawmixhook">draw-mix-hook</em> (id old-x old-y x y)
</pre>

<p>This hook is called before a mix tag is drawn. If the hook returns either #t or a list, the mix tag is not drawn by Snd (the
assumption is that the hook function drew something).  old-x and old-y are the previous mix tag positions (in case
you're using draw-mix-hook to draw your own mix tag as in musglyphs.scm).  x and y give the current position.
If the hook returns a list, its two elements (integers) are treated as the mix's tag x and y locations
for subsequent mouse click hit detection.
</p>
<div class="spacer"></div>


<!-- drop-hook -->
<pre class="indented">
<em class=def id="drophook">drop-hook</em> (name) 
</pre>

<p>This hook is called each time Snd receives a drag-and-drop event, passing the hook functions the dropped filename.
If the hook returns #t, the file is not opened by Snd.  Normally if you drag a file icon to the menubar, 
Snd opens it as if you had called <a href="#opensound">open-sound</a>.  If you drag the icon to a particular channel,
Snd mixes it at the mouse location in that channel.  To get Snd to
mix the dragged file even from the menubar:
</p>

<pre class="indented">
(hook-push <em class=red>drop-hook</em>
  (lambda (hook) 
    (<a class=quiet href="#mix">mix</a> (hook 'name))
    (set! (hook 'result) #t))) ; return #t = we already dealt with the drop
</pre>
<div class="spacer"></div>


<!-- during-open-hook -->
<pre class="indented">
<em class=def id="duringopenhook">during-open-hook</em> (fd name reason)
</pre>

<p>This hook is called after a file is opened, but before its data has been read.
'reason' is an integer indicating why this file is being opened:
</p>
<pre class="indented">
0: reopen a temporarily closed file (internal to Snd &mdash; normally invisible)
1: sound-open, File:open etc &mdash; the normal path to open a sound
2: copy reader &mdash; another internal case; this happens if a sound is played and edited at the same time
3: insert sound (File:Insert etc)
4: re-read after an edit (file changed, etc &mdash; an invisible editing case)
5: open temp file after an edit (another invisible editing case)
6: mix sound (File:Mix etc)
</pre>

<p>So, to restrict the hook action to the normal case where Snd is opening a file for the first time,
check that 'reason' is 1, or perhaps 1, 3, or 6 (these read the external form of the data).
</p>
<div class="spacer"></div>



<!-- effects-hook -->
<pre class="indented">
<em class=def id="effectshook">effects-hook</em> ()
</pre>

<p>effects-hook is a convenience hook for the effects dialogs.
</p>
<div class="spacer"></div>



<!-- enved-hook -->
<pre class="indented">
<em class=def id="envedhook">enved-hook</em> (envelope point x y reason)
</pre>

<p>Each time a breakpoint is changed in the envelope editor, this hook 
is called; if it returns a list, that list defines the new envelope, 
otherwise the breakpoint is moved (but not beyond the neighboring 
breakpoint), leaving other points untouched.  The kind of change that triggered the hook callback
is indicated by the argument 'reason'. It can be enved-move-point, enved-delete-point,
or enved-add-point.  This hook makes it possible to define attack 
and decay portions in the envelope editor, or use functions such as 
<a href="sndscm.html#stretchenvelope">stretch-envelope</a> from env.scm:
</p>

<pre class="indented">
(hook-push <em class=red>enved-hook</em>
  (lambda (hook)
    (let ((env (hook 'envelope))
          (pt (* 2 (hook 'point)))
          (x (hook 'x))
          (y (hook 'y))
          (reason (hook 'reason)))
      (if (and (= reason enved-move-point)
               (&gt; x 0.0)
               (&lt; x (envelope-last-x env)))
          (let ((new-env (stretch-envelope env (env pt) x)))
            (set! (new-env (+ pt 1)) y)
            (set! (hook 'result) new-env))))))
</pre>

<p>In Forth/Ruby, if there are several functions on the hook, each gets the envelope
result of the preceding function.
</p>
<div class="spacer"></div>


<!-- exit-hook -->
<pre class="indented">
<em class=def id="exithook">exit-hook</em> ()
</pre>

<p>This hook is called upon exit.
</p>
<div class="spacer"></div>



<!-- graph-hook -->
<pre class="indented">
<em class=def id="graphhook">graph-hook</em> (snd chn y0 y1) 
</pre>

<p>This hook is called each time a graph is updated or redisplayed.
If it returns #t, the display is not updated.
See examp.scm for many examples.  If you want to add your own graphics to the display, use <a href="#aftergraphhook">after-graph-hook</a>.
</p>

<pre class="indented">
(hook-push <em class=red>graph-hook</em>
  (let ((+documentation+ "set the dot size depending on the number of samples being displayed"))
    (lambda (hook)
      (let* ((snd (hook 'snd))
             (chn (hook 'chn))
             (dots (- (<a class=quiet href="#rightsample">right-sample</a> snd chn) (<a class=quiet href="#leftsample">left-sample</a> snd chn))))
        (set! (dot-size snd chn)
              (cond ((assoc dots '((100 . 1) (50 . 3) (25 . 5)) >) => cdr) 
                    (else 8)))))))	
</pre>
<div class="spacer"></div>



<!-- help-hook -->
<pre class="indented">
<em class=def id="helphook">help-hook</em> (subject help-string)
</pre>

<p>This hook is called from <a href="#sndhelp">snd-help</a> with the current help subject and default help-string.  
Say we want the index.scm
procedure <a href="sndscm.html#html">html</a> called any time snd-help is called (from C-? for example):
</p>

<pre class="indented">
(hook-push <em class=red>help-hook</em> (lambda (hook) (<a class=quiet href="sndscm.html#html">html</a> (hook 'subject))))
</pre>
<div class="spacer"></div>


<!-- initial-graph-hook -->
<pre class="indented">
<em class=def id="initialgraphhook">initial-graph-hook</em> (snd chn duration) 
</pre>

<p>This hook is called the first time a given channel is displayed (when the sound is first opened).
If the hook returns a list, the list's contents are interpreted as:
</p>

<pre class="indented">
(list x0 x1 y0 y1 label ymin ymax)
</pre>

<p>(all trailing values are optional), where these numbers set the
initial x and y axis limits and the x axis label.
The default (an empty hook) is equivalent to:
</p>

<pre class="indented">
(hook-push <em class=red>initial-graph-hook</em> 
  (lambda (hook) 
    (set! (hook 'result) (list 0.0 0.1 -1.0 1.0 "time" -1.0 1.0))))
</pre>

<p>The 'duration' argument is the total length in seconds of the displayed portion of the channel, so to cause the
entire sound to be displayed initially:
</p>

<pre class="indented">
(hook-push <em class=red>initial-graph-hook</em> 
  (lambda (hook) 
    (set! (hook 'result) (list 0.0 (hook 'duration)))))
</pre>

<p>To get other the data limits (rather than the default y axis limits of -1.0 to 1.0), you can use <a href="#mussoundmaxamp">mus-sound-maxamp</a>,
but if that sound's maxamp isn't already known, it can require a long process of reading the file. The following hook procedure
uses the maxamp data if it is already available or if the file is short:
</p>

<pre class="indented">
(hook-push <em class=red>initial-graph-hook</em>
  (lambda (hook)
    (let ((snd (hook 'snd))
          (chn (hook 'chn))
          (dur (hook 'duration)))
      (if (or (<a class=quiet href="#mussoundmaxampexists">mus-sound-maxamp-exists?</a> (<a class=quiet href="#filename">file-name</a> snd))
              (&lt; (<a class=quiet href="#framples">framples</a> snd chn) 10000000))
	  (let* ((amp-vals (<a class=quiet href="#mussoundmaxamp">mus-sound-maxamp</a> (<a class=quiet href="#filename">file-name</a> snd)))
	         (max-val (max 1.0 (amp-vals (+ (* chn 2) 1)))))
                 ;; max amp data is list: (sample value sample value ...)
	    (set! (hook 'result) (list 0.0 dur (- max-val) max-val))) ; these are the new y-axis limits
	(set! (hook 'result) (list 0.0 dur -1.0 1.0))))))             ; max amp unknown, so use defaults
</pre>
<div class="spacer"></div>



<!-- key-press-hook -->
<pre class="indented">
<em class=def id="keypresshook">key-press-hook</em> (snd chn key state)
</pre>

<p>This hook is called upon key press while the mouse is in the lisp graph (the third graph, 
to the right of the time and fft graphs).
If it returns #t, the key press is not passed to the main handler.
'state' refers to the control, meta, and shift keys.
<a href="sndscm.html#enveddoc">start-enveloping</a> in enved.scm uses this hook to add C-g and C-. support to the
channel-specific envelope editors.
</p>
<div class="spacer"></div>



<!-- lisp-graph-hook -->
<pre class="indented">
<em class=def id="lispgraphhook">lisp-graph-hook</em> (snd chn)
</pre>

<p>This hook is called just before the lisp graph is updated or redisplayed (see <a href="#displaydb">display-db</a>).
If it returns a list of pixels (xm style), they are used in order by the list of graphs, rather than Snd's default colors.
If it returns a thunk, that function is called rather than the standard graph routine:
</p>

<pre class="indented">
(hook-push <em class=red>lisp-graph-hook</em>
  (lambda (hook)
    (let ((snd (hook 'snd))
          (chn (hook 'chn)))
      (set! (hook 'result)
        (lambda ()
          (<a class=quiet href="#drawstring">draw-string</a> "hi" 
                       (<a class=quiet href="#xtoposition">x-&gt;position</a> 0.5 snd chn <a class=quiet href="#ytoposition">lisp-graph</a>) 
	               (<a class=quiet href="#ytoposition">y-&gt;position</a> 0.0 snd chn <a class=quiet href="#ytoposition">lisp-graph</a>)
	               snd chn))))))
</pre>

<p>For a fancy example, see <a href="sndscm.html#displaybarkfft">display-bark-fft</a> in dsp.scm.
</p>
<div class="spacer"></div>




<!-- listener-click-hook -->
<pre class="indented">
<em class=def id="listenerclickhook">listener-click-hook</em> (position)
</pre>

<p>This hook is called when a click occurs in the listener; the 'position' argument is the position in the text 
(a character number) where the click occurred.
</p>
<div class="spacer"></div>



<!-- mark-click-hook -->
<pre class="indented">
<em class=def id="markclickhook">mark-click-hook</em> (id)
</pre>

<p>This hook is called when a mark is clicked; return #t to squelch the default status area mark identification.
</p>

<pre class="indented">
(hook-push <em class=red>mark-click-hook</em>
  (lambda (hook)
    (let ((n (hook 'id)))
      (if (not (defined? 'mark-properties)) (load "marks.scm"))
      (<a class=quiet href="#infodialog">info-dialog</a> "Mark Help"
        (<a class=quiet>format</a> #f "Mark ~A~A:~%  sample: ~D = ~,3F secs~A~A"
	        n 
	        (let ((name (<a class=quiet href="#markname">mark-name</a> n)))
   	          (if (&gt; (string-length name) 0)
		      (<a class=quiet>format</a> #f " (~S)" name)
		      ""))
	        (<a class=quiet href="#marksample">mark-sample</a> n)
	        (* 1.0 (/ (<a class=quiet href="#marksample">mark-sample</a> n) (<a class=quiet href="#srate">srate</a> (car (<a class=quiet href="#markhome">mark-home</a> n)))))
	        (if (zero? (<a class=quiet href="#marksync">mark-sync</a> n))
                    ""
	            (<a class=quiet>format</a> #f "~%  sync: ~A" (<a class=quiet href="#marksync">mark-sync</a> n)))
	        (let ((props (<a class=quiet href="#markproperties">mark-properties</a> n)))
	          (if (pair? props)
	            (<a class=quiet>format</a> #f "~%  properties: '~A" props)
	            ""))))
      (set! (hook 'result) #t))))
</pre>
<div class="spacer"></div>


<!-- mark-drag-hook -->
<pre class="indented">
<em class=def id="markdraghook">mark-drag-hook</em> (id)
</pre>

<p>This hook is called when a mark is dragged.  If it returns #t, the mark position is not reflected in the status area.
</p>

<pre class="indented">
(define (report-mark-location id)
  ;; print current mark location in status area
  (let ((samp (<a class=quiet href="#marksample">mark-sample</a> id))
        (sndchn (<a class=quiet href="#markhome">mark-home</a> id)))
    (<a class=quiet href="#statusreport">status-report</a> 
      (<a class=quiet>format</a> #f "mark ~A: sample: ~D (~,3F) ~A[~D]: ~,3F"
              id samp 
              (exact-&gt;inexact (/ samp (<a class=quiet href="#srate">srate</a> (car sndchn))))
              (<a class=quiet href="#shortfilename">short-file-name</a> (car sndchn))
              (cadr sndchn)
	      (<a class=quiet href="#sample">sample</a> samp (car sndchn) (cadr sndchn))))))

(hook-push <em class=red>mark-drag-hook</em> 
  (lambda (hook) 
    (report-mark-location (hook 'id))
    (set! (hook 'result) #t)))
</pre>
<div class="spacer"></div>



<!-- mark-hook -->
<pre class="indented">
<em class=def id="markhook">mark-hook</em> (mark snd chn reason)
</pre>

<p id="snpmark">This hook is called when a mark is added, deleted, or moved (but not while moving). 
'reason' can be 0: add, 1: delete, 2: move (via set! mark-sample), 3: delete all marks, 4: release (after drag). 
In the "release" case, the hook is called upon button release before any edits (control-drag of mark) or sorting (simple drag),
and if the <a href="#marksync">mark-sync</a> is not 0, the hook is called on each syncd mark.
</p>

<pre class="indented">
(define (snap-mark-to-beat)
  ;; when a mark is dragged, its end position is always on a beat
  (hook-push <em class=red>mark-hook</em>
    (lambda (hook)
      (let ((mrk (hook 'id))
            (snd (hook 'snd))
            (chn (hook 'chn))
            (reason (hook 'reason)))
        (let ((mark-release 4))
          (if (= reason mark-release)
              (let* ((samp (mark-sample mrk))
                     (bps (/ (beats-per-minute snd chn) 60.0))
                     (sr (srate snd))
                     (beat (floor (/ (* samp bps) sr)))
                     (lower (floor (/ (* beat sr) bps)))
                     (higher (floor (/ (* (+ 1 beat) sr) bps))))
                (set! (mark-sample mrk) (if (&lt; (- samp lower) (- higher samp))
                                            lower
                                            higher)))))))))
</pre>
<div class="spacer"></div>


<!-- mix-click-hook -->
<pre class="indented">
<em class=def id="mixclickhook">mix-click-hook</em> (id)
</pre>

<p>This hook is called when a mix tag is clicked (when the double-arrow is displayed over the tag); 
return #t to omit the default action which is to start the Mix dialog 
with the clicked mix.
One example is <a href="sndscm.html#mixclickinfo">mix-click-info</a> in mix.scm.
Here's an example that sets a mix's amps to 0 if you click it (see <a href="sndscm.html#mixclicksetsamp">mix-click-sets-amp</a>
in mix.scm for a fancier version):
</p>

<pre class="indented">
(hook-push <em class=red>mix-click-hook</em>
  (lambda (hook)
    (set! (<a class=quiet href="#mixamp">mix-amp</a> (hook 'id)) 0.0)
    (set! (hook 'result) #t)))
</pre>
<div class="spacer"></div>


<!-- mix-drag-hook -->
<pre class="indented">
<em class=def id="mixdraghook">mix-drag-hook</em> (id x y)
</pre>

<p>This hook is called when a mix is dragged.
</p>

<pre class="indented">
(hook-push <em class=red>mix-drag-hook</em>
  (lambda (hook)
    (<a class=quiet href="#statusreport">status-report</a> 
      (<a class=quiet>format</a> #f "mix ~A at ~D: ~,3F" 
        (hook 'id) 
        (<a class=quiet href="#mixposition">mix-position</a> (hook 'id)) 
        (exact-&gt;inexact (/ (<a class=quiet href="#mixposition">mix-position</a> (hook 'id)) (<a class=quiet href="#srate">srate</a>)))))))
</pre>

<p>A neat example is to set up an empty sound with a 1.0 in sample 0, mix in a float-vector containing one element of 0.5, then set
up this mix-drag-hook:
</p>

<pre class="indented">
(hook-push mix-drag-hook 
  (lambda (hook) 
    (<a class=quiet href="#updatetransformgraph">update-transform-graph</a>)))
</pre>

<p>and turn on the FFT graph.  As you drag the mix, you can see the spectral effect of that
moving value as a comb filter.
</p>
<div class="spacer"></div>



<!-- mix-release-hook -->
<pre class="indented">
<em class=def id="mixreleasehook">mix-release-hook</em> (id samples)
</pre>

<p>This hook is called after a mix has been dragged by the mouse to a new position.
'samples' is the number of samples moved during the drag.  If the hook returns #t, the final position
of the mix is
hook's responsibility.  See <a href="sndscm.html#snapmarktobeat">snap-mix-to-beat</a> in mix.scm.
</p>
<div class="spacer"></div>



<!-- mouse-click-hook -->
<pre class="indented">
<em class=def id="mouseclickhook">mouse-click-hook</em> (snd chn button state x y axis) 
</pre>

<p>This hook is called upon a mouse button release or click (with various exceptions).  If its function returns #t, the click is ignored by Snd.
</p>

<pre class="indented">
(define (click-to-center snd chn x axis)
  ;; if mouse click in time domain graph, set cursor as normally, but also center the window
  (and (= axis <a class=quiet>time-graph</a>)
       (let ((samp (floor (* (<a class=quiet href="#srate">srate</a> snd) (<a class=quiet href="#positiontox">position-&gt;x</a> x snd chn)))))
	 (set! (<a class=quiet href="#cursor">cursor</a> snd chn) samp)
	 (set! (<a class=quiet href="#rightsample">right-sample</a> snd chn) 
           (- samp (floor (* .5 (- (<a class=quiet href="#leftsample">left-sample</a> snd chn) (<a class=quiet href="#rightsample">right-sample</a> snd chn))))))
	 (<a class=quiet href="#updatetimegraph">update-time-graph</a>)
	 #t)))

(hook-push <em class=red>mouse-click-hook</em> 
  (lambda (hook) 
    (set! (hook 'result) (click-to-center (hook 'snd) (hook 'chn) (hook 'x) (hook 'axis)))))

;;; this example disables button 2 -&gt; insert selection
(hook-push <em class=red>mouse-click-hook</em>
  (lambda (hook)
    (set! (hook 'result) 
       (and (= (hook 'axis) <a class=quiet>time-graph</a>) 
            (= (hook 'button) 2)))))
</pre>

<p>The mouse scroll wheel is sometimes reported as buttons 4 and 5; in the next example,
turning the wheel zooms the graph in or out:
</p>

<pre class="indented">
(hook-push <em class=red>mouse-click-hook</em>
  (lambda (hook)
    (let ((button (hook 'button))
          (axis (hook 'axis)))
      (if (and (= axis <a class=quiet>time-graph</a>)
	       (memv button '(4 5))) ; mouse scroll wheel
  	  (let ((midpoint (* 0.5 (apply + (<a class=quiet href="#xbounds">x-bounds</a>))))
	        (dur (/ (<a class=quiet href="#framples">framples</a>) (<a class=quiet href="#srate">srate</a>)))
	        (range (if (= button 4)
			   (* -0.25 (apply - (<a class=quiet href="#xbounds">x-bounds</a>))) ; zoom in
			   (abs (apply - (<a class=quiet href="#xbounds">x-bounds</a>))))))  ; zoom out
	    (set! (<a class=quiet href="#xbounds">x-bounds</a>) (list (max 0.0 (- midpoint range))
				   (min dur (+ midpoint range)))))))))

</pre>

<p>Here is a Forth example:
</p>

<pre class="indented">
mouse-click-hook lambda: &lt;{ snd chn button state x y axis -- }&gt; 
 axis time-graph = if 
   $" freq: %.3f" '( snd chn #f cursor  snd chn spot-freq ) string-format 
   snd #f status-report 
 else 
   #f 
 then 
; add-hook! 
</pre>
<div class="spacer"></div>


<!-- mouse-drag-hook -->
<pre class="indented">
<em class=def id="mousedraghook">mouse-drag-hook</em> (snd chn button state x y)
</pre>

<p>This hook is called when the mouse is dragged within the lisp graph (see enved.scm).
</p>
<div class="spacer"></div>


<!-- mouse-enter-graph-hook -->
<pre class="indented">
<em class=def id="mouseentergraphhook">mouse-enter-graph-hook</em> (snd chn)
</pre>

<p>This hook is called when the mouse enters a channel's drawing area (graph pane).
</p>

<pre class="indented">
(hook-push <em class=red>mouse-enter-graph-hook</em>
  (lambda (hook)
    (<a class=quiet href="#sndprint">snd-print</a> (<a class=quiet>format</a> #f "~A[~A]" (<a class=quiet href="#shortfilename">short-file-name</a> (hook 'snd)) (hook 'chn)))))
</pre>
<div class="spacer"></div>


<!-- mouse-enter-label-hook -->
<pre class="indented">
<em class=def id="mouseenterlabelhook">mouse-enter-label-hook</em> (type position label)
</pre>

<p>This hook is called when the mouse enters a file viewer or region label.
The 'type' is 1 for view files list, and 2 for regions. 
The 'position' is the scrolled list position of the label. 
The label itself is 'label'. We can use the <a href="sndscm.html#finfo">finfo</a> procedure in examp.scm
to popup file info as follows:
</p>

<pre class="indented">
(hook-push <em class=red>mouse-enter-label-hook</em>
  (lambda (hook)
    (if (not (= (hook 'type) 2))
        (<a class=quiet href="#infodialog">info-dialog</a> (hook 'label) (finfo (hook 'label))))))
</pre>

<p>See also <a href="sndscm.html#nbdoc">files-popup-info</a> in nb.scm.
</p>
<div class="spacer"></div>


<!-- mouse-enter-listener-hook -->
<pre class="indented">
<em class=def id="mouseenterlistenerhook">mouse-enter-listener-hook</em> (widget)
</pre>

<p>This hook is called when the mouse enters the listener pane. This hook, along with the parallel graph hook
makes it possible to set up Snd to behave internally like a window manager with pointer focus.  That is, to
ensure that the pane under the mouse is the one that receives keyboard input, we can define the following
hook procedures:
</p>

<pre class="indented">
(hook-push <em class=red>mouse-enter-graph-hook</em>
  (lambda (hook)
    (if (<a class=quiet href="#soundp">sound?</a> (hook 'snd))
         (<a class=quiet href="#focuswidget">focus-widget</a> (car (<a class=quiet href="#channelwidgets">channel-widgets</a> (hook 'snd) (hook 'chn)))))))

(hook-push <em class=red>mouse-enter-listener-hook</em>
  (lambda (hook)
    (<a class=quiet href="#focuswidget">focus-widget</a> (hook 'widget))))
</pre>
<div class="spacer"></div>



<!-- mouse-enter-text-hook -->
<pre class="indented">
<em class=def id="mouseentertexthook">mouse-enter-text-hook</em> (widget)
</pre>

<p>This hook is called when the mouse enters a text widget (this is the third of the pointer focus hooks).
</p>

<pre class="indented">
(hook-push <em class=red>mouse-enter-text-hook</em>
  (lambda (hook)
    (<a class=quiet href="#focuswidget">focus-widget</a> (hook 'widget))))
</pre>
<div class="spacer"></div>


<!-- mouse-leave-graph-hook -->
<pre class="indented">
<em class=def id="mouseleavegraphhook">mouse-leave-graph-hook</em> (snd chn)
</pre>

<p>This hook is called when the mouse leaves a channel's drawing area (graph pane). 
</p>
<div class="spacer"></div>


<!-- mouse-leave-label-hook -->
<pre class="indented">
<em class=def id="mouseleavelabelhook">mouse-leave-label-hook</em> (type position name)
</pre>

<p>This hook is called when the mouse exits one of the labels covered by <a href="#mouseenterlabelhook">mouse-enter-label-hook</a>. 
See <a href="sndscm.html#nbdoc">nb.scm</a>.
</p>
<div class="spacer"></div>


<!-- mouse-leave-listener-hook -->
<pre class="indented">
<em class=def id="mousleavelistenerhook">mouse-leave-listener-hook</em> (widget)
</pre>

<p>This hook is called when the mouse leaves the listener pane.
</p>
<div class="spacer"></div>


<!-- mouse-leave-text-hook -->
<pre class="indented">
<em class=def id="mousleavetexthook">mouse-leave-text-hook</em> (widget)
</pre>

<p>This hook is called when the mouse leaves a text widget.
</p>
<div class="spacer"></div>


<!-- mouse-press-hook -->
<pre class="indented">
<em class=def id="mousepresshook">mouse-press-hook</em> (snd chn button state x y)
</pre>

<p>This hook is called upon a mouse button press within the lisp graph (see enved.scm).  The 'x' and 'y' values are 
relative to the lisp graph axis (as if the raw mouse pixel position was passed through
<a href="#positiontox">position-&gt;x</a> and <a href="#positiontoy">position-&gt;y</a>).
</p>
<div class="spacer"></div>


<!-- mus-error-hook -->
<pre class="indented">
<em class=def id="muserrorhook">mus-error-hook</em> (type message)
</pre>

<p>This hook is called upon mus-error.
If it returns #t, Snd ignores the error (it assumes you've handled it via the hook).
Both mus_error and mus_print run this hook; in the mus_print case, the 'type' is mus-no-error (0).
You can redirect mus_print output from stderr (the default) to stdout via:
</p>

<pre class="indented">
(hook-push <em class=red>mus-error-hook</em>
  (lambda (hook)
    (if (= (hook 'type) 0)
        (begin
	  (display (hook 'message))
	  (set! (hook 'result) #t)))))
</pre>

<p>To decode the 'type' argument, see <a href="#muserrortypetostring">mus-error-type-&gt;string</a>.
</p>
<div class="spacer"></div>


<!-- name-click-hook -->
<pre class="indented">
<em class=def id="nameclickhook">name-click-hook</em> (snd)
</pre>

<p>This hook is called when the sound name is clicked (in the label in the status area region of the sound's pane).
If the function returns #t, the usual highly informative status area babbling is squelched.
</p>

<pre class="indented">
(hook-push <em class=red>name-click-hook</em>
  (lambda (hook) ; toggle read-only
    (set! (<a class=quiet href="#readonly">read-only</a> (hook 'snd)) (not (<a class=quiet href="#readonly">read-only</a> (hook 'snd))))
    (set! (hook 'result) #t)))
</pre>
<div class="spacer"></div>


<!-- new-sound-hook -->
<pre class="indented">
<em class=def id="newsoundhook">new-sound-hook</em> (name)
</pre>

<p>This hook is called whenever a new sound file is being created.  <a href="sndscm.html#sound-let">sound-let</a> in ws.scm uses
this hook to keep track of newly created temporary sounds so that it can delete them once they are no longer needed.
</p>
<div class="spacer"></div>


<!-- new-widget-hook -->
<pre class="indented">
<em class=def id="newwidgethook">new-widget-hook</em> (widget)
</pre>

<p>This hook is called each time a dialog or a new set of channel or sound widgets is created.  
This is used in misc.scm (paint-all) to
make sure all newly created widgets have the same background pixmaps.
</p>
<div class="spacer"></div>



<!-- open-hook -->
<pre class="indented">
<em class=def id="openhook">open-hook</em> (name)
</pre>

<p>This hook is called before a sound file is opened.
If the function returns #t, or the sound is not readable (bad header, etc) the file is not opened
and any corresponding <a href="#afteropenhook">after-open-hook</a> functions are not called.
If it returns a string (a filename), that file is opened instead of the original one.
</p>

<pre class="indented">
(hook-push <em class=red>open-hook</em>
  (lambda (hook)
    (let ((filename (hook 'name)))
      (if (and (= (<a class=quiet href="#mussoundheadertype">mus-sound-header-type</a> filename) <a class=quiet href="#headertype">mus-raw</a>)
               ;; check for "OggS" first word, if found, translate to something Snd can read
	       (call-with-input-file filename 
	        (lambda (fd)
		  (equal? (read-string 4 fd) "OggS"))))
	(let ((aufile (string-append filename ".au")))
	  (if (file-exists? aufile) (delete-file aufile))
	  (system (<a class=quiet>format</a> #f "ogg123 -d au -f ~A ~A" aufile filename))
	  (set! (hook 'result) aufile)))))) ; now open-sound will read the new .au file
</pre>

<div class="spacer"></div>



<!-- open-raw-sound-hook -->
<pre class="indented">
<em class=def id="openrawsoundhook">open-raw-sound-hook</em> (name state)
</pre>

<p>This hook is called each time <a href="#opensound">open-sound</a> encounters a headerless file.
Its result can be a list describing the raw file's attributes (thereby bypassing the Raw File Dialog and so on):
(list chans srate sample-type data-location data-length) where trailing elements can 
be omitted ('data-location' defaults to 0, and 'data-length' defaults to the file length in bytes).
In Ruby and Forth, if there is more than one function on the hook list, functions after the first get the
on-going list result as the 'state (the empty list is the default).
</p>

<pre class="indented">
(hook-push <em class=red>open-raw-sound-hook</em> 
  (lambda (hook) 
    (set! (hook 'result) (list 1 44100 <a class=quiet href="#sampletype">mus-lshort</a>))))
</pre>

<p>Return () to accept all the current raw header defaults; return #f to fallback on the Raw File Dialog.
The raw header defaults are stereo, 44100 Hz, big endian short data; these values can be changed in the
Raw File Dialog, by calling <a href="#openrawsound">open-raw-sound</a> with explicit arguments, 
or via <a href="#musheaderrawdefaults">mus-header-raw-defaults</a>.
If the hook returns #t, <a href="#opensound">open-sound</a> returns without opening the file.
</p>
<div class="spacer"></div>



<!-- orientation-hook -->
<pre class="indented">
<em class=def id="orientationhook">orientation-hook</em> () 
</pre>

<p>This hook is called whenever one of the variables associated with the orientation dialog changes.  
</p>
<div class="spacer"></div>



<!-- output-comment-hook -->
<pre class="indented">
<em class=def id="outputcommenthook">output-comment-hook</em> (comment)
</pre>

<p>This hook is called in the Save-As dialog to set the default output comment value. 'str' is the current sound's comment.
If there is more than one hook function, each function's result is passed as input to the next function in the list.
</p>

<pre class="indented">
(hook-push <em class=red>output-comment-hook</em>
  (lambda (hook)   ; append a time-stamp
    (set! (hook 'result) 
      (string-append (hook 'comment)
                     ": written " 
                     (strftime "%a %d-%b-%Y %H:%M %Z" (localtime (current-time)))))))

;; in Ruby: format("%s: written %s", comment, Time.new.localtime.strftime("%d-%b %H:%M %Z"))
</pre>
<div class="spacer"></div>


<!-- play-hook -->
<pre class="indented">
<em class=def id="playhook">play-hook</em> (size)
</pre>

<p>This hook is called each time a buffer is about to be 
filled for the DAC.  The buffer size is 'size'.
See <a href="sndscm.html#enveddoc">enved.scm</a> and <a href="sndscm.html#marksdoc">marks.scm</a>.
</p>
<div class="spacer"></div>



<!-- read-hook -->
<pre class="indented">
<em class=def id="readhook">read-hook</em> (text)
</pre>

<p>This hook is called each time a line is typed into the listener (it is triggered by the carriage return).
</p>
<div class="spacer"></div>



<!-- save-hook -->
<pre class="indented">
<em class=def id="savehook">save-hook</em> (snd name)
</pre>

<p>This hook is called each time a sound ('snd') is about to be saved.
If it returns #t, the file is not saved.  'name' is #f unless 
the file is being saved under a new name (as in <a href="#savesoundas">save-sound-as</a>).
See <a href="sndscm.html#autosavedoc">autosave.scm</a>.
</p>
<div class="spacer"></div>



<!-- save-state-hook -->
<pre class="indented">
<em class=def id="savestatehook">save-state-hook</em> (name)
</pre>

<p>This hook is called each time the <a href="#savestate">save-state</a>
mechanism is about to create a new temporary file to save some edit history sample data; that is,
each channel's edit history data is saved in a separate temporary file, and this hook provides
a way to specify the name of that file.
'name' is the temporary file name that will be used unless
the hook function returns a different one (as a string).  This hook provides a way to
keep track of which files are used in a given saved state batch, so
that later cleanup is easier to manage.
</p>
<div class="spacer"></div>



<!-- select-channel-hook -->
<pre class="indented">
<em class=def id="selectchannelhook">select-channel-hook</em> (snd chn)
</pre>

<p>This hook is called when a channel is selected (after the sound has been selected). 
The function arguments are the sound's index and the channel number.
</p>
<div class="spacer"></div>



<!-- select-sound-hook -->
<pre class="indented">
<em class=def id="selectsoundhook">select-sound-hook</em> (snd)
</pre>

<p>This hook is called when a sound is selected. The argument is the about-to-be-selected sound.
</p>
<div class="spacer"></div>



<!-- snd-error-hook -->
<pre class="indented">
<em class=def id="snderrorhook">snd-error-hook</em> (message)
</pre>

<p>This hook is called upon <a href="#snderror">snd-error</a>.  If the listener is closed, it is also called upon any Scheme, Ruby, or Forth error.
If it returns #t, Snd flushes the error (it assumes you've 
dealt with it via the hook).
</p>

<pre class="indented">
(hook-push <em class=red>snd-error-hook</em>
  (lambda (hook)
    (<a class=quiet href="#play">play</a> "bong.snd")))
</pre>
<div class="spacer"></div>



<!-- snd-warning-hook -->
<pre class="indented">
<em class=def id="sndwarninghook">snd-warning-hook</em> (message)
</pre>

<p>This hook is called upon <a href="#sndwarning">snd-warning</a>.
If it returns #t, Snd flushes the warning (it assumes you've 
reported it via the hook).
</p>

<pre class="indented">
(define without-warnings
  (lambda (thunk)
    (let ((no-warning (lambda (hook) (set! (hook 'result) #t))))
      (hook-push <em class=red>snd-warning-hook</em> no-warning)
      (thunk)
      (hook-remove <em class=red>snd-warning-hook</em> no-warning))))
</pre>
<div class="spacer"></div>


<!-- start-playing-hook -->
<pre class="indented">
<em class=def id="startplayinghook">start-playing-hook</em> (snd)
</pre>

<p>This hook is called when a sound is about to be played.
If its function returns #t, Snd does not play.
We can use this hook to replace "play" with "play selection" if the
selection is active:
</p>

<pre class="indented">
(hook-push <em class=red>start-playing-hook</em>
  (lambda (hook)
    (if (and (<a class=quiet href="#selectionok">selection?</a>)
	     (<a class=quiet href="#selectionmember">selection-member?</a> (hook 'snd)))
	(begin
	  (play (selection))
	  (set! (hook 'result) #t))))) ; there's a selection so don't play the entire sound
</pre>
<div class="spacer"></div>



<!-- start-playing-selection-hook -->
<pre class="indented">
<em class=def id="startplayingselectionhook">start-playing-selection-hook</em> ()
</pre>

<p>This hook is called when the selection is about to be played.
If its function returns #t, Snd does not play the selection.
</p>
<div class="spacer"></div>



<!-- stop-playing-hook -->
<pre class="indented">
<em class=def id="stopplayinghook">stop-playing-hook</em> (snd)
</pre>

<p>This hook is called when a sound finishes playing.  stop-playing-hook may be called more often than start-playing-hook.
</p>
<div class="spacer"></div>


<!-- stop-playing-selection-hook -->
<pre class="indented">
<em class=def id="stopplayingselectionhook">stop-playing-selection-hook</em> ()
</pre>

<p>This hook is called when the selection finishes playing.
</p>
<div class="spacer"></div>


<!-- update-hook -->
<pre class="indented">
<em class=def id="updatehook">update-hook</em> (snd)
</pre>

<p>update-hook is called just before a sound is updated ("update" means the sound is re-read from the disk, flushing the current version; this
is useful if you overwrite a sound file with some other program, while viewing it in Snd). 
The update process can be triggered by a variety of situations, not just by <a href="#updatesound">update-sound</a>. 
The hook is passed the sound's index.  If it returns #t, the update is cancelled (this is not 
recommended!); if it returns a procedure of one argument, that procedure is called upon 
completion of the update operation; its argument is the (possibly different) sound. 
Snd tries to maintain the index across the update, but if you change the number of channels 
the newly updated sound may have a different index.  <a href="sndscm.html#addmarkpane">add-mark-pane</a> in snd-motif.scm uses
the returned procedure to make sure the mark pane is reactivated right away when a sound is updated. The basic idea is:
</p>

<pre class="indented">
(hook-push <em class=red>update-hook</em>
  (lambda (hook)             
    (set! (hook 'result) 
      (lambda (updated-snd)  ; this code executed when update is complete
        (<a class=quiet href="#sndprint">snd-print</a> "ok!")))))
</pre>

<p>I use update-hook to make sure the y axis bounds reflect the new maxamp, if it is greater than 1.0:
</p>

<pre class="indented">
(hook-push <em class=red>update-hook</em>
  (lambda (hook)
    (let ((old-snd (hook 'snd)))  ; (hook 'snd) is the sound about to be updated
      (set! (hook 'result) 
           (lambda (snd)
              (do ((i 0 (+ i 1)))
	          ((= i (<a class=quiet href="#chans">channels</a> snd)))
	        (let ((mx (<a class=quiet href="#maxamp">maxamp</a> snd i)))
	        (if (&gt; mx 1.0)
  	            (set! (<a class=quiet href="#ybounds">y-bounds</a> snd i) (list (- mx) mx))
	            (if (and (&gt; (cadr (<a class=quiet href="#ybounds">y-bounds</a> old-snd)) 1.0) ; previous (pre-update) version was &gt; 1.0
		             (&lt;= mx 1.0))                      ; but current is not, so reset axes
		        (set! (<a class=quiet href="#ybounds">y-bounds</a> snd i) (list -1.0 1.0)))))))))))
</pre>
<div class="spacer"></div>


<!-- view-files-select-hook -->
<pre class="indented">
<em class=def id="viewfilesselecthook">view-files-select-hook</em> (dialog name) [Motif only]
</pre>

<p>This hook is called each time a file is selected in a View Files dialog's files list. 
</p>
<div class="spacer"></div>



<div class="innerheader">Channel-specific hooks:</div>

<pre class="indented">
<em class=def id="edithook">edit-hook</em> (snd chn)
<em class=def id="undohook">undo-hook</em> (snd chn)
<em class=def id="afteredithook">after-edit-hook</em> (snd chn)
</pre>

<p>These are functions that return the hooks in question associated with the specified channel.
In Ruby and Forth the functions on these hooks are thunks &mdash; they should take no arguments.
edit-hook is called just before any attempt to edit the channel's data; if it returns #t,
the edit is cancelled. So,
</p>

<pre class="indented">
Scheme: (hook-push (edit-hook hook) (lambda (hook) (set! (hook 'result) #t)))
Ruby:   edit_hook(snd, chn).add_hook!(\"stop-edit\") do | | true end
Forth:  snd chn edit-hook lambda: &lt;{ }&gt; #t ; add-hook!
</pre>

<p>halts any attempt to edit the data; this is even more restrictive than setting the read-only
flag because the latter only refuses to overwrite the current data.  undo-hook is called
just after any undo, redo, or revert that affects the channel.  after-edit-hook is called
after an edit, but before after-graph-hook (<a href="sndscm.html#addmarkpane">add-mark-pane</a> in snd-motif.scm 
uses this hook to update a mark list after each edit
so that the displayed mark positions are correct).
You can use edit-hook to set
up protected portions of the edit history:
</p>

<pre class="indented">
(define* (protect snd chn)
  (let ((edit-pos (<a class=quiet href="#editposition">edit-position</a> snd chn))
        (hook (<em class=red>edit-hook</em> snd chn)))
    (set! (hook-functions hook)
      (list 
        (lambda ()
          (let ((val (&lt; (<a class=quiet href="#editposition">edit-position</a> snd chn) edit-pos)))
            (if val (<a class=quiet href="#statusreport">status-report</a> "protected"))
            (set! (hook 'result) val)))))))

(define* (unprotect snd chn)
  (set! (hook-functions (<em class=red>edit-hook</em> snd chn)) ()))
</pre>

<p><a href="sndscm.html#enveddoc">enved.scm</a> uses several of these hooks to implement an envelope editor in lisp.
add-mark-pane in snd-motif.scm uses them to make sure the mark list reflects the current edit history location.
See also autosave.scm.  It is possible for after-edit-hook to be called more often that edit-hook, or
vice-versa; edit-hook may be called more than once on a given attempt to edit; if a long computation is required
Snd may check edit-hook ahead of time to avoid unnecessary work.
</p>




<div class="header" id="sndobjects">Snd's objects</div>

<p>Snd presents its various data structures as a list
of sounds, each with a list of channels, each with lists of edits,
marks, and mixes.  The sound data itself is accessed through
a variety of structures and functions, each aimed at a particular
kind of use.  The accessors from lowest level up are:
samplers (one sample at a time iterators) and frample-readers (a "frample" is a multichannel sample),
channel-at-a-time blocks (float-vectors, map-channel, etc), multichannel blocks (map-sound, etc),
a few historical leftovers that follow the "sync" field (scale-to, etc), and finally
the top-level operations such as save-sound-as (these are used in the File menu, etc).
In the following sections, I'll start with the lowest level and work upwards, more or less.
But before launching into samplers, I need to explain a few things
about the following documentation.
</p>

<p>
Each sound is an object in Snd, and has an
associated index.  To refer to that sound, you can use either the object or the index.
In the argument lists
below, 'snd' as an argument refers to either the sound object or its index.  It normally defaults to the currently
selected sound.  Similarly, 'chn' is the channel number, starting from 0, and defaults
to the currently selected channel.  So if there's only one sound active, and it has only
one channel, (cursor), (cursor 0), (cursor 0 0), and (cursor (integer-&gt;sound 0)) all refer to the same
thing.  If you want to refer to the currently selected sound explicitly, use
<a href="#selectedsound">selected-sound</a>.
</p>

<p>In many cases, the 'snd', 'chn', and 'reg' arguments
can be #t which
means "all"; if 'snd' is #t, all sounds are included.
<code>(<a class=quiet href="#expandcontrol">expand-control</a> #t)</code>
returns a list of the current
control panel expansion settings of all sounds, and
<code>(set! (<a class=quiet href="#transformgraphp">transform-graph?</a> #t #t) #t)</code>
turns on the fft display in all channels of all sounds.
</p>

<p>When an error occurs, the function throws a tag such as 'no-such-sound,
'no-active-selection, etc.
All the functions that take sound and channel args ('snd chn' below) can return the errors
'no-such-sound and 'no-such-channel; all the mix-related functions can return 'no-such-mix;
all the region-related functions can return 'no-such-region; all selection-oriented functions
can return 'no-active-selection. To reduce clutter, I'll omit mention
of these below.  
</p>



<!-- INDEX samplers:samplers -->
<!--  SAMPLERS  -->

<div class="header" id="samplers">Samplers</div>

<p>
The simplest data access function is <a href="#sample">sample</a> which returns the sample at
a given position in a sound's channel.  This simplicity, however, comes at
a price in computation:  if the desired sample is not in Snd's
in-core (already loaded) view of the data, it has to go get the sample,
which can sometimes require that it open, read, and close a sound file.
The result is that sample can bring your code
to a grinding halt.  There are two alternatives, leaving aside the scanning
and mapping functions mentioned below.  One involves keeping the buffer of
data around explicitly (channel-&gt;float-vector), and the other involves the
use of a special object known as a sampler.  The sampler
returns the next sample in its sound each time it is called; this kind
of access is sometimes called an "enumerator" (Ruby) or perhaps "iterator".
The buffer approach (channel-&gt;float-vector in <a href="grfsnd.html#expsrc">expsrc</a>)
is better if you're jumping around in the data, the sample-by-sample approach if you're treating
the data as a sequence of samples.
To get a sampler,
you create a reader (via <a class=quiet href="#makesampler">make-sampler</a>) giving it the start position, the sound and channel
to read, and the initial read direction, then get data via <a class=quiet href="#readsample">read-sample</a> (which remembers the
read direction passed to <a class=quiet href="#makesampler">make-sampler</a>), 
or <a class=quiet href="#nextsample">next-sample</a> (read forward) and
<a class=quiet href="#previoussample">previous-sample</a> (read backward); 
when done, you can close the reader with <a class=quiet href="#freesampler">free-sampler</a>, 
but it's usually not necessary; the
garbage collector will take care of it if you forget (but, sigh, the GC can be dilatory at times).
</p>

<p>There is a similar set of functions giving access to the mix data.
<a class=quiet href="#makemixsampler">make-mix-sampler</a> returns a mix reader for the desired mix,
<a class=quiet href="#mixsamplerQ">mix-sampler?</a> returns #t if its argument in a mix sampler,
and <a class=quiet href="#readmixsample">read-mix-sample</a> returns the next sample (before it is mixed into
the output).
</p>


<!--  SAMPLER TABLE  -->
<div class="spacer"></div>


<!-- copy-sampler -->
<pre class="indented">
<em class=def id="copysampler">copy-sampler</em> obj
</pre>

<p>copy-sampler returns a copy of 'obj' which can be any kind of sampler.
</p>
<div class="spacer"></div>


<!-- free-sampler -->
<pre class="indented">
<em class=def id="freesampler">free-sampler</em> obj
</pre>

<p>free-sampler
releases the sampler 'obj'.  In most cases, you don't need to call this
function because the garbage collector handles the sampler object, but it doesn't hurt anything (but don't try to use a sampler
after you've freed it!).  If you're using zillions of samplers, sometimes freeing the samplers explicitly can reduce
demands on memory.
</p>
<div class="spacer"></div>


<!-- make-mix-sampler -->
<pre class="indented">
<em class=def id="makemixsampler">make-mix-sampler</em> mix (beg 0)
</pre>

<p>make-mix-sampler creates a mix-sampler reading 'mix' starting (in the mix input) at 'beg'.
See <a href="sndscm.html#mixtofv">mix-&gt;float-vector</a> in mix.scm.
</p>
<div class="spacer"></div>


<!-- make-region-sampler -->
<pre class="indented">
<em class=def id="makeregionsampler">make-region-sampler</em> reg start chn (dir 1)
</pre>

<p>make-region-sampler creates a sampler reading channel 'chn' of the region 'reg' starting
at sample 'start', and reading forward if 'dir' is 1, backwards if 'dir' is -1.
It is not safe to assume that this reader will return zeros beyond the region boundaries.
</p>
<div class="spacer"></div>


<!-- make-sampler -->
<pre class="indented">
<em class=def id="makesampler">make-sampler</em> start snd chn dir edpos
</pre>

<p>make-sampler creates a sampler reading the given channel
starting at sample 'start' with initial read direction 'dir' 
(1=forward, -1=backward).  'edpos' is the edit history position to read;
it defaults to the current edit. 
</p>

<pre class="indented">
&gt; (open-sound "oboe.snd")
#&lt;sound 0&gt;
&gt; (define reader (make-sampler 1000))
reader
&gt; reader
#&lt;sampler: oboe.snd[0: 0] from 1000, at 1000, forward&gt;
&gt; (read-sample reader)
0.0328369140625
&gt; (sample 1000)
0.0328369140625
&gt; (next-sample reader)
0.0347900390625
&gt; (sample 1001)
0.0347900390625
&gt; (sampler-home reader)
(#&lt;sound 0&gt; 0)
&gt; (sampler-position reader)
1002
</pre>

<p>One use of 'edpos' is to get the difference 
between two edits:
</p>

<pre class="indented">
(define snd-diff
  (lambda () ;assume mono, get diff between current state and previous
    (let* ((index (<a class=quiet href="#selectedsound">selected-sound</a>))
           (edit-pos (<a class=quiet href="#editposition">edit-position</a> index))
           (previous-edit (<em class=red>make-sampler</em> 0 0 index 1 (- edit-pos 1))))
      (lambda (x)
        (- x (<a class=quiet href="#readsample">read-sample</a> previous-edit)) #f))))

(<a class=quiet href="#mapchannel">map-channel</a> (snd-diff))
</pre>

<p>Once the reader has been set up to read at a given edit position, subsequent
edits won't affect it. One sequence that takes advantage of this is: make-sampler, scale-by 0,
then run an overlap-add process on the data from before the scaling.
</p>

<p>'snd' can be a filename (a string); in this way a sampler
can read external sounds without going to the trouble of loading them into Snd.
</p>

<pre class="indented">
(define reader (make-sampler 100 "oboe.snd"))
</pre>

<p>'snd' also can be a mix or region.
make-sampler is probably the most useful function in Snd; there are lots of examples
in the Scheme, Ruby, and Forth files.
</p>
<div class="spacer"></div>


<!-- mix-sampler? -->
<pre class="indented">
<em class=def id="mixsamplerQ">mix-sampler?</em> obj
</pre>

<p>mix-sampler? returns #t if 'obj' is a mix-sampler.
</p>
<div class="spacer"></div>


<!-- next-sample -->
<pre class="indented">
<em class=def id="nextsample">next-sample</em> obj
</pre>

<p>next-sample returns the next sample (reading forward) read by the sampler 'obj'.
</p>
<div class="spacer"></div>


<!-- previous-sample -->
<pre class="indented">
<em class=def id="previoussample">previous-sample</em> obj
</pre>

<p>previous-sample returns the previous sample in the stream read by the sampler 'obj'.
</p>
<div class="spacer"></div>


<!-- read-mix-sample -->
<pre class="indented">
<em class=def id="readmixsample">read-mix-sample</em> obj
</pre>

<p>read-mix-sample returns the next sample read by the mix-sampler 'obj'.
</p>
<div class="spacer"></div>


<!-- read-region-sample -->
<pre class="indented">
<em class=def id="readregionsample">read-region-sample</em> obj
</pre>

<p>read-region-sample returns the next sample read by the region-sampler 'obj'.
</p>

<pre class="indented">
(define* (region-&gt;float-vector reg (chn 0))
  (cond ((not (region? reg))
         (error 'no-such-region (list "region-&gt;float-vector" reg)))

        ((&lt; chn (channels reg))
         (let ((reader (<em class=red>make-region-sampler</em> 0 reg chn))
               (len (region-framples reg)))
           (do ((data (make-float-vector len))
                (i 0 (+ i 1)))
               ((= i len) data)
             (set! (data i) (<em class=red>reader</em>)))))

        (else
         (error 'no-such-channel (list "region-&gt;float-vector" reg chn)))))
</pre>
<div class="spacer"></div>


<!-- read-sample -->
<pre class="indented">
<em class=def id="readsample">read-sample</em> obj
</pre>

<p>read-sample returns the next sample read by the sampler 'obj', 
reading in the direction set by <a class=quiet href="#makesampler">make-sampler</a>.
</p>
<div class="spacer"></div>


<!-- read-sample-with-direction -->
<pre class="indented">
<em class=def id="readsamplewithdirection">read-sample-with-direction</em> obj dir
</pre>

<p>read-sample-with-direction returns the next sample read by the sampler 'obj', 
reading in the direction set by 'dir' (1 = forward, -1 = backward).  This
combination of next-sample and previous-sample is intended mainly for src.
</p>
<div class="spacer"></div>


<!-- region-sampler? -->
<pre class="indented">
<em class=def id="regionsamplerQ">region-sampler?</em> obj
</pre>

<p>region-sampler? returns #t if 'obj' is a region sampler.
</p>
<div class="spacer"></div>


<!-- sampler-at-end? -->
<pre class="indented">
<em class=def id="sampleratendQ">sampler-at-end?</em> obj
</pre>

<p>sampler-at-end? returns #t if the sampler 'obj' (any kind of reader) is at the end of the sound (or whatever it is reading),
and hence is returning 0.0 each time it is called.  When the last "real" sample is returned, the at-end? flag is still false; when it
becomes true, the sampler returns a 0.0 sample.
See <a href="sndscm.html#locatezero">locate-zero</a> in examp.scm, or <a href="sndscm.html#linearsrcchannel">linear-src-channel</a> in dsp.scm.
</p>
<div class="spacer"></div>


<!-- sampler-home -->
<pre class="indented">
<em class=def id="samplerhome">sampler-home</em> obj
</pre>

<p>sampler-home returns information describing the source of the data the sampler 'obj' is reading.
if 'obj' is a sound sampler, it returns a list with the sound and channel number associated with 'obj'.
If 'obj' is a mix reader, it returns the mix. 
Finally, if 'obj' is a region reader, it returns a list with the region.
</p>
<div class="spacer"></div>


<!-- sampler-position -->
<pre class="indented">
<em class=def id="samplerposition">sampler-position</em> obj
</pre>

<p>sampler-position returns the
current (sample-wise) location of the sampler 'obj' (any kind of reader).
</p>
<div class="spacer"></div>


<!-- sampler? -->
<pre class="indented">
<em class=def id="samplerQ">sampler?</em> obj
</pre>

<p>sampler? returns #t if 'obj' is a sampler.
</p>


<p>If your extension language supports it, the read-sample functions can be omitted: <code>(reader)</code> is the same as <code>(<a class=quiet href="#readsample">read-sample</a> reader)</code>.
</p>



<div class="innerheader">Snd-&gt;sample</div>

<p>There is a Snd-specific CLM-style generator that redirects CLM instrument input (via in-any, ina, etc)
to Snd data, snd-&gt;sample. 
</p>

<!-- make-snd->sample -->
<pre class="indented">
<em class=def id="makesndtosample">make-snd-&gt;sample</em> snd
</pre>

<p>make-snd-&gt;sample creates a Snd data reader for use with CLM's in-any, file-&gt;sample, etc.
</p>
<div class="spacer"></div>



<!-- snd->sample -->
<pre class="indented">
<em class=def id="sndtosample">snd-&gt;sample</em> gen frample chan
</pre>

<p>snd-&gt;sample gets the next sample from the data accessed by 'gen', similar to file-&gt;sample.
If *reverb* is a snd-&gt;sample generator, for example,
<a class=quiet href="sndclm.html#ina">ina</a> and <a class=quiet href="sndclm.html#filetosample">file-&gt;sample</a> actually call snd-&gt;sample.
</p>
<div class="spacer"></div>


<!-- snd->sample? -->
<pre class="indented">
<em class=def id="sndtosamplep">snd-&gt;sample?</em> obj
</pre>

<p>snd-&gt;sample? returns #t if 'obj' is a snd-&gt;sample generator.
</p>
<div class="spacer"></div>




<!-- INDEX Floatvectors:Float-vectors -->

<div class="header" id="Floatvectors">float-vectors or vcts</div>

<p>These are arrays of floats.  In s7, use "float-vector", and in Forth and
Ruby use "vct".  
</p>


<!--  FLOATVECTOR TABLE  -->

<div class="spacer"></div>


<!-- list->float-vector -->
<pre class="indented">
<em class=def id="listtofv">list-&gt;float-vector</em> lst
<em class=emdef>list-&gt;vct</em> lst
</pre>

<p>return a new float-vector with elements of list 'lst' (equivalent to the <a href="#fv">float-vector</a> function).
</p>
<div class="spacer"></div>


<!-- make-float-vector -->
<pre class="indented">
<em class=def id="makefv">make-float-vector</em> len (initial-element 0.0)
<em class=emdef>make-vct</em> len (initial-element 0.0)
</pre>

<p>make-float-vector creates a float-vector of size 'len'.
</p>
<div class="spacer"></div>


<!-- float-vector -->
<pre class="indented">
<em class=def id="fv">float-vector</em> :rest args
<em class=emdef>vct</em> :rest args
</pre>

<p>float-vector is equivalent to list-&gt;float-vector with 'args' as the list: <code>(float-vector 0.0 0.1 0.2)</code>.
</p>
<div class="spacer"></div>


<!-- float-vector? -->
<pre class="indented">
<em class=def id="fvp">float-vector?</em> v
<em class=emdef>vct?</em> v
</pre>

<p>float-vector? returns #t if 'v' is a float-vector.
</p>
<div class="spacer"></div>


<!-- float-vector-abs! -->
<pre class="indented">
<em class=def id="fvabs">float-vector-abs!</em> v
<em class=emdef>vct-abs!</em> v
</pre>

<p>float-vector-abs! replaces each element of 'v' with its absolute value.
</p>
<div class="spacer"></div>


<!-- float-vector-add! -->
<pre class="indented">
<em class=def id="fvadd">float-vector-add!</em> v1 v2 (off 0)
<em class=emdef>vct-add!</em> v1 v2 (off 0)
</pre>

<p>float-vector-add! performs element-wise add: v1[i + off] += v2[i], returning 'v1'.
</p>
<div class="spacer"></div>


<!-- float-vector-copy -->
<pre class="indented">
<em class=def id="fvcopy">copy</em> v
<em class=emdef>vct-copy</em> v
</pre>

<p>float-vector-copy returns a copy of the float-vector 'v'.
</p>

<!-- INDEX copying:Copying -->
<TABLE class="method">
<tr><th class="title">Copying</th></tr>
<tr><td>
<blockquote id="copying"><small>
copy file: in Scheme: copy-file, in Ruby: File.copy or File.syscopy<br>
copy string: in Forth: string-copy<br>
copy list: in Forth: list-copy or copy-tree<br>
copy mix: <a href="sndscm.html#mixtofv">mix-&gt;float-vector</a><br>
copy sampler: <a href="#copysampler">copy-sampler</a><br>
copy (clone) current sound edit state: <a href="#clonesoundas">clone-sound-as</a><br>
copy channel data: <a href="#channeltofv">channel-&gt;float-vector</a>, or <a href="#savesoundas">save-sound-as</a><br>
copy selection data: <a href="#selection2fv">selection-&gt;float-vector</a> or <a href="#saveselection">save-selection</a><br>
copy region data: <a href="#regiontofv">region-&gt;float-vector</a>, <a href="#saveregion">save-region</a><br>
copy transform data: <a href="#transformtofv">transform-&gt;float-vector</a><br>
</small></blockquote>
</td></tr></TABLE>
<div class="spacer"></div>


<!-- float-vector-equal? -->
<pre class="indented">
<em class=def id="fvequal">float-vector-equal?</em> v1 v2 diff
<em class=emdef>vct-equal?</em> v1 v2 diff
</pre>

<p>float-vector-equal? is an element-wise relative difference check.
If (abs(v1[i] - v2[i]) / (max (abs v1[i]) (abs v2[i]))) &gt; diff, it returns false.
Otherwise it returns the maximum relative difference encountered.  If v1 and v2
are of different lengths, the overlapping portion is checked.
</p>
<div class="spacer"></div>


<!-- float-vector-fill! -->
<pre class="indented">
<em class=def id="fvfill">float-vector-fill!</em> v val
<em class=emdef>vct-fill!</em> v val
</pre>

<p>float-vector-fill! sets each element of 'v' to 'val': v[i] = val.  It returns 'v'.
</p>
<div class="spacer"></div>


<!-- float-vector-length -->
<pre class="indented">
<em class=def id="fvlength">float-vector-length</em> v
<em class=emdef>vct-length</em> v
</pre>

<p>float-vector-length returns the length of 'v'.
</p>
<div class="spacer"></div>


<!-- float-vector-max -->
<pre class="indented">
<em class=def id="fvmax">float-vector-max</em> v
<em class=emdef>vct-max</em> v
</pre>

<p>float-vector-max returns the maximum value of the elements of 'v'.
</p>
<div class="spacer"></div>


<!-- float-vector-min -->
<pre class="indented">
<em class=def id="fvmin">float-vector-min</em> v
<em class=emdef>vct-min</em> v
</pre>

<p>float-vector-min returns the minimum value of the elements of 'v'.
</p>
<div class="spacer"></div>


<!-- float-vector-move! -->
<pre class="indented">
<em class=def id="fvmove">float-vector-move!</em> v new old backwards
<em class=emdef>vct-move!</em> v new old backwards
</pre>

<p>float-vector-move moves a block of values within a float-vector:  v[new++] = v[old++], or
if 'backwards' is #t: v[new--] = v[old--].  It returns 'v'.
</p>
<div class="spacer"></div>


<!-- float-vector-multiply! -->
<pre class="indented">
<em class=def id="fvmultiply">float-vector-multiply!</em> v1 v2
<em class=emdef>vct-multiply!</em> v1 v2
</pre>

<p>float-vector-multiply! performs element-wise multiply of two float-vectors: v1[i] *= v2[i].  It returns 'v1'.
</p>
<div class="spacer"></div>


<!-- float-vector-offset! -->
<pre class="indented">
<em class=def id="fvoffset">float-vector-offset!</em> v val
<em class=emdef>vct-offset!</em> v val
</pre>

<p>float-vector-offset! adds 'val' to each element of 'v':  v[i] += val.  It returns 'v'.
</p>
<div class="spacer"></div>


<!-- float-vector-peak -->
<pre class="indented">
<em class=def id="fvpeak">float-vector-peak</em> v
<em class=emdef>vct-peak</em> v
</pre>

<p>float-vector-peak returns the maximum absolute value of the elements of 'v'.
</p>
<div class="spacer"></div>


<!-- float-vector-ref -->
<pre class="indented">
<em class=emdef>float-vector-ref</em> v pos
<em class=emdef>vct-ref</em> v pos
</pre>

<p>float-vector-ref returns the element 'pos' in 'v': v[pos].
</p>
<div class="spacer"></div>


<!-- float-vector-reverse! -->
<pre class="indented">
<em class=def id="fvreverse">float-vector-reverse!</em> v size
<em class=emdef>vct-reverse!</em> v size
</pre>

<p>float-vector-reverse! reverses the elements of 'v' (in-place), returning 'v'.  
If 'size' is given, the reversal centers around it.
</p>
<div class="spacer"></div>


<!-- float-vector-scale! -->
<pre class="indented">
<em class=def id="fvscale">float-vector-scale!</em> v scl
<em class=emdef>vct-scale!</em> v scl
</pre>

<p>float-vector-scale! multiplies each element of 'v' by 'scl': v[i] *= scl.  It returns 'v'.
</p>
<div class="spacer"></div>


<!-- float-vector-set! -->
<pre class="indented">
<em class=emdef>float-vector-set!</em> v pos val
<em class=emdef>vct-set!</em> v pos val
</pre>

<p>float-vector-set! sets the float-vector 'v' element at 'pos' to 'val': v[pos] = val. 
In Scheme, this is the same as (set! (v pos) val).
</p>
<div class="spacer"></div>


<!-- float-vector-subtract! -->
<pre class="indented">
<em class=def id="fvsubtract">float-vector-subtract!</em> v1 v2
<em class=emdef>vct-subtract!</em> v1 v2
</pre>

<p>float-vector-subtract! performs an element-wise subtract: v1[i] -= v2[i].  It returns 'v1'.
</p>
<div class="spacer"></div>


<!-- float-vector-subseq -->
<pre class="indented">
<em class=def id="fvsubseq">float-vector-subseq</em> v start (end len) nv
<em class=emdef>vct-subseq</em> v start (end len) nv
</pre>

<p>float-vector-subseq returns a new float-vector (or 'nv' if given) with the elements of 'v' between 'start' and 'end' inclusive.  'end' defaults
to the end of 'v'.
</p>
<div class="spacer"></div>


<!-- float-vector+ -->
<pre class="indented">
<em class=def id="fvplus">float-vector+</em> obj1 obj2
<em class=emdef>vct+</em> obj1 obj2
</pre>

<p>float-vector+ combines float-vector-add! and float-vector-offset!, 
depending on the type of its arguments.
</p>
<div class="spacer"></div>


<!-- float-vector* -->
<pre class="indented">
<em class=def id="fvtimes">float-vector*</em> obj1 obj2
<em class=emdef>vct*</em> obj1 obj2
</pre>

<p>float-vector* combines float-vector-multiply! and float-vector-scale!, 
depending on the type of its arguments.
</p>
<div class="spacer"></div>


<!-- float-vector->channel -->
<pre class="indented">
<em class=def id="fvtochannel">float-vector-&gt;channel</em> v (beg 0) dur snd chn edpos origin
<em class=emdef>vct-&gt;channel</em> v (beg 0) dur snd chn edpos origin
</pre>

<p>float-vector-&gt;channel sets the samples from 'beg' to 'beg' + 'dur' from the values in 'v'.
This changes (edits) the channel, so 'origin' provides a way to name the edit (for the edit history list and whatnot).
</p>
<div class="spacer"></div>


<!-- float-vector->list -->
<pre class="indented">
<em class=def id="fvtolist">float-vector-&gt;list</em> v
<em class=emdef>vct-&gt;list</em> v
</pre>

<p>float-vector-&gt;list returns a list with elements of 'v'.
</p>
<div class="spacer"></div>


<!-- float-vector->string -->
<pre class="indented">
<em class=def id="fvtostring">float-vector-&gt;string</em> v
<em class=emdef>vct-&gt;string</em> v
</pre>

<p>float-vector-&gt;string returns a string describing 'v'.
</p>
<div class="spacer"></div>


<!-- vct-&gt;vector -->
<pre class="indented">
<em class=emdef>vct-&gt;vector</em> v
</pre>

<p>vct-&gt;vector returns a vector with the elements of 'v'.
</p>
<div class="spacer"></div>


<!-- vector-&gt;vct -->
<pre class="indented">
<em class=emdef>vector-&gt;vct</em> vect
</pre>

<p>vector-&gt;vct returns a vct with elements of vector 'vect'.
</p>
<div class="spacer"></div>


<p>
In Ruby, vcts partake in the Enumerable and Comparable classes, and have a variety of
additional methods: map, each, &lt;=&gt;, etc.  See vct.c and the Ruby documentation for a complete list.
</p>

<pre class="indented">
:v1
#&lt;vct[len=10]: 0.100 0.100 0.100 3.000 0.100 0.100 0.100 0.100 0.100 0.100&gt;
:v1.find_all {|x| x &gt; 1.0 }
[3.0, 4.0]
:v1.max
4.0
:v2 = make_vct(10, 0.1)
#&lt;vct[len=10]: 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100&gt;
:v2 &lt; v1
true
</pre>





<div class="header" id="extsndlib">Sndlib</div>

<p>All of the underlying sound library (<a href="sndlib.html">Sndlib</a>)
functions are available, as well as most of CLM (<a href="sndclm.html">sndclm.html</a>).
See play.scm.  Much of the mus-audio interface is changing.  In particular, I'm removing the
input side of the audio code.
The most important Sndlib functions for Snd are:
</p>

<!--  SNDLIB TABLE  -->

<div class="spacer"></div>

<!-- mus-alsa-buffers -->
<pre class="indented">
<em class=def id="musalsabuffers">mus-alsa-buffers</em>
</pre>

<p>mus-alsa-buffers is the number of buffers ("periods") used in ALSA; you can also use the environment variable MUS_ALSA_BUFFERS.
The default setting is 3.
These ALSA variables only matter if you built Snd with the configure switch --with-alsa.
</p>
<div class="spacer"></div>


<!-- mus-alsa-buffer-size -->
<pre class="indented">
<em class=def id="musalsabuffersize">mus-alsa-buffer-size</em>
</pre>

<p>mus-alsa-buffer-size is the buffer size used in ALSA. You can also use the environment variable MUS_ALSA_BUFFER_SIZE.
The defaut setting is 1024.
</p>
<div class="spacer"></div>


<!-- mus-alsa-device -->
<pre class="indented">
<em class=def id="musalsadevice">mus-alsa-device</em>
</pre>

<p>This is the ALSA audio device; it defaults to "default". 
The matching environment variable is MUS_ALSA_DEVICE.  If the ALSA "default" device can't be found, we also look
for "plughw:0" and "hw:0".  The "0" is apparently a card number or something.  On my machine where the internal
sound card is worse than useless, I have an EMI 2|6 connected to a USB port.  Its ALSA name seems to be "hw:1"
on a good day.
</p>
<div class="spacer"></div>


<!-- mus-alsa-capture-device -->
<pre class="indented">
<em class=def id="musalsacapturedevice">mus-alsa-capture-device</em>
</pre>

<p>This is the ALSA capture device. The matching environment variable is MUS_ALSA_CAPTURE_DEVICE.
</p>
<div class="spacer"></div>


<!-- mus-alsa-playback-device -->
<pre class="indented">
<em class=def id="musalsaplaybackdevice">mus-alsa-playback-device</em>
</pre>

<p>This is the ALSA audio playback device. The matching environment variable is MUS_ALSA_PLAYBACK_DEVICE.
</p>
<div class="spacer"></div>


<!-- mus-alsa-squelch-warning -->
<pre class="indented">
<em class=def id="musalsasquelchwarning">mus-alsa-squelch-warning</em>
</pre>

<p>Set mus-alsa-squelch-warning to #t to squelch warnings from ALSA about srate mismatches.
</p>
<div class="spacer"></div>


<!-- mus-bytes-per-sample -->
<pre class="indented">
<em class=def id="musbytespersample">mus-bytes-per-sample</em> sample-type
</pre>

<p>mus-bytes-per-sample returns the number of bytes that 'sample-type' uses to encode one sample of sound.
</p>

<pre class="indented">
&gt; (mus-bytes-per-sample mus-bdouble)
8
</pre>
<div class="spacer"></div>


<!-- mus-clipping -->
<pre class="indented">
<em class=def id="musclipping">mus-clipping</em>
</pre>

<p>mus-clipping is the default low-level clipping choice while accessing sound data.
Its default is #f which makes clipping very obvious (it will cause wrap-around).
If you're using the standard Snd file accessors, you probably want to use <a href="#clipping">clipping</a>, not this function.
See also <a href="#cliphook">clip-hook</a>.
</p>
<div class="spacer"></div>


<!-- mus-error-type->string -->
<pre class="indented">
<em class=def id="muserrortypetostring">mus-error-type-&gt;string</em> error
</pre>

<p>mus-error-type-&gt;string returns a brief string description of 'error'
(a mus-error return type).  This is only useful in <a href="#muserrorhook">mus-error-hook</a>, and it's not very useful even there.
</p>
<div class="spacer"></div>


<!-- mus-expand-filename -->
<pre class="indented">
<em class=def id="musexpandfilename">mus-expand-filename</em> name
</pre>

<p>mus-expand-filename fills out the filename 'name' to include its 'absolute' pathname; 
that is, it replaces '~' with the current home directory,
and whatever else seems appropriate.
</p>

<pre class="indented">
&gt; (mus-expand-filename "oboe.snd")
"/home/bil/cl/oboe.snd"
</pre>
<div class="spacer"></div>


<!-- mus-file-clipping -->
<pre class="indented">
<em class=def id="musfileclipping">mus-file-clipping</em> fd
</pre>

<p>This is the clipping choice for the file referred to by 'fd.
The default is #f which makes clipping very obvious (it will cause wrap-around).
See also <a href="#cliphook">clip-hook</a>.
</p>
<div class="spacer"></div>


<!-- mus-header-raw-defaults -->
<pre class="indented">
<em class=def id="musheaderrawdefaults">mus-header-raw-defaults</em>
</pre>

<p>mus-header-raw-defaults returns a list: '(srate chans sample-type), the current raw header defaults.  These can be
set: 
</p>

<pre class="indented">
(set! (<em class=red>mus-header-raw-defaults</em>) (list 22050 4 mus-lint))
</pre>
<div class="spacer"></div>


<!-- mus-header-type-name -->
<pre class="indented">
<em class=def id="musheadertypename">mus-header-type-name</em> type
</pre>

<p>mus-header-type-name converts 'type', an integer, to a string, e.g. "AIFF".  Some of the sndlib header types are:
</p>

<pre class="indented">
mus-next  mus-aifc  mus-riff  mus-rf64 mus-nist  mus-raw  mus-ircam  mus-aiff mus-caff
mus-bicsf mus-soundfont mus-voc mus-svx mus-unsupported
</pre>

<p>This function just decodes a sndlib header type identifier.
</p>

<pre class="indented">
&gt; (mus-header-type-name (mus-sound-header-type "oboe.snd"))
"Sun/Next"
</pre>

<p>The default sound output header choice is <a href="#defaultoutputheadertype">default-output-header-type</a>,
a sound file's
header type is <a href="#mussoundheadertype">mus-sound-header-type</a>, the CLM (<a href="sndscm.html#wsdoc">with-sound</a>) header default
is *clm-header-type*, and an opened sound's header type is <a href="#headertype">header-type</a>. 
</p>
<div class="spacer"></div>

<!-- mus-header-type->string -->
<pre class="indented">
<em class=def id="musheadertypetostring">mus-header-type-&gt;string</em> type
</pre>

<p>mus-header-type-&gt;string converts 'type', an integer, to a string, e.g. "mus-aifc".
</p>
<div class="spacer"></div>


<!-- mus-oss-set-buffers -->
<pre class="indented">
<em class=def id="musosssetbuffers">mus-oss-set-buffers</em> num size
</pre>

<p>In Linux (OSS), this sets the number and size of the OSS fragments.
The default (as of 21-May-01) is to accept whatever OSS chooses: I believe this is normally
equivalent to (mus-oss-set-buffers 16 12).  This default makes the control panel controls very sluggish.  
Snd used to call (mus-oss-set-buffers 4 12) as its default, 
but this seems to cause trouble for a variety of new sound cards.
My initialization file includes (mus-oss-set-buffers 2 12).
</p>
<div class="spacer"></div>


<!-- mus-sample-type-name -->
<pre class="indented">
<em class=def id="mussampletypename">mus-sample-type-name</em> format
</pre>

<p>mus-sample-type-name converts 'format' from an integer to an explanatory string, e.g. "16-bit big endian linear".  
</p>

<pre class="indented">
mus-bshort   mus-lshort   mus-mulaw   mus-alaw   mus-byte  
mus-lfloat   mus-bint     mus-lint    mus-b24int mus-l24int
mus-ubshort  mus-ulshort  mus-ubyte   mus-bfloat mus-bdouble 
mus-ldouble  mus-unknown
</pre>

<p>There are also "unscaled" versions of the floating point types, and "normalized" versions of the integers.
</p>
<div class="spacer"></div>


<!-- mus-sample-type->string -->
<pre class="indented">
<em class=def id="mussampletypetostring">mus-sample-type-&gt;string</em> format
</pre>

<p>mus-sample-type-&gt;string converts 'format' from an integer to a string, e.g. "mus-mulaw".
</p>

<pre class="indented">
&gt; (mus-sample-type-&gt;string mus-bdouble)
"mus-bdouble"
</pre>
<div class="spacer"></div>


<!-- mus-sound-chans -->
<pre class="indented">
<em class=def id="mussoundchans">mus-sound-chans</em> filename
</pre>

<p>This is the number of channels in 'filename'.  This value can be set (as can the others like it mentioned below);
the assignment refers to the table of sound file data maintained by sndlib.  The file itself is not touched, but any
subsequent reference to it in Snd will assume the new value.  In the mus-sound-chans case, say we have a sound file
whose header claims it has 43 channels, but we know it only has 2:
</p>

<pre class="indented">
(set! (<em class=red>mus-sound-chans</em> "43chans.snd") 2)
</pre>

<p>tells Snd that it has 2 channels no matter what the header says.
</p>
<div class="spacer"></div>


<!-- mus-sound-comment -->
<pre class="indented">
<em class=def id="mussoundcomment">mus-sound-comment</em> filename
</pre>

<p>mus-sound-comment returns the comment in the header of the file 'filename'.
</p>

<pre class="indented">
&gt; (with-sound (:comment "this is a comment") (fm-violin 0 1 440 .1))
"test.snd"
&gt; (mus-sound-comment "test.snd")
"this is a comment"
</pre>
<div class="spacer"></div>


<!-- mus-sound-data-location -->
<pre class="indented">
<em class=def id="mussounddatalocation">mus-sound-data-location</em> filename
</pre>

<p>This is the location in bytes of the first sample in the file 'filename'.
</p>
<div class="spacer"></div>


<!-- mus-sound-datum-size -->
<pre class="indented">
<em class=def id="mussounddatumsize">mus-sound-datum-size</em> filename
</pre>

<p>This returns the size in bytes of each sample in 'filename'.  
It is equivalent to (mus-bytes-per-sample (mus-sound-sample-type filename)).
</p>
<div class="spacer"></div>


<!-- mus-sound-duration -->
<pre class="indented">
<em class=def id="mussoundduration">mus-sound-duration</em> filename
</pre>

<p>This returns the duration in seconds of the sound data in the file 'filename'.
</p>

<pre class="indented">
&gt; (mus-sound-duration "oboe.snd")
2.30512475967407
</pre>
<div class="spacer"></div>


<!-- mus-sound-forget -->
<pre class="indented">
<em class=def id="mussoundforget">mus-sound-forget</em> filename
</pre>

<p>mus-sound-forget removes the file 'filename' from the sndlib sound cache.
</p>
<div class="spacer"></div>


<!-- mus-sound-framples -->
<pre class="indented">
<em class=def id="mussoundframples">mus-sound-framples</em> filename
</pre>

<p>mus-sound-framples returns the number of framples of sound data in the file 'filename' according to its header
(this number is occasionally incorrect in mus-next headers).
</p>
<div class="spacer"></div>


<!-- mus-sound-header-type -->
<pre class="indented">
<em class=def id="mussoundheadertype">mus-sound-header-type</em> filename
</pre>

<p>This returns the header type (e.g. mus-aifc) of the file 'filename'.
</p>

<pre class="indented">
&gt; (mus-header-type-&gt;string (mus-sound-header-type "oboe.snd"))
"mus-next"
</pre>
<div class="spacer"></div>


<!-- mus-sound-length -->
<pre class="indented">
<em class=def id="mussoundlength">mus-sound-length</em> filename
</pre>

<p>mus-sound-length returns the number of bytes of sound data in the file 'filename'.
</p>
<div class="spacer"></div>


<!-- mus-sound-loop-info -->
<pre class="indented">
<em class=def id="mussoundloopinfo">mus-sound-loop-info</em> filename
</pre>

<p>This function refers to the "loop" info that is sometimes found in some headers (aifc, wav etc).
<a href="sndscm.html#markloops">mark-loops</a> in examp.scm uses mus-sound-loop-info to place a mark at each loop point.
</p>

<pre class="indented">
&gt; (mus-sound-loop-info "~/sf1/forest.aiff")
(24981 144332 0 0 60 0 1 0)
</pre>

<p>The loop info is a list of
up to 4 points, the first two (start, end = 24981 144332 above) refer to the sustain loop,
and the second two (0 0 above) refer to the release.  
The 5th and 6th list entries are the base note and detune values (60 0 above).
For historical reasons, the 7th and 8th entries are the sustain and release modes (1 0 above).
The <a href="sndclm.html#table-lookup">looper</a> instrument uses this function to implement a sort of "freeze" function.
See also <a href="#soundloopinfo">sound-loop-info</a>.
</p>
<div class="spacer"></div>


<!-- mus-sound-mark-info -->
<pre class="indented">
<em class=def id="mussoundmarkinfo">mus-sound-mark-info</em> filename
</pre>

<p>This function refers to the "mark" info that is sometimes found in aifc and aiff headers.
It returns a list of lists (or an empty list if there are no marks),
each inner list being (mark-id mark-position).  The mark-id is a number that identifies it for
use with mus-sound-loop-info, and the mark-position is its sample number in the file.
Normally, this information is already included in the mus-sound-loop-info list:
</p>

<pre class="indented">
&gt; (mus-sound-mark-info "/home/bil/sf1/forest.aiff")
((4 1) (3 0) (2 144332) (1 24981))
&gt; (mus-sound-loop-info "/home/bil/sf1/forest.aiff")
(24981 144332 0 0 60 0 1 0)
</pre>
<div class="spacer"></div>


<!-- mus-sound-maxamp -->
<pre class="indented">
<em class=def id="mussoundmaxamp">mus-sound-maxamp</em> filename
</pre>

<p>mus-sound-maxamp returns a list of max amps and locations thereof.  The corresponding set! 
affects only the sndlib table of sound file info, not the sound file itself, as in all such cases.
</p>

<pre class="indented">
&gt; (mus-sound-maxamp "oboe.snd")
(24971 0.147247314453125)                  
;; oboe's maxamp is .147 first encountered at sample 24971
&gt; (mus-sound-maxamp "2a.snd")
(933 0.0999755859375 2827 0.0999755859375) 
;; 2a's maxamps are 0.1 in each channel at sample 933 in chan 0, 2827 in chan 1
</pre>
<div class="spacer"></div>


<!-- mus-sound-maxamp-exists? -->
<pre class="indented">
<em class=def id="mussoundmaxampexists">mus-sound-maxamp-exists?</em> filename
</pre>

<p>This function returns #t if the sound's maxamp data is available
in the sound cache; if it isn't, a call on mus-sound-maxamp has to open and read the data to get the maxamp.
</p>

<pre class="indented">
&gt; (mus-sound-maxamp-exists? "/home/bil/test/sound/away.snd")
#f
&gt; (mus-sound-maxamp "/home/bil/test/sound/away.snd")
(14562264 0.463623046875 14557044 0.404571533203125)
&gt; (mus-sound-maxamp-exists? "/home/bil/test/sound/away.snd")
#t
</pre>
<div class="spacer"></div>


<!-- mus-sound-preload -->
<pre class="indented">
<em class=def id="mussoundpreload">mus-sound-preload</em> filename
</pre>

<p>mus-sound-preload loads a sound file into memory, and uses that copy of it thereafter.  If the sound data is
stored in some odd format, and you use that file a lot, this can save some time.
</p>
<div class="spacer"></div>


<!-- mus-sound-prune -->
<pre class="indented">
<em class=def id="mussoundprune">mus-sound-prune</em>
</pre>

<p>mus-sound-prune removes all defunct (non-existent) files from the sound cache.  This is primarily intended for internal testing (snd-test.scm).
</p>
<div class="spacer"></div>


<!-- mus-sound-report-cache -->
<pre class="indented">
<em class=def id="mussoundreportcache">mus-sound-report-cache</em> file
</pre>

<p>This function prints the current sound header data table to the file given or stdout if none is specified.
</p>
<div class="spacer"></div>


<!-- mus-sound-samples -->
<pre class="indented">
<em class=def id="mussoundsamples">mus-sound-samples</em> filename
</pre>

<p>mus-sound-samples returns the number of samples in the sound file 'filename' according to its header.
</p>

<pre class="indented">
&gt; (mus-sound-samples "oboe.snd")
50828
</pre>
<div class="spacer"></div>


<!-- mus-sound-sample-type -->
<pre class="indented">
<em class=def id="mussoundsampletype">mus-sound-sample-type</em> filename
</pre>

<p>mus-sound-sample-type returns the sample type (e.g. mus-bshort) of the file 'filename'.
</p>

<pre class="indented">
&gt; (mus-sample-type-&gt;string (mus-sound-sample-type "oboe.snd"))
"mus-bshort"
</pre>
<div class="spacer"></div>


<!-- mus-sound-srate -->
<pre class="indented">
<em class=def id="mussoundsrate">mus-sound-srate</em> filename
</pre>

<p>mus-sound-srate returns the sampling rate of 'filename'.
</p>
<div class="spacer"></div>


<!-- mus-sound-type-specifier -->
<pre class="indented">
<em class=def id="mussoundtypespecifier">mus-sound-type-specifier</em> filename
</pre>

<p>This is the original type indication of 'filename'.  This is only useful in internal testing.
</p>
<div class="spacer"></div>


<!-- mus-sound-write-date -->
<pre class="indented">
<em class=def id="mussoundwritedate">mus-sound-write-date</em> filename
</pre>

<p>This returns the sound's write date:
</p>

<pre class="indented">
&gt; (strftime "%d-%b %H:%M %Z" (localtime (mus-sound-write-date "oboe.snd")))
"18-Oct 06:56 PDT"
</pre>
<div class="spacer"></div>


<p>See <a href="sndlib.html">Sndlib</a> for more information on these functions. When called from Snd, these
throw 'mus-error upon encountering an error, rather than returning -1 like the underlying sndlib functions.
</p>

<p id="sndinfo">The following function uses the sndlib functions to mimic the 'info' popup menu option 
(see <a href="sndscm.html#exampdoc">examp.scm</a> for a version that uses format):
</p>

<pre class="indented">
(define info 
  (lambda (file)
    (string-append 
     file
     ": chans: " (number-&gt;string (channels file))
     ", srate: " (number-&gt;string (srate file))
     ", " (<a class=quiet href="#musheadertypename">mus-header-type-name</a> (<a class=quiet href="#mussoundheadertype">mus-sound-header-type</a> file))
     ", " (<a class=quiet href="#mussampletypename">mus-sample-type-name</a> (<a class=quiet href="#mussoundsampletype">mus-sound-sample-type</a> file))
     ", len: " (number-&gt;string 
                (/ (<a class=quiet href="#mussoundsamples">mus-sound-samples</a> file) 
                   (channels file) (srate file))))))
</pre>




<div class="header" id="sndmarks">Marks</div>

<p id="markstuff">A mark is an object that refers to a particular sample.
Each mark has an associated sample number (<a class=quiet href="#marksample">mark-sample</a>), 
name (<a class=quiet href="#markname">mark-name</a>), and sync value (<a class=quiet href="#marksync">mark-sync</a>).
See <a href="snd.html#marks">Marks</a> in snd.html
for an overview and key bindings associated with marks.
See also the <a href="#sndhooks">hooks</a> section above for various mark-related hooks.
</p>

<!--  MARKS TABLE  -->
<div class="spacer"></div>


<!-- add-mark -->
<pre class="indented">
<em class=def id="addmark">add-mark</em> sample snd chn name sync
</pre>

<p>add-mark adds a mark at the position 'sample', returning the new mark.
</p>

<pre class="indented">
&gt; (define m1 (add-mark 1234))
m1
&gt; m1
#&lt;mark 0&gt;
&gt; (mark-sample m1)
1234
</pre>

<p>The mark-name can be set via 'name', and the mark-sync field via 'sync'.
If 'sample' is beyond the end of the data, add-mark throws 'no-such-sample.
There is also the form add-mark! which returns #f if the sample number is beyond the current last sample,
rather than throwing the 'no-such-sample error.
</p>
<div class="spacer"></div>


<!-- delete-mark -->
<pre class="indented">
<em class=def id="deletemark">delete-mark</em> mark
</pre>

<p>delete-mark deletes the mark.  Mark additions and deletions follow the
edit list, so if the deleted mark was present in an earlier edit, and you undo to that point,
the mark comes back to life.
</p>
<div class="spacer"></div>


<!-- delete-marks -->
<pre class="indented">
<em class=def id="deletemarks">delete-marks</em> snd chn
</pre>

<p>This function deletes all marks in the given channel.  It could be defined in Scheme as:
</p>

<pre class="indented">
(for-each delete-mark (<a class=quiet href="#emarks">marks</a> (or snd (<a class=quiet href="#selectedsound">selected-sound</a>)) (or chn (<a class=quiet href="#selectedchannel">selected-channel</a>))))
</pre>
<div class="spacer"></div>


<!-- find-mark -->
<pre class="indented">
<em class=def id="findmark">find-mark</em> samp snd chn edpos
</pre>

<p>find-mark returns the mark at sample 'samp' or #f if none is found.
If 'samp' is a string, rather than an integer, find-mark
looks for a mark of that name.  <a href="sndscm.html#marknametoid">mark-name-&gt;id</a>
in marks.scm finds a named mark in any channel (a global version of find-mark).
</p>
<div class="spacer"></div>


<!-- integer->mark -->
<pre class="indented">
<em class=def id="integertomark">integer-&gt;mark</em> i
</pre>

<p>In olden times, a mark was handled in Snd code as an integer; nowadays, it's an object.
Originally I said, "this function, and its companion <a href="#marktointeger">mark-&gt;integer</a>, exist mainly to convert
old code to the current style", but that was premature.  The mark-as-integer approach was handy
because it's easy to type the mark's identifying integer.  I changed from integers to mark objects to
make it possible to treat marks in the various generic functions, but that meant 
that if you forget to save the mark object in some handy variable, 
you end up typing "integer-&gt;mark" over and over.
One way out is to define
a #-reader that sees something like "#m12" and expands that into (integer-&gt;mark 12):
</p>

<pre class="indented">
&gt; (set! <a href="s7.html#sharpreaders">*#readers*</a>
    (cons (cons #\m (lambda (str)
                      (integer-&gt;mark (string-&gt;number (substring str 1)))))
          *#readers*))
((#\m . #&lt;lambda (str)&gt;))
&gt; #m1
#&lt;mark 1&gt;
&gt; (mark-sample #m1)
38694
</pre>
<div class="spacer"></div>


<!-- mark->integer -->
<pre class="indented">
<em class=def id="marktointeger">mark-&gt;integer</em> mark
</pre>

<p>This is the counterpart to <a href="#integertomark">integer-&gt;mark</a>.
</p>
<div class="spacer"></div>


<pre class="indented">
<em class=emdef><a href="#markcolor">mark-color</a></em>
</pre>

<p>This sets the color of mark indicator; the default is red.
<a href="sndscm.html#marksynccolor">mark-sync-color</a> uses mark-color to
display all sync'd marks with some distinctive color.
</p>
<div class="spacer"></div>


<pre class="indented">
<em class=emdef><a href="#markcontext">mark-context</a></em>
</pre>

<p>This is the graphics context to use to draw a mark (XOR mode).
</p>
<div class="spacer"></div>


<!-- mark-home -->
<pre class="indented">
<em class=def id="markhome">mark-home</em> mark
</pre>

<p>mark-home is a list with the sound and channel that hold the mark.
</p>

<pre class="indented">
&gt; (marks 0 0)   ; what marks are in snd 0, chn 0?
(#&lt;mark 0&gt;)            ; just one
&gt; (mark-home (car (marks 0 0))) ; what is that mark's snd/chn?
(#&lt;sound 0&gt; 0)
</pre>
<div class="spacer"></div>


<!-- mark-name -->
<pre class="indented">
<em class=def id="markname">mark-name</em> mark
</pre>

<p>This is the name of the mark.
</p>

<pre class="indented">
&gt; (define m1 (add-mark 1234 0 0 "a name"))
m1
&gt; (mark-name m1)
"a name"
&gt; (set! (mark-name m1) "a new name")
"a new name"
&gt; (mark-name m1)
"a new name"
</pre>
<div class="spacer"></div>


<!-- mark-properties -->
<pre class="indented">
<em class=def id="markproperties">mark-properties</em> mark
</pre>

<p>mark-properties is a property list associated with a mark.
<a href="#markproperty">mark-property</a> reads and writes this list.  
</p>
<div class="spacer"></div>


<!-- mark-property -->
<pre class="indented">
<em class=def id="markproperty">mark-property</em> key mark
</pre>

<p>mark-property accesses the property 'key' in the property list associated with the mark.
</p>

<pre class="indented">
&gt; (set! (mark-property :weight m0) 2.5)   ; m0 is the mark
2.5
&gt; (mark-property :weight m0)
2.5
</pre>
<div class="spacer"></div>


<!-- mark-sample -->
<pre class="indented">
<em class=def id="marksample">mark-sample</em> mark edpos
</pre>

<p>mark-sample is the sample number (a location) marked by the mark at edit history position 'edpos'.
</p>

<pre class="indented">
&gt; (mark-sample m1)
1234
&gt; (set! (mark-sample m1) 4321)
4321
&gt; (mark-sample m1)
4321
</pre>

<p>It might be more consistent with other Snd names to call this mark-position, but I wanted to emphasize
that a mark follows its sample around as a sound is edited; that is, it marks a sample, not a position in the sound.
Say we have three named marks in a speech excerpt (see below), then delete the initial spoken word ("now"); 
each mark backs up with the deletion so that it
continues to point to its original sample:
</p>

<img class="indented" src="pix/mark1.png" alt="marks">
<div class="spacer"></div>


<!-- mark-sync -->
<pre class="indented">
<em class=def id="marksync">mark-sync</em> mark
</pre>

<p>This is the 
mark's sync field (the default is 0).
The sync value 
provides a way to group marks for simultaneous
changes.  Marks that share the same sync value (if not 0), move together when any one of them is
dragged, play together if clicked, etc.  To find which marks share a given
sync value, use <a href="#syncdmarks">syncd-marks</a>; to find an unused sync value use <a href="#marksyncmax">mark-sync-max</a>.
</p>

<p>Marks that are syncd together can be used for insertions, and deletions, and can
set arbitrary groups of play points.  But it's a bit tedious to type (set! (mark-sync ...)...)
for each of the marks you want in the group.  The following code example uses the <a href="#markclickhook">mark-click-hook</a>
instead; you type (start-sync), then click each of the marks that you want grouped together, then (stop-sync).
</p>

<pre class="indented">
(define mark-sync-number 0)
(define (start-sync) (set! mark-sync-number (+ (<a class=quiet href="#marksyncmax">mark-sync-max</a>) 1)))
(define (stop-sync) (set! mark-sync-number 0))
(define (click-to-sync id) (set! (<em class=red>mark-sync</em> id) mark-sync-number) #f)
(hook-push <a class=quiet href="#markclickhook">mark-click-hook</a> click-to-sync)
</pre>

<p>Now control-click and drag one of them, and all of them move together deleting data, or
inserting zeros; or click the "play" triangle, and all of them play together starting from
their respective samples.
</p>
<div class="spacer"></div>


<!-- mark-sync-max -->
<pre class="indented">
<em class=def id="marksyncmax">mark-sync-max</em>
</pre>

<p>This is the maximum mark sync value seen so far.
</p>
<div class="spacer"></div>


<!-- mark-tag-height -->
<pre class="indented">
<em class=def id="marktagheight">mark-tag-height</em>
</pre>

<p>When a mark is drawn, it has a horizontal rectangle at the top, then a vertical line, then a triangle.
The line marks the marked sample, the triangle can be clicked to play from the mark, and the
rectangle can be clicked or dragged.  The mark-tag-height refers to the vertical thickness of that tag
in pixels; its default is 4.
</p>
<div class="spacer"></div>


<!-- mark-tag-width -->
<pre class="indented">
<em class=def id="marktagwidth">mark-tag-width</em>
</pre>

<p>This is the 
mark tag width in pixels; it defaults to 10.
</p>
<div class="spacer"></div>


<!-- marks -->
<pre class="indented">
<em class=def id="emarks">marks</em> snd chn edpos
</pre>

<p>This function returns a list of mark ids in the given channel at the edit history position 'edpos'.
If 'chn' and 'edpos' are omitted, a list of lists is returned, 
each inner list representing a channel of 'snd'.  If 'snd' is 
also omitted, a list of lists of lists is returned, representing
each sound and its channels.
</p>

<pre class="indented">
(define (how-many-marks-in-channel snd chn)
  (length (<em class=red>marks</em> snd chn)))

(define (how-many-marks-in-sound snd)
  (apply + (map length (<em class=red>marks</em> snd))))

(define (how-many-marks)
  (apply + (map how-many-marks-in-sound (<a class=quiet href="#sounds">sounds</a>))))
</pre>

<p>If the marks function is called
without any argument, or with just a sound, it returns a list of lists; each inner list is the list
of current marks active in that channel, ordered by sample number.  If the channel argument is
specified, marks returns just the list of marks.  If the edit history position is given,
the list of marks reflects the marks active at that point in the edit history.  See <a href="sndscm.html#describemark">describe-mark</a> in marks.scm.
</p>

<p>Say we have two sounds open, 2 marks in the first (a mono sound), and one
in the second channel of the second (a stereo sound):
</p>
<pre class="indented">
&gt; (marks 0 0)
(#&lt;mark 1&gt; #&lt;mark 0&gt;)     ; these are mark id's, as returned by the add-mark function for example
&gt; (marks 1)
(() (#&lt;mark 2&gt;))  ; no mark in channel 0, one in channel 1
&gt; (marks)
(((#&lt;mark 1&gt; #&lt;mark 0&gt;)) (() (#&lt;mark 2&gt;)))
</pre>
<div class="spacer"></div>


<!-- mark? -->
<pre class="indented">
<em class=def id="markp">mark?</em> obj
</pre>

<p>mark? returns #t if 'obj' is a mark and is active (that is, if it is present in a currently open channel).
</p>
<div class="spacer"></div>


<!-- save-marks -->
<pre class="indented">
<em class=def id="savemarks">save-marks</em> snd filename
</pre>

<p>save-marks saves the given sound's marks, writing a Scheme, Ruby, or Forth source file named either 'filename' or
&lt;sound's file-name&gt;.marks.  It returns the file name or #f if there are no marks to save.
</p>
<div class="spacer"></div>


<pre class="indented">
<em class=emdef><a href="#showmarks">show-marks</a></em>
</pre>

<p>show-marks is #t if marks are being displayed.
</p>
<div class="spacer"></div>


<!-- syncd-marks -->
<pre class="indented">
<em class=def id="syncdmarks">syncd-marks</em> sync
</pre>

<p>syncd-marks returns a list of marks that share the mark-sync value 'sync'.
</p>

<pre class="indented">
(define (move-syncd-marks sync diff)
  (for-each 
    (lambda (m) 
      (set! (<a class=quiet href="#marksample">mark-sample</a> m) (+ (<a class=quiet href="#marksample">mark-sample</a> m) diff))) 
    (<em class=red>syncd-marks</em> sync)))
</pre>
<div class="spacer"></div>


<!-- INDEX markstuff:Marking -->
<p>
See <a href="sndscm.html#marksdoc">marks.scm</a> for
more examples including:
</p>

<TABLE class="method">
<tr><th class="title"><a class=quiet href="extsnd.html#sndmarks">Marks</a></th></tr><tr><td>
<blockquote><small>
find mark in any sound: <a href="sndscm.html#marknametoid">mark-name-&gt;id</a><br>
mark history: <a href="sndscm.html#describemark">describe-mark</a><br>
synchronize marks by inserting silences: <a href="sndscm.html#syncup">syncup</a><br>
squeeze selection between marks: <a href="sndscm.html#fitselectionbetweenmarks">fit-selection-between-marks</a><br>
insert silence before marks: <a href="sndscm.html#padmarks">pad-marks</a><br>
move syncd marks: <a href="sndscm.html#movesyncdmarks">move-syncd-marks</a><br>
play starting from syncd marks: <a href="sndscm.html#playsyncdmarks">play-syncd-marks</a><br>
place marks at selection start and end: <a href="sndscm.html#snapmarks">snap-marks</a><br>
define selection via marks: <a href="sndscm.html#defineselectionviamarks">define-selection-via-marks</a><br>
force dragged mark to land on a beat: <a href="sndscm.html#snapmarktobeat">snap-mark-to-beat</a><br>
split sound into separate files based on mark placement: <a href="sndscm.html#markexplode">mark-explode</a><br>
mark property lists: <a href="extsnd.html#markproperty">mark-property</a><br>
save mark properties in saved state file: <a href="sndscm.html#savemarkproperties">save-mark-properties</a><br>
show mark properties upon click: <a href="sndscm.html#markclickinfo">mark-click-info</a><br>
</small></blockquote>
</td></tr></TABLE>


<p>Other examples can be found in Dave Phillips' marks-menu.scm, snd-motif.scm (add-mark-pane),
edit-menu.scm (trim from mark, etc), examp.scm (move window to correspond to mark, looping).
</p>



<div class="header" id="sndmixes">Mixes</div>

<p>Mixing operations have a lot of extra support built into Snd.  In nearly every mixing function, you
can request a "mix tag" (or set that request globally via <a href="#withmixtags">with-mix-tags</a>).
If the mix operation is tagged, you can then operate on that data through a number of functions,
the Mix Dialog, various hooks, and various mouse-related actions.
</p>

<p>A mix is an object that represents a channel (one channel in and one channel out) of a sound mix.
Various mixing functions create these objects (mix-float-vector for example).  In the old days, mixes were identified
by integers, so for conversion you can use mix-&gt;integer and integer-&gt;mix.
Say we have a mix object stored in the variable "id":
</p>

<pre class="indented">
&gt; (set! (mix-amp id) .5)
.5
</pre>

<p>This sets the mix's amplitude scaler to .5.  
</p>


<!--  MIX FUNCTION TABLE  -->

<div class="spacer"></div>


<!-- integer->mix -->
<pre class="indented">
<em class=def id="integertomix">integer-&gt;mix</em> i
</pre>

<p>In olden times, a mix was handled in Snd code as an integer; nowadays, it's an object.
This function, and its companion <a href="#mixtointeger">mix-&gt;integer</a>, exist mainly to convert
old code to the current style.
</p>
<div class="spacer"></div>


<!-- mix->integer -->
<pre class="indented">
<em class=def id="mixtointeger">mix-&gt;integer</em> mix
</pre>

<p>This is the counterpart to <a href="#integertomix">integer-&gt;mix</a>.
</p>
<div class="spacer"></div>


<!-- mix -->
<pre class="indented">
<em class=def id="mix">mix</em> file samp in-chan snd chn with-mix-tags auto-delete
</pre>

<p>mix is one of the basic mixing functions.
It mixes the 'in-chan' channel of the file 'file' into the given channel
starting at 'samp' in the output channel, and returns a list with the mix.
If 'in-chan' is #t, all input channels are mixed into successive output channels, and
mix returns a list of the mixes.
</p>

<p>If 'with-mix-tags' is #f (the default is #t), the data is
mixed without creating any mix objects. 
</p>

<pre class="indented">
(mix "test.snd")             ; add channel 0 of test.snd to the current sound at sample 0
(mix "test.snd" 0 #t)        ; same but add all channels of test.snd into successive output channels
(mix "test.snd" 0 1)         ; add channel 1 of test.snd to channel 0 of the current sound
(mix "test.snd" 0 0 #f 1)    ; add channel 0 of test.snd to channel 1 of the current sound
(mix "test.snd" 0 3 #f 1 #f) ; add channel 3 of test.snd to channel 1 of the current sound, without a mix tag
</pre>

<p>
The input file ('file') is not deleted by Snd unless 'auto-delete' is #t (or 1 or 3). 
auto-delete can be a boolean (#f = don't delete), or and integer: 0=don't delete, 1=delete, 3=delete but keep track of multichannel inputs.
</p>

<p>In the next example, we mix in two sounds:
</p>

<img class="indented" src="pix/mix1.png" alt="mixes">

<p>Now we can drag either of the red tags to move the mixed sounds, call up the View:Mixes dialog to edit them,
or use the functions in this section.  For example, we'll set the amplitude of the first and the position of
the second:
</p>

<img class="indented" src="pix/mix2.png" alt="mixes">

<p id="mixmovesound">We can use <a href="sndscm.html#dlocsigdoc">dlocsig</a> in conjunction with mix to move the mixed-in sound:
</p>

<pre class="indented">
(if (not (provided? 'snd-dlocsig.scm)) (load-from-path "dlocsig.scm"))
(if (not (provided? 'snd-ws.scm)) (load-from-path "ws.scm"))

(define (mix-move-sound start-time file path)
  "mix file at start-time in the currently selected sound following the given dlocsig path"
  (let* ((duration (<a class=quiet href="#mussoundduration">mus-sound-duration</a> file))
	 (rd (<a class=quiet href="#makesampler">make-sampler</a> 0 file))
	 (start (<a class=quiet href="sndclm.html#secondstosamples">seconds-&gt;samples</a> start-time))
         (tmp-sound (<a class=quiet href="sndscm.html#sound-let">with-temp-sound</a> (:channels (<a class=quiet href="#channels">channels</a>) :srate (srate file))

         ;; We use with-temp-sound here rather than sound-let because mix normally expects its input file to
         ;; be around until it decides it doesn't need it anymore, but sound-let deletes all its temp files.
         ;; We use with-temp-sound rather than with-sound because the latter would want to open the output
         ;; file in Snd; this could be turned off by including the :to-snd #f argument.

                       (let* ((vals (<em class=red>make-dlocsig</em> :start-time 0
				                  :duration duration
				                  :path path))
		              (dloc (car vals))
		              (beg (cadr vals))
		              (end (caddr vals)))
		         (do ((i beg (+ i 1)))
		             ((= i end))
		           (<em class=red>dlocsig</em> dloc i (<a class=quiet href="#readsample">read-sample</a> rd)))))))

         ;; now tmp-sound is the name of a temp sound file that moves 'file' in a spiral

    (<em class=red>mix</em> tmp-sound start #t #f #f (<a class=quiet href="#withmixtags">with-mix-tags</a>) #t)))

;;; (mix-move-sound 0 "oboe.snd" (make-spiral-path :turns 3))
</pre>
<div class="spacer"></div>


<!-- mixes -->
<pre class="indented">
<em class=def id="mixes">mixes</em> snd chn
</pre>

<p>mixes returns a list of the mix objects associated with the given channel.
If the channel argument is omitted, you get a list of lists, each inner list referring to a single channel of that sound.
If the sound is also omitted, you get a list of lists of lists, the outer list referring to each sound, each
inner list to that sound's channels.  Say we have two sounds open, 2 mixes in the first (a mono sound), and 1 mix
in the second channel of the second (a stereo sound):
</p>

<pre class="indented">
&gt; (mixes 0 0)
(#&lt;mix 0&gt; #&lt;mix 2&gt;)     ; these are mix objects, as returned by the mix function for example
&gt; (mixes 1)
(() (#&lt;mix 1&gt;))  ; no mix in channel 0, one in channel 1
&gt; (mixes)
(((#&lt;mix 0&gt; #&lt;mix 2&gt;)) (() (#&lt;mix 1&gt;)))
</pre>
<div class="spacer"></div>


<!-- mix-amp -->
<pre class="indented">
<em class=def id="mixamp">mix-amp</em> mix
</pre>

<p>mix-amp is the amplitude scaler applied to the mix.  To make mix mx half as loud:
</p>

<pre class="indented">
(set! (mix-amp mx) .5)
</pre>
<div class="spacer"></div>


<!-- mix-amp-env -->
<pre class="indented">
<em class=def id="mixampenv">mix-amp-env</em> mix
</pre>

<p>mix-amp-env is the 
amplitude envelope applied to the mix (a list of breakpoints).  
To reset this to its default (null) state, use #f.
</p>

<pre class="indented">
(set! (mix-amp-env mx) '(0 0 1 1))
</pre> 

<p>sets mix mx's envelope to a ramp.
</p>
<div class="spacer"></div>


<!-- mix-color -->
<pre class="indented">
<em class=def id="mixcolor">mix-color</em> mix
</pre>

<p>This is the color of mix waveforms; it defaults to dark-gray.
If you
want to set just a particular mix's color, pass the mix object 
as the 'mix' argument: (set! (mix-color) red) sets all mix waveforms to
red; but (set! (mix-color mx) red) sets only mix mx's waveform to red.
</p>
<div class="spacer"></div>


<!-- mix-length -->
<pre class="indented">
<em class=def id="mixlength">mix-length</em> mix
</pre>

<p>mix-length returns the mix's length in samples.
</p>
<div class="spacer"></div>


<!-- mix-home-->
<pre class="indented">
<em class=def id="mixhome">mix-home</em> mix
</pre>

<p>mix-home returns a list containing the mix's output sound and channel number, and the input original filename (if any), and input channel.
</p>

<pre class="indented">
&gt; (define mx (mix "pistol.snd" 1000))
(#&lt;mix 0&gt;)
&gt; (mix-home (car mx))
(#&lt;sound 0&gt; 0 "/home/bil/cl/pistol.snd" 0)
;; (list output-sound-index output-channel input-filename input-channel)
&gt; (set! mx (mix-float-vector (make-float-vector 100 .1) 2000))
#&lt;mix 1&gt;
&gt; (mix-home mx)
(#&lt;sound 0&gt; 0 #f 0)
;;   #f: no input file
</pre>
<div class="spacer"></div>


<!-- mix-name -->
<pre class="indented">
<em class=def id="mixname">mix-name</em> mix
</pre>

<p>mix-name is the mix's name, if any.  The mix name is displayed near the mix tag.
See also <a href="sndscm.html#mixnametoid">mix-name-&gt;id</a>.
Here's an example that uses the mix name and the tag location (mix-tag-y) to provide some pitch
feedback:
</p>

<pre class="indented">
(if (not (provided? 'snd-v.scm)) (load-from-path "v.scm"))
(if (not (provided? 'snd-ws.scm)) (load-from-path "ws.scm"))

(define (frequency-&gt;tag-y freq lo octs) ; tag height dependent on freq
  (round (* 100 (- 1.0 (/ (log (/ freq lo)) (* (log 2.0) octs))))))

(let ((violin-sync 1)
      (violin-color (<a class=quiet href="#makecolor">make-color</a> 0 0 1)) ; blue
      (cello-sync 2)
      (cello-color (<a class=quiet href="#makecolor">make-color</a> 0 1 0)) ; green
      (index (<a class=quiet href="#newsound">new-sound</a> "test.snd" :channels 1 :size (* 44100 22))))
  
  (define (violin beg dur freq amp)
    (let ((id (<a class=quiet href="#mix">mix</a> (<a class=quiet href="sndscm.html#withtempsound">with-temp-sound</a> ()                            ; write instrument output to temp sound
   	             (<a class=quiet href="sndscm.html#fmviolin">fm-violin</a> 0 dur (<a class=quiet href="sndscm.html#tofrequency">-&gt;frequency</a> freq #t) amp)) ; our favorite FM instrument
		(<a class=quiet href="sndscm.html#tosample">-&gt;sample</a> beg) 0 index 0  ; mix start, file in-chan, sound, channel
                #t #t)))                  ; mix with tag and auto-delete
      (if (symbol? freq)
	  (set! (<em class=red>mix-name</em> id) (symbol-&gt;string freq)))
      (set! (<a class=quiet href="#mixsync">mix-sync</a> id) violin-sync)
      (set! (<a class=quiet href="#mixcolor">mix-color</a> id) violin-color)
      (set! (<a class=quiet href="#mixtagy">mix-tag-y</a> id) (frequency-&gt;tag-y (<a class=quiet href="sndscm.html#tofrequency">-&gt;frequency</a> freq #t) (<a class=quiet href="sndscm.html#tofrequency">-&gt;frequency</a> 'c2) 3))))
  
  (define (cello beg dur freq amp)
    (let ((id (<a class=quiet href="#mix">mix</a> (<a class=quiet href="sndscm.html#withtempsound">with-temp-sound</a> ()
   	             (<a class=quiet href="sndscm.html#fmviolin">fm-violin</a> 0 dur (<a class=quiet href="sndscm.html#tofrequency">-&gt;frequency</a> freq #t) amp :fm-index 1.5))
                (<a class=quiet href="sndscm.html#tosample">-&gt;sample</a> beg) 0 index 0
  	        #t #t)))
      (if (symbol? freq)
	  (set! (<em class=red>mix-name</em> id) (symbol-&gt;string freq)))
      (set! (<a class=quiet href="#mixsync">mix-sync</a> id) cello-sync)
      (set! (<a class=quiet href="#mixcolor">mix-color</a> id) cello-color)
      (set! (<a class=quiet href="#mixtagy">mix-tag-y</a> id) (frequency-&gt;tag-y (<a class=quiet href="sndscm.html#tofrequency">-&gt;frequency</a> freq #t) (<a class=quiet href="sndscm.html#tofrequency">-&gt;frequency</a> 'c2) 3))))
  
  (<a class=quiet href="#asoneedit">as-one-edit</a>
   (lambda ()
     (violin 0 1 'e4 .2)  (violin 1 1.5 'g4 .2)  (violin 2.5 .5 'g3 .2)
     (cello  0 1 'c3 .2)  (cello  1 1.5 'e3 .2)  (cello  2.5 .5 'g2 .2)
     
     (violin 3 3 'f4 .2)
     (cello  3 3 'd3 .2)
     
     (violin 6 1 'e4 .2)   (violin 7 1 'g3 .2)   (violin 8 1 'e4 .2)
     (cello  6 1 'c3 .2)   (cello  7 1 'g2 .2)   (cello  8 1 'c3 .2)
     
     (violin 9 3 'd4 .2)
     (cello  9 3 'b2 .2))))
</pre>

<img class="indented" src="pix/mixname.png" alt="mix name example">

<p id="waltzexample">But note names are a bother to read; musglyphs.scm has code to display notes using CMN glyphs.
Here we use the draw-mix-hook to display our notes as a score:
</p>

<img class="indented" src="pix/mixcmn.png" alt="mix CMN example">

<p>
In more complex cases, using a mix per note fills the screen with mix tags; it's probably cleaner
to use multiple output files, collecting related notes in one file, then mixing these at the end:
</p>

<pre class="indented">
;; open two output files, one for the violin notes, the other for the cellos
;;   then mix them into "test.snd"

(let ((violins (<a class=quiet href="sndclm.html#make-sampletofile">make-sample-&gt;file</a> "violins.snd" 1 <a class=quiet href="#sampletype">mus-lfloat</a> mus-next))
      (cellos (<a class=quiet href="sndclm.html#make-sampletofile">make-sample-&gt;file</a> "cellos.snd" 1 <a class=quiet href="#sampletype">mus-lfloat</a> mus-next)))

  (define (violin beg dur freq amp)
    (<a class=quiet href="sndscm.html#withtempsound">with-temp-sound</a> (:continue-old-file #t :output "violins.snd") 
      (<a class=quiet href="sndscm.html#fmviolin">fm-violin</a> beg dur (<a class=quiet href="sndscm.html#tofrequency">-&gt;frequency</a> freq #t) amp)))

  (define (cello beg dur freq amp)
    (<a class=quiet href="sndscm.html#withtempsound">with-temp-sound</a> (:continue-old-file #t :output "cellos.snd") 
      (<a class=quiet href="sndscm.html#fmviolin">fm-violin</a> beg dur (<a class=quiet href="sndscm.html#tofrequency">-&gt;frequency</a> freq #t) amp :fm-index 1.5)))

  (violin 0 1 'e4 .2)  (violin 1 1.5 'g4 .2)   (violin 2.5 .5 'g3 .2)
  (cello  0 1 'c3 .2)  (cello  1 1.5 'e3 .2)  (cello  2.5 .5 'g2 .2)
  ;; etc

  (<a class=quiet href="#newsound">new-sound</a> "test.snd" :channels 1) ; our overall output file
  (<a class=quiet href="#mix">mix</a> "violins.snd")
  (<a class=quiet href="#mix">mix</a> "cellos.snd")
  (<a class=quiet href="sndclm.html#mus-close">mus-close</a> violins)
  (<a class=quiet href="sndclm.html#mus-close">mus-close</a> cellos))
</pre>

<p>See also <a href="sndscm.html#withmixedsound">with-mixed-sound</a> in ws.scm.
</p>
<div class="spacer"></div>


<!-- mix-position -->
<pre class="indented">
<em class=def id="mixposition">mix-position</em> mix
</pre>

<p>mix-position is the current starting position (a sample number) of 'mix'.  To move mix mx so that it starts at sample 200 in the output:
</p>

<pre class="indented">
(set! (mix-position mx) 200)
</pre>
<div class="spacer"></div>


<!-- mix-properties -->
<pre class="indented">
<em class=def id="mixproperties">mix-properties</em> mix
</pre>

<p>mix-properties is a property list associated with a mix.
<a href="#mixproperty">mix-property</a> reads and writes this list.  
</p>
<div class="spacer"></div>


<!-- mix-property -->
<pre class="indented">
<em class=def id="mixproperty">mix-property</em> key mix
</pre>

<p>mix-property associates a property with a mix.
</p>

<pre class="indented">
&gt; (set! (mix-property :info mx) "this is a mix")
"this is a mix"
&gt; (mix-property :info mx)
"this is a mix"
</pre>
<div class="spacer"></div>


<!-- mix-region -->
<pre class="indented">
<em class=def id="mixregion">mix-region</em> reg samp snd chn reg-chan
</pre>

<p>mix-region mixes region 'reg's' channel 'reg-chan' into the given channel starting at sample 'samp' ('samp' defaults to the cursor sample).
It returns a list of the new mixes.
</p>
<div class="spacer"></div>


<!-- mix-selection -->
<pre class="indented">
<em class=emdef>mix-selection</em> beg snd chn selection-chan
</pre>

<p>mix-selection mixes the current selection's channel 'selection-cha' into the given channel starting at 'beg', returning a list of the new mixes.
The Edit:Mix selection menu choice is essentially (mix-selection (cursor)).
</p>
<div class="spacer"></div>


<!-- mix-speed -->
<pre class="indented">
<em class=def id="mixspeed">mix-speed</em> mix
</pre>

<p>mix-speed is the speed (resampling ratio) of 'mix'; 1.0 (the default) means no resampling takes place; 
2.0 causes the mix data to be read twice as fast.
</p>
<div class="spacer"></div>


<!-- mix-sync -->
<pre class="indented">
<em class=def id="mixsync">mix-sync</em> mix
</pre>

<p>mix-sync is an integer, like <a href="#sync">sync</a> that you can use to group mixes.  See <a href="sndscm.html#mixdoc">mix.scm</a>
for many examples.  Mix objects that share a non-zero sync value drag together, and are edited together in the mix dialog.
</p>
<div class="spacer"></div>


<!-- mix-sync-max -->
<pre class="indented">
<em class=def id="mixsyncmax">mix-sync-max</em>
</pre>

<p>This is the maximum mix sync value seen so far.
</p>
<div class="spacer"></div>


<!-- mix-tag-height -->
<pre class="indented">
<em class=def id="mixtagheight">mix-tag-height</em>
</pre>

<p>This is the mix tag height (the vertical extent of the tag rectangle) in pixels (the default is 14).  
</p>
<div class="spacer"></div>


<!-- mix-tag-width -->
<pre class="indented">
<em class=def id="mixtagwidth">mix-tag-width</em>
</pre>

<p>This is the mix tag width in pixels (the default is 6).
</p>
<div class="spacer"></div>


<!-- mix-tag-y -->
<pre class="indented">
<em class=def id="mixtagy">mix-tag-y</em> mix
</pre>

<p>This is the mix tag y (vertical) offset; 0 (the default) is the top of the graph, so
higher tag-y values position the tag lower in the graph. For
example, if you know the frequency of the mix sound, you can reflect that in the tag height with:
</p>

<pre class="indented">
(set! (mix-tag-y mix-id) (round (* 100 (- 1.0 (/ (log (/ freq 40.0)) (log 2.0) 7)))))
</pre>

<p>See, for example, check-mix-tags in sndscm.html.
</p>
<div class="spacer"></div>


<!-- mix-float-vector -->
<pre class="indented">
<em class=def id="mixfv">mix-float-vector</em> v beg snd chn with-mix-tags origin
</pre>

<p>mix-float-vector is one of the basic mixing functions. It
mixes the contents of 'v' into the given channel starting at sample 'beg'.
If 'with-mix-tags' is #f (the default is #t), the data is
mixed without creating any mix tags.
mix-float-vector returns the id of the new mix, or -1 (a simple mix, no tag).
</p>
<div class="spacer"></div>


<!-- mix-waveform-height -->
<pre class="indented">
<em class=def id="mixwaveformheight">mix-waveform-height</em>
</pre>

<p>This is the maximum height in pixels of mix waveforms.  The default is 20 (see <a href="#showmixwaveforms">show-mix-waveforms</a>).
</p>
<div class="spacer"></div>


<!-- mix? -->
<pre class="indented">
<em class=def id="mixp">mix?</em> obj
</pre>

<p>mix? returns #t if 'obj' is a mix object and it is accessible in a channel's edit list.
</p>
<div class="spacer"></div>


<!-- save-mix -->
<pre class="indented">
<em class=def id="savemix">save-mix</em> mix filename
</pre>

<p>save-mix saves a given mix's data in the file 'filename'.
</p>
<div class="spacer"></div>


<!-- with-mix-tags -->
<pre class="indented">
<em class=def id="withmixtags">with-mix-tags</em>
</pre>

<p>If with-mix-tags is #f (the default is #t), newly mixed data does not have a mix id or tag associated with it.
</p>


<!-- INDEX sndmixes:Mixing -->

<TABLE class="method">
<tr><th class="title"><a class=quiet href="extsnd.html#sndmixes">Mixing</a></th></tr><tr><td>
<blockquote><small>
mix sound file: <a href="extsnd.html#mix">mix</a> or drag-and-drop it where you want it mixed<br>
mix channel: see <a href="sndscm.html#mixchannel">mix-channel</a> in extensions.scm<br>
mix region: <a href="extsnd.html#mixregion">mix-region</a><br>
mix selection: <a href="extsnd.html#mixselection">mix-selection</a><br>
mix float-vector: <a href="extsnd.html#mixfv">mix-float-vector</a><br>
enveloped mix: see <a href="sndscm.html#envelopedmix">enveloped-mix</a> in extensions.scm<br>
read mix samples: <a href="extsnd.html#makemixsampler">make-mix-sampler</a><br>
mix data maxamp: <a href="sndscm.html#mixmaxamp">mix-maxamp</a><br>
mix data to float-vector: <a href="sndscm.html#mixtofv">mix-&gt;float-vector</a><br>
save mix data in file: <a href="extsnd.html#savemix">save-mix</a><br>
mix property list: <a href="extsnd.html#mixproperty">mix-property</a> in mix.scm<br>
pan mono sound into stereo: see <a href="sndscm.html#placesound">place-sound</a> in examp.scm<br>
move a mixed sound via dlocsig: <a href="extsnd.html#mixmovesound">mix-move-sound</a><br>
the mix dialog: <a href="snd.html#mixdialog">Mix Dialog</a><br>
cross-fade in frequency: cross-fade and dissolve-fade in <a href="sndscm.html#fadedoc">fade.scm</a><br>
zipper cross-fade: <a href="sndscm.html#zipdoc">zipper.scm</a><br>
snap mix to beat after drag: <a href="sndscm.html#snapmixtobeat">snap-mix-to-beat</a><br>
delete all mixes: <a href="sndscm.html#silenceallmixes">silence-all-mixes</a><br>
with-sound (a notelist) expanded into mixes: <a href="sndscm.html#withmixedsound">with-mixed-sound</a><br>
</small></blockquote>
</td></tr></TABLE>




<div class="header" id="sndregions">Regions and Selections</div>

<p id="regionstuff">A region is a saved portion of sound data.  Use the View:Region browser to inspect, edit, and save regions.
As regions are defined, the new ones are pushed on a stack, and if enough regions already
exist, old ones are pushed off (and deleted) to make room.
</p>


<!--  REGION TABLE  -->

<div class="spacer"></div>


<!-- forget-region -->
<pre class="indented">
<em class=def id="forgetregion">forget-region</em> reg
</pre>

<p>forget-region deletes region 'reg', removing it from the region stack.  This does not affect any of the
active sounds; it just tells Snd that you no longer need any access to one of the current regions.
To delete all regions, 
</p>

<pre class="indented">
(for-each <em class=red>forget-region</em> (<a class=quiet href="#eregions">regions</a>))
</pre>

<p>I called this forget-region because delete-region seemed ambiguous, especially given delete-selection.
</p>
<div class="spacer"></div>


<!-- insert-region -->
<pre class="indented">
<em class=def id="insertregion">insert-region</em> reg beg snd chn
</pre>

<p>insert-region inserts region 'reg' at sample 'beg' in the given channel.  The following
function uses insert-region (and other region functions) to rotate the samples in a channel:
</p>

<pre class="indented">
(define* (rotate-channel (samps 1) snd chn)
  (let ((ind (or snd (<a class=quiet href="#selectedsound">selected-sound</a>) (car (<a class=quiet href="#sounds">sounds</a>))))
	(chan (or chn (<a class=quiet href="#selectedchannel">selected-channel</a>) 0)))
    (let ((reg (<em class=red>make-region</em> 0 (- samps 1) ind chan)))
      (<a class=quiet href="#asoneedit">as-one-edit</a>
       (lambda ()
	 (<a class=quiet href="#deletesamples">delete-samples</a> 0 samps ind chan)
	 (<em class=red>insert-region</em> reg (<a class=quiet href="#framples">framples</a> ind chan))))
      (<em class=red>forget-region</em> reg))))
</pre>
<div class="spacer"></div>


<!-- integer->region -->
<pre class="indented">
<em class=def id="integertoregion">integer-&gt;region</em> i
</pre>

<p>In olden times, a region was handled in Snd code as an integer; nowadays, it's an object.
This function, and its companion <a href="#regiontointeger">region-&gt;integer</a>, exist mainly to convert
old code to the current style.
</p>
<div class="spacer"></div>


<!-- make-region -->
<pre class="indented">
<em class=def id="makeregion">make-region</em> beg end snd chn
</pre>

<p>make-region creates a new region spanning the samples 'beg' to 'end' in the given channel.
It returns the new region.  If no arguments are given, the 
current selection is used. If 'chn' is #t, all chans are included, taking the <a class=quiet href="#sync">sync</a> fields into account.
</p>
<div class="spacer"></div>


<!-- make-region-sampler -->
<pre class="indented">
<em class=emdef><a href="#makeregionsampler">make-region-sampler</a></em> reg start chn (dir 1)
</pre>

<p>This creates a <a href="#samplers">sampler</a> reading the region's channel 'chn' starting at sample 'start' within that region.
'dir' can be 1 (read forwards) or -1 (read backwards).
</p>
<div class="spacer"></div>



<!-- mix-region -->
<pre class="indented">
<em class=emdef>mix-region</em> reg samp snd chn
</pre>

<p>mix-region mixes region 'reg' into the given channel starting at sample 'samp' (defaulting to the cursor location).
It returns a list of mixes, one for each channel mixed.
</p>
<div class="spacer"></div>


<!-- region-chans -->
<pre class="indented">
<em class=def id="regionchans">region-chans</em> reg
</pre>

<p>This returns the number of channels in the region 'reg'.
</p>
<div class="spacer"></div>


<!-- region-framples -->
<pre class="indented">
<em class=def id="regionframples">region-framples</em> reg (chan 0)
</pre>

<p>region-framples returns the number of framples in the region 'reg'.
</p>

<pre class="indented">
&gt; (make-region 100 200)
#&lt;region 1&gt;
&gt; (region-framples (integer-&gt;region 1))
101
</pre>
<div class="spacer"></div>


<!-- region-graph-style -->
<pre class="indented">
<em class=def id="regiongraphstyle">region-graph-style</em>
</pre>

<p>region-graph-style is the graph drawing choice for the region dialog's graph.
The choices are:
</p>

<pre class="indented">
graph-lines  graph-dots  graph-filled  graph-lollipops  graph-dots-and-lines 
</pre>

<p>graph-lines is the default.
</p>
<div class="spacer"></div>


<!-- region-home -->
<pre class="indented">
<em class=def id="regionhome">region-home</em> reg
</pre>

<p>This returns a list with the name of the source file for the given region, its start time in the original
data, and its length in framples.
</p>
<div class="spacer"></div>


<!-- region->integer -->
<pre class="indented">
<em class=def id="regiontointeger">region-&gt;integer</em> region
</pre>

<p>This is the counterpart to <a href="#integertoregion">integer-&gt;region</a>.
</p>
<div class="spacer"></div>


<!-- region-maxamp -->
<pre class="indented">
<em class=def id="regionmaxamp">region-maxamp</em> reg
</pre>

<p>region-maxamp is the peak amplitude of the samples in the region 'reg'.
</p>

<pre class="indented">
&gt; (region-maxamp (integer-&gt;region 1))
4.8828125e-4
</pre>
<div class="spacer"></div>


<!-- region-maxamp-position -->
<pre class="indented">
<em class=def id="regionmaxampposition">region-maxamp-position</em> reg
</pre>

<p>region-maxamp-position returns the location (a sample number) of the peak amplitude of the region 'reg'.
</p>
<div class="spacer"></div>


<!-- region-position -->
<pre class="indented">
<em class=def id="regionposition">region-position</em> reg chan
</pre>

<p>region-position returns the begin time of the region's channel 'chan' in the original sound.
</p>

<pre class="indented">
&gt; (make-region 1000 2000)
2
&gt; (region-position (integer-&gt;region 2))
1000
</pre>
<div class="spacer"></div>


<!-- region-sample -->
<pre class="indented">
<em class=def id="regionsample">region-sample</em> reg samp chan
</pre>

<p>region-sample returns the value of the sample 'samp' in channel 'chan' of the region 'reg'.
</p>
<div class="spacer"></div>


<!-- region->float-vector -->
<pre class="indented">
<em class=def id="regiontofv">region-&gt;float-vector</em> reg samp samps chan v
</pre>

<p>region-&gt;float-vector returns a float-vector containing 'samps' samples starting at 'samp' in channel 'chan' of the region 'reg'.
If 'v' (a float-vector) is provided, it is filled, 
rather than creating a new one.
</p>

<pre class="indented">
(define (region-rms n)
  (let* ((data (<em class=red>region-&gt;float-vector</em> (integer-&gt;region 0) 0 #f n))
	 (len (length data)))
    (sqrt (/ (<a class=quiet href="sndclm.html#dot-product">dot-product</a> data data len) len))))
</pre>
<div class="spacer"></div>


<!-- region-srate -->
<pre class="indented">
<em class=def id="regionsrate">region-srate</em> reg
</pre>

<p>region-srate returns the sampling rate of the data that makes up the region 'reg'.
</p>
<div class="spacer"></div>


<!-- regions -->
<pre class="indented">
<em class=def id="eregions">regions</em>
</pre>

<p>regions returns a list of active regions.  The most recently created region is (car (regions)).
(map region-framples (regions)) returns a list of region lengths.
The maximum length of this list is set by <a href="#maxregions">max-regions</a>.
</p>
<div class="spacer"></div>


<!-- region? -->
<pre class="indented">
<em class=def id="regionok">region?</em> reg
</pre>

<p>region? returns #t if the region 'reg' exists.  There is a limit to how many regions Snd tries to
keep track of (<a href="#maxregions">max-regions</a>); when necessary, the least-recently created region is
deleted.
</p>
<div class="spacer"></div>


<!-- save-region -->
<pre class="indented">
<em class=def id="saveregion">save-region</em> reg :file :sample-type :header-type :comment
</pre>

<p>save-region saves the region 'reg' in 'file' in the given sample type and header type.
It returns the output filename.  
The following calls are equivalent:
</p>

<pre class="indented">
(save-region reg "reg0.snd")
(save-region reg :file "reg0.snd" :header-type mus-next)
(save-region reg "reg0.snd" <a class=quiet href="#sampletype">mus-bfloat</a> mus-next "a comment")
(save-region reg :file "reg0.snd" :comment "a comment" :sample-type <a class=quiet href="#sampletype">mus-bfloat</a>)
</pre>


<!-- INDEX regionstuff:Regions -->

<TABLE class="method">
<tr><th class="title"><a class=quiet href="extsnd.html#sndregions">Regions</a></th></tr><tr><td>
<blockquote><small>
Max length of region list: <a href="extsnd.html#maxregions">max-regions</a><br>
Whether selection creates a region: <a href="extsnd.html#selectioncreatesregion">selection-creates-region</a><br>
To play region repeatedly: <a href="sndscm.html#playregionforever">play-region-forever</a><br>
Start region browser from Scheme: <a href="extsnd.html#viewregionsdialog">view-regions-dialog</a><br>
All about regions: <a href="snd.html#regions">regions</a><br>
The region dialog: <a href="snd.html#regionbrowser">region browser</a><br>
Region rms amp: <a href="sndscm.html#regionrms">region-rms</a><br>
region-play-list and region-play-sequence in examp.scm<br>
</small></blockquote>
</td></tr></TABLE>



<!--  SELECTION TABLE  -->
<div class="spacer"></div>


<!-- convolve-selection-with -->
<pre class="indented">
<em class=def id="convolveselectionwith">convolve-selection-with</em> file amp
</pre>

<p id="selectionstuff">convolve-selection-with convolves the current selection with 'file', replacing the selection with the result.
'amp' sets the maxamp of the result.
</p>
<div class="spacer"></div>


<!-- delete-selection -->
<pre class="indented">
<em class=def id="deleteselection">delete-selection</em>
</pre>

<p>delete-selection deletes the selection, equivalent to the Edit:Delete selection menu choice.
</p>
<div class="spacer"></div>


<!-- delete-selection-and-smooth -->
<pre class="indented">
<em class=def id="deleteselectionandsmooth">delete-selection-and-smooth</em>
</pre>

<p>delete-selection-and-smooth deletes the selection, then tries to make the splice smooth.
</p>
<div class="spacer"></div>


<!-- env-selection -->
<pre class="indented">
<em class=def id="envselection">env-selection</em> envelope env-base
</pre>

<p>env-selection applies 'envelope' to the selection. (as an amplitude envelope).
'envelope' can also be a CLM env generator; in this case, 'env-base' is ignored.
These are equivalent:
</p>

<pre class="indented">
(env-selection '(0 0 1 1 2 0))
(env-selection (<a class=quiet href="sndclm.html#make-env">make-env</a> '(0 0 1 1 2 0) :length (<a class=quiet href="#selectionframples">selection-framples</a>)))
</pre>
<div class="spacer"></div>


<!-- filter-selection -->
<pre class="indented">
<em class=def id="filterselection">filter-selection</em> env order truncate
</pre>

<p>filter-selection applies an FIR filter of order 'order' and frequency response 'env'
to the selection.  'env' can be the filter coefficients
themselves in a float-vector with at least 'order' elements, or 
a CLM filtering generator (see <a href="#filtersound">filter-sound</a>).
If 'truncate' is #t (the default), the filter output is truncated at the selection
end.  If 'truncate' is #f, the extra output ('order' samples worth) is mixed into the stuff following the selection.
</p>
<div class="spacer"></div>


<!-- insert-selection -->
<pre class="indented">
<em class=def id="insertselection">insert-selection</em> beg snd chn
</pre>

<p>insert-selection inserts a copy of the selection starting at 'beg' in the given channel (that is, it pastes in the selection
as a block).
The Edit:Insert selection menu choice is essentially (insert-selection (cursor)).
</p>
<div class="spacer"></div>


<!-- mix-selection -->
<pre class="indented">
<em class=def id="mixselection">mix-selection</em> beg snd chn selection-channel
</pre>

<p>mix-selection mixes (adds) a copy of the selection starting at 'beg' in the given channel, and returns a list of the new mixes.
The Edit:Mix selection menu choice is (mix-selection (cursor)).
</p>
<div class="spacer"></div>


<!-- reverse-selection -->
<pre class="indented">
<em class=def id="reverseselection">reverse-selection</em>
</pre>

<p>reverse-selection reverses the selection.
</p>
<div class="spacer"></div>


<!-- save-selection -->
<pre class="indented">
<em class=def id="saveselection">save-selection</em> :file :srate :sample-type (:header-type mus-next) :comment :channel
</pre>

<p id="extractchannels">save-selection saves the selection in 'file'.  If 'channel' is given, it saves only that channel.
</p>

<pre class="indented">
(define brksnd
  (let ((+documentation+ "(brksnd dur base) divides the current sound into dur-sized pieces, 
saving them in files named 'base'.n: (brksnd 1.0 \"sec\")"))
    (lambda (dur base)
      (let ((hop (floor (* (<a class=quiet href="#srate">srate</a>) dur)))
	    (len (<a class=quiet href="#framples">framples</a>)))
        (let-temporarily (((sync) 1))          ; save all chans
          (do ((i 0 (+ i hop))
	       (j 0 (+ j 1)))
	      ((&gt;= i len))
            (<a class=quiet href="sndscm.html#makeselection">make-selection</a> i (+ i hop)) ; in extensions.scm
            (<em class=red>save-selection</em> (string-append base "." (number-&gt;string j)))))))))
</pre>

<pre class="indented">
(define* (extract-channels :rest chans)
  ;; extract a list of channels from the current sound and save as test.snd: (extract-channels 0 2)
  (let ((snd (or (<a class=quiet href="#selectedsound">selected-sound</a>) (car (<a class=quiet href="#sounds">sounds</a>)))))
    (if (<a class=quiet href="#soundp">sound?</a> snd)
	(begin
	  (for-each
	   (lambda (chan)
	     (set! (<a class=quiet href="#selectionmember">selection-member?</a> snd chan) #t)
	     (set! (<a class=quiet href="#selectionposition">selection-position</a> snd chan) 0)
	     (set! (<a class=quiet href="#selectionframples">selection-framples</a> snd chan) (<a class=quiet href="#framples">framples</a> snd chan)))
	   chans)
	  (<em class=red>save-selection</em> "test.snd")))))
</pre>
<div class="spacer"></div>


<!-- scale-selection-by -->
<pre class="indented">
<em class=def id="scaleselectionby">scale-selection-by</em> scalers
</pre>

<p>scale-selection-by scales (multiplies) the selection by 'scalers' which can be either a float, 
a list of floats, or a float-vector.  In a multichannel selection, each member of the float-vector or list
is applied to the next channel in the selection.  (scale-selection-by '(0.0 2.0)) scales
the first channel by 0.0, the second (if any) by 2.0.  (scale-selection-by 2.0) scales
all channels by 2.0.  Normally the order of channels follows the order of the sounds.
</p>
<div class="spacer"></div>


<!-- scale-selection-to -->
<pre class="indented">
<em class=def id="scaleselectionto">scale-selection-to</em> norms
</pre>

<p>scale-selection-to normalizes the selection to peak amplitude 'norms' which can be either a float, 
a list of floats, or a float-vector.
</p>
<div class="spacer"></div>


<!-- select-all -->
<pre class="indented">
<em class=def id="selectall">select-all</em> snd chn
</pre>

<p>This function selects all samples in the given channel.
If a region is created, it returns the new region.
</p>
<div class="spacer"></div>


<!-- selection -->
<pre class="indented">
<em class=def id="selection">selection</em>
</pre>

<p>selection returns an object representing the current selection, or #f if there is no active selection.
The object can be passed to the <a href="#sndgenericfuncs">generic functions</a> to refer to the
current selection:
</p>

<pre class="indented">
&gt; (define selobj (selection))
selobj
&gt; selobj
#&lt;selection 1&gt;
&gt; (selection-chans)
1
&gt; (channels selobj)
1
</pre>
<div class="spacer"></div>


<!-- selection-chans -->
<pre class="indented">
<em class=def id="selectionchans">selection-chans</em>
</pre>

<p>selection-chans returns the number of channels in the current selection.
</p>
<div class="spacer"></div>


<!-- selection-framples -->
<pre class="indented">
<em class=def id="selectionframples">selection-framples</em> snd chn
</pre>

<p>selection-framples returns the number of framples in the current selection (its length in samples).  
You can set this to move the selection end point:
</p>

<pre class="indented">
&gt; (select-all)                    ; grab all of current channel
#&lt;region 1&gt;
&gt; (selection-framples)
55240
&gt; (set! (selection-framples) 10000) ; unselect all but the starting 10000
10000
&gt; (selection-framples)
10000
&gt; (set! (selection-framples) (* 2 (selection-framples))) ; double the selection length
20000
</pre>

<p>See also <a href="sndscm.html#makeselection">make-selection</a>.
</p>
<div class="spacer"></div>


<!-- selection-maxamp -->
<pre class="indented">
<em class=def id="selectionmaxamp">selection-maxamp</em> snd chn
</pre>

<p>selection-maxamp returns the peak amplitude of the selection in the given channel.
If no arguments are passed, selection-maxamp returns the overall selection maxamp.
I use this to provide a view of the selection amplitude envelope in the envelope editor.  If you select
'selection' and 'wave' in that dialog, it displays a copy of whatever is in the main channel graph,
so to get a display that makes it easy to "connect the dots", I use C-x m:
</p>

<pre class="indented">
(<a class=quiet href="#bindkey">bind-key</a> #\m 0
  (lambda ()
    (set! (<a class=quiet href="#ybounds">y-bounds</a> (<a class=quiet href="#selectedsound">selected-sound</a>) (<a class=quiet href="#selectedchannel">selected-channel</a>)) (list 0 (<em class=red>selection-maxamp</em>))))
    #t)

(<a class=quiet href="#bindkey">bind-key</a> #\m 4
  (lambda ()
    (set! (<a class=quiet href="#ybounds">y-bounds</a> (<a class=quiet href="#selectedsound">selected-sound</a>) (<a class=quiet href="#selectedchannel">selected-channel</a>)) (list -1.0 1.0)))
    #t)
</pre>

<p>The second key binding (C-x C-m), undoes the previous C-x m.  Another useful key binding in this regard is C-x v, the
built-in command to fill the current window with the selection.
</p>
<div class="spacer"></div>


<!-- selection-maxamp-position -->
<pre class="indented">
<em class=def id="selectionmaxampposition">selection-maxamp-position</em> snd chn
</pre>

<p>selection-maxamp-position returns the location (a sample number) of the peak amplitude of the selection in the given channel.
</p>
<div class="spacer"></div>


<!-- selection-member? -->
<pre class="indented">
<em class=def id="selectionmember">selection-member?</em> snd chn
</pre>

<p>selection-member? returns #t if the given channel has data that is currently selected.
This is mostly useful when adding a channel to the current selection; see
<a href="sndscm.html#makeselection">make-selection</a> in extensions.scm.
If 'snd' is #t and the new value is #f, the entire selection is deactivated.
</p>

<pre class="indented">
(set! (<em class=red>selection-member?</em> #t) #f)
</pre>

<p>i.e. equivalent to unselect-all.
</p>
<div class="spacer"></div>


<!-- selection->mix -->
<pre class="indented">
<em class=def id="selectiontomix">selection-&gt;mix</em>
</pre>

<p>selection-&gt;mix turns the current selection into a mix, or into several sync'd mixes if the selection
has more than one channel.
</p>
<div class="spacer"></div>


<!-- selection-position -->
<pre class="indented">
<em class=def id="selectionposition">selection-position</em> snd chn
</pre>

<p>selection-position is the sample where selection begins. 
You can set this to move the selection's starting point to some arbitrary sample.
If changed, the selection end point stays the same, while the length (<a class=quiet href="#selectionframples">selection-framples</a>) changes to reflect the
moved origin. 
See <a href="sndscm.html#makeselection">make-selection</a> in extensions.scm.
</p>
<div class="spacer"></div>


<!-- selection-srate -->
<pre class="indented">
<em class=def id="selectionsrate">selection-srate</em>
</pre>

<p>This function returns the selection srate.  There's some arbitrariness in this if the sounds that make up the selection have different sampling rates.
</p>
<div class="spacer"></div>


<!-- selection? -->
<pre class="indented">
<em class=def id="selectionok">selection?</em> obj
</pre>

<p>selection? returns #t if there is a selection.
If some 'obj' is passed, selection? returns #t is obj is a selection object, and there is a selection.
</p>

<pre class="indented">
&gt; (select-all)
#&lt;region 2&gt;
&gt; (selection?)
#t
&gt; (set! (selection-member? #t) #f)
#f
&gt; (selection?)
#f
</pre>
<div class="spacer"></div>


<!-- show-selection -->
<pre class="indented">
<em class=def id="showselection">show-selection</em>
</pre>

<p>show-selection finds the bounds of the current selection (in all channels), and 
sets the time domain view to show it.
</p>
<div class="spacer"></div>


<!-- smooth-selection -->
<pre class="indented">
<em class=def id="smoothselection">smooth-selection</em>
</pre>

<p>smooth-selection applies a smoothing function to the selection, producing a sinusoid between
the selection end points.  In normal use, you'd bind this function to some key,
select a portion (say a few samples) of a sound around a click,
then smooth it by typing that key.
</p>
<div class="spacer"></div>


<!-- src-selection -->
<pre class="indented">
<em class=def id="srcsoundselection">src-selection</em> num-or-env base
</pre>

<p>src-selection applies sampling rate conversion to the selection;
this is the same as src-sound but as applied to the selection.
</p>
<div class="spacer"></div>


<!-- unselect-all -->
<pre class="indented">
<em class=def id="unselectall">unselect-all</em>
</pre>

<p>If there is currently a selection, this deactivates (unselects) it.
</p>


<!-- INDEX selectionstuff:Selections -->

<TABLE class="method">
<tr><th class="title"><a class=quiet href="extsnd.html#sndregions">Selections</a></th></tr><tr><td>
<blockquote><small>
show the current selection: <a href="extsnd.html#showselection">show-selection</a><br>
color of selected portion: <a href="extsnd.html#selectioncolor">selection-color</a><br>
set whether creating a selection creates a region: <a href="extsnd.html#selectioncreatesregion">selection-creates-region</a><br>
fft graph refers to the selection: <a href="extsnd.html#showselectiontransform">show-selection-transform</a><br>
hook called when selection stops playing: <a href="extsnd.html#stopplayingselectionhook">stop-playing-selection-hook</a><br>
swap chans in selected portion: <a href="sndscm.html#swapselectionchannels">swap-selection-channels</a><br>
replace portion with selection: <a href="sndscm.html#replacewithselection">replace-with-selection</a><br>
select portion via function: <a href="sndscm.html#makeselection">make-selection</a><br>
selection members as list of lists of sound indices and channels: <a href="sndscm.html#selectionmembers">selection-members</a><br>
rms of selection data: <a href="sndscm.html#selectionrms">selection-rms</a><br>
delete selection and smooth the splice: <a href="extsnd.html#deleteselectionandsmooth">delete-selection-and-smooth</a><br>
select portion between two marks: <a href="sndscm.html#defineselectionviamarks">define-selection-via-marks</a><br>
place marks at selection start and end: <a href="sndscm.html#snapmarks">snap-marks</a><br>
squeeze selection between marks: <a href="sndscm.html#fitselectionbetweenmarks">fit-selection-between-marks</a><br>
delete selection and write it to a file: <a href="sndscm.html#menusdoc">cut-selection-&gt;new</a><br>
append selection: <a href="sndscm.html#menusdoc">append-selection</a><br>
write selection to a file: <a href="sndscm.html#menusdoc">selection-&gt;new</a><br>
notch filter selection: <a href="sndscm.html#notchselection">notch-selection</a><br>
undo select-all.: <a href="sndscm.html#menusdoc">deselect-all</a><br>
filter the selection: <a href="extsnd.html#filterselection">filter-selection</a>, <a href="sndscm.html#filterselectionandsmooth">filter-selection-and-smooth</a><br>
turn the selection into a mix: <a href="extsnd.html#selectiontomix">selection-&gt;mix</a><br>
unselect everything: <a href="extsnd.html#unselectall">unselect-all</a><br>
</small></blockquote>
</td></tr></TABLE>

<p>The selected portion can be chosen, independent of any region, by setting selection-position and selection-framples.
It's easy to extend the notion of a selection to an arbitrary list of sound portions:
</p>

<pre class="indented">
(define (make-section . members)
  ;; each member is '(beg dur snd chn)
  (cons 'Section members))

(define (section-for-each func section)
  ;; call func on each member of the section
  (<a class=quiet href="#asoneedit">as-one-edit</a> (lambda () (for-each func (cdr section)))))

;; an example that scales each member of the section by .5
(section-for-each 
 (lambda (sect)
   (apply <a class=quiet href="#scalechannel">scale-channel</a> (cons .5 sect)))
 (make-section (list 0 10000 0 0) (list 30000 10000 0 0)))
</pre>



<div class="header" id="sndsounds">Sounds and channels</div>

<p>This is the heart of Snd; we've waded through all the ancillary junk, and we've
finally reached the functions that actually edit sounds!  Most of these functions
take both a sound and a channel number.  When the function refers to a variable
that can be set locally on a sound (zero-pad, for example), 
the 'snd' and 'chn' arguments can be #t, referring to all current sounds or all channels of a sound.
In cases where it makes sense, if the 'snd' argument is omitted, the
reference is to the global default value.  So, (set! (amp-control-bounds) '(0.0 2.0))
sets the global amp control (slider) bounds to be between 0.0 and 2.0, whereas
(set! (amp-control-bounds snd) '(0.0 2.0)) sets it only for the sound referred to by 'snd'.
</p>

<p id="currenteditposition">Many of the procedures also have an 'edpos' argument (standing for "edit position").
It always defaults to the current edit history position.  If specified, it can be either an edit history position (to which
the operation is applied), or the constant current-edit-position.
</p>

<p id="regularizedargs">
For not-very-good historical reasons (it took me awhile to decide how to organize things), some of the procedures here are unnecessarily inconsistent in
what arguments they accept, whether a channel of #t signals application to all channels or just the
selected one, whether the <a class=quiet href="#sync">sync</a> field is followed, and so on.  Rather than make a bunch of backwards
incompatible changes, I decided to add a bunch of more-or-less synonymous functions that regularize
these calls. The replacements always take arguments in the order begin time, duration (not end sample),
sound, channel number, and edit position, possibly preceded by one argument, and sometimes followed by 
an edit history name or 'ring time' (overlap).  The <a class=quiet href="#sync">sync</a> field is ignored, an unspecified sound argument applies only to the
current sound, and an unspecified channel argument applies only to the current channel. 
The following substitutions can be made:
</p>

<pre class="indented">
<a href="#convolvewith">convolve-with</a> file amp s c e                    <a href="#clmchannel">clm-channel</a> convolve-gen beg dur s c e
<a href="#envsound">env-sound</a> env beg dur base s c e                <a href="#envchannel">env-channel</a> env beg dur s c e
<a href="#filtersound">filter-sound</a> env order s c e                    <a href="#filterchannel">filter-channel</a> env order beg dur s c e trunc
<a href="#insertsilence">insert-silence</a> beg dur s c                      <a href="#padchannel">pad-channel</a> beg dur s c e
<a href="#insertsound">insert-sound</a> file beg filechn s c e             <a href="sndscm.html#insertchannel">insert-channel</a> filedat beg dur s c e
<a href="#mix">mix</a> file beg filechn s c with-tags              <a href="sndscm.html#mixchannel">mix-channel</a> filedat beg dur s c e
<a href="#redo">redo</a> edits s c                                  <a href="#redochannel">redo-channel</a> edits s c
<a href="#reversesound">reverse-sound</a> s c e                             <a href="#reversechannel">reverse-channel</a> beg dur s c e
<A href="#scaleby">scale-by</A> scls s c                               <a href="#scalechannel">scale-channel</a> scl beg dur s c e
<A href="#scaleto">scale-to</A> scls s c                               <a href="#normalizechannel">normalize-channel</a> norm beg dur s c e
<a href="#setsamples">set-samples</a> beg dur data s c trunc origin fchan <a href="#fvtochannel">float-vector-&gt;channel</a> v beg dur s c e
<a href="#smoothsound">smooth-sound</a> beg dur s c                        <a href="#smoothchannel">smooth-channel</a> beg dur s c e
<a href="#srcsound">src-sound</a> num base s c e                        <a href="#srcchannel">src-channel</a> ratio-or-env beg dur s c e
<a href="#undo">undo</a> edits s c                                  <a href="#undochannel">undo-channel</a> edits s c
<a href="grfsnd.html#applyladspa">apply-ladspa</a> reader dat dur origin snd chn      <a href="grfsnd.html#ladspachannel">ladspa-channel</a> dat beg dur s c e
</pre>

<p>Another case that might deserve "regularization" is <a class=quiet href="#makesampler">make-sampler</a> which confusingly interpolates
the direction argument between the channel and edit-position:
</p>

<pre class="indented">
(define* (read-channel (beg 0) snd chn edpos (direction 1))
  (<a class=quiet href="#makesampler">make-sampler</a> beg snd chn direction edpos))
</pre>

<p>
The edit position argument can cause ambiguity in a few cases.  What should Snd do with:
(pad-channel 100 0 snd chn 2)?
It currently treats any 0-length operation as a no-op, so the edit history is not changed by this function call.
However, in a similar situation (where the current edit counter is greater than 2, so this code is reaching
back into the edit history list): (scale-channel 1.0 0 #f snd chn 2)
Snd essentially copies the state of the channel at that edit position, and puts it in the current edit position.
There's never any good reason to do this, so if it looks like a no-op, do it a different way.
</p>


<!--  SOUND AND CHANNEL TABLE  -->
<div class="separator"></div>


<!-- add-player -->
<pre class="indented">
<em class=def id="addplayer">add-player</em> player start end edpos stop-proc out-chan
</pre>

<p>add-player adds 'player' to the play-list (see <a href="#makeplayer">make-player</a>). 
If 'edpos' is given, play at that edit position. 
'stop-proc' can be a procedure of one argument; it is called when the play process stops and passed
the reason the play is stopping; it will be 0 if the play completed normally (the other possibilities
are listed <a href="#stopplayreasons">here</a>, but they really aren't interesting).
The 'out-chan' argument is the audio output channel to send the data to; it defaults to
the channel number of the player's channel in the containing sound (that is, the default is to
send channel 1 data to channel 1 of the DAC, and so on).
See play-with-envs in enved.scm, play-syncd-marks in marks.scm, or start-dac in play.scm.
</p>
<div class="separator"></div>


<!-- axis-info -->
<pre class="indented">
<em class=def id="axisinfo">axis-info</em> snd chn grf
</pre>

<p>axis-info returns a list describing the specified axis:
</p>

<pre class="indented">
(list left-sample right-sample 
      x0 y0 x1 y1 x-min y-min x-max y-max 
      x0-position y0-position x1-position y1-position y-offset 
      xlabel ylabel new-peaks)
</pre>
<p>This can be
useful if you're drawing arbitrary figures in a graph.  'grf' defaults to
time-graph; the other choices are transform-graph and lisp-graph.  
'x0' is the time in seconds corresponding to the left-sample (the left edge of the graph).
Similarly 'y0' is the lower y axis limit as a sample value (i.e. -1.0).
'x-max' is the sound's duration in seconds ('x-min' is always 0.0).
The "positions" are pixel values, in drawing area coordinates; these give the position
of the graph in the drawing area.  'y-offset' refers to "united" graphs where
several channels share one drawing area.  You can use it to translate mouse coordinates
to channel number in that situation.
For example, <a href="#xtoposition">x-&gt;position</a>
could be:
</p>

<pre class="indented">
(define (x-&gt;position-1 x snd chn)
  (let* ((axinfo (<em class=red>axis-info</em> snd chn <a class=quiet>time-graph</a>))
	 (x0 (axinfo 2))
	 (x1 (axinfo 4))
	 (axis-left (axinfo 10))
	 (axis-right (axinfo 12)))
    (floor
     (+ axis-left
	(* (- x x0) 
	   (/ (- axis-right axis-left)
	      (- x1 x0)))))))
</pre>

<p>Here's a key binding that uses axis-info to save every channel's graph position upon "Page Down",
then restore that state upon "Page Up":
</p>

<pre class="indented">
(<a class=quiet href="#bindkey">bind-key</a> "Page_Down" 0 
	  (lambda ()
	    (let ((last-page-state 
	            (map (lambda (snd) 
			   (let ((data (list snd (<a class=quiet href="#filename">file-name</a> snd))))
			     (do ((i 0 (+ i 1)))
 				 ((= i (<a class=quiet href="#channels">channels</a> snd)) data)
			       (set! data (append data (list (cons i (<em class=red>axis-info</em> snd i))))))))
		         (<a class=quiet href="#sounds">sounds</a>))))
	      (<a class=quiet href="#bindkey">bind-key</a> "Page_Up" 0
			(lambda ()
			  (for-each
			    (lambda (lst)
			      (let ((snd (lst 0))
				    (name (lst 1)))
				(if (and (<a class=quiet href="#soundp">sound?</a> snd) 
				         (string=? (<a class=quiet href="#filename">file-name</a> snd) name))
				    (for-each
				      (lambda (chan-data)
				        (let ((chn (chan-data 0))
					      (x0 (chan-data 3))
					      (x1 (chan-data 5))
					      (y0 (chan-data 4))
					      (y1 (chan-data 6)))
					  (set! (<a class=quiet href="#xbounds">x-bounds</a> snd chn) (list x0 x1))
					  (set! (<a class=quiet href="#ybounds">y-bounds</a> snd chn) (list y0 y1))))
				      (cddr lst)))))
			       last-page-state))))))
</pre>
<div class="separator"></div>


<!-- beats-per-measure -->
<pre class="indented">
<em class=def id="beatspermeasure">beats-per-measure</em> snd chn
</pre>

<p>The x axis labelling of the time domain waveform can be in measures
(<a class=quiet href="#xaxisstyle">x-axis-style</a> = x-axis-in-measures); this variable sets the number of beats per measure.
The default is 4.
</p>
<div class="separator"></div>


<!-- beats-per-minute -->
<pre class="indented">
<em class=def id="beatsperminute">beats-per-minute</em> snd chn
</pre>

<p>The x axis labelling of the time domain waveform can be in beats
(<a class=quiet href="#xaxisstyle">x-axis-style</a> = x-axis-in-beats) or in measures 
(x-axis-in-measures); this variable sets the number of beats per minute.
The default is 60.0, making it the same as x-axis-in-seconds.  
See <a href="#snpmark">snap-mark-to-beat</a>, or <a href="sndscm.html#snapmixtobeat">snap-mix-to-beat</a>.
</p>
<div class="separator"></div>


<!-- channel-amp-envs -->
<pre class="indented">
<em class=def id="channelampenvs">channel-amp-envs</em> file chan size peak-file-func work-proc-func
</pre>

<p>channel-amp-envs returns two float-vectors of length 'size' containing the peak-amp envelopes of the channel 'chan' of file 'file'.
'peak-file-func' (if any) is used to get the name of the associated peak-env file if the file is very large.
'work-proc-func' is called when the amp envs are ready if the amp envs are gathered in the background.
If 'file' is a sound, 'size' is an edit-position, and the current amp envs (if any) are returned.
The arguments to 'peak-file-func' are the file and the channel.  If it returns a string, that is treated as the filename
to read to get the peak info.  The arguments to 'work-proc-func' are the filename, the channel and the current peak.
make-sound-icon in <a href="sndscm.html#makesoundbox">make-sound-box</a> in snd-motif.scm uses
this function to draw the little thumbnail graph for each sound icon.
</p>
<div class="separator"></div>


<!-- channel-data -->
<pre class="indented">
<em class=def id="channeldata">channel-data</em> snd chn
</pre>

<p>channel-data provides very low-level access to the data currently in the given channel's sample buffers.
It is used by the <a href="sndscm.html#variabledisplay">variable-display</a> mechanism to show graphs
of variable values (normally in an instrument).  channel-data only works with sounds returned
by make-variable-display, and only in a float-sample version of Snd (i.e. not one that was built with
the configure argument --without-float-samples).  See make-variable-display in snd-motif.scm.  
</p>
<div class="separator"></div>


<!-- channel-properties -->
<pre class="indented">
<em class=def id="channelproperties">channel-properties</em> snd chn
</pre>

<p>channel-properties is a property list associated with a channel.  It is set to () at the time a sound is opened, so
it provides a relatively simple way to save data about a channel which will automatically be erased when the channel is closed.
<a href="#channelproperty">channel-property</a> reads and writes this list.  
</p>

<p>Traditionally in Lisp, a property list has been treated as an association list. This is a list
of pairs (made by cons), each inner pair having a key as its first element, and the associated value as the second element.
The function <b>assoc</b> can be used to search the list for a given key's value; a new key-value pair can be
added with:
</p>

<pre class="indented">
(cons (cons key value) a-list)
</pre>

<p>In Common Lisp, property lists have other properties, so to speak, but channel-properties (and
<a href="#soundproperties">sound-properties</a>) can be handled in any way you like.
See <a href="sndscm.html#channelsync">channel-sync</a> in extensions.scm for a brief example; more
elaborate examples are in enved.scm (enved-envelope), or draw.scm (colored-samples and insert-envelope).
</p>
<div class="separator"></div>


<!-- channel-property -->
<pre class="indented">
<em class=def id="channelproperty">channel-property</em> key snd chn
</pre>

<p>channel-property returns the value associated with 'key' in the given channel's
<a href="extsnd.html#channelproperties">property list</a>.  To add or change a property, use set! with this procedure. 
</p>

<pre class="indented">
Scheme:
&gt; (set! (channel-property 'info 0 0) "this is sound 0, first channel")
"this is sound 0, first channel"
&gt; (channel-property 'info 0 0)
"this is sound 0, first channel"

Ruby:
>set_channel_property(:info, "this is info", 0, 0)
this is info
>channel_property(:info, 0, 0)
this is info

Forth:
>'info "this is info" 0 0 set-channel-property
'( '( 'info . this is info ) )
>'info 0 0 channel-property
this is info
</pre>

<p>The property list is convenient because the associated information goes away automatically
when the channel is closed, and the property lists are saved by <a href="extsnd.html#savestate">save-state</a>.
</p>
<div class="separator"></div>


<!-- channel-style -->
<pre class="indented">
<em class=def id="channelstyle">channel-style</em> snd
</pre>

<p>channel-style reflects the value of the '<a href="snd.html#unitebutton">unite</a>' button in multichannel files.  
Possible values are channels-separate, channels-combined (the default), and channels-superimposed. 
The following code sets the 'unite' button if the current sound has more than 4 channels: 
</p>

<pre class="indented">
(hook-push <a class=quiet href="#afteropenhook">after-open-hook</a> 
  (lambda (hook)
    (if (&gt; (<a class=quiet href="#chans">channels</a> (hook 'snd)) 4)
        (set! (<em class=red>channel-style</em> (hook 'snd)) <a class=quiet href="#channelstyle">channels-combined</a>))))
</pre>
<div class="separator"></div>


<!-- channel->float-vector -->
<pre class="indented">
<em class=def id="channeltofv">channel-&gt;float-vector</em> beg dur snd chn edpos
</pre>

<p id="selection2fv">channel-&gt;float-vector returns a float-vector with the specified data.  In Ruby, the "-&gt;" in a function name is translated to "2",
so the function call is: 
</p>

<pre class="indented">    v = channel2vct(0, 100)
</pre>

<pre class="indented">
(define* (selection-&gt;float-vector snd chn)
  (cond ((selection-member? snd chn)
         (channel-&gt;float-vector (selection-position snd chn) (selection-framples snd chn) snd chn))

        ((selection?)
         (error 'no-such-channel
                (list "selection-&gt;float-vector" 
                      (format #f "snd ~A channel ~D is not a member of the selection" snd chn))))
        (else
         (error 'no-active-selection (list "selection-&gt;float-vector")))))
</pre>

<p>See also mark-explode in marks.scm.
</p>
<div class="separator"></div>


<!-- channels -->
<pre class="indented">
<em class=def id="channels">channels</em> snd 
<em class=def id="chans">chans</em> snd
</pre>

<p>This function returns the number of channels in 'snd'.  It can be set, but the result is a new
version of the underlying sound with the header changed to reflect the new number of channels.
That is, no new data is created, but the existing data is reapportioned to the new channels:
(set! (channels) 2); this is not undo-able (except by calling it again with the
original number of channels &mdash; the data is not touched).
</p>
<div class="separator"></div>


<!-- clm-channel -->
<pre class="indented">
<em class=def id="clmchannel">clm-channel</em> clm-gen beg dur snd chn edpos overlap origin
</pre>

<p>clm-channel applies 'clm-gen' to the given channel starting
at sample 'beg' for 'dur' samples, and 'overlap' samples of 'ring time'.
This is used by some of the <a class=quiet href="#regularizedargs">regularized</a> functions, but it can also be used directly:
</p>

<pre class="indented">
(define* (convolve-channel kernel nbeg ndur nsnd nchn nedpos)
  (let* ((beg (or nbeg 0)) 
	 (snd (or nsnd (<a class=quiet href="#selectedsound">selected-sound</a>) (car (<a class=quiet href="#sounds">sounds</a>))))
	 (chn (or nchn (<a class=quiet href="#selectedchannel">selected-channel</a>)))
	 (dur (or ndur (- (<a class=quiet href="#framples">framples</a> snd chn) beg)))
	 (edpos (or nedpos current-edit-position))
	 (reader (<a class=quiet href="#makesampler">make-sampler</a> beg snd chn 1 edpos))
	 (cgen (<a class=quiet href="sndclm.html#make-convolve">make-convolve</a> :filter kernel 
                              :input (lambda (dir)
				       (<a class=quiet href="#readsample">read-sample</a> reader)))))
    (<em class=red>clm-channel</em> cgen beg dur snd chn edpos)
    (<a class=quiet href="#freesampler">free-sampler</a> reader)))

(define (difference) (<em class=red>clm-channel</em> (<a class=quiet href="sndclm.html#make-two-zero">make-two-zero</a> 1 -1)))
(define (wobble) (<em class=red>clm-channel</em> (<a class=quiet href="sndclm.html#make-ncos">make-ncos</a> 50 3)))
(define (hold-nose) (<em class=red>clm-channel</em> (<a class=quiet href="sndclm.html#make-ncos">make-ncos</a> 1 3)))
(define (bad-reception) (<em class=red>clm-channel</em> (<a class=quiet href="sndclm.html#make-ncos">make-ncos</a> 10 5)))
</pre>
<div class="separator"></div>


<!-- close-sound -->
<pre class="indented">
<em class=def id="closesound">close-sound</em> snd
</pre>

<p>This closes 'snd' (the same as the File:Close menu item). To close all sounds: 
</p>

<pre class="indented">
(close-sound #t) 
;; equivalent to:
(for-each close-sound (<a class=quiet href="#sounds">sounds</a>))
</pre>

<p>Before the sound is actually closed, <a class=quiet href="#beforeclosehook">before-close-hook</a> 
is called, then <a class=quiet href="#closehook">close-hook</a>,
then the sound is closed.
</p>
<div class="separator"></div>


<!-- comment -->
<pre class="indented">
<em class=def id="comment">comment</em> snd
</pre>

<p>This returns the sound's comment, if any; when a sound is opened, the comment is taken from the file's header 
(the same as <a href="#mussoundcomment">mus-sound-comment</a>).  If you set it, the header is not updated until the sound is saved.
If the new comment is the only change you want to make, you can save the new header via the Edit:Edit Header menu option.
</p>
<div class="separator"></div>


<!-- main-index |convolvewith:convolution reverb -->
<!-- convolve-with -->
<pre class="indented">
<em class=def id="convolvewith">convolve-with</em> file amp snd chn edpos
</pre>

<p>This convolves the given channel (or the currently sync'd data)
with the data in the sound file 'file'. 'amp' is the resultant 
peak amplitude (leave 'amp' unset, or set it to #f to get the 
unnormalized result).
Convolve-with in conjunction with mix can provide high-quality reverb:
</p>

<pre class="indented">
(define conrev
  (lambda (impulse amp)
    (<em class=red>convolve-with</em> impulse amp)
    (<a class=quiet href="#savesoundas">save-sound-as</a> "reverb.snd") ;let mix scalers set reverb amount
    (<a class=quiet href="#revertsound">revert-sound</a>)
    (<em class=red>mix</em> "reverb.snd")))
</pre>
<div class="separator"></div>


<!-- count-matches -->
<pre class="indented">
<em class=def>count-matches</em> proc sample snd chn edpos
</pre>

<p>count-matches returns how many samples satisfy the function 'proc'; 'proc' should
take one argument (the current sample value), and return #t for a hit. 'sample' 
determines where to start the search.
</p>

<pre class="indented">
Scheme: (count-matches (lambda (y) (&gt; y .1)))
Ruby:   count_matches(lambda do |y| y &gt; 0.1 end)
Forth:  lambda: &lt;{ y }&gt; y 0.1 f- f0&lt; ; count-matches
</pre>

<p>count-matches is obsolete; use a do loop and a sampler:
</p>

<pre class="indented">
(define* (count-matches func (beg 0) snd chn edpos)
  (let ((end (framples snd chn edpos))
	(matches 0)
	(reader (make-sampler beg snd chn 1 edpos)))
    (do ((i beg (+ i 1)))
	((= i end) matches)
      (if (func (next-sample reader))
	  (set! matches (+ matches 1))))))
</pre>

<div class="separator"></div>


<!-- cursor -->
<pre class="indented">
<em class=def id="cursor">cursor</em> snd chn edpos
</pre>

<p id="cursorexamples">This returns the cursor location (as a sample number; the first sample is numbered 0) in channel 'chn' of 'snd'.
<code>(set! (cursor) 100)</code> moves the cursor to sample 100.  The cursor is somewhat similar to a
mark in that it moves if you delete or insert samples in front of it.  To turn the cursor off, set
it to some negative number.
</p>

<!-- INDEX cursorexamples:Cursors -->
<TABLE class="method">
<tr><th class="title">Cursor</th></tr>
<tr><td>
<blockquote><small>
Tracking cursor: <a href="extsnd.html#withtrackingcursor">with-tracking-cursor</a><br>
Change cursor shape or size: <a href="extsnd.html#cursorstyle">cursor-style</a>, <a href="extsnd.html#cursorsize">cursor-size</a><br>
Cursor moving keys: <a href="snd.html#movecursor">Moving the Cursor</a><br>
Display data about sample under cursor: <a href="extsnd.html#withverbosecursor">with-verbose-cursor</a><br>
play from the current cursor position with a tracking cursor:  <a href="extsnd.html#pfc">pfc</a><br>
display tracking cursor as a full height vertical line: <a href="extsnd.html#trackingcursorstyle">tracking-cursor-style</a><br>
track play once: control-click 'play'. (You can add a mark at the current tracking cursor location during the play with C-m)<br>
leave the cursor at the final position after tracking play: (set! *with-tracking-cursor* :track-and-stay)<br>
tracking cursor accuracy: <a href="extsnd.html#cursorlocationoffset">cursor-location-offset</a><br>
tracking cursor updating: <a href="extsnd.html#cursorupdateinterval">cursor-update-interval</a><br>
</small></blockquote>
</td></tr></TABLE>
<div class="separator"></div>



<!-- cursor-position -->
<pre class="indented">
<em class=def id="cursorposition">cursor-position</em> snd chn
</pre>

<p>This gives the current cursor position as a list (x y).
These graph-relative values can be turned into axis-relative values with
<a href="#positiontox">position-&gt;x</a> and <a href="#positiontoy">position-&gt;y</a>:
</p>

<pre class="indented">
(<a class=quiet href="#positiontox">position-&gt;x</a> (car (cursor-position)))
;; equals:
(/ (<a class=quiet href="#cursor">cursor</a>) (<a class=quiet href="#srate">srate</a>))
</pre>
<div class="separator"></div>


<!-- cursor-size -->
<pre class="indented">
<em class=def id="cursorsize">cursor-size</em> snd chn
</pre>

<p>This gives the cursor size in pixels; it defaults to 15. (set! (cursor-size) 30) makes the cursor twice as big as usual.
</p>
<div class="separator"></div>


<!-- cursor-style -->
<pre class="indented">
<em class=def id="cursorstyle">cursor-style</em> snd chn
</pre>

<p id="xcursor">The cursor style is cursor-cross, cursor-line, or a cursor-drawing function.
The default cursor shape is a "+" sign; the cursor-line is a vertical line.
As a function, cursor-style is a procedure of three arguments, the
sound, channel number, and a boolean that is true if the cursor is currently
tracking playback (a "tracking-cursor").
The procedure
should draw the cursor at the current cursor position using the
<a href="#cursorcontext">cursor-context</a>.
Here is a simpler one that
replaces the normal "+" cursor with an "x":
</p>

<pre class="indented">
(define (x-cursor snd chn ax) ; works only in motif currently
  (let* ((point (<em class=red>cursor-position</em>))
         (x (car point))
         (y (cadr point))
         (size (<em class=red>cursor-size</em>)))
    (<a class=quiet href="#drawline">draw-line</a> (- x size) (- y size) (+ x size) (+ y size) snd chn <em class=red>cursor-context</em> #f)    
    (<a class=quiet href="#drawline">draw-line</a> (- x size) (+ y size) (+ x size) (- y size) snd chn <em class=red>cursor-context</em> #f)))

(set! (<em class=red>cursor-style</em>) x-cursor)
</pre>
<div class="separator"></div>


<!-- data-location -->
<pre class="indented">
<em class=def id="datalocation">data-location</em> snd
</pre>

<p>This gives the location (in bytes) of the sound samples in the file represented by 'snd'.  In a raw (headerless) file,
this is 0, but normally the data comes after some portion of the header.  
To get the data-location of some sound file, use <a href="#mussounddatalocation">mus-sound-data-location</a>.
If you set this field (you don't want to do this &mdash; it is a law of nature that you will forget the original setting!), the underlying file is immediately rewritten.
</p>
<div class="separator"></div>


<!-- data-size -->
<pre class="indented">
<em class=def id="datasize">data-size</em> snd
</pre>

<p>This gives the size (in bytes) of the sound data in the file represented by 'snd'.
If you set this field, the underlying file is immediately rewritten (the header is changed; I don't
think the file is truncated, but no matter what happens, it is not my fault).
Next/Sun files treat the size field as purely "advisory", so an incorrect data size is often
ignored in that case.
</p>
<div class="separator"></div>


<!-- delete-sample -->
<pre class="indented">
<em class=def id="deletesample">delete-sample</em> samp snd chn edpos
</pre>

<p id="deletionexamples">This deletes sample 'samp' in the given channel.
</p>

<!-- INDEX deletionexamples:Deletions -->
<TABLE class="method">
<tr><th class="title">Deletions</th></tr><tr><td>
<blockquote><small>
delete a file: in scheme delete-file or Ruby's File.delete<br>
delete a region: <a href="extsnd.html#forgetregion">forget-region</a><br>
delete the currently selected samples: <a href="extsnd.html#deleteselection">delete-selection</a><br>
delete the selection and smooth the splice: <a href="extsnd.html#deleteselectionandsmooth">delete-selection-and-smooth</a><br>
delete a mark or all marks: <a href="extsnd.html#deletemark">delete-mark</a><br>
delete a colormap: <a href="extsnd.html#deletecolormap">delete-colormap</a><br>
delete samples: <a href="extsnd.html#deletesamples">delete-samples</a><br>
delete samples and smooth over the splice: <a href="#deletesamplesandsmooth">delete-samples-and-smooth</a><br>
remove a file from the sound cache: <a href="extsnd.html#mussoundforget">mus-sound-forget</a><br>
remove a menu item: <a href="extsnd.html#removefrommenu">remove-from-menu</a> or remove-main-menu in snd-motif.scm<br>
delete a mix or all mixes: <a href="sndscm.html#silenceallmixes">silence-mixes</a><br>
add a 'delete' option to the file selection dialog: <a href="sndscm.html#adddeleteoption">add-delete-option</a><br>
</small></blockquote>
</td></tr></TABLE>
<div class="separator"></div>




<!-- delete-samples -->
<pre class="indented">
<em class=def id="deletesamples">delete-samples</em> samp samps snd chn edpos
</pre>

<p>This deletes a block of samples.  The deleted portion starts at sample 'samp' and runs for 'samps' samples.
</p>
<div class="separator"></div>


<!-- delete-samples-and-smooth -->
<pre class="indented">
<em class=def id="deletesamplesandsmooth">delete-samples-and-smooth</em> samp samps snd chn edpos
</pre>

<p>This deletes a block of samples, then tries to smooth over the splice.  The deleted portion starts at sample 'samp' and runs for 'samps' samples.
</p>
<div class="separator"></div>


<!-- dot-size -->
<pre class="indented">
<em class=def id="dotsize">dot-size</em> snd chn
</pre>

<p>This gives the size in pixels of dots when graphing with dots (default: 1); this affects <a href="#graphstyle">graph-styles</a> such as graph-lollipops.  See <a href="#graphhook">graph-hook</a> or auto-dot in examp.scm.
</p>
<div class="separator"></div>


<!-- env-channel -->
<pre class="indented">
<em class=def id="envchannel">env-channel</em> clm-env-gen beg dur snd chn edpos
</pre>

<p id="envexamples">env-channel is the <a class=quiet href="#regularizedargs">regularized</a> version of <a href="#envsound">env-sound</a>.  'clm-env-gen'
can be either a CLM envelope generator or an envelope (a list of breakpoints). <code>(env-channel '(0 0 1 1 2 0))</code>.
To get .1 seconds of attack and decay:
</p>

<pre class="indented">
(let ((dur (/ (<a class=quiet href="#framples">framples</a>) (<a class=quiet href="#srate">srate</a>)))) 
  (<em class=red>env-channel</em> (list 0 0  .1 1  (- dur .1) 1  dur 0)))
</pre>

<p>
An envelope in Snd is a list of breakpoints. It can be packaged as a CLM generator (an 'env') via <a href="sndclm.html#make-env">make-env</a>.
It can be declared via define just like any other variable, or with <a href="#defineenvelope">define-envelope</a>.
</p>


<!-- INDEX envexamples:Envelopes -->
<TABLE class="method">
<tr><th class="title">Envelopes</th></tr><tr><td>
<blockquote><small>
envelope sound: <a href="#envchannel">env-channel</a>, <a href="#envsound">env-sound</a><br>
Other enveloping functions: <a href="#rampchannel">ramp-channel</a>, <a href="#xrampchannel">xramp-channel</a>, <a href="#smoothchannel">smooth-channel</a><br>
The CLM env generator: <a href="sndclm.html#make-env">env</a>, many examples in examp.scm, new-effects.scm, etc<br>
Various operations on envelopes: <a href="sndscm.html#envdoc">env.scm</a><br>
The envelope editor: <a href="snd.html#editenvelope">Edit or View and Envelope</a><br>
Panning: place-sound in examp.scm<br>
Envelope over mix: <a href="sndscm.html#envelopedmix">enveloped-mix</a><br>
Local envelope editor: <a href="sndscm.html#enveddoc">enved.scm</a>, xm-enved.scm<br>
Read sound indexed through envelope: <a href="sndscm.html#envsoundinterp">env-sound-interp</a><br>
Cosine as envelope: <a href="#cosinechannel">cosine-channel</a>, <a href="sndclm.html#bellcurve">bell-curve</a><br>
envelope with sinusoidal connections between points: <a href="sndscm.html#sineenvchannel">sine-env-channel</a><br>
envelope with separate base for each segment: <a href="sndscm.html#powenvchannel">powenv-channel</a><br>
envelope with x^2 connections: <a href="sndscm.html#envsquaredchannel">env-squared-channel</a><br>
envelope with x^n connections: <a href="sndscm.html#envexptchannel">env-expt-channel</a><br>
envelope with <a href="sndclm.html#ncos">ncos</a> connections: <a href="sndscm.html#blackman4envchannel">blackman4-env-channel</a><br>
Customizing the envelope editor: <a href="#envedhook">enved-hook</a><br>
peak amp follower: <a href="sndclm.html#moving-max">moving-max</a><br>
</small></blockquote>
</td></tr></TABLE>
<div class="separator"></div>



<!-- env-channel-with-base -->
<pre class="indented">
<em class=def id="envchannelwithbase">env-channel-with-base</em> envelope-or-env-gen base beg dur snd chn edpos
</pre>

<p>env-channel-with-base is a slight variation on env-channel.  There are times when it's a bother
to call <a href="sndclm.html#make-env">make-env</a> just to get an exponential envelope.
</p>
<div class="separator"></div>


<!-- env-sound -->
<pre class="indented">
<em class=def id="envsound">env-sound</em> envelope samp samps env-base snd chn edpos
</pre>

<p>env-sound applies the amplitude 'envelope' to the given channel starting
at sample 'samp' for 'samps' samples with connecting segments
based on 'env-base'.  'env-base' defaults to 1.0.
'samp' defaults to 0.  'samps' defaults to the full duration.
'envelope' is a list containing the breakpoint values 
(as in CLM) or an env generator.
</p>

<table class="method">
<tr><td>
<img src="pix/ampenv1.png" alt="ampenvs">
</td><td>
<img src="pix/ampenv2.png" alt="ampenvs">
</td></tr>
<tr><td colspan=2 class="center">
<pre class="indented">
Scheme: (env-sound '(0 0 1 1 2 0))
Ruby:   env_sound([0.0, 0.0, 1.0, 1.0, 2.0, 0.0])
Forth:  '( 0.0 0.0 1.0 1.0 2.0 0.0 ) env-sound
</pre>
</td></tr></table>


<p>As mentioned in <a href="sndclm.html#make-env">sndclm.html</a>, 
'env-base' determines how the break-points are connected.  If it is 1.0 (the
default), you get straight line segments.  'env-base' = 0.0 gives a step
function (the envelope changes its value suddenly to the new one without any
interpolation).  Any other positive value becomes the exponent of the exponential curve
connecting the points.  'env-base' &lt; 1.0 gives convex curves (i.e. bowed
out), and 'env-base' &gt; 1.0 gives concave curves (i.e. sagging).
If you'd rather think in terms of e^-kt, set 'env-base' to (exp k).
See env.lisp for a CLM instrument that shows the relation between the connecting
curve's exponent and 'env-base'.  Here's a brief restatement:
</p>

<pre class="indented">
(define (compare-exp k)
   (let ((e (<a class=quiet href="sndclm.html#make-env">make-env</a> (list 0 1 1 (exp (- k))) :base (exp k) :length 11)))
      (do ((i 0 (+ 1 i )))
         ((= i 10))
         (<a class=quiet href="#sndprint">snd-print</a> (<a class=quiet>format</a> #f "~A ~A~%" (<a class=quiet href="sndclm.html#env">env</a> e) (exp (* (- k) (/ i 10.0))))))))
</pre>

<p>If 'envelope' is a CLM env generator, 'env-base' 
is ignored.
</p>
<div class="separator"></div>


<!-- fft-log-frequency -->
<pre class="indented">
<em class=def id="fftlogfrequency">fft-log-frequency</em> snd chn
</pre>

<p>This returns whether the spectrum frequency axis is logarithmic (#t) or linear (#f, the default).  If logarithmic, the lower end
is set by <a href="#logfreqstart">log-freq-start</a> which defaults to 32Hz.
</p>
<div class="separator"></div>


<!-- fft-log-magnitude -->
<pre class="indented">
<em class=def id="fftlogmagnitude">fft-log-magnitude</em> snd chn
</pre>

<p>This returns whether the spectrum magnitude axis is in decibels (#t) or linear (#f, the default).  If in decibels, the
minimum displayed is set by <a href="#mindb">min-dB</a> which defaults to -60.
</p>
<div class="separator"></div>


<!-- fft-window -->
<pre class="indented">
<em class=def id="fftwindow">fft-window</em> snd chn
</pre>

<p>This sets the choice of fft data window (default: blackman2-window)
</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>The Hann window is sometimes called Hanning in the DSP literature, apparently
as an in-joke.  For an extensive discussion of these windows, see
Fredric J. Harris, "On the Use of Windows for Harmonic Analysis with the Discrete Fourier Transform", Proceedings of the
IEEE, Vol. 66, No. 1, January 1978, with updates from: Albert H. Nuttall, "Some Windows with Very Good Sidelobe Behaviour", IEEE Transactions
of Acoustics, Speech, and Signal Processing, Vol. ASSP-29, 1, February 1981, and of course, Julius Smith's DSP web site.
</p>
<div class="separator"></div>


<!-- fft-window-alpha -->
<pre class="indented">
<em class=def id="fftalpha">fft-window-alpha</em> snd chn
</pre>

<p>The ultraspherical window has two "family" parameters; the one named "mu" is called "beta" here,
to parallel its use in related windows; the other one, named "x<sub>mu</sub>" is named "alpha" here,
for no good reason.  fft-window-alpha sets the shape of the side lobes; see
"Design of Ultraspherical Window Functions with Prescribed Spectral Characteristics", Bergen and Antoniou, EURASIP JASP 2004
(also available on-line) for details.
</p>
<div class="separator"></div>


<!-- fft-window-beta -->
<pre class="indented">
<em class=def id="fftbeta">fft-window-beta</em> snd chn
</pre>

<p>Some fft windows have a parameter, often named alpha or beta, that chooses one from a family of possible windows.
The actual (underlying) beta values are dependent on the window choice, but
in Snd, fft-window-beta is scaled to fit the current window's range of values, so
its value here should fall between 0.0 and 1.0.
</p>
<div class="separator"></div>


<!-- fft-with-phases -->
<pre class="indented">
<em class=def id="fftwithphases">fft-with-phases</em> snd chn
</pre>

<p>This returns whether the single FFT display includes phase information (the default is #f).
</p>
<div class="separator"></div>


<!-- file-name -->
<pre class="indented">
<em class=def id="filename">file-name</em> snd
</pre>

<p>This returns the sound's complete (or "absolute") file name; the directory is included; see <a href="#shortfilename">short-file-name</a>
if you don't want all the directory junk.  See examp.scm for many examples.
</p>
<div class="separator"></div>


<!-- filter-channel -->
<pre class="indented">
<em class=def id="filterchannel">filter-channel</em> env order beg dur snd chn edpos trunc origin
</pre>

<p>The regularized version of filter-sound.  If the end of the filtered portion is not the end of the sound,
the 'trunc' argument determines whether the filtered sound is truncated at that point (the default: #t),
or mixed with the overlapping section, similar to the truncate argument to <a href="#filterselection">filter-selection</a>.
'env' can be either the frequency response envelope, or a float-vector containing the desired coefficients.
</p>
<div class="separator"></div>


<!-- filter-sound -->
<pre class="indented">
<em class=def id="filtersound">filter-sound</em> env order snd chn edpos origin
</pre>

<p>filter-sound applies an FIR filter of order 'order' (actually one more than the nominal order)
and frequency response 'env'
to the given channel.  'env' can also be a float-vector containing the filter coefficients,
or any CLM filtering generator 
(e.g. comb, formant, one-pole, iir-filter, etc). The generator 
is called in C, not Scheme, so this is the fastest way to apply 
CLM filtering to a sound.  See also <a href="#clmchannel">clm-channel</a>.
</p>

<pre class="indented">
(<em class=red>filter-sound</em> '(0 1 1 0) 1024)                             ; FIR filter given frequency response
(<em class=red>filter-sound</em> (float-vector .1 .2 .3 .3 .2 .1) 6)                   ; FIR filter given actual coefficients
(<em class=red>filter-sound</em> (<a class=quiet href="sndclm.html#make-fir-filter">make-fir-filter</a> 6 (float-vector .1 .2 .3 .3 .2 .1))) ; CLM FIR filter
(<em class=red>filter-sound</em> (<a class=quiet href="sndclm.html#make-delay">make-delay</a> 120))                            ; CLM delay (same as insert-silence)
(<em class=red>filter-sound</em> (<a class=quiet href="sndclm.html#make-formant">make-formant</a> 1200 .99))                     ; CLM formant
(<em class=red>filter-sound</em> (<a class=quiet href="sndclm.html#make-filter">make-filter</a> 2 (float-vector 1 -1) (float-vector 0 -0.99)))    ; remove DC
</pre>

<p>If you want to use the cascade filter structure, rather than the canonical
form of CLM's filter generator:
</p>

<pre class="indented">
(define (<a class=quiet href="sndscm.html#makebiquad">make-biquad</a> a0 a1 a2 b1 b2)
  (<a class=quiet href="sndclm.html#make-filter">make-filter</a> 3 (float-vector a0 a1 a2) (float-vector 0.0 b1 b2)))
</pre>

<p>If you have coefficients for the cascade form, but have no scruples about using 
some other form, see cascade-&gt;canonical in dsp.scm, and the examples that follow.
</p>

<!-- INDEX filtersinsnd:Filters -->

<TABLE class="method">
<tr><th class="title">Filters</th></tr><tr><td>
<blockquote id="filtersinsnd"><small>
filter a sound: <a href="extsnd.html#filtersound">filter-sound</a>, <a href="extsnd.html#filterchannel">filter-channel</a>, and <a href="extsnd.html#clmchannel">clm-channel</a><br>
filter the selection: <a href="extsnd.html#filterselection">filter-selection</a>, <a href="sndscm.html#filterselectionandsmooth">filter-selection-and-smooth</a><br>
CLM filter generators: <a href="sndclm.html#filterdoc">filter, one-pole, formant, comb, notch, all-pass, etc</a><br>
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>
the usual analog filters (Butterworth, Chebyshev, Bessel, Elliptic): <a href="sndscm.html#analogfilterdoc">analog-filter.scm</a><br>
Butterworth filters: <a href="sndscm.html#makebutter">make-butter-high-pass</a>, make-butter-low etc in dsp.scm, used in new-effects.scm<br>
IIR filters of various orders/kinds: <a href="sndscm.html#IIRfilters">dsp.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: see example above, dc-block in prc95.scm, or stereo-flute in clm-ins.scm<br>
hum elimination: see <a href="sndscm.html#IIRfilters">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="sndclm.html#moving-average">moving-average</a>, <a href="sndclm.html#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 <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>
Max Mathews resonator: <a href="sndclm.html#firmant">firmant</a>, <a href="sndscm.html#maxfdoc">maxf.scm, maxf.rb</a><br>
Spectral edit dialog: <a href="snd.html#editenvelope">Envelope Editor</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>
see also convolution, physical modeling, reverb, and <a href="sndscm.html#ssffts">fft-based filtering</a><br>
</small></blockquote>
</td></tr></TABLE>
<div class="separator"></div>



<!-- INDEX searchexamples:Searching -->

<TABLE class="method">
<tr><th class="title">Searches</th></tr><tr><td>
<blockquote id="searchexamples"><small>
find a mark: <a href="extsnd.html#findmark">find-mark</a><br>
find a mix: <a href="sndscm.html#findmix">find-mix</a><br>
find a sound: <a href="extsnd.html#findsound">find-sound</a><br>
Example find procedures: <a href="sndscm.html#searchforclick">search-for-click, zero+, next-peak, find-pitch</a><br>
Default search procedure: <a href="extsnd.html#searchprocedure">search-procedure</a><br>
The Find dialog: <a href="snd.html#editoperations">Find</a> or <a href="extsnd.html#finddialog">find-dialog</a><br>
find silence: <a href="extsnd.html#mapsilence">map-silence</a>, scramble-channel in examp.scm<br>
find any difference between two chans: <a href="sndscm.html#channelsequal">channels-equal</a><br>
find a widget: find-child in snd-motif.scm<br>
add C-s and C-r to the listener key bindings: add-find-to-listener in snd-motif.scm<br>
Scheme find: find-if<br>
</small></blockquote>
</td></tr></TABLE>
<div class="separator"></div>


<!-- find-sound -->
<pre class="indented">
<em class=def id="findsound">find-sound</em> filename nth
</pre>

<p>find-sound returns the sound object of 'filename' or
#f if no sound is found that matches 'filename'.  If there is (or might be) more than one file
open with the given filename, the 'nth' parameter (which defaults to 0) chooses which to return.
Leaving aside the 'nth' parameter, find-sound could be defined as:
</p>

<pre class="indented">
(define (find-sound name)
  (call-with-current-continuation
   (lambda (return)
     (for-each 
      (lambda (snd)
	(if (or (string=? (<a class=quiet href="#shortfilename">short-file-name</a> snd) name)
		(string=? (<a class=quiet href="#filename">file-name</a> snd) name))
	    (return snd)))
      (<a class=quiet href="#sounds">sounds</a>))
     #f)))
</pre>

<p>See files-popup-buffer, open-next-file-in-directory, and the "Buffer Menu" code in examp.scm.
</p>
<div class="separator"></div>


<!-- finish-progress-report -->
<pre class="indented">
<em class=def id="finishprogressreport">finish-progress-report</em> snd chn
</pre>

<p>This ends an on-going progress report (a visual indication of how far along some time-consuming process is). 
See <a href="#progressreport">progress-report</a>.
</p>
<div class="separator"></div>


<!-- framples -->
<pre class="indented">
<em class=def id="framples">framples</em> snd chn edpos
</pre>

<p>This returns current length in samples of the channel 'chn'.  Used with set!, this either truncates 
the sound or pads it with zeros at the end.
</p>
<div class="separator"></div>


<!-- free-player -->
<pre class="indented">
<em class=def id="freeplayer">free-player</em> player
</pre>

<p>free-player frees all resources associated with 'player' and remove it from the play-list.
</p>
<div class="separator"></div>


<!-- graph -->
<pre class="indented">
<em class=def id="graph">graph</em> data xlabel x0 x1 y0 y1 snd chn force-display show-axes-choice
</pre>

<p>This function displays a graph of 'data' in a separate display per channel.  The x axis
is labelled 'xlabel', the x axis units go from 'x0' to 'x1' (the default is 0.0 to 1.0),
the y axis goes from 'y0' to 'y1' (the default fits the data), and the display is 
associated with channel 'chn' in 'snd'.
</p>

<pre class="indented">
(graph (float-vector 0 .1 .2 .3 .4 .3 .2 .1 0) "roof")
</pre>

<p id="xdisplayenergy">The current slider values can be read from <a href="#xpositionslider">x-position-slider</a>, 
<a href="#xzoomslider">x-zoom-slider</a>, etc.  The 'data' argument can be a list of float-vectors; each is graphed at the same time, following the sequence of
colors used when channels are superimposed.  If 'data'
is a list of numbers, it is assumed to be an envelope (a list of breakpoints).
If 'force-display' is #f (the default is #t), the graph is not
explicitly drawn; this is useful when you're calling graph from
the lisp-graph-hook, where the redisplay is automatic.
'show-axes-choice' sets the <a href="#showaxes">show-axes</a> choice for the lisp graph.
</p>

<pre class="indented">
(define display-energy
  ;; y-zoom-slider controls the graph amp
  (lambda (snd chn)
    (let* ((ls (<a class=quiet href="#leftsample">left-sample</a>))
           (rs (<a class=quiet href="#rightsample">right-sample</a>))
	   (datal (<a class=quiet href="#makegraphdata">make-graph-data</a> snd chn))
	   (data (if (float-vector? datal) datal (cadr datal)))
           (sr (<a class=quiet href="#srate">srate</a> snd))
	   (y-max (<a class=quiet href="#yzoomslider">y-zoom-slider</a> snd chn)))
      (float-vector-multiply! data data)
      (<em class=red>graph</em> data "energy" (/ ls sr) (/ rs sr) 0.0 (* y-max y-max) snd chn #f))))

(hook-push <a href="#lispgraphhook">lisp-graph-hook</a> (lambda (hook) (display-energy (hook 'snd) (hook 'chn))))
</pre>
<img class="indented" src="pix/energy.png" alt="picture of examp.scm in action">
<div class="separator"></div>


<!-- graph-style -->
<pre class="indented">
<em class=def id="graphstyle">graph-style</em> snd chn
</pre>

<p>graph-style determines how sound data is displayed (default: graph-lines).
The choices are:
</p>

<pre class="indented">
graph-lines  graph-dots  graph-filled  graph-lollipops  graph-dots-and-lines 
</pre>

<p>In the set! case, if no 'snd' is specified, all graph-styles are set to the
new value.  If 'snd' is given, the three graph styles for that sound's channels (or channel 'chn') are
set. See <a href="#timegraphstyle">time-graph-style</a>, <a href="#lispgraphstyle">lisp-graph-style</a>, and
<a href="#transformgraphstyle">transform-graph-style</a> to override the default for a specific graph.
</p>
<div class="separator"></div>


<!-- graphs-horizontal -->
<pre class="indented">
<em class=def id="graphshorizontal">graphs-horizontal</em> snd chn
</pre>

<p>This determines whether channel graphs (the time domain, spectrum, and lisp graphs) 
are arranged vertically
or horizontally (the latter is the default).
</p>
<div class="separator"></div>


<!-- grid-density -->
<pre class="indented">
<em class=def id="griddensity">grid-density</em> snd chn
</pre>

<p>This controls the spacing of axis ticks; the default is 1.0.  If grid-density is less than 1.0, more ticks are squeezed
in; if greater than 1.0, fewer ticks are displayed.  This mainly affects the grid display
(<a href="#showgrid">show-grid</a>).
</p>
<div class="separator"></div>


<!-- header-type -->
<pre class="indented">
<em class=def id="headertype">header-type</em> snd
</pre>

<p>This returns the header type (e.g. mus-aiff) of the file that underlies 'snd'.  
Snd can read about 60 header types, and write 7 or so.
"aiff" and "aifc" come from Apple, "riff" is the Microsoft "wave" header,
"rf64" is the European Broadcast Union's 64-bit RIFF replacement,
"nist" comes from the NIST-Sphere package, "next" or "sun" is the Next/Sun
(".au") header, "ircam" is IRCAM's extension of the Next header, 
"caf" is Apple's 64-bit AIFC replacement,
and "raw"
means the sound file has no header.  If you change the header type to "raw",
any existing header is removed.
Each header type has its own peculiarities; if in doubt, use mus-next because it is simple,
and can handle any sample type that Snd can write (whereas each of the others is restricted in this regard).
The writable header types are mus-next, mus-nist, 
mus-aiff (obsolete, rarely needed), mus-aifc, mus-riff, mus-rf64, mus-caff,
mus-ircam, and mus-raw (no header).  For technical descriptions of the headers,
see headers.c; for actual sound files, see sf.tar.gz at ccrma-ftp.
</p>

<p>To turn a header type number into a string, use <a href="#musheadertypename">mus-header-type-name</a>. To get
the header type of some sound file, use <a href="#mussoundheadertype">mus-sound-header-type</a>.
If you set the header-type, the sound file is rewritten with the new header.  The default output
(<a class=quiet href="#newsound">new-sound</a>, and
<a class=quiet href="#savesoundas">save-sound-as</a>) header type is <a href="#defaultoutputheadertype">default-output-header-type</a>.
</p>

<p>To read or write your own headers (or some header that isn't built-in),
I recommend using either <a href="#openhook">open-hook</a> or <a href="#openrawsoundhook">open-raw-sound-hook</a>:
in the latter case, when you open the file with the unsupported header,
Snd will throw up its hands and say "maybe it's a raw (headerless)
sound"; it will then look at open-raw-sound-hook before trying
other fallbacks (such as the Raw File Dialog).
See examp.scm or misc.scm (MPEG, OGG, etc).
</p>
<div class="separator"></div>


<!-- insert-sample -->
<pre class="indented">
<em class=def id="insertsample">insert-sample</em> samp value snd chn edpos
</pre>

<p id="insertionexamples">This inserts sample 'value' at sample 'samp' in the given channel 
</p>

<!-- INDEX insertionexamples:Insertions -->

<TABLE class="method">
<tr><th class="title">Insertions</th></tr><tr><td>
<blockquote><small>
insert some portion of a channel: <a href="sndscm.html#insertchannel">insert-channel</a><br>
insert a silence: <a href="extsnd.html#padchannel">pad-channel</a>, <a href="extsnd.html#insertsilence">insert-silence</a>, <a href="sndscm.html#padsound">pad-sound</a><br>
insert a region: <a href="extsnd.html#insertregion">insert-region</a><br>
insert the selection: <a href="extsnd.html#insertselection">insert-selection</a><br>
insert a float-vector of samples: <a href="extsnd.html#insertsamples">insert-samples</a><br>
insert a sound: <a href="extsnd.html#insertsound">insert-sound</a><br>
append a sound and silence: <a href="extsnd.html#appendsound">append-sound</a><br>
</small></blockquote>
</td></tr></TABLE>
<div class="separator"></div>



<!-- insert-samples -->
<pre class="indented">
<em class=def id="insertsamples">insert-samples</em> samp samps data snd chn edpos auto-delete origin
</pre>

<p>This inserts 'samps' samples of 'data' (normally a float-vector) starting at sample 'samp' in the given channel.
'data' can be a filename.
The regularized version of this is:
</p>

<pre class="indented">
(define* (<a class=quiet href="sndscm.html#insertchannel">insert-channel</a> data beg dur snd chn edpos)
  (insert-samples beg dur data snd chn edpos))
</pre>

<p>To insert a block of samples of a given value: (insert-samples beg dur (make-float-vector dur val))
If 'data' is a file, it is not deleted by Snd unless 'auto-delete' is #t. 
</p>
<div class="separator"></div>


<!-- insert-silence -->
<pre class="indented">
<em class=def id="insertsilence">insert-silence</em> beg num snd chn
</pre>

<p>This inserts 'num' zeros at 'beg' in the given channel. <a href="#padchannel">pad-channel</a> is the regularized version,
with one small change: insert-silence forces 'beg' to be within the current sound, but pad-channel pads out to 'beg' if
'beg' is past the end of the sound.  (And, as  usual in these cases, insert-silence follows the <a class=quiet href="#sync">sync</a>
field, whereas <a class=quiet href="#padchannel">pad-channel</a> ignores it).
</p>
<div class="separator"></div>


<!-- insert-sound -->
<pre class="indented">
<em class=def id="insertsound">insert-sound</em> file beg in-chan snd chn edpos auto-delete
</pre>

<p id="appendsound">This inserts channel 'in-chan' of 'file' at sample 'beg' in the given channel.
'beg' defaults to the cursor position; if 'in-chan' is not given, all 
channels are inserted. To append one sound to another, padding at the end with some silence:
</p>

<pre class="indented">
(define* (append-sound file (silence 1.0))
  (<em class=red>insert-sound</em> file (<a class=quiet href="#framples">framples</a>))
  (<em class=red>insert-silence</em> (<a class=quiet href="#framples">framples</a>) (round (* (<a class=quiet href="#srate">srate</a>) silence))))
</pre>

<p>'file' is not deleted by Snd unless 'auto-delete' is #t. 
</p>
<div class="separator"></div>


<!-- integer->sound -->
<pre class="indented">
<em class=def id="integertosound">integer-&gt;sound</em> i
</pre>

<p>In olden times, a sound was handled in Snd code as an integer; nowadays, it's an object (although the integer approach still works).
This function, and its companion <a href="#soundtointeger">sound-&gt;integer</a>, exist mainly to convert
old code to the current style.
</p>
<div class="separator"></div>


<!-- left-sample -->
<pre class="indented">
<em class=def id="leftsample">left-sample</em> snd chn
</pre>

<p>This returns the position in samples of the left edge of the time domain
waveform for the given channel.
To get the data currently displayed in the time domain window:
</p>

<pre class="indented">
(define (<a class=quiet href="sndscm.html#windowsamples">window-samples</a>)
  (let ((wl (<em class=red>left-sample</em>))
	(wr (<a href="#rightsample">right-sample</a>)))
   (<a href="#samples">samples</a> wl (- (+ wr 1) wl))))
</pre>

<p id="movingwindows">See also <a href="#moveonepixel">move-one-pixel</a>.
</p>

<!-- INDEX movingwindows:Window size and position -->

<TABLE class="method">
<tr><th class="title">Time Domain Display</th></tr><tr><td>
<blockquote><small>
Built-in keyboard commands: <a href="snd.html#movewindow">Moving the Window</a><br>
Specialized keyboard commands: <a href="extsnd.html#bindkey">bind-key</a><br>
Window size: <a href="extsnd.html#xzoomslider">x-zoom-slider</a>, <a href="extsnd.html#zoomonepixel">zoom-one-pixel</a>, <br>
Window position: <a href="extsnd.html#xpositionslider">x-position-slider</a>, <a href="extsnd.html#moveonepixel">move-one-pixel</a><br>
Window left edge: <a href="extsnd.html#leftsample">left-sample</a><br>
Window right edge: <a href="extsnd.html#rightsample">right-sample</a><br>
<br>
fft window:<br>
window size: drag x axis, <a href="extsnd.html#spectrumend">spectrum-end</a><br>
window start: <a href="extsnd.html#spectrumstart">spectrum-start</a><br>
relation to time domain: <a href="extsnd.html#beforetransformhook">before-transform-hook</a><br>
selection fft: <a href="extsnd.html#showselectiontransform">show-selection-transform</a><br>
<br>
general info:<br>
Axis description: <a href="extsnd.html#axisinfo">axis-info</a><br>
</small></blockquote>
</td></tr></TABLE>
<div class="separator"></div>


<!-- lisp-graph? -->
<pre class="indented">
<em class=def id="lispgraphp">lisp-graph?</em> snd chn
</pre>

<p>lisp-graph? returns #t if the lisp-generated graph is currently displayed ("lisp" here means any extension language).  
The lisp graph section is also active if there's a drawing function
on the <a href="#lispgraphhook">lisp-graph-hook</a>.
</p>
<div class="separator"></div>


<!-- lisp-graph-style -->
<pre class="indented">
<em class=def id="lispgraphstyle">lisp-graph-style</em> snd chn
</pre>

<p>This determines how lisp-generated data is displayed.
The choices are:
</p>

<pre class="indented">
graph-lines  graph-dots  graph-filled  graph-lollipops  graph-dots-and-lines 
</pre>
<div class="separator"></div>


<!-- make-player -->
<pre class="indented">
<em class=def id="makeplayer">make-player</em> snd chn
</pre>

<p>This function makes a new player associated with the given channel.
A player is a sort of wrapper for a channel of a sound that supports
all the control-panel functions.  Once created, you can set these
fields, then call <a href="#addplayer">add-player</a> to add this channel to the list of
channels either being played (if a play is in progress) or about
to be played.  Once some player is in the play-list, you can start 
the play with <a href="#startplaying">start-playing</a>, and stop it prematurely with either 
<a href="#stopplayer">stop-player</a> or <a href="#stopplaying">stop-playing</a>.  These functions make it possible 
to build custom control panels.  Here's an example that plays a 
sound with individual amplitudes for the channels:
</p>

<pre class="indented">
(define play-with-amps
  (lambda (sound . amps)
    (let ((chans (<a class=quiet href="#chans">channels</a> sound)))
      (do ((chan 0 (+ 1 chan)))
          ((= chan chans))
        (let ((player (<em class=red>make-player</em> sound chan)))
          (set! (<a class=quiet href="#ampcontrol">amp-control</a> player) (amps chan))
          (<em class=red>add-player</em> player)))
      (<em class=red>start-playing</em> chans (<a class=quiet href="#srate">srate</a> sound)))))

(play-with-amps 0 1.0 0.5) ;plays channel 2 of stereo sound at half amplitude
</pre>

<p>See play-with-envs in enved.scm, 
play-syncd-marks in marks.scm, start-dac in play.scm,
and add-amp-controls in <a href="sndscm.html#sndmotifdoc">snd-motif.scm</a>.
</p>
<div class="separator"></div>


<!-- make-variable-graph -->
<pre class="indented">
<em class=def id="makevariablegraph">make-variable-graph</em> container name length srate
</pre>

<p>make-variable-graph is a part of the <a href="sndscm.html#variabledisplay">variable-display</a> mechanism in snd-motif.scm.  It creates the
sound/channel pair that displays a graph or spectrum of the arbitrary data accessed via <a href="#channeldata">channel-data</a>.
</p>
<div class="separator"></div>


<!-- map-channel -->
<pre class="indented">
<em class=def id="mapchannel">map-channel</em> func beg dur snd chn edpos origin
</pre>

<p>map-channel is one of the standard ways to change a sound.  It applies 'func' to each sample
replacing the current value with whatever 'func' returns.  
As usual, 'beg' defaults to 0, 'dur' defaults to the full length of the sound,
'snd' and 'chn' default to the currently selected sound, and 'edpos' to the
current edit history list position. 'origin' is the edit history name of the current
operation.
</p>

<p>'func', a procedure of one argument (the current sample),
can return #f, which means that the data passed in is
deleted (replaced by nothing), or a number which replaces the
current sample,
or #t which halts the mapping operation, leaving trailing samples
unaffected, or a float-vector
the contents of which are spliced into the edited version, effectively
replacing the current sample with any number of samples. This sounds
more complicated than it is!  Basically, a map-channel function receives
each sample and returns either #f (no corresponding output), a number
(the new output), or a bunch of numbers.
If every value returned for a given channel is #f, the data is not edited.
Here we add 0.2 to every sample in a channel:
</p>

<pre class="indented">
Scheme:
&gt; (map-channel (lambda (y) (+ y 0.2)))
0

Ruby:
&gt;map_channel(lambda do |y| y + 0.2 end)
-0.0015869140625

Forth:
&gt;lambda: &lt;{ y }&gt; y 0.2 f+ ; map-channel
-0.00158691
</pre>

<p>
In the next sequence, we replace a sound by the difference between successive
samples (a high-pass effect), then undo that by adding them back together,
then check to see how close our reconstruction is to the original:
</p>

<pre class="indented">
&gt; (let ((y0 0.0)) (map-channel (lambda (y) (let ((diff (- y y0))) (set! y0 y) diff))))
0
&gt; (let ((y0 0.0)) (map-channel (lambda (y) (let ((add (+ y y0))) (set! y0 add) add))))
0
&gt; (let ((rd (make-sampler 0 0 0 1 0))) (map-channel (lambda (y) (- y (rd)))))
0          ; the sampler is reading the unedited form of the sound
&gt; (maxamp) ; i.e. how big is the biggest difference
0.0
</pre>

<pre class="indented">
(define* (<em class="noem" id="cosinechannel">cosine-channel</em> (beg 0) dur snd chn edpos)
  (let ((fnc (let* ((samps (or dur (<a class=quiet href="#framples">framples</a> snd chn)))
	            (incr (/ pi samps))
	            (angle (* -0.5 pi)))
               (lambda (y)
                 (let ((val (* y (cos angle))))
	           (set! angle (+ angle incr))
	           val)))))
  (<em class=red>map-channel</em> fnc beg dur snd chn edpos)))
</pre>

<p id="mapsilence">Here's a slightly more involved example;
we define a function that finds silent portions and replaces them with
something:
</p>

<pre class="indented">
(define (map-silence in-silence replacement)
  (let ((buffer (<a class=quiet href="sndclm.html#make-moving-average">make-moving-average</a> 128))
        (silence (/ in-silence 128)))
    (lambda (y)
      (if (> (moving-average buffer (* y y)) silence) y replacement))))

(<em class=red>map-channel</em> (map-silence .01 0.0))  ; squelch background noise
(<em class=red>map-channel</em> (map-silence .001 #f))  ; remove silences altogether
</pre>

<p>Here we're using 'buffer', a CLM <a href="sndclm.html#moving-average">moving-average</a> generator, to track the
RMS value of the last 128 input samples.
When that falls below
the argument 'silence', we replace the current sample with 'replacement'.
It may be easier in complex cases to use with-sound rather than map-channel. 
See <a href="#setsamples">step-src</a> for example.
</p>

<p>It is possible to break out of a map, flushing any edits, via call-with-current-continuation:
</p>

<pre class="indented">
(define ctr 0)
(call-with-current-continuation 
  (lambda (return)
    (<em class=red>map-channel</em> (lambda (val)
                   (set! ctr (+ 1 ctr)) 
                   (if (&gt; ctr 100) 
                     (return "quitting!") 
                     val)))))
</pre>

<p>It is also possible to stop, then continue map-channel:
</p>

<pre class="indented">
(define go-on #f)
(<em class=red>map-channel</em> (lambda (y) 
               (call-with-current-continuation 
                 (lambda (stop) 
                   (if (&gt; y 1.0)
                       (begin 
                         (set! go-on stop) 
                         (error 'oops))))) 
               .2))
</pre>

<p>If this hits a sample &gt; 1.0, it will print 'oops and put the continuation in the variable 'go-on'.
(go-on) will continue where you left off.  (I'm not sure how far this can be pushed, or
whether it's a good idea &mdash; you may end up with unclosed files and so on).
</p>

<p>If the editing action is not mapping something over the current sound, it is
safest to write a temp file with the new data, then pass that to set-samples
with the 'trunc' argument set to #t.  This way you don't assume the new sound
will fit in memory (as in using float-vector-&gt;channel for example).
Use <a href="#sndtempnam">snd-tempnam</a> to get a temporary filename that reflects the current
temp-dir setting.  The env-sound-interp function in <a href="sndscm.html#envsoundinterp">examp.scm</a>
is an example of this. 
</p>

<pre class="indented">
(define* (map-sound-chans proc (beg 0) dur snd edpos origin)
  (do ((i 0 (+ i 1)))
      ((= i (<a class=quiet href="#chans">channels</a> snd)))
    (<em class=red>map-channel</em> proc beg dur snd i edpos origin)))
</pre>

<p>An esoteric aside: map-channel sets up the sampler before calling the procedure, so if that procedure edits
the sound itself (independent of map-channel), the result will be all such edits after the current edit, then the map-channel result
applied to the original (not the newly edited) data.  That is,
</p>
<br>
<pre class="indented">
(let ((first #t)) 
  (<em class=red>map-channel</em> (lambda (y) 
                 (if first (set! (<a class=quiet href="#sample">sample</a> 0) 1.0)) 
                 (set! first #f) 
                 (* y 2))))
</pre>

<p>will return with two edits registered in the edit history list; the map-channel result will be the original data doubled;
the preceding edit in the list will be the <code>(set! (<a class=quiet href="#sample">sample</a> 0) 1.0)</code> which the map-channel ignores.
</p>
<div class="separator"></div>


<!-- maxamp -->
<pre class="indented">
<em class=def id="maxamp">maxamp</em> snd chn edpos
</pre>

<p>This returns the max amp of the given channel, or the overall maxamp of snd if no channel argument is given.
Used with set!, it is equivalent to <a class=quiet href="#scaleto">scale-to</a>.
</p>

<pre class="indented">
(define maxamp-all
  (let ((+documentation+ "(maxamp-all) returns the current maxamp of all currently open sounds"))
    (lambda ()
      (apply max (map (lambda (snd) (apply max (<em class=red>maxamp</em> snd #t))) (<a class=quiet href="#sounds">sounds</a>))))))
</pre>

<!-- INDEX maxampexamples:Maxamps -->

<TABLE class="method">
<tr><th class="title">Maxamps</th></tr><tr><td>
<blockquote id="maxampexamples"><small>
Sound file maxamp: <a href="extsnd.html#mussoundmaxamp">mus-sound-maxamp</a><br>
Region maxamp: <a href="extsnd.html#regionmaxamp">region-maxamp</a><br>
Selection maxamp: <a href="extsnd.html#selectionmaxamp">selection-maxamp</a><br>
To set the y axis bounds to reflect the channel's maxamp: <a href="extsnd.html#ybounds">y-bounds</a><br>
Mix maxamp: <a href="sndscm.html#mixmaxamp">mix-maxamp</a><br>
maxamp locations: <a href="extsnd.html#maxampposition">maxamp-position</a>, <a href="extsnd.html#regionmaxampposition">region-maxamp-position</a>, <a href="extsnd.html#selectionmaxampposition">selection-maxamp-position</a>
</small></blockquote>
</td></tr></TABLE>
<div class="separator"></div>



<!-- maxamp-position -->
<pre class="indented">
<em class=def id="maxampposition">maxamp-position</em> snd chn edpos
</pre>

<p>This gives the location (sample number) of the maximum sample in the given channel.
</p>
<div class="separator"></div>


<!-- max-transform-peaks -->
<pre class="indented">
<em class=def id="maxfftpeaks">max-transform-peaks</em> snd chn
</pre>

<p>This returns the maximum number of transform peaks reported.
The default is 100.  max-transform-peaks affects both the fft display (if <a href="#showtransformpeaks">show-transform-peaks</a>)
and the <a href="#peaks">peaks</a> function.
</p>
<div class="separator"></div>


<!-- min-dB -->
<pre class="indented">
<em class=def id="mindb">min-dB</em> snd chn
</pre>

<p>This sets the minimum dB value displayed in various graphs (the default is -60.0).
Due to problems with arithmetic underflows in sqrt, the spectrum functions set the lowest
actual dB value calculated to -140.0 or -180.0 (depending on which function is called and so on).
</p>
<div class="separator"></div>


<!-- new-sound -->
<pre class="indented">
<em class=def id="newsound">new-sound</em> :file :channels :srate :sample-type :header-type :comment :size
</pre>

<p>new-sound creates a new sound named 'file'.  The following function opens a new sound named "test.snd",
extends it to 'dur' samples, and initializes all samples to 'val':
</p>

<pre class="indented">
(define (init-sound val dur)
  (let ((ind (<em class=red>new-sound</em> "test.snd" :size dur)))
    (<a class=quiet href="#mapchannel">map-channel</a> (lambda (y) val))
    ind))
</pre>

<p>If the 'header-type' and other 
arguments are not specified, they
default to the current <a href="#defaultoutputheadertype">default-output-header-type</a> and 
related settings. sample types are (b=big-endian, l=little, u=unsigned):
</p>

<pre class="indented">
mus-bshort  mus-lshort mus-mulaw  mus-alaw   mus-byte   mus-ubyte   mus-bfloat
mus-lfloat  mus-bint   mus-lint   mus-b24int mus-l24int mus-bdouble mus-ldouble
mus-ubshort mus-ulshort
</pre>

<p>Header-types are:
</p>

<pre class="indented">
mus-next mus-aifc mus-riff mus-rf64 mus-nist mus-raw mus-ircam mus-aiff 
mus-soundfont mus-bicsf mus-voc mus-svx mus-caff
</pre>

<p>To be informed whenever a new sound is created, use <a href="#newsoundhook">new-sound-hook</a> (see ws.scm).
</p>
<div class="separator"></div>


<!-- normalize-channel -->
<pre class="indented">
<em class=def id="normalizechannel">normalize-channel</em> norm beg dur snd chn edpos
</pre>

<p>normalize-channel
scales (changes the amplitude) of a sound so that its new peak amplitude is 'norm'.  This
is the "regularized" form of <a href="#scaleto">scale-to</a>.
The multichannel version is <a href="sndscm.html#normalizesound">normalize-sound</a> in extensions.scm.
</p>
<div class="separator"></div>


<!-- open-raw-sound -->
<pre class="indented">
<em class=def id="openrawsound">open-raw-sound</em> :file :channels :srate :sample-type
</pre>

<p>This opens 'file' as a raw (no header) sound in the layout specified.
If the file has a header, it is not ignored (use (set! (<a class=quiet href="#sampletype">sample-type</a> ...))
and friends to get around this).  If the header is messed up, you can override its settings by
giving the correct values in the call to open-raw-sound.
</p>

<pre class="indented">
(define mpg
  (let ((+documentation+ "(<a class=quiet href="sndscm.html#mpg">mpg</a> file tmpname chans) converts file from MPEG-3 to raw 16-bit samples using mpg123"))
    (lambda (mpgfile rawfile chans)
      (system (<a class=quiet>format</a> #f "mpg123 -s ~A &gt; ~A" mpgfile rawfile))
      (<em class=red>open-raw-sound</em> rawfile 1 44100 (if (<a class=quiet>little-endian?</a>) <a class=quiet href="#sampletype">mus-lshort</a> <a class=quiet href="#sampletype">mus-bshort</a>)))))
</pre>

<p>There's a more elaborate version of this function in examp.scm.  See also <a href="#openrawsoundhook">open-raw-sound-hook</a>.
</p>
<div class="separator"></div>



<!-- open-sound -->
<pre class="indented">
<em class=def id="opensound">open-sound</em> filename
</pre>

<p>open-sound opens 'filename' and returns the sound object; this is equivalent to the File:Open option. <a href="#viewsound">view-sound</a>
opens a sound read-only, or you can set <a class=quiet href="#readonly">read-only</a> by hand. <a class=quiet href="#closesound">close-sound</a>
closes a file opened by open-sound.  There are a variety of hooks that are invoked during the sound opening process:
<a class=quiet href="#duringopenhook">during-open-hook</a>, <a class=quiet href="#openhook">open-hook</a>, 
<a class=quiet href="#afteropenhook">after-open-hook</a>,
<a class=quiet href="#initialgraphhook">initial-graph-hook</a>, <a class=quiet href="#openrawsoundhook">open-raw-sound-hook</a>.  
The sequence of actions is:
</p>

<pre class="indented">
bad header?: <a class=quiet href="#badheaderhook">bad-header-hook</a> &mdash; can cancel request
no header?:  <a class=quiet href="#openrawsoundhook">open-raw-sound-hook</a> &mdash; can cancel request
file ok: 
     <a class=quiet href="#openhook">open-hook</a> &mdash; can change filename
     file opened (no data read yet)
         <a class=quiet href="#duringopenhook">during-open-hook</a> (can set prescaling etc)
     data read, no graphics yet
     <a class=quiet href="#afteropenhook">after-open-hook</a>
     <a class=quiet href="#initialgraphhook">initial-graph-hook</a>
</pre>

<p>There are
other ways to get at sound file data: <a class=quiet href="#makesampler">make-sampler</a> can be given a filename,
rather than a sound; file-&gt;floats in examp.scm; 
and a variety of CLM-based functions such as
<a class=quiet href="sndclm.html#filetosample">file-&gt;sample</a> and
<a class=quiet href="sndclm.html#filetoarray">file-&gt;array</a>.
</p>
<div class="separator"></div>


<!-- pad-channel -->
<pre class="indented">
<em class=def id="padchannel">pad-channel</em> beg dur snd chn edpos
</pre>

<p>pad-channel inserts 'dur' zeros at 'beg' in the given channel. This is the <a class=quiet href="#regularizedargs">regularized</a> 
version of <a href="#insertsilence">insert-silence</a>.  To set a block of samples to zero, use 
<a href="#scalechannel">scale-channel</a> with a scaler of 0.0.
To insert a block of arbitrary-valued samples:
</p>

<pre class="indented">
(define* (<em class="noem">block-channel</em> value (beg 0) dur snd chn edpos)
  (<em class=red>pad-channel</em> beg dur snd chn edpos) ; insert 'dur' samples
  (map-channel (lambda (y) value) beg dur snd chn))
</pre>
<div class="separator"></div>


<!-- pausing -->
<pre class="indented">
<em class=def id="pausing">pausing</em>
</pre>

<p>pausing is #t if sound output is currently paused.  You can unpause the sound by setting pausing to #f,
and pause it by setting pausing to #t.  If you pause a sound (via C-click of the play button, for example),
then call <a href="#play">play</a> (via a key binding perhaps), the sound remains paused by default.  To
cancel the current pause and restart with the new play command:
</p>

<pre class="indented">
(<a class=quiet href="#bindkey">bind-key</a> (char-&gt;integer #\p) 0
  (lambda ()
    (if (<em class=red>pausing</em>) (<a class=quiet href="#stopplaying">stop-playing</a>))
    (<a class=quiet href="#play">play</a>)))
</pre>
<div class="separator"></div>


<!-- peaks -->
<pre class="indented">
<em class=def id="peaks">peaks</em> file snd chn
</pre>

<p>peaks displays fft peak information.  If 'file' is not null, it writes
the information to that file, otherwise it posts the data in a help window.
The maximum number of peaks reported is set
by <a href="#maxfftpeaks">max-transform-peaks</a>.
</p>

<pre class="indented">
(hook-push <a class=quiet href="#aftertransformhook">after-transform-hook</a> 
  (lambda (hook)
    (<em class=red>peaks</em>))) ; post a detailed list of peaks after each FFT
</pre>
<div class="separator"></div>


<!-- play -->
<pre class="indented">
<em class=def id="play">play</em> object :start :end :channel :edit-position :out-channel :with-sync :wait :stop :srate :channels
</pre>

<p>
play plays 'object'.  If no arguments are passed, it plays the currently selected sound.
'object' can be a string (sound filename), a sound object or index, a mix, a region, the selection object, #f, a procedure, or a player.
Not all the keyword arguments apply in all cases, though I hope to fill in the table of possibilities eventually.
'start' is where to start playing (a sample number, defaults to 0).
'end' is where to stop playing.
'channel' is which channel to play (the default is to play all channels).
'edit-position' is which edit history list entry to play, where that is relevant.  The default is the current entry.
'out-channel' is which DAC channel to send the samples to.
'with-sync' sets whether to include all objects sync'd to the current one (default is no, #f).
'wait' sets whether the function call should wait until the play is complete before returning (default is no, #f).
'stop' is a procedure called when the play completes.
'srate' and 'channels' are for one special case, described below.
</p>

<pre class="indented">
(play)                                                       ; play current sound, all chans from start to end
(play 0 :channel 1)                                          ; play just the second channel of sound 0
(play ((selected-sound) <a class=quiet href="#cursor">cursor</a>))                             ; play starting from the cursor
(play (integer-&gt;sound 1) (round (* 3.0 (<a class=quiet href="#srate">srate</a>))) :channel 3) ; play snd 1, chan 3 (4th chan), start at 3.0 secs
(play (selected-sound) 0 :with-sync #t)                      ; play sync'd sounds
(play (selected-sound) 0 :end (round (* 3.0 (<a class=quiet href="#srate">srate</a>))))       ; play from start for 3.0 secs
(play (selected-sound) 0 :edit-position 2)                   ; play the version at edit history position 2
(play (integer-&gt;sound 0) 0 :channel 2 :out-channel 0)        ; play chan 2, but send it to DAC chan 0
(play (selected-sound) (<a class=quiet href="#marksample">mark-sample</a> (integer-&gt;mark 0)) :end (<a class=quiet href="#marksample">mark-sample</a> (integer-&gt;mark 1))); play between marks 0 and 1
(play (selection))                                           ; play the selection
(play #f :srate 44100 :channels 2)                           ; open DAC and run, stop with stop-playing
(play "1a.snd")                                              ; play 1a.snd
(play "1a.snd" 1000 4000)                                    ; play 1a.snd from sample 1000 to 4000
</pre>

<p>
If 'stop' is a procedure of one argument, it is called when the play process stops.
The argument passed to the stop procedure provides the reason the play is stopping; it will be 0 if the play completed normally.
This is intended mainly for looping plays, as in <a href="sndscm.html#playoften">play-often</a>.
</p>

<pre class="indented">
(play (selected-sound) 0 :stop (lambda (reason)              ; if interrupted, say so in the listener
                                 (if (not (= reason 0))
                                     (<a class=quiet href="#sndprint">snd-print</a> ";play interrupted"))))
</pre>

<p>
The 'edit-position' argument makes it easier to try "A:B" comparisons; this plays the version before the latest edit:
</p>

<pre class="indented">
(play (selected-sound) :edit-position (- (<a class=quiet href="#editposition">edit-position</a>) 1))
</pre>

<p>
The following code binds the "p" key to play all channels of the current sound from the cursor, and
the "P" key to play the previous version of the current sound:
</p>

<pre class="indented">
(define (play-from-cursor current)
  (<em class=red>play</em> (selected-sound) (<a class=quiet href="#cursor">cursor</a>) :edit-position (and (not current) (- (<a class=quiet href="#editposition">edit-position</a>) 1))))

(<a class=quiet href="#bindkey">bind-key</a> (char-&gt;integer #\p) 0 
  (lambda () "play from cursor" (play-from-cursor #t) <a class=quiet>keyboard-no-action</a>))

(<a class=quiet href="#bindkey">bind-key</a> (char-&gt;integer #\P) 0 
  (lambda () "play previous version from cursor" (play-from-cursor #f) <a class=quiet>keyboard-no-action</a>))
</pre>

<p id="pfc">
And here we play from the cursor with a moving ("tracking") cursor:
</p>

<pre class="indented">
(define (pfc)
  (let ((old-tracking (<a class=quiet href="#withtrackingcursor">with-tracking-cursor</a>)))
    (set! (<a class=quiet href="#withtrackingcursor">with-tracking-cursor</a>) #t)
    (hook-push <a class=quiet href="#stopplayinghook">stop-playing-hook</a> 
      (lambda (hook)
        (set! (<a class=quiet href="#withtrackingcursor">with-tracking-cursor</a>) old-tracking)))
    (<em class=red>play</em> (selected-sound) (<a class=quiet href="#cursor">cursor</a>))))
</pre>

<p>
If 'object' is #f, the :srate and :channels arguments set up the DAC.
The DAC then stays open until you call <a href="#stopplaying">stop-playing</a>. This is useful
when you're using bind-key and play to trigger sounds, but want the output to have more channels
than the various inputs.
</p>

<pre class="indented">
(bind-key #\o 0 
  (lambda () ; send oboe.snd to chan 0
    (play "oboe.snd" :out-channel 0)))   

(bind-key #\p 0 
  (lambda () ; send pistol.snd to chan 1
    (play "pistol.snd" :out-channel 1))) 

;;; Now open a sound (so you have a non-listener pane to type to)

(play #f :srate 22050 :channels 2) ; srate 22050, 2 output chans

;;; this holds the DAC open indefinitely
;;; Now type o and p in the sound pane until you want to quit, then

(stop-playing) 
</pre>

<p>
Finally, if 'object' is a function, it is called on every sample; if it returns a number, that number is
sent to the DAC; if it returns #f, it stops.  <a href="sndscm.html#playmixes">play-mixes</a> uses this
function option to time the playing of each mix in a sequence of mixes.  Another example is <a href="sndscm.html#playsine">play-sine</a>:
</p>

<pre class="indented">
(define play-sine 
  (let ((+documentation+ "(play-sine freq amp) plays a 1 second sinewave at freq and amp"))
    (lambda (freq amp)
      (let ((len 22050)
            (osc (<a class=quiet href="sndclm.html#make-oscil">make-oscil</a> freq)))
        (<em class=red>play</em> (lambda ()
	        (set! len (- len 1))
	        (and (positive? len)        ; we've sent 22050 samples, so it's time to stop
		     (* amp (<a class=quiet href="sndclm.html#oscil">oscil</a> osc)))))))))
</pre>

<p>Here's another example that plays a sound file, skipping any portion that looks like silence:
</p>

<pre class="indented">
(define (play-skipping-silence file)
  (let ((buffer (make-moving-average 128))
        (silence (/ .001 128))
	(rd (make-sampler 0 file))
	(sum-of-squares 0.0)
	(y 0.0))
    (<em class=red>play</em> (lambda ()
	    (let loop ()
	      (set! y (rd))
	      (set! sum-of-squares (moving-average buffer (* y y)))
	      (and (not (sampler-at-end? rd))
		   (if (&gt; sum-of-squares silence)
		       y
		       (loop))))))))
</pre>

<!-- INDEX playexamples:Playing -->

<TABLE class="method">
<tr><th class="title">Play</th></tr><tr><td>
<blockquote id="playexamples"><small>
play from cursor: C-q and example above<br>
play from cursor with tracking cursor: <a href="extsnd.html#pfc">pfc</a> above<br>
play the selection: (play (selection)), <a href="snd.html#cxp">C-x p</a><br>
play a region: (play region-object), <a href="snd.html#cxp">C-x p</a>, play button in Region dialog<br>
play a mix: (play mix-object), play button in Mix dialog<br>
play a sequence of mixes: <a href="sndscm.html#playmixes">play-mixes</a><br>
play from mark: click or drag triangle (control-click for all chans)<br>
stop playing: C-g, C-t, <a href="extsnd.html#stopplaying">stop-playing</a>, set <a href="extsnd.html#playing">playing</a> to #f<br>
pause or resume playback: space, set <a href="extsnd.html#pausing">pausing</a><br>
play repeatedly: <a href="sndscm.html#playoften">play-often</a><br>
play repeatedly until C-g: <a href="sndscm.html#playuntilcg">play-until-c-g</a><br>
play region repeatedly: <a href="sndscm.html#playregionforever">play-region-forever</a><br>
play a file upon a keystroke: <a href="extsnd.html#extendedpiano">bind-key</a><br>
play using an external program: (system "sndplay wood16.wav")<br>
play a sine-wave or spectrum: <a href="sndscm.html#playsine">play-sine</a> and <a href="sndscm.html#playsines">play-sines</a><br>
play arbitrary mixtures of things: <a href="extsnd.html#makeplayer">make-player</a> and related functions, <a href="sndscm.html#playsyncdmarks">play-syncd-marks</a><br>
play with applied amplitude envelope: <a href="sndscm.html#playwithenvs">play-with-envs</a><br>
play an external file: (play "file")<br>
</small></blockquote>
</td></tr></TABLE>

<p id="stopplayreasons">
The "reasons" that might be passed to the stop-procedure are:
</p>

<pre class="indented">
0    play completed normally	
1    file is being closed	
2    play button unset
3    stop-playing function called	
4    C-g	
5    DAC error (no available channel)
6    play error (audio setup problem)	
7    apply requested (control panel)	
8    file edited
9    C-t
</pre>

<p>
The hooks called during a play operation are:
</p>

<pre class="indented">
when a play request occurs: <a class=quiet href="#startplayinghook">start-playing-hook</a> &mdash; can cancel the request, 
                            also <a class=quiet href="#startplayingselectionhook">start-playing-selection-hook</a>
    (any number of sounds can be playing at once)
as each sound ends: <a class=quiet href="#stopplayinghook">stop-playing-hook</a>, <a class=quiet href="#stopplayingselectionhook">stop-playing-selection-hook</a>
</pre>
<div class="separator"></div>


<!-- player-home -->
<pre class="indented">
<em class=def id="playerhome">player-home</em> player
</pre>

<p>This returns a list of the sound and channel number associated with <a href="#makeplayer">player</a>.
</p>
<div class="separator"></div>


<!-- playing -->
<pre class="indented">
<em class=def id="playing">playing</em>
</pre>

<p>This returns #t if sound output is currently in progress.  You can also start playing by setting playing to #t (equivalent
to calling <a href="#startplaying">start-playing</a> with default arguments), and stop by setting it to #f
(equivalent to <a href="#stopplaying">stop-playing</a>).
</p>
<div class="separator"></div>


<!-- players -->
<pre class="indented">
<em class=def id="players">players</em>
</pre>

<p>This returns a list of currently active <a href="#makeplayer">players</a>.
</p>
<div class="separator"></div>


<!-- player? -->
<pre class="indented">
<em class=def id="playerQ">player?</em> obj
</pre>

<p>This returns #t if 'obj' is an active <a href="#makeplayer">player</a>.
</p>
<div class="separator"></div>


<!-- position->x -->
<pre class="indented">
<em class=def id="positiontox">position-&gt;x</em> xpos snd chn axis
</pre>

<p>This returns the x axis value that corresponds to the graph (screen pixel) position 'xpos'.
To find the sample that the mouse is pointing at, given the current mouse position,
</p>

<pre class="indented">
(round (* (<a class=quiet href="#srate">srate</a> snd) (position-&gt;x x snd chn)))
</pre>
<div class="separator"></div>


<!-- position->y -->
<pre class="indented">
<em class=def id="positiontoy">position-&gt;y</em> ypos snd chn axis
</pre>

<p>This returns the y axis value that corresponds to the graph (screen pixel) position 'ypos'.
</p>
<div class="separator"></div>


<!-- progress-report -->
<pre class="indented">
<em class=def id="progressreport">progress-report</em> pct snd chn
</pre>

<p>The functions <a href="#startprogressreport">start-progress-report</a>, progress-report, and 
<a href="#finishprogressreport">finish-progress-report</a> handle the animated hour-glass icon
that hopes to amuse the idle user while some long computation is in progress.  
The 'pct' argument is a float between 0.0 and 1.0 which indicates how 
far along we are in the computation; there are only 20 separate 
icons, so there's no point in calling this more often than that.  
<a href="#startprogressreport">start-progress-report</a> posts the initial icon, and <a href="#finishprogressreport">finish-progress-report</a> 
removes it.  If the icons are not available, a message is posted in 
the sound's status area using 'name' to identify itself.
</p>
<div class="separator"></div>




<!-- ramp-channel -->
<pre class="indented">
<em class=def id="rampchannel">ramp-channel</em> rmp0 rmp1 beg dur snd chn edpos
</pre>

<p>ramp-channel is a slight extension of scale-channel. It scales samples in the given sound/channel
between 'beg' and 'beg' + 'dur' by a (linear) ramp going from 'rmp0' to 'rmp1'. 
</p>
<div class="separator"></div>


<!-- read-only -->
<pre class="indented">
<em class=def id="readonly">read-only</em> snd
</pre>

<p>This returns #t if 'snd' is read-only, #f otherwise.  If you open
a file with <a href="#viewsound">view-sound</a>, read-only is set to #t.
read-only does not reflect (or affect) the write permission state of the underlying file; it is a way
to keep from accidentally clobbering an otherwise writable file.  
If it is #t (or if the file is not writable), a lock icon is displayed beside the file name.
</p>
<div class="separator"></div>


<!-- redo -->
<pre class="indented">
<em class=def id="redo">redo</em> edits snd chn
</pre>

<p id="redochannel">This re-activates 'edits' edits (the default is 1) in the given channel. 
Redo follows the <a class=quiet href="#sync">sync</a> field if it
is not 0.  The following might be a more reasonable redo function:
</p>

<pre class="indented">
(define* (redo-channel (<a class=quiet href="#edits">edits</a> 1) snd chn)
  (if (and snd (not (= (<a class=quiet href="#sync">sync</a> snd) 0)) chn)
      (set! (<a class=quiet href="#editposition">edit-position</a> snd chn) (+ (<a class=quiet href="#editposition">edit-position</a> snd chn) edits))
      (<em class=red>redo</em> edits snd)))
</pre>

<p>redo moves forward in the edit history list, whereas 
<a href="#undo">undo</a> backs up, and <a href="#revertsound">revert-sound</a> resets the current
edit position to the start of the list.
For more about the edit history list, see <a href="#editlists">Edit Lists</a>.
</p>

<p>In Ruby, redo is a part of the loop handling, so Snd's redo is renamed redo_edit.
redo-edit also exists in Scheme, for consistency.
</p>
<div class="separator"></div>


<!-- reverse-channel -->
<pre class="indented">
<em class=def id="reversechannel">reverse-channel</em> beg dur snd chn edpos
</pre>

<p id="reverseexamples">reverse-channel is the <a class=quiet href="#regularizedargs">regularized</a> version of <a href="#reversesound">reverse-sound</a>.
</p>
<!-- INDEX reverseexamples:Reversing -->

<TABLE class="method">
<tr><th class="title">Reversing</th></tr><tr><td>
<blockquote><small>
reverse channel: <a href="extsnd.html#reversechannel">reverse-channel</a>, <a href="extsnd.html#reversesound">reverse-sound</a><br>
reverse selected portion: <a href="extsnd.html#reverseselection">reverse-selection</a><br>
read samples in reverse: use <a href="extsnd.html#makesampler">make-sampler</a> with direction -1<br>
reverse at new sampling rate: use <a href="extsnd.html#srcchannel">src-channel</a> with a negative ratio<br>
Reverse in control panel: <a href="snd.html#speed">control panel</a> and <a href="extsnd.html#speedcontrol">speed-control</a> variable<br>
reverse an envelope: <a href="sndscm.html#reverseenvelope">reverse-envelope</a><br>
reverse block-wise: <a href="sndscm.html#reversebyblocks">reverse-by-blocks and reverse-within-blocks</a><br>
reverse via FFT: <a href="extsnd.html#sillyreverse">silly-reverse</a><br>
reverse order of channels: <a href="extsnd.html#reversechannels">reverse-channels</a><br>
reverse a list: reverse and reverse!<br>
reverse a string: in Ruby: reverse<br>
reverse float-vector: reverse!<br>
</small></blockquote>
</td></tr></TABLE>
<div class="separator"></div>


<!-- reverse-sound -->
<pre class="indented">
<em class=def id="reversesound">reverse-sound</em> snd chn edpos
</pre>

<p id="sillyreverse">reverse-sound reverses the sound data in the given channel.  There are some interesting non-causal effects you can get with this:
take a voice sound, reverse it, reverberate it, reverse it again, and you get the original with
reversed reverb.  As a hack, you can reverse a sound (modulo a one sample rotation) by doing two ffts
(DSP-ers call this a "flip"):
</p>

<pre class="indented">
(define* (silly-reverse snd)
  (let* ((len (<a class=quiet href="#framples">framples</a> snd 0))
	 (fsize (expt 2 (ceiling (log len 2))))
	 (rl (channel-&gt;float-vector 0 fsize snd 0))
	 (im (make-float-vector fsize)))
    (<a class=quiet href="sndclm.html#fft">mus-fft</a> rl im fsize)
    (<a class=quiet href="sndclm.html#fft">mus-fft</a> rl im fsize)
    (float-vector-scale! rl (/ 1.0 fsize))
    (float-vector-&gt;channel (float-vector-subseq rl (- fsize len) fsize) 0 len snd 0)))
</pre>
<div class="separator"></div>


<!-- revert-sound -->
<pre class="indented">
<em class=def id="revertsound">revert-sound</em> snd
</pre>

<p>This reverts 'snd' to its saved (unedited) state.  A channel-specific version:
</p>

<pre class="indented">
(define* (revert-channel snd chn)
  (set! (<a class=quiet href="#editposition">edit-position</a> snd chn) 0))
</pre>
<div class="separator"></div>


<!-- right-sample -->
<pre class="indented">
<em class=def id="rightsample">right-sample</em> snd chn
</pre>

<p>This returns the position (in samples) of right edge of the time domain waveform.  See <a href="#leftsample">left-sample</a>, 
<a href="#moveonepixel">move-one-pixel</a>, and many examples in examp.scm.
</p>
<div class="separator"></div>


<!-- sample -->
<pre class="indented">
<em class=def id="sample">sample</em> samp snd chn edpos
</pre>

<p>This function gives the value of sample 'samp' in the given channel.
</p>

<pre class="indented">
Scheme: (set! (sample 100) .5)
Ruby:   set_sample(100, 0.5)
Forth:  100 0.5 set-sample
</pre>

<p>'samp' defaults to the current cursor location.  If 'chn' is #t, sample returns a list of all the
samples at 'samp', so:
</p>

<pre class="indented">
(define* (frample samp snd edpos)
  (apply float-vector (sample samp snd #t edpos)))
</pre>

<div class="separator"></div>


<!-- samples -->
<pre class="indented">
<em class=def id="samples">samples</em> samp samps snd chn edpos
</pre>

<p>This returns a float-vector of 'samps' samples starting at 'samp' in the given channel.
'samp' defaults to 0.  'samps' defaults to framples - 'samp' (i.e. read to the end of the data).
'pos' is the edit history position to read (it defaults to the current position).
This is settable (as is <a href="#sample">sample</a>):
</p>

<pre class="indented">
&gt; (samples 1000 10)
#&lt;float-vector[len=10]: 0.033 0.035 0.034 0.031 0.026 0.020 0.013 0.009 0.005 0.004&gt;
&gt; (set! (samples 1000 10) (make-float-vector 10 .1))
#&lt;float-vector[len=10]: 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100&gt;
</pre>
<div class="separator"></div>


<!-- sample-type -->
<pre class="indented">
<em class=def id="sampletype">sample-type</em> snd
</pre>

<p>This returns the sound's sample type &mdash; the encoding used for the sound samples (e.g. mus-bshort).
</p>

<p>The standard formats nowadays are mus-bshort (big-endian 16-bit integers), mus-bfloat
(32-bit big-endian floats), and mus-bint (32-bit big-endian integers), and the
corresponding little-endian versions: mus-lshort, mus-lfloat, and mus-lint.
If you're using an Intel-style PC, you're using a little-endian machine;
Old macs (PowerPC Macs) and Suns use big-endian (NeXT, SGI, and Atari also used it in the good old days).  If you
write a Next file and use little-endian data, some programs other than Snd
may complain; similarly, RIFF wants little-endian and AIFC wants big-endian
data (both can handle the other kind, but most sound-related programs don't know
that).  In the old days, when disk space was at a premium, 8-bit formats
were used a lot: mus-mulaw and mus-alaw (kludges for a kind of 8-bit float),
mus-byte and mus-ubyte (8-bit ints, unsigned in the latter case).  A few
DACs want a particular kind of data, but Snd handles that conversion internally.
Anything less than 12 bits will sound bad &mdash; Perry Cook's book "Real Sound Synthesis"
has examples.  
</p>

<p>If you encounter a file
with an unknown format, or a header that has the wrong format, 
you can set this field to force Snd to interpret the data in any 
way you like.  Similar remarks apply to the <a class=quiet href="#srate">srate</a>, <a class=quiet href="#datalocation">data-location</a>,
<a class=quiet href="#headertype">header-type</a>, and <a class=quiet href="#channels">channels</a> fields.  There are ambiguities in some header
specifications, usually involving big/little endian or signed/unsigned data confusion.
If you encounter a sound that is clipping crazily or is just a burst of noise, try changing these settings.
Some NeXT/Sun (au) header files using byte-wide data
assume the byte is unsigned, whereas most others assume it is signed.  Sndlib
treats it as signed by default, so to make one of the unsigned-byte files playable,
</p>

<pre class="indented">
(set! (sample-type) <a class=quiet href="#sampletype">mus-ubyte</a>)
</pre>

<p>mus_float_t data is another source of confusion;
there is apparently no agreement on whether the data is between -1.0 and 1.0, or -32768.0 and 32767.0 or anything else.
In this case, Snd assumes -1.0 to 1.0 (except in one special case involving IRCAM headers), and you may have to 
set <a class=quiet href="#ybounds">y-bounds</a> to see the actual data.
Yet another gotcha: files with 32-bit integers.  Some programs (Glame, apparently, and perhaps Ardour) assume the fraction is
31 bits wide, others (Snd) use whatever its sample width is configured to be; there is no correct or standard
placement of the fixed point, but not to worry!  Your data is ok:
<code>(set! (<a class=quiet href="#ybounds">y-bounds</a>) (list -256.0 256.0))</code>. 
There are several ways you can handle
these files automatically in Snd.  Perhaps the simplest is to use one of the open hooks:
</p>

<pre class="indented">
(hook-push <a class=quiet href="#afteropenhook">after-open-hook</a> 
  (lambda (hook) 
    ;; this could also (alternatively) set the y-bounds as above
    (if (= (<em class=red>sample-type</em> (hook 'snd)) mus-lint)
        (set! (<em class=red>sample-type</em> (hook 'snd)) mus-lintn))))
</pre>

<p>or (an alternative that sets the underlying database entry, rather than the current in-Snd choice):
</p>

<pre class="indented">
(hook-push <a class=quiet href="#openhook">open-hook</a> 
  (lambda (hook)
    (if (= (<a class=quiet href="#mussoundsampletype">mus-sound-sample-type</a> (hook 'name)) mus-lint)
        (set! (<a class=quiet href="#mussoundsampletype">mus-sound-sample-type</a> (hook 'name)) mus-lintn))))
</pre>

<p>If you set any of these fields, the sound's index may change (there can be an embedded <a class=quiet href="#updatesound">update-sound</a>).
To deal with MPEG, OGG, Flac, or Speex files, see examp.scm (<a class=quiet href="sndscm.html#mpg">mpg</a>) or misc.scm (mpg123 and ogg123).
Octave/WaveLab ASCII files can be translated by read-ascii (examp.scm).
</p>

<p>To turn a sample-type number into a string, use <a href="#mussampletypename">mus-sample-type-name</a>. To get
the sample type of some sound file, use <a href="#mussoundsampletype">mus-sound-sample-type</a>.
The default output (<a class=quiet href="#newsound">new-sound</a>, and
<a class=quiet href="#savesoundas">save-sound-as</a>) sample-type is <a href="#defaultoutputsampletype">default-output-sample-type</a>.
To change a sound file's sample-type, use <a href="#savesoundas">save-sound-as</a>.
</p>
<div class="separator"></div>


<!-- save-sound -->
<pre class="indented">
<em class=def id="savesound">save-sound</em> snd
</pre>

<p id="saveexamples">save-sound saves 'snd', writing the current state of the sound to its underlying sound file, (like the File menu's Save option).
<a href="#savehook">save-hook</a> is invoked upon save-sound.  After save-sound, the sound has no undoable edits in its edit history
(this is different from Emacs, but I find Emac's way of handling this very confusing, and it's never what I want).
</p>

<!-- INDEX saveexamples:Saving -->

<TABLE class="method">
<tr><th class="title">Saving</th></tr><tr><td>
<blockquote><small>
save sound: <a href="extsnd.html#savesound">save-sound</a><br>
save all sounds: (for-each save-sound (sounds))<br>
save a sound under a different name: <a href="extsnd.html#savesoundas">save-sound-as</a><br>
extract one channel from a sound: <a href="extsnd.html#extractchannel">extract-channel</a><br>
extract a set of channels from a sound: <a href="extsnd.html#extractchannels">extract-channels</a><br>
save a sound in a different sample type or header: <a href="extsnd.html#savesoundas">save-sound-as</a><br>
backup edits automatically: <a href="sndscm.html#autosavedoc">autosave</a><br>
check first for unsaved edits: <a href="extsnd.html#askaboutunsavededits">ask-about-unsaved-edits</a><br>
save Snd's complete state (unsaved edits and all): <a href="extsnd.html#savestate">save-state</a>, <a href="extsnd.html#savedir">save-dir</a>, <a href="extsnd.html#savestatehook">save-state-hook</a>, <a href="extsnd.html#savestatefile">save-state-file</a><br>
save the selection: <a href="extsnd.html#saveselection">save-selection</a><br>
save a region: <a href="extsnd.html#saveregion">save-region</a><br>
save a mix: <a href="extsnd.html#savemix">save-mix</a><br>
save the control panel state: <a href="extsnd.html#savecontrols">save-controls</a><br>
save currently defined envelopes (envelope editor): <a href="extsnd.html#saveenvelopes">save-envelopes</a><br>
start the file save dialog: <a href="extsnd.html#savesounddialog">save-sound-dialog</a><br>
start the selection save dialog: <a href="extsnd.html#saveselectiondialog">save-selection-dialog</a><br>
start the region save dialog: <a href="extsnd.html#saveregiondialog">save-region-dialog</a><br>
save the current listener text: <a href="extsnd.html#savelistener">save-listener</a><br>
save marks: <a href="extsnd.html#savemarks">save-marks</a><br>
save just the edit history: <a href="extsnd.html#saveedithistory">save-edit-history</a><br>
take some action upon a window manager save-yourself signal: <a href="sndscm.html#uponsaveyourself">upon-save-yourself</a><br>
save the current sound setup for a later reopen: <a href="extsnd.html#remembersoundstate">remember-sound-state</a><br>
save the current fft peak info: <a href="extsnd.html#peaks">peaks</a><br>
</small></blockquote>
</td></tr></TABLE>
<div class="separator"></div>



<!-- save-sound-as -->
<pre class="indented">
<em class=def id="savesoundas">save-sound-as</em> :file :sound :srate :sample-type :header-type :channel :edit-position :comment
</pre>

<p>This saves 'sound' as 'file' (like the 'File:Save as' menu option).  If 'channel' is specified,
only that channel is saved (it is extracted if necessary from the multichannel original).  
'edit-position', if given, specifies which edit history position to save.
The :srate argument refers only to the new sound file's header's srate field;
the data is not resampled.  If you want to resample the data as it is saved, see
the example under <a href="#beforesaveashook">before-save-as-hook</a>.  If :sample-type
is given, the sound file is written using that sample type.
Any omitted argument's value
is taken from the sound being saved. save-sound-as returns the new file name.
</p>

<pre class="indented">
(save-sound-as "test.snd" :sample-type mus-bdouble :header-type mus-aifc)
</pre>

<p>saves the currently selected sound as an AIFC file using big-endian doubles for the samples.
</p>

<p>To start a parallel editing branch on a given file, you could:
</p>

<pre class="indented">
(save-sound-as "test.snd") (<a class=quiet href="#opensound">open-sound</a> "test.snd")
</pre>

<p id="extractchannel">To define an explicit channel extraction function:
</p><br>

<pre class="indented">
Scheme:
(define (extract-channel filename snd chn) (<em class=red>save-sound-as</em> filename snd :channel chn))

Ruby:
def extract_channel(filename, snd, chn) save_sound_as(filename, snd, :channel, chn) end

Forth:
: extract-channel { filename snd chn } filename snd :channel chn save-sound-as ;
</pre>

<p>The hooks called during a save operation are:
</p>

<pre class="indented">
<a class=quiet href="#beforesaveashook">before-save-as-hook</a> &mdash; can cancel the request or set its output parameters
<a class=quiet href="#savehook">save-hook</a>
    sound saved
      if any sample is clipped during save, <a class=quiet href="#cliphook">clip-hook</a>
<a class=quiet href="#aftersaveashook">after-save-as-hook</a>
</pre>
<div class="separator"></div>


<!-- scale-by -->
<pre class="indented">
<em class=def id="scaleby">scale-by</em> scalers snd chn
</pre>

<p>scale-by <a href="snd.html#scaling">scales</a> the amplitude of 'snd' by 'scalers'.  Unlike most of these functions,
scale-by follows the 'sync' buttons and affects all currently sync'd 
channels. 'scalers' can be either a float, a list, or a float-vector.  
In the latter case, the values are used one by one, applying each as 
scale-by moves through the channels. If 'sync' is off, channel 'chn' 
is scaled (it defaults to the currently selected channel).  <code>(scale-by 2.0)</code> doubles all samples.
</p>
<div class="separator"></div>


<!-- scale-channel -->
<pre class="indented">
<em class=def id="scalechannel">scale-channel</em> scl beg dur snd chn edpos
</pre>

<p>scale-channel 
scales (changes the amplitude) of a sound by 'scl'.
<a href="sndscm.html#channelpolynomial">channel-polynomial</a> is a generalization of the idea.
There are approximately a bazillion ways to scale samples in Snd; here's a potpourri of increasingly silly choices:
</p>

<pre class="indented">
(scale-channel 2.0)
(<a class=quiet href="#scaleby">scale-by</a> 2.0)
(<a class=quiet href="#mapchannel">map-channel</a> (lambda (val) (* val 2.0)))
(set! (<a class=quiet href="#maxamp">maxamp</a>) (* 2 (<a class=quiet href="#maxamp">maxamp</a>)))
(<a class=quiet href="#envsound">env-sound</a> '(0 2 1 2))
(<a class=quiet href="#envchannel">env-channel</a> (<a class=quiet href="sndclm.html#make-env">make-env</a> '(0 1 1 1) :scaler 2.0 :length (<a class=quiet href="#framples">framples</a>)))
(<a class=quiet href="#clmchannel">clm-channel</a> (<a class=quiet href="sndclm.html#make-one-zero">make-one-zero</a> :a0 2.0 :a1 0.0))
(<a class=quiet href="#filterchannel">filter-channel</a> (float-vector 2.0) 1)
(float-vector-&gt;channel (float-vector-scale! (channel-&gt;float-vector) 2.0) 0)
(begin (<a class=quiet href="#selectall">select-all</a>) (<a class=quiet href="#mixselection">mix-selection</a> 0))
(begin (<a class=quiet href="#selectall">select-all</a>) (<a class=quiet href="#scaleselectionby">scale-selection-by</a> 2.0))
(begin (<a class=quiet href="#savesoundas">save-sound-as</a> "temp.snd") (<a class=quiet href="#mix">mix</a> "temp.snd" 0) (delete-file "temp.snd"))

(let ((flt (make-float-vector 8)))
  (set! (flt 0) 2.0)
  (let ((cnv (<a class=quiet href="sndclm.html#make-convolve">make-convolve</a> :filter flt))
	(sf (<a class=quiet href="#makesampler">make-sampler</a> 0)))
    (<a class=quiet href="#mapchannel">map-channel</a>
     (lambda (val)
       (<a class=quiet href="sndclm.html#convolve">convolve</a> cnv (lambda (dir) 
                       (<a class=quiet href="#readsample">read-sample</a> sf)))))))

(float-vector-&gt;channel (<a class=quiet href="sndscm.html#polydoc">poly*</a> (channel-&gt;float-vector 0 (<a class=quiet href="#framples">framples</a>)) (float-vector 2.0))) ; poly.scm (sound = polynomial coeffs)

(let* ((len (<a class=quiet href="#framples">framples</a>))
       (fsize (expt 2 (ceiling (/ (log len) (log 2)))))
       (rl (channel-&gt;float-vector 0 fsize))
       (im (make-float-vector fsize)))
  (<a class=quiet href="sndclm.html#fft">mus-fft</a> rl im fsize)
  (<a class=quiet href="sndclm.html#fft">mus-fft</a> rl im fsize)
  (<a class=quiet href="sndclm.html#fft">mus-fft</a> rl im fsize)
  (<a class=quiet href="sndclm.html#fft">mus-fft</a> rl im fsize)
  (float-vector-&gt;channel (float-vector-scale! rl (/ 2.0 (* fsize fsize))) 0 len))

(do ((i 0 (+ i 1)))
    ((= i (<a class=quiet href="#framples">framples</a>)))
  ;; don't actually do this! &mdash; it involves a separate edit on each sample
  (set! (<a class=quiet href="#sample">sample</a> i) (* 2 (<a class=quiet href="#sample">sample</a> i))))

(let ((make-scaler 
       (lambda (start end)
	 (letrec ((ctr start)
		  (us (lambda (them)
			(set! (<a class=quiet href="#sample">sample</a> ctr) (* 2.0 (<a class=quiet href="#sample">sample</a> ctr)))
			(set! ctr (+ ctr 2))
			(if (&lt;= ctr end)
			    (them us)))))
	   us))))
  ((make-scaler 0 (<a class=quiet href="#framples">framples</a>)) 
     (make-scaler 1 (<a class=quiet href="#framples">framples</a>))))
</pre>
<div class="separator"></div>

<!-- another method that is a bit too verbose: array-interp with a ramp of slope 2
     a similar table of ways to make a sine wave?
     sin oscil Table-lookup polyshape ifft(spike) firmant(r=1.0), ssb-am+? formulas?
-->




<!-- scale-to -->
<pre class="indented">
<em class=def id="scaleto">scale-to</em> norms snd chn
</pre>

<p>scale-to <a href="snd.html#scaling">normalizes</a> 'snd' to 'norms' (following <a class=quiet href="#sync">sync</a> as in <a href="#scaleby">scale-by</a>).
(scale-to 0.5) scales the current channel so that its maxamp is 0.5.
If all the sound's samples are 0.0, scale-to returns #f and does not perform any edit.
'norms' can be a number, a list of numbers, or a float-vector.
</p>
<div class="separator"></div>



<!-- scan-channel -->
<pre class="indented">
<em class=def id="scanchannel">scan-channel</em> func beg dur snd chn edpos
</pre>

<p>scan-channel is obsolete; use a do loop with a sampler:
</p>

<pre class="indented">
(define* (scan-channel func (beg 0) dur snd chn edpos)
  (let ((end (if dur (min (+ beg dur) (framples snd chn)) (framples snd chn)))
	(rd (make-sampler beg snd chn 1 edpos)))
    (do ((pos beg (+ pos 1)))
        ((or (&gt;= pos end)
	     (func (next-sample rd)))
         (and (&lt; pos end)
	      pos)))))
</pre>

<p>scan-channel "scans" the data in the specified channel between the given sample numbers (the default
is the entire sound) by applying 'func' to each sample.
If 'func' returns something other than #f, the scan is halted, 
and the current sample number is returned.
The following call scans the
current channel looking for any sample greater than .1:
</p>

<pre class="indented">
&gt; (scan-channel (lambda (y) (&gt; y .1)))
4423
</pre>

<div class="separator"></div>


<!-- selected-channel -->
<pre class="indented">
<em class=def id="selectedchannel">selected-channel</em> snd
</pre>

<p>This gives the selected channel in 'snd'; you can set it to select a channel.  It returns #f is no channel is selected in 'snd'. 
</p>
<div class="separator"></div>


<!-- selected-sound -->
<pre class="indented">
<em class=def id="selectedsound">selected-sound</em>
</pre>

<p>This returns the currently selected sound; you can set it to select a sound. It returns #f is there is no selected sound. 
</p>

<pre class="indented">
(or (<a class=quiet href="#selectedsound">selected-sound</a>)
    (and (pair? (<a class=quiet href="#sounds">sounds</a>))
         (car (<a class=quiet href="#sounds">sounds</a>))))
</pre>

<p>returns the currently selected sound, if any, and failing that, any other sound that is currently open.
</p>
<div class="separator"></div>


<!-- select-channel -->
<pre class="indented">
<em class=def id="selectchannel">select-channel</em> chn
</pre>

<p>This selects channel 'chn' in the currently selected sound;
equivalent to (set! (<a class=quiet href="#selectedchannel">selected-channel</a>) chn). 
See also <a href="#selectchannelhook">select-channel-hook</a>.
</p>
<div class="separator"></div>


<!-- select-sound -->
<pre class="indented">
<em class=def id="selectsound">select-sound</em> snd
</pre>

<p>This selects sound 'snd' (a sound object or an index); equivalent to (set! (<a class=quiet href="#selectedsound">selected-sound</a>) snd).
See also <a href="#selectsoundhook">select-sound-hook</a>.
</p>
<div class="separator"></div>


<!-- set-samples -->
<pre class="indented">
<em class=def id="setsamples">set-samples</em> samp samps data snd chn trunc edname infile-chan edpos auto-delete
</pre>

<p>set-samples (and its equivalent form <code>(set! (samples...)...)</code>) set the given channel's samples starting from
sample 'samp' for 'samps' samples to the values in 'data'.
</p>

<pre class="indented">
(set! (samples 0 100) (make-float-vector 100 .1))
(set-samples 0 100 (make-float-vector 100 .1))
</pre>

<p>both change all samples between 0 and 100 to be 0.1. 
If 'samp' is beyond the end of the file, the file is first zero-padded to reach it.
'data' can be a filename.  
</p>

<pre class="indented">
(set-samples 10000 20000 "oboe.snd")
</pre>

<p>replaces 10000 samples with data from oboe.snd.
If 'data' is a float-vector, set-samples is identical to <a href="#fvtochannel">float-vector-&gt;channel</a>.
If 'trunc' is #t and 'samp' is 0, the
sound is truncated (if necessary) to reflect the end of 'data'.
If the in-coming data file has more than one channel, 'infile-chan'
sets which input file to read. The in-coming data file is not deleted by Snd
unless 'auto-delete' is #t.  (If you write a temporary sound
as an edit, it can be non-obvious when it is safe to delete that
file; 'auto-delete' set to #t asks Snd to handle cleanup).
</p>

<p>The form (set! (<a class=quiet href="#samples">samples</a> samp samps 'snd chn trunc edname infile-chan edpos auto-delete') data) can also be used.
</p>

<pre class="indented">
(define (step-src)
  (let* ((rd (<a class=quiet href="#makesampler">make-sampler</a> 0))
	 (o (<a class=quiet href="sndclm.html#make-oscil">make-oscil</a> 2205.0))
	 (s (<a class=quiet href="sndclm.html#make-src">make-src</a> :srate 0.0))
	 (incr (+ 2.0 (<a class=quiet href="sndclm.html#oscil">oscil</a> o)))	  
	 (tempfile (<em class=red>with-sound</em> (:output (<a class=quiet href="#sndtempnam">snd-tempnam</a>) :srate (<a class=quiet href="#srate">srate</a>) :to-snd #f)
		     (do ((samp 0 (+ 1 samp)))
			 ((<a class=quiet href="#sampleratendQ">sampler-at-end?</a> rd))
		       (<a class=quiet href="sndclm.html#out-any">out-any</a> samp (<a class=quiet href="sndclm.html#src">src</a> s incr (lambda (dir) (<a class=quiet href="#readsample">read-sample</a> rd))) 0)
		       (if (= (modulo samp 2205) 0)
			   (set! incr (+ 2.0 (<a class=quiet href="sndclm.html#oscil">oscil</a> o))))))))
    (<em class=red>set-samples</em> 0 (- (<a class=quiet href="#mussoundframples">mus-sound-framples</a> tempfile) 1) tempfile #f #f #t "step-src" 0 #f #t)))
</pre>
<div class="separator"></div>


<!-- short-file-name -->
<pre class="indented">
<em class=def id="shortfilename">short-file-name</em> snd
</pre>

<p>This returns the brief (no directory) form of the sound's filename.
</p>

<pre class="indented">
&gt; (open-sound "oboe.snd")
#&lt;sound 0&gt;
&gt; (file-name (integer-&gt;sound 0))
"/home/bil/cl/oboe.snd"
&gt; (short-file-name (integer-&gt;sound 0))
"oboe.snd"
</pre>
<div class="separator"></div>


<!-- show-axes -->
<pre class="indented">
<em class=def id="showaxes">show-axes</em> snd chn
</pre>

<p>This determines what axes are displayed.
If show-axes is show-all-axes (the default), both the x and y axes are displayed; if it is show-x-axis, 
just one (bottom) x axis is displayed, reducing screen clutter. 
show-no-axes omits both x and y axes.  To remove the x axis label, use
either show-x-axis-unlabelled or show-all-axes-unlabelled.
To omit all the x axis labels and ticks (but include the y axis as usual) use show-bare-x-axis.
This is the View:Axes choice.
</p>
<div class="separator"></div>


<!-- show-grid -->
<pre class="indented">
<em class=def id="showgrid">show-grid</em> snd chn
</pre>

<p>If show-grid is #t (the default is #f), a background grid is displayed (default is #f).  See also <a href="#griddensity">grid-density</a>.
</p>

<img class="indented" src="pix/grid.png" alt="grid">
<div class="separator"></div>

<!--
./snd -horizontal now.snd now.snd
(set! (grid-density 1) 0.2)
(set! (selected-graph-color) (make-color 1 1 1))
(set! (selected-data-color) (make-color 0 0 0))
(set! (x-axis-label 1 0) "grid-density: 0.2")
(set! (x-axis-label 1 0) "grid-density: 0.2")
-->



<!-- show-marks -->
<pre class="indented">
<em class=def id="showmarks">show-marks</em> snd chn
</pre>

<p>If show-marks is #t (the default), marks are displayed.  This is the '<a href="snd.html#marks">Show marks</a>' View menu option.
</p>
<div class="separator"></div>


<!-- show-mix-waveforms -->
<pre class="indented">
<em class=def id="showmixwaveforms">show-mix-waveforms</em> snd chn
</pre>

<p>If show-mix-waveforms is #t (the default), a mixed sound is displayed as a separate waveform above the main data.  The rectangular tag
at the start of the waveform can be dragged to move the mix, or clicked to select it for the mix dialog.
</p>
<div class="separator"></div>


<!-- show-sonogram-cursor -->
<pre class="indented">
<em class=def id="showsonogramcursor">show-sonogram-cursor</em> snd chn
</pre>

<p>If show-sonogram-cursor is #t (the default is #f), the cursor is also displayed in the sonogram.
</p>
<div class="separator"></div>


<!-- show-transform-peaks -->
<pre class="indented">
<em class=def id="showtransformpeaks">show-transform-peaks</em> snd chn
</pre>

<p>If show-transform-peaks is #t (the default is #f), transform peak information is included in the transform display.
This is the 'peaks' button in the <a href="snd.html#viewfft">Transform</a> options dialog.
</p>
<div class="separator"></div>


<!-- show-y-zero -->
<pre class="indented">
<em class=def id="showyzero">show-y-zero</em> snd chn
</pre>

<p>If show-y-zero is #t (the default is #f), the y=0 axis is displayed.  This is the '<a href="snd.html#viewy0">Show Y=0</a>' View menu option.
</p>
<div class="separator"></div>


<!-- smooth-channel -->
<pre class="indented">
<em class=def id="smoothchannel">smooth-channel</em> beg dur snd chn edpos
</pre>

<p>smooth-channel is the <a class=quiet href="#regularizedargs">regularized</a> version of <a href="#smoothsound">smooth-sound</a>.
</p>

<!-- INDEX smoothexamples:Smoothing -->

<TABLE class="method">
<tr><th class="title">Smoothing</th></tr><tr><td>
<blockquote id="smoothexamples"><small>
smooth channel: <a href="extsnd.html#smoothchannel">smooth-channel</a><br>
smooth all channels: <a href="extsnd.html#smoothsound">smooth-sound</a><br>
smooth selection: <a href="extsnd.html#smoothselection">smooth-selection</a><br>
delete the selection and smooth the splice: <a href="extsnd.html#deleteselectionandsmooth">delete-selection-and-smooth</a><br>
smoothing via fft: <a href="sndscm.html#fftsmoother">fft-smoother</a><br>
smooth via low-pass <a href="extsnd.html#filtersinsnd">filter</a><br>
smooth over click: <a href="sndscm.html#removeclicks">remove-clicks</a> in examp.scm<br>
</small></blockquote>
</td></tr></TABLE>
<div class="separator"></div>



<!-- smooth-sound -->
<pre class="indented">
<em class=def id="smoothsound">smooth-sound</em> beg num snd chn
</pre>

<p>smooth-sound applies a smoothing function to the indicated data.  This produces a sinusoid between
the end points:
</p>

<pre class="indented">
(define (smoother y0 y1 num)
   (do ((v (make-float-vector (+ 1 num))) 
	(angle (if (&gt; y1 y0) pi 0.0)) 
	(off (* .5 (+ y0 y1))) 
	(scale (* 0.5 (abs (- y1 y0))))
        (i 0 (+ i 1)))
       ((= i num) v)
     (set! (v i) (+ off (* scale (cos (+ angle (* i (/ pi num)))))))))
</pre>

<img class="indented" src="pix/click.png" alt="smoother">

<p>For a fancier version, see fft-smoother in examp.scm.  See also <a href="sndscm.html#removeclicks">remove-clicks</a> in examp.scm.
</p>
<div class="separator"></div>


<!-- sound? -->
<pre class="indented">
<em class=def id="soundp">sound?</em> snd
</pre>

<p>sound? returns #t if 'snd' refers to an open sound.
</p>
<div class="separator"></div>


<!-- soundfont-info -->
<pre class="indented">
<em class=def id="soundfontinfo">soundfont-info</em> snd
</pre>

<p>This returns a list of lists describing 'snd' as a soundfont.  Each inner list
consists of the sound name, start point, loop start, and loop end.
</p>

<pre class="indented">
&gt; (soundfont-info)
(("BrSteel_E4" 0 65390 65458) ("BrSteel_B2" 65490 131458 131637) ...)
</pre>

<p>To set a named mark at the start of each sound with un-named marks 
at the loop points:
</p>
<pre class="indented">
(define (mark-sf2)
  (for-each (lambda (vals)
              (let ((m1 (add-mark (cadr vals))))
                (set! (mark-name m1) (car vals)))
              (add-mark (caddr vals))
              (add-mark (cadddr vals)))
    (soundfont-info)))
</pre>

<img class="indented" src="pix/bongo.png" alt="soundfont marks">

<p>See also explode-sf2 in examp.scm.
</p>
<div class="separator"></div>


<!-- sound->integer -->
<pre class="indented">
<em class=def id="soundtointeger">sound-&gt;integer</em> sound
</pre>

<p>This is the counterpart to <a href="#integertosound">integer-&gt;sound</a>.
</p>
<div class="separator"></div>


<!-- sound-loop-info -->
<pre class="indented">
<em class=def id="soundloopinfo">sound-loop-info</em> snd
</pre>

<p>This gives info about loop points from the sound's header.  The loop info is a list of
up to 4 points, the first two (start, end) refer to the sustain loop,
the second two to the release.  The 5th and 6th list entries are the base note and detune values.
For historical reasons, the 7th and 8th entries are the sustain and release modes.
This is similar to <a href="#mussoundloopinfo">mus-sound-loop-info</a> (but it's settable).  See explode-sf2 in examp.scm.
</p>

<pre class="indented">
&gt; (sound-loop-info)
(24981 144332 0 0 60 0 1 0)
</pre>
<div class="separator"></div>


<!-- sound-properties -->
<pre class="indented">
<em class=def id="soundproperties">sound-properties</em> snd
</pre>

<p>This is a property list associated with the given sound.  It is set to () at the time a sound is opened.  The accessor
is <a href="#soundproperty">sound-property</a>.  There are several
examples of using it in snd-motif.scm and autosave.scm.
</p>
<div class="separator"></div>


<!-- sound-property -->
<pre class="indented">
<em class=def id="soundproperty">sound-property</em> key snd
</pre>

<p>sound-property provides access to a sound's <a href="#soundproperties">property list</a>.
These properties are saved when Snd's state is saved (via <a href="extsnd.html#savestate">save-state</a>
or the Options:Save session menu).  To omit a given property at that time, add its name (a symbol) to
the property 'save-state-ignore (a list of symbols); see 'inset-envelope in extensions.scm.
</p>
<div class="separator"></div>


<!-- sounds -->
<pre class="indented">
<em class=def id="sounds">sounds</em>
</pre>

<p>sounds returns a list of currently active sounds.
A common Snd trope is (map func (sounds)): 
</p>

<pre class="indented">
(map maxamp (sounds))
</pre>

<p>Or, if
the return value is not needed:
</p>

<pre class="indented">
(for-each (lambda (snd) (display (<a class=quiet href="#shortfilename">short-file-name</a> snd))) (sounds))
</pre>

<p>This can be
extended to provide a complete list of sounds and channels (since many Snd functions
take the "snd chn" arguments):
</p>

<pre class="indented">
(define (all-chans)
  (let ((sndlist ())
        (chnlist ()))
    (for-each (lambda (snd)
                (do ((i (- (<a class=quiet href="#channels">channels</a> snd) 1) (- i 1)))
                    ((&lt; i 0))
                  (set! sndlist (cons snd sndlist))
                  (set! chnlist (cons i chnlist))))
              (<em class=red>sounds</em>))
    (list sndlist chnlist)))

(apply map <a class=quiet href="#maxamp">maxamp</a> (all-chans))
</pre>
<div class="separator"></div>


<!-- spectrum-end -->
<pre class="indented">
<em class=def id="spectrumend">spectrum-end</em> snd chn
</pre>

<p>This is the amount of the frequency domain to include in the spectrum 
display (the default is 1.0 = all of it). 
spectrum-end the slider labelled '% of spectrum' in the View 
Orientation dialog. See zoom-fft in examp.scm.
</p>
<div class="separator"></div>


<!-- spectro-hop -->
<pre class="indented">
<em class=def id="spectrohop">spectro-hop</em> snd chn
</pre>

<p>This is the distance (in pixels) moved between successive spectrogram traces 
(default is 4).  spectro-hop is the 'hop' slider in the Color/Orientation dialog.
</p>
<div class="separator"></div>


<!-- spectrum-start -->
<pre class="indented">
<em class=def id="spectrumstart">spectrum-start</em> snd chn
</pre>

<p>This is the start point of the frequency domain in the spectrum
display (default is 0.0).  See zoom-fft in examp.scm.
</p>
<div class="separator"></div>


<!-- spectro-x-angle -->
<pre class="indented">
<em class=def id="spectroxangle">spectro-x-angle</em> snd chn
</pre>

<p>This is the spectrogram x-axis viewing angle (the default is 90.0 except in GL where it is 300.0).  See snd-gl.scm.
</p>
<div class="separator"></div>


<!-- spectro-x-scale -->
<pre class="indented">
<em class=def id="spectroxscale">spectro-x-scale</em> snd chn
</pre>

<p>This is the scaler (stretch amount) along the spectrogram x axis (the is default 1.0, in GL: 1.5).
</p>
<div class="separator"></div>


<!-- spectro-y-angle -->
<pre class="indented">
<em class=def id="spectroyangle">spectro-y-angle</em> snd chn
</pre>

<p>This is the spectrogram y axis viewing angle (the default is 0.0, in GL: 320.0).
</p>
<div class="separator"></div>


<!-- spectro-y-scale -->
<pre class="indented">
<em class=def id="spectroyscale">spectro-y-scale</em> snd chn
</pre>

<p>This is the scaler (stretch amount) for the spectrogram y axis (the default is 1.0).
</p>
<div class="separator"></div>


<!-- spectro-z-angle -->
<pre class="indented">
<em class=def id="spectrozangle">spectro-z-angle</em> snd chn
</pre>

<p>This is the spectrogram viewing angle for the z axis (the default is 358.0, in GL: 0.0).
</p>
<div class="separator"></div>


<!-- spectro-z-scale -->
<pre class="indented">
<em class=def id="spectrozscale">spectro-z-scale</em> snd chn
</pre>

<p>This is the scaler (stretch amount) for the z axis (the default is 0.1, in GL: 1.0).
</p>
<div class="separator"></div>


<!-- squelch-update -->
<pre class="indented">
<em class=def id="squelchupdate">squelch-update</em> snd chn
</pre>

<p>This is #t if graphic updates are currently squelched (turned off).  If you're doing a sequence of edits where intermediate
states aren't of great interest, you can save time by turning off redisplays.
</p>

<pre class="indented">
(define (without-graphics thunk)
  (set! (<em class=red>squelch-update</em>) #t)
  (let ((val (catch #t thunk (lambda args (car args)))))
    (set! (<em class=red>squelch-update</em>) #f)
    val))
</pre>
<div class="separator"></div>


<!-- srate -->
<pre class="indented">
<em class=def id="srate">srate</em> snd
</pre>

<p>This is the sound's sampling rate.  If you set this to a new value, update-sound is called to
reflect the new srate, but any current edits are flushed.  This is consistent
with the other header fields (sample-type, etc), but it can be annoying.
</p>

<p>There are several srates floating around in Snd.  
<code>(srate snd)</code> returns the sampling rate of a particular (currently open) sound. 
<code>(<a class=quiet href="#mussoundsrate">mus-sound-srate</a> filename)</code>
returns a sound file's sampling rate.  
*clm-srate* (also known as mus-srate) is associated with the CLM package (setting the implicit srate for oscil etc).  
default-output-srate is the default sampling rate used when opening new files.  
enved-srate is a constant that can be assigned to the envelope editor's enved-target (to apply an envelope to the sampling rate).  
region-srate is the sampling rate associated with a region.  
</p>
<div class="separator"></div>


<!-- src-channel -->
<pre class="indented">
<em class=def id="srcchannel">src-channel</em> num-or-env beg dur snd chn edpos
</pre>

<p id="resampleexamples">src-channel preforms sampling rate conversion using 'warped sinc interpolation'.  The
argument 'num-or-env' can be a number, an envelope, or a CLM env generator.
(src-channel 2.0) makes the sound go twice as fast.
This is the <a class=quiet href="#regularizedargs">regularized</a> version of <a href="#srcsound">src-sound</a>.
</p>

<pre class="indented">
&gt; (framples)                  ; current duration
50828
&gt; (src-channel 2.0)         ; make it half as long
2.0
&gt; (framples)
25415
&gt; (src-channel '(0 .5 1 1)) ; start slow and speed up
(0 0.5 1 1)
&gt; (framples)
35235
&gt; (src-channel (make-env '(0 .5 1 1) :length 20000)) ; stick at 1 after sample 20000
#&lt;env linear, pass: 35236 (dur: 20000), index: 1, scaler: 1.0000, offset: 0.0000, ...&gt;
&gt; (framples)
42964
</pre>


<!-- INDEX resampleexamples:Resampling -->

<TABLE class="method">
<tr><th class="title">Resampling</th></tr><tr><td>
<blockquote><small>
resample channel: <a href="extsnd.html#srcchannel">src-channel</a><br>
resample all chans: <a href="extsnd.html#srcsound">src-sound</a><br>
resample selection: <a href="extsnd.html#srcsoundselection">src-selection</a><br>
resample mix: speed control in <a href="snd.html#mixdialog">Mix dialog</a> (also <a href="extsnd.html#applycontrols">apply-controls</a>)<br>
resample via drawn envelope: srate in <a href="snd.html#editenvelope">Envelope editor</a><br>
resample via CLM gen: <a href="sndclm.html#src">src</a><br>
resample with independent time control (ssb-am): <a href="sndscm.html#ssbbank">ssb-bank</a> in dsp.scm<br>
resample with independent time control (granulate): expand in <a href="extsnd.html#customcontrols">control panel</a>, <a href="sndscm.html#expsrc">expsrc</a> and <a href="sndscm.html#expsnd">expsnd</a><br>
resample with independent time control (vocoder): <a href="sndclm.html#phase-vocoder">phase-vocoder</a> (this never works)<br>
another time stretcher (autocorrelation):<a href="sndscm.html#rubbersound">rubber-sound</a> (this takes forever and rarely works)<br>
resampling-based sound effects: <a href="sndscm.html#hellodentist">hello-dentist</a>, <a href="sndscm.html#fp">fp</a>, flange and chorus in dsp.scm and new-effects.scm<br>
the digital zipper: <a href="sndscm.html#zipdoc">zipper</a><br>
resample via FFT: <a href="sndscm.html#downoct">down-oct</a><br>
resample through env: <a href="sndscm.html#soundinterp">sound-interp</a> and <a href="sndscm.html#envsoundinterp">env-sound-interp</a><br>
resample through list: <a href="sndscm.html#scratch">scratch</a><br>
resample step-size through a function: <a href="extsnd.html#setsamples">step-src</a><br>
predict duration of resampled sound: <a href="sndscm.html#srcduration">src-duration</a><br>
linear src: linear-src-channel in dsp.scm<br>
</small></blockquote>
</td></tr></TABLE>
<div class="separator"></div>



<!-- src-sound -->
<pre class="indented">
<em class=def id="srcsound">src-sound</em> num-or-env base snd chn edpos
</pre>

<p>src-sound performs sampling rate conversion using 'warped sinc interpolation'.  The
argument 'num-or-env', which sets the ratio between the old and the new srate, can be either a number or an envelope.  
In the latter case, 'base' sets the segment base (the default is 1.0 = linear).
A value greater than 1.0 causes the sound to be transposed up.
A value less than 0.0 causes the sound to be reversed. 
(src-sound 2.0) speeds the sound up by a factor
of 2 (transposes it up an octave), whereas (src-sound 0.5)
slows it down by the same factor (transposes it down an octave).
(src-sound '(0 1 1 2)) starts at the original speed, then
gradually increases until, at the end of the sound, it is going
twice as fast.
</p>

<p>'num-or-env' can also be a CLM env generator (its duration should
be the same as the original sound, and its segments should not pass through 0.0).  The following function can be used to predict
how long the resultant note will be given an src envelope:
</p>

<pre class="indented">
;;; find new duration of sound after using env as srate.
;;; the envelope gives the per-sample increment, so the "tempo"
;;;   is the inverse of that. To get the total new duration,
;;;   we need to integrate the inverse envelope, but a straight
;;;   line in the increment envelope becomes a 1/x curve in the
;;;   tempo curve, so we use log(x) as integral of 1/x and
;;;   take into account the local notion of "x".

(define (<em class="noem">src-duration</em> e)
  (let* ((len (length e))
	 (all-x (- (e (- len 2)) (e 0)))) ; last x - first x
    (do ((dur 0.0)
         (i 0 (+ i 2)))
	((&gt;= i (- len 2)) dur)
      (let* ((x0 (e i))
	     (x1 (e (+ i 2)))
	     (y0 (e (+ i 1))) ; 1/x x points
	     (y1 (e (+ i 3)))
	     (area (if (&lt; (abs (- y0 y1)) .0001)
		       (/ (- x1 x0) (* y0 all-x))
		       (/ (* (- (log y1) (log y0)) (- x1 x0))
			  (* (- y1 y0) all-x)))))
	(set! dur (+ dur (abs area)))))))

;;; (src-duration '(0 1 1 2)) -&gt; 0.693147180559945
:;; (src-duration '(0 1 1 .5)) -&gt; 1.38629436111989
;;; (src-duration '(0 .5 .5 3 .6 1 .7 .1 .8 1.5 1 1)) -&gt; 1.02474349685432

;;; here we're using this in the Snd listener:
&gt; (framples)
220501
&gt; (src-duration '(0 1 1 2))
0.693147180559945
&gt; (src-sound '(0 1 1 2)) ; should be about .693 * 220500 framples 
(0 1 1 2)
&gt; (framples)
152842
&gt; (/ 152842.0 220501)
0.693157854159392       ; tada!
</pre>

<p>The inverse, so to speak, of this is <a href="sndscm.html#srcfitenvelope">src-fit-envelope</a>:
</p>

<pre class="indented">
(define (src-fit-envelope e target-dur)
  (scale-envelope e (/ (src-duration e) target-dur)))
</pre>
<div class="separator"></div>


<!-- start-playing -->
<pre class="indented">
<em class=def id="startplaying">start-playing</em> chans srate background
</pre>

<p>If a <a href="#makeplayer">play-list</a> is waiting, this starts it.  'chans' defaults to 1, 
'srate' defaults to 44100, 'background' defaults to #t. See play.scm or marks.scm.
</p>
<div class="separator"></div>


<!-- start-progress-report -->
<pre class="indented">
<em class=def id="startprogressreport">start-progress-report</em> snd chn
</pre>

<p>This starts a <a href="#progressreport">progress-report</a>.
</p>
<div class="separator"></div>


<!-- status-report -->
<pre class="indented">
<em class=def id="statusreport">status-report</em> msg snd
</pre>

<p>This posts 'msg' in the sound's status area.  The status area is the text widget between the sound's filename and the buttons
on the right, beneath the graph.  
If 'snd' is not a currently open sound, the message is sent to the listener, if it is open. 
If there is no sound or listener, 'msg' is sent to stderr.
</p>
<div class="separator"></div>


<!-- stop-player -->
<pre class="indented">
<em class=def id="stopplayer">stop-player</em> player
</pre>

<p>This removes 'player' from the current play-list (see <a href="#makeplayer">make-player</a>).
</p>
<div class="separator"></div>


<!-- stop-playing -->
<pre class="indented">
<em class=def id="stopplaying">stop-playing</em> snd
</pre>

<p>If 'snd' is playing, this stops it.
If no argument is given, it stops all playback.  See play.scm,
<a href="#stopplayinghook">stop-playing-hook</a>, or <a href="#stopplayingselectionhook">stop-playing-selection-hook</a>.
</p>
<div class="separator"></div>


<!-- swap-channels -->
<pre class="indented">
<em class=def id="swapchannels">swap-channels</em> snd1 chn1 snd2 chn2 beg dur edpos0 edpos1
</pre>

<p id="reversechannels">This swaps the indicated channels, between 'beg' and 'beg' + 'dur'. 
In simple cases, this is a virtual operation.  swap-channels can be used to change channel order arbitrarily.
For example, the following function reverses the channel order:
</p>

<pre class="indented">
(define* (reverse-channels snd)
  (let* ((ind (or snd (<a class=quiet href="#selectedsound">selected-sound</a>) (car (<a class=quiet href="#sounds">sounds</a>))))
	 (chns (<a class=quiet href="#channels">channels</a> ind))
         (swaps (floor (/ chns 2))))
    (<a class=quiet href="#asoneedit">as-one-edit</a>
     (lambda ()
       (do ((i 0 (+ i 1))
	    (j (- chns 1) (- j 1)))
	   ((= i swaps))
	 (<em class=red>swap-channels</em> ind i ind j))))))
</pre>

<p>Channel rotation is similar, though slightly more work; see scramble-channels in examp.scm.
Since swap-channels is a virtual operation in many cases, it's worth using it even
where just a channel copy is desired; <a href="sndscm.html#monotostereo">mono-&gt;stereo</a>
in extensions.scm for an example.  
Another example is swap-selection-channels in examp.scm.
</p>
<div class="separator"></div>


<!-- sync -->
<pre class="indented">
<em class=def id="sync">sync</em> snd
</pre>

<p>sync returns the sound's 'sync' value (an integer, 0 = not sync'd). Several functions (<a href="#scaleby">scale-by</a>, for example), apply to the
currently selected sound and also to any other sounds that share its sync value.  (I later decided that
this was a bad idea, hence the regularized replacements).  Sounds that share a given sync value 
move together when you drag an x-axis slider and so on.
</p>
<div class="separator"></div>


<!-- sync-max -->
<pre class="indented">
<em class=def id="syncmax">sync-max</em>
</pre>

<p>This is the maximum <a href="#sync">sync</a> setting seen so far &mdash; it provides a painless way to get a sync value that
is guaranteed to be unique. To sync all currently open sounds:
</p>

<pre class="indented">
(let ((new-sync (+ 1 (<em class=red>sync-max</em>))))
  (for-each (lambda (snd) (set! (<a class=quiet href="#sync">sync</a> snd) new-sync)) (<a class=quiet href="#sounds">sounds</a>)))
</pre>
<div class="separator"></div>


<!-- time-graph? -->
<pre class="indented">
<em class=def id="timegraphp">time-graph?</em> snd chn
</pre>

<p>This is #t if the time domain graph is being displayed (the 'w' button).
</p>
<div class="separator"></div>


<!-- time-graph-style -->
<pre class="indented">
<em class=def id="timegraphstyle">time-graph-style</em> snd chn
</pre>

<p>This determines how time-domain data is displayed.
The choices are:
</p>

<pre class="indented">
graph-lines  graph-dots  graph-filled  graph-lollipops  graph-dots-and-lines

(set! (time-graph-style 0 4) graph-lollipops)
</pre>
<img class="indented" src="pix/graphstyle.png" alt="graph styles">

<div class="separator"></div>


<!--
(with-sound (:channels 5) (do ((i 0 (+ i 1))) ((= i 5)) (fm-violin 0 .4 (* (+ i 1) 100) .1 :degree (* i 72))))
(do ((i 0 (+ i 1))) ((= i 5)) (set! (time-graph-style 0 i) i))
(set! (dot-size) 4)
(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) "graph-lines")
(set! (x-axis-label 0 1 0) "graph-dots")
(set! (x-axis-label 0 2 0) "graph-filled")
(set! (x-axis-label 0 3 0) "graph-dots-and-lines")
(set! (x-axis-label 0 4 0) "graph-lollipops")
-->


<!-- time-graph-type -->
<pre class="indented">
<em class=def id="timegraphtype">time-graph-type</em> snd chn
</pre>

<p>If time-graph-type is graph-as-wavogram, the time domain waveform is displayed as a 
'<a href="snd.html#wavogram">wavogram</a>'.
The default is graph-once.  See also <a href="#wavohop">wavo-hop</a> and <a href="#wavotrace">wavo-trace</a>.
</p>
<div class="separator"></div>


<!-- tracking-cursor-style -->
<pre class="indented">
<em class=def id="trackingcursorstyle">tracking-cursor-style</em> snd chn
</pre>

<p>This is the <a href="#cursorstyle">cursor-style</a> in effect when the cursor is tracking playback (<a href="#withtrackingcursor">with-tracking-cursor</a>).
tracking-cursor-style can be cursor-cross or cursor-line (the default).  If you want some other shape, 
use the function choice for cursor-style (that function's third argument can tell you when you're tracking).
</p>
<div class="separator"></div>


<!-- transform-framples -->
<pre class="indented">
<em class=def id="transformframples">transform-framples</em> snd chn
</pre>

<p>This returns either 0 if there is no transform, <a href="#transformsize">transform-size</a> if 
<a href="#transformgraphtype">transform-graph-type</a> is graph-once,
or (list spectrum-end time-slices fft-bins) if either a sonogram or a spectrogram is being displayed.
</p>

<pre class="indented">
&gt; (set! (transform-graph?) #t) ; turn on fft display
#t
&gt; (transform-framples)
512
&gt; (set! (transform-graph-type) graph-as-sonogram)
1                             ; 1 = graph-as-sonogram
&gt; (transform-framples)
(1.0 375 256)                 ; 1.0 -&gt; full spectrum displayed
&gt; (set! (transform-graph?) #f) ; turn off fft display
#f
&gt; (transform-framples)
0
</pre>
<div class="separator"></div>


<!-- transform-graph? -->
<pre class="indented">
<em class=def id="transformgraphp">transform-graph?</em> snd chn
</pre>

<p>This is #t if the given channel is displaying a spectrum (the 'f' button).
</p>
<div class="separator"></div>


<!-- transform-graph-style -->
<pre class="indented">
<em class=def id="transformgraphstyle">transform-graph-style</em> snd chn
</pre>

<p>This determines how frequency-domain data is displayed.
The choices are:
</p>

<pre class="indented">
graph-lines  graph-dots  graph-filled  graph-lollipops  graph-dots-and-lines 
</pre>
<div class="separator"></div>


<!-- transform-graph-type -->
<pre class="indented">
<em class=def id="transformgraphtype">transform-graph-type</em> snd chn
</pre>

<p>This determines the choice of spectral display.  The choices are (default) graph-once (a single FFT), 
graph-as-sonogram, and graph-as-spectrogram.
The sonogram is a set of FFTS taken at regular time intervals displayed as time vs frequency, using the
width or color of the spectral portion to indicate its amplitude.  The spectrogram is similar, but uses
a 3D effect where the height of the line corresponds to its amplitude.
Currently, the <a href="#fftlogfrequency">fft-log-frequency</a> and <a href="#normalizefft">transform-normalization</a>
choices are ignored by the spectrogram display.
If you've included openGL in Snd, the spectrogram will use openGL if <a href="#withgl">with-gl</a> is #t (the
default).
</p>
<div class="separator"></div>


<!-- transform-normalization -->
<pre class="indented">
<em class=def id="normalizefft">transform-normalization</em> snd chn
</pre>

<p>This is the transform normalization choice (default: normalize-by-channel).
If it is normalize-by-channel or normalize-by-sound, spectral data is 
normalized to 1.0 before display. If dont-normalize, you get the 
raw data values, which can reflect amplitude changes &mdash; Snd tries to 
choose a y axis limit that makes successive displays move smoothly. 
The other choice is normalize-globally (i.e. across all sounds).
</p>
<div class="separator"></div>


<!-- transform-sample -->
<pre class="indented">
<em class=def id="transformsample">transform-sample</em> bin slice snd chn
</pre>

<p>This is the current value of the transform (if any) in 'bin' and (if a 
sonogram or spectrogram) 'slice' in the given channel.  
</p>
<div class="separator"></div>


<!-- transform-size -->
<pre class="indented">
<em class=def id="transformsize">transform-size</em> snd chn
</pre>

<p>This is the fft size (the default size is 512).  It should be a power of 2.
If your version of Snd was built with FFTW, and you set transform-size
too large (on my machine, with 2 GBytes of memory,
(expt 2 26) is apparently too large), FFTW exits Snd!  There is currently
no way to trap the error.  Also, FFTW assumes the fft size is a (signed) int &mdash; 2^30 is probably
the transform-size limit.
</p>
<div class="separator"></div>


<!-- transform-type -->
<pre class="indented">
<em class=def id="transformtype">transform-type</em> snd chn
</pre>

<p>This is the spectrum transform type (the default is fourier-transform).
</p>

<pre class="indented">
fourier-transform  wavelet-transform   haar-transform
autocorrelation    walsh-transform     cepstrum     
</pre>
<div class="separator"></div>


<!-- transform->float-vector -->
<pre class="indented">
<em class=def id="transformtofv">transform-&gt;float-vector</em> snd chn v
</pre>

<p>This returns a float-vector with the transform data from the given channel.
If 'v' (a float-vector) is provided, it is filled, rather than creating a new one.
See <a href="#fftpeak">fft-peak</a> for an example.
</p>
<div class="separator"></div>


<!-- undo -->
<pre class="indented">
<em class=def id="undo">undo</em> edits snd chn
</pre>

<p id="undochannel">This undoes 'edits' edits (the default is 1) in the given channel.
Undo follows the <a class=quiet href="#sync">sync</a> field if it
is not 0.  The following might be a more reasonable undo function:
</p>

<pre class="indented">
(define* (undo-channel (<a class=quiet href="#edits">edits</a> 1) snd chn)
  (if (and snd (not (= (<a class=quiet href="#sync">sync</a> snd) 0)) chn)
      (set! (<a class=quiet href="#editposition">edit-position</a> snd chn) 
         (max 0 (- (<a class=quiet href="#editposition">edit-position</a> snd chn) edits)))
      (<em class=red>undo</em> edits snd)))
</pre>

<p id="undoexamples">See also <a href="#undohook">undo-hook</a>.
Since redo collides with Ruby, forcing me to change its name to redo_edit,
undo can also be accessed under the name undo_edit (in Scheme, undo-edit).
</p>

<!-- INDEX undoexamples:Undo and Redo -->

<TABLE class="method">
<tr><th class="title">Undo</th></tr><tr><td>
<blockquote><small>
undo edit: <a href="extsnd.html#undo">undo</a> and <a href="extsnd.html#undochannel">undo-channel</a><br>
undo all edits: <a href="extsnd.html#revertsound">revert-sound</a><br>
specialize undo: <a href="extsnd.html#undohook">undo-hook</a><br>
protect against undo: <a href="extsnd.html#edithook">edit-hook</a><br>
redo edit: <a href="extsnd.html#redo">redo</a> and <a href="extsnd.html#redochannel">redo-channel</a><br>
move around in edit list: <a href="extsnd.html#editposition">edit-position</a> and <a href="extsnd.html#currenteditposition">current-edit-position</a><br>
About edit lists: <a href="extsnd.html#editlists">Edit lists</a>
</small></blockquote>
</td></tr></TABLE>
<div class="separator"></div>



<!-- update-lisp-graph -->
<pre class="indented">
<em class=def id="updatelispgraph">update-lisp-graph</em> snd chn
</pre>

<p>This forces Snd to redisplay 'chn's' lisp graph.  See <a href="sndscm.html#enveddoc">enved.scm</a> which uses the lisp graph as a local envelope editor.
</p>
<div class="separator"></div>


<!-- update-sound -->
<pre class="indented">
<em class=def id="updatesound">update-sound</em> snd
</pre>

<p>This causes Snd to update 'snd' (it re-reads the data from disk, flushing any pending edits).  In some cases (primarily involving
a change in the number of channels), update-sound can change the index of the sound referred to by 'snd'.
See <a href="#updatehook">update-hook</a> for a way to deal with the index confusion.
</p>
<div class="separator"></div>


<!-- update-time-graph -->
<pre class="indented">
<em class=def id="updatetimegraph">update-time-graph</em> snd chn
</pre>

<p>This forces Snd to redisplay 'chn's' time domain graph.  See color-samples in draw.scm.
</p>
<div class="separator"></div>


<!-- update-transform-graph -->
<pre class="indented">
<em class=def id="updatetransformgraph">update-transform-graph</em> snd chn
</pre>

<p>This forces Snd to redisplay 'chn's' fft graph.  For historical reasons, it also forces the current transform to completion.  
</p>
<div class="separator"></div>



<!-- variable-graph? -->
<pre class="indented">
<em class=def id="variablegraphp">variable-graph?</em> index
</pre>

<p>This returns #t if 'index' refers to a variable graph (see <a href="#makevariablegraph">make-variable-graph</a>).
</p>
<div class="separator"></div>



<!-- view-sound -->
<pre class="indented">
<em class=def id="viewsound">view-sound</em> filename
</pre>

<p>This opens 'filename' read-only (you can edit the sound within Snd, but you can't overwrite the original sound).
</p>
<div class="separator"></div>


<!-- wavelet-type -->
<pre class="indented">
<em class=def id="wavelettype">wavelet-type</em> snd chn
</pre>

<p>If <a href="#transformtype">transform-type</a> is wavelet-transform, wavelet-type selects which 
wavelet is used.  The list of available wavelets is in the Transform 
Dialog. There are around 48 choices, so this variable goes from 
0 to 47 (the default is 0).
</p>
<div class="separator"></div>


<!-- wavo-hop -->
<pre class="indented">
<em class=def id="wavohop">wavo-hop</em> snd chn
</pre>

<p>This sets the distance upward (in pixels) between wavogram traces; that is,
the smaller this number, the more traces can be displayed (the default is 3).  See <a href="#timegraphtype">time-graph-type</a>.
</p>
<div class="separator"></div>


<!-- wavo-trace -->
<pre class="indented">
<em class=def id="wavotrace">wavo-trace</em> snd chn
</pre>

<p>This sets the length (in samples) of each wavogram trace (the default is 64).  See <a href="#timegraphtype">time-graph-type</a>.
</p>
<div class="separator"></div>


<!-- with-verbose-cursor -->
<pre class="indented">
<em class=def id="withverbosecursor">with-verbose-cursor</em> snd chn
</pre>

<p>If with-verbose-cursor is #t, the cursor's position and other information is constantly 
displayed in the status area.  This is the View:Verbose cursor option 
(default: #f). 
</p>
<div class="separator"></div>


<!-- x-axis-label -->
<pre class="indented">
<em class=def id="xaxislabel">x-axis-label</em> snd chn context
</pre>

<p>This is the current x axis label. 'context' is one of time-graph (the default), lisp-graph, or 
transform-graph.
</p>

<pre class="indented">
&gt; (x-axis-label)
"time"
&gt; (set! (x-axis-label) "tempus")
"tempus"
</pre>
<div class="separator"></div>


<!-- x-axis-style -->
<pre class="indented">
<em class=def id="xaxisstyle">x-axis-style</em> snd chn
</pre>

<p>x-axis-style is the View menu 'X-axis units' option (the default value is x-axis-in-seconds). 
The x axis labelling of the time domain waveform can be in seconds
(x-axis-in-seconds), in samples (x-axis-in-samples), expressed
as a percentage of the overall duration (x-axis-as-percentage, useful in envelope definitions), as a beat number (x-axis-in-beats),
as a measure number (x-axis-in-measures), or in digital clock format (DD:HH:MM:SS.ddd) (x-axis-as-clock, useful in
very large files).
When the x axis labelling is in measures, the label has the form M(B)F or M(B) where M is the one-based
measure number (that is, the first measure, at time 0.0, is measure 1), B is the one-based beat number
within that measure, and F (if present) is the location within that beat on a scale of 0.0 to 1.0.
If a major tick marks a measure beginning, and there are non-measure minor ticks, then the measure
is distinguished from the beat by having a longer tick mark.
</p>
<div class="separator"></div>


<!-- x-bounds -->
<pre class="indented">
<em class=def id="xbounds">x-bounds</em> snd chn axis
</pre>

<p>This returns (list x0 x1), the current x axis bounds in seconds.  To display the entire sound:
</p>

<pre class="indented">
(set! (x-bounds) (/ (<a class=quiet href="#framples">framples</a>) (<a class=quiet href="#srate">srate</a>)))
</pre> 
<div class="separator"></div>


<!-- x->position -->
<pre class="indented">
<em class=def id="xtoposition">x-&gt;position</em> x snd chn axis
</pre>

<p>This returns the graph (screen pixel) position that corresponds to the x axis value 'x'. 
'axis' is one of time-graph (the default), lisp-graph, or transform-graph.
See draw.scm for an example.
</p>
<div class="separator"></div>


<!-- x-position-slider -->
<pre class="indented">
<em class=def id="xpositionslider">x-position-slider</em> snd chn
</pre>

<p>
This is the value of x axis position slider.  See zoom-fft in examp.scm.
</p>
<div class="separator"></div>


<!-- x-zoom-slider -->
<pre class="indented">
<em class=def id="xzoomslider">x-zoom-slider</em> snd chn
</pre>

<p>This is the value of x axis zoom slider.  See <a href="#zoomonepixel">zoom-one-pixel</a>.
</p>
<div class="separator"></div>


<!-- xramp-channel -->
<pre class="indented">
<em class=def id="xrampchannel">xramp-channel</em> rmp0 rmp1 base beg dur snd chn edpos
</pre>

<p>xramp-channel is a slight extension of <a href="#rampchannel">ramp-channel</a>. It scales samples in the given sound/channel
between 'beg' and 'beg' + 'dur' by an exponential ramp going from 'rmp0' to 'rmp1' with the connecting segment curvature
set by 'base'.
</p>

<pre class="indented">
(xramp-channel 0.0 1.0 32.0)
</pre>
<div class="separator"></div>


<!-- y-axis-label -->
<pre class="indented">
<em class=def id="yaxislabel">y-axis-label</em> snd chn context
</pre>

<p>This is the current y axis label. 'context' is one of time-graph (the default), lisp-graph, or transform-graph.
</p>
<div class="separator"></div>


<!-- y-bounds -->
<pre class="indented">
<em class=def id="ybounds">y-bounds</em> snd chn axis
</pre>

<p>This returns (list y0 y1), the current y axis bounds.
To set the bounds to reflect the channel's maxamp, use (set! (y-bounds) ()).
To set all channels at once using the selected sound's maxamp:
</p>

<pre class="indented">
(let ((maxval (apply max (<a class=quiet href="#maxamp">maxamp</a> #f #t)))) 
  (do ((i 0 (+ i 1))) 
      ((= i (<a class=quiet href="#chans">channels</a>))) 
    (set! (<em class=red>y-bounds</em> #f i) (list (- maxval) maxval))))
</pre>

<p>Or to set each channel to its own maxamp:
</p>

<pre class="indented">
(do ((i 0 (+ i 1))) 
    ((= i (<a class=quiet href="#chans">channels</a>)))
  (let ((maxval (<a class=quiet href="#maxamp">maxamp</a> #f i))) 
    (set! (<em class=red>y-bounds</em> #f i) (list (- maxval) maxval))))
</pre>
<div class="separator"></div>


<!-- y->position -->
<pre class="indented">
<em class=def id="ytoposition">y-&gt;position</em> y snd chn axis
</pre>

<p>This returns the graph (screen pixel) position that corresponds to the y axis value 'y'. 
'axis' is one of time-graph (the default), lisp-graph, or transform-graph.
This is used in samples-via-colormap in draw.scm to draw the time domain samples in many colors.
</p>
<div class="separator"></div>


<!-- y-position-slider -->
<pre class="indented">
<em class=def id="ypositionslider">y-position-slider</em> snd chn
</pre>

<p>This is the value of y axis position slider.  See zync in snd-motif.scm.
</p>
<div class="separator"></div>


<!-- y-zoom-slider -->
<pre class="indented">
<em class=def id="yzoomslider">y-zoom-slider</em> snd chn
</pre>

<p>This is the value of y axis zoom slider.  See <a href="#xdisplayenergy">display-energy</a>, or zync in snd-motif.scm.
</p>
<div class="separator"></div>


<!-- zero-pad -->
<pre class="indented">
<em class=def id="zeropad">zero-pad</em> snd chn
</pre>

<p>zero-pad is the fft zero pad size as a multiple of the fft size; (set! (zero-pad) 1)
gives you half data, half zeros (the default value is 0).  The data length is 
determined by the nominal transform-size.  Zero padding causes interpolation 
of the fft points, making the display look smoother.
</p>

<pre class="indented">
(<a class=quiet href="#bindkey">bind-key</a> (char-&gt;integer #\p) 0 
  (lambda () 
    (set! (zero-pad) (+ (<em class=red>zero-pad</em>) 1)) 
    (<a class=quiet href="#updatetransformgraph">update-transform-graph</a>)))

(<a class=quiet href="#bindkey">bind-key</a> (char-&gt;integer #\m) 0 
  (lambda () 
    (set! (zero-pad) (- (<em class=red>zero-pad</em>) 1)) 
    (<a class=quiet href="#updatetransformgraph">update-transform-graph</a>)))
</pre>

<img class="indented" src="pix/pad1.png" alt="more pads">






<div class="innerheader" id="customcontrols">the control panel</div>

<p>The control panel makes it easy to try out various sound effects without
editing anything.  You can change volume ('amp'), pitch ('speed'), tempo
('expand'), reverb amount ('reverb'), simulated room size ('reverb len'),
brightness ('contrast'), and dullness ('filter').  To treat a current
setting as an edit operation, call <a href="#applycontrols">apply-controls</a>.  For more on
the effects themselves (and a pretty picture!), see the discussion in <a href="snd.html#controls">snd.html</a>.
</p>

<p>
The control panel normally processes samples as follows: if the sampling
rate conversion is on (the 'Speed' control is not 1.0), it applies srate
conversion to the incoming sample; the next stage is the expansion function,
if the 'Expand' toggle button is set; this value is passed
next to the Contrast function, if it is running, and then the result
is scaled by the Amp slider's value.  The filter is run next, if
it's on, and finally the sample is scaled by the reverb slider and
passed to the reverb, if any, which adds its result to the sample;
the final result is sent to the speakers.
The control panel procedures are:
</p>
<div class="spacer"></div>
<!--  CONTROL PANEL  -->

<!-- amp-control -->
<pre class="indented">
<em class=def id="ampcontrol">amp-control</em> snd chn
</pre>

<p>The current amp value.
It is possible to use these controls (in "real-time") in your own functions.
See amprt in <a href="sndscm.html#exampdoc">examp.scm</a> for an example,
or add-amp-control in snd-motif.scm.
As an experiment, I added the optional 'chn' argument; if it is specified, the
channel's local amp-control value is set instead of the sound's.  This affects
<a class=quiet href="#applycontrols">apply-controls</a> and playback.
</p>
<div class="spacer"></div>


<!-- amp-control-bounds -->
<pre class="indented">
<em class=def id="ampcontrolbounds">amp-control-bounds</em> snd
</pre>

<p>The amp-control min and max amounts as a list.  The default is
(list 0.0 8.0).  The value 1.0 should be in the given range, since it is placed in the middle of the slider's range.
If no 'snd' argument is given, this also affects the Mix and View:Files dialogs.
</p>
<div class="spacer"></div>


<!-- apply-controls -->
<pre class="indented">
<em class=def id="applycontrols">apply-controls</em> snd target beg dur
</pre>

<p>Apply the current control panel state as an edit.
'target' can be 0=sound, 1=channel, 2=selection.
'beg' sets where in samples the apply starts: (apply-controls 0 0 (<a class=quiet href="#marksample">mark-sample</a> m)) starts from the given mark.
'dur', if given, sets how many samples to run through the apply process (the input duration).
apply-controls can be used in conjunction with the various control panel variables:
</p>

<table>
<tr><td>
<div class="scheme">
<pre class="indented">
(define (expnd amt)
  (set! (<a class=quiet href="#expandcontrolp">expand-control?</a>) #t) 
  (set! (<a class=quiet href="#expandcontrol">expand-control</a>) amt) 
  (<em class=red>apply-controls</em>))
</pre>
</div>
</td></tr>
<tr><td>
<div class="ruby">
<pre class="indented">
def expnd(amt)
  set_expand_control? true
  set_expand_control amt
  apply_controls
end
</pre>
</div>
</td></tr>
<tr><td>
<div class="forth">
<pre class="indented">
: expnd ( amt -- ) { amt }
  #t set-expand-control? drop
  amt set-expand-control drop
  apply-controls
;
</pre>
</div>
</td></tr></table>

<p>For many examples see new-effects.scm.
</p>
<div class="spacer"></div>


<!-- controls->channel -->
<pre class="indented">
<em class=def id="controlstochannel">controls-&gt;channel</em> settings beg dur snd chn origin
</pre>

<p>This sets up the sound's controls to reflect 'settings' (unspecified settings are not changed), then applies the controls as
an edit of channel 'chn'. The 'settings' argument is a list where each entry can also be #f or an empty list:
</p>

<pre class="indented">
(list amp speed
  (list contrast contrast_amp)
  (list expand expand_length expand_ramp expand_hop expand_jitter)
  (list reverb_scale reverb_length reverb_feedback reverb_low_pass reverb_decay)
  (list filter_order filter_env))
</pre>
<div class="spacer"></div>


<!-- contrast-control -->
<pre class="indented">
<em class=def id="contrastcontrol">contrast-control</em> snd
</pre>

<p>The <a class=quiet href="snd.html#contrast">contrast</a> amount.
The <a href="sndclm.html#contrast-enhancement">contrast-enhancement</a> algorithm treats this variable as a kind of modulation index (the higher, the brighter),
whereas contrast-control-amp below prescales the in-coming signal to be closer to -1.0 to 1.0
(the brightening effect works best if it has a full amplitude signal to work with).
</p>
<div class="spacer"></div>


<!-- contrast-control-amp -->
<pre class="indented">
<em class=def id="contrastcontrolamp">contrast-control-amp</em> snd
</pre>

<p>The <a class=quiet href="snd.html#contrast">contrast-control-amp</a> (a prescaler on the contrast-enhancement to get the
full effect of the compander).
</p>
<div class="spacer"></div>


<!-- contrast-control-bounds -->
<pre class="indented">
<em class=def id="contrastcontrolbounds">contrast-control-bounds</em> snd
</pre>

<p>The contrast-control min and max amounts as a list.  The default is
(list 0.0 10.0).
</p>
<div class="spacer"></div>


<!-- contrast-control? -->
<pre class="indented">
<em class=def id="contrastcontrolp">contrast-control?</em> snd
</pre>

<p>#t if the <a class=quiet href="snd.html#contrast">contrast</a> button is set (i.e. the contrast compander is active).
</p>
<div class="spacer"></div>


<!-- expand-control -->
<pre class="indented">
<em class=def id="expandcontrol">expand-control</em> snd
</pre>

<p>The <a class=quiet href="snd.html#expand">expansion</a> amount.  This sets the ratio between the
output and input grain spacing.  If it is greater than 1.0, the result is longer.
</p>
<div class="spacer"></div>


<!-- expand-control-bounds -->
<pre class="indented">
<em class=def id="expandcontrolbounds">expand-control-bounds</em> snd
</pre>

<p>The expand-control min and max amounts as a list.  The default is
(list 0.001 20.0).
</p>
<div class="spacer"></div>


<!-- expand-control-hop -->
<pre class="indented">
<em class=def id="expandcontrolhop">expand-control-hop</em> snd
</pre>

<p>The <a class=quiet href="snd.html#expand">expansion</a> hop amount in seconds (the distance between successive grains).
</p>
<div class="spacer"></div>


<!-- expand-control-jitter -->
<pre class="indented">
<em class=def id="expandcontroljitter">expand-control-jitter</em> snd
</pre>

<p>The <a class=quiet href="snd.html#expand">expansion</a> grain timing jitter.  This defaults to .1; if you set it
to too small a number (0.0 for example), you'll probably notice (presumably unwanted) notch-filter effects.
</p>
<div class="spacer"></div>


<!-- expand-control-length -->
<pre class="indented">
<em class=def id="expandcontrollength">expand-control-length</em> snd
</pre>

<p>The <a class=quiet href="snd.html#expand">expansion</a> segment (grain) length in seconds.  The longer the grain,
the more reverberated or slurred the effect.
</p>
<div class="spacer"></div>


<!-- expand-control-ramp -->
<pre class="indented">
<em class=def id="expandcontrolramp">expand-control-ramp</em> snd
</pre>

<p>The <a class=quiet href="snd.html#expand">expansion</a> ramp amount (between 0 and .5).
This affects the smoothness of the grain overlaps &mdash; .001 gives a 
rattling effect.
</p>
<div class="spacer"></div>


<!-- expand-control? -->
<pre class="indented">
<em class=def id="expandcontrolp">expand-control?</em> snd
</pre>

<p>#t if the expand button is set (i.e. the expansion effect is active).
</p>
<div class="spacer"></div>


<!-- filter-control-coeffs -->
<pre class="indented">
<em class=def id="filtercontrolcoeffs">filter-control-coeffs</em> snd
</pre>

<p>The <a class=quiet href="snd.html#filtercontrol">filter</a> coefficients (read-only currently).  It is
a float-vector suitable for use with the <a href="sndclm.html#filter">filter generator</a> or with
<a href="#filtersound">filter-sound</a>.
</p>
<div class="spacer"></div>


<!-- filter-control-envelope -->
<pre class="indented">
<em class=def id="filtercontrolenvelope">filter-control-envelope</em> snd
</pre>

<p>The <a class=quiet href="snd.html#filtercontrol">filter</a> (frequency response) envelope (a list of breakpoints).
</p>
<div class="spacer"></div>


<!-- filter-control-in-dB -->
<pre class="indented">
<em class=def id="filtercontrolindB">filter-control-in-dB</em> snd
</pre>

<p>The <a class=quiet href="snd.html#filtercontrol">filter</a> dB button.  If #t, the filter (frequency) envelope
graph is displayed in dB.
</p>
<div class="spacer"></div>


<!-- filter-control-in-hz -->
<pre class="indented">
<em class=def id="filtercontrolinhz">filter-control-in-hz</em> snd
</pre>

<p>If #t, the filter frequency response envelope x axis is in Hz, otherwise 0 to 1.0 (where 1.0 corresponds to srate/2).
</p>
<div class="spacer"></div>


<!-- filter-control-order -->
<pre class="indented">
<em class=def id="filtercontrolorder">filter-control-order</em> snd
</pre>

<p>The <a class=quiet href="snd.html#filtercontrol">filter</a> order.  This affects how much computing
is needed to run the filter, and how close the filter can get to the desired frequency response envelope.
</p>
<div class="spacer"></div>


<!-- filter-control-waveform-color -->
<pre class="indented">
<em class=def id="filterwaveformcolor">filter-control-waveform-color</em>
</pre>

<p>The filter frequency response waveform color.
</p>
<div class="spacer"></div>


<!-- filter-control? -->
<pre class="indented">
<em class=def id="filtercontrolp">filter-control?</em> snd
</pre>

<p>#t if the filter button is set (i.e. the filter is active).
</p>
<div class="spacer"></div>


<!-- reset-controls -->
<pre class="indented">
<em class=def id="resetcontrols">reset-controls</em> snd
</pre>

<p>Set all the controls to their default state.
</p>
<div class="spacer"></div>


<!-- restore-controls -->
<pre class="indented">
<em class=def id="restorecontrols">restore-controls</em> snd
</pre>

<p>Set all the
controls to the last saved state.
</p>
<div class="spacer"></div>


<!-- reverb-control-decay -->
<pre class="indented">
<em class=def id="reverbdecay">reverb-control-decay</em> snd
</pre>

<p>The length (in seconds) of the reverberation after the sound has 
finished (default: 1.0).
</p>
<div class="spacer"></div>


<!-- reverb-control-feedback -->
<pre class="indented">
<em class=def id="reverbcontrolfeedback">reverb-control-feedback</em> snd
</pre>

<p>The reverb feedback coefficient.  The more feedback, the happier Elvis.
</p>
<div class="spacer"></div>


<!-- reverb-control-length -->
<pre class="indented">
<em class=def id="reverbcontrollength">reverb-control-length</em> snd
</pre>

<p>The <a class=quiet href="snd.html#reverb">reverb</a> delay line length scaler. Longer reverb simulates, to some
extent, a bigger hall.
</p>
<div class="spacer"></div>


<!-- reverb-control-length-bounds -->
<pre class="indented">
<em class=def id="reverbcontrollengthbounds">reverb-control-length-bounds</em> snd
</pre>

<p>The reverb-control-length min and max amounts as a list.  The default is
(list 0.0 5.0).
</p>
<div class="spacer"></div>


<!-- reverb-control-lowpass -->
<pre class="indented">
<em class=def id="reverbcontrollowpass">reverb-control-lowpass</em> snd
</pre>

<p>The reverb low pass filter coefficient.  (This filter is in the feedback loop).
</p>
<div class="spacer"></div>


<!-- reverb-control-scale -->
<pre class="indented">
<em class=def id="reverbcontrolscale">reverb-control-scale</em> snd
</pre>

<p>The <a class=quiet href="snd.html#reverb">reverb</a> amount (the amount of the direct signal sent to the reverb).
You can never have enough reverb.
</p>
<div class="spacer"></div>


<!-- reverb-control-scale-bounds -->
<pre class="indented">
<em class=def id="reverbcontrolscalebounds">reverb-control-scale-bounds</em> snd
</pre>

<p>The reverb-control-scale min and max amounts as a list.  The default is
(list 0.0 4.0).
</p>
<div class="spacer"></div>


<!-- reverb-control? -->
<pre class="indented">
<em class=def id="reverbcontrolp">reverb-control?</em> snd
</pre>

<p>#t if the reverb button is set (i.e. the reverberator is active).
</p>
<div class="spacer"></div>


<!-- save-controls -->
<pre class="indented">
<em class=def id="savecontrols">save-controls</em> snd
</pre>

<p>This remembers the current control
settings for a later <a class=quiet href="#restorecontrols">restore-controls</a>.  In new-effects.scm, the effects that use the control panel
internally (post-expsrc-dialog, for example) save and restore the current state via:
</p>

<pre class="indented">
(<em class=red>save-controls</em>)
(reset-controls)
;;; now set the ones that are of interest for the current effect
(apply-controls)
(restore-controls)
</pre>
<div class="spacer"></div>


<!-- show-controls -->
<pre class="indented">
<em class=def id="showcontrols">show-controls</em> snd
</pre>

<p>#t if the sound's control panel is currently open.
If set to #t, the sound's control panel is opened, else it is closed. 
</p>
<div class="spacer"></div>


<!-- speed-control -->
<pre class="indented">
<em class=def id="speedcontrol">speed-control</em> snd
</pre>

<p>current <a class=quiet href="snd.html#speed">speed</a> (sampling rate conversion factor).  A speed of 2 plays the sound twice as fast.
</p>
<div class="spacer"></div>


<!-- speed-control-bounds -->
<pre class="indented">
<em class=def id="speedcontrolbounds">speed-control-bounds</em> snd
</pre>

<p>The speed-control min and max amounts as a list.  The default is
(list 0.05 20.0).
If no 'snd' argument is given, this also affects the Mix, and View:Files dialogs.
</p>
<div class="spacer"></div>


<!-- speed-control-style -->
<pre class="indented">
<em class=def id="speedstyle">speed-control-style</em> snd
</pre>

<p>The speed control can be interpreted as a 
float, (speed-control-as-float, the default), as a ratio 
of relatively small integers (speed-control-as-ratio), or as a step in a 
microtonal scale (speed-control-as-semitone).  
In the various speed controls, you can click the number to cycle through the speed style choices.
</p>
<div class="spacer"></div>


<!-- speed-control-tones -->
<pre class="indented">
<em class=def id="speedtones">speed-control-tones</em> snd
</pre>

<p>The number of tones per octave in the speed-control-as-semitone speed 
style (default: 12).
</p>
<div class="spacer"></div>


<p>
The Options:Controls menu option 
starts a dialog to handle the controls that aren't handled by
the control panel (expand-control-hop, expand-control-length, expand-control-ramp,
contrast-control-amp, reverb-control-lowpass, and reverb-control-feedback).
The control panel itself is accessible as <code>((<a href="#soundwidgets">sound-widgets</a>) 2)</code>.
You can add or remove controls; <a href="sndscm.html#addampcontrols">add-amp-controls</a>
in snd-motif.scm sets up a separate amp slider for each channel in the current sound.
<a href="sndscm.html#disablecontrolpanel">disable-control-panel</a> disables (hides) the
entire panel.
</p>





<!-- INDEX editlists:Edit lists -->
<!-- Edit Lists -->

<div class="innerheader" id="editlists">Edit Lists</div>

<p>An edit list (in other editors this is called an "edit decision list", I guess because it sounds decisive)
describes the edit history of a channel. When, for example, you type C-d, nothing actually
happens to any data, despite the fact that the graph no longer shows that sample, it's omitted when you play the
channel, and so on.  Instead, a descriptor is appended to the edit history of that
channel saying "sample n was deleted".  Undo and redo move around in this list (they just move the
pointer to the current edit history position); all the positions are accessible just like the current
one, and are exposed in many functions described above via the 'pos' or 'edpos' arguments.
The edit list functions are:
</p>
<div class="spacer"></div>

<!--  EDIT-LIST TABLE  -->

<!-- as-one-edit -->
<pre class="indented">
<em class=def id="asoneedit">as-one-edit</em> func origin
</pre>

<p>call 'func', a function of no arguments, treating it as
one edit (in all channels) in the edit history mechanism.  Graphics redisplays are squelched during as-one-edit.
as-one-edit returns the result of 'func'.
</p>

<table>
<tr><td>
<div class="scheme">
<pre class="indented">
(<em class=red>as-one-edit</em> 
  (lambda () 
    (set! (<a class=quiet href="#sample">sample</a> 100) .1) 
    (set! (<a class=quiet href="#sample">sample</a> 200) .2)))
</pre>
</div>
</td></tr>
<tr><td>
<div class="ruby">
<pre class="indented">
<em class=red>as_one_edit</em>(lambda do || 
  set_sample(100, 0.1)
  set_sample(200, 0.2)
  end)
</pre>
</div>
</td></tr>
<tr><td>
<div class="forth">
<pre class="indented">
lambda: 
  100 .1 set-sample drop 
  200 .2 set-sample drop
; 0 make-proc <em class=red>as-one-edit</em>
</pre>
</div>
</td></tr></table>

<p>See mix.scm for many examples. If you want to save and restore Snd's state after using as-one-edit, you need to
set 'origin' to some string that can restore the effect of the as-one-edit; the default is
to copy the last edit history string and use its associated bounds &mdash; unlikely to be what you want.
</p>
<div class="spacer"></div>


<!-- display-edits -->
<pre class="indented">
<em class=def id="displayedits">display-edits</em> snd chn edpos
</pre>

<p>This returns the current edit list contents as a string.  If 'edpos' is specified, only that position is described.
</p>

<pre class="indented">
&gt; (open-sound "oboe.snd")
#&lt;sound 0&gt;
&gt; (scale-channel 2.0)
2.0
&gt; (pad-channel 100 200)
100
&gt; (display-edits 0 0 1)  ; show just edit 1 (the scale-channel call)
"
 (scale 0 50828) ; scale-channel 2.000 0 #f [1:2]:
   (at 0, cp-&gt;sounds[0][0:50827, 2.000]) [file: /home/bil/cl/oboe.snd[0]]
   (at 50828, end_mark)
"
</pre>
<div class="spacer"></div>


<!-- edit-fragment -->
<pre class="indented">
<em class=def id="editfragment">edit-fragment</em> edpos snd chn
</pre>

<p>This returns a list similar to that displayed in the edit history window giving 
the origin of the specified edit, its type (delete, insert, etc), its 
begin sample, and the number of samples 
affected.  If 'edpos' is omitted, edit-fragment returns the currently active
edit.
</p>

<pre class="indented">
&gt; (edit-fragment 2 0 0) ; continuing example above
("pad-channel" "zero" 100 200)
</pre>
<div class="spacer"></div>



<!-- edit-list->function -->
<pre class="indented">
<em class=def id="editlisttofunction">edit-list-&gt;function</em> snd chn start end
</pre>

<p>This returns a function encapsulating the current edit history list,  providing a way to save an edit
sequence and re-apply it in some other context.  For example, you can back up to some earlier point,
save the edit list, make a change, then re-run the saved edit sequence.  
The function returned takes 2 arguments, a sound and a channel number.
</p>

<pre class="indented">
&gt; (define our-edits (<em class=red>edit-list-&gt;function</em>)) ; same example as above
#&lt;unspecified&gt;
&gt; our-edits
#&lt;procedure our-edits ((snd chn) (scale-channel 2.0 0 #f snd chn) (pad-channel 100 200 snd chn))&gt;
&gt; (undo 2)
2
&gt; (our-edits 0 0)
100
</pre>

<p>In Ruby:
</p>

<pre class="indented">
:open_sound "oboe.snd"
0
:scale_channel 2.0
2.0
:pad_channel 100, 200
100
:our_edits = edit_list2function
#&lt;Proc:0x40c713ec@(eval):2&gt;
:our_edits.source
Proc.new {|snd, chn|  scale_channel(2.000, 0, false, snd, chn); pad_channel(100, 200, snd, chn) }
:undo 2
2
:our_edits.call(0, 0)
100
</pre>

<p>In Forth:
</p>

<pre class="indented">
snd&gt; "oboe.snd" open-sound
0
snd&gt; 2.0 scale-channel
2.0
snd&gt; 100 200 pad-channel
100
snd&gt; 0 0 edit-list-&gt;function value our-edits
nil
snd&gt; our-edits proc-source-ref
lambda: { snd chn } 2.000 0 #f snd chn scale-channel drop 100 200 snd chn pad-channel drop ; 2 make-proc
snd&gt; 2 undo
2
snd&gt; our-edits '( 0 0 ) run-proc
#f
</pre>
<div class="spacer"></div>


<!-- edit-position -->
<pre class="indented">
<em class=def id="editposition">edit-position</em> snd chn
</pre>

<p>The current position in the edit history list; it can be set:  (set! (edit-position) 0) is equivalent
to (<a class=quiet href="#revertsound">revert-sound</a>) in a mono sound.
See <a href="#makesampler">make-sampler</a>.
</p>
<div class="spacer"></div>


<!-- edit-properties -->
<pre class="indented">
<em class=def id="editproperties">edit-properties</em> snd chn edpos
</pre>

<p>Each entry in a channel's edit history list has a property list (similar to the
<a href="#channelproperties">channel-properties</a> list).  If you have information that changes with the
edit lists, these property lists might simplify the access code.
</p>
<div class="spacer"></div>


<!-- edit-property -->
<pre class="indented">
<em class=def id="editproperty">edit-property</em> key snd chn edpos
</pre>

<p>edit-property returns the value associated with 'key' in the given channel's edit history list
<a href="extsnd.html#editproperties">property list</a> at edit location 'edpos'.  To add or change a property, use set! with this procedure
as in <a href="#channelproperty">channel-property</a>.
The edit list property list is convenient because the associated information goes away automatically
when the given edit is no longer accessible.
</p>
<div class="spacer"></div>


<!-- edits -->
<pre class="indented">
<em class=def id="edits">edits</em> snd chn
</pre>

<p>This returns a list with the number of undo-able edits and redo-able edits.  That is, if we have 2 undo-able edits and
no redo-able edits, (edits) returns (list 2 0).
</p>
<div class="spacer"></div>


<!-- edit-tree -->
<pre class="indented">
<em class=def id="edittree">edit-tree</em> snd chn edpos
</pre>

<p>This returns a list of lists completely describing current edit list.
Each inner list has the form 
</p>

<pre class="indented">
(list global-position data-number local-position local-end scaler ramp0 ramp1 type)
</pre>

<p>If 'data-number' is -2, it marks the end of the list.  In our example above (the scale-channel/pad-channel sequence):
</p>

<pre class="indented">
&gt; (edit-tree)
    ((0 0 0 99 2.0 0.0 0.0 0) (100 -1 0 199 0.0 0.0 0.0 1) 
        (300 0 100 50827 2.0 0.0 0.0 0) (51028 -2 0 0 0.0 0.0 0.0 0))
</pre>
<div class="spacer"></div>


<!-- save-edit-history -->
<pre class="indented">
<em class=def id="saveedithistory">save-edit-history</em> filename snd chn
</pre>

<p>This function saves the current edit lists in 'filename'.
If 'chn' is omitted, all of the sound's channels are saved; if 'snd' is omitted,
all edit lists are saved.  If the underlying files are not subsequently 
changed, you can load this file to restore the current edit list state.
save-edit-history returns #t if all went well.
The following function makes an
exact copy of the state (edit lists and all) of the given sound,
providing a way to fork an edit path (geez, what jargon!).  The idea here
is to copy the complete edit state into a new sound so that two or more
edit sequences can be compared.
</p>

<pre class="indented">
(define sfile 0)

(define* (<em class="noem" id="clonesoundas">clone-sound-as</em> new-name snd)
  (let* ((tmpf (<a class=quiet href="#sndtempnam">snd-tempnam</a>))
	 (scm (string-append (substring tmpf 0 (- (string-length tmpf) 3)) "scm"))
	 (oldsnd (or snd (<a class=quiet href="#selectedsound">selected-sound</a>))))
    (if (not (string? (<a class=quiet href="#savedir">save-dir</a>))) (set! (<a class=quiet href="#savedir">save-dir</a>) "/tmp"))
    (<em class=red>save-edit-history</em> scm oldsnd)
    (copy-file (<a class=quiet href="#filename">file-name</a> oldsnd) new-name)
    (set! sfile (<a class=quiet href="#opensound">open-sound</a> new-name))
    (load scm)
    (delete-file scm)
    sfile))
</pre>

<p>We can also use save-edit-history (with some trouble) to split a sound off
into an independent Snd process:
</p>

<pre class="indented">
(define* (separate-sound snd)
  (let* ((tmpf (<a class=quiet href="#sndtempnam">snd-tempnam</a>))
	 (scm (string-append (substring tmpf 0 (- (string-length tmpf) 3)) "scm"))
	 (scm1 (string-append (substring tmpf 0 (- (string-length tmpf) 4)) "-1.scm"))
	 (oldsnd (or snd (<a class=quiet href="#selectedsound">selected-sound</a>)))
	 (name (<a class=quiet href="#filename">file-name</a> oldsnd)))
    (if (string=? (<a class=quiet href="#savedir">save-dir</a>) "") (set! (<a class=quiet href="#savedir">save-dir</a>) "/tmp"))
    (<em class=red>save-edit-history</em> scm oldsnd)
    (<a class=quiet href="#closesound">close-sound</a> oldsnd)
    (with-output-to-file
	scm1
      (lambda ()
	(<a class=quiet>format</a> () "(define sfile (<a class=quiet href="#opensound">open-sound</a> ~S))~%" name)
	(<a class=quiet>format</a> () "(load ~S)~%" scm)))
    (system (<a class=quiet>format</a> #f "snd ~A &amp;" scm1))))
</pre>
<div class="separator"></div>


<p>It is sometimes more convenient to edit the edit history lists
directly, than to run Snd and invoke the <a href="snd.html#savedstate">"Save session"</a> menu option.
These lists are Scheme, Ruby, or Forth programs, just like anything else
discussed in this document.  You could even write them from
scratch.  Say we want to make a stereo file that consists
of four mono files mixed at various points; we know where they
should go, and we have religious objections to using a
graphical user interface.  So we create myfile.scm, and
put in it something like:
</p>

<pre class="indented">
(let ((myfile (<a class=quiet href="#newsound">new-sound</a> "mysound.snd" 2 44100 mus-bshort mus-aifc "this is my sound")))
	;; this is equivalent to the New file menu option
  (<a class=quiet href="#mix">mix</a> "oboe.snd" 0 0 myfile 0)
  ;; this mixes in the mono file oboe.snd at sample 0 in channel 0
  ;; use (<a class=quiet href="#mix">mix</a> "oboe.snd" 0 0 myfile 0 #f) to forego the editable mix
  (<a class=quiet href="#mix">mix</a> "pistol.snd" 0 0 myfile 1)
  ;; now pistol.snd is at sample 0 in channel 1
  (<a class=quiet href="#mix">mix</a> "fyow.snd" 10000 0 myfile 0)
  ;; add in fyow.snd at sample 10000 in the first channel
  (<a class=quiet href="#mix">mix</a> "cardinal.snd" 20000 0 myfile 1)
  ;; etc
  )
</pre>

<p>Now start Snd: snd -l myfile.scm and voila!
Files like this can contain any arbitrary code, calling
anything in Snd or anywhere else for that matter; you
have a CLM-like notelist reader to describe sound file edits.
Similarly, when you save Snd's state (via the Save session menu
option or by calling the function <a href="#savestate">save-state</a>),
the result is a program that can be edited just like any
other such text.
</p>



<!-- Transforms -->

<div class="innerheader" id="sndtransforms">Transforms</div>

<p>Most of the transform functions and variables have been treated above, so they are only mentioned here.
</p>
<div class="spacer"></div>

<!--  TRANSFORM TABLE  -->

<!-- add-transform -->
<pre class="indented">
<em class=def id="addtransform">add-transform</em> name xlabel lo hi transform
</pre>

<p>add-transform adds a transform to the transform choices (alongside fourier-transform, etc).  'name' is the name
to use in the transform dialog. 'xlabel' is the x axis label
of the resultant graph.  'lo' and 'hi' set which portion of the returned data
to graph (normally 0.0 to 1.0).  'proc' is a function of two 
arguments, the length of the desired transform, and a sampler that 
can be used to get the current data.  Do not free the sampler!  
The function should return a float-vector containing the transform data.  
add-transform returns the new transform's transform-type (an object).
Here's an example that displays a histogram of the current values in 16 bins:
</p>

<pre class="indented">
(<em class=red>add-transform</em> "histogram" "bins" 0.0 1.0 
  (lambda (len fd)
    (do ((v (make-float-vector len))
         (steps (/ len 16))
         (step (/ 1.0 len))
         (i 0 (+ i 1))) 
        ((= i len) v)
      (let ((val (<a class=quiet href="#readsample">read-sample</a> fd)))
        (do ((bin (floor (* (abs val) 16.0)))
             (j 0 (+ j 1))) 
            ((= j steps))
          (set! (v (+ j bin)) (+ step (v (+ j bin)))))))))
</pre>

<p>If GSL is included in Snd, the following code ties in the (slow) Hankel transform:
</p>

<pre class="indented">
(<em class=red>add-transform</em> "Hankel" "Hankel" 0.0 1.0
   (lambda (n rd)
      (let ((v (make-float-vector n)))
         (do ((i 0 (+ i 1))) ((= i n)) (set! (v i) (rd)))
         (gsl-dht n v 1.0 1.0)
         v)))
</pre>
<div class="spacer"></div>


<!-- delete-transform -->
<pre class="indented">
<em class=def id="deletetransform">delete-transform</em> type
</pre>

<p>This removes a transform that was added via <a class=quiet href="#addtransform">add-transform</a>.
</p>
<div class="spacer"></div>


<!-- fft -->
<pre class="indented">
<em class=def id="fft">fft</em> rl im sgn
</pre>

<p>This performs an FFT on float-vectors 'rl' and 'im' (the real and imaginary parts of the
input data). 'sgn' is 1 for an FFT, -1 for an inverse FFT; (the default is 1).
The CLM <a href="sndclm.html#fft">fft</a> function is called mus-fft in Snd.
The only difference between the two is that Snd's fft determines the fft size from 
the size of the float-vectors passed to it, whereas CLM's takes the size as an argument.
Here's an example that uses the fft to produce a sum of sinusoids each with arbitrary amplitude
and initial-phase:
</p>

<pre class="indented">
(define (fft-&gt;sines amps phases)
  (let* ((len (length phases))
	 (fft-size (expt 2 (+ 10 (ceiling (log len 2)))))
	 (rl (make-float-vector fft-size))
	 (im (make-float-vector fft-size)))
    (do ((i 0 (+ i 1)))
	((= i len))
      (let ((amp (amps i))
	    (phase (phases i)))
	(set! (rl (+ i 1)) (* amp (sin phase)))
	(set! (im (+ i 1)) (* amp (cos phase)))))
    (<em class=red>fft</em> rl im -1)
    rl))
</pre>
<div class="spacer"></div>


<!-- integer->transform -->
<pre class="indented">
<em class=def id="integertotransform">integer-&gt;transform</em> i
</pre>

<p>This function returns the transform (type object) corresponding to a given integer. 
</p>
<div class="spacer"></div>


<!-- snd-spectrum -->
<pre class="indented">
<em class=def id="sndspectrum">snd-spectrum</em> data window length (linear #t) (beta 0.0) in-place (normalized #t)
</pre>

<p>This returns the spectrum (as a float-vector) of 'data' (also a float-vector) using the fft window 'win'.
'length' is the number of samples 
of data. 
</p>

<pre class="indented">
(let ((spectr (snd-spectrum data rectangular-window (<a class=quiet href="#transformsize">transform-size</a>)))) 
  ...)
</pre>

<p>If 'linear' is #f (its default is #t), the spectrum is in dB.
'beta' is the fft data window family parameter; it is scaled internally so here it should be between 0.0 and 1.0.
If 'in-place' is #t, the spectrum is in 'data', otherwise snd-spectrum returns a new float-vector.
</p>
<div class="spacer"></div>


<!-- transform->integer -->
<pre class="indented">
<em class=def id="transformtointeger">transform-&gt;integer</em> transform-object
</pre>

<p>This function returns the integer corresponding to a given transform type object (e.g. fourier-transform).
</p>
<div class="spacer"></div>


<!-- transform? -->
<pre class="indented">
<em class=def id="transformp">transform?</em> object
</pre>

<p>This returns #t if 'object' is a transform object.
</p>
<div class="spacer"></div>



<p>Other related variables and functions:</p>
<pre class="indented">
<a href="#transformgraphp">transform-graph?</a>         <a href="#showtransformpeaks">show-transform-peaks</a>        <a href="#transformsample">transform-sample</a>
<a href="#fftbeta">fft-window-beta</a>          <a href="#showselectiontransform">show-selection-transform</a>    <a href="#transformtofv">transform-&gt;float-vector</a>
<a href="#aftertransformhook">after-transform-hook</a>     <a href="#spectrumend">spectrum-end</a>                <a href="#transformframples">transform-framples</a>
<a href="#fftlogfrequency">fft-log-frequency</a>        <a href="#spectrohop">spectro-hop</a>                 <a href="#transformtype">transform-type</a>
<a href="#fftlogmagnitude">fft-log-magnitude</a>        <a href="#spectrumstart">spectrum-start</a>              <a href="#updatetransformgraph">update-transform-graph</a>
<a href="#transformsize">transform-size</a>           <a href="#spectroxangle">spectro-x-angle</a>             <a href="#normalizefft">transform-normalization</a>
<a href="#transformgraphtype">transform-graph-type</a>     <a href="#spectroxscale">spectro-x-scale</a>             <a href="#zeropad">zero-pad</a>
<a href="#fftwindow">fft-window</a>               <a href="#spectroyangle">spectro-y-angle</a>             <a href="#wavelettype">wavelet-type</a>
<a href="#maxfftpeaks">max-transform-peaks</a>      <a href="#spectroyscale">spectro-y-scale</a>             <a href="#spectrozscale">spectro-z-scale</a>
<a href="#mindb">min-dB</a>                   <a href="#spectrozangle">spectro-z-angle</a>
</pre>

<p id="fftexamples">Some FFT-based effects and editing functions:
</p>

<!-- INDEX fftexamples:FFTs -->

<TABLE class="method">
<tr><th class="title">FFTs</th></tr><tr><td>
<blockquote><small>
CLM fft function: <a href="sndclm.html#fft">mus-fft</a><br>
CLM spectrum: <a href="sndclm.html#spectrum">spectrum</a><br>
Snd spectrum: <a href="#sndspectrum">snd-spectrum</a><br>
autocorrelation: <a href="sndclm.html#autocorrelate">autocorrelate</a><br>
cross correlation: <a href="sndclm.html#correlate">correlate</a>, <a href="sndscm.html#displaycorrelation">display-correlation</a><br>
FFT window: <a href="sndclm.html#make-fft-window">make-fft-window</a><br>
Dolph-Chebyshev window in Scheme: <a href="sndscm.html#dolph">dolph</a><br>
Hartley transform in Scheme: <a href="sndscm.html#dht">dht</a><br>
Spectral edit dialog: <a href="snd.html#editenvelope">Envelope Editor</a><br>
<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="sndclm.html#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>
power spectral density: green.scm<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>
<br>
Superimpose ffts: <a href="sndscm.html#superimposeffts">superimpose-ffts</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>
3D (single) fft display: <a href="sndscm.html#complexify">complexify</a><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>




<!-- Dialogs -->

<div class="header" id="snddialogs">Dialogs and other widgets</div>

<p>The built-in dialogs, accessible from the main menu, provide the standard, but sometimes clumsy
ways to open and save sounds, edit envelopes and headers, and set various global variables.
In addition, many other dialogs are implemented in various Scheme/Ruby/Forth files.  
The following
functions refer to the built-in dialogs.  They were aimed originally at semi-internal needs like
saving the current Snd state, but might be useful elsewhere.
Functions such as color-orientation-dialog normally create and start the dialog in question; that is,
(color-orientation-dialog) puts the color/orientation dialog on the screen.  If you're trying instead to
customize the dialog in some way (in your initialization file, for example), you want the
dialog to be created (so that the various widget children exist), but don't want it to pop
up on the screen ('managed' in X jargon). So, most of the dialog functions have a 'managed' argument.
If it is #f, the dialog is created, if need be, but not started.
install-searcher-with-colors in snd-motif.scm, which adds customized file filtering code
to the File:Open dialog, first makes sure the dialog exists with (open-file-dialog #f).
</p>
<div class="spacer"></div>

<!--  DIALOG TABLE  -->


<!-- add-directory-to-view-files-list -->
<pre class="indented">
<em class=def id="adddirectorytoviewfileslist">add-directory-to-view-files-list</em> dir dialog [Motif only]
</pre>

<p>This adds the sound files in directory 'dir' to the list of files in the View:Files dialog.  
</p>
<div class="spacer"></div>


<!-- add-file-to-view-files-list -->
<pre class="indented">
<em class=def id="addfiletoviewfileslist">add-file-to-view-files-list</em> file dialog [Motif only]
</pre>

<p>This adds 'file' to the list of files in the View:Files dialog.
</p>
<div class="spacer"></div>


<!-- add-file-filter -->
<pre class="indented">
<em class=def id="addfilefilter">add-file-filter</em> name func
</pre>

<p>This adds 'func' to the file filter list under the name 'name'.  The file filter list is a list
of functions, accessed from drop-down menus in the various file-related dialogs.  Each such function
filters the list of files displayed by the dialog, so that only some interesting subset is posted.
The built-in filter is <a href="#justsounds">just-sounds</a> which uses the sound file extension
tables to decide which files are sounds, omitting all others from the file lists.
You can add your own filters to this
menu with add-file-filter.  The 'name' appears as the menu item label corresponding to the function.
The function should take one argument, a file name, and return #t to retain that file in the file list.
add-file-filter returns an integer to identify 'func' in other contexts.
</p>

<pre class="indented">
(<em class=red>add-file-filter</em>
 "mono files"
 (lambda (a)
   (and (<a class=quiet href="#soundfilep">sound-file?</a> a)
	(= (channels a) 1))))
</pre>
<div class="spacer"></div>



<!-- add-file-sorter -->
<pre class="indented">
<em class=def id="addfilesorter">add-file-sorter</em> name func [Motif only]
</pre>

<p>This adds 'func' to the file-sorter list under the name 'name'.  Some dialog file lists include
a "sort" menu to reorder the files in the file list.  You can add your own sort functions to this
menu with add-file-sorter.  The 'name' appears as the menu item label corresponding to the function.
The new sorter's index is returned; it is an integer for use with functions such as <a href="#viewfilessort">view-files-sort</a>.
The function should take two arguments, each a filename, and return a strcmp-like number describing
how to sort the pair.  The following adds a sorter named "duration" that sorts files from shorter
to longer:
</p>

<pre class="indented">
  (<em class=red>add-file-sorter</em>
   "duration"
   (lambda (a b)
     (let ((dur1 (<a class=quiet href="#mussoundduration">mus-sound-duration</a> a))
	   (dur2 (<a class=quiet href="#mussoundduration">mus-sound-duration</a> b)))
       (cond ((&gt; dur1 dur2) 1) 
             ((&lt; dur1 dur2) -1) 
             (else 0)))))
</pre>
<div class="spacer"></div>



<!-- add-sound-file-extension -->
<pre class="indented">
<em class=def id="addsoundfileextension">add-sound-file-extension</em> ext
</pre>

<p>This adds 'ext' to the list of (case sensitive) sound file extensions used by <a href="#soundfilesindirectory">sound-files-in-directory</a>.
The initial list is ("snd" "aiff" "aif" "wav" "au" "aifc" "voc" "wve" "WAV" "sf2" "rf64" "caf").
To add "ogg" as a recognized extension:
</p>

<pre class="indented">
 (add-sound-file-extension "ogg")
</pre>

<p>The list itself is <a href="#soundfileextensions">sound-file-extensions</a>.
See also <a href="sndscm.html#matchsoundfiles">add-sound-file-extension-1</a>.
</p>
<div class="spacer"></div>


<!-- add-to-main-menu -->
<pre class="indented">
<em class=def id="addtomainmenu">add-to-main-menu</em> menu-label update-callback
</pre>

<p>This adds a new top-level menu named 'menu-label' and returns its menu index.  The index
identifies the menu for add-to-menu and others.
'update-callback' is a procedure of no arguments that is
called each time the menu is displayed. 
</p>

<pre class="indented">
Scheme:
(define new-menu (add-to-main-menu "New Menu"))
(<a class=quiet href="#addtomenu">add-to-menu</a> new-menu "First Item" (lambda () (<a class=quiet href="#sndprint">snd-print</a> ";item 1")))
(<a class=quiet href="#addtomenu">add-to-menu</a> new-menu "Second Item" (lambda () (<a class=quiet href="#sndprint">snd-print</a> ";item 2")))

Ruby:
new_menu = add_to_main_menu("New Menu")
add_to_menu(new_menu, "First Item", lambda do | | snd_print("item 1") end)
add_to_menu(new_menu, "Second Item", lambda do | | snd_print("item 2") end)

Forth:
"New Menu" add-to-main-menu constant new-menu drop
new-menu "First Item" lambda: &lt;{ }&gt; "item1" snd-print ; undef add-to-menu drop
new-menu "Second Item" lambda: &lt;{ }&gt; "item2" snd-print ; undef add-to-menu drop
</pre>
<div class="spacer"></div>


<!-- add-to-menu -->
<pre class="indented">
<em class=def id="addtomenu">add-to-menu</em> top-menu menu-label callback position
</pre>

<p>This adds the menu 'menu-label' to the top-level menu whose index is 
'top-menu' with the callback function 'callback', then returns the new menu label widget.
The built-in
Snd menus are numbered from 0 ('File') to 4 ('Help').  If the label and callback are #f, a separator is added to the menu.
'position' sets the position of the new menu option; it defaults to the end of the menu.  See new-effects.scm for many examples.
</p>

<pre class="indented">
  (<em class=red>add-to-menu</em> 1 "Stop Playing" <a class=quiet href="#stopplaying">stop-playing</a>)

  (<em class=red>add-to-menu</em> 5 "Reduce height" 
    (lambda () (set! (<a class=quiet href="#windowheight">window-height</a>) (/ (<a class=quiet href="#windowheight">window-height</a>) 2))))
</pre>
<div class="spacer"></div>



<!-- channel-widgets -->
<pre class="indented">
<em class=def id="channelwidgets">channel-widgets</em>
</pre>

<p>channel-widgets returns a list of various widgets associated with a given channel:
</p>

<pre class="indented">
0: graph                      ;drawing area for all 3 graphs (time, fft, lisp)
1: w-button 
2: f-button 
3: x-position slider
4: y-position slider
5: x-zoom slider
6: y-zoom slider
7: edit history list 
8: right(united-chans) y-position slider
9: right y-zoom slider
10: main pane for channel
</pre>
<div class="spacer"></div>


<!-- clear-listener -->
<pre class="indented">
<em class=def id="clearlistener">clear-listener</em>
</pre>

<p>This deletes all listener text from the beginning to the cursor position (C-M-g is bound to this function).
</p>
<div class="spacer"></div>


<!-- color-orientation-dialog -->
<pre class="indented">
<em class=def id="colororientationdialog">color-orientation-dialog</em> managed
</pre>

<p>This creates and (if 'managed') activates the Color/Orientation dialog; it returns the dialog widget.
</p>
<div class="spacer"></div>


<!-- define-envelope -->
<pre class="indented">
<em class=def id="defineenvelope">define-envelope</em> name data (base 1.0)
</pre>

<p>This adds an envelope to the envelope editor's list, under the name 'name', using the list of breakpoints
'data', and the optional 'base'. 
</p>

<pre class="indented">
Scheme: (define-envelope ramp '(0 0 1 1))
Ruby:   define_envelope("ramp", [0, 0, 1, 1])
Forth:  $" ramp" '( 0.0 0.0 1.0 1.0 ) 1.0 define-envelope
</pre>
<div class="spacer"></div>


<!-- delete-file-filter -->
<pre class="indented">
<em class=def id="deletefilefilter">delete-file-filter</em> index
</pre>

<p>This removes the file filter function associated with 'index' from the file filter list. 
</p>
<div class="spacer"></div>


<!-- delete-file-sorter -->
<pre class="indented">
<em class=def id="deletefilesorter">delete-file-sorter</em> index [Motif only]
</pre>

<p>This removes the file sorter function associated with 'index' from the file sorter list.
</p>
<div class="spacer"></div>


<!-- dialog-widgets -->
<pre class="indented">
<em class=def id="dialogwidgets">dialog-widgets</em>
</pre>

<p>dialog-widgets returns a list of dialog widgets (or lists thereof, or #f if none yet):
</p>

<pre class="indented">
0: View: Color/Orientation dialog 
2: Edit: EnvelopeEditor dialog 
   3 and 4: unused
5: Options: Transform dialog 
6: File: Open dialog 
7: File: Save as dialog 
8: View: Files dialog 
9: raw data dialog (activated when raw sound opened, sometimes)
10: File: New sound dialog 
11: File: Mix dialog 
12: Edit: Edit header dialog 
13: Edit: Find dialog 
14: Help dialog 
16: View: Mixes dialog
17: File: Print dialog 
19: View: Regions dialog
20: info dialog (activated by info-dialog function)
21: more controls dialog
22: Edit: Selection Save as dialog
23: File: Insert file dialog
24: region save as dialog (from regions dialog save button)
25: Options: Preferences dialog
</pre>
<div class="spacer"></div>


<!-- edit-header-dialog -->
<pre class="indented">
<em class=def id="editheaderdialog">edit-header-dialog</em> snd
</pre>

<p>This starts the Edit Header dialog on 'snd', returning the dialog widget.
</p>
<div class="spacer"></div>


<!-- enved-base -->
<pre class="indented">
<em class=def id="envedbase">enved-base</em> 
</pre>

<p>This is the envelope editor exponential base value.
</p>
<div class="spacer"></div>


<!-- enved-clip? -->
<pre class="indented">
<em class=def id="envedclipping">enved-clip?</em>
</pre>

<p>This reflects the state of the envelope editor 'clip' button.
</p>
<div class="spacer"></div>


<!-- enved-dialog -->
<pre class="indented">
<em class=def id="enveddialog">enved-dialog</em>
</pre>

<p>This starts the envelope editor dialog, returning the dialog widget.
</p>
<div class="spacer"></div>


<!-- enved-envelope -->
<pre class="indented">
<em class=def id="envedenvelope">enved-envelope</em>
</pre>

<p>This is the envelope (a list of breakpoints) in the envelope editor's graph window.
</p>
<div class="spacer"></div>


<!-- enved-filter -->
<pre class="indented">
<em class=def id="filterenv">enved-filter</em>
</pre>

<p>This reflects the type of the envelope editor's filter (the default #t means FIR; #f is FFT).  To get the FFT display in the envelope editor
as the default:
</p>

<pre class="indented">
  (set! (<em class=red>enved-filter)</em> #f)
  (set! (<a class=quiet href="#envedwaving">enved-wave?</a>) #t)
  (set! (<a class=quiet href="#envedtarget">enved-target</a>) <a class=quiet href="#envedtarget">enved-spectrum</a>)
</pre>
<div class="spacer"></div>


<!-- enved-filter-order -->
<pre class="indented">
<em class=def id="filterenvorder">enved-filter-order</em>
</pre>

<p>This is the order of the envelope editor's FIR filter (the default is 40).
</p>
<div class="spacer"></div>


<!-- enved-in-dB -->
<pre class="indented">
<em class=def id="envedin-dB">enved-in-dB</em>
</pre>

<p>This reflects the state of the envelope editor 'dB' button (it defaults to #f).
</p>
<div class="spacer"></div>


<!-- enved-power -->
<pre class="indented">
<em class=def id="envedpower">enved-power</em>
</pre>

<p>This is the envelope editor's base scale range (it defaults to 3.0).
</p>
<div class="spacer"></div>


<!-- enved-style -->
<pre class="indented">
<em class=def id="envedstyle">enved-style</em>
</pre>

<p>This is the envelope editor choice for connecting breakpoints.  It can be envelope-linear (the default), or
envelope-exponential.
</p>
<div class="spacer"></div>


<!-- enved-target -->
<pre class="indented">
<em class=def id="envedtarget">enved-target</em>
</pre>

<p>This determines how the envelope editor's current envelope is applied to the selected data.
The choices are enved-amplitude, enved-srate and enved-spectrum.
The first treats the envelope as an amplitude envelope, the second as an srate curve (changing speed),
and the last as a frequency response envelope for a filter.
</p>
<div class="spacer"></div>


<!-- enved-waveform-color -->
<pre class="indented">
<em class=def id="envedwaveformcolor">enved-waveform-color</em>
</pre>

<p>This is the color of the waveform displayed in envelope editor (the default is blue).
</p>
<div class="spacer"></div>


<!-- enved-wave? -->
<pre class="indented">
<em class=def id="envedwaving">enved-wave?</em>
</pre>

<p>This reflects the state of the envelope editor 'wave' button.
The wave shown is the time domain display, even when filtering.
</p>
<div class="spacer"></div>


<!-- find-dialog -->
<pre class="indented">
<em class=def id="finddialog">find-dialog</em> managed text
</pre>

<p>This creates and (if 'managed' which defaults to #t) starts the Edit:Find dialog, returning the dialog widget.
</p>
<div class="spacer"></div>


<!-- focus-widget -->
<pre class="indented">
<em class=def id="focuswidget">focus-widget</em> widget
</pre>

<p>This gives 'widget' "focus" &mdash; it becomes the active widget, receiving keystrokes and so on.
</p>
<div class="spacer"></div>


<!-- gl-graph->ps -->
<pre class="indented">
<em class=def id="glgraphtops">gl-graph-&gt;ps</em> file (type 0) snd chn
</pre>

<p>This creates a Postscript picture of the current openGL display in snd's channel chn (a spectrogram).
'file' defaults to <a href="#epsfile">eps-file</a>.
'type' can be 0: eps, 1: ps, 2: pdf, 3: tex, 4: svg, or 5: pgf.
This function is available only if OpenGL and gl2ps have been loaded (via the --with-gl and
--with-gl2ps configuration switches).
</p>
<div class="spacer"></div>


<!-- goto-listener-end -->
<pre class="indented">
<em class=def id="gotolistenerend">goto-listener-end</em>
</pre>

<p>This moves the cursor to the end of the listener text, and scrolls the window so that it is visible.
</p>
<div class="spacer"></div>


<!-- graph->ps -->
<pre class="indented">
<em class=def id="graphtops">graph-&gt;ps</em> file
</pre>

<p>This creates a Postscript picture of the current display.
'file' defaults to <a href="#epsfile">eps-file</a>.
See also <a href="#epsbottommargin">eps-bottom-margin</a>, <a href="#epsleftmargin">eps-left-margin</a>, 
and <a href="#epssize">eps-size</a>.
</p>
<div class="spacer"></div>


<!-- help-dialog -->
<pre class="indented">
<em class=def id="helpdialog">help-dialog</em> subject help-string xrefs urls
</pre>

<p>This starts the help dialog with the title 'subject' and help area text 'help', returning the dialog widget.
'xrefs' is an optional list of strings to post in the "related items" list.  'urls' is a corresponding
list of urls.
There are many examples in new-effects.scm.
</p>

<pre class="indented">
(define-macro (with-snd-help form)
  ;; if an error occurs while evaluating form, try to start the help dialog with some relevant help
  `(catch #t 
	  (lambda ()
	    ,form)
	  (lambda args
	    (if (and args (cadr args) (string? (cadr args)))
		(let* ((func (if (string=? "set!" (substring (cadr args) 0 4))
				(substring (cadr args) 5)
				(cadr args)))
		       (help (<a class=quiet href="#sndhelp">snd-help</a> func)))
		  (if help (<em class=red>help-dialog</em> func help))))
	    args)))
</pre>
<div class="spacer"></div>


<!-- hide-widget -->
<pre class="indented">
<em class=def id="hidewidget">hide-widget</em> widget
</pre>

<p>This hides (unmanages) 'widget'.
To remove the y-position slider (which is only there
for looks):
</p>

<pre class="indented">
(<a class=quiet href="#hidewidget">hide-widget</a> ((<a class=quiet href="#channelwidgets">channel-widgets</a>) 4))
</pre>
<div class="spacer"></div>


<!-- info-dialog -->
<pre class="indented">
<em class=def id="infodialog">info-dialog</em> subject info
</pre>

<p>This starts the info dialog with the title 'subject' and body 'info' returning the dialog widget.
</p>
<div class="spacer"></div>


<!-- insert-file-dialog -->
<pre class="indented">
<em class=def id="insertfiledialog">insert-file-dialog</em> managed
</pre>

<p>This creates and (if 'managed' which defaults to #t) activates the File:Insert dialog, returning the dialog widget.
</p>
<div class="spacer"></div>


<!-- listener-color -->
<pre class="indented">
<em class=def id="listenercolor">listener-color</em>
</pre>

<p>This is the background color of listener.
</p>

<pre class="indented">
(set! (listener-color) (<a class=quiet href="#makecolor">make-color</a> 0 0 0))
</pre>
<div class="spacer"></div>


<!-- listener-colorized -->
<pre class="indented">
<em class=def id="listenercolorized">listener-colorized</em>
</pre>

<div class="spacer"></div>


<!-- listener-font -->
<pre class="indented">
<em class=def id="listenerfont">listener-font</em>
</pre>

<p>This is the listener font.
</p>
<div class="spacer"></div>


<!-- listener-prompt -->
<pre class="indented">
<em class=def id="listenerprompt">listener-prompt</em>
</pre>

<p>This is the listener prompt which defaults to "&gt;".  I like ":" better (as you can see in many of the examples in this file),
so in ~/.snd_s7 I have this line:
</p>

<pre class="indented">
(set! (listener-prompt) ":")
</pre>
<div class="spacer"></div>


<!-- listener-selection -->
<pre class="indented">
<em class=def id="listenerselection">listener-selection</em>
</pre>

<p>listener-selection returns the currently selected text in the listener, or #f if there isn't any.  The following code 
starts the help dialog with help related to the selection if "h" is typed in the graph:
</p>

<pre class="indented">
(<a class=quiet href="#bindkey">bind-key</a> #\h 0 
  (let ((+documentation+ "start help dialog based on listener selected text"))
    (lambda ()
      (let ((subject (<em class=red>listener-selection</em>)))
        (if (string? subject)
            (<a class=quiet href="#helpdialog">help-dialog</a> subject (<a class=quiet href="#sndhelp">snd-help</a> subject)))))))
</pre>
<div class="spacer"></div>


<!-- listener-text-color -->
<pre class="indented">
<em class=def id="listenertextcolor">listener-text-color</em>
</pre>

<p>This is the text color in the listener.  For red text on a black background:
</p>

<div class="spacer"></div>


<!-- main-menu -->
<pre class="indented">
<em class=def id="mainmenu">main-menu</em> menu
</pre>

<p>main-menu returns the top-level menu 
associated with its integer argument:
</p>

<pre class="indented">
0: File menu
1: Edit menu
2: View menu
3: Options menu
4: Help menu
and others as added by add-main-menu
</pre>
<div class="spacer"></div>


<!-- main-widgets -->
<pre class="indented">
<em class=def id="mainwidgets">main-widgets</em>
</pre>

<p>main-widgets returns a list of the top-level widgets in Snd (#f if not created):
</p>

<pre class="indented">
0: top-level-application      ; XtAppContext in Motif
1: top-level-shell 
2: main-pane                  ; outer paned window top window (holds sounds)
3: main-sound-pane 
4: listener-pane              ; outer paned window bottom window
5: notebook-outer-pane
</pre>

<p>For example, to get at Snd's main shell widget:
</p>

<pre class="indented">
Scheme:    (cadr (main-widgets)) 
Ruby:      main_widgets.cadr
Forth:     main-widgets cadr
</pre>

<div class="spacer"></div>


<!-- menu-widgets -->
<pre class="indented">
<em class=def id="menuwidgets">menu-widgets</em>
</pre>

<p>menu-widgets returns the top-level menu widgets (cascade menus in Motif)
as a list:
</p>

<pre class="indented">
0: top-level-menu-bar 
1: file-menu
2: edit-menu 
3: view-menu 
4: options-menu 
5: help-menu
</pre>

<p>See snd-motif.scm, and new-effects.scm for various examples.
Manipulating menus can be tricky in Motif; if I were to try to explain
submenus and whatnot here, I'd only get tangled up in half-forgotten complications.
When I have to deal with this stuff, I always go to a working example.
</p>
<div class="spacer"></div>


<!-- mix-dialog-mix -->
<pre class="indented">
<em class=def id="mixdialogmix">mix-dialog-mix</em>
</pre>

<p>This is the id (mix object) of the mix displayed by the mix dialog.
</p>
<div class="spacer"></div>


<!-- mix-file-dialog -->
<pre class="indented">
<em class=def id="mixfiledialog">mix-file-dialog</em> managed
</pre>

<p>This creates and (if 'managed' which defaults to #t) activates the File:Mix dialog,
returning the dialog widget.
</p>
<div class="spacer"></div>


<!-- new-sound-dialog -->
<pre class="indented">
<em class=def id="newsounddialog">new-sound-dialog</em> managed
</pre>

<p>This creates and (if 'managed' which defaults to #t)
starts the File:New sound dialog, returning the dialog widget.
</p>
<div class="spacer"></div>


<!-- open-file-dialog -->
<pre class="indented">
<em class=def id="openfiledialog">open-file-dialog</em> managed
</pre>

<p>This creates and (if 'managed' which defaults to #t) activates the File:Open dialog,
returning the dialog widget.
</p>
<div class="spacer"></div>


<!-- preferences-dialog -->
<pre class="indented">
<em class=def id="preferencesdialog">preferences-dialog</em>
</pre>

<p>This activates the Options:Preferences dialog.
</p>
<div class="spacer"></div>


<!-- print-dialog -->
<pre class="indented">
<em class=def id="printdialog">print-dialog</em> managed direct-to-printer
</pre>

<p>This creates and (if 'managed' which defaults to #t) activates the File:Print dialog, returning the dialog widget.
</p>
<div class="spacer"></div>


<!-- remove-from-menu -->
<pre class="indented">
<em class=def id="removefrommenu">remove-from-menu</em> top-menu menu-label
</pre>

<p>This removes the menu 'menu-label' from the top top-level menu whose index is 'top-menu'.  See examp.scm or snd-motif.scm.
</p>
<div class="spacer"></div>


<!-- reset-listener-cursor -->
<pre class="indented">
<em class=def id="resetlistenercursor">reset-listener-cursor</em>
</pre>

<p>This resets the listener cursor to the default pointer shape.
</p>
<div class="spacer"></div>


<!-- save-as-dialog-auto-comment -->
<pre class="indented">
<em class=def id="saveasdialogautocomment">save-as-dialog-auto-comment</em>
</pre>

<p>This is the 'auto' button in the Save-as dialogs.  If set, a comment is automatically
generated for the new file.
</p>
<div class="spacer"></div>


<!-- save-as-dialog-src -->
<pre class="indented">
<em class=def id="saveasdialogsrc">save-as-dialog-src</em>
</pre>

<p>This is the 'src' button in the Save-as dialogs.  If set, sampling rate conversion
is performed if the output srate does not match the original srate.
</p>
<div class="spacer"></div>


<!-- save-envelopes -->
<pre class="indented">
<em class=def id="saveenvelopes">save-envelopes</em> filename
</pre>

<p>This saves the envelope editor envelopes in 'filename'.
</p>
<div class="spacer"></div>


<!-- save-listener -->
<pre class="indented">
<em class=def id="savelistener">save-listener</em> filename
</pre>

<p>This saves the listener contents in 'filename'.
</p>
<div class="spacer"></div>


<!-- save-region-dialog -->
<pre class="indented">
<em class=def id="saveregiondialog">save-region-dialog</em> managed
</pre>

<p>This creates and (if 'managed' which defaults to #t)
starts the Region Save-as dialog (to save the current Region browser region), returning the dialog widget.
</p>
<div class="spacer"></div>


<!-- save-selection-dialog -->
<pre class="indented">
<em class=def id="saveselectiondialog">save-selection-dialog</em> managed
</pre>

<p>This creates and (if 'managed' which defaults to #t)
starts the Edit:Save selection as dialog (to save the current selection), returning the dialog widget.
</p>
<div class="spacer"></div>


<!-- save-sound-dialog -->
<pre class="indented">
<em class=def id="savesounddialog">save-sound-dialog</em> managed
</pre>

<p>This creates and (if 'managed' which defaults to #t)
starts the File:Save as dialog (to save the currently selected sound), returning the dialog widget.
</p>
<div class="spacer"></div>


<!-- show-listener -->
<pre class="indented">
<em class=def id="showlistener">show-listener</em>
</pre>

<p>If show-listener is set to #t, Snd opens the listener pane; otherwise it closes the listener.
</p>
<div class="spacer"></div>


<!-- show-widget -->
<pre class="indented">
<em class=def id="showwidget">show-widget</em> widget
</pre>

<p>This shows (manages) 'widget'.
</p>
<div class="spacer"></div>


<!-- sound-file-extensions -->
<pre class="indented">
<em class=def id="soundfileextensions">sound-file-extensions</em>
</pre>

<p>This is the list of sound file extensions used by the "just-sounds" buttons and 
<a href="#soundfilesindirectory">sound-files-in-directory</a> to try to recognize
sound files.  It is settable: a list of extensions as strings:
</p>

<pre class="indented">
(set! (sound-file-extensions) 
  (list "snd" "aiff" "aif" "wav" "au" "aifc" "voc" "wve" "WAV" "sf2" "rf64" "caf"))
</pre>
<div class="spacer"></div>


<!-- sound-file? -->
<pre class="indented">
<em class=def id="soundfilep">sound-file?</em> filename
</pre>

<p>This returns #t if 'filename' has an extension that matches one in the <a href="#soundfileextensions">sound-file-extensions</a> list.
</p>

<pre class="indented">
&gt; (sound-file? "oboe.snd")
#t
&gt; (sound-file? "extsnd.html")
#f
</pre>
<div class="spacer"></div>


<!-- sound-files-in-directory -->
<pre class="indented">
<em class=def id="soundfilesindirectory">sound-files-in-directory</em> dir
</pre>

<p>This returns a list of the sound files found in 'dir'.  A file is considered a sound if it has data and
its extension is on the sound file extension list (see <a href="#addsoundfileextension">add-sound-file-extension</a>).
The directory name defaults to the current directory.
This is useful for batch processing of sounds.  The following
prints the names of all the stereo AIFC files it finds:
</p>

<pre class="indented">
(for-each
  (lambda (filename)
    (if (and (= (<a class=quiet href="#mussoundheadertype">mus-sound-header-type</a> filename) <a class=quiet href="#headertype">mus-aifc</a>)
             (= (channels filename) 2))
        (<a class=quiet href="#sndprint">snd-print</a> (<a class=quiet>format</a> #f "~%~A" filename))))
  (<em class=red>sound-files-in-directory</em>))
</pre>

<p>See also <a href="sndscm.html#mapsoundfiles">map-sound-files</a> in extensions.scm.
</p>
<div class="spacer"></div>


<!-- sound-widgets -->
<pre class="indented">
<em class=def id="soundwidgets">sound-widgets</em>
</pre>

<p>sound-widgets returns a list of various widgets specific to a given sound:
</p>

<pre class="indented">
0: main-pane 
1: name-label                 ; sound's file name
2: control-panel 
3: status area 
4: play button
5: filter-graph               ; control panel drawing area for filter envelope
6: unite button               ; invisible in mono sounds
8: name-icon                  ; hour-glass or whatever
9: sync button
</pre>

<p>For example, we can read and write the status area:
</p>

<pre class="indented">
Scheme:
&gt; (status-report "this is a test")
"this is a test"
&gt; (widget-text ((sound-widgets) 3))
"this is a test"
    
Ruby:
:status_report("this is a test")
this is a test
:widget_text(sound_widgets()[3])
this is a test
    
Forth:
snd&gt; "this is a test" status-report
this is a test
snd&gt; 0 sound-widgets 3 list-ref widget-text
this is a test
</pre>
<div class="spacer"></div>


<!-- stdin-prompt -->
<pre class="indented">
<em class=def id="stdinprompt">stdin-prompt</em>
</pre>

<p>This is the stdin prompt which defaults to "".
</p>
<div class="spacer"></div>


<!-- transform-dialog -->
<pre class="indented">
<em class=def id="transformdialog">transform-dialog</em> managed
</pre>

<p>This creates and (if 'managed') activates the Options:Transform dialog, returning the dialog widget.
</p>
<div class="spacer"></div>


<!-- view-files-amp -->
<pre class="indented">
<em class=def id="viewfilesamp">view-files-amp</em> dialog [Motif only]
</pre>

<p>This is the value of the amplitude slider in the View:Files dialog.
</p>
<div class="spacer"></div>


<!-- view-files-amp-env -->
<pre class="indented">
<em class=def id="viewfilesampenv">view-files-amp-env</em> dialog [Motif only]
</pre>

<p>This is the amplitude envelope displayed in the View:Files dialog.
</p>
<div class="spacer"></div>


<!-- view-files-dialog -->
<pre class="indented">
<em class=def id="viewfilesdialog">view-files-dialog</em> managed [Motif only]
</pre>

<p>This creates and (if 'managed') activates a
View:Files <a href="snd.html#viewfiles">dialog</a> and returns the dialog widget.
</p>
<div class="spacer"></div>


<!-- view-files-files -->
<pre class="indented">
<em class=def id="viewfilesfiles">view-files-files</em> dialog [Motif only]
</pre>

<p>This is the file list (a list of strings) of a View:Files dialog.
</p>
<div class="spacer"></div>


<!-- view-files-selected-files -->
<pre class="indented">
<em class=def id="viewfilesselectedfiles">view-files-selected-files</em> dialog [Motif only]
</pre>

<p>This is the list of selected files (a list of strings) in a View:Files dialog.
</p>
<div class="spacer"></div>


<!-- view-files-sort -->
<pre class="indented">
<em class=def id="viewfilessort">view-files-sort</em> dialog [Motif only]
</pre>

<p>This is the sort function choice in a View:Files dialog.  Initially there are 6 sort choices: a..z, z..a (sort by file name),
new..old, old..new (sort by file write date), and small..big, big..small (sort by file size).  The default is 0 (a..z).
If you set view-files-sort without giving the dialog argument, it just affects the startup state of subsequent new View:Files
dialogs.  To set the sort choice in the current dialog:
</p>

<pre class="indented">
  (set! (view-files-sort ((<a class=quiet href="#dialogwidgets">dialog-widgets</a>) 8)) 2) ; 2=new..old
</pre>
<div class="spacer"></div>


<!-- view-files-speed -->
<pre class="indented">
<em class=def id="viewfilesspeed">view-files-speed</em> dialog [Motif only]
</pre>

<p>This is the value of the speed slider in a View:Files dialog.
</p>
<div class="spacer"></div>


<!-- view-files-speed-style -->
<pre class="indented">
<em class=def id="viewfilesspeedstyle">view-files-speed-style</em> dialog [Motif only]
</pre>

<p>This is the speed style choice in a View:Files dialog. It is one of speed-control-as-float (the default),
speed-control-as-ratio, or speed-control-as-semitone.
</p>
<div class="spacer"></div>


<!-- view-mixes-dialog -->
<pre class="indented">
<em class=def id="viewmixesdialog">view-mixes-dialog</em>
</pre>

<p>This creates and activates the View:Mixes Dialog, returning the dialog widget.
</p>
<div class="spacer"></div>


<!-- view-regions-dialog -->
<pre class="indented">
<em class=def id="viewregionsdialog">view-regions-dialog</em>
</pre>

<p>This starts the <a href="snd.html#regionbrowser">region browser</a> (a no-op if there are no regions), and returns the dialog widget.
</p>
<div class="spacer"></div>


<!-- widget-position -->
<pre class="indented">
<em class=def id="widgetposition">widget-position</em> widget
</pre>

<p>This returns a list giving the widget's x and y coordinates (in pixels).  It can be set to reposition the widget.  
See nb.scm where it uses the current window position to try to find a convenient place for the help dialog.
</p>
<div class="spacer"></div>


<!-- widget-size -->
<pre class="indented">
<em class=def id="widgetsize">widget-size</em> widget
</pre>

<p>This returns a list giving the widget's width and height (in pixels).  It can be set to resize the widget. See nb.scm and examp.scm.
</p>

<pre class="indented">
(set! (<a class=quiet href="#widgetposition">widget-position</a> (cadr (<a class=quiet href="#mainwidgets">main-widgets</a>))) (list 300 100))
</pre>
<div class="spacer"></div>


<!-- widget-text -->
<pre class="indented">
<em class=def id="widgettext">widget-text</em> widget
</pre>

<p>This returns the text widget's text.  It can be set.
</p>
<div class="spacer"></div>





<div class="header" id="sndmisc">Miscellaneous functions</div>

<!--  MISCELLANEOUS TABLE  -->
<div class="spacer"></div>


<!-- abort -->
<pre class="indented">
<em class=def id="abort">abort</em>
</pre>

<p>This exits Snd via "abort", presumably to fall into the C debugger.  To stop some on-going Snd operation,
use <a href="#cgp">C-g</a>.
</p>
<div class="spacer"></div>


<!-- add-source-file-extension -->
<pre class="indented">
<em class=def id="addsourcefileextension">add-source-file-extension</em> ext
</pre>

<p>add-source-file-extension adds 'ext' to the list of source file extensions. 
</p>

<pre class="indented">
(add-source-file-extension "rbs")
</pre>
<div class="spacer"></div>


<!-- bes-* -->
<pre class="indented">
<em class=def id="besj0">bes-j0</em> x
<em class=emdef>bes-j1</em> x
<em class=emdef>bes-jn</em> n x
<em class=emdef>bes-y0</em> x
<em class=emdef>bes-y1</em> x
<em class=emdef>bes-yn</em> n x
<em class=emdef>bes-i0</em> n x
<em class=emdef>bes-i1</em> n x ; from GSL
<em class=emdef>bes-in</em> n x
<em class=emdef>bes-k0</em> x
<em class=emdef>bes-k1</em> x
<em class=emdef>bes-kn</em> n x
</pre>

<p>If the Bessel functions are available from the math library (or GSL), these are J0 and friends.
</p>
<div class="spacer"></div>


<!-- bind-key -->
<pre class="indented">
<em class=def id="bindkey">bind-key</em> key state func extended origin
</pre>

<p>
bind-key causes 'key' (an integer or a key name) with modifiers 'state' (and preceding C-x if 'extended') to evaluate 'func'
when the graph is receiving keysrokes.  If bind-key seems to be a no-op, try clicking in the graph to
force it to take the focus.
If 'origin' is included, it is the name reported if an error occurs.  The default is a description of the key.
</p>

<p>The function ('func' above) should take zero or one arguments and
return one of the cursor choices telling Snd what 
action (if any) to take after evaluating 'code'.  
Possible return values are:
</p>

<pre class="indented">
cursor-in-view  cursor-on-left  cursor-on-right  cursor-in-middle  keyboard-no-action
</pre>

<p>If the function takes one argument, 
that argument is the count (the C-u number prefixed to the keyboard command)
defaulting to 1 if no prefix is typed.  
</p>

<p>The modifier 'state' is a combination of control = 4 and meta = 8.
If the key argument is a string (a key name) it has to match exactly one of the known key names.
In X, these can be found in &lt;X11/xkeysymdef.h&gt;.  
Remove the XK_ prefix.  So, for example, the key marked "Page Down" is named
"Page_Down".  Similarly "+" is "plus".  
</p>

<pre class="indented">
  Scheme: (bind-key "End" 0 (lambda () "view full sound" (set! (<a class=quiet href="#xbounds">x-bounds</a>) (list 0.0 (/ (<a class=quiet href="#framples">framples</a>) (<a class=quiet href="#srate">srate</a>))))))

  Ruby: bind_key("End", 0, lambda do || set_x_bounds([0.0, framples.to_f / srate.to_f]) end)

  Forth: "End" 0 lambda: 0.0 #f #f #f framples #f srate f/ 2 &gt;list set-x-bounds ; 0 make-proc bind-key
</pre>

<pre class="indented">
(<em class=red>bind-key</em> "Home" 0 
           (lambda () 
	     (let ((ed (<a class=quiet href="#editfragment">edit-fragment</a>))) 
	       (<a class=quiet href="#statusreport">status-report</a> (<a class=quiet>format</a> #f "~A" ed)) 
	       (set! (<a class=quiet href="#cursor">cursor</a>) (caddr ed)) 
	       cursor-in-view)))

(<em class=red>bind-key</em> #\p 0 
          (lambda () 
            cursor-on-left)
          #f "#\\p-&gt;cursor-on-left")

(<em class=red>bind-key</em> #\v 4
	  (lambda ()
	    (if (&lt; (<a class=quiet href="#rightsample">right-sample</a>) (<a class=quiet href="#framples">framples</a>))
		(set! (<a class=quiet href="#leftsample">left-sample</a>) (<a class=quiet href="#rightsample">right-sample</a>)))
	    keyboard-no-action))

(<em class=red>bind-key</em> #\v 0 
          (lambda () 
            (set! (<a class=quiet href="#sample">sample</a> (<a class=quiet href="#cursor">cursor</a>)) (* 0.5 (+ (<a class=quiet href="#sample">sample</a> (- (<a class=quiet href="#cursor">cursor</a>) 1)) (<a class=quiet href="#sample">sample</a> (+ 1 (<a class=quiet href="#cursor">cursor</a>)))))) 
            cursor-in-view))
</pre>

<p id="extendedpiano">We can use bind-key to turn the keyboard into a sort of extended piano:
</p>

<pre class="indented">
(<em class=red>bind-key</em> #\o 0 
  (lambda ()
    (<a class=quiet href="#play">play</a> "oboe.snd") 
    keyboard-no-action))

(<em class=red>bind-key</em> #\p 0 
  (lambda ()
    (<a class=quiet href="#play">play</a> "pistol.snd") 
    keyboard-no-action))
</pre>

<p>Now each time we hit "o", "oboe.snd" plays,  etc.  Or say we want to move
forward two samples in the graph each time we type "l":
</p>

<pre class="indented">
(<em class=red>bind-key</em> #\l 0 
  (lambda ()
    (set! (<a class=quiet href="#leftsample">left-sample</a> 0 0) (+ 2 (<a class=quiet href="#leftsample">left-sample</a> 0 0))) 
    keyboard-no-action))
</pre>

<p>Or, more useful perhaps, have C-c set the cursor at a particular sample:
</p>

<pre class="indented">
(<em class=red>bind-key</em> #\c 4
  (lambda (arg)
    (set! (<a class=quiet href="#cursor">cursor</a>) arg) 
    cursor-in-middle))
</pre>

<p id="moveonepixel">A similar set rebinds the arrow keys to give much more precise window position and size control:
</p>

<pre class="indented">
(define (move-one-pixel s c right)
  (let* ((ax (<a class=quiet href="#axisinfo">axis-info</a> s c <a class=quiet>time-graph</a>))
	 (lo (ax 0))
	 (hi (ax 1))
	 (lo-pix (ax 10))
	 (hi-pix (ax 12))
	 (samps-per-pixel (max 1 (round (/ (- hi lo) (- hi-pix lo-pix)))))
	 (change (if right 
                     (- (min (+ hi samps-per-pixel) (<a class=quiet href="#framples">framples</a> s c)) hi)
                     (- (max 0 (- lo samps-per-pixel)) lo))))
    (set! (<a class=quiet href="#leftsample">left-sample</a>) (+ lo change))
    keyboard-no-action))

(<em class=red>bind-key</em> "Left" 0     ;left arrow
  (lambda () 
    (move-one-pixel (<a class=quiet href="#selectedsound">selected-sound</a>) (<a class=quiet href="#selectedchannel">selected-channel</a>) #f)))

(<em class=red>bind-key</em> "Right" 0    ;right arrow
  (lambda () 
    (move-one-pixel (<a class=quiet href="#selectedsound">selected-sound</a>) (<a class=quiet href="#selectedchannel">selected-channel</a>) #t)))

(define (<em class="noem" id="zoomonepixel">zoom-one-pixel</em> s c in)
  (let* ((ax (<a class=quiet href="#axisinfo">axis-info</a> s c <a class=quiet>time-graph</a>))
	 (lo (ax 0))
	 (hi (ax 1))
	 (lo-pix (ax 10))
	 (hi-pix (ax 12))
	 (samps-per-pixel (max 1 (round (/ (- hi lo) (- hi-pix lo-pix)))))
	 (len (<a class=quiet href="#framples">framples</a> s c)))
    (if in
	(if (&gt; (- hi-pix lo-pix) samps-per-pixel)
	    (begin
	      (set! (<a class=quiet href="#leftsample">left-sample</a>) (+ lo samps-per-pixel))
	      (set! (<a class=quiet href="#xzoomslider">x-zoom-slider</a>) 
                (* 1.0 (round (/ (max samps-per-pixel (- hi lo (* 2 samps-per-pixel))) len))))))
	(begin
	  (set! (<a class=quiet href="#leftsample">left-sample</a>) (max 0 (- lo samps-per-pixel)))
	  (set! (<a class=quiet href="#xzoomslider">x-zoom-slider</a>) 
            (* 1.0 (round (/ (min len (+ (- hi lo) (* 2 samps-per-pixel))) len))))))
    keyboard-no-action))

(<em class=red>bind-key</em> "Up" 0     ;up arrow
  (lambda () 
    (zoom-one-pixel (<a class=quiet href="#selectedsound">selected-sound</a>) (<a class=quiet href="#selectedchannel">selected-channel</a>) #f)))

(<em class=red>bind-key</em> "Down" 0   ;down arrow
  (lambda () 
    (zoom-one-pixel (<a class=quiet href="#selectedsound">selected-sound</a>) (<a class=quiet href="#selectedchannel">selected-channel</a>) #t)))
</pre>

<p>The key bindings set by bind-key are active only when the active widget is a graph; when the listener is receiving
key strokes, the underlying text widget interprets them itself (using Emacs as a vague guide).  You can change the listener's interpretation
in the following manner (this assumes you're using Motif and have the xm module loaded):
</p>

<pre class="indented">
(XtAppAddActions (car (<a class=quiet href="#mainwidgets">main-widgets</a>)) (list (list "hiho" (lambda args (<a class=quiet href="#sndprint">snd-print</a> "hiho")))))
(XtOverrideTranslations ((<a class=quiet href="#mainwidgets">main-widgets</a>) 4) (XtParseTranslationTable "Ctrl &lt;Key&gt;i: hiho()\n"))
</pre>

<p>Since Motif does not explicitly support an Emacs-like extended mode, we have to go to
a bit of trouble to add an extended command to the listener.  The following implements C-x C-f
in Motif:
</p>

<pre class="indented">
;;; Motif version:

(define extended #f)     ; our extended mode flag

(XtAddEventHandler ((<a class=quiet href="#mainwidgets">main-widgets</a>) 4) KeyPressMask #f
  (lambda (w context event go)
    (let* ((bits (.state event))
	   (keysym (XKeycodeToKeysym (XtDisplay w)
				    (.keycode event)
				    (if (not (= (logand bits ShiftMask) 0)) 1 0))))
      (if (= (logand bits ControlMask) 0)
	  (set! extended #f)
	  ;; got C-&lt;something&gt;
	  (if (= (cadr keysym) 120) ; C-x
	      (set! extended #t)
	      (begin
		(if (and extended
			 (= (cadr keysym) 102)) ; C-x C-f
		    (<a class=quiet href="#openfiledialog">open-file-dialog</a>))
		(set! extended #f)))))))
</pre>
<div class="separator"></div>


<!-- break -->
<pre class="indented">
<em class=def id="break">break</em>
</pre>

<p>In s7, this places a breakpoint at the current code location.
If you hit the breakpoint, the listener prompt reflects the current
function name (if any), and any typing at that point is evaluated
in the local environment (so you have access to function arguments and
local variables).  To continue from the breakpoint, (break-ok).  To
exit back to the top level, (break-exit):
</p>
<div class="spacer"></div>


<!-- c-g? -->
<pre class="indented">
<em class=def id="cgp">c-g?</em>
</pre>

<p>This checks for C-g to interrupt an on-going computation, and lets other UI 
events through.  It is obsolete in s7.
</p>
<div class="spacer"></div>


<!-- erf -->
<pre class="indented">
<em class=emdef>erf</em> x
<em class=emdef>erfc</em> n x
</pre>

<p>These are the erf and erfc functions from the math library.
</p>
<div class="spacer"></div>


<!-- exit -->
<pre class="indented">
<em class=def id="exit">exit</em> exit-value
</pre>

<p>This exits Snd.  Scheme's exit function is renamed %exit.  In Forth, this function is snd-exit.
The hooks associated with this function are:
</p>

<pre class="indented">
<a class=quiet href="#beforeexithook">before-exit-hook</a> &mdash; can cancel exit request
<a class=quiet href="#exithook">exit-hook</a>
Snd cleans up and exits
</pre>
<div class="spacer"></div>


<!-- fmod -->
<pre class="indented">
<em class=emdef>fmod</em> x y
</pre>

<p>fmod is mod with float arguments:
</p>

<pre class="indented">
&gt; (fmod 2.5 1.4)
1.1
</pre>

<p>In Scheme, fmod is a synonym for modulo.
</p>
<div class="spacer"></div>


<!-- gc-off -->
<pre class="indented">
<em class=def id="gcoff">gc-off</em>
</pre>

<p>gc-off turns garbage collection off, if possible.
</p>
<div class="spacer"></div>


<!-- gc-on -->
<pre class="indented">
<em class=def id="gcon">gc-on</em>
</pre>

<p>gc-on turns garbage collection on.
</p>
<div class="spacer"></div>


<!-- in -->
<pre class="indented">
<em class=def id="gin">in</em> ms thunk
</pre>

<p>'ms' milliseconds from now, evaluate 'thunk', a function of no arguments.  In Ruby, this
is named "call_in".
</p>

<pre class="indented">
(<em class=red>in</em> 5000 (lambda () (<a class=quiet href="#sndprint">snd-print</a> "boo!")))
</pre>

<pre class="indented">
(define (at hour minute func)
  (let* ((cur-time (localtime (current-time)))
	 (cur-minute (cur-time 1))
	 (cur-hour (cur-time 2))
	 (now (+ (* cur-hour 60) cur-minute))
	 (then (+ (* hour 60) minute)))
    (<em class=red>in</em> (* 60000 (- then now)) func)))

(at 15 11 (lambda () (<a class=quiet href="#sndprint">snd-print</a> "it's 3:11 pm!")))
</pre>
<div class="spacer"></div>



<!-- key -->
<pre class="indented">
<em class=def id="key">key</em> key state snd chn
</pre>

<p>This executes the keyboard command 'key' with modifier keys 'state'.
'state' is a combination of control = 4 and meta = 8.
</p>
<div class="spacer"></div>


<!-- key-binding -->
<pre class="indented">
<em class=def id="keybinding">key-binding</em> key (state 0) extended
</pre>

<p>This returns the user-defined (not built-in) procedure, if any, currently bound to 'key' with 'state' and 'extended' flags.
'state' is a combination of control = 4 and meta = 8.  'extended' is #t if the command
is preceded by C-x.
</p>

<pre class="indented">
&gt; (key-binding "Right" 0)
#&lt;procedure #f (() "move one pixel forward" (move-one-pixel (selected-sound) (selected-channel) #t))&gt;
</pre>
<div class="spacer"></div>


<!-- lgamma -->
<pre class="indented">
<em class=emdef>lgamma</em> x<br>
</pre>

<p>This is the lgamma function from the math library.
</p>
<div class="spacer"></div>


<!-- little-endian? -->
<pre class="indented">
<em class=def id="littleendianp">little-endian?</em>
</pre>

<p>This returns #t if underlying machine is little endian.
</p>
<div class="spacer"></div>


<!-- save-state -->
<pre class="indented">
<em class=def id="savestate">save-state</em> filename
</pre>

<p>This saves the current state of Snd in 'filename'.  The saved-state file is a Scheme/Ruby/Forth program that when loaded
into Snd, recreates the state of Snd (as far as possible) at the point of the save.  
<a href="#savestatehook">save-state-hook</a> is called during the saving process (once on each temp file),
and <a href="#aftersavestatehook">after-save-state-hook</a> is called afterwards.
'filename' defaults to <a href="#savestatefile">save-state-file</a> which itself defaults to "saved-snd.scm"
or some variant thereof.
</p>

<p>There are a variety of
limitations to this process; the worst is that save-state does not try to save hook values or global variable values.
If you call save-state with active regions, and have the region browser running all the time, and subsequently
want to back up to the saved state, it's safer to delete all the regions first (via <a href="#forgetregion">forget-region</a>), 
then load the saved-state file.
</p>
<div class="spacer"></div>


<!-- script-arg -->
<pre class="indented">
<em class=def id="scriptarg">script-arg</em>
</pre>

<p>This is the current startup argument number (normally 1). See <a href="grfsnd.html#sndwithnogui">Snd as a script engine</a> and snd-test.scm.
</p>
<div class="spacer"></div>


<!-- script-args -->
<pre class="indented">
<em class=def id="scriptargs">script-args</em>
</pre>

<p>This returns the startup arguments as a list of strings. See <a href="grfsnd.html#sndwithnogui">Snd as a script engine</a> and snd-test.scm.
</p>
<div class="spacer"></div>


<!-- snd-error -->
<pre class="indented">
<em class=def id="snderror">snd-error</em> str
</pre>

<p>This throws 'snd-error with the error message 'str'.  It provides a way to dive directly into
Snd's error handling mechanism.
See also <a href="#muserrorhook">mus-error-hook</a> and <a href="#snderrorhook">snd-error-hook</a>.
</p>
<div class="spacer"></div>


<!-- snd-help -->
<pre class="indented">
<em class=def id="sndhelp">snd-help</em> obj (formatted #t)
</pre>

<p>This returns the help text associated with 'obj':
</p>

<pre class="indented">
Scheme:
&gt; (snd-help 'open-sound)   ; or "open-sound"
"(open-sound filename) opens filename (as if opened from File:Open menu option), 
and returns the new sound's index"

Ruby:
:snd_help("close_sound")  ; or :open_sound
close_sound((snd false)): close snd

Forth:
snd> "revert-sound" snd-help
(revert-sound (snd #f)): revert snd to its unedited state (undo all)
</pre>

<p>If no help string can be found, or if the name doesn't come close to any currently defined name,
snd-help runs through the current load path searching *.scm (or *.rb) files for a definition
of that name.  So, if you haven't loaded dsp.scm:
</p>

<pre class="indented">
&gt; (snd-help "volterra-filter")
"volterra-filter is not defined; it appears to be defined in:
/home/bil/cl/dsp.scm:1936&gt; (define (volterra-filter flt x) <!-- ) -->
and documented at sndscm.html#volterrafilter"
</pre>

<p>snd-help tries to be smart about minor mispellings:
</p>

<pre class="indented">
&gt; (snd-help "close-soud")
"(close-sound (snd #f)): close snd
Other possibilities:
close-sound is defined; it is documented at extsnd.html#closesound"
</pre>

<p>To go to the
HTML documentation for a given object, load <a href="sndscm.html#indexdoc">index.scm</a> and use the html function.
</p>

<p>Normally snd-help adds carriage-returns to fit the current size of the listener; to
get the raw string instead, set the argument 'formatted' to #f (or use s7's help function).
</p>
<div class="spacer"></div>

<!-- snd-version -->
<pre class="indented">
<em class=def id="sndversion">snd-version</em>
</pre>

<p>This is a string giving the current Snd version.
</p>
<div class="spacer"></div>




<!-- *snd-opened-sound* -->
<pre class="indented">
<em class=def id="sndopenedsound">*snd-opened-sound*</em>
</pre>

<p>When a sound file is opened, Snd looks for a file with the same 
name but with an appended ".scm" extension.  If such a file is found, 
it is loaded automatically.  The variable *snd-opened-sound* is set to 
the newly opened sound (the object).  This supports the snd-memo feature 
in the CL version of CLM, but can be used independently of CLM to store marks, selections,
or whatever that you want associated with a particular sound. Confusingly
enough, this is a variable, unlike all the others &mdash; that is, you
refer to it directly, not as a procedure call.  Say we have a sound file "now.snd",
and we want it to use the grid-graph whenever it is viewed.  We make "now.snd.scm"
and put in it: (set! (show-grid *snd-opened-sound*) #t).  When "now.snd" is
opened, "now.snd.scm" is loaded automatically with *snd-opened-sound* holding the sound object of "now.snd".
</p>
<div class="spacer"></div>


<!-- snd-print -->
<pre class="indented">
<em class=def id="sndprint">snd-print</em> str
</pre>

<p>This displays 'str' in the listener, then returns 'str'.
</p>
<div class="spacer"></div>


<!-- snd-tempnam -->
<pre class="indented">
<em class=def id="sndtempnam">snd-tempnam</em>
</pre>

<p>This returns a new temp file name using Snd's <a href="#tempdir">temp-dir</a>.
</p>

<pre class="indented">
&gt; (temp-dir)
"/home/bil/zap/tmp"
&gt; (snd-tempnam)
"/home/bil/zap/tmp/snd_7000_2.snd"
</pre>
<div class="spacer"></div>


<!-- snd-url -->
<pre class="indented">
<em class=def id="sndurl">snd-url</em> name
</pre>

<p>This is the url (in the Snd documentation) corresponding to 'name'; 'name' can be a string or a symbol.
</p>

<pre class="indented">
&gt; (snd-url 'open-sound)
"extsnd.html#opensound"
</pre>
<div class="spacer"></div>


<!-- snd-urls -->
<pre class="indented">
<em class=def id="sndurls">snd-urls</em>
</pre>

<p>This returns a list of lists, each inner list containing a Snd function name (as a string) and its associated url in the Snd documentation.
</p>

<pre class="indented">
&gt; (assoc "open-sound" (snd-urls))
("open-sound" . "extsnd.html#opensound")
</pre>
<div class="spacer"></div>


<!-- snd-warning -->
<pre class="indented">
<em class=def id="sndwarning">snd-warning</em> str
</pre>

<p>This posts a 'str' in the status area and returns 'str'.
See also <a href="#sndwarninghook">snd-warning-hook</a>.
</p>
<div class="spacer"></div>


<!-- unbind-key -->
<pre class="indented">
<em class=def id="unbindkey">unbind-key</em> key state extended
</pre>

<p>This causes 'key' with modifiers 'state' and 'extended' to revert to its built-in default.
</p>
<div class="spacer"></div>



<!--  CONSTANTS  -->

<div class="header" id="sndconstants">Constants</div>

<p id="musoutformat"><b>Sndlib</b> (see <a href="sndlib.html#sndlibxen">sndlib.html</a> for a complete list):
</p>

<pre class="indented">
mus-next mus-aifc mus-riff mus-rf64 mus-nist mus-raw mus-ircam mus-aiff
mus-bicsf mus-soundfont mus-voc mus-svx mus-caff

mus-bshort  mus-lshort mus-mulaw  mus-alaw   mus-byte   mus-ubyte   mus-bfloat
mus-lfloat  mus-bint   mus-lint   mus-b24int mus-l24int mus-bdouble mus-ldouble
mus-ubshort mus-ulshort

mus-out-format
</pre>

<p><b>Time domain graph type</b> (<a href="#timegraphtype">time-graph-type</a>):</p>
<pre class="indented">
  graph-once  <a class=quiet href="snd.html#wavogram">graph-as-wavogram</a>
</pre>

<p><b>Transform graph type</b> (the Transform Options Display choice, <a href="#transformgraphtype">transform-graph-type</a>):</p>
<pre class="indented">
  graph-once  graph-as-sonogram  graph-as-spectrogram
</pre>

<p><b>Transform type</b> (<a href="#transformtype">transform-type</a>):</p>
<pre class="indented">
  fourier-transform  wavelet-transform   cepstrum   haar-transform
  autocorrelation    walsh-transform
</pre>

<p><b>Transform normalization</b> (<a href="#normalizefft">transform-normalization</a>):</p>
<pre class="indented">
  dont-normalize     normalize-by-channel    normalize-by-sound    normalize-globally
</pre>

<p><b>FFT Window</b> type (<a href="#fftwindow">fft-window</a>):</p>
<pre class="indented">
  rectangular-window     hann(ing)-window      welch-window         parzen-window
  bartlett-window        hamming-window        blackman2-window     blackman3-window
  blackman4-window       exponential-window    riemann-window       kaiser-window
  cauchy-window          poisson-window        gaussian-window      tukey-window
  dolph-chebyshev-window hann-poisson-window   connes-window        samaraki-window
  ultraspherical-window  bartlett-hann-window  bohman-window        flat-top-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><b>Zoom Focus</b> style (<a href="#zoomfocusstyle">zoom-focus-style</a>):</p>
<pre class="indented">
  zoom-focus-left    zoom-focus-right   zoom-focus-active zoom-focus-middle
</pre>

<p><b>X-axis Label</b> (<a href="#xaxisstyle">x-axis-style</a>):</p>
<pre class="indented">
  x-axis-in-seconds  x-axis-in-samples  x-axis-as-percentage  x-axis-in-beats  x-axis-in-measures x-axis-as-clock
</pre>

<p><b>Speed Control</b> style (<a href="#speedstyle">speed-control-style</a>, <a href="#viewfilesspeedstyle">view-files-speed-style</a>):</p>
<pre class="indented">
  speed-control-as-float     speed-control-as-ratio     speed-control-as-semitone
</pre>

<p><b>Channel Combination</b> style (<a href="#channelstyle">channel-style</a>):</p>
<pre class="indented">
  channels-separate  channels-combined  channels-superimposed
</pre>

<p><b>Envelope Editor</b> target (<a href="#envedtarget">enved-target</a>):</p>
<pre class="indented">
  enved-amplitude      enved-spectrum       enved-srate
</pre>

<p><b>Envelope Editor</b> ramp choice (<a href="#envedstyle">enved-style</a>):</p>
<pre class="indented">
  envelope-linear   envelope-exponential
</pre>

<p><b>Graph Line</b> style (<a href="#graphstyle">graph-style</a>):</p>
<pre class="indented">
  graph-lines        graph-dots         graph-filled      graph-lollipops
  graph-dots-and-lines 
</pre>

<p><b>Key binding</b> cursor action (<a href="#bindkey">bind-key</a>):</p>
<pre class="indented">
  cursor-in-view     cursor-on-left     cursor-on-right   cursor-in-middle  keyboard-no-action
</pre>

<p><b>Cursor</b> style (<a href="#cursorstyle">cursor-style</a>):</p>
<pre class="indented">
  cursor-cross   cursor-line
</pre>

<p><b>Axis placement</b> choice (<a href="#showaxes">show-axes</a>):</p>
<pre class="indented">
  show-all-axes  show-no-axes  show-x-axis  show-all-axes-unlabelled  show-x-axis-unlabelled  show-bare-x-axis
</pre>

<p><b>Graph</b> id (for <a href="#ytoposition">y-&gt;position</a> etc):</p>
<pre class="indented">
  time-graph     transform-graph     lisp-graph
</pre>

<p><b>Colormap</b> choice (<a href="#colormap">colormap</a>):</p>
<pre class="indented">
  black-and-white-colormap gray-colormap     hot-colormap     cool-colormap
  bone-colormap            copper-colormap   pink-colormap    jet-colormap
  prism-colormap           autumn-colormap   winter-colormap  spring-colormap
  summer-colormap          rainbow-colormap  flag-colormap    phases-colormap
</pre>

<p><b>Graphics context</b> choice (<a href="#graphdata">graph-data</a>)</p>
<pre class="indented">
  copy-context   cursor-context   selection-context  mark-context
</pre>




<!--  ERRORS  -->

<div class="header" id="snderrors">Errors and debugging</div>
<!-- INDEX snderrors:Debugging (Scheme) -->

<p>When something goes awry, the various functions can throw an error (a symbol)
which is normally caught by the default error handler (this is a kind of goto 
but without the embarrassment).  It prints out some message,
and sometimes appends a stack trace.  So, as an example, selection-position
throws 'no-active-selection if there isn't a selection:
</p>

<pre class="indented">
&gt; (selection-position)
selection-position: no-active-selection
&gt; asdf
Unbound variable: asdf
</pre>

<p>But there are cases where you'd rather handle an error (or all errors) specially.
In the case of 'no-active-selection, we set up our own handler for that as follows:
</p>

<pre class="indented">
&gt; (catch 'no-active-selection 
    (lambda () 
      (+ 1 (<a class=quiet href="#selectionposition">selection-position</a>))) 
    (lambda (tag val) 0))
0
</pre>

<p>Here we've caught 'no-active-selection (if it occurs within the
first thunk's body), and return 0 if it occurs; otherwise we return
(+ 1 (<a class=quiet href="#selectionposition">selection-position</a>)).  Scheme has a number
of errors such as 'out-of-range, 'wrong-type-arg, 'numerical-overflow,
etc.  The Snd-specific errors are:
</p>

<pre class="indented">
'no-such-channel  'no-such-sound  'no-such-mark       'no-such-mix
'no-such-menu     'no-such-file   'no-such-region     'no-such-sample
'no-such-edit     'cannot-save    'no-such-envelope   'no-active-selection
'no-such-widget   'mus-error                          'bad-arity
'cannot-print     'no-such-axis   'no-such-player     'no-such-graphics-context
'no-such-color    'no-such-widget 'no-such-plugin     'no-data
'gsl-error        'no-such-key    'no-such-direction  'cannot-parse
'no-such-colormap
</pre>

<p>bad-arity is jargon indicating that a procedure has been passed the
wrong number of arguments.  gsl-error indicates that the GSL
library is the source of the error.
The symbol #t stands for all errors in this case, so we can 
run rough-shod over any error with:
</p>

<pre class="indented">
(define-macro (without-errors func)
  `(catch #t 
	  (lambda ()
	    ,func)
	  (lambda args 
            (car args))))
</pre>

<p>You can use these errors in your code, if you like, or add your own.  The following
throws the error 'no-such-file:
</p>

<pre class="indented">
(define look-for-file
  (lambda (file)
    (or (file-exists? file)
	(error 'no-such-file (list "look-for-file" file)))))
</pre>

<p>There is one special catch: 'snd-top-level.  This is used by the
debuggers to exit the current context, returning up a level in the
stack of listeners.  Normally that means you jump out of a breakpoint
or whatever and find yourself back at the top level.  (throw 'snd-top-level).
</p>


<div class="innermostheader">s7 debugging</div>

<p>When s7 hits an error, it prints out a stacktrace as well as the error message.
The <a href="s7.html#owlet">owlet</a> has additional info.  You can also trace functions, and
place breakpoints.  See <a href="s7.html">s7.html</a> for further details.
</p>


<div class="innermostheader">Forth debugging</div>
<p>See the debugging section in the fth documentation.
</p>


<div class="innermostheader">Ruby debugging</div>
<p>
$DEBUG = true turns on the Ruby debugger.
</p>


<div class="innermostheader" id="cdebugging">C debugging</div>

<!-- INDEX cdebugging:Debugging (C) -->
<p>If you hit a bug in Snd's C code, you'll need to use gdb
to track it down, or mail me the gory details;
if the error is a segfault, there is probably a file named "core" or "core.nnnn"
on the current directory:
</p>

<pre class="indented">
gdb snd core
where
</pre>

<p>The "where" command displays the stack at the point of the error.
"up", and "down" move around in the stack, and "info locals" prints out
the current frame's variables.  If it's not a segfault, you can
</p>

<pre class="indented">
gdb snd
run
</pre>

<p>Then get the error to happen, at which point you should fall into gdb
where you can type "where" and so on.  If the problem involves X, you
may need to run -sync.  If Snd gets hung
and you need to type C-C to get out (that is, C-g doesn't interrupt the loop), 
</p>

<pre class="indented">
gdb snd
break exit
run
</pre>




<div class="header" id="appearance">Customizing Snd's appearance</div>

<p>Snd's overall appearance is controlled first by the startup <a href="grfsnd.html#sndswitches">switches</a> that
choose the outermost widget; normally this is a paned window with a sound
in each pane; -separate puts each
sound in a separate window, and -notebook
puts each sound on a separate page of a notebook widget.  Similarly -horizontal
and -vertical determine which way the outer panes are laid out. 
There are a variety of functions and variables related to widget colors and so forth.
</p>


<!--  COLORS  -->

<div class="header" id="colors">Colors</div>

<p>A color in Snd is an object with three fields representing the
rgb (red green blue) settings as numbers between 0.0 and 1.0.  A color
object is created via make-color:
</p>

<pre class="indented">
&gt; (define blue (<a class=quiet href="#makecolor">make-color</a> 0 0 1))
</pre>

<p>This declares the Scheme variable "blue" and gives it the value
of the color whose rgb components include only blue in full force.
The X11 color names are defined in <a href="sndscm.html#rgbdoc">rgb.scm</a>. The overall
widget background color is basic-color.
</p>

<pre class="indented">
&gt; (set! (<a class=quiet href="#basiccolor">basic-color</a>) blue)
</pre>

<p>The color variables
are:
</p>

<pre class="indented">
<em class=def id="axiscolor">axis-color</em>                    black           color of axes
<em class=def id="basiccolor">basic-color</em>                   ivory2          main Snd color.
<em class=def id="combineddatacolor">combined-data-color</em>           black           color of channel data if channels-combined
<em class=def id="cursorcolor">cursor-color</em>                  red             graph cursor color.
<em class=def id="datacolor">data-color</em>                    black           color of data in unselected graph.
<em class=emdef>enved-waveform-color</em>          blue            color of waveform displayed in envelope editor.
<em class=emdef>filter-control-waveform-color</em> blue            color of control panel filter waveform.
<em class=def id="graphcolor">graph-color</em>                   white           background color of unselected graph.
<em class=def id="highlightcolor">highlight-color</em>               ivory1          highlighting color.
<em class=emdef>listener-color</em>                aliceblue       background color of listener.
<em class=emdef>listener-colorized</em>            #f              is syntax highlighting in effect.
<em class=emdef>listener-text-color</em>           black           text color in listener.
<em class=def id="markcolor">mark-color</em>                    red             color of mark indicator.
<em class=emdef>mix-color</em>                     darkgray        color of mix waveforms.
<em class=def id="positioncolor">position-color</em>                ivory3          position slider color
<em class=def id="sashcolor">sash-color</em>                    lightgreen      color of paned window sashes.
<em class=def id="selecteddatacolor">selected-data-color</em>           black           color of data in currently selected graph.
<em class=def id="selectedgraphcolor">selected-graph-color</em>          white           background color of currently selected graph.
<em class=def id="selectioncolor">selection-color</em>               lightsteelblue1 color of selected portion of graph.
<em class=def id="textfocuscolor">text-focus-color</em>              white           color of text field when it has focus.
<em class=def id="zoomcolor">zoom-color</em>                    ivory4          zoom slider color.
</pre>

<p>I have these lines in my ~/.snd_s7 file:
</p>

<pre class="indented">
(define beige (<a class=quiet href="#makecolor">make-color</a> 0.96 0.96 0.86))
(define blue (<a class=quiet href="#makecolor">make-color</a> 0 0 1))
(set! *selected-graph-color* beige)
(set! *selected-data-color* blue)
</pre>

<p>In Forth (~/.snd_forth) this is:
</p>

<pre class="indented">
0.96 0.96 0.86 make-color ( beige ) set-selected-graph-color drop
0.00 0.00 1.00 make-color ( blue )  set-selected-data-color drop
</pre>

<p>And in Ruby (~/.snd_ruby):
</p>

<pre class="indented">
beige = make_color 0.96, 0.96, 0.86
blue = make_color 0, 0, 1
set_selected_graph_color beige
set_selected_data_color blue
</pre>

<p>combined-data-color is slightly special.  It takes two arguments, the sound and channel number, and applies to the
channel's data only if the graphs are superimposed, when <a href="#channelstyle">channel-style</a> is channels-combined.
</p>

<!-- INDEX colors:Colors -->
<TABLE class="method">
<tr><th class="title"><a class=quiet href="extsnd.html#colors">Colors</a></th></tr>
<tr><td>
<blockquote><small>
Other color-related stuff:<br>
Color names: <a href="sndscm.html#rgbdoc">rgb.scm, rgb.rb</a><br>
colors in the file dialogs: install-searcher-with-colors in snd-motif.scm<br>
color-orientation-dialog: <a href="extsnd.html#colororientationdialog">color-orientation-dialog</a><br>
colored samples: <a href="sndscm.html#drawdoc">display-colored-samples</a> and others in draw.scm<br>
colored edits: <a href="sndscm.html#drawdoc">display-previous-edits</a> in draw.scm<br>
colored marks: mark-sync-color in snd-motif.scm<br>
colors in rxvt: red-text et al in examp.scm<br>
flashing colors: flash-selected-data in examp.scm<br>
openGL: snd-gl.scm, <a href="grfsnd.html#sndandgl">Snd and OpenGL</a><br>
color hook: <a href="extsnd.html#colorhook">color-hook</a><br>
Snd graphics contexts: <a href="extsnd.html#sndgcs">snd-gcs</a><br>
</small></blockquote>
</td></tr></TABLE>




<!--  FONTS  -->

<div class="header" id="fonts">Fonts</div>

<p>Fonts in Snd are strings containing a description of the
desired font.  These can be the abbreviated forms such as
"8x14" or a full X font name such as "-misc-fixed-bold-r-normal--*-140-*-*-*-*-*-*".
The font variables are:
</p>

<pre class="indented">
<em class=def id="axislabelfont">axis-label-font</em>     used in axis labels
<em class=def id="axisnumbersfont">axis-numbers-font</em>   used in axis tick numbers
<em class=def id="boldpeaksfont">bold-peaks-font</em>     used by fft peaks display
<em class=def id="peaksfont">peaks-font</em>          used by fft peaks display
<em class=emdef>listener-font</em>       listener font
<em class=def id="tinyfont">tiny-font</em>           smallest font used
</pre>

<pre class="indented">
(set! (<a class=quiet href="#listenerfont">listener-font</a>) "9x15")
(set! (<a class=quiet href="#axislabelfont">axis-label-font</a>) "-*-times-medium-r-normal-*-18-*-*-*-*-*-*-*")
(set! (<a class=quiet href="#axisnumbersfont">axis-numbers-font</a>) "9x15")
</pre>

<p>See also <a href="#currentfont">current-font</a> below.
If the requested font can't be loaded, the set! statement returns the old (unchanged) font name.
</p>

<pre class="indented">
&gt; (set! (axis-label-font) "8x14")
"-*-times-medium-r-normal-*-18-*-*-*-*-*-*-*"
</pre>



<div class="header" id="graphics">Graphics</div>

<!--  GRAPHICS  -->
<div class="spacer"></div>

<!-- add-colormap -->
<pre class="indented">
<em class=def id="addcolormap">add-colormap</em> name func
</pre>

<p>add-colormap adds a new colormap to the colormap table, returning the colormap object (for
use with <a href="#colormap">colormap</a> or <a href="#colormapref">colormap-ref</a>).
'name' is the name displayed in the Color/Orientation Dialog's list of colormaps.
'func' is a function of one argument, the desired colormap size; it will be
called whenever the new colormap's values are needed or the colormap size changes,
so that the colormap needs to be recomputed.  It should return a list of
three float-vectors, each float-vector containing 'size' values representing respectively
the red, green, and blue values (each a number between 0.0 and 1.0).
In the following code, the fields are set from envelopes (this is a loose translation
of FractInt's royal colormap):
</p>

<pre class="indented">
(add-colormap "purple" 
  (lambda (size) 
    (do ((r (make-float-vector size))
	 (g (make-float-vector size))
	 (b (make-float-vector size))
	 (incr (/ 256.0 size))
	 (er (list 0 60 60 116 128 252 192 252 256 60))
	 (eg (list 0 0  64 0   128 252 192 252 256 0))
	 (eb (list 0 80        128 252 192 0   256 80))
         (i 0 (+ i 1))
	 (x 0.0 (+ x incr)))
        ((= i size)
	 (list r g b))
      (set! (r i) (/ (<a class=quiet href="sndscm.html#envelopeinterp">envelope-interp</a> x er) 256.0)) ; from env.scm
      (set! (g i) (/ (<a class=quiet href="sndscm.html#envelopeinterp">envelope-interp</a> x eg) 256.0))
      (set! (b i) (/ (<a class=quiet href="sndscm.html#envelopeinterp">envelope-interp</a> x eb) 256.0)))))

;;; another amusing colormap from FractInt:
(add-colormap "cos" 
  (lambda (size) 
    (do ((r (make-float-vector size))
	 (g (make-float-vector size))
	 (b (make-float-vector size))
	 (incr (/ 3.14159 size))
         (i 0 (+ i 1))
	 (x 0.0 (+ x incr)))
	((= i size)
         (list r g b))
      (set! (r i) (abs (sin (* 1.5 x))))
      (set! (g i) (abs (sin (* 3.5 x))))
      (set! (b i) (abs (sin (* 2.5 x)))))))
</pre>

<table><tr>
<td><img src="pix/coscolor.png" alt="colormaps"></td>
<td><img class="indented" src="pix/jetcolor.png" alt="colormaps"></td>
<td><img class="indented" src="pix/hotcolor.png" alt="colormaps"></td>
</tr></table>
<div class="spacer"></div>


<!-- background-gradient -->
<pre class="indented">
<em class=def id="backgroundgradient">background-gradient</em>
</pre>

<div class="spacer"></div>


<!-- color? -->
<pre class="indented">
<em class=def id="colorp">color?</em> obj
</pre>

<p>This returns #t if 'obj' is a color (a Pixel in xm jargon); see <a href="#makecolor">make-color</a>.
</p>
<div class="spacer"></div>


<!-- color->list -->
<pre class="indented">
<em class=def id="colortolist">color-&gt;list</em> obj
</pre>

<p>This returns the rgb color components of 'obj' in a list.
</p>

<pre class="indented">
  &gt; (color-&gt;list (make-color 1 0 0))
  (1.0 0.0 0.0)
</pre>
<div class="spacer"></div>


<!--  color-cutoff -->
<pre class="indented">
<em class=def id="colorcutoff">color-cutoff</em>
</pre>

<p>In spectra, this sets the lowest data value that will be colored (the default is 0.003).  Anything less than that
is rendered in the background color.  This is the "data cutoff" slider in the View:Color/Orientation dialog.
</p>
<div class="spacer"></div>


<!--  color-inverted -->
<pre class="indented">
<em class=def id="colorinverted">color-inverted</em>
</pre>

<p>This reflects the 'invert' button in the View:<a href="snd.html#colorbrowser">Color/Orientation</a> dialog.
If the colormap is inverted, the order of colors is reversed.
</p>
<div class="spacer"></div>


<!-- color-scale -->
<pre class="indented">
<em class=def id="colorscale">color-scale</em>
</pre>

<p>color-scale reflects the darkness setting in the View:<a href="snd.html#colorbrowser">Color/Orientation</a> dialog.
The mapping between the slider in the dialog and the color-scale value is not linear, and is
currently different in Motif.  
</p>
<div class="spacer"></div>


<!-- colormap -->
<pre class="indented">
<em class=def id="colormap">colormap</em>
</pre>

<p>This is the colormap choice for various displays, most prominently the transform sonogram and spectrogram,
and the wavogram.
The built-in maps are: 
black-and-white-colormap, gray-colormap, hot-colormap, cool-colormap, bone-colormap, 
copper-colormap, pink-colormap, jet-colormap, prism-colormap, autumn-colormap, winter-colormap, 
spring-colormap, summer-colormap, rainbow-colormap, flag-colormap, and phases-colormap. 
</p>
<div class="spacer"></div>


<!-- colormap-name -->
<pre class="indented">
<em class=def id="colormapname">colormap-name</em> index
</pre>

<p>colormap-name returns the specified colormap's name.
</p>

<pre class="indented">
&gt; (colormap-name (colormap))
"hot"
</pre>
<div class="spacer"></div>


<!-- colormap-ref -->
<pre class="indented">
<em class=def id="colormapref">colormap-ref</em> map pos
</pre>

<p>colormap-ref returns the rgb values of the colormap 'map' at position 'pos',
suitable for use with make-color.  'pos' should be a float between
0.0 and 1.0.
See the example above, or samples-via-colormap in draw.scm.
</p>
<div class="spacer"></div>


<!-- colormap-size -->
<pre class="indented">
<em class=def id="colormapsize">colormap-size</em>
</pre>

<p>colormap-size returns (or sets) the current number of colors in each colormap.
The default is 512.
</p>
<div class="spacer"></div>


<!-- colormap->integer -->
<pre class="indented">
<em class=def id="colormaptointeger">colormap-&gt;integer</em> colormap-object
</pre>

<p>This function returns the integer corresponding to a given colormap.
</p>
<div class="spacer"></div>


<!-- colormap? -->
<pre class="indented">
<em class=def id="colormapp">colormap?</em> object
</pre>

<p>colormap? returns #t if 'object' is a usable colormap.
</p>
<div class="spacer"></div>


<!-- copy-context -->
<pre class="indented">
<em class=def id="copycontext">copy-context</em>
</pre>

<p>This is the graphics mode (an integer in Snd, not a function) to use to draw over whatever is currently in a graph.
The "contexts" refer to graphics contexts used throughout Snd; the copy-context
copies into the current graph, whereas the cursor-context uses XOR.
The error thrown for an unimplemented context is 'no-such-graphics-context.
</p>
<div class="spacer"></div>


<!-- current-font -->
<pre class="indented">
<em class=def id="currentfont">current-font</em> snd chn context
</pre>

<div class="spacer"></div>


<!-- cursor-context -->
<pre class="indented">
<em class=def id="cursorcontext">cursor-context</em>
</pre>

<p>This is the graphics mode (an integer in Snd, not a function) for XOR drawing in the cursor color (for cursors, normally).
See <a href="#xcursor">x-cursor</a> or
<a href="#foregroundcolor">foreground-color</a>.
</p>
<div class="spacer"></div>


<!-- delete-colormap -->
<pre class="indented">
<em class=def id="deletecolormap">delete-colormap</em> object
</pre>

<p>delete-colormap deletes the memory associated with the given colormap.
</p>
<div class="spacer"></div>


<!-- draw-axes -->
<pre class="indented">
<em class=def id="drawaxes">draw-axes</em> wid gc label x0 x1 y0 y1 style axes cr
</pre>

<p>This draws axes in the widget 'wid', using the graphics context 'gc', with the x-axis label 'label'
going from 'x0' to 'x1' (floats) along the x axis, 'y0' to 'y1' along the y axis, with x-axis-style
'style' (x-axis-in-seconds etc).  Whether axes are actually displayed or just implied
depends on 'axes', which defaults to show-all-axes. The "cr" argument is ignored in Motif.
draw-axes returns a list of the actual (pixel) axis bounds.  
</p>
<div class="spacer"></div>


<!-- draw-dot -->
<pre class="indented">
<em class=def id="drawdot">draw-dot</em> x0 y0 dot-size snd chn context cr
</pre>

<p>This draws a dot at ('x0 y0') of diameter 'dot-size' pixels in the specified context.  See musglyphs.scm.
</p>
<div class="spacer"></div>


<!-- draw-dots -->
<pre class="indented">
<em class=def id="drawdots">draw-dots</em> positions dot-size snd chn context cr
</pre>

<p>This draws dots of size 'dot-size' from the (x y) pairs in the vector 'positions' in the specified context.
draw-dots, draw-lines, and fill-polygon take vectors, rather than float-vectors (which would be more consistent
with the rest of Snd) because the values passed are supposed to be short ints.
</p>
<div class="spacer"></div>


<!-- draw-line -->
<pre class="indented">
<em class=def id="drawline">draw-line</em> x0 y0 x1 y1 snd chn context cr
</pre>

<p>This draws a line from ('x0 y0') to ('x1 y1') in the specified context.
</p>
<div class="spacer"></div>


<!-- draw-lines -->
<pre class="indented">
<em class=def id="drawlines">draw-lines</em> lines snd chn context cr
</pre>

<p>This draws lines following the (x y) pairs in the vector 'lines' in the specified context.
make-bezier-1 in <a href="sndscm.html#musglyphs">musglyphs.scm</a> can be used to draw Bezier curves.
</p>
<div class="spacer"></div>


<!-- draw-string -->
<pre class="indented">
<em class=def id="drawstring">draw-string</em> text x0 y0 snd chn context cr
</pre>

<p>This draws a string ('text') in the current font and foreground color starting at ('x0 y0') in the specified context.
The next procedures use the channel-property list to maintain a list
of sample-oriented comments, displaying a given comment if its associated sample is
currently in the time-domain graph:
</p>

<pre class="indented">
(define* (add-comment sample comment snd1 chn1)
  (let* ((snd (or snd1 (<a class=quiet href="#selectedsound">selected-sound</a>)))
	 (chn (or chn1 (<a class=quiet href="#selectedchannel">selected-channel</a>)))
	 (old-comments (or (<a class=quiet href="#channelproperty">channel-property</a> 'comments snd chn) ())))
    (set! (<a class=quiet href="#channelproperty">channel-property</a> 'comments snd chn)
	  (cons (list sample comment)
		old-comments))))
	  
(define (show-comments snd chn) ; works only in motif currently
  (let ((comments (or (<a class=quiet href="#channelproperty">channel-property</a> 'comments snd chn) ())))
    (for-each
     (lambda (<a class=quiet href="#comment">comment</a>)
       (let* ((samp (car comment))
	      (text (cadr comment))
	      (text-width (* 6 (string-length text)))
	      (ls (<a class=quiet href="#leftsample">left-sample</a> snd chn))
	      (rs (<a class=quiet href="#rightsample">right-sample</a> snd chn)))
	 (if (and (&lt; ls samp)
		  (&gt; rs samp))
	     (let ((xpos (<a class=quiet href="#xtoposition">x-&gt;position</a> (/ samp (<a class=quiet href="#srate">srate</a>))))
		   (ypos (<a class=quiet href="#ytoposition">y-&gt;position</a> (<a class=quiet href="#sample">sample</a> samp))))
	       (<a class=quiet href="#drawline">draw-line</a> xpos 20 xpos (- ypos 4) snd chn time-graph #f)
	       (<em class=red>draw-string</em> text (- xpos (/ text-width 2)) 18 snd chn time-graph #f)))))
     comments)))

(hook-push <a class=quiet href="#aftergraphhook">after-graph-hook</a>
  (lambda (hook) 
    (show-comments (hook 'snd) (hook 'chn))))
</pre>
<div class="spacer"></div>


<!-- fill-rectangle -->
<pre class="indented">
<em class=def id="fillrectangle">fill-rectangle</em> x0 y0 width height snd chn context erase cr
</pre>

<p>This draws a filled rectangle in the current foreground color from ('x0 y0') of size ('width height').
If 'erase' is #t, this function erases the rectangular area.
See draw.scm and snd-motif.scm.
</p>
<div class="spacer"></div>


<!-- fill-polygon -->
<pre class="indented">
<em class=def id="fillpolygon">fill-polygon</em> points snd chn context cr
</pre>

<p>This draws a filled polygon whose vertices are in the vector 'points'.
</p>

<pre class="indented">
(define (-&gt; x0 y0 size snd chn cr)
  ;; draw an arrow pointing (from the left) at the point (x0 y0)
  (let ((points (make-vector 8)))
    (define (point i x y)
      (set! (points (* i 2)) x)
      (set! (points (+ (* i 2) 1)) y))
    (define (arrow-head x y)
      (point 0 x y)
      (point 1 (- x (* 2 size)) (- y size))
      (point 2 (- x (* 2 size)) (+ y size))
      (point 3 x y)
      (<em class=red>fill-polygon</em> points snd chn time-graph cr))
    (arrow-head x0 y0)
    (<a class=quiet href="#fillrectangle">fill-rectangle</a> (- x0 (* 4 size)) 
		    (floor (- y0 (* .4 size)))
		    (* 2 size)
		    (floor (* .8 size))
                    snd chn time-graph #f cr)))	
</pre>

<p>musglyphs.scm has some elaborate examples that use fill-polygon to draw music notation symbols.
</p>
<div class="spacer"></div>


<!-- foreground-color -->
<pre class="indented">
<em class=def id="foregroundcolor">foreground-color</em> snd chn context
</pre>

<p>This is the current foreground color.
The following gives us a green cursor:
</p>

<pre class="indented">
  (set! (foreground-color 0 0 <a class=quiet href="#cursorcontext">cursor-context</a>) (<a class=quiet href="#makecolor">make-color</a> 1 0 1))
</pre>
<div class="spacer"></div>


<!-- glSpectrogram -->
<pre class="indented">
<em class=def id="glspectrogram">glSpectrogram</em> data gl-list cutoff use-dB min-dB scale br bg bb
</pre>

<p>glSpectrogram takes spectrogram data and passes it to openGL.  
</p>
<div class="spacer"></div>


<!-- graph-data -->
<pre class="indented">
<em class=def id="graphdata">graph-data</em> data snd chn context low high graphics-style cr
</pre>

<p>graph-data displays 'data' in the time domain graph of the sound's channel
'chn' using the graphics context 'context' (normally copy-context), placing the
data in the recipient's graph between points 'low' and 'high'
in the drawing mode 'graphics-style'.
With this function and make-graph-data, we can overlay sounds,
overlay different versions of the same sound, place a portion of a
sound over another at an arbitrary point, and so on (see draw.scm).
</p>

<img class="indented" src="pix/redsamps.png" alt="red samples">
<div class="spacer"></div>


<!-- integer->colormap -->
<pre class="indented">
<em class=def id="integertocolormap">integer-&gt;colormap</em> i
</pre>

<p>This function returns the colormap corresponding to a given integer. 
</p>
<div class="spacer"></div>


<!--  make-color -->
<pre class="indented">
<em class=def id="makecolor">make-color</em> red green blue (alpha 1.0)
</pre>

<p>make-color returns a color object using the rgb values 'red', 'green', and 'blue'.  Each argument
is a float between 0.0 (none of that color) and 1.0 (full value for that color).  So,
</p>

<pre class="indented">
(make-color 1 0 0)
</pre>

<p>returns a red color object.
Two colors are equal (i.e. equal? returns #t) if their rgb values are the same.
</p>
<div class="spacer"></div>


<!-- make-graph-data -->
<pre class="indented">
<em class=def id="makegraphdata">make-graph-data</em> snd chn edit-position low-sample high-sample
</pre>

<p id="displaydb">Use make-graph-data to get the currently displayed data (i.e. the waveform displayed
in the graph, which can be based on an overall peak envelope rather than the
individual samples).
It returns either a float-vector (if the graph has one trace), or a
list of two float-vectors (the two sides of the peak envelope graph).
'edit-position' defaults to the current edit history position,
'low-sample' defaults to the current window left sample, and
'high-sample' defaults to the current rightmost sample.
The result can be used in the lisp graph:
</p>

<pre class="indented">
(define display-db
  (lambda (snd chn)
    (let ((datal (<em class=red>make-graph-data</em> snd chn)))
      (if datal
          (let* ((data (if (float-vector? datal) datal (cadr datal)))
                 (len (length data))
                 (sr (<a class=quiet href="#srate">srate</a> snd)))
            (define (dB val)
	      (if (&lt; val .001)
	          -60.0
	          (* 20.0 (log10 val))))
            (do ((i 0 (+ i 1)))
	        ((= i len))
	      (set! (data i) (+ 60.0 (dB (abs (data i))))))
              (<a class=quiet href="#graph">graph</a> data "dB" 
	            (/ (<a class=quiet href="#leftsample">left-sample</a> snd chn) sr) (/ (<a class=quiet href="#rightsample">right-sample</a> snd chn) sr)  
	            0.0 60.0
	            snd chn))))))

(hook-push <a class=quiet href="#lispgraphhook">lisp-graph-hook</a> 
  (lambda (hook)
    (display-db (hook 'snd) (hook 'chn))))
</pre>

<p>Here we are taking whatever is displayed in the time domain, and
presenting the same thing in dB in the lisp graph.  <a href="sndscm.html#displayenergy">display-energy</a>
in draw.scm is another example.  But the real power of this function
comes from its use with graph-data.  
The latter takes its argument (either a float-vector or a list of two
float-vectors), and displays it in any channel's time domain graph using its current graph-style.
</p>
<div class="spacer"></div>


<!-- mark-context -->
<pre class="indented">
<em class=def id="markcontext">mark-context</em>
</pre>

<p>This is the graphics context used to draw a mark (XOR mode). (It is an integer, not a function).
</p>
<div class="spacer"></div>


<!-- selection-context -->
<pre class="indented">
<em class=def id="selectioncontext">selection-context</em>
</pre>

<p>This is the graphics context for XOR drawing in the selection color.  (An integer, not a function).
</p>
<div class="spacer"></div>


<!-- snd-color -->
<pre class="indented">
<em class=def id="sndcolor">snd-color</em> choice
</pre>

<p>snd-color returns a Snd built-in color (as a Pixel); it simplifies 
code that wants to follow whatever the current Snd color choices are.  The choices are:
</p>

<pre class="indented">
0: white                   12: listener-color                 
1: black                   13: listener-text-color            25: sash-color
2: red                     14: basic-color                    
3: yellow                  15: selection-color                
4: green                   16: zoom-color                     
5: light-blue              17: position-color                 
6: lighter-blue            18: highlight-color                
7: data-color              19: enved-waveform-color           31: grid-color
8: selected-data-color     20: cursor-color                   32: selected-grid-color
9: mark-color              21: text-focus-color               33: axis-color
10: graph-color            22: filter-control-waveform-color
11: selected-graph-color   23: mix-color
</pre>
<div class="spacer"></div>


<!-- snd-font -->
<pre class="indented">
<em class=def id="sndfont">snd-font</em> choice
</pre>

<p>snd-font returns a Snd built-in font (as a raw pointer, suitable for <a href="#currentfont">current-font</a> but not much else); it simplifies 
code that wants to follow whatever the current Snd font choices are, but is really aimed at code that wants to use
just built-in functions like <a href="#currentfont">current-font</a>, and not rely 
on the <a href="grfsnd.html#sndwithmotif">xm</a> module.
The choices are:
</p>

<pre class="indented">
0: <a class=quiet href="#peaksfont">peaks-font</a>
1: <a class=quiet href="#boldpeaksfont">bold-peaks-font</a>
2: <a class=quiet href="#tinyfont">tiny-font</a>
3: <a class=quiet href="#axislabelfont">axis-label-font</a>
4: <a class=quiet href="#axisnumbersfont">axis-numbers-font</a>
5: <a class=quiet href="#listenerfont">listener-font</a>
</pre>

<p>See <a href="sndscm.html#displaybarkfft">display-bark-fft</a> in dsp.scm for an example.
</p>
<div class="spacer"></div>


<!-- snd-gcs -->
<pre class="indented">
<em class=def id="sndgcs">snd-gcs</em>
</pre>

<p>snd-gcs returns a list of Snd's graphics contexts:
</p>

<pre class="indented">
0: bg=graph-color, fg=data-color
1: bg=selected-graph-color, fg=selected-data-color
2: bg=graph-color, fg=data-color, fg changes for superimposed graphs

3: bg=graph-color, fg=cursor-color, XOR (for cursor)
4: bg=selected-graph-color, fg=cursor-color, XOR (for cursor in selection)

5: bg=graph-color, fg=selection-color, XOR (for selection highlighting)
6: bg=selected-graph-color, fg=selection-color, XOR (selection highlighting)

7: bg=data-color, fg=graph-color (to erase data)
8: bg=selected-data-color, fg=selected-graph-color (erase data in selected channel)

9: bg=graph-color, fg=mark-color, XOR (for marks)
0: bg=selected-graph-color, fg=mark-color, XOR (marks in selected channel)

1: bg=graph-color, fg=mix-color
2: bg=selected-graph-color, fg=mix-color

3: bg=basic-color, fg=black
4: bg=basic-color, fg=filter-waveform-color
</pre>

<p>These graphics-contexts make it easier to fit in with whatever color scheme is currently in use.  For example,
in to make sure the font color reflects whether we're in the selected channel:
</p>

<pre class="indented">
(XSetFont dpy
  ((if (= chn (<a class=quiet href="#selectedsound">selected-channel</a> snd)) cadr car) (snd-gcs))
  (.fid fs))
</pre>
<div class="spacer"></div>


<!-- with-gl -->
<pre class="indented">
<em class=def id="withgl">with-gl</em>
</pre>

<p>If with-gl is #t and GL is loaded, use GL where possible (the default is #t if HAVE_GL).
You can find out at run-time whether GL is loaded via (provided? 'gl).
</p>
<div class="spacer"></div>


<div class="related">
related documentation: &nbsp;
<a href="snd.html">snd.html &nbsp;</a>
<a href="grfsnd.html">grfsnd.html &nbsp;</a>
<a href="sndscm.html">sndscm.html &nbsp;</a>
<a href="sndclm.html">sndclm.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>