diff options
| author | IOhannes m zmölnig <zmoelnig@umlautQ.umlaeute.mur.at> | 2016-01-25 11:25:59 +0100 |
|---|---|---|
| committer | IOhannes m zmölnig <zmoelnig@umlautQ.umlaeute.mur.at> | 2016-01-25 11:25:59 +0100 |
| commit | 110d59c341b8c50c04f30d90e85e9b8f6f329a0e (patch) | |
| tree | 174afbe2ded41ae03923b93a0c4e6975e3163ad5 /extsnd.html | |
| parent | e5328e59987b90c4e98959510b810510e384650d (diff) | |
Imported Upstream version 16.1
Diffstat (limited to 'extsnd.html')
| -rw-r--r-- | extsnd.html | 17054 |
1 files changed, 8894 insertions, 8160 deletions
diff --git a/extsnd.html b/extsnd.html index 57fe4f5..2d46494 100644 --- a/extsnd.html +++ b/extsnd.html @@ -1,59 +1,177 @@ -<html> +<!DOCTYPE html> + +<html lang="en"> <head> +<meta http-equiv="Content-Type" content="text/html;charset=utf-8" > <title>Snd Customization and Extension</title> <style type="text/css"> -<!-- EM.red {color:red; font-style: normal} EM.error {color:chocolate; font-style: normal} - EM.narg {color:sienna; font-style: normal} - EM.typing {color:maroon; font-style: normal} - EM.listener {color:darkblue; 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} - A.def {font-weight: bold; font-style: normal; text-decoration:none; text-color:black; padding-right: 0.2cm} ---> + + EM.def {font-weight: bold; font-style: normal; text-decoration:none; text-color:black; 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 bgcolor=white> +<body class="body"> -<script language=JavaScript type="text/javascript" src="wz_tooltip.js"></script> -<script language=JavaScript type="text/javascript" src="wz_data.js"></script> +<div class="topheader" id="extsndcontents">Snd Customization and Extension</div> -<!-- I'm using A NAME (i.e caps) where the entity should be ignored by the indexer (make-index.scm) --> +<div class="related"> +related documentation: +<a href="snd.html">snd.html </a> +<a href="grfsnd.html">grfsnd.html </a> +<a href="sndscm.html">sndscm.html </a> +<a href="sndclm.html">sndclm.html </a> +<a href="fm.html">fm.html </a> +<a href="sndlib.html">sndlib.html </a> +<a href="s7.html">s7.html </a> +<a href="index.html">index.html</a> +</div> -<A NAME="extsndcontents"></a> -<table border=0 bordercolor="lightgreen" width=100% cellpadding=2 cellspacing=0><tr><td bgcolor="lightgreen"> -<table width="100%" border=0><tr> -<td bgcolor="beige" align="center" valign="middle"><h1>Snd Customization and Extension</h1></td> -</tr></table> -</td></tr></table> -<br> -<center> -<table bgcolor="aliceblue" border=0 cellspacing=8><tr> -<td><small>related documentation:</small></td> -<td><small><a href="snd.html" onmouseout="UnTip()" onmouseover="Tip(snd_html_tip)">snd.html</a></small></td> -<td><small><a href="grfsnd.html" onmouseout="UnTip()" onmouseover="Tip(grfsnd_html_tip)">grfsnd.html</a></small></td> -<td><small><a href="sndscm.html" onmouseout="UnTip()" onmouseover="Tip(sndscm_html_tip)">sndscm.html</a></small></td> -<td><small><a href="sndclm.html" onmouseout="UnTip()" onmouseover="Tip(sndclm_html_tip)">sndclm.html</a></small></td> -<td><small><a href="fm.html" onmouseout="UnTip()" onmouseover="Tip(fm_html_tip)">fm.html</a></small></td> -<td><small><a href="sndlib.html" onmouseout="UnTip()" onmouseover="Tip(sndlib_html_tip)">sndlib.html</a></small></td> -<td><small><a href="libxm.html" onmouseout="UnTip()" onmouseover="Tip(libxm_html_tips extension language')">libxm.html</a></small></td> -<td><small><a href="s7.html" onmouseout="UnTip()" onmouseover="Tip(s7_html_tip)">s7.html</a></small></td> -<td><small><a href="index.html" onmouseout="UnTip()" onmouseover="Tip(index_html_tip)">index.html</a></small></td> -</tr></table> -</center> - - -<table border=0 cellpadding=10 vspace=10 hspace=20> -<tr><th>this file:</th><th>grfsnd.html:</th></tr> +<table> +<tr><th>this file:</th><th>grfsnd.html:</th><th></th></tr> <tr><td> <ul> <li><a href="#lisplistener">Introduction</a> @@ -63,25 +181,24 @@ <ul> <li><a href="#sndglobalvars">Global variables</a> <li><a href="#sndgenericfuncs">Generic functions</a> - <li><a href="#sndhooks" onmouseout="UnTip()" onmouseover="Tip('callbacks')">Hooks</a> + <li><a href="#sndhooks">Hooks</a> </ul> <li><a href="#sndobjects">Snd's objects</a> <ul> - <li><a href="#samplers" onmouseout="UnTip()" onmouseover="Tip('sound data iterators', WIDTH, 200)">Samplers</a> - <li><a href="#Vcts" onmouseout="UnTip()" onmouseover="Tip('real arrays', WIDTH, 100)">Vcts</a> - <li><a href="#sndsounddata" onmouseout="UnTip()" onmouseover="Tip('arrays of vcts for multichannel data')">Sound-data</a> - <li><a href="#extsndlib" onmouseout="UnTip()" onmouseover="Tip('the underlying library that handles sound data and files')">Sndlib</a> - <li><a href="#sndmarks" onmouseout="UnTip()" onmouseover="Tip('location markers in sound data')">Marks</a> - <li><a href="#sndmixes" onmouseout="UnTip()" onmouseover="Tip('mixed sounds and groups of mixed sounds')">Mixes</a> - <li><a href="#sndregions" onmouseout="UnTip()" onmouseover="Tip('selected or saved portions of sound data')">Regions and Selections</a> - <li><a href="#sndsounds" onmouseout="UnTip()" onmouseover="Tip('editing functions, per-channel display decisions, etc')">Sounds and channels</a> + <li><a href="#samplers">Samplers</a> + <li><a href="#Vcts">Vcts, Float-vectors</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" onmouseout="UnTip()" onmouseover="Tip('a set of common sound effects below the main graph')">the control panel</a> - <li><a href="#editlists" onmouseout="UnTip()" onmouseover="Tip('current edit sequence', WIDTH, 200)">edit lists</a> + <li><a href="#customcontrols">the control panel</a> + <li><a href="#editlists">edit lists</a> </ul> - <li><a href="#sndtransforms" onmouseout="UnTip()" onmouseover="Tip('Fourier transform, wavelets, autocorelation, etc')">Transforms</a> - <li><a href="#snddialogs" onmouseout="UnTip()" onmouseover="Tip('customizing the built-in dialogs, etc')">Dialogs and Other Widgets</a> - <li><a href="#sndmisc" onmouseout="UnTip()" onmouseover="Tip('bind-key, exit, etc')">Miscellaneous functions</a> + <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> @@ -89,7 +206,7 @@ <ul> <li><a href="#colors">Colors</a> <li><a href="#fonts">Fonts</a> - <li><a href="#graphics" onmouseout="UnTip()" onmouseover="Tip('write your own sound display functions or customize Snd\'s')">Graphics</a> + <li><a href="#graphics">Graphics</a> </ul> </ul> </ul> @@ -98,43 +215,41 @@ <ul> <li><a href="grfsnd.html#startup">Snd Startup</a> <ul> - <li><a href="grfsnd.html#sndswitches" onmouseout="UnTip()" onmouseover="Tip('startup switches such as -l and -p')">Snd invocation flags</a> - <li><a href="grfsnd.html#sndinitfile" onmouseout="UnTip()" onmouseover="Tip('~/.snd, ~/.snd_s7, ~/.snd_prefs_s7, etc')">The initialization file</a> - <li><a href="grfsnd.html#sndconfigurationswitches" onmouseout="UnTip()" onmouseover="Tip('this refers to the configure script that prepares a makefile to build Snd from its sources')">Configuration choices</a> - <li><a href="grfsnd.html#sndenvvars" onmouseout="UnTip()" onmouseover="Tip('mostly related to audio hardware choices')">Environment variables</a> + <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" onmouseout="UnTip()" onmouseover="Tip('Use Emacs as the listener')">Snd as an Emacs subjob</a> - <li><a href="grfsnd.html#dynamic" onmouseout="UnTip()" onmouseover="Tip('Load your own C code into Snd')">Dynamically loaded modules</a> - <li><a href="grfsnd.html#sndaswidget" onmouseout="UnTip()" onmouseover="Tip('Embed Snd in some other program')">Snd as a Widget</a> - <li><a href="grfsnd.html#sndwithclm" onmouseout="UnTip()" onmouseover="Tip('CLM is built into Snd')">Snd and CLM</a> - <li><a href="grfsnd.html#sndwithcm" onmouseout="UnTip()" onmouseover="Tip('CM is Rick Taube\'s composition environment')">Snd and Common Music</a> - <li><a href="grfsnd.html#sndwithmotif" onmouseout="UnTip()" onmouseover="Tip('Motif extensions from xm.c')">Snd and Motif</a> - <li><a href="grfsnd.html#sndwithgtk" onmouseout="UnTip()" onmouseover="Tip('Gtk extensions from xg.c')">Snd and Gtk</a> + <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#sndwithgtk">Snd and Gtk</a> <li><a href="grfsnd.html#sndwithnogui">Snd with no GUI</a> - <li><a href="grfsnd.html#sndandruby" onmouseout="UnTip()" onmouseover="Tip('Ruby is a scripting/extension language somewhat like Python')">Snd with Ruby</a> - <li><a href="grfsnd.html#sndandforth" onmouseout="UnTip()" onmouseover="Tip('Forth is a postfix extension language')">Snd with Forth</a> - <li><a href="grfsnd.html#sndands7" onmouseout="UnTip()" onmouseover="Tip('s7 is yet-another Scheme extension language')">Snd with s7</a> - <li><a href="grfsnd.html#sndandladspa" onmouseout="UnTip()" onmouseover="Tip('This is a Linux-based sound-effects plugin system')">Snd and LADSPA plugins</a> - <li><a href="grfsnd.html#sndandalsa" onmouseout="UnTip()" onmouseover="Tip('This is the no-longer-very-new Linux audio library')">Snd and ALSA</a> - <li><a href="grfsnd.html#sndandjack" onmouseout="UnTip()" onmouseover="Tip('This is the Jack audio library')">Snd and Jack</a> - <li><a href="grfsnd.html#sndandgl" onmouseout="UnTip()" onmouseover="Tip('OpenGL (Mesa) extensions via gl.c')">Snd and OpenGL</a> - <li><a href="grfsnd.html#sndandgsl" onmouseout="UnTip()" onmouseover="Tip('include some special functions from GSL')">Snd and GSL</a> - <li><a href="grfsnd.html#sndandgmp" onmouseout="UnTip()" onmouseover="Tip('build s7 with gmp, mpfr, mpc')">multiprecision arithmetic</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><td> +<img src="pix/rr2.png" alt="setting switches"> </td></tr></table> -<br><br> -<table border=0 bordercolor="lightgreen" width=100% cellpadding=1 cellspacing=0><tr><td bgcolor="lightgreen"> -<table width="100%" border=0><tr><td bgcolor="beige" align="center" valign="middle"><h2>Introduction</h2></td></tr></table> -</td></tr></table> -<A NAME="lisplistener"></a> + +<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 @@ -150,6 +265,7 @@ 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>. @@ -161,210 +277,129 @@ 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 ">". So, -say we've opened the listener (my typing is -in <em class=typing>this color</em> and Snd's responses -are in <em class=listener>this color</em>): +say we've opened the listener. </p> -<table border=0 cellspacing=10> -<tr><th bgcolor="#f2f4ff" align=left>Scheme</th><th></th><th bgcolor="beige" align=left>Ruby</th><th></th><th bgcolor="lightgreen" align=left>Forth</th></tr> - -<tr> -<td bgcolor="#fbfbff"><pre> -><em class=typing>(+ 1 2)</em> -<em class=listener>3</em> -</pre></td><td width=60></td> - -<td bgcolor="#FdFdf2"><pre> -><em class=typing>1+2</em> -<em class=listener>3</em> -</pre></td><td width=60></td> - -<td bgcolor="#EefdEe"><pre> -><em class=typing>1 2 +</em> -<em class=listener>3</em> -</pre></td> -</tr> -<!-- ------------ --> - -<tr> -<td bgcolor="#fbfbff" onmouseout="UnTip()" onmouseover="Tip('this opens oboe.snd; the "0" returned is the new sound\'s \'index\'')"><pre> -><em class=typing>(open-sound "oboe.snd")</em> -<em class=listener>#<sound 0></em> -</pre></td><td></td> - -<td bgcolor="#FdFdf2"><pre> -><em class=typing>open_sound("oboe.snd")</em> -<em class=listener>0</em> -</pre></td><td></td> - -<td bgcolor="#EefdEe"><pre> -><em class=typing>"oboe.snd" open-sound</em> -<em class=listener>0</em> -</pre></td> -</tr> -<!-- ------------ --> - -<tr> -<td bgcolor="#fbfbff" onmouseout="UnTip()" onmouseover="Tip('#t = true, #f = false in Scheme and Forth')"><pre> -><em class=typing>(auto-resize)</em> -<em class=listener>#t</em> -</pre></td><td></td> - -<td bgcolor="#FdFdf2"><pre> -><em class=typing>auto_resize</em> -<em class=listener>true</em> -</pre></td><td></td> - -<td bgcolor="#EefdEe"><pre> -><em class=typing>auto-resize</em> -<em class=listener>#t</em> -</pre></td> -</tr> -<!-- ------------ --> - -<tr> -<td bgcolor="#fbfbff"><pre> -><em class=typing>(set! (auto-resize) #f)</em> -<em class=listener>#f</em> -</pre></td><td></td> - -<td bgcolor="#FdFdf2"><pre> -><em class=typing>set_auto_resize false</em> -<em class=listener>false</em> -</pre></td><td></td> - -<td bgcolor="#EefdEe"><pre> -><em class=typing>#f set-auto-resize</em> -<em class=listener>#f</em> -</pre></td> -</tr> -<!-- ------------ --> - -<tr> -<td bgcolor="#fbfbff"><pre> -><em class=typing>(set! (x-bounds) '(0.0 1.0))</em> -<em class=listener>(0.0 1.0)</em> -</pre></td><td></td> - -<td bgcolor="#FdFdf2" onmouseout="UnTip()" onmouseover="Tip('Ruby runs array elements together in printout: "0.01.0" should be "0.0 1.0"')"><pre> -><em class=typing>set_x_bounds([0.0, 1.0])</em> -<em class=listener>0.01.0</em> -</pre></td><td></td> - -<td bgcolor="#EefdEe"><pre> -><em class=typing>'( 0.0 1.0 ) set-x-bounds</em> -<em class=listener>'( 0.0 1.0 )</em> -</pre></td> -</tr> -<!-- ------------ --> - -<tr> -<td bgcolor="#fbfbff" onmouseout="UnTip()" onmouseover="Tip('this is Scheme\'s way of saying the previous evaluation returned no newsworthy result.')"><pre> -><em class=typing>(load "bird.scm")</em> -<em class=listener>make-birds</em> -</pre></td><td></td> - -<td bgcolor="#FdFdf2"><pre> -><em class=typing>load "bird.rb"</em> -<em class=listener>true</em> -</pre></td><td></td> - -<td bgcolor="#EefdEe"><pre> -><em class=typing>"bird.fs" file-eval</em> -<em class=listener>0</em> -</pre></td> -</tr> -<!-- ------------ --> - -<tr> -<td bgcolor="#fbfbff"><pre> -><em class=typing>(map-channel (lambda (y) (* y 2)))</em> -<em class=listener>0</em> -</pre></td><td></td> - -<td bgcolor="#FdFdf2"><pre> -><em class=typing>map_channel(lambda do |y| y * 2 end)</em> -<em class=listener>-0.0015869140625</em> -</pre></td><td></td> - -<td bgcolor="#EefdEe"><pre> -><em class=typing>lambda: <{ y }> y 2.0 f* ; map-channel</em> -<em class=listener>-0.00158691</em> -</pre></td> -</tr> -<!-- ------------ --> - -<tr> -<td bgcolor="#fbfbff"><pre> -><em class=typing>(define (plus a b) (+ a b))</em> -<em class=listener>plus</em> -</pre></td><td></td> - -<td bgcolor="#FdFdf2"><pre> -><em class=typing>def plus(a, b) a+b end</em> - -</pre></td><td></td> - -<td bgcolor="#EefdEe"><pre> -><em class=typing>: plus ( a b -- sum ) { a b } a b + ;</em> -<em class=listener>nil</em> -</pre></td> -</tr> -<!-- ------------ --> - -<tr> -<td bgcolor="#fbfbff"><pre> -><em class=typing>(set! (basic-color) (make-color 1 0 0))</em> -<em class=listener>(Pixel 16711680)</em> -</pre></td><td></td> - -<td bgcolor="#FdFdf2"><pre> -><em class=typing>set_basic_color make_color(1, 0, 0)</em> -<em class=listener>[:Pixel, 16711680]</em> -</pre></td><td></td> - -<td bgcolor="#EefdEe"><pre> -><em class=typing>1 0 0 make-color set-basic-color</em> -<em class=listener>#<XmRaw: Pixel 0x9d3b430></em> -</pre></td> -</tr> -<!-- ------------ --> - +<table> +<tr><th>Scheme</th><th>Ruby</th><th>Forth</th></tr> + +<tr><td><div class="scheme1"><pre> +> (+ 1 2) +3 +</pre></div></td><td><div class="ruby1"><pre> +>1+2 +3 +</pre></div></td><td><div class="forth1"><pre> +>1 2 + +3 +</pre></div></td></tr> + +<tr><td><div class="scheme1"><pre> +> (open-sound "oboe.snd") +#<sound 0> +</pre></div></td><td><div class="ruby1"><pre> +>open_sound("oboe.snd") +0 +</pre></div></td><td><div class="forth1"><pre> +>"oboe.snd" open-sound +0 +</pre></div></td></tr> + +<tr><td><div class="scheme1"><pre> +> (auto-resize) +#t +</pre></div></td><td><div class="ruby1"><pre> +>auto_resize +true +</pre></div></td><td><div class="forth1"><pre> +>auto-resize +#t +</pre></div></td></tr> + + + +<tr><td><div class="scheme1"><pre> +> (set! (auto-resize) #f) +#f +</pre></div></td><td><div class="ruby1"><pre> +>set_auto_resize false +false +</pre></div></td><td><div class="forth1"><pre> +>#f set-auto-resize +#f +</pre></div></td></tr> + +<tr><td><div class="scheme1"><pre> +> (set! (x-bounds) '(0.0 1.0)) +(0.0 1.0) +</pre></div></td><td><div class="ruby1"><pre> +>set_x_bounds([0.0, 1.0]) +0.01.0 +</pre></div></td><td><div class="forth1"><pre> +>'( 0.0 1.0 ) set-x-bounds +'( 0.0 1.0 ) +</pre></div></td></tr> + +<tr><td><div class="scheme1"><pre> +> (load "bird.scm") +make-birds +</pre></div></td><td><div class="ruby1"><pre> +>load "bird.rb" +true +</pre></div></td><td><div class="forth1"><pre> +>"bird.fs" file-eval +0 +</pre></div></td></tr> + +<tr><td><div class="scheme1"><pre> +> (map-channel (lambda (y) (* y 2))) +0 +</pre></div></td><td><div class="ruby1"><pre> +>map_channel(lambda do |y| y * 2 end) +-0.0015869140625 +</pre></div></td><td><div class="forth1"><pre> +>lambda: <{ y }> y 2.0 f* ; map-channel +-0.00158691 +</pre></div></td></tr> + +<tr><td><div class="scheme1"><pre> +> (define (plus a b) (+ a b)) +plus +</pre></div></td><td><div class="ruby1"><pre> +>def plus(a, b) a+b end + +</pre></div></td><td><div class="forth1"><pre> +>: plus ( a b -- sum ) { a b } a b + ; +nil +</pre></div></td></tr> + +<tr><td><div class="scheme1"><pre> +> (set! (basic-color) (make-color 1 0 0)) +(Pixel 16711680) +</pre></div></td><td><div class="ruby1"><pre> +>set_basic_color make_color(1, 0, 0) +[:Pixel, 16711680] +</pre></div></td><td><div class="forth1"><pre> +>1 0 0 make-color set-basic-color +#<XmRaw: Pixel 0x9d3b430> +</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> -<blockquote> -<p><small>If the listener is active, and some sound -is selected, any characters typed while in the sound -graph which it can't handle are passed to the -listener. -If the listener appears to be hung, try C-g; normally -in this situation, -it's actually waiting for a close paren; if you put the -cursor just past the close paren you're interested in -and type return, -Snd will flash the unbalanced open paren (if any) briefly. -In any case, whenever the cursor is just past a close paren, -the matching open paren is underlined. -</small></p> -</blockquote> -<br> -<table border=0 bordercolor="lightgreen" width=100% cellpadding=1 cellspacing=0><tr><td bgcolor="lightgreen"> -<table width="100%" border=0><tr><td bgcolor="beige" align="center" valign="middle"><h2><A NAME="etc">Snd Programming</a></h2></td></tr></table> -</td></tr></table> +<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, vcts (an optimization -of vectors), and regions; the currently active region is +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 @@ -377,196 +412,185 @@ and <a href="sndscm.html#sndtestdoc">snd-test.scm</a>. Extensions to Snd can be found in: </p> - -<table border=8 bordercolor="lightsteelblue" cellpadding=6 hspace=20><tr><td> -<table border=0 cellspacing=0 cellpadding=2> -<tr><th colspan=2 bgcolor="beige">Contents</th></tr> - -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#analogfilterdoc">analog-filter</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(analog_filter_doc_tip)">standard IIR filters</td></tr> +<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 onmouseout="UnTip()" onmouseover="Tip(animals_doc_tip)">a bunch of animals</td></tr> + <td>a bunch of animals</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#autosavedoc">autosave</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(autosave_doc_tip)">auto-save (edit backup) support</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 onmouseout="UnTip()" onmouseover="Tip(bess_doc_tip)">FM demo</td></tr> + <td>FM demo</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#binaryiodoc">binary-io</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(binary_io_doc_tip)">binary files</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 onmouseout="UnTip()" onmouseover="Tip(bird_doc_tip)">North-American birds</td></tr> + <td>North-American birds</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#cleandoc">clean</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(clean_doc_tip)">noise reduction</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 onmouseout="UnTip()" onmouseover="Tip(clm_ins_doc_tip)">various CLM instruments</td></tr> + <td>various CLM instruments</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#dlocsigdoc">dlocsig</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(dlocsig_doc_tip)">moving sounds (Michael Scholz)</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 onmouseout="UnTip()" onmouseover="Tip(draw_doc_tip)">graphics additions</td></tr> + <td>graphics additions</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#dspdoc">dsp</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(dsp_doc_tip)">various DSP-related procedures</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 onmouseout="UnTip()" onmouseover="Tip(env_doc_tip)">envelope functions</td></tr> + <td>envelope functions</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#enveddoc">enved</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(enved_doc_tip)">envelope editor</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 onmouseout="UnTip()" onmouseover="Tip(examp_doc_tip)">many examples</td></tr> + <td>many examples</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#extensionsdoc">extensions</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(extensions_doc_tip)">various generally useful Snd extensions</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 onmouseout="UnTip()" onmouseover="Tip(fade_doc_tip)">frequency-domain cross-fades</td></tr> - -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#framedoc">frame</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(frame_doc_tip)">frames, vcts, sound-data objects</td></tr> + <td>frequency-domain cross-fades</td></tr> <tr><td><a href="sndscm.html#freeverbdoc">freeverb</a></td> - <td onmouseout="UnTip()" onmouseover="Tip(freeverb_doc_tip)">a reverb</td></tr> + <td>a reverb</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndclm.html#othergenerators">generators</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(generators_doc_tip)">a bunch of generators</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 onmouseout="UnTip()" onmouseover="Tip(grani_doc_tip)">CLM's grani (Fernando Lopez-Lezcano and Mike Scholz)</td></tr> + <td>CLM's grani (Fernando Lopez-Lezcano and Mike Scholz)</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#heartdoc">heart</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(heart_doc_tip)">use Snd with non-sound (arbitrary range) data</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 onmouseout="UnTip()" onmouseover="Tip(hooks_doc_tip)">functions related to hooks</td></tr> + <td >functions related to hooks</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#indexdoc">index</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(index_doc_tip)">snd-help extension</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 onmouseout="UnTip()" onmouseover="Tip(inf_snd_doc_tip)">Emacs subjob support (Michael Scholz, Fernando Lopez-Lezcano)</td></tr> + <td>Emacs subjob support (Michael Scholz, Fernando Lopez-Lezcano)</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#jcrevdoc">jcrev</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(jcrev_doc_tip)">John Chowning's ancient reverb</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 onmouseout="UnTip()" onmouseover="Tip(maraca_doc_tip)">Perry Cook's maraca physical model</td></tr> + <td>Perry Cook's maraca physical model</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#marksdoc">marks</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(marks_doc_tip)">functions related to marks</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 onmouseout="UnTip()" onmouseover="Tip(maxf_doc_tip)">Max Mathews resonator</td></tr> + <td>Max Mathews resonator</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#menusdoc">menus</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(menus_doc_tip)">additional menus</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 onmouseout="UnTip()" onmouseover="Tip(mix_doc_tip)">functions related to mixes</td></tr> - -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#mixerdoc">mixer</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(mixer_doc_tip)">functions related to linear algebra</td></tr> + <td>functions related to mixes</td></tr> <tr><td><a href="sndscm.html#moogdoc">moog</a></td> - <td onmouseout="UnTip()" onmouseover="Tip(moog_doc_tip)">Moog filter</td></tr> + <td>Moog filter</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#musglyphs">musglyphs</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(musglyphs_doc_tip)">Music notation symbols (from CMN)</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 onmouseout="UnTip()" onmouseover="Tip(nb_doc_tip)">Popup File info etc</td></tr> + <td>Popup File info etc</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#noisedoc">noise</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(noise_doc_tip)">noise maker</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 onmouseout="UnTip()" onmouseover="Tip(numerics_doc_tip)">various numerical functions</td></tr> - -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#oscopedoc">oscope</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(oscope_doc_tip)">an oscilloscope/spectrum analysis dialog</td></tr> + <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 bgcolor="#f2f4ff"><a href="sndscm.html#pianodoc">piano</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(piano_doc_tip)">piano physical model</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 onmouseout="UnTip()" onmouseover="Tip(play_doc_tip)">play-related functions</td></tr> + <td>play-related functions</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#polydoc">poly</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(poly_doc_tip)">polynomial-related stuff</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 onmouseout="UnTip()" onmouseover="Tip(prc95_doc_tip)">Perry Cook's physical model examples</td></tr> + <td>Perry Cook's physical model examples</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#pvocdoc">pvoc</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(pvoc_doc_tip)">phase-vocoder</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 onmouseout="UnTip()" onmouseover="Tip(rgb_doc_tip)">color names</td></tr> - -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#rtiodoc">rtio</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(rtio_doc_tip)">real-time stuff</td></tr> + <td>color names</td></tr> <tr><td><a href="sndscm.html#rubberdoc">rubber</a></td> - <td onmouseout="UnTip()" onmouseover="Tip(rubber_doc_tip)">rubber-sound</td></tr> + <td>rubber-sound</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#selectiondoc">selection</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(selection_doc_tip)">functions acting on the current selection</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 onmouseout="UnTip()" onmouseover="Tip(singer_doc_tip)">Perry Cook's vocal-tract physical model</td></tr> + <td>Perry Cook's vocal-tract physical model</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#sndolddoc">snd9|10|11.scm</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(sndold_doc_tip)">Backwards compatibility</td></tr> +<tr><td><a href="sndscm.html#sndolddoc">snd13|14|15.scm</a></td> + <td>Backwards compatibility</td></tr> <tr><td><a href="sndscm.html#snddiffdoc">snddiff</a></td> - <td onmouseout="UnTip()" onmouseover="Tip(snddiff_doc_tip)">sound difference detection</td></tr> + <td>sound difference detection</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#sndgldoc">snd-gl</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(snd_gl_doc_tip)">OpenGL examples (gl.c)</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-gtk, snd-xm</a></td> - <td onmouseout="UnTip()" onmouseover="Tip(snd_motif_doc_tip)">Motif/Gtk module (xm.c, xg.c)</td></tr> + <td>Motif/Gtk module (xm.c, xg.c)</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#sndtestdoc">snd-test</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(snd_test_doc_tip)">Snd regression tests</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 onmouseout="UnTip()" onmouseover="Tip(sndwarp_doc_tip)">Bret Battey's sndwarp instrument</td></tr> + <td>Bret Battey's sndwarp instrument</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#spectrdoc">spectr</a></td> - <td bgcolor="#f2f4ff">instrument steady state spectra</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 bgcolor="#f2f4ff"><a href="sndscm.html#straddoc">strad</a></td> - <td bgcolor="#f2f4ff">string physical model (from CLM)</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#vdoc">v</a></td> <td>fm-violin</td></tr> -<tr><td bgcolor="#f2f4ff"><a href="sndscm.html#wsdoc">ws</a></td> - <td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip(ws_doc_tip)">with-sound</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 onmouseout="UnTip()" onmouseover="Tip(zip_doc_tip)">the zipper (the anti-cross-fader)</td></tr> - + <td>the zipper (the anti-cross-fader)</td></tr> +</tbody> </table> </td></tr></table> -<br><br> -<table width="80%" border=0><tr><td bgcolor="lightsteelblue" valign="middle"><h3><A NAME="behavior">Customizing Snd's behavior</a></h3></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 @@ -578,29 +602,30 @@ 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> -<table border=0 cellpadding=5 hspace=20> -<tr><td><pre> -(define <A NAME="unsavededitsp">(unsaved-edits? lst)</A> - (if (not (null? lst)) - (if (> (car (<a class=quiet href="#edits" onmouseout="UnTip()" onmouseover="Tip(extsnd_edits_tip)">edits</a> (car lst))) 0) - (begin - (<a class=quiet href="#reportinminibuffer" onmouseout="UnTip()" onmouseover="Tip(extsnd_reportinminibuffer_tip)">report-in-minibuffer</a> "there are unsaved edits") - #t) - (unsaved-edits? (cdr lst))) - #f)) +<pre class="indented"> +(define (unsaved-edits? lst) + (and (pair? lst) + (if (> (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 () (unsaved-edits? (<a class=quiet href="#sounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_sounds_tip)">sounds</a>)))) -</pre></td></tr></table> +(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 minibuffer, and refuses to +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> -<br> -<table width="60%" border=0><tr><td bgcolor="lightgreen" valign="middle"><h4><A NAME="sndglobalvars">Global variables</a></h4></td></tr></table> + + +<div class="header" id="sndglobalvars">Global variables</div> <p>The global variables handle various customizations that aren't callback-oriented. For example, @@ -610,204 +635,241 @@ up to Snd). Many people find this distracting — they would rather that th overall window stick to one size. The Snd variable associated with this is "auto-resize"; it can be accessed as: </p> -<pre> - Scheme: (auto-resize) +<pre class="indented"> + Scheme: *auto-resize* or (auto-resize) Ruby: auto_resize() Forth: auto-resize </pre> <p>and set via:</p> -<pre> - Scheme: (set! (auto-resize) #f) +<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> -The variables are presented as a special kind of function, rather than as bare variables, mainly -to ensure that Snd's response to the assignment is immediate. -The statement <code>(set! (auto-resize) #f)</code> can be placed in your ~/.snd initialization file +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 variables affecting Snd's overall behavior are: +<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> -<!-- -------------------------------- GLOBAL VARIABLE TABLE -------------------------------- --> - -<table border=0 cellspacing=4 cellpadding=6> - -<tr><td width=30></td><td width=220></td><td></td></tr> +<div class="spacer"></div> <!-- ask-about-unsaved-edits --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="askaboutunsavededits">ask-about-unsaved-edits</a></code></td> -<td bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip('in this table, the default value of the given variable is listed after the variable name,<br>so ask-about-unsaved-edits defaults to false')"><code>#f</code></td></tr><tr><td></td><td colspan=2> -If ask-about-unsaved-edits is #t, Snd worries about unsaved edits when a sound is about to be closed. +<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> -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- ask-before-overwrite --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="askbeforeoverwrite">ask-before-overwrite</a></code></td> -<td bgcolor="#f2f4ff"><code>#f</code></td></tr><tr><td></td><td colspan=2> -ask-before-overwrite determines whether Snd asks before overwriting an existing file: -<code>(set! (ask-before-overwrite) #t)</code> -</td></tr><tr><td colspan=3 height=16></td></tr> - - -<!-- audio-input-device --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="audioinputdevice">audio-input-device</a></code></td> -<td bgcolor="#f2f4ff"><code>mus-audio-default</code></td></tr><tr><td></td><td colspan=2> -This is the recorder's input device: <code>(set! (audio-input-device) mus-audio-microphone)</code>. -</td></tr><tr><td colspan=3 height=16></td></tr> - +<pre class="indented"> +<em class=def id="askbeforeoverwrite">ask-before-overwrite</em> (default: #f) +</pre> -<!-- audio-output-device --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="audiooutputdevice">audio-output-device</a></code></td> -<td bgcolor="#f2f4ff"><code>mus-audio-default</code></td></tr><tr><td></td><td colspan=2> -This is the audio output device for the play button. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="autoresize">auto-resize</a></code></td> -<td bgcolor="#f2f4ff"><code>#t in Motif, #f in Gtk</code></td></tr><tr><td></td><td colspan=2> -auto-resize determines whether the Snd window should be resized +<pre class="indented"> +<em class=def id="autoresize">auto-resize</em> (default: #t in Motif, #f in Gtk) +</pre> + +<p>auto-resize determines whether the Snd window should be resized when a sound is opened or closed. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- auto-update --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="autoupdate">auto-update</a></code></td> -<td bgcolor="#f2f4ff"><code>#f</code></td></tr><tr><td></td><td colspan=2> -auto-update determines whether Snd should <a href="snd.html#updatefile">update</a> a file automatically +<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 bomb icon warns you that there are two conflicting versions of the sound. -</td></tr><tr><td colspan=3 height=16></td></tr> +a warning is posted that there are two conflicting versions of the sound. +</p> +<div class="spacer"></div> <!-- auto-update-interval --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="autoupdateinterval">auto-update-interval</a></code></td> -<td bgcolor="#f2f4ff"><code>60</code></td></tr><tr><td></td><td colspan=2> -This is the time (in seconds) between background checks for a changed file on +<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. -If the file alternation monitor is running (the default if you have libfam or libgamin), auto-update-interval is ignored -since in that case the check happens instantly. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- clipping --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="clipping">clipping</a></code></td> -<td bgcolor="#f2f4ff"><code>#f</code></td></tr><tr><td></td><td colspan=2> -If clipping is #t, output values are clipped to fit the current sndlib sample +<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! -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- cursor-location-offset --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="cursorlocationoffset">cursor-location-offset</a></code></td> -<td bgcolor="#f2f4ff"><code>0.05</code></td></tr><tr><td></td><td colspan=2> -cursor-location-offset is the offset in samples between Snd's notion of the location of the tracking cursor +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- cursor-update-interval --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="cursorupdateinterval">cursor-update-interval</a></code></td> -<td bgcolor="#f2f4ff"><code>0.05</code></td></tr><tr><td></td><td colspan=2> -This is the time in seconds between +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- dac-combines-channels --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="dacfolding">dac-combines-channels</a></code></td> -<td bgcolor="#f2f4ff"><code>#t</code></td></tr><tr><td></td><td colspan=2> -If dac-combines-channels is #t, and the current sound has more channels than are +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- dac-size --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="dacsize">dac-size</a></code></td> -<td bgcolor="#f2f4ff"><code>256</code></td></tr><tr><td></td><td colspan=2> -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 or -<a href="sndscm.html#playsound">play-sound</a> in play.scm. When you change the control panel settings during playback, the snappiness of the +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- default-output-chans --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="defaultoutputchans">default-output-chans</a></code></td> -<td bgcolor="#f2f4ff"><code>1</code></td></tr><tr><td></td><td colspan=2> -default-output-chans is the default number of channels when a new or temporary file is created, +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> -<!-- default-output-data-format --> -<tr><td colspan=2 bgcolor="#f2f4ff" onmouseout="UnTip()" onmouseover="Tip('I originally intended the names to be "header-format" and "data-type"<br>but somehow things got bollixed up and I didn\'t notice the confusion until years later')"><code><a class=def name="defaultoutputdataformat">default-output-data-format</a></code></td> -<td bgcolor="#f2f4ff"><code>mus-bfloat</code></td></tr><tr><td></td><td colspan=2> -default-output-data-format is the default data format when a new or temporary file is created, -or a save dialog is opened. (The default, <code>mus-bfloat</code>, 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 data formats are (b=big-endian, l=little, u=unsigned, short=16 bits, byte=8 bits, int = 32 bits): -<pre onmouseout="UnTip()" onmouseover="Tip('mus-bshort: big-endian (au-style) 16-bit ints, doubles are 64-bit floats,<br>alaw and mulaw are compression schemes, mus-b24int is a 3-byte (24-bit) format;<br>each header type has restrictions on the kinds of data it can accommodate.')"> - 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 +<!-- default-output-header-type --> +<pre class="indented"> +<em class=def id="defaultoutputheadertype">default-output-header-type</em> (default: mus-next) </pre> -There are also "unscaled" versions of the floating point types, and "normalized" versions of the integers. -</td></tr><tr><td colspan=3 height=16></td></tr> - -<!-- default-output-header-type --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="defaultoutputheadertype">default-output-header-type</a></code></td> -<td bgcolor="#f2f4ff"><code>mus-next</code></td></tr><tr><td></td><td colspan=2> -This is the default header type when a new file is created, -or a save dialog is opened. (The default, <code>mus-next</code>, stands for the NeXT/Sun sound file header). +<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: -<pre onmouseout="UnTip()" onmouseover="Tip('mus-riff is our name for Microsoft wave,<br>mus-rf64 is the EBU 64-bit RIFF-replacement header,<br>mus-nist refers to NIST-SPHERE files,<br>mus-next and mus-sun are the same,<br>mus-aiff is the obsolete predecessor to mus-aifc,<br>mus-bicsf and mus-ircam are extensions of mus-next headers,<br>mus-raw means "headerless",<br>mus-soundfont refers to Emu\'s extension of mus-riff files,<br>mus-voc refers to Creative Voice File,<br>mus-svx refers to 8SVX headers.<br>Many other headers are supported read-only.')"> +</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> -</td></tr><tr><td colspan=3 height=16></td></tr> + +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="defaultoutputsrate">default-output-srate</a></code></td> -<td bgcolor="#f2f4ff"><code>44100</code></td></tr><tr><td></td><td colspan=2> -This is the default sampling rate when a new or temporary file is created, +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- eps-bottom-margin --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="epsbottommargin">eps-bottom-margin</a></code></td> -<td bgcolor="#f2f4ff"><code>0.0</code></td></tr><tr><td></td><td colspan=2> -eps-bottom-margin is the bottom margin used in snd.eps, created by the File:Print dialog, or the <a href="#graphtops">graph->ps</a> function. +<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->ps</a> function. PostScript units are 1/72 of an inch (a "point" in printer jargon); an inch is 2.54 cm: +</p> -<table border=0 cellpadding=5 vspace=10 hspace=20><tr><td> - -<table border=0 cellpadding=5><tr><td><pre> +<table> +<tr> +<td> +<div class="scheme"> +<pre class="indented"> Scheme: (define (inches-to-ps inches) @@ -815,11 +877,12 @@ Scheme: (define (cm-to-ps cm) (* cm (/ 72.0 2.54))) -</pre></td></tr></table> - -</td><td> - -<table border=0 cellpadding=5><tr><td bgcolor="Beige"><pre> +</pre> +</div> +</td> +<td> +<div class="ruby"> +<pre class="indented"> Ruby: def inches_to_ps(inches) inches * 72 @@ -827,11 +890,12 @@ end def cm_to_ps(cm) cm * 72.0 / 2.54 end -</pre></td></tr></table> - -</td><td> - -<table border=0 cellpadding=5><tr><td bgcolor="LightGreen"><pre> +</pre> +</div> +</td> +<td> +<div class="forth"> +<pre class="indented"> Forth: : inches-to-ps { inches } inches 72 f* @@ -839,495 +903,603 @@ Forth: : cm-to-ps { cm } cm 2.54 f/ 72 f* ; -</pre></td></tr></table> +</pre> +</div> </td></tr></table> -In the resulting .eps file, you'll find a <code>concat</code> statement near the +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- eps-file --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="epsfile">eps-file</a></code></td> -<td bgcolor="#f2f4ff"><code>"snd.eps"</code></td></tr><tr><td></td><td colspan=2> -This is the default name of the Postscript file produced by the File:Print dialog, or the <a href="#graphtops">graph->ps</a> function. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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->ps</a> function. +</p> +<div class="spacer"></div> <!-- eps-left-margin --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="epsleftmargin">eps-left-margin</a></code></td> -<td bgcolor="#f2f4ff"><code>0.0</code></td></tr><tr><td></td><td colspan=2> -eps-left-margin is the left margin used in snd.eps, created by the File:Print dialog, or the <a href="#graphtops">graph->ps</a> function. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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->ps</a> function. +</p> +<div class="spacer"></div> <!-- eps-size --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="epssize">eps-size</a></code></td> -<td bgcolor="#f2f4ff"><code>1.0</code></td></tr><tr><td></td><td colspan=2> -eps-size is the scaler used to set the overall picture size in snd.eps, +<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->ps</a> function, -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- graph-cursor --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="graphcursor">graph-cursor</a></code></td> -<td bgcolor="#f2f4ff"><code>XC_crosshair (34)</code></td></tr><tr><td></td><td colspan=2> -graph-cursor is the kind of cursor displayed following the mouse in the data graph. +<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 or Gtk+: <code>(set! (graph-cursor) 22)</code>. The X/Motif cursors are declared in /usr/include/X11/cursorfont.h or some such file; gtk versions are in gdkcursor.h. Some useful choices are: +</p> + +<pre class="indented"> + Motif Gtk+ value + +XC_center_ptr GDK_CENTER_PTR 22 +XC_cross GDK_CROSS 30 +XC_crosshair GDK_CROSSHAIR 34 +XC_left_ptr GDK_LEFT_PTR 68 +XC_plus GDK_PLUS 90 +XC_right_ptr GDK_RIGHT_PTR 94 +XC_tcross GDK_TCROSS 130 +XC_xterm GDK_XTERM 152 +</pre> + +<div class="spacer"></div> -<table border=0 cellpadding=6 vspace=10><tr><td> -<table border=0 cellspacing=4 cellpadding=4> -<tr><th bgcolor="beige"><small>Motif</small></th><th bgcolor="beige"><small>Gtk+</small></th><th bgcolor="beige"><small>value</small></th></tr> -<tr><td><small>XC_arrow</small></td><td><small>GDK_ARROW</small></td><td><small>2</small></td></tr> -<tr><td><small>XC_center_ptr</small></td><td><small>GDK_CENTER_PTR</small></td><td><small>22</small></td></tr> -<tr><td><small>XC_cross</small></td><td><small>GDK_CROSS</small></td><td><small>30</small></td></tr> -<tr><td><small>XC_crosshair</small></td><td><small>GDK_CROSSHAIR</small></td><td><small>34</small></td></tr> -<tr><td><small>XC_left_ptr</small></td><td><small>GDK_LEFT_PTR</small></td><td><small>68</small></td></tr> -<tr><td><small>XC_plus</small></td><td><small>GDK_PLUS</small></td><td><small>90</small></td></tr> -<tr><td><small>XC_right_ptr</small></td><td><small>GDK_RIGHT_PTR</small></td><td><small>94</small></td></tr> -<tr><td><small>XC_tcross</small></td><td><small>GDK_TCROSS</small></td><td><small>130</small></td></tr> -<tr><td><small>XC_xterm</small></td><td><small>GDK_XTERM</small></td><td><small>152</small></td></tr> -</table> -</td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> <!-- html-dir --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="htmldir">html-dir</a></code></td> -<td bgcolor="#f2f4ff"><code>"."</code></td></tr><tr><td></td><td colspan=2> -html-dir is the directory to search for documentation if an HTML reader is in use. +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- html-program --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="htmlprogram">html-program</a></code></td> -<td bgcolor="#f2f4ff"><code>"firefox"</code></td></tr><tr><td></td><td colspan=2> -This is the program to use to read HTML files. +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- initial-beg --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="initialbeg">initial-beg</a></code></td> -<td bgcolor="#f2f4ff"><code>0.0</code></td></tr><tr><td></td><td colspan=2> -initial-beg is the start point (in seconds) of the initial graph of a sound. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="initialdur">initial-dur</a></code></td> -<td bgcolor="#f2f4ff"><code>0.1</code></td></tr><tr><td></td><td colspan=2> -initial-dur is the duration (in seconds) of the initial graph of a sound. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="justsounds">just-sounds</a></code></td> -<td bgcolor="#f2f4ff"><code>#t</code></td></tr><tr><td></td><td colspan=2> -If just-sounds is #t, +<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>). -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- ladspa-dir --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="ladspadir">ladspa-dir</a></code></td> -<td bgcolor="#f2f4ff"><code>#f</code></td></tr><tr><td></td><td colspan=2> -LADSPA is a way of managing plug-ins in Linux. I consider it very old-fashioned, but +<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>. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- log-freq-start --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="logfreqstart">log-freq-start</a></code></td> -<td bgcolor="#f2f4ff"><code>32.0</code></td></tr><tr><td></td><td colspan=2> -log-freq-start is the start (lowest) frequency used in the log freq display (ffts). Since the log display emphasizes the lower +<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>. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- max-regions --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="maxregions">max-regions</a></code></td> -<td bgcolor="#f2f4ff"><code>16</code></td></tr><tr><td></td><td colspan=2> -This sets the maximum size of the region list, the number of regions that are accessible. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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> -<!-- max-virtual-ptrees --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="maxvirtualptrees">max-virtual-ptrees</a></code></td> -<td bgcolor="#f2f4ff"><code>32</code></td></tr><tr><td></td><td colspan=2> -This sets the maximum number of parse-trees (see <a href="#ptreechannel">ptree-channel</a>) that the -virtual editor will allow in any virtual edit (once the maximum is reached, the operation is handled -locally, not via a virtual edit). -</td></tr><tr><td colspan=3 height=16></td></tr> +<!-- mus-max-malloc --> +<pre class="indented"> +<em class=def id="musmaxmalloc">mus-max-malloc</em> (default: 67108864) +</pre> -<!-- minibuffer-history-length --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="minibufferhistorylength">minibuffer-history-length</a></code></td> -<td bgcolor="#f2f4ff"><code>8</code></td></tr><tr><td></td><td colspan=2> -This sets the maximum length of the minibuffer and listener M-p/M-n history lists. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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-malloc --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musmaxmalloc">mus-max-malloc</a></code></td> -<td bgcolor="#f2f4ff"><code>67108864</code></td></tr><tr><td></td><td colspan=2> -This sets the maximum memory allocation (in bytes). -</td></tr><tr><td colspan=3 height=16></td></tr> +<!-- 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-max-table-size --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musmaxtablesize">mus-max-table-size</a></code></td> -<td bgcolor="#f2f4ff"><code>20971520</code></td></tr><tr><td></td><td colspan=2> -This sets the maximum table size (delay line length in samples, etc). -</td></tr><tr><td colspan=3 height=16></td></tr> +<!-- 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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="openfiledialogdirectory">open-file-dialog-directory</a></code></td> -<td bgcolor="#f2f4ff"><code>"."</code></td></tr><tr><td></td><td colspan=2> -open-file-dialog-directory is the name of the initial open file dialog directory (normally "."). -</td></tr><tr><td colspan=3 height=16></td></tr> - - -<!-- optimization --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="optimization">optimization</a></code></td> -<td bgcolor="#f2f4ff"><code>6</code></td></tr><tr><td></td><td colspan=2> -optimization affects optimization levels in Scheme. -If non-zero, it causes Snd to try to optimize simple lambda forms passed to the searches and so forth. -This applies only to s7. -The actual values of the optimization switch are: -<pre> - 0: no optimization (use the standard Scheme parser/evaluator) - 1: optimize simple stuff (if complex result possible, give up) - 2: assume nothing will return a complex number - 3: if an undefined variable is encountered, try to guess its type - 4: make questionable assumptions about variable types - 5: make dangerous assumptions about variable locations (for set!) - 6: try to splice in user-defined functions -</pre> - -Currently, the optimizer is able to speed up Scheme code by factors between -8 and 20; see run.c for what is implemented, what the major limitations are, and so on. -If you set the optimization-hook to print out whatever its argument is, you can -find out what the optimizer found confusing: -<pre> - (hook-push <a class=quiet href="#optimizationhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_optimizationhook_tip)">optimization-hook</a> (lambda (n) (display (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "opt: ~A~%" n)))) +<pre class="indented"> +<em class=def id="openfiledialogdirectory">open-file-dialog-directory</em> (default: ".") </pre> -See also <a href="#maxvirtualptrees">max-virtual-ptrees</a>. -</td></tr><tr><td colspan=3 height=16></td></tr> + +<p>open-file-dialog-directory is the name of the initial open file dialog directory (normally "."). +</p> +<div class="spacer"></div> <!-- peak-env-dir --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="peakenvdir">peak-env-dir</a></code></td> -<td bgcolor="#f2f4ff"><code>#f</code></td></tr><tr><td></td><td colspan=2> -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. +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- play-arrow-size --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="playarrowsize">play-arrow-size</a></code></td> -<td bgcolor="#f2f4ff"><code>10</code></td></tr><tr><td></td><td colspan=2> -This is the size of the triangular arrow that handles click-to-play duties for the cursor, marks, mixes, and the selection. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="printlength">print-length</a></code></td> -<td bgcolor="#f2f4ff"><code>12</code></td></tr><tr><td></td><td colspan=2> -For objects such as vcts, print-length sets the number of elements printed. -In S7, this also sets *vector-print-length*. -<pre> - <em class=listener>></em><em class=typing>(set! (print-length) 3)</em> - <em class=listener>3</em> - <em class=listener>></em><em class=typing>(make-vct 10 .1)</em> - <em class=listener>#<vct[len=10]: 0.100 0.100 0.100 ...></em> +<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"> +> (set! (print-length) 3) +3 +> (make-float-vector 10 .1) +#(0.1 0.1 0.1 ...) </pre> -</td></tr><tr><td colspan=3 height=16></td></tr> +<div class="spacer"></div> <!-- remember-sound-state --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="remembersoundstate">remember-sound-state</a></code></td> -<td bgcolor="#f2f4ff"><code>#f</code></td></tr><tr><td></td><td colspan=2> -If remember-sound-state is #t, Snd saves most of a sound's display state when it is closed, +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- save-dir --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="savedir">save-dir</a></code></td> -<td bgcolor="#f2f4ff"><code>#f</code></td></tr><tr><td></td><td colspan=2> -save-dir is the name of the directory for saved-state files. -<br><br> +<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. -<span onmouseout="UnTip()" onmouseover="Tip('<pre>Ruby: set_save_dir("/tmp"), Forth: "/tmp" set-save-dir</pre>')"><code>(set! (<a class=quiet href="#savedir" onmouseout="UnTip()" onmouseover="Tip(extsnd_savedir_tip)">save-dir</a>) "/tmp")</code></span>. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- save-state-file --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="savestatefile">save-state-file</a></code></td> -<td bgcolor="#f2f4ff"><code>"saved-snd.scm"</code></td></tr><tr><td></td><td colspan=2> -This is the <a href="snd.html#savedstate">saved state</a> file name. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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) (> y .1))) +</pre> +<div class="spacer"></div> <!-- selection-creates-region --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="selectioncreatesregion">selection-creates-region</a></code></td> -<td bgcolor="#f2f4ff"><code>#t</code></td></tr><tr><td></td><td colspan=2> -If selection-creates-region is #t, a region is created whenever a selection is made. If you're editing very large sounds +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- show-full-duration --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="showfullduration">show-full-duration</a></code></td> -<td bgcolor="#f2f4ff"><code>#f</code></td></tr><tr><td></td><td colspan=2> -If show-full-duration is #t, Snd displays the entire sound when it is first opened. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="showindices">show-indices</a></code></td> -<td bgcolor="#f2f4ff"><code>#f</code></td></tr><tr><td></td><td colspan=2> -If show-indices is #t, each sound's name is preceded by its index in the sound pane. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="showselectiontransform">show-selection-transform</a></code></td> -<td bgcolor="#f2f4ff"><code>#f</code></td></tr><tr><td></td><td colspan=2> -If show-selection-transform is #t, Snd displays the transform of the current active selection, if any. +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- sinc-width --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="sincwidth">sinc-width</a></code></td> -<td bgcolor="#f2f4ff"><code>10</code></td></tr><tr><td></td><td colspan=2> -sinc-width is the width in samples of the sampling rate conversion sinc interpolation. -<br><br> +<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_srcsound_tip)">src-sound</a> '(0 3 1 1))</code> with sinc-width at 4. -</td></tr><tr><td colspan=3 height=16></td></tr> - - -<!-- snd-version --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="sndversion">snd-version</a></code></td> -<td bgcolor="#f2f4ff"><code>"Snd 11.7, 9-Aug-10"</code></td></tr><tr><td></td><td colspan=2> -This is a string giving the current Snd version. -</td></tr><tr><td colspan=3 height=16></td></tr> +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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="syncstyle">sync-style</a></code></td> -<td bgcolor="#f2f4ff"><code>sync-by-sound</code></td></tr><tr><td></td><td colspan=2> -sync-style determines how sounds and their channels are sync'd together when they are -opened. <code>sync-none</code> means that no sounds, and no channels are tied together; -<code>sync-all</code> causes everything to be tied together; <code>sync-by-sound</code>, the default, causes individual sounds to +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- temp-dir --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="tempdir">temp-dir</a></code></td> -<td bgcolor="#f2f4ff"><code>#f</code></td></tr><tr><td></td><td colspan=2> -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>. -</td></tr><tr><td colspan=3 height=16></td></tr> - +<pre class="indented"> +<em class=def id="tempdir">temp-dir</em> (default: #f) +</pre> -<!-- trap-segfault --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="trapsegfault">trap-segfault</a></code></td> -<td bgcolor="#f2f4ff"><code>#t</code></td></tr><tr><td></td><td colspan=2> -If trap-segfault is #t, Snd tries to catch segfaults and continue anyway. This normally gives you -a chance to save your current work, but please also send bil@ccrma.stanford.edu a bug report! -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="windowheight">window-height</a></code></td> -<td bgcolor="#f2f4ff"><code>0</code></td></tr><tr><td></td><td colspan=2> -window-height is the current Snd window height in pixels. -This is the same as <br> -<pre> - Scheme: (cadr (<a class=quiet href="#widgetsize" onmouseout="UnTip()" onmouseover="Tip(extsnd_widgetsize_tip)">widget-size</a> (cadr (<a class=quiet href="#mainwidgets" onmouseout="UnTip()" onmouseover="Tip(extsnd_mainwidgets_tip)">main-widgets</a>)))) +<pre class="indented"> +<em class=def id="windowheight">window-height</em> (default: 0) +</pre> - Ruby: widget_size(main_widgets.cadr).cadr +<p>window-height is the current Snd window height in pixels. +This is the same as +</p> - Forth: main-widgets cadr widget-size cadr +<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> -except at startup when the window-height function and friends defer the assignment until after the main widgets + +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- window-width --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="windowwidth">window-width</a></code></td> -<td bgcolor="#f2f4ff"><code>0</code></td></tr><tr><td></td><td colspan=2> -This is the current Snd window width in pixels. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="windowx">window-x</a></code></td> -<td bgcolor="#f2f4ff"><code>-1</code></td></tr><tr><td></td><td colspan=2> -This is the current Snd window left side position in pixels (-1 means unset). -This is (usually) the same as -<pre> - (car (<a class=quiet href="#widgetposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_widgetposition_tip)">widget-position</a> (cadr (<a class=quiet href="#mainwidgets" onmouseout="UnTip()" onmouseover="Tip(extsnd_mainwidgets_tip)">main-widgets</a>)))) +<pre class="indented"> +<em class=def id="windowx">window-x</em> (default: -1) </pre> -</td></tr><tr><td colspan=3 height=16></td></tr> + +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="windowy">window-y</a></code></td> -<td bgcolor="#f2f4ff"><code>-1</code></td></tr><tr><td></td><td colspan=2> -This is the current Snd window upper side position in pixels (X numbering starts at 0 at the top, -1 means unset). -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="withbackgroundprocesses">with-background-processes</a></code></td> -<td bgcolor="#f2f4ff"><code>#t</code></td></tr><tr><td></td><td colspan=2> -with-background-processes determines whether Snd should use background (idle time) processes for ffts and so forth. +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- with-file-monitor --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="withfilemonitor">with-file-monitor</a></code></td> -<td bgcolor="#f2f4ff"><code>#t</code></td></tr><tr><td></td><td colspan=2> -If with-file-monitor is #t (the default), the file alteration monitor is active. There are still bugs +<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 — I haven't tracked down what the problem is yet; in the meantime, -set this switch to #f to disable the monitor. (One such bug was fixed in gamin 1.8.0). -</td></tr><tr><td colspan=3 height=16></td></tr> +set this switch to #f to disable the monitor. +</p> +<div class="spacer"></div> <!-- with-inset-graph --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="withinsetgraph">with-inset-graph</a></code></td> -<td bgcolor="#f2f4ff"><code>#f</code></td></tr><tr><td></td><td colspan=2> -If with-inset-graph is #t, a small graph is +<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 src="pix/uppergrf.png" alt="with-inset-graph" hspace=20 vspace=10> -<br> -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 Gtk/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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="withmenuicons">with-menu-icons</a></code></td> -<td bgcolor="#f2f4ff"><code>#f</code></td></tr><tr><td></td><td colspan=2> -with-menu-icons determines whether some menus display icons beside the item labels (in Gtk only). -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 (in Gtk only). +This sets both gtk-menu-images and gtk-button-images. There are a lot of these default settings +in gtk (see GtkSettings.html). To set one from Scheme: +</p> + +<pre class="indented"> +(with-let *gtk* (g_object_set (GPOINTER (gtk_settings_get_default)) "gtk-menu-images" #t)) +</pre> + +<p>To get the current value of one of these settings, you need to tell xg the expected return +type. In the next example, we assume we're getting an integer: +</p> + +<pre class="indented"> +> (with-let *gtk* (g_object_get (GPOINTER (gtk_settings_get_default)) "gtk-cursor-blink-time" #f)) +1200 +</pre> +<div class="spacer"></div> <!-- with-pointer-focus --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="withpointerfocus">with-pointer-focus</a></code></td> -<td bgcolor="#f2f4ff"><code>#f</code></td></tr><tr><td></td><td colspan=2> -If with-pointer-focus is #t, whatever text or graph widget is underneath the mouse cursor is activated +<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). -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- with-relative-panes --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="withrelativepanes">with-relative-panes</a></code></td> -<td bgcolor="#f2f4ff"><code>#t</code></td></tr><tr><td></td><td colspan=2> -If with-relative-panes is #t in the Motif +<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?). -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- with-smpte-label --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="withsmptelabel">with-smpte-label</a></code></td> -<td bgcolor="#f2f4ff"><code>#f</code></td></tr><tr><td></td><td colspan=2> -with-smpte-label shows the current SMPTE frame number in a box +<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). -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- with-toolbar --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="withtoolbar">with-toolbar</a></code></td> -<td bgcolor="#f2f4ff"><code>#t (gtk), #f (motif)</code></td></tr><tr><td></td><td colspan=2> -with-toolbar places a toolbar at the top of the Snd window, just under the main menu. - -<img src="pix/toolbar.png" alt="with-toolbar picture" hspace=20 vspace=10 usemap="#toolbarmap" border=0> -<map name="toolbarmap" - <area shape=rect coords="3, 42, 31, 76" alt="new sound icon" onmouseout="UnTip()" onmouseover="Tip('new sound')"> - <area shape=rect coords="32, 42, 60, 76" alt="open sound icon" onmouseout="UnTip()" onmouseover="Tip('open sound')"> - <area shape=rect coords="61, 42, 89, 76" alt="save icon" onmouseout="UnTip()" onmouseover="Tip('save edits')"> - <area shape=rect coords="90, 42, 118, 76" alt="revert icon" onmouseout="UnTip()" onmouseover="Tip('revert to saved')"> - <area shape=rect coords="119, 42, 149, 76" alt="undo icon" onmouseout="UnTip()" onmouseover="Tip('undo edit')"> - <area shape=rect coords="148, 42, 176, 76" alt="redo icon" onmouseout="UnTip()" onmouseover="Tip('redo edit')"> - <area shape=rect coords="177, 42, 205, 76" alt="close icon" onmouseout="UnTip()" onmouseover="Tip('close sound')"> - <area shape=rect coords="206, 42, 234, 76" alt="play icon" onmouseout="UnTip()" onmouseover="Tip('play from the start')"> - <area shape=rect coords="235, 42, 263, 76" alt="play from cursor icon" onmouseout="UnTip()" onmouseover="Tip('play from the cursor')"> - <area shape=rect coords="264, 42, 292, 76" alt="stop playing icon" onmouseout="UnTip()" onmouseover="Tip('stop playing')"> - <area shape=rect coords="293, 42, 321, 76" alt="full sound icon" onmouseout="UnTip()" onmouseover="Tip('show full sound')"> - <area shape=rect coords="322, 42, 350, 76" alt="zoom out icon" onmouseout="UnTip()" onmouseover="Tip('zoom out')"> - <area shape=rect coords="351, 42, 379, 76" alt="zoom in icon" onmouseout="UnTip()" onmouseover="Tip('zoom in')"> - <area shape=rect coords="380, 42, 408, 76" alt="start icon" onmouseout="UnTip()" onmouseover="Tip('go to start of sound')"> - <area shape=rect coords="409, 42, 437, 76" alt="back icon" onmouseout="UnTip()" onmouseover="Tip('go back a window')"> - <area shape=rect coords="438, 42, 466, 76" alt="next icon" onmouseout="UnTip()" onmouseover="Tip('go forward a window')"> - <area shape=rect coords="467, 42, 495, 76" alt="end icon" onmouseout="UnTip()" onmouseover="Tip('go to end of sound')"> - <area shape=rect coords="496, 42, 524, 76" alt="select icon" onmouseout="UnTip()" onmouseover="Tip('select all of sound')"> - <area shape=rect coords="525, 42, 553, 76" alt="unselect icon" onmouseout="UnTip()" onmouseover="Tip('unselect everything')"> - <area shape=rect coords="554, 42, 582, 76" alt="cut icon" onmouseout="UnTip()" onmouseover="Tip('delete selection')"> - <area shape=rect coords="583, 42, 611, 76" alt="paste icon" onmouseout="UnTip()" onmouseover="Tip('insert selection at cursor')"> - <area shape=rect coords="612, 42, 640, 76" alt="prefs icon" onmouseout="UnTip()" onmouseover="Tip('start preferences dialog')"> - <area shape=rect coords="641, 42, 669, 76" alt="quit icon" onmouseout="UnTip()" onmouseover="Tip('stop everything')"> - <area shape=rect coords="670, 42, 700, 76" alt="exit icon" onmouseout="UnTip()" onmouseover="Tip('exit Snd')"> -</map> - -</td></tr><tr><td colspan=3 height=16></td></tr> +<pre class="indented"> +<em class=def id="withtoolbar">with-toolbar</em> (default: #t (gtk), #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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="withtooltips">with-tooltips</a></code></td> -<td bgcolor="#f2f4ff"><code>#t</code></td></tr><tr><td></td><td colspan=2> -Set with-tooltips to #f to turn off tooltips. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="withtrackingcursor">with-tracking-cursor</a></code></td> -<td bgcolor="#f2f4ff"><code>#f</code></td></tr><tr><td></td><td colspan=2> -<p>This is #t if the cursor always follows along in the sound during playback. If it is #f, +<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). +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 @@ -1338,46 +1510,53 @@ apparent progress (if playing forwards). </p> <!-- INDEX trackingcursors:Tracking cursors --> -<A NAME="trackingcursors"></a> -<TABLE border=3 bordercolor="tan" hspace=20 vspace=10><tr><td> +<TABLE class="method"> +<tr><th class="title">tracking cursor</th></tr> +<tr><td> <blockquote><small> -<br> 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: if-cursor-follows-play-it-stays-where-play-stopped in examp.scm<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> -<br> </small></blockquote> </td></tr></TABLE> -</td></tr><tr><td colspan=3 height=16></td></tr> + +<div class="spacer"></div> + <!-- zoom-focus-style --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="zoomfocusstyle">zoom-focus-style</a></code></td> -<td bgcolor="#f2f4ff"><code>zoom-focus-active</code></td></tr><tr><td></td><td colspan=2> -This determines what a zoom action focuses (centers) on. The choices are -<code>zoom-focus-left</code>, <code>zoom-focus-right</code>, <code>zoom-focus-active</code>, <code>zoom-focus-middle</code>, +<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. -<pre> - (set! (zoom-focus-style) (lambda (snd chn zx x0 x1 range) (- x1 (* zx range)))) +</p> + +<pre class="indented"> +(set! (zoom-focus-style) (lambda (snd chn zx x0 x1 range) (- x1 (* zx range)))) </pre> -mimics zoom-focus-right. <code>zoom-focus-active</code> tries to focus on some object in the view: the cursor, a mix or mark, etc. + +<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>. -</td></tr> -</table> -<br><br> +</p> + + + +<!-- GENERIC FUNCTIONS --> -<!-- ---------------------------------------- GENERIC FUNCTIONS ---------------------------------------- --> -<table width="60%" border=0><tr><td bgcolor="lightgreen" valign="middle"><h4><A NAME="sndgenericfuncs">Generic functions</a></h4></td></tr></table> +<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, @@ -1385,1564 +1564,1672 @@ as well as lists. Objects specific to Snd include sounds, the selection, mixes, samplers, regions, and players, all of which should be compared with equal?, not eq?. </p> -<table border=0 cellspacing=4 cellpadding=6 hspace=10> +<div class="spacer"></div> <!-- channels --> <!-- INDEX genericchannels:channels (generic) --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def>channels</a> obj</code> -</td></tr><tr><td></td><td> -<A NAME="genericchannels">channels</A> handles strings (<a href="#mussoundchans">mus-sound-chans</a>), +<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="#sounddatachans">sound-data-chans</a>, <a href="sndclm.html#genericfunctions">mus-channels</a>, +<a href="sndclm.html#genericfunctions">mus-channels</a>, <a href="#sndmixes">mixes</a>, <a href="#Vcts">vcts</a>, and vectors (always 1 channel), and <a href="#sndsounds">sounds</a> (as objects or as integers). -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="spacer"></div> <!-- copy --> <!-- INDEX genericcopy:copy (generic) --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def>copy</a> obj</code> -</td></tr><tr><td></td><td> -<A NAME="genericcopy">copy</A> returns a copy of its argument. -It works with strings, lists, vectors, hash tables, vcts, sound-data objects, frames, mixers, sounds, the current selection, mixes, marks, +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="spacer"></div> <!-- file-name --> <!-- INDEX genericfilename:file-name (generic) --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def>file-name</a> obj</code> -</td></tr><tr><td></td><td> -<A NAME="genericfilename">filename</A> can replace <a href="#musexpandfilename">mus-expand-filename</a>, +<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>. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="spacer"></div> <!-- fill! --> <!-- INDEX genericfill:fill! (generic) --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def>fill!</a> obj val</code> -</td></tr><tr><td></td><td> -<A NAME="genericfill">fill!</A> fills obj with val (s7 only). -fill! works with strings, vectors, hash-tables, vcts, lists, sounds, the selection, sound-data objects, -frames, and mixers. -</td></tr><tr><td colspan=2 height=18></td></tr> - - -<!-- frames --> -<!-- INDEX genericframes:frames (generic) --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def>frames</a> obj <em class=narg>chn edpos</em></code> -</td></tr><tr><td></td><td> -<A NAME="genericframes">frames</A> returns the number of "frames" in an object, that is, -the number of samples per channel. The frames function overlaps -the <a href="#genericlength">length</a> function, but length of a string is string-length, whereas frames of a string -treats the string as a sound file name and returns <a href="#mussoundframes">mus-sound-frames</a>. frames can replace -<a href="#mussoundframes">mus-sound-frames</a>, <a href="sndclm.html#genericfunctions">mus-length</a>, +<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="#regionframes">region-frames</a>, <a href="#selectionframes">selection-frames</a>, -<a href="#vctlength">vct-length</a>, <a href="#sounddatalength">sound-data-length</a>, -and the regular <a href="#frames">frames</a> function that handles sound objects and integers as sound indices. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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) --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def>length</a> obj</code> -</td></tr><tr><td></td><td> -<A NAME="genericlength">length</A> handles list length, string-length, vector-length, <a href="s7.html#s7doc">hash-table-size</a>, -<a href="#vctlength">vct-length</a>, <a href="#frames">frames</a> (sound length), <a href="#colormapsize">colormap-size</a>, -<a href="sndclm.html#genericfunctions">mus-length</a> (generators), <a href="#sounddatalength">sound-data-length</a>, +<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="#selectionframes">selection-frames</a>, -and <a href="#regionframes">region-frames</a>. -</td></tr><tr><td colspan=2 height=18></td></tr> +<a href="#selectionframples">selection-framples</a>, +and <a href="#regionframples">region-framples</a>. +</p> +<div class="spacer"></div> <!-- maxamp --> <!-- INDEX genericmaxamp:maxamp (generic) --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def>maxamp</a> obj <em class=narg>chn</em></code> -</td></tr><tr><td></td><td> -<A NAME="genericmaxamp">maxamp</A> can handle a sound (via the regular <a href="#maxamp">maxamp</a> function), +<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 vct, if any), -sound-data (<a href="#sounddatamaxamp">sound-data-maxamp</a>), -vct (<a href="#vctpeak">vct-peak</a>), +float-vector, region (<a href="#regionmaxamp">region-maxamp</a>), the current selection (<a href="#selectionmaxamp">selection-maxamp</a>), vector, list, or mix object. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="spacer"></div> <!-- play --> <!-- INDEX genericplay:play (generic) --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def>play</a> <em class=narg>object :start :end :channel :edit-position :out-channel :with-sync :wait :stop :srate :channels</em></code> -</td></tr><tr><td></td><td> -<A NAME="genericplay">play</A> plays an object. +<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>. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="spacer"></div> <!-- srate --> <!-- INDEX genericsrate:srate (generic) --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def>srate</a> obj</code> -</td></tr><tr><td></td><td> -<A NAME="genericsrate">srate</A> handles strings (treated as file names: <a href="#mussoundsrate">mus-sound-srate</a>), +<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). -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="spacer"></div> <!-- sync --> <!-- INDEX genericsync:sync (generic) --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def>sync</a> obj</code> -</td></tr><tr><td></td><td> -<A NAME="genericsync">sync</A> accesses the '<a href="#sync">sync</a>' field of a sound, mark, or mix. -</td></tr><tr><td colspan=2 height=18></td></tr> +<pre class="indented"> +<em class=def>sync</em> obj +</pre> -</table> +<p id="genericsync">sync accesses the '<a href="#sync">sync</a>' field of a sound, mark, or mix. +</p> -<br><br> -<!-- ---------------------------------------- HOOKS ---------------------------------------- --> +<!-- HOOKS --> <!-- INDEX sndhooks:Hooks --> -<table width="60%" border=0><tr><td bgcolor="lightgreen" valign="middle"><h4><A NAME="sndhooks">Hooks</a></h4></td></tr></table> + +<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 minibuffer is +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> - Scheme: (hook-push <a class=quiet href="#nameclickhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_nameclickhook_tip)">name-click-hook</a> (lambda (snd) (<a class=quiet href="#sndprint" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndprint_tip)">snd-print</a> "hi") #t)) - - Ruby: $name_click_hook.add_hook!("print") do |snd| snd_print("hi"); true end - - Forth: name-click-hook lambda: <{ snd }> "hi" snd-print drop #t ; add-hook! +<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: <{ snd }> "hi" snd-print drop #t ; add-hook! </pre> -<p> -If there is more than one function attached to a hook, some of the hooks -"or" the functions together (marked <b>[or]</b> below); that is they +<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 the other -cases ("progn", the name coming from Common Lisp), the result returned by the hook is the result of the last function in the list. +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. There are a variety of hook-related functions in hooks.scm. +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" onmouseout="UnTip()" onmouseover="Tip(extsnd_badheaderhook_tip)">bad-header-hook</a> — can cancel request - no header?: <a class=quiet href="#openrawsoundhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_openrawsoundhook_tip)">open-raw-sound-hook</a> — can cancel request + bad header?: <a class=quiet href="#badheaderhook">bad-header-hook</a> — can cancel request + no header?: <a class=quiet href="#openrawsoundhook">open-raw-sound-hook</a> — can cancel request file ok: - <a class=quiet href="#openhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_openhook_tip)">open-hook</a> — can change filename + <a class=quiet href="#openhook">open-hook</a> — can change filename file opened (no data read yet) - <a class=quiet href="#duringopenhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_duringopenhook_tip)">during-open-hook</a> (can set prescaling etc) + <a class=quiet href="#duringopenhook">during-open-hook</a> (can set prescaling etc) data read, no graphics yet - <a class=quiet href="#afteropenhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_afteropenhook_tip)">after-open-hook</a> - <a class=quiet href="#initialgraphhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_initialgraphhook_tip)">initial-graph-hook</a> + <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" onmouseout="UnTip()" onmouseover="Tip(extsnd_beforesaveashook_tip)">before-save-as-hook</a> — can cancel the request or set its output parameters - <a class=quiet href="#savehook" onmouseout="UnTip()" onmouseover="Tip(extsnd_savehook_tip)">save-hook</a> + <a class=quiet href="#beforesaveashook">before-save-as-hook</a> — 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" onmouseout="UnTip()" onmouseover="Tip(extsnd_cliphook_tip)">clip-hook</a> - <a class=quiet href="#aftersaveashook" onmouseout="UnTip()" onmouseover="Tip(extsnd_aftersaveashook_tip)">after-save-as-hook</a> + 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" onmouseout="UnTip()" onmouseover="Tip(extsnd_startplayinghook_tip)">start-playing-hook</a> — can cancel the request, also <a class=quiet href="#startplayingselectionhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_startplayingselectionhook_tip)">start-playing-selection-hook</a> + when a play request occurs: <a class=quiet href="#startplayinghook">start-playing-hook</a> — 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 buffer is sent to the audio device: <a class=quiet href="#playhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_playhook_tip)">play-hook</a> and <a class=quiet href="#dachook" onmouseout="UnTip()" onmouseover="Tip(extsnd_dachook_tip)">dac-hook</a> - as each sound ends: <a class=quiet href="#stopplayinghook" onmouseout="UnTip()" onmouseover="Tip(extsnd_stopplayinghook_tip)">stop-playing-hook</a>, <a class=quiet href="#stopplayingselectionhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_stopplayingselectionhook_tip)">stop-playing-selection-hook</a> - close audio device: <a class=quiet href="#stopdachook" onmouseout="UnTip()" onmouseover="Tip(extsnd_stopdachook_tip)">stop-dac-hook</a> + 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" onmouseout="UnTip()" onmouseover="Tip(extsnd_beforeclosehook_tip)">before-close-hook</a> — can cancel close - <a class=quiet href="#closehook" onmouseout="UnTip()" onmouseover="Tip(extsnd_closehook_tip)">close-hook</a> (sound is still open) + <a class=quiet href="#beforeclosehook">before-close-hook</a> — 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" onmouseout="UnTip()" onmouseover="Tip(extsnd_savestatehook_tip)">save-state-hook</a> — can change output filename (crummy name is an historical artifact) + <a class=quiet href="#savestatehook">save-state-hook</a> — can change output filename (crummy name is an historical artifact) output save-state file opened - <a class=quiet href="#beforesavestatehook" onmouseout="UnTip()" onmouseover="Tip(extsnd_beforesavestatehook_tip)">before-save-state-hook</a> + <a class=quiet href="#beforesavestatehook">before-save-state-hook</a> Snd saves its state - <a class=quiet href="#aftersavestatehook" onmouseout="UnTip()" onmouseover="Tip(extsnd_aftersavestatehook_tip)">after-save-state-hook</a> + <a class=quiet href="#aftersavestatehook">after-save-state-hook</a> output closed Exit Snd - <a class=quiet href="#beforeexithook" onmouseout="UnTip()" onmouseover="Tip(extsnd_beforeexithook_tip)">before-exit-hook</a> — can cancel exit request - <a class=quiet href="#exithook" onmouseout="UnTip()" onmouseover="Tip(extsnd_exithook_tip)">exit-hook</a> + <a class=quiet href="#beforeexithook">before-exit-hook</a> — can cancel exit request + <a class=quiet href="#exithook">exit-hook</a> Snd cleans up and exits </pre> -<p> -You can find out what's on a given hook with the following (which is mostly adding carriage returns to the -printout from hook-functions): -</p> -<table border=0 cellpadding=5 hspace=20><tr><td><pre> -(define (describe-hook hook) - (for-each - (lambda (n) - (<a class=quiet href="#sndprint" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndprint_tip)">snd-print</a> (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "~A~%" n))) - (reverse (<em class=red>hook-functions</em> hook)))) -</pre></td></tr></table> - <p>Here's the Ruby version of some of the hook-related functions: </p> -<pre> - $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 + +<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 +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> - open-hook ' open-buffer 1 make-proc add-hook! - open-hook "open-buffer" remove-hook! - open-hook reset-hook! - open-hook hook->list + +<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->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 +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> -<!-- -------------------------------- HOOK TABLE -------------------------------- --> - <p> In the following list of hooks, the arguments after the hook name refer to the arguments to the functions invoked by -the hook. That is, <code>after-apply-controls-hook (snd)</code> means that the functions on the -<a class=quiet href="#afterapplycontrolshook" onmouseout="UnTip()" onmouseover="Tip(extsnd_afterapplycontrolshook_tip)">after-apply-controls-hook</a> list each take one argument, a sound. -If the argument list is followed by some -indication such as "[or]", that means the various hook function values are or-d together. +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> -<table border=0 cellspacing=4 cellpadding=6> <!-- after-apply-controls-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="afterapplycontrolshook">after-apply-controls-hook</a> (snd)</code> -</td></tr><tr><td width=30></td><td colspan=2> -This hook is called when <a href="#applycontrols">apply-controls</a> finishes. +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- after-graph-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="aftergraphhook">after-graph-hook</a> (snd chn)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called after a graph is updated or redisplayed. +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- after-lisp-graph-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="afterlispgraphhook">after-lisp-graph-hook</a> (snd chn)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called after a "lisp" graph is updated or redisplayed. The <a href="#lispgraphhook">lisp-graph-hook</a> functions +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- after-open-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="afteropenhook">after-open-hook</a> (snd)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called just before a newly opened sound's window is displayed. -This provides a way to set various sound-specific defaults. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>after-open-hook</em> - (lambda (snd) - (if (> (<a class=quiet href="#channels" onmouseout="UnTip()" onmouseover="Tip(extsnd_channels_tip)">channels</a> snd) 1) - (begin - (set! (<a class=quiet href="#sync" onmouseout="UnTip()" onmouseover="Tip(extsnd_sync_tip)">sync</a> snd) (+ 1 snd)) ; 0 = #f - (set! (<a class=quiet href="#channelstyle" onmouseout="UnTip()" onmouseover="Tip(extsnd_channelstyle_tip)">channel-style</a> snd) <a class=quiet href="#channelstyle" onmouseout="UnTip()" onmouseover="Tip(extsnd_channelstyle_tip)">channels-combined</a>) - (set! (<a class=quiet href="#graphstyle" onmouseout="UnTip()" onmouseover="Tip(extsnd_graphstyle_tip)">graph-style</a> snd) <a class=quiet href="#graphstyle" onmouseout="UnTip()" onmouseover="Tip(extsnd_graphstyle_tip)">graph-filled</a>))))) -</pre></td></tr></table> + (lambda (hook) + (let ((snd (hook 'snd))) + (if (> (<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> -See also <a href="sndscm.html#xbopen">C-x b</a> support in examp.scm, +<p>See also enved.scm, and various examples in snd-motif.scm. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> + <!-- after-save-as-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="aftersaveashook">after-save-as-hook</a> (index filename from-dialog)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called after File:Save as. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="aftersavestatehook">after-save-state-hook</a> (filename)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called after Snd has saved its state (<a href="#savestate">save-state</a>). 'filename' is the (otherwise complete) saved state -program. See <a href="sndscm.html#wssavestate">ws-save-state</a> in ws.scm. It uses this sequence: -<br> -<pre> -(lambda (filename) - (let ((fd (open filename (logior O_RDWR O_APPEND)))) ; open to write at the end - (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> fd "~%~%;;; save-state stuff here ~%") - ... - (close fd))) +<pre class="indented"> +<em class=def id="aftersavestatehook">after-save-state-hook</em> (name) </pre> -</td></tr><tr><td colspan=3 height=16></td></tr> + +<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="aftertransformhook">after-transform-hook</a> (snd chn scaler)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called just after an FFT (or spectrum) is calculated. - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define (<A NAME="fftpeak">report-fft-peak</A> snd chn scale) - (if (and (<a class=quiet href="#transformgraphp" onmouseout="UnTip()" onmouseover="Tip(extsnd_transformgraphp_tip)">transform-graph?</a>) - (= (<a class=quiet href="#transformgraphtype" onmouseout="UnTip()" onmouseover="Tip(extsnd_transformgraphtype_tip)">transform-graph-type</a>) <a class=quiet href="#transformgraphtype" onmouseout="UnTip()" onmouseover="Tip(extsnd_transformgraphtype_tip)">graph-once</a>)) - (<a class=quiet href="#reportinminibuffer" onmouseout="UnTip()" onmouseover="Tip(extsnd_reportinminibuffer_tip)">report-in-minibuffer</a> - (number->string (/ (* 2 (<a class=quiet href="#vctpeak" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctpeak_tip)">vct-peak</a> (<a class=quiet href="#transformtovct" onmouseout="UnTip()" onmouseover="Tip(extsnd_transformtovct_tip)">transform->vct</a> snd chn))) - (<a class=quiet href="#transformsize" onmouseout="UnTip()" onmouseover="Tip(extsnd_transformsize_tip)">transform-size</a> snd chn)))))) -(hook-push <em class=red>after-transform-hook</em> report-fft-peak) -</pre></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> +<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->string (/ (* 2 (maxamp (transform->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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="badheaderhook">bad-header-hook</a> (filename)</code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called if a file has a bogus-looking header (that is, +<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 a hook function returns #t, Snd does not try to open the file. -<pre> - (hook-push bad-header-hook (lambda (n) #t)) ; don't open bogus-looking files +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> -If no header is found, <a href="#openrawsoundhook">open-raw-sound-hook</a> is invoked instead ("raw" = "headerless"). -</td></tr><tr><td colspan=3 height=16></td></tr> + +<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="beforeclosehook">before-close-hook</a> (snd) </code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called when a file is about to be closed. If a hook function returns #t, the file is not closed. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="beforeexithook">before-exit-hook</a> ()</code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called upon a request to exit Snd. -If a hook function returns #t, Snd does not exit. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="beforesaveashook">before-save-as-hook</a> (index filename selection srate header-type data-format comment)</code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called before <a href="#savesoundas">save-sound-as</a> or File:Save as. -If a hook function returns something other than #f, the +<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; -'index' is the to-be-saved sound's index; 'filename' is the output file's name; 'selection' is #t if +'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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>before-save-as-hook</em> - (lambda (index filename selection sr type format comment) - (if (not (= sr (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a> index))) - (let ((chns (<a class=quiet href="#chans" onmouseout="UnTip()" onmouseover="Tip(extsnd_chans_tip)">channels</a> index))) - (do ((i 0 (+ 1 i))) - ((= i chns)) - (<a class=quiet href="#srcchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_srcchannel_tip)">src-channel</a> (exact->inexact (/ (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a> index) sr)) 0 #f index i)) - (<a class=quiet href="#savesoundas" onmouseout="UnTip()" onmouseover="Tip(extsnd_savesoundas_tip)">save-sound-as</a> filename index :header-type type :data-format format :srate sr :comment comment) - ;; hook won't be invoked recursively - (do ((i 0 (+ 1 i))) - ((= i chns)) - (<a class=quiet href="#undo" onmouseout="UnTip()" onmouseover="Tip(extsnd_undo_tip)">undo</a> 1 index i)) - #t) ; tell Snd that the sound is already saved - #f))) -</pre></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> + (lambda (hook) + ((lambda (index filename sr dformat htype comment) + (if (not (= sr (<a class=quiet href="#srate">srate</a> index))) + (let ((chns (<a class=quiet href="#chans">channels</a> index))) + (do ((i 0 (+ i 1))) + ((= i chns)) + (<a class=quiet href="#srcchannel">src-channel</a> (exact->inexact (/ (<a class=quiet href="#srate">srate</a> index) sr)) 0 #f index i)) + (<a class=quiet href="#savesoundas">save-sound-as</a> filename index :header-type htype :sample-type dformat :srate sr :comment comment) + (do ((i 0 (+ i 1))) + ((= i chns)) + (<a class=quiet href="#undo">undo</a> 1 index i)) + (set! (hook 'result) #t)))) ; tell Snd that the sound is already saved + (hook 'snd) (hook 'name) (hook 'sampling-rate) (hook 'header-type) (hook 'sample-type) (hook 'comment)))) + +</pre> +<div class="spacer"></div> <!-- before-save-state-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="beforesavestatehook">before-save-state-hook</a> (filename)</code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called before Snd saves its state (<a href="#savestate">save-state</a>). 'filename' is the saved state -file. If the hook functions return #t, the save state file is opened in append mode (rather than create/truncate), +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>before-save-state-hook</em> - (lambda (name) - (<span onmouseout="UnTip()" onmouseover="Tip('io-open-write in Forth (see fs.fs); File.open in Ruby (I think — see extensions.rb)')">with-output-to-file name</span> - (lambda () - (display (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f ";this comment will be at the top of the saved state file.~%~%")) - #t)))) -</pre></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> + (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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="beforetransformhook">before-transform-hook</a> (snd chn)</code> [<b>progn</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called just before an FFT (or spectrum) is calculated. If a hook function returns +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>before-transform-hook</em> - (lambda (snd chn) ; 0.5 * (left + right) = midpoint - (round (* 0.5 (+ (<a class=quiet href="#rightsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_rightsample_tip)">right-sample</a> snd chn) (<a class=quiet href="#leftsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_leftsample_tip)">left-sample</a> snd chn)))))) -</pre></td></tr></table> + (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> -The following +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define fft-position #f) -(hook-push <em class=red>before-transform-hook</em> (lambda (snd chn) fft-position)) -(hook-push <a class=quiet href="#markdraghook" onmouseout="UnTip()" onmouseover="Tip(extsnd_markdraghook_tip)">mark-drag-hook</a> (lambda (id) - (set! fft-position (<a class=quiet href="#marksample" onmouseout="UnTip()" onmouseover="Tip(extsnd_marksample_tip)">mark-sample</a> id)) - (<a class=quiet href="#updatetransformgraph" onmouseout="UnTip()" onmouseover="Tip(extsnd_updatetransformgraph_tip)">update-transform-graph</a>))) -</pre></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> <!-- clip-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="cliphook">clip-hook</a> (clipping-value) </code> [<b>progn</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called whenever a sample is about to be clipped while writing out a sound file. -The hook function can return the new value. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="closehook">close-hook</a> (snd)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when a file is closed (before the actual close, so the index 'snd' is still valid). -<table border=0><tr><td> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(hook-push <em class=red>close-hook</em> - (lambda (snd) - (system "sndplay wood16.wav"))) -</pre></td></tr></table> -</td><td width=30></td><td> +<!-- close-hook --> +<pre class="indented"> +<em class=def id="closehook">close-hook</em> (snd) +</pre> -<table border=0 cellpadding=5 vspace=10><tr><td bgcolor="Beige"><pre> -<em class=red>$close_hook</em>.add_hook!("play") do |snd| - system("aplay wood16.wav") -end -</pre></td></tr></table> +<p>This hook is called when a file is closed (before the actual close, so the index 'snd' is still valid). +</p> -</td></tr></table> -close-hook is used in <a href="sndscm.html#autosavedoc">autosave.scm</a>, -the <a href="sndscm.html#xbopen">C-x b</a> support in examp.scm, -and many other places. -</td></tr><tr><td colspan=3 height=16></td></tr> +<pre class="indented"> +(hook-push <em class=red>close-hook</em> + (lambda (hook) + (play "wood16.wav"))) +</pre> +<div class="spacer"></div> <!-- color-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="colorhook">color-hook</a> () </code> [<b>progn</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called whenever one of the variables associated with the color dialog changes. -See <a href="sndscm.html#startwaterfall">start-waterfall</a> in snd-gl.scm. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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> -<!-- dac-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="dachook">dac-hook</a> (data) </code> [<b>progn</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called just before data is sent to DAC; 'data' is a <a href="#sndsounddata">sound-data</a> object. -See <a href="sndscm.html#withlevelmeters">with-level-meters</a> in snd-motif.scm. -</td></tr><tr><td colspan=3 height=16></td></tr> <!-- draw-mark-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="drawmarkhook">draw-mark-hook</a> (mark)</code> [<b>progn</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called before a mark is drawn. If the hook function returns #t, the mark is not drawn. +<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>. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- draw-mix-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="drawmixhook">draw-mix-hook</a> (mix old-x old-y x y)</code> [<b>progn</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called before a mix tag is drawn. If the hook function returns either #t or a list, the mix tag is not drawn by Snd (the +<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 function returns a list, its two elements (integers) are treated as the mix's tag x and y locations +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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- drop-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="drophook">drop-hook</a> (filename) </code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called each time Snd receives a drag-and-drop event, passing the hook functions the dropped filename. -If the hook functions return #t, the file is not opened by Snd. Normally if you drag a file icon to the menubar, +<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: -<pre> - (hook-push <em class=red>drop-hook</em> (lambda (filename) (<a class=quiet href="#mix" onmouseout="UnTip()" onmouseover="Tip(extsnd_mix_tip)">mix</a> filename) #t)) ; return #t = we already dealt with the drop +</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> -snd-motif.scm has examples that add a drop callback to an arbitrary widget, or -change an existing callback (to pass the sound and channel number to the drop callback function, bypassing drop-hook). -</td></tr><tr><td colspan=3 height=16></td></tr> +<div class="spacer"></div> <!-- during-open-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="duringopenhook">during-open-hook</a> (fd name reason)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called after file is opened, but before data has been read. -This provides an opportunity to set sndlib prescaling values: - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(hook-push <em class=red>during-open-hook</em> - (lambda (fd name reason) - (if (= (<a class=quiet href="#mussoundheadertype" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussoundheadertype_tip)">mus-sound-header-type</a> name) <a class=quiet href="#headertype" onmouseout="UnTip()" onmouseover="Tip(extsnd_musraw_tip)">mus-raw</a>) - (set! (<a href="#musfileprescaler" onmouseout="UnTip()" onmouseover="Tip(extsnd_musfileprescaler_tip)">mus-file-prescaler</a> fd) 500.0)))) -</pre></td></tr></table> - -The prescaling affects only sound data made up of floats or doubles. 'reason' is an integer indicating why this file is being opened: -<pre> - 0: reopen a temporarily closed file (internal to Snd — normally invisible) - 1: sound-open, File:open etc — the normal path to open a sound - 2: copy reader — 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 — an invisible editing case) - 5: open temp file after an edit (another invisible editing case) - 6: mix sound (File:Mix etc) -</pre> -So, to restrict the hook action to the normal case where Snd is opening a file for the first time, +<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 — normally invisible) +1: sound-open, File:open etc — the normal path to open a sound +2: copy reader — 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 — 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). -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> + <!-- effects-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="effectshook">effects-hook</a> ()</code> -</td></tr><tr><td></td><td colspan=2> -effects-hook is a convenience hook for the effects dialogs. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="envedhook">enved-hook</a> (env pt new-x new-y reason)</code> [<b>cascade</b>] -</td></tr><tr><td></td><td colspan=2> -Each time a breakpoint is changed in the envelope editor, this 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 <code>enved-move-point</code>, <code>enved-delete-point</code>, -or <code>enved-add-point</code>. This hook makes it possible to define attack +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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>enved-hook</em> - (lambda (env pt x y reason) - (if (= reason enved-move-point) - (if (and (> x 0.0) (< x (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(sndscm_envelopelastx_tip)">envelope-last-x</a> env))) ; from env.scm - (let* ((old-x (list-ref env (* pt 2))) - (new-env (<em class=red>stretch-envelope</em> env old-x x))) - (list-set! new-env (+ (* pt 2) 1) y) - new-env) - env) - #f))) -</pre></td></tr></table> - -If there are several functions on the hook, each gets the envelope -result of the preceding function (if a function returns #f, the envelope -is not changed). A math-type would call this a "function composition" -method combination; a filter-type would say "cascade"; -</td></tr><tr><td colspan=3 height=16></td></tr> + (lambda (hook) + ((lambda (env pt x y reason) + (if (and (= reason enved-move-point) + (> x 0.0) + (< x (<a class=quiet>envelope-last-x</a> env))) ; from env.scm + (let* ((old-x (env (* pt 2))) + (new-env (<em class=red>stretch-envelope</em> env old-x x))) + (set! (new-env (+ (* pt 2) 1)) y) + (set! (hook 'result) new-env)))) + (hook 'envelope) (hook 'point) (hook 'x) (hook 'y) (hook 'reason)))) +</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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="exithook">exit-hook</a> ()</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called upon exit. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="graphhook">graph-hook</a> (snd chn y0 y1) </code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called each time a graph is updated or redisplayed. -If its hook functions return #t, the display is not updated. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>graph-hook</em> - (lambda (snd chn y0 y1) - "set the dot size depending on the number of samples being displayed" - (let ((dots (- (<a class=quiet href="#rightsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_rightsample_tip)">right-sample</a> snd chn) (<a class=quiet href="#leftsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_leftsample_tip)">left-sample</a> snd chn)))) - (if (> dots 100) - (set! (<a class=quiet href="#dotsize" onmouseout="UnTip()" onmouseover="Tip(extsnd_dotsize_tip)">dot-size</a> snd chn) 1) - (if (> dots 50) - (set! (<a class=quiet href="#dotsize" onmouseout="UnTip()" onmouseover="Tip(extsnd_dotsize_tip)">dot-size</a> snd chn) 2) - (if (> dots 25) - (set! (<a class=quiet href="#dotsize" onmouseout="UnTip()" onmouseover="Tip(extsnd_dotsize_tip)">dot-size</a> snd chn) 3) - (set! (<a class=quiet href="#dotsize" onmouseout="UnTip()" onmouseover="Tip(extsnd_dotsize_tip)">dot-size</a> snd chn) 5)))) - #f))) -</pre></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> + (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)))) + (if (> dots 100) + (set! (<a class=quiet href="#dotsize">dot-size</a> snd chn) 1) + (if (> dots 50) + (set! (<a class=quiet href="#dotsize">dot-size</a> snd chn) 3) + (if (> dots 25) + (set! (<a class=quiet href="#dotsize">dot-size</a> snd chn) 5) + (set! (<a class=quiet href="#dotsize">dot-size</a> snd chn) 8)))))))) +</pre> +<div class="spacer"></div> + <!-- help-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="helphook">help-hook</a> (subject help-string)</code> [<b>cascade</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called from <a href="#sndhelp">snd-help</a> with the current help subject and default help-string. +<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): -<pre> - (hook-push <em class=red>help-hook</em> (lambda (subject help) (<a class=quiet href="sndscm.html#html" onmouseout="UnTip()" onmouseover="Tip(sndscm_html_function_tip)">html</a> subject) #f)) +</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> -If there is more than one hook function, each function's result is passed as input to the next function. -</td></tr><tr><td colspan=3 height=16></td></tr> +<div class="spacer"></div> <!-- initial-graph-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="initialgraphhook">initial-graph-hook</a> (snd chn dur) </code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called the first time a given channel is displayed (when the sound is first opened). -If the hook function returns a list, the list's contents are interpreted as: -<pre> - (list x0 x1 y0 y1 label ymin ymax) +<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> -(all trailing values are optional), where these numbers set the + +<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: -<pre> - (hook-push <em class=red>initial-graph-hook</em> (lambda (snd chn dur) (list 0.0 0.1 -1.0 1.0 "time" -1.0 1.0))) +</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> -The 'dur' argument is the total length in seconds of the displayed portion of the channel, so to cause the + +<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: -<pre> - (hook-push <em class=red>initial-graph-hook</em> (lambda (snd chn dur) (list 0.0 dur))) +</p> + +<pre class="indented"> +(hook-push <em class=red>initial-graph-hook</em> + (lambda (hook) + (set! (hook 'result) (list 0.0 (hook 'duration))))) </pre> -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>, + +<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 the file is short: +uses the maxamp data if it is already available or if the file is short: +</p> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>initial-graph-hook</em> - (lambda (snd chn dur) - (if (or (<a class=quiet href="#mussoundmaxampexists" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussoundmaxampexists_tip)">mus-sound-maxamp-exists?</a> (<a class=quiet href="#filename" onmouseout="UnTip()" onmouseover="Tip(extsnd_filename_tip)">file-name</a> snd)) - (< (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a> snd chn) 10000000)) - (let* ((amp-vals (<a class=quiet href="#mussoundmaxamp" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussoundmaxamp_tip)">mus-sound-maxamp</a> (<a class=quiet href="#filename" onmouseout="UnTip()" onmouseover="Tip(extsnd_filename_tip)">file-name</a> snd))) - (max-val (max 1.0 (list-ref amp-vals (+ (* chn 2) 1))))) - ;; max amp data is list: (sample value sample value ...) - (list 0.0 dur (- max-val) max-val)) ; these are the new y-axis limits - (list 0.0 dur -1.0 1.0)))) ; max amp unknown, so use defaults -</pre></td></tr></table> -</td></tr><tr><td colspan=3 height=16></td></tr> + (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)) + (< (<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="keypresshook">key-press-hook</a> (snd chn key state)</code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called upon key press while the mouse is in the lisp graph (the third graph, +<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 its function returns #t, the key press is not passed to the main handler. +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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> + <!-- lisp-graph-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="lispgraphhook">lisp-graph-hook</a> (snd chn)</code> [<b>progn</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called just before the lisp graph is updated or redisplayed (see <a href="#displaydb">display-db</a>). -If its function returns a list of pixels (xm style), these are used in order by the list of graphs (if any), rather than Snd's default set -(this makes it possible to use different colors for the various graphs). -If it returns a function (of no arguments), that function is called rather than the standard graph routine: - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<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 (snd chn) - (lambda () - (<a class=quiet href="#drawstring" onmouseout="UnTip()" onmouseover="Tip(extsnd_drawstring_tip)">draw-string</a> "hi" - (<a class=quiet href="#xtoposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_xtoposition_tip)">x->position</a> 0.5 snd chn <a class=quiet href="#ytoposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_lispgraph_tip)">lisp-graph</a>) - (<a class=quiet href="#ytoposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_ytoposition_tip)">y->position</a> 0.0 snd chn <a class=quiet href="#ytoposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_ytoposition_tip)">lisp-graph</a>) - snd chn)))) -</pre></td></tr></table> + (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->position</a> 0.5 snd chn <a class=quiet href="#ytoposition">lisp-graph</a>) + (<a class=quiet href="#ytoposition">y->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> + -For a fancy example, see <a href="sndscm.html#displaybarkfft">display-bark-fft</a> in dsp.scm. -</td></tr><tr><td colspan=3 height=16></td></tr> <!-- listener-click-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="listenerclickhook">listener-click-hook</a> (textpos)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when a click occurs in the listener; the 'textpos' argument is the position in the text +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> + <!-- mark-click-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="markclickhook">mark-click-hook</a> (mark)</code> [<b>progn</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called when a mark is clicked; return #t to squelch the default minibuffer mark identification. The following -hook function is used in <a href="sndscm.html#withmarkedsound">with-marked-sound</a> in ws.scm to display arbitrary info about a mark. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>mark-click-hook</em> - (lambda (n) - (if (not (defined? 'mark-properties)) (load "marks.scm")) - (<a class=quiet href="#infodialog" onmouseout="UnTip()" onmouseover="Tip(extsnd_infodialog_tip)">info-dialog</a> "Mark Help" - (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "Mark ~A~A:~% sample: ~D = ~,3F secs~A~A" - n - (let ((name (<a class=quiet href="#markname" onmouseout="UnTip()" onmouseover="Tip(extsnd_markname_tip)">mark-name</a> n))) - (if (> (string-length name) 0) - (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f " (~S)" name) - "")) - (<a class=quiet href="#marksample" onmouseout="UnTip()" onmouseover="Tip(extsnd_marksample_tip)">mark-sample</a> n) - (/ (<a class=quiet href="#marksample" onmouseout="UnTip()" onmouseover="Tip(extsnd_marksample_tip)">mark-sample</a> n) (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a> (car (<a class=quiet href="#markhome" onmouseout="UnTip()" onmouseover="Tip(extsnd_markhome_tip)">mark-home</a> n)))) - (if (not (= (<a class=quiet href="#marksync" onmouseout="UnTip()" onmouseover="Tip(extsnd_marksync_tip)">mark-sync</a> n) 0)) - (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "~% sync: ~A" (<a class=quiet href="#marksync" onmouseout="UnTip()" onmouseover="Tip(extsnd_marksync_tip)">mark-sync</a> n)) - "") - (let ((props (<a class=quiet href="#markproperties" onmouseout="UnTip()" onmouseover="Tip(sndscm_markproperties_tip)">mark-properties</a> n))) - (if (and (list? props) - (not (null? props))) - (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "~% properties: '~A" props) - "")))) - #t)) -</pre></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> + (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 (> (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 (not (= (<a class=quiet href="#marksync">mark-sync</a> n) 0)) + (<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="markdraghook">mark-drag-hook</a> (mark)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when a mark is dragged. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define (report-mark-location id) - ;; print current mark location in minibuffer - (let ((samp (<a class=quiet href="#marksample" onmouseout="UnTip()" onmouseover="Tip(extsnd_marksample_tip)">mark-sample</a> id)) - (sndchn (<a class=quiet href="#markhome" onmouseout="UnTip()" onmouseover="Tip(extsnd_markhome_tip)">mark-home</a> id))) - (<a class=quiet href="#reportinminibuffer" onmouseout="UnTip()" onmouseover="Tip(extsnd_reportinminibuffer_tip)">report-in-minibuffer</a> - (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "mark ~A: sample: ~D (~,3F) ~A[~D]: ~,3F" + ;; 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 - (/ samp (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a> (car sndchn))) - (<a class=quiet href="#shortfilename" onmouseout="UnTip()" onmouseover="Tip(extsnd_shortfilename_tip)">short-file-name</a> (car sndchn)) + (exact->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" onmouseout="UnTip()" onmouseover="Tip(extsnd_sample_tip)">sample</a> samp (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> -(hook-push <em class=red>mark-drag-hook</em> report-mark-location) -</pre></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> <!-- mark-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="markhook">mark-hook</a> (mark snd chn reason)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when a mark is added, deleted, or moved (but not while moving). +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define (<A NAME="snpmark">snap-mark-to-beat</a>) +<pre class="indented"> +(define (snap-mark-to-beat) ;; when a mark is dragged, its end position is always on a beat - (let ((mark-release 4)) - (hook-push <em class=red>mark-hook</em> - (lambda (mrk snd chn reason) - (if (= reason mark-release) - (let* ((samp (<a class=quiet href="#marksample" onmouseout="UnTip()" onmouseover="Tip(extsnd_marksample_tip)">mark-sample</a> mrk)) - (bps (/ (<a class=quiet href="#beatsperminute" onmouseout="UnTip()" onmouseover="Tip(extsnd_beatsperminute_tip)">beats-per-minute</a> snd chn) 60.0)) - (sr (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a> snd)) - (beat (floor (/ (* samp bps) sr))) - (lower (floor (/ (* beat sr) bps))) - (higher (floor (/ (* (+ 1 beat) sr) bps)))) - (set! (<a class=quiet href="#marksample" onmouseout="UnTip()" onmouseover="Tip(extsnd_marksample_tip)">mark-sample</a> mrk) - (if (< (- samp lower) (- higher samp)) - lower - higher)))))))) -</pre></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> + (hook-push <em class=red>mark-hook</em> + (lambda (hook) + ((lambda (mrk snd chn reason) + (let ((mark-release 4)) + (if (= reason mark-release) + (let* ((samp (<a class=quiet href="#marksample">mark-sample</a> mrk)) + (bps (/ (<a class=quiet href="#beatsperminute">beats-per-minute</a> snd chn) 60.0)) + (sr (<a class=quiet href="#srate">srate</a> snd)) + (beat (floor (/ (* samp bps) sr))) + (lower (floor (/ (* beat sr) bps))) + (higher (floor (/ (* (+ 1 beat) sr) bps)))) + (set! (<a class=quiet href="#marksample">mark-sample</a> mrk) (if (< (- samp lower) (- higher samp)) lower higher)))))) + (hook 'id) (hook 'snd) (hook 'chn) (hook 'reason))))) +</pre> +<div class="spacer"></div> <!-- mix-click-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="mixclickhook">mix-click-hook</a> (mix)</code> [<b>progn</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called when a mix tag is clicked; return #t to omit the default action which is to start the Mix dialog +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>mix-click-hook</em> - (lambda (n) - (set! (<a class=quiet href="#mixamp" onmouseout="UnTip()" onmouseover="Tip(extsnd_mixamp_tip)">mix-amp</a> n) 0.0) - #t)) -</pre></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> + (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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="mixdraghook">mix-drag-hook</a> (mix x y)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when a mix is dragged. +<pre class="indented"> +<em class=def id="mixdraghook">mix-drag-hook</em> (id x y) +</pre> -<table border=0 cellpadding=5 vspace=10><tr><td><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 (n x y) - (<a class=quiet href="#reportinminibuffer" onmouseout="UnTip()" onmouseover="Tip(extsnd_reportinminibuffer_tip)">report-in-minibuffer</a> - (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "mix ~A at ~D: ~,3F" - n (<a class=quiet href="#mixposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_mixposition_tip)">mix-position</a> n) - (exact->inexact (/ (<a class=quiet href="#mixposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_mixposition_tip)">mix-position</a> n) (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a>))))))) -</pre></td></tr></table> - -A neat example is to set up an empty sound with a 1.0 in sample 0, mix in a vct containing one element of 0.5, then set + (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->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: -<pre> - (hook-push mix-drag-hook (lambda (id x y) (<a class=quiet href="#updatetransformgraph" onmouseout="UnTip()" onmouseover="Tip(extsnd_updatetransformgraph_tip)">update-transform-graph</a>))) +</p> + +<pre class="indented"> +(hook-push mix-drag-hook + (lambda (hook) + (<a class=quiet href="#updatetransformgraph">update-transform-graph</a>))) </pre> -and turn on the FFT graph. As you drag the mix, you can see the spectral effect of that + +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> + <!-- mix-release-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="mixreleasehook">mix-release-hook</a> (mix samps)</code> [<b>progn</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called after a mix has been dragged by the mouse to a new position. -'samps' is the number of samples moved during the drag. If its function returns #t, the final position +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> + <!-- mouse-click-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="mouseclickhook">mouse-click-hook</a> (snd chn button state x y axis) </code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -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. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define (click-to-center snd chn button state x y axis) +<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 - (if (= axis <a class=quiet onmouseout="UnTip()" onmouseover="Tip(extsnd_time_graph_tip)">time-graph</a>) - (let ((samp (floor (* (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a> snd) (<a class=quiet href="#positiontox" onmouseout="UnTip()" onmouseover="Tip(extsnd_positiontox_tip)">position->x</a> x snd chn))))) - (set! (<a class=quiet href="#cursor" onmouseout="UnTip()" onmouseover="Tip(extsnd_cursor_tip)">cursor</a> snd chn) samp) - (set! (<a class=quiet href="#rightsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_rightsample_tip)">right-sample</a> snd chn) - (- samp (floor (* .5 (- (<a class=quiet href="#leftsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_leftsample_tip)">left-sample</a> snd chn) (<a class=quiet href="#rightsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_rightsample_tip)">right-sample</a> snd chn)))))) - (<a class=quiet href="#updatetimegraph" onmouseout="UnTip()" onmouseover="Tip(extsnd_updatetimegraph_tip)">update-time-graph</a>) - #t) - #f)) -(hook-push <em class=red>mouse-click-hook</em> click-to-center) + (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->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 -> insert selection (hook-push <em class=red>mouse-click-hook</em> - (lambda (snd chn button state x y axis) - (and (= axis <a class=quiet onmouseout="UnTip()" onmouseover="Tip(extsnd_time_graph_tip)">time-graph</a>) (= button 2)))) -</pre></td></tr></table> + (lambda (hook) + (set! (hook 'result) + (and (= (hook 'axis) <a class=quiet>time-graph</a>) + (= (hook 'button) 2))))) +</pre> -The mouse scroll wheel is sometimes reported as buttons 4 and 5; in the next example, +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>mouse-click-hook</em> - (lambda (snd chn button state x y axis) - (if (and (= axis <a class=quiet onmouseout="UnTip()" onmouseover="Tip(extsnd_time_graph_tip)">time-graph</a>) - (or (= button 4) (= button 5))) ; mouse scroll wheel - (let ((midpoint (* 0.5 (apply + (<a class=quiet href="#xbounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_xbounds_tip)">x-bounds</a>)))) - (dur (/ (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a>) (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a>))) - (range (if (= button 4) - (* -0.25 (apply - (<a class=quiet href="#xbounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_xbounds_tip)">x-bounds</a>))) ; zoom in - (abs (apply - (<a class=quiet href="#xbounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_xbounds_tip)">x-bounds</a>)))))) ; zoom out - (set! (<a class=quiet href="#xbounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_xbounds_tip)">x-bounds</a>) (list (max 0.0 (- midpoint range)) - (min dur (+ midpoint range)))))) - #f)) -</pre></td></tr></table> - -Here is a Forth example: - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> + (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: <{ snd chn button state x y axis -- }> axis time-graph = if $" freq: %.3f" '( snd chn #f cursor snd chn spot-freq ) string-format - snd #f report-in-minibuffer + snd #f status-report else #f then ; add-hook! -</pre></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> +</pre> +<div class="spacer"></div> <!-- mouse-drag-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="mousedraghook">mouse-drag-hook</a> (snd chn button state x y)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when the mouse is dragged within the lisp graph (see enved.scm or rtio.scm). -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="mouseentergraphhook">mouse-enter-graph-hook</a> (snd chn)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when the mouse enters a channel's drawing area (graph pane). +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>mouse-enter-graph-hook</em> - (lambda (snd chn) - (<a class=quiet href="#sndprint" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndprint_tip)">snd-print</a> (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "~A[~A]" (<a class=quiet href="#shortfilename" onmouseout="UnTip()" onmouseover="Tip(extsnd_shortfilename_tip)">short-file-name</a> snd) chn)))) -</pre></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> + (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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="mouseenterlabelhook">mouse-enter-label-hook</a> (type position label)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when the mouse enters a file viewer or region label. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>mouse-enter-label-hook</em> - (lambda (type position name) - (if (not (= type 2)) - (<a class=quiet href="#infodialog" onmouseout="UnTip()" onmouseover="Tip(extsnd_infodialog_tip)">info-dialog</a> name (finfo name))))) -</pre></td></tr></table> + (lambda (hook) + (if (not (= (hook 'type) 2)) + (<a class=quiet href="#infodialog">info-dialog</a> (hook 'label) (finfo (hook 'label)))))) +</pre> -See also <a href="sndscm.html#nbdoc">files-popup-info</a> in nb.scm. -</td></tr><tr><td colspan=3 height=16></td></tr> +<p>See also <a href="sndscm.html#nbdoc">files-popup-info</a> in nb.scm. +</p> +<div class="spacer"></div> <!-- mouse-enter-listener-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="mouseenterlistenerhook">mouse-enter-listener-hook</a> (widget)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when the mouse enters the listener pane. This hook, along with the parallel graph 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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>mouse-enter-graph-hook</em> - (lambda (snd chn) - (if (<a class=quiet href="#soundp" onmouseout="UnTip()" onmouseover="Tip(extsnd_soundp_tip)">sound?</a> snd) (<a class=quiet href="#focuswidget" onmouseout="UnTip()" onmouseover="Tip(extsnd_focuswidget_tip)">focus-widget</a> (car (<a class=quiet href="#channelwidgets" onmouseout="UnTip()" onmouseover="Tip(extsnd_channelwidgets_tip)">channel-widgets</a> snd chn)))))) + (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 (widget) - (<a class=quiet href="#focuswidget" onmouseout="UnTip()" onmouseover="Tip(extsnd_focuswidget_tip)">focus-widget</a> widget))) -</pre></td></tr></table> + (lambda (hook) + (<a class=quiet href="#focuswidget">focus-widget</a> (hook 'widget)))) +</pre> +<div class="spacer"></div> -I much prefer this style of operation. -</td></tr><tr><td colspan=3 height=16></td></tr> <!-- mouse-enter-text-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="mouseentertexthook">mouse-enter-text-hook</a> (widget)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when the mouse enters a text widget (this is the third of the pointer focus hooks). +<pre class="indented"> +<em class=def id="mouseentertexthook">mouse-enter-text-hook</em> (widget) +</pre> -<table border=0 cellpadding=5 vspace=10><tr><td><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 (w) - (<a class=quiet href="#focuswidget" onmouseout="UnTip()" onmouseover="Tip(extsnd_focuswidget_tip)">focus-widget</a> w))) -</pre></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> + (lambda (hook) + (<a class=quiet href="#focuswidget">focus-widget</a> (hook 'widget)))) +</pre> +<div class="spacer"></div> <!-- mouse-leave-graph-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="mouseleavegraphhook">mouse-leave-graph-hook</a> (snd chn)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when the mouse leaves a channel's drawing area (graph pane). -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="mouseleavelabelhook">mouse-leave-label-hook</a> (type position name)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when the mouse exits one of the labels covered by <a href="#mouseenterlabelhook">mouse-enter-label-hook</a>. +<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>. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mouse-leave-listener-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="mousleavelistenerhook">mouse-leave-listener-hook</a> (widget)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when the mouse leaves the listener pane. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="mousleavetexthook">mouse-leave-text-hook</a> (widget)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when the mouse leaves a text widget. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="mousepresshook">mouse-press-hook</a> (snd chn button state x y)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called upon a mouse button press within the lisp graph (see enved.scm). The 'x' and 'y' values are +<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->x</a> and <a href="#positiontoy">position->y</a>). -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mus-error-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="muserrorhook">mus-error-hook</a> (error-type error-message)</code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called upon mus-error. -If its functions return #t, Snd ignores the error (it assumes you've handled it via the hook). -This hook is used in <a href="sndscm.html#playsound">play-sound</a> in play.scm to flush an error message -that the Snd ALSA support code generates (or used to generate). +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>mus-error-hook</em> - (lambda (typ msg) - (and (= typ 0) ; it's mus_print, not mus_error - (display msg)))) ; display returns some non-#f result, I assume -</pre></td></tr></table> + (lambda (hook) + (if (= (hook 'type) 0) + (begin + (display (hook 'message)) + (set! (hook 'result) #t))))) +</pre> -To decode the 'error-type' argument, see <a href="#muserrortypetostring">mus-error-type->string</a>. -</td></tr><tr><td colspan=3 height=16></td></tr> +<p>To decode the 'type' argument, see <a href="#muserrortypetostring">mus-error-type->string</a>. +</p> +<div class="spacer"></div> <!-- name-click-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="nameclickhook">name-click-hook</a> (snd)</code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called when the sound name is clicked (in the label in the minibuffer region of the sound's pane). -If the function returns #t, the usual highly informative minibuffer babbling is squelched. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>name-click-hook</em> - (lambda (snd) ; toggle read-only - (set! (<a class=quiet href="#readonly" onmouseout="UnTip()" onmouseover="Tip(extsnd_readonly_tip)">read-only</a> snd) (not (<a class=quiet href="#readonly" onmouseout="UnTip()" onmouseover="Tip(extsnd_readonly_tip)">read-only</a> snd))) - #t)) -</pre></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> + (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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="newsoundhook">new-sound-hook</a> (filename)</code> -</td></tr><tr><td></td><td colspan=2> -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 +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- new-widget-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="newwidgethook">new-widget-hook</a> (widget)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called each time a dialog or a new set of channel or sound widgets is created. +<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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> + <!-- open-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="openhook">open-hook</a> (filename)</code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called before a sound file is opened. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>open-hook</em> - (lambda (filename) - (if (= (<a class=quiet href="#mussoundheadertype" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussoundheadertype_tip)">mus-sound-header-type</a> filename) <a class=quiet href="#headertype" onmouseout="UnTip()" onmouseover="Tip(extsnd_headertype_tip)">mus-raw</a>) - ;; check for "OggS" first word, if found, translate to something Snd can read - (if (call-with-input-file filename - (lambda (fd) - (and (char=? (read-char fd) #\O) - (char=? (read-char fd) #\g) - (char=? (read-char fd) #\g) - (char=? (read-char fd) #\S)))) - (let ((aufile (string-append filename ".au"))) - (if (file-exists? aufile) (delete-file aufile)) - (system (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "ogg123 -d au -f ~A ~A" aufile filename)) - aufile) ; now open-sound will read the new .au file - #f) - #f))) -</pre></td></tr></table> -See also <a href="sndscm.html#openbuffer">open-buffer</a> in examp.scm. -</td></tr><tr><td colspan=3 height=16></td></tr> + (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) + (and (char=? (read-char fd) #\O) + (char=? (read-char fd) #\g) + (char=? (read-char fd) #\g) + (char=? (read-char fd) #\S))))) + (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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="openrawsoundhook">open-raw-sound-hook</a> (filename current-choices)</code> [<b>cascade</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called each time <a href="#opensound">open-sound</a> encounters a headerless file. +<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): -<code>(list chans srate data-format data-location data-length)</code> where trailing elements can +(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). -If there is more than one function on the hook list, functions after the first get the -on-going list result (if any) as the 'current-choices' argument (the empty list is the default). -<pre> - (hook-push <em class=red>open-raw-sound-hook</em> (lambda (file choices) (list 1 44100 <a class=quiet href="#dataformat" onmouseout="UnTip()" onmouseover="Tip(extsnd_dataformat_tip)">mus-lshort</a>))) +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> -Return '() to accept all the current raw header defaults; return #f to fallback on the Raw File Dialog. + +<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 function returns #t, the <a href="#opensound">open-sound</a> returns without opening. -</td></tr><tr><td colspan=3 height=16></td></tr> +If the hook returns #t, <a href="#opensound">open-sound</a> returns without opening the file. +</p> +<div class="spacer"></div> -<!-- optimization-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="optimizationhook">optimization-hook</a> (message)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called each time the optimizer hits something it can't handle; 'message' tries to give some information about the situation. -<pre> - (hook-push <em class=red>optimization-hook</em> (lambda (n) (display (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "~A~%" n)))) + +<!-- orientation-hook --> +<pre class="indented"> +<em class=def id="orientationhook">orientation-hook</em> () </pre> -Normally, if the optimizer fails for some reason, it falls back silently on the Scheme evaluator, so -the code runs slower. This hook gives you a way to find out why the optimizer gave up. -</td></tr><tr><td colspan=3 height=16></td></tr> +<p>This hook is called whenever one of the variables associated with the orientation dialog changes. +</p> +<div class="spacer"></div> -<!-- orientation-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="orientationhook">orientation-hook</a> () </code> [<b>progn</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called whenever one of the variables associated with the orientation dialog changes. -See <a href="sndscm.html#startwaterfall">start-waterfall</a> in snd-gl.scm. -</td></tr><tr><td colspan=3 height=16></td></tr> <!-- output-comment-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="outputcommenthook">output-comment-hook</a> (str)</code> [<b>cascade</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called in the Save-As dialog to set the default output comment value. 'str' is the current sound's comment. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td> -<pre> +<pre class="indented"> (hook-push <em class=red>output-comment-hook</em> - (lambda (str) ; append a time-stamp - (string-append str ": written " (strftime "%a %d-%b-%Y %H:%M %Z" (localtime (current-time)))))) + (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", str, Time.new.localtime.strftime("%d-%b %H:%M %Z")) +;; in Ruby: format("%s: written %s", comment, Time.new.localtime.strftime("%d-%b %H:%M %Z")) </pre> -</td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> - +<div class="spacer"></div> -<!-- output-name-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="outputnamehook">output-name-hook</a> (current-name)</code> [<b>progn</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called in the New File dialog. If it returns a filename, that name is presented in the New File dialog, -making it slightly easier to set default output names. -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(let ((file-ctr -1)) - (hook-push <em class=red>output-name-hook</em> - (lambda (ignored-name) - (set! file-ctr (+ file-ctr 1)) - (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "~A-~D.snd" ; make new file name based on date and file-ctr: "Jun-01-23.snd" - (strftime "%b-%d" (localtime (current-time))) - file-ctr)))) -</pre></td></tr></table></td></tr> -<tr><td colspan=3 height=16></td></tr> +<!-- 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> -<!-- peak-env-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="peakenvhook">peak-env-hook</a> (snd chn)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called upon completion of a new peak envelope. -</td></tr><tr><td colspan=3 height=16></td></tr> -<!-- play-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="playhook">play-hook</a> (samps)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called each time a buffer is about to be -filled for the DAC. The buffer size is 'samps'. -See <a href="sndscm.html#enveddoc">enved.scm</a> and <a href="sndscm.html#marksdoc">marks.scm</a>. -</td></tr><tr><td colspan=3 height=16></td></tr> - - -<!-- print-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="printhook">print-hook</a> (text)</code> [<b>progn</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called each time some Snd-generated response ('text') is about to be appended to the listener. -If the function returns some non-#f result, Snd assumes you've sent the text out yourself, as well as any needed prompt. -The prompt is important! Snd uses it to find the current form to evaluate, so if your print hook function -forgets to include it, you can end up with a comatose listener. To get out of this state, include -the prompt by hand (i.e. type in the shell that Snd started in, ">(reset-hook! print-hook)"). -This is intended to make it possible to -distinguish Snd responses from user-typing, or add arbitrarily fancy prompts, but both should be handled -in some other way — I should rewrite this part of Snd. - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(hook-push <em class=red>print-hook</em> - (lambda (msg) - (if (char=? (string-ref msg 0) #\newline) - (<a class=quiet href="#sndprint" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndprint_tip)">snd-print</a> msg) - (<a class=quiet href="#sndprint" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndprint_tip)">snd-print</a> (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "~A~%[~A]~%~A" ;need newline just before listener-prompt - msg - (strftime "%d-%b %H:%M %Z" (localtime (current-time))) - (<a class=quiet href="#listenerprompt" onmouseout="UnTip()" onmouseover="Tip(extsnd_listenerprompt_tip)">listener-prompt</a>)))))) -</pre></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> +<!-- 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> -<!-- read-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="readhook">read-hook</a> (text)</code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called each time a line is typed into the listener (it is triggered by the carriage return). -</td></tr><tr><td></td><td colspan=2></td></tr> <!-- save-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="savehook">save-hook</a> (snd name)</code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called each time a sound ('snd') is about to be saved. -If its function returns #t, the file is not saved. 'name' is #f unless +<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>. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> + <!-- save-state-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="savestatehook">save-state-hook</a> (temp-filename)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called each time the <a href="#savestate">save-state</a> +<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. -'temp-filename' is the temporary file name that will be used unless +'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. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> + <!-- select-channel-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="selectchannelhook">select-channel-hook</a> (snd chn)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when a channel is selected (after the sound has been selected). +<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. -select-channel-hook is used in <a href="sndscm.html#playbetweenmarks">play-between-marks</a> -to keep the loop bounds up-to-date. -</td></tr><tr><td colspan=3 height=16></td></tr> +</p> +<div class="spacer"></div> + <!-- select-sound-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="selectsoundhook">select-sound-hook</a> (snd)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when a sound is selected. The argument is the about-to-be-selected sound. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="snderrorhook">snd-error-hook</a> (error-message)</code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -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. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>snd-error-hook</em> - (lambda (msg) - (<a class=quiet href="#play" onmouseout="UnTip()" onmouseover="Tip(extsnd_play_tip)">play</a> "bong.snd") ; or if xm is loaded, (XBell (XtDisplay (cadr (<a class=quiet href="#mainwidgets" onmouseout="UnTip()" onmouseover="Tip(extsnd_mainwidgets_tip)">main-widgets</a>))) 10) - #f)) -</pre></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> + (lambda (hook) + (<a class=quiet href="#play">play</a> "bong.snd"))) +</pre> +<div class="spacer"></div> + <!-- snd-warning-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="sndwarninghook">snd-warning-hook</a> (warning-message)</code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called upon <a href="#sndwarning">snd-warning</a>. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define without-warnings (lambda (thunk) - (define no-warning (lambda (msg) #t)) + (define 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></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> - - -<!-- start-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="starthook">start-hook</a> (filename)</code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called when Snd starts. -If its function returns #t, Snd exits immediately. -Say we are so annoyed with Snd's really very fine file browser that we want -Snd to exit back to the shell if its file argument is not -found (this code has to be in the ~/.snd init file): - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(hook-push <em class=red>start-hook</em> - (lambda (file) - (if (not (file-exists? file)) - (begin - (display file) (display " does not exist") - #t)))) -</pre></td></tr></table></td></tr><tr><td colspan=3 height=16></td></tr> +</pre> +<div class="spacer"></div> <!-- start-playing-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="startplayinghook">start-playing-hook</a> (snd)</code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called when a sound is about to be played. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>start-playing-hook</em> - (lambda (snd) - (if (and (<a class=quiet href="#selectionok" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectionok_tip)">selection?</a>) - (<a class=quiet href="#selectionmember" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectionmember_tip)">selection-member?</a> snd)) + (lambda (hook) + (if (and (<a class=quiet href="#selectionok">selection?</a>) + (<a class=quiet href="#selectionmember">selection-member?</a> (hook 'snd))) (begin (play (selection)) - #t) ; there's a selection so don't play the entire sound - #f))) ; no selection, so go ahead and play it all -</pre></td></tr></table> + (set! (hook 'result) #t))))) ; there's a selection so don't play the entire sound +</pre> +<div class="spacer"></div> -See also <a href="sndscm.html#reportmarknames">report-mark-names</a> in marks.scm. -</td></tr><tr><td colspan=3 height=16></td></tr> <!-- start-playing-selection-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="startplayingselectionhook">start-playing-selection-hook</a> ()</code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called when the selection is about to be played. -If its function returns #t, Snd does not play the selection. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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-dac-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="stopdachook">stop-dac-hook</a> ()</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when Snd stops playing and turns off the DAC, normally upon <a href="#musaudioclose">mus-audio-close</a>. -It is used by <a href="sndscm.html#withlevelmeters">with-level-meters</a> to start draining away the red bubble in the VU meter. -</td></tr><tr><td colspan=3 height=16></td></tr> <!-- stop-playing-hook --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="stopplayinghook">stop-playing-hook</a> (snd)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called when a sound finishes playing. stop-playing-hook may be called more often than start-playing-hook. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="stopplayingselectionhook">stop-playing-selection-hook</a> ()</code> [<b>progn</b>] -</td></tr><tr><td></td><td colspan=2> -This hook is called when the selection finishes playing. -</td></tr><tr><td colspan=3 height=16></td></tr> +<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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="updatehook">update-hook</a> (snd)</code> [<b>or</b>] -</td></tr><tr><td></td><td colspan=2> -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 +<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 its function returns #t, the update is cancelled (this is not +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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>update-hook</em> - (lambda (snd-about-to-be-updated) - ;; this function called just before update - (lambda (updated-snd) - ;; this code executed when update is complete - (<a class=quiet href="#sndprint" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndprint_tip)">snd-print</a> "ok!")))) -</pre></td></tr></table> + (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> -I use update-hook to make sure the y axis bounds reflect the new maxamp, if it is greater than 1.0: +<p>I use update-hook to make sure the y axis bounds reflect the new maxamp, if it is greater than 1.0: +</p> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (hook-push <em class=red>update-hook</em> - (lambda (old-snd) - (lambda (snd) - (do ((i 0 (+ 1 i))) - ((= i (<a class=quiet href="#chans" onmouseout="UnTip()" onmouseover="Tip(extsnd_chans_tip)">channels</a> snd))) - (let ((mx (<a class=quiet href="#maxamp" onmouseout="UnTip()" onmouseover="Tip(extsnd_maxamp_tip)">maxamp</a> snd i))) - (if (> mx 1.0) - (set! (<a class=quiet href="#ybounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_ybounds_tip)">y-bounds</a> snd i) (list (- mx) mx)) - (if (and (> (cadr (<a class=quiet href="#ybounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_ybounds_tip)">y-bounds</a> snd)) 1.0) ; previous (pre-update) version was > 1.0 - (<= mx 1.0)) ; but current is not, so reset axes - (set! (<a class=quiet href="#ybounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_ybounds_tip)">y-bounds</a> snd i) (list -1.0 1.0))))))))) -</pre></td></tr></table> - -Say we're editing a sound in several different windows, and want to save and re-apply any -edits we may have in the other windows when we save the sound from one window (all the others -then get the exploding bomb icon because their underlying data has changed): - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(let ((eds #f)) - (hook-push <em class=red>update-hook</em> - (lambda (cursnd) ; called before actual update -- save our edits - (set! eds (<a href="#editlisttofunction">edit-list->function</a> cursnd 0)) - (lambda (newsnd) ; called after update -- reapply our edits - (if eds (eds newsnd 0)))))) -</pre></td></tr></table> - -Actually this only works if there are just two windows on the same (mono) sound. I suppose for -trickier cases, we could set up an association list with the old sound ("cursnd" above) and its edits, -but it's probably better to bind some keystroke to a function that performs the same operations. -</td></tr><tr><td colspan=3 height=16></td></tr> + (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 (> mx 1.0) + (set! (<a class=quiet href="#ybounds">y-bounds</a> snd i) (list (- mx) mx)) + (if (and (> (cadr (<a class=quiet href="#ybounds">y-bounds</a> old-snd)) 1.0) ; previous (pre-update) version was > 1.0 + (<= 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 --> -<tr><td colspan=3 bgcolor="#f2f4ff"> -<code><a class=def name="viewfilesselecthook">view-files-select-hook</a> (dialog filename)</code> -</td></tr><tr><td></td><td colspan=2> -This hook is called each time a file is selected in a View Files dialog's files list. -</td></tr><tr><td colspan=3 height=16></td></tr> +<pre class="indented"> +<em class=def id="viewfilesselecthook">view-files-select-hook</em> (dialog name) [Motif only] +</pre> -</table> -<br><br> +<p>This hook is called each time a file is selected in a View Files dialog's files list. +</p> +<div class="spacer"></div> -<table width="50%" border=0><tr><td bgcolor="#EEFDEE" valign="middle"><h4>Channel-specific hooks:</h4></td></tr></table> -<pre> - <a class=def name="edithook">edit-hook</a> (snd chn) - <a class=def name="undohook">undo-hook</a> (snd chn) - <a class=def name="afteredithook">after-edit-hook</a> (snd chn) +<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> -<table border=0><tr><td width=30><br></td><td> -These are functions that return the hooks in question associated with the specified channel. -The functions on these hooks are thunks — they should take no arguments. +<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 — 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, -</td></tr></table> -<pre> - Scheme: (hook-push (edit-hook snd chn) (lambda () #t)) - Ruby: edit_hook(snd, chn).add_hook!(\"stop-edit\") do | | true end - Forth: snd chn edit-hook lambda: <{ }> #t ; add-hook! +</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: <{ }> #t ; add-hook! </pre> -<table border=0><tr><td width=30><br></td><td> -halts any attempt to edit the data; this is even more restrictive than setting the read-only + +<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 @@ -2950,43 +3237,42 @@ 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> -<table border=0 cellpadding=5 hspace=20 vspace=10><tr><td><pre> +<pre class="indented"> (define* (protect snd chn) - "(protect snd chn) disallows any edits before the current one" - (let* ((edit-pos (<a class=quiet href="#editposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_editposition_tip)">edit-position</a> snd chn)) - (hook (<em class=red>edit-hook</em> snd chn))) - (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_reset_hook_tip)">reset-hook!</a> hook) - (hook-push hook - (lambda () - (let ((val (< (<a class=quiet href="#editposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_editposition_tip)">edit-position</a> snd chn) edit-pos))) - (if val (<a class=quiet href="#reportinminibuffer" onmouseout="UnTip()" onmouseover="Tip(extsnd_reportinminibuffer_tip)">report-in-minibuffer</a> "protected")) - val))))) + (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 (< (<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) - "(unprotect snd chn) allows edits at any edit history position" - (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_reset_hook_tip)">reset-hook!</a> (<em class=red>edit-hook</em> snd chn))) -</pre></td></tr></table> + (set! (hook-functions (<em class=red>edit-hook</em> snd chn)) ())) +</pre> -<a href="sndscm.html#enveddoc">enved.scm</a> uses several of these hooks to implement an envelope editor in lisp. +<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. <small>It is possible for after-edit-hook to be called more often that edit-hook, or +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.</small> +Snd may check edit-hook ahead of time to avoid unnecessary work. +</p> + -</td></tr></table> -<br><br> -<table width="80%" border=0><tr><td bgcolor="lightsteelblue" valign="middle"><h3><A NAME="sndobjects">Snd's objects</a></h3></td></tr></table> +<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 frame-readers (a "frame" is a multichannel sample), -channel-at-a-time blocks (vcts, map-channel, etc), multichannel blocks (sound-data objects, map-sound, etc), +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. @@ -3009,15 +3295,13 @@ thing. If you want to refer to the currently selected sound explicitly, use <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" onmouseout="UnTip()" onmouseover="Tip(extsnd_expandcontrol_tip)">expand-control</a> #t)</code> returns a list of the current +<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_transformgraphp_tip)">transform-graph?</a> #t #t) #t)</code> +<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>In the function documentation here, optional arguments are brown, and optional keyword arguments are preceded by a colon. -</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 @@ -3026,13 +3310,14 @@ all the region-related functions can return 'no-such-region; all selection-orien can return 'no-active-selection. To reduce clutter, I'll omit mention of these below. </p> -<br> + <!-- INDEX samplers:samplers --> -<!-- ---------------------------------------- SAMPLERS ---------------------------------------- --> +<!-- SAMPLERS --> + +<div class="header" id="samplers">Samplers</div> -<table width="50%" border=0><tr><td bgcolor="lightgreen" valign="middle"><h3><A NAME="samplers">Samplers</a></h3></td></tr></table> <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 @@ -3042,1604 +3327,1475 @@ 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 (<a class=quiet href="#channeltovct" onmouseout="UnTip()" onmouseover="Tip(extsnd_channeltovct_tip)">channel->vct</a>), and the other involves the +data around explicitly (channel->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" (Gtk+). -The buffer approach (<a class=quiet href="#channeltovct" onmouseout="UnTip()" onmouseover="Tip(extsnd_channeltovct_tip)">channel->vct</a> in <a href="grfsnd.html#expsrc">expsrc</a>) +The buffer approach (channel->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" onmouseout="UnTip()" onmouseover="Tip(extsnd_makesampler_tip)">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" onmouseout="UnTip()" onmouseover="Tip(extsnd_readsample_tip)">read-sample</a> (which remembers the -read direction passed to <a class=quiet href="#makesampler" onmouseout="UnTip()" onmouseover="Tip(extsnd_makesampler_tip)">make-sampler</a>), -or <a class=quiet href="#nextsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_nextsample_tip)">next-sample</a> (read forward) and -<a class=quiet href="#previoussample" onmouseout="UnTip()" onmouseover="Tip(extsnd_previoussample_tip)">previous-sample</a> (read backward); -when done, you can close the reader with <a class=quiet href="#freesampler" onmouseout="UnTip()" onmouseover="Tip(extsnd_freesampler_tip)">free-sampler</a>, +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" onmouseout="UnTip()" onmouseover="Tip(extsnd_makemixsampler_tip)">make-mix-sampler</a> returns a mix reader for the desired mix, -<a class=quiet href="#mixsamplerQ" onmouseout="UnTip()" onmouseover="Tip(extsnd_mixsamplerQ_tip)">mix-sampler?</a> returns #t if its argument in a mix sampler, -and <a class=quiet href="#readmixsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_readmixsample_tip)">read-mix-sample</a> returns the next sample (before it is mixed into +<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> -<p>Multichannel iterations can be handled via <a href="sndscm.html#framereaders">frame-readers</a>. These are currently -implemented in frame.scm. -</p> - -<!-- -------------------------------- SAMPLER TABLE -------------------------------- --> +<!-- SAMPLER TABLE --> +<div class="spacer"></div> -<table border=0 cellspacing=4 cellpadding=6 hspace=10> <!-- copy-sampler --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="copysampler">copy-sampler</a> obj</code> -</td></tr><tr><td width=30><br></td><td> -copy-sampler returns a copy of 'obj' which can be any kind of sampler. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="freesampler">free-sampler</a> obj</code> -</td></tr><tr><td></td><td> -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 in an optimized (run-based) loop that -doesn't trigger garbage collection, freeing the samplers explicitly can reduce +after you've freed it!). If you're using zillions of samplers, sometimes freeing the samplers explicitly can reduce demands on memory. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- make-mix-sampler --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="makemixsampler">make-mix-sampler</a> mix <em class=narg>(beg 0)</em></code> -</td></tr><tr><td></td><td> -make-mix-sampler creates a mix-sampler reading 'mix' starting (in the mix input) at 'beg'. -See <a href="sndscm.html#mixtovct">mix->vct</a> in mix.scm. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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#mixtovct">mix->float-vector</a> in mix.scm. +</p> +<div class="spacer"></div> <!-- make-region-sampler --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="makeregionsampler">make-region-sampler</a> start <em class=narg>reg chn (dir 1)</em></code> -</td></tr><tr><td></td><td> -make-region-sampler creates a sampler reading channel 'chn' of the region 'reg' starting +<pre class="indented"> +<em class=def id="makeregionsampler">make-region-sampler</em> start reg 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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- make-sampler --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="makesampler">make-sampler</a> <em class=narg>start snd chn dir edpos</em></code> -</td></tr><tr><td></td><td> -make-sampler creates a sampler reading the given channel +<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. -<pre> - :<em class=typing>(open-sound "oboe.snd")</em> - <em class=listener>#<sound 0></em> - :<em class=typing>(define reader (make-sampler 1000))</em> - <em class=listener>reader</em> - :<em class=typing>reader</em> - <em class=listener>#<sampler: oboe.snd[0: 0] from 1000, at 1000, forward></em> - :<em class=typing>(read-sample reader)</em> - <em class=listener>0.0328369140625</em> - :<em class=typing>(sample 1000)</em> - <em class=listener>0.0328369140625</em> - :<em class=typing>(next-sample reader)</em> - <em class=listener>0.0347900390625</em> - :<em class=typing>(sample 1001)</em> - <em class=listener>0.0347900390625</em> - :<em class=typing>(sampler-home reader)</em> - <em class=listener>(#<sound 0> 0)</em> - :<em class=typing>(sampler-position reader)</em> - <em class=listener>1002</em> -</pre> -One use of 'edpos' is to get the difference +</p> + +<pre class="indented"> +> (open-sound "oboe.snd") +#<sound 0> +> (define reader (make-sampler 1000)) +reader +> reader +#<sampler: oboe.snd[0: 0] from 1000, at 1000, forward> +> (read-sample reader) +0.0328369140625 +> (sample 1000) +0.0328369140625 +> (next-sample reader) +0.0347900390625 +> (sample 1001) +0.0347900390625 +> (sampler-home reader) +(#<sound 0> 0) +> (sampler-position reader) +1002 +</pre> + +<p>One use of 'edpos' is to get the difference between two edits: +</p> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define snd-diff (lambda () ;assume mono, get diff between current state and previous - (let* ((index (<a class=quiet href="#selectedsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>)) - (edit-pos (<a class=quiet href="#editposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_editposition_tip)">edit-position</a> index)) + (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_readsample_tip)">read-sample</a> previous-edit)) #f)))) + (- x (<a class=quiet href="#readsample">read-sample</a> previous-edit)) #f)))) -(<a class=quiet href="#mapchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_mapchannel_tip)">map-channel</a> (snd-diff)) -</pre></td></tr></table> +(<a class=quiet href="#mapchannel">map-channel</a> (snd-diff)) +</pre> -Once the reader has been set up to read at a given edit position, subsequent +<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. -<br><br> -'snd' can be a filename (a string); in this way a sampler +</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. -<pre> - (define reader (make-sampler 100 "oboe.snd")) +</p> + +<pre class="indented"> +(define reader (make-sampler 100 "oboe.snd")) </pre> -'snd' also can be a mix or region. + +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mix-sampler? --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixsamplerQ">mix-sampler?</a> obj</code> -</td></tr><tr><td></td><td> -mix-sampler? returns #t if 'obj' is a mix-sampler. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="nextsample">next-sample</a> obj</code> -</td></tr><tr><td></td><td> -next-sample returns the next sample (reading forward) read by the sampler 'obj'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="previoussample">previous-sample</a> obj</code> -</td></tr><tr><td></td><td> -previous-sample returns the previous sample in the stream read by the sampler 'obj'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="readmixsample">read-mix-sample</a> obj</code> -</td></tr><tr><td></td><td> -read-mix-sample returns the next sample read by the mix-sampler 'obj'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="readregionsample">read-region-sample</a> obj</code> -</td></tr><tr><td></td><td> -read-region-sample returns the next sample read by the region-sampler 'obj'. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define* (region->vct reg (chn 0)) - (if (<a class=quiet href="#regionok" onmouseout="UnTip()" onmouseover="Tip(extsnd_regionok_tip)">region?</a> reg) +<pre class="indented"> +(define* (region->float-vector reg (chn 0)) + (if (<a class=quiet href="#regionok">region?</a> reg) (if (< chn (channels reg)) (let* ((reader (<em class=red>make-region-sampler</em> 0 reg chn)) - (len (<a class=quiet href="#regionframes" onmouseout="UnTip()" onmouseover="Tip(extsnd_regionframes_tip)">region-frames</a> reg)) - (data (<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> len))) - (do ((i 0 (+ 1 i))) + (len (<a class=quiet href="#regionframples">region-framples</a> reg)) + (data (make-float-vector len 0.0))) + (do ((i 0 (+ i 1))) ((= i len) data) (set! (data i) (<em class=red>reader</em>)))) - (throw 'no-such-channel (list "region->vct" reg chn))) - (throw 'no-such-region (list "region->vct" reg)))) -</pre></td></tr></table> - -</td></tr><tr><td colspan=2 height=16></td></tr> + (error 'no-such-channel (list "region->float-vector" reg chn))) + (error 'no-such-region (list "region->float-vector" reg)))) +</pre> +<div class="spacer"></div> <!-- read-sample --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="readsample">read-sample</a> obj</code> -</td></tr><tr><td></td><td> -read-sample returns the next sample read by the sampler 'obj', -reading in the direction set by <a class=quiet href="#makesampler" onmouseout="UnTip()" onmouseover="Tip(extsnd_makesampler_tip)">make-sampler</a>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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? --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="regionsamplerQ">region-sampler?</a> obj</code> -</td></tr><tr><td></td><td> -region-sampler? returns #t if 'obj' is a region sampler. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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? --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="sampleratendQ">sampler-at-end?</a> obj</code> -</td></tr><tr><td></td><td> -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), +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- sampler-home --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="samplerhome">sampler-home</a> obj</code> -</td></tr><tr><td></td><td> -sampler-home returns information describing the source of the data the sampler 'obj' is reading. +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- sampler-position --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="samplerposition">sampler-position</a> obj</code> -</td></tr><tr><td></td><td> -sampler-position returns the +<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). -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- sampler? --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="samplerQ">sampler?</a> obj</code> -</td></tr><tr><td></td><td> -sampler? returns #t if 'obj' is a sampler. -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="samplerQ">sampler?</em> obj +</pre> -</table> +<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_readsample_tip)">read-sample</a> reader)</code>. + +<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> -<br> -<table width="35%" border=0><tr><td bgcolor="#EEFDEE" valign="middle"><h4>Snd->sample</h4></td></tr></table> + + +<div class="innerheader">Snd->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->sample. </p> -<table border=0 cellspacing=4 cellpadding=6 hspace=10> - <!-- make-snd->sample --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="makesndtosample">make-snd->sample</a> <em class=narg>snd</em></code> -</td></tr><tr><td width=30><br></td><td> -make-snd->sample creates a Snd data reader for use with CLM's in-any, file->sample, etc. -</td></tr> -<tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="makesndtosample">make-snd->sample</em> snd +</pre> + +<p>make-snd->sample creates a Snd data reader for use with CLM's in-any, file->sample, etc. +</p> +<div class="spacer"></div> + <!-- snd->sample --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="sndtosample">snd->sample</a> gen frame <em class=narg>chan</em></code> -</td></tr><tr><td><br></td><td> -snd->sample gets the next sample from the data accessed by 'gen', similar to file->sample. +<pre class="indented"> +<em class=def id="sndtosample">snd->sample</em> gen frample chan +</pre> + +<p>snd->sample gets the next sample from the data accessed by 'gen', similar to file->sample. If *reverb* is a snd->sample generator, for example, -<a class=quiet href="sndclm.html#ina" onmouseout="UnTip()" onmouseover="Tip(sndclm_ina_tip)">ina</a> and <a class=quiet href="sndclm.html#filetosample" onmouseout="UnTip()" onmouseover="Tip(sndclm_filetosample_tip)">file->sample</a> actually call snd->sample. -</td></tr><tr><td colspan=2 height=16></td></tr> +<a class=quiet href="sndclm.html#ina">ina</a> and <a class=quiet href="sndclm.html#filetosample">file->sample</a> actually call snd->sample. +</p> +<div class="spacer"></div> <!-- snd->sample? --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="sndtosamplep">snd->sample?</a> obj</code> -</td></tr><tr><td><br></td><td> -snd->sample? returns #t if 'obj' is a snd->sample generator. -</td></tr> +<pre class="indented"> +<em class=def id="sndtosamplep">snd->sample?</em> obj +</pre> + +<p>snd->sample? returns #t if 'obj' is a snd->sample generator. +</p> +<div class="spacer"></div> + -</table> -<br> <!-- INDEX Vcts:Vcts --> -<table width="50%" border=0><tr><td bgcolor="lightgreen" valign="middle"><h3><A NAME="Vcts">Vcts</a></h3></td></tr></table> -<p> -Many of the Snd and CLM functions handle vectors (arrays) of data. -By defining a new vector type, named vct, and providing a package -of old-style array-processing calls upon that type, we can speed up many -operations by a factor of 30 — enough of a difference to warrant -the added complexity. -<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> creates a new vct object. It is freed by the -garbage collector when it can't be referenced any further. To get -an element of a vct, use <a class=quiet href="#vctref" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctref_tip)">vct-ref</a>; similarly <a class=quiet href="#vctset" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctset_tip)">vct-set!</a> -sets an element. (vct's are applicable objects, so vct-ref can always be omitted, and set! can replace vct-set!). -Once created, a vct can be passed to a variety of built-in -functions:</p> - -<table border=0><tr><td> - -<table border=0 cellpadding=5><tr><td><pre> -Scheme: - (define hi (<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> 100)) - (<a class=quiet href="#vctfill" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctfill_tip)">vct-fill!</a> hi 3.14) - (<a class=quiet href="#vctscale" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctscale_tip)">vct-scale!</a> hi -1.0) -</pre></td></tr></table> -</td><td> -<table border=0 cellpadding=5><tr><td bgcolor="Beige"><pre> -Ruby: - hi = make_vct(100) - vct_fill!(hi, 3.14) - vct_scale!(hi, -1.0) -</pre></td></tr></table> -</td><td> +<div class="header" id="Vcts">Vcts or float-vectors</div> -<table border=0 cellpadding=5><tr><td bgcolor="LightGreen"><pre> -Forth: variable hi - 100 0.0 make-vct hi ! - hi @ 3.14 vct-fill! - hi @ -1.0 vct-scale! -</pre></td></tr></table> -</td></tr></table> +<p>These are arrays of floats. In s7, use "float-vector", and in Forth and +Ruby use "vct". +</p> -<p>Now our vct 'hi' has 100 -3.14's. </p> +<!-- VCT TABLE --> -<!-- -------------------------------- VCT TABLE -------------------------------- --> +<div class="spacer"></div> -<table border=0 cellspacing=4 cellpadding=6 hspace=10> <!-- list->vct --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="listtovct">list->vct</a> lst</code> -</td></tr><tr><td width=30></td><td> -return a new vct with elements of list 'lst' (equivalent to the <a href="#vct">vct</a> function). -<pre> - :<em class=typing>(list->vct (list 0.1 0.2 0.3))</em> - <em class=listener>#<vct[len=3]: 0.100 0.200 0.300></em> - :<em class=typing>(vct 0.1 0.2 0.3)</em> - <em class=listener>#<vct[len=3]: 0.100 0.200 0.300></em> +<pre class="indented"> +<em class=def id="listtovct">list->vct</em> lst +<em class=def id="listtofv">list->float-vector</em> lst </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>return a new float-vector with elements of list 'lst' (equivalent to the <a href="#vct">float-vector</a> function). +</p> +<div class="spacer"></div> <!-- make-vct --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="makevct">make-vct</a> len <em class=narg>(initial-element 0.0)</em></code> -</td></tr><tr><td></td><td> -make-vct creates a vct of size 'len'. -<pre> - :<em class=typing>(make-vct 3 0.1)</em> - <em class=listener>#<vct[len=3]: 0.100 0.100 0.100></em> +<pre class="indented"> +<em class=def id="makevct">make-vct</em> len (initial-element 0.0) +<em class=def id="makefv">make-float-vector</em> len (initial-element 0.0) </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> - -<!-- sound-date->vct --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><em class=emdef>sound-data->vct</em> sdobj <em class=narg>(chan 0) (v #f)</em></code> -</td></tr><tr><td></td><td> -sound-data->vct places the sound-data data in a vct, returning 'v' (if given) or a new vct. -</td></tr><tr><td colspan=2 height=16></td></tr> +<p>make-float-vector creates a float-vector of size 'len'. +</p> +<div class="spacer"></div> <!-- vct --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vct">vct</a> :rest args</code> -</td></tr><tr><td></td><td> -vct is equivalent to list->vct with 'args' as the list: <code>(vct 1 2 3)</code> is the same as <code>(<a class=quiet href="#listtovct" onmouseout="UnTip()" onmouseover="Tip(extsnd_listtovct_tip)">list->vct</a> '(1 2 3))</code> -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="vct">vct</em> :rest args +<em class=def id="fv">float-vector</em> :rest args +</pre> + +<p>float-vector is equivalent to list->float-vector with 'args' as the list: <code>(float-vector 0.0 0.1 0.2)</code>. +</p> +<div class="spacer"></div> <!-- vct? --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctp">vct?</a> v</code> -</td></tr><tr><td></td><td> -vct? returns #t if 'v' is a vct. -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="vctp">vct?</em> v +<em class=def id="fvp">float-vector?</em> v +</pre> + +<p>float-vector? returns #t if 'v' is a float-vector. +</p> +<div class="spacer"></div> + + +<!-- vct-abs! --> +<pre class="indented"> +<em class=def id="vctabs">vct-abs!</em> v +<em class=def id="fvabs">float-vector-abs!</em> v +</pre> + +<p>float-vector-abs! replaces each element of 'v' with its absolute value. +</p> +<div class="spacer"></div> <!-- vct-add! --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctadd">vct-add!</a> v1 v2 <em class=narg>(off 0)</em></code> -</td></tr><tr><td></td><td> -vct-add! performs element-wise add: <code>v1[i + off] += v2[i]</code>, returning 'v1'. To protect the -original vct, use vct-copy: <code>(vct-add! (vct-vopy v1) v2)</code>. -<pre> -:<em class=typing>(define v1 (vct .1 .2 .3))</em> -<em class=listener>#<unspecified></em> -:<em class=typing>(vct-add! v1 (vct .3 .2 .1))</em> -<em class=listener>#<vct[len=3]: 0.400 0.400 0.400></em> -:<em class=typing>v1</em> -<em class=listener>#<vct[len=3]: 0.400 0.400 0.400></em> +<pre class="indented"> +<em class=def id="vctadd">vct-add!</em> v1 v2 (off 0) +<em class=def id="fvadd">float-vector-add!</em> v1 v2 (off 0) </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>float-vector-add! performs element-wise add: v1[i + off] += v2[i], returning 'v1'. +</p> +<div class="spacer"></div> <!-- vct-copy --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctcopy">vct-copy</a> v</code> -</td></tr><tr><td></td><td> -vct-copy returns a copy of the vct 'v'. +<pre class="indented"> +<em class=def id="vctcopy">vct-copy</em> v +<em class=def id="fvcopy">float-vector-copy</em> v +</pre> + +<p>float-vector-copy returns a copy of the float-vector 'v'. +</p> <!-- INDEX copying:Copying --> -<A NAME="copying"></a> -<TABLE border=3 bordercolor="tan" hspace=20 vspace=10><tr><td> -<blockquote><small> -<br> +<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 vct: <a href="#vctcopy">vct-copy</a>, <a href="#vcttovector">vct->vector</a>, <a href="sndscm.html#vcttoframe">vct->frame</a><br> -copy mix: <a href="sndscm.html#mixtovct">mix->vct</a><br> +copy mix: <a href="sndscm.html#mixtovct">mix->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="#channeltovct">channel->vct</a>, or <a href="#savesoundas">save-sound-as</a><br> -copy selection data: <a href="#selection2vct">selection->vct</a> or <a href="#saveselection">save-selection</a><br> -copy region data: <a href="#regiontovct">region->vct</a>, <a href="#regiontovct">region->vct</a>, <a href="#saveregion">save-region</a>, or <a href="sndscm.html#regiontosounddata">region->sound-data</a><br> -copy transform data: <a href="#transformtovct">transform->vct</a><br> -copy sound-data: <a href="#sounddatatovct">sound-data->vct</a><br> -copy a frame: <a href="sndscm.html#framecopy">frame-copy</a>, <a href="sndscm.html#frametovct">frame->vct</a><br> -copy vector: <a href="#vectortovct">vector->vct</a><br> -<br> +copy channel data: <a href="#channeltovct">channel->float-vector</a>, or <a href="#savesoundas">save-sound-as</a><br> +copy selection data: <a href="#selection2vct">selection->float-vector</a> or <a href="#saveselection">save-selection</a><br> +copy region data: <a href="#regiontovct">region->float-vector</a>, <a href="#saveregion">save-region</a><br> +copy transform data: <a href="#transformtovct">transform->float-vector</a><br> </small></blockquote> </td></tr></TABLE> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> -<!-- vct-fill! --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctfill">vct-fill!</a> v val</code> -</td></tr><tr><td></td><td> -vct-fill! sets each element of 'v' to 'val': <code>v[i] = val</code>. It returns 'v'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- vct-equal? --> +<pre class="indented"> +<em class=def id="vctequal">vct-equal?</em> v1 v2 diff +<em class=def id="fvequal">float-vector-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]))) > 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> -<!-- vct-length --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctlength">vct-length</a> v</code> -</td></tr><tr><td></td><td> -vct-length returns the length of 'v'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- vct-fill! --> +<pre class="indented"> +<em class=def id="vctfill">vct-fill!</em> v val +<em class=def id="fvfill">float-vector-fill!</em> v val +</pre> -<!-- vct-map! --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctmap">vct-map!</a> v proc</code> -</td></tr><tr><td></td><td> -vct-map! sets each element of 'v' to the value returned by the thunk 'proc': <code>(vct-map! v (lambda () 3.0))</code> -is the same as <code>(<a class=quiet href="#vctfill" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctfill_tip)">vct-fill!</a> v 3.0)</code>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<p>float-vector-fill! sets each element of 'v' to 'val': v[i] = val. It returns 'v'. +</p> +<div class="spacer"></div> -<!-- vct-move! --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctmove">vct-move!</a> v new old <em class=narg>backwards</em></code> -</td></tr><tr><td></td><td> -vct-move moves a block of values within a vct: <code>v[new++] = v[old++]</code>, or -if 'backwards' is #t: <code>v[new--] = v[old--]</code>. It returns 'v'. -<pre> -:<em class=typing>(define v1 (vct 1 2 3 4 5 6 7 8 9 10))</em> -<em class=listener>#<unspecified></em> -:<em class=typing>(vct-move! v1 0 5)</em> -<em class=listener>#<vct[len=10]: 6.000 7.000 8.000 9.000 10.000 6.000 7.000 8.000 9.000 10.000></em> +<!-- vct-length --> +<pre class="indented"> +<em class=def id="vctlength">vct-length</em> v +<em class=def id="fvlength">float-vector-length</em> v </pre> -We can use vct-move! to maintain a sliding window on a sound: - -<pre> - (<a class=quiet href="#mapchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_mapchannel_tip)">map-channel</a> - (let* ((size 100) - (samps (<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> size))) - (lambda (y) - (<em class=red>vct-move!</em> samps 0 1) - (<a class=quiet href="#vctset" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctset_tip)">vct-set!</a> samps (- size 1) y) - ...))) -</pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<p>float-vector-length returns the length of 'v'. +</p> +<div class="spacer"></div> -<!-- vct-multiply! --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctmultiply">vct-multiply!</a> v1 v2</code> -</td></tr><tr><td></td><td> -vct-multiply! performs element-wise multiply of two vcts: <code>v1[i] *= v2[i]</code>. It returns 'v1'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- vct-max --> +<pre class="indented"> +<em class=def id="vctmax">vct-max</em> v +<em class=def id="fvmax">float-vector-max</em> v +</pre> +<p>float-vector-max returns the maximum value of the elements of 'v'. +</p> +<div class="spacer"></div> -<!-- vct-offset! --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctoffset">vct-offset!</a> v val</code> -</td></tr><tr><td></td><td> -vct-offset! adds 'val' to each element of 'v': <code>v[i] += val</code>. It returns 'v'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- vct-min --> +<pre class="indented"> +<em class=def id="vctmin">vct-min</em> v +<em class=def id="fvmin">float-vector-min</em> v +</pre> -<!-- vct-peak --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctpeak">vct-peak</a> v</code> -</td></tr><tr><td></td><td> -vct-peak returns the maximum absolute value of the elements of 'v'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<p>float-vector-min returns the minimum value of the elements of 'v'. +</p> +<div class="spacer"></div> -<!-- vct-ref --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctref">vct-ref</a> v pos</code> -</td></tr><tr><td></td><td> -vct-ref returns the element 'pos' in 'v': <code>v[pos]</code>. -<pre> -:<em class=typing>(vct-ref (vct .1 .2 .3) 1)</em> -<em class=listener>0.200000002980232</em> +<!-- vct-move! --> +<pre class="indented"> +<em class=def id="vctmove">vct-move!</em> v new old backwards +<em class=def id="fvmove">float-vector-move!</em> v new old backwards </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> - -<!-- vct-reverse! --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctreverse">vct-reverse!</a> v <em class=narg>size</em></code> -</td></tr><tr><td></td><td> -vct-reverse! reverses the elements of 'v' (in-place), returning 'v'. -If 'size' is given, the reversal centers around it. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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> -<!-- vct-scale! --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctscale">vct-scale!</a> v scl</code> -</td></tr><tr><td></td><td> -vct-scale! multiplies each element of 'v' by 'scl': <code>v[i] *= scl</code>. It returns 'v'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- vct-multiply! --> +<pre class="indented"> +<em class=def id="vctmultiply">vct-multiply!</em> v1 v2 +<em class=def id="fvmultiply">float-vector-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> -<!-- vct-set! --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctset">vct-set!</a> v pos val</code> -</td></tr><tr><td></td><td> -vct-set! sets the vct 'v' element at 'pos' to 'val': <code>v[pos] = val</code>. -In Scheme, this is the same as <code>(set! (<a class=quiet href="#vctref" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctref_tip)">vct-ref</a> v pos) val)</code>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- vct-offset! --> +<pre class="indented"> +<em class=def id="vctoffset">vct-offset!</em> v val +<em class=def id="fvoffset">float-vector-offset!</em> v val +</pre> -<!-- vct-subtract! --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctsubtract">vct-subtract!</a> v1 v2</code> -</td></tr><tr><td></td><td> -vct-subtract! performs an element-wise subtract: <code>v1[i] -= v2[i]</code>. It returns 'v1'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<p>float-vector-offset! adds 'val' to each element of 'v': v[i] += val. It returns 'v'. +</p> +<div class="spacer"></div> -<!-- vct-subseq --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctsubseq">vct-subseq</a> v start <em class=narg>(end len) nv</em></code> -</td></tr><tr><td></td><td> -vct-subseq returns a new vct (or 'nv' if given) with the elements of 'v' between 'start' and 'end' inclusive. 'end' defaults -to the end of 'v'. -<pre> -:<em class=typing>(define v1 (vct 1 2 3 4 5 6 7 8 9 10))</em> -<em class=listener>#<unspecified></em> -:<em class=typing>(vct-subseq v1 3 6)</em> -<em class=listener>#<vct[len=4]: 4.000 5.000 6.000 7.000></em> +<!-- vct-peak --> +<pre class="indented"> +<em class=def id="vctpeak">vct-peak</em> v +<em class=def id="fvpeak">float-vector-peak</em> v </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> - -<!-- vct+ --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vctplus">vct+</a> obj1 obj2</code> -</td></tr><tr><td></td><td> -vct+ combines <a class=quiet href="#vctadd" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctadd_tip)">vct-add!</a> and <a class=quiet href="#vctoffset" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctoffset_tip)">vct-offset!</a>, -depending on the type of its arguments. -<code>(vct+ v 1.0)</code> or <code>(vct+ 1.0 v)</code> is the same as -<code>(vct-offset! v 1.0)</code>, and <code>(vct+ v1 v2)</code> is the same as <code>(vct-add! v1 v2)</code>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<p>float-vector-peak returns the maximum absolute value of the elements of 'v'. +</p> +<div class="spacer"></div> -<!-- vct* --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vcttimes">vct*</a> obj1 obj2</code> -</td></tr><tr><td></td><td> -vct* combines <a class=quiet href="#vctmultiply" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctmultiply_tip)">vct-multiply!</a> and <a class=quiet href="#vctscale" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctscale_tip)">vct-scale!</a>, -depending on the type of its arguments. -<code>(vct* v 2.0)</code> or <code>(vct* 2.0 v)</code> is the same as <code>(vct-scale! v 2.0)</code>, and -<code>(vct* v1 v2)</code> is the same as <code>(vct-multiply! v1 v2)</code>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- vct-ref --> +<pre class="indented"> +<em class=def id="vctref">vct-ref</em> v pos +<em class=def id="fvref">float-vector-ref</em> v pos +</pre> +<p>float-vector-ref returns the element 'pos' in 'v': v[pos]. +</p> +<div class="spacer"></div> -<!-- vct->channel --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vcttochannel">vct->channel</a> v <em class=narg>(beg 0) dur snd chn edpos origin</em></code> -</td></tr><tr><td></td><td> -vct->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). -Since with-sound can write its output to a vct, we can use it with vct->channel to paste in an fm-violin note as -an edit: -<pre> - (vct->channel (<a class=quiet href="sndscm.html#withsound" onmouseout="UnTip()" onmouseover="Tip(sndscm_wsdoc_tip)">with-sound</a> (:output (make-vct 44100)) (<a class=quiet href="sndscm.html#fmviolin" onmouseout="UnTip()" onmouseover="Tip(sndscm_fmviolin_tip)">fm-violin</a> 0 1 440 .1))) +<!-- vct-reverse! --> +<pre class="indented"> +<em class=def id="vctreverse">vct-reverse!</em> v size +<em class=def id="fvreverse">float-vector-reverse!</em> v size </pre> -To add such a note to whatever is already present, use either <a href="#mixvct">mix-vct</a> or -<a href="sndscm.html#mixsounddata">mix-sound-data</a>. -</td></tr><tr><td colspan=2 height=16></td></tr> - -<!-- vct->list --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vcttolist">vct->list</a> v</code> -</td></tr><tr><td></td><td> -vct->list returns a list with elements of 'v'. -<pre> - ;; Scheme: - :<em class=typing>(vct->list (list->vct (list 0.1 0.2 0.3)))</em> - <em class=listener>(0.100000001490116 0.200000002980232 0.300000011920929)</em> ; (sigh...) +<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> - ;; Ruby: - :<em class=typing>vct2list(list2vct([0.1, 0.2, 0.3]))</em> - <em class=listener>[0.100000001490116, 0.200000002980232, 0.300000011920929]</em> - ;; Forth: - <em class=listener>snd></em> <em class=typing>'( 0.1 0.2 0.3 ) list->vct vct->list</em> - <em class=listener>'( 0.1 0.2 0.3 )</em> +<!-- vct-scale! --> +<pre class="indented"> +<em class=def id="vctscale">vct-scale!</em> v scl +<em class=def id="fvscale">float-vector-scale!</em> v scl </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> - -<!-- vct->sound-data --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><em class=emdef>vct->sound-data</em> v <em class=narg>sd (chan 0)</em></code> -</td></tr><tr><td></td><td> -vct->sound-data places the data in vct 'v' in the sound-data object 'sd', returning sd. -</td></tr><tr><td colspan=2 height=16></td></tr> +<p>float-vector-scale! multiplies each element of 'v' by 'scl': v[i] *= scl. It returns 'v'. +</p> +<div class="spacer"></div> -<!-- vct->string --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vcttostring">vct->string</a> v</code> -</td></tr><tr><td></td> -<td> -vct->string returns a Scheme-readable string describing 'v'. The standard way of displaying a vct -uses "#<vct...>" which is not useful if you want to read the string later as a piece of Scheme code. -<pre> - :<em class=typing>(define v1 (make-vct 3 0.1))</em> - prints v1 as <em class=listener>#<vct[len=3]: 0.100 0.100 0.100></em> - :<em class=typing>(vct->string v1)</em> - <em class=listener>"(vct 0.100 0.100 0.100)"</em> +<!-- vct-set! --> +<pre class="indented"> +<em class=def id="vctset">vct-set!</em> v pos val +<em class=def id="fvset">float-vector-set!</em> v pos val </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<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> -<!-- vct->vector --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vcttovector">vct->vector</a> v</code> -</td></tr><tr><td></td><td> -vct->vector returns a vector with the elements of 'v'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- vct-subtract! --> +<pre class="indented"> +<em class=def id="vctsubtract">vct-subtract!</em> v1 v2 +<em class=def id="fvsubtract">float-vector-subtract!</em> v1 v2 +</pre> -<!-- vector->vct --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vectortovct">vector->vct</a> vect</code> -</td></tr><tr><td></td><td> -vector->vct returns a vct with elements of vector 'vect'. -</td></tr> +<p>float-vector-subtract! performs an element-wise subtract: v1[i] -= v2[i]. It returns 'v1'. +</p> +<div class="spacer"></div> -</table> -<br> -<p>Many of the functions described below can take a vct as an argument; -there are also several functions that create and fill vcts with data:</p> -<pre> - <a href="#regiontovct">region->vct</a> region samples to vct - <a href="#transformtovct">transform->vct</a> fft data to vct - <a href="#channeltovct">channel->vct</a> channel samples to vct - <a href="sndscm.html#mixtovct">mix->vct</a> mix samples to vct - <a href="#sounddatatovct">sound-data->vct</a> sound-data samples to vct - <a href="#vectortovct">vector->vct</a> vector data to vct (assumed to be floats) - <a href="#selection2vct">selection->vct</a> selected samples to vct - <a href="sndscm.html#filetovct">file->vct</a> file data to vct - <a href="sndscm.html#frametovct">frame->vct</a> frame data to vct - <a href="sndscm.html#vcttoframe">vct->frame</a> vct data to frame -</pre> - -<p>We could combine some of these vct functions to implement Horner's rule -(the <a href="sndclm.html#polynomial">polynomial</a> generator) over an entire -channel: -</p> -<table border=0 cellpadding=5 hspace=20><tr><td><pre> -(define (vct-polynomial v coeffs) - (let* ((v-len (<em class=red>length</em> v)) - (num-coeffs (<em class=red>length</em> coeffs)) - (new-v (<em class=red>make-vct</em> v-len (coeffs (- num-coeffs 1))))) - (do ((i (- num-coeffs 2) (- i 1))) - ((< i 0)) - (<em class=red>vct-offset!</em> (<em class=red>vct-multiply!</em> new-v v) (coeffs i))) - new-v)) - -(define* (channel-polynomial coeffs snd chn) - (let ((len (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a> snd chn))) - (<em class=red>vct->channel</em> (vct-polynomial (<em class=red>channel->vct</em> 0 len snd chn) coeffs) 0 len snd chn))) - -;;; (channel-polynomial (<em class=red>vct</em> 0.0 .5)) = x*.5 -;;; (channel-polynomial (<em class=red>vct</em> 0.0 1.0 1.0 1.0)) = x*x*x + x*x + x -</pre></td></tr></table> - -<p>There is one slightly -unusual function in this family: vct-map!. -This is a do-loop (or for-each) over a vct, calling some -function to get the values to assign into the vct. For example</p> -<pre> - (<a class=quiet href="#vctmap" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctmap_tip)">vct-map!</a> out-data (lambda () - (<a class=quiet href="sndclm.html#convolve" onmouseout="UnTip()" onmouseover="Tip(sndclm_convolve_tip)">convolve</a> cnv (lambda (dir) - (<a class=quiet href="#readsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_readsample_tip)">read-sample</a> sf))))) +<!-- vct-subseq --> +<pre class="indented"> +<em class=def id="vctsubseq">vct-subseq</em> v start (end len) nv +<em class=def id="fvsubseq">float-vector-subseq</em> v start (end len) nv </pre> -<p>in the cnvtest function in <a href="sndscm.html#exampdoc">examp.scm</a> is calling the convolve generator and -assigning the result to each successive member of the out-data vct. -</p> -<p>In some cases (s7, Ruby) it's possible to access a vct's -elements with the syntax <code>(v index)</code>, equivalent to <code>(<a class=quiet href="#vctref" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctref_tip)">vct-ref</a> v index)</code>. -In Ruby, vcts partake in the Enumerable and Comparable classes, and have a variety of -additional methods: map, each, <=>, etc. See vct.c and the Ruby documentation for a complete list. +<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> -<pre> - :<em class=typing>v1</em> - <em class=listener>#<vct[len=10]: 0.100 0.100 0.100 3.000 0.100 0.100 0.100 0.100 0.100 0.100></em> - :<em class=typing>v1.find_all {|x| x > 1.0 }</em> - <em class=listener>[3.0, 4.0]</em> - :<em class=typing>v1.max</em> - <em class=listener>4.0</em> - :<em class=typing>v2 = make_vct(10, 0.1)</em> - <em class=listener>#<vct[len=10]: 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100></em> - :<em class=typing>v2 < v1</em> - <em class=listener>true</em> +<div class="spacer"></div> + + +<!-- vct+ --> +<pre class="indented"> +<em class=def id="vctplus">vct+</em> obj1 obj2 +<em class=def id="fvplus">float-vector+</em> obj1 obj2 </pre> -<br><br> +<p>float-vector+ combines float-vector-add! and float-vector-offset!, +depending on the type of its arguments. +</p> +<div class="spacer"></div> -<!-- INDEX sndsounddata:sound-data --> -<table width="50%" border=0><tr><td bgcolor="lightgreen" valign="middle"><h3><A NAME="sndsounddata">Sound-data</a></h3></td></tr></table> +<!-- vct* --> +<pre class="indented"> +<em class=def id="vcttimes">vct*</em> obj1 obj2 +<em class=def id="fvtimes">float-vector*</em> obj1 obj2 +</pre> -<p>Another Snd object containing sound samples is the sound-data object; it can be viewed either as an array of vcts, -each vct representing one channel's data, or as an array of frames, each frame holding a sample from -each channel at that position in the sound. <a href="sndscm.html#framedoc">frame.scm</a> has a number of useful functions that use -sound-data objects. -As with vcts, sound-data objects partake in the Enumerable and Comparable -classes in Ruby. +<p>float-vector* combines float-vector-multiply! and float-vector-scale!, +depending on the type of its arguments. </p> +<div class="spacer"></div> -<!-- -------------------------------- SOUND-DATA TABLE -------------------------------- --> -<table border=0 cellspacing=4 cellpadding=6 hspace=10> - -<!-- make-sound-data --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="makesounddata">make-sound-data</a> chans frames</code> -</td></tr><tr><td width=30><br></td><td> -make-sound-data returns a new sound-data object with 'chans' arrays, each with 'frames' elements. -<pre> - :<em class=typing>(make-sound-data 2 5)</em> - <em class=listener>#<sound-data[chans=2, length=5]: - (0.000 0.000 0.000 0.000 0.000) - (0.000 0.000 0.000 0.000 0.000)></em> +<!-- vct->channel --> +<pre class="indented"> +<em class=def id="vcttochannel">vct->channel</em> v (beg 0) dur snd chn edpos origin +<em class=def id="fvtochannel">float-vector->channel</em> v (beg 0) dur snd chn edpos origin </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>float-vector->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> -<!-- sound-data-add! --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sounddataadd">sound-data-add!</a> sd1 sd2</code> -</td></tr><tr><td><br></td><td> -sound-data-add! adds the contents of sd2 into sd1 and returns sd1. -<pre> - :<em class=typing>(define sd1 (make-sound-data 2 5))</em> - <em class=listener>#<unspecified></em> - :<em class=typing>(do ((chn 0 (+ 1 chn))) ((= chn 2)) - (do ((i 0 (+ 1 i))) ((= i 5)) - (sound-data-set! sd1 chn i (+ i (* 5 chn)))))</em> - <em class=listener>#<unspecified></em> - :<em class=typing>sd1</em> - <em class=listener>#<sound-data[chans=2, length=5]: - (0.000 1.000 2.000 3.000 4.000) - (5.000 6.000 7.000 8.000 9.000)></em> - :<em class=typing>(sound-data-add! (sound-data-fill! (make-sound-data 2 5) .25) sd1)</em> - <em class=listener>#<sound-data[chans=2, length=5]: - (0.250 1.250 2.250 3.250 4.250) - (5.250 6.250 7.250 8.250 9.250)></em> -</pre> -</td></tr><tr><td colspan=2 height=16></td></tr> - - -<!-- sound-data-chans --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="sounddatachans">sound-data-chans</a> sd</code> -</td></tr><tr><td></td><td> -sound-data-chans returns the number of channels in sd. -</td></tr><tr><td colspan=2 height=16></td></tr> - - -<!-- sound-data-copy --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sounddatacopy">sound-data-copy</a> sd</code> -</td></tr><tr><td></td><td> -sound-data-copy returns a copy of the sound-data object sd. -</td></tr><tr><td colspan=2 height=16></td></tr> - - -<!-- sound-data-fill! --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="sounddatafill">sound-data-fill!</a> sd value</code> -</td></tr><tr><td></td><td> -sound-data-fill! sets each element of sound-data object sd to 'value'. -</td></tr><tr><td colspan=2 height=16></td></tr> - - -<!-- sound-data-length --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="sounddatalength">sound-data-length</a> sd</code> -</td></tr><tr><td></td><td> -sound-data-length returns the length (in samples) of each channel in the sound-data-object sd. -</td></tr><tr><td colspan=2 height=16></td></tr> - - -<!-- sound-data-maxamp --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="sounddatamaxamp">sound-data-maxamp</a> sd</code> -</td></tr><tr><td></td><td> -sound-data-maxamp returns a list of maxamps (one for each channel) of the data in sd. -<pre> - :<em class=typing>sd1</em> - <em class=listener>#<sound-data[chans=2, length=5]: - (0.000 1.000 2.000 3.000 4.000) - (5.000 6.000 7.000 8.000 9.000)></em> - :<em class=typing>(sound-data-maxamp sd1)</em> - <em class=listener>(4.0 9.0)</em> - :<em class=typing>(sound-data-peak sd1)</em> - <em class=listener>9.0</em> -</pre> -</td></tr><tr><td colspan=2 height=16></td></tr> - - -<!-- sound-data-multiply! --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sounddatamultiply">sound-data-multiply!</a> sd1 sd2</code> -</td></tr><tr><td></td><td> -sound-data-multiply! multiplies each element of sd2 by the corresponding element of sd2 and returns sd1. -</td></tr><tr><td colspan=2 height=16></td></tr> - - -<!-- sound-data-offset! --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sounddataoffset">sound-data-offset!</a> sd off</code> -</td></tr><tr><td></td><td> -sound-data-offset! adds the number 'off' to each element of sd and returns sd. -</td></tr><tr><td colspan=2 height=16></td></tr> - - -<!-- sound-data-peak --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sounddatapeak">sound-data-peak</a> sd</code> -</td></tr><tr><td></td><td> -sound-data-peak returns the overall maximum element in sd. -</td></tr><tr><td colspan=2 height=16></td></tr> - - -<!-- sound-data-ref --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="sounddataref">sound-data-ref</a> sd chan frame</code> -</td></tr><tr><td></td><td> -sound-data-ref returns (as a float) the sample in channel chan at location frame. In s7 you can omit the "sound-data-ref": -<pre> - <em class=listener>></em><em class=typing>(let ((sd (make-sound-data 1 1))) (sd 0 0))</em> - <em class=listener>0.0</em> +<!-- vct->list --> +<pre class="indented"> +<em class=def id="vcttolist">vct->list</em> v +<em class=def id="fvtolist">float-vector->list</em> v </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<p>float-vector->list returns a list with elements of 'v'. +</p> +<div class="spacer"></div> -<!-- sound-data-reverse! --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sounddatareverse">sound-data-reverse!</a> sd</code> -</td></tr><tr><td></td><td> -sound-data-reverse! reverses the elements of each channel of sd and returns sd. -<pre> - :<em class=typing>sd1</em> - <em class=listener>#<sound-data[chans=2, length=5]: - (0.000 1.000 2.000 3.000 4.000) - (5.000 6.000 7.000 8.000 9.000)></em> - :<em class=typing>(sound-data-reverse! sd1)</em> - <em class=listener>#<sound-data[chans=2, length=5]: - (4.000 3.000 2.000 1.000 0.000) - (9.000 8.000 7.000 6.000 5.000)></em> -</pre> -</td></tr><tr><td colspan=2 height=16></td></tr> - - -<!-- sound-data-scale! --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="sounddatascale">sound-data-scale!</a> sd scaler</code> -</td></tr><tr><td></td><td> -sound-data-scale! multiplies each sample in sd by scaler. -</td></tr><tr><td colspan=2 height=16></td></tr> - - -<!-- sound-data-set! --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="sounddataset">sound-data-set!</a> sd chan frame val</code> -</td></tr><tr><td></td><td> -sound-data-set! sets sd's sample at 'frame' in channel 'chan' to val. -In s7 you can use generalized set: -<pre> - <em class=listener>></em><em class=typing>(let ((sd (make-sound-data 1 1))) (set! (sd 0 0) 1.0) (sd 0 0))</em> - <em class=listener>1.0</em> -</pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- vct->string --> +<pre class="indented"> +<em class=def id="vcttostring">vct->string</em> v +<em class=def id="fvtostring">float-vector->string</em> v +</pre> +<p>float-vector->string returns a string describing 'v'. +</p> +<div class="spacer"></div> -<!-- sound-data+ --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sounddata+">sound-data+</a> val1 val2</code> -</td></tr><tr><td></td><td> -sound-data+ adds val1 to val2 (either or both can be sound-data objects). -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- vct->vector --> +<pre class="indented"> +<em class=def id="vcttovector">vct->vector</em> v +</pre> -<!-- sound-data* --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sounddata*">sound-data*</a> val1 val2</code> -</td></tr><tr><td></td><td> -sound-data* multiplies val1 by val2 (either or both can be sound-data objects). -</td></tr><tr><td colspan=2 height=16></td></tr> +<p>vct->vector returns a vector with the elements of 'v'. +</p> +<div class="spacer"></div> -<!-- sound-data? --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="sounddata?">sound-data?</a> obj</code> -</td></tr><tr><td></td><td> -sound-data? returns #t if obj is a sound-data object. -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- vector->vct --> +<pre class="indented"> +<em class=def id="vectortovct">vector->vct</em> vect +</pre> +<p>vector->vct returns a vct with elements of vector 'vect'. +</p> +<div class="spacer"></div> -<!-- sound-data->sound-data --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="sounddatatosounddata">sound-data->sound-data</a> sd-in sd-out beg dur cycle</code> -</td></tr><tr><td></td><td> -sound-data->sound-data copies sound-data sd-in's -data from 0 for dur frames into sound-data sd-out starting at beg, wrapping around if sd-out's end is reached. -This is an experimental function currently used in the oscilloscope (oscope.scm). -</td></tr><tr><td colspan=2 height=16></td></tr> +<p> +In Ruby, vcts partake in the Enumerable and Comparable classes, and have a variety of +additional methods: map, each, <=>, etc. See vct.c and the Ruby documentation for a complete list. +</p> -<!-- sound-data->vct --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="sounddatatovct">sound-data->vct</a> sd <em class=narg>chan v</em></code> -</td></tr><tr><td></td><td> -sound-data->vct copies sound-data sd's channel 'chan' data into vct v. -<pre> - :<em class=typing>sd1</em> - <em class=listener>#<sound-data[chans=2, length=5]: - (4.000 3.000 2.000 1.000 0.000) - (9.000 8.000 7.000 6.000 5.000)></em> - :<em class=typing>(sound-data->vct sd1 1)</em> - <em class=listener>#<vct[len=5]: 9.000 8.000 7.000 6.000 5.000></em> +<pre class="indented"> +:v1 +#<vct[len=10]: 0.100 0.100 0.100 3.000 0.100 0.100 0.100 0.100 0.100 0.100> +:v1.find_all {|x| x > 1.0 } +[3.0, 4.0] +:v1.max +4.0 +:v2 = make_vct(10, 0.1) +#<vct[len=10]: 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100> +:v2 < v1 +true </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> -<!-- vct->sound-data --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="vcttosounddata">vct->sound-data</a> v <em class=narg>sd chan</em></code> -</td></tr><tr><td></td><td> -vct->sound-data copies vct v's data into sound-data sd's channel chan. -</td></tr> -</table> -<br> -<table width="50%" border=0><tr><td bgcolor="lightgreen" valign="middle"><h3><A NAME="extsndlib">Sndlib</a></h3></td></tr></table> +<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>). -For many eamples, see play.scm and rtio.scm. The most important Sndlib functions for Snd are: +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 -------------------------------- --> +<!-- SNDLIB TABLE --> -<table border=0 cellspacing=4 cellpadding=6 hspace=10> +<div class="spacer"></div> <!-- mus-alsa-buffers --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musalsabuffers">mus-alsa-buffers</a></code> -</td></tr><tr><td width=30><br></td><td> -mus-alsa-buffers is the number of buffers ("periods") used in ALSA; you can also use the environment variable 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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mus-alsa-buffer-size --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musalsabuffersize">mus-alsa-buffer-size</a></code> -</td></tr><tr><td><br></td><td> -mus-alsa-buffer-size is the buffer size used in ALSA. You can also use the environment variable 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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mus-alsa-device --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musalsadevice">mus-alsa-device</a></code> -</td></tr><tr><td><br></td><td> -This is the ALSA audio device; it defaults to "default". +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mus-alsa-capture-device --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musalsacapturedevice">mus-alsa-capture-device</a></code> -</td></tr><tr><td><br></td><td> -This is the ALSA capture (audio recording) device. The matching environment variable is MUS_ALSA_CAPTURE_DEVICE. -</td></tr><tr><td colspan=2 height=16></td></tr> - - -<!-- mus-alsa-playback-device --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musalsaplaybackdevice">mus-alsa-playback-device</a></code> -</td></tr><tr><td><br></td><td> -This is the ALSA audio playback device. The matching environment variable is MUS_ALSA_PLAYBACK_DEVICE. -</td></tr><tr><td colspan=2 height=16></td></tr> - - -<!-- mus-alsa-squelch-warning --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musalsasquelchwarning">mus-alsa-squelch-warning</a></code> -</td></tr><tr><td><br></td><td> -Set mus-alsa-squelch-warning to #t to squelch warnings from ALSA about srate mismatches. -</td></tr><tr><td colspan=2 height=16></td></tr> - - -<!-- mus-audio-close --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musaudioclose">mus-audio-close</a> line</code> -</td></tr><tr><td><br></td><td> -mus-audio-close closes the audio port 'line' ('line' comes from either <a href="#musaudioopeninput">mus-audio-open-input</a> -or <a href="#musaudioopenoutput">mus-audio-open-output</a>). - -<table border=0 cellpadding=5 vspace=10><tr><td> -<pre> -(let* ((audio-fd (<a class=quiet href="#musaudioopenoutput" onmouseout="UnTip()" onmouseover="Tip(extsnd_musaudioopenoutput_tip)">mus-audio-open-output</a> mus-audio-default 22050 1 <a class=quiet href="#dataformat" onmouseout="UnTip()" onmouseover="Tip(extsnd_muslshort_tip)">mus-lshort</a> 1024)) - ;; open DAC at srate 22050, 1 channel, 1024 bytes per buffer - (osc (<a class=quiet href="sndclm.html#make-oscil" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_oscil_tip)">make-oscil</a> 440.0)) ; make a sine wave at 440 Hz - (data (<a class=quiet href="#makesounddata" onmouseout="UnTip()" onmouseover="Tip(extsnd_makesounddata_tip)">make-sound-data</a> 1 512))) ; output buffer (1 chan, 512 samples) - (do ((beg 0 (+ beg 512))) ; fill a buffer at a time - ((> beg 22050)) ; stop playing after 1 second - (do ((i 0 (+ 1 i))) ; write each sample of the sinusoid - ((= i 512)) ; until this buffer is full - (<a class=quiet href="#sounddataset" onmouseout="UnTip()" onmouseover="Tip(extsnd_sounddataset_tip)">sound-data-set!</a> data 0 i (* .1 (<a class=quiet href="sndclm.html#oscil" onmouseout="UnTip()" onmouseover="Tip(sndclm_oscil_tip)">oscil</a> osc)))) ; .1 amp - (<a class=quiet href="#musaudiowrite" onmouseout="UnTip()" onmouseover="Tip(extsnd_musaudiowrite_tip)">mus-audio-write</a> audio-fd data 512)) ; send a buffer to the DAC - (<em class=red>mus-audio-close</em> audio-fd)) ; close the DAC +<pre class="indented"> +<em class=def id="musalsacapturedevice">mus-alsa-capture-device</em> </pre> -</td></tr></table></td></tr><tr><td colspan=2 height=16></td></tr> +<p>This is the ALSA capture device. The matching environment variable is MUS_ALSA_CAPTURE_DEVICE. +</p> +<div class="spacer"></div> -<!-- mus-audio-describe --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musaudiodescribe">mus-audio-describe</a></code> -</td></tr><tr><td></td><td> -mus-audio-describe returns a string describing the current audio hardware state. -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- mus-alsa-playback-device --> +<pre class="indented"> +<em class=def id="musalsaplaybackdevice">mus-alsa-playback-device</em> +</pre> -<!-- mus-audio-open-input --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musaudioopeninput">mus-audio-open-input</a> device srate chans format bufsize</code> -</td></tr><tr><td></td><td> -mus-audio-open-input opens the audio input (recording) port 'device'. It returns -1 if the open failed. -</td></tr><tr><td colspan=2 height=16></td></tr> +<p>This is the ALSA audio playback device. The matching environment variable is MUS_ALSA_PLAYBACK_DEVICE. +</p> +<div class="spacer"></div> -<!-- mus-audio-open-output --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musaudioopenoutput">mus-audio-open-output</a> device srate chans format bufsize</code> -</td></tr><tr><td></td><td> -mus-audio-open-output opens the audio output (playback) port 'device'. It returns -1 if the open failed. -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- 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-audio-read --> -<tr><td colspan=2 height=16><code><a class=def name="musaudioread">mus-audio-read</a> line sd frames</code> -</td></tr><tr><td></td><td> -mus-audio-read reads 'frames' frames of data into the sound-data object 'sd' from the audio input port 'line'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- mus-bytes-per-sample --> +<pre class="indented"> +<em class=def id="musbytespersample">mus-bytes-per-sample</em> sample-type +</pre> -<!-- mus-audio-write --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musaudiowrite">mus-audio-write</a> line sd frames (start 0)</code> -</td></tr><tr><td></td><td> -<p>mus-audio-write writes 'frames' frames of data from the sound-data object 'sd' to the audio output port 'line'. -If 'start' is given, it sets where to start reading in the sound-data buffers. +<p>mus-bytes-per-sample returns the number of bytes that 'sample-type' uses to encode one sample of sound. </p> -<pre> -(let ((sd (make-sound-data 1 44100))) - (with-sound (:output sd) - (fm-violin 0 1 440 .1) - (fm-violin .5 .1 660 .1)) - (let* ((audio-fd (mus-audio-open-output mus-audio-default 44100 1 mus-lfloat (* 4 1024)))) - (do ((i 0 (+ i 1024))) - ((>= i 44100)) - (mus-audio-write audio-fd sd 1024 i)) - (mus-audio-close audio-fd))) +<pre class="indented"> +> (mus-bytes-per-sample mus-bdouble) +8 </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> -<!-- mus-bytes-per-sample --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musbytespersample">mus-bytes-per-sample</a> data-format</code> -</td></tr><tr><td></td><td> -mus-bytes-per-sample returns the number of bytes that 'data-format' uses to encode one sample of sound. -<pre> - :<em class=typing>(mus-bytes-per-sample mus-bdouble)</em> - <em class=listener>8</em> +<!-- mus-clipping --> +<pre class="indented"> +<em class=def id="musclipping">mus-clipping</em> </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> - -<!-- mus-clipping --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musclipping">mus-clipping</a></code> -</td></tr><tr><td></td><td> -mus-clipping is the default low-level clipping choice while accessing sound data. +<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. This function refers to <a href="#mussoundopenoutput">mus-sound-open-output</a> and friends; the file-local version is <a href="#musfileclipping">mus-file-clipping</a> — surely we could make this more confusing! See also <a href="#cliphook">clip-hook</a>. -</td></tr><tr><td colspan=2 height=16></td></tr> - - -<!-- mus-data-format-name --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musdataformatname">mus-data-format-name</a> format</code> -</td></tr><tr><td></td><td> -mus-data-format-name converts 'format' from an integer to an explanatory string, e.g. "16-bit big endian linear". -The sndlib data formats are:</td></tr> -<tr><td></td><td> -<pre> - 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> -There are also "unscaled" versions of the floating point types, and "normalized" versions of the integers. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> -<!-- mus-data-format->string --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musdataformattostring">mus-data-format->string</a> format</code> -</td></tr><tr><td></td><td> -mus-data-format->string converts 'format' from an integer to a string, e.g. "mus-mulaw". -<pre> - :<em class=typing>(mus-data-format->string mus-bdouble)</em> - <em class=listener>"mus-bdouble"</em> +<!-- mus-error-type->string --> +<pre class="indented"> +<em class=def id="muserrortypetostring">mus-error-type->string</em> error </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> - -<!-- mus-error-type->string --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="muserrortypetostring">mus-error-type->string</a> error</code> -</td></tr><tr><td></td><td> -mus-error-type->string returns a brief string description of 'error' +<p>mus-error-type->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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mus-expand-filename --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musexpandfilename">mus-expand-filename</a> name</code> -</td></tr><tr><td></td><td> -mus-expand-filename fills out the filename 'name' to include its 'absolute' pathname; +<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. -<pre> - :<em class=typing>(mus-expand-filename "oboe.snd")</em> - <em class=listener>"/home/bil/cl/oboe.snd"</em> +</p> + +<pre class="indented"> +> (mus-expand-filename "oboe.snd") +"/home/bil/cl/oboe.snd" </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- mus-file-clipping --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musfileclipping">mus-file-clipping</a> fd</code> -</td></tr><tr><td></td><td> -This is the clipping choice for the file referred to by 'fd' +<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' (a file identifier as returned by <a href="#mussoundopeninput">mus-sound-open-input</a>). The default is #f which makes clipping very obvious (it will cause wrap-around). See also <a href="#cliphook">clip-hook</a>. -</td></tr><tr><td colspan=2 height=16></td></tr> - - -<!-- mus-file-prescaler --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musfileprescaler">mus-file-prescaler</a> fd</code> -</td></tr><tr><td></td><td> -This is the prescaling value for reading data from the sndlib file descriptor 'fd'. -If you're reading float data that is extremely soft (i.e. peak amplitude -below .001), the transfer to integer form in sndlib (if you're using an integer internal sample format) can cause bits -to be lost, resulting in hiss. In this case set the prescaler for -the file to 1000.0 or so to get the data into a more normal -range. Since mus-file-prescaler must be set after opening -the sound file, but before trying to read any data, you need to use it in the context of <a href="#duringopenhook">during-open-hook</a>. -The default prescaler value is <a href="#musprescaler">mus-prescaler</a>, normally 1.0. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mus-header-raw-defaults --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musheaderrawdefaults">mus-header-raw-defaults</a></code> -</td></tr><tr><td></td><td> -mus-header-raw-defaults returns a list: '(srate chans data-format), the current raw header defaults. These can be +<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: -<pre> - (set! (<em class=red>mus-header-raw-defaults</em>) (list 22050 4 mus-lint)) +</p> + +<pre class="indented"> +(set! (<em class=red>mus-header-raw-defaults</em>) (list 22050 4 mus-lint)) </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- mus-header-type-name --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musheadertypename">mus-header-type-name</a> type</code> -</td></tr><tr><td></td><td> -mus-header-type-name converts 'type', an integer, to a string, e.g. "AIFF". Some of the sndlib header types are: -</td></tr> -<tr><td></td><td><pre> +<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> - 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 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> -This function doesn't set the header choices for output of recording; it just decodes a sndlib header type identifier. -<pre> - :<em class=typing>(mus-header-type-name (mus-sound-header-type "oboe.snd"))</em> - <em class=listener>"Sun/Next"</em> + +<p>This function just decodes a sndlib header type identifier. +</p> + +<pre class="indented"> +> (mus-header-type-name (mus-sound-header-type "oboe.snd")) +"Sun/Next" </pre> -The default sound output header choice is <a href="#defaultoutputheadertype">default-output-header-type</a>, + +<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>. -</td></tr><tr><td colspan=2 height=16></td></tr> - +</p> +<div class="spacer"></div> <!-- mus-header-type->string --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musheadertypetostring">mus-header-type->string</a> type</code> -</td></tr><tr><td></td><td> -mus-header-type->string converts 'type', an integer, to a string, e.g. "mus-aifc". -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="musheadertypetostring">mus-header-type->string</em> type +</pre> + +<p>mus-header-type->string converts 'type', an integer, to a string, e.g. "mus-aifc". +</p> +<div class="spacer"></div> <!-- mus-oss-set-buffers --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musosssetbuffers">mus-oss-set-buffers</a> num size</code> -</td></tr><tr><td></td><td> -In Linux (OSS), this sets the number and size of the OSS fragments. +<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 <code>(mus-oss-set-buffers 16 12)</code>. This default makes the control panel controls very sluggish. -Snd used to call <code>(mus-oss-set-buffers 4 12)</code> as its default, +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 <code>(mus-oss-set-buffers 2 12)</code>. -</td></tr><tr><td colspan=2 height=16></td></tr> +My initialization file includes (mus-oss-set-buffers 2 12). +</p> +<div class="spacer"></div> -<!-- mus-prescaler --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="musprescaler">mus-prescaler</a></code> -</td></tr><tr><td></td><td> -mus-prescaler is the global default prescaling value for reading data from a file (see <a href="#musfileprescaler">mus-file-prescaler</a>). -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- 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->string</em> format +</pre> + +<p>mus-sample-type->string converts 'format' from an integer to a string, e.g. "mus-mulaw". +</p> + +<pre class="indented"> +> (mus-sample-type->string mus-bdouble) +"mus-bdouble" +</pre> +<div class="spacer"></div> <!-- mus-sound-chans --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundchans">mus-sound-chans</a> filename</code> -</td></tr><tr><td></td><td> -This is the number of channels in 'filename'. This value can be set (as can the others like it mentioned below); +<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: -<pre> - (set! (<em class=red>mus-sound-chans</em> "43chans.snd") 2) +</p> + +<pre class="indented"> +(set! (<em class=red>mus-sound-chans</em> "43chans.snd") 2) </pre> -tells Snd that it has 2 channels no matter what the header says. -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>tells Snd that it has 2 channels no matter what the header says. +</p> +<div class="spacer"></div> <!-- mus-sound-close-input --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundcloseinput">mus-sound-close-input</a> fd</code> -</td></tr><tr><td></td><td> -This closes the sound file referred to by 'fd'; 'fd' is an integer returned by <a href="#mussoundopeninput">mus-sound-open-input</a>. +<pre class="indented"> +<em class=def id="mussoundcloseinput">mus-sound-close-input</em> fd +</pre> + +<p>This closes the sound file referred to by 'fd'; 'fd' is an integer returned by <a href="#mussoundopeninput">mus-sound-open-input</a>. These mus-sound-* file functions refer to a direct path to read and write sound files. Any such operation is beneath the notice, so to speak, of Snd. -This function reads the first 32 samples of a file, returning the 30th in channel 0: - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define read-sample-30 - (lambda (file) - (let* ((fd (<a class=quiet href="#mussoundopeninput" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussoundopeninput_tip)">>mus-sound-open-input</a> file)) - (<a class=quiet href="#chans" onmouseout="UnTip()" onmouseover="Tip(extsnd_chans_tip)">channels</a> (channels file)) - (data (<a class=quiet href="#makesounddata" onmouseout="UnTip()" onmouseover="Tip(extsnd_makesounddata_tip)">make-sound-data</a> chans 32))) - (<a class=quiet href="#mussoundread" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussoundread_tip)">mus-sound-read</a> fd 0 31 chans data) - (let ((val (<a class=quiet href="#sounddataref" onmouseout="UnTip()" onmouseover="Tip(extsnd_sounddataref_tip)">sound-data-ref</a> data 0 29))) - (<em class=red>mus-sound-close-input</em> fd) - val)))) -</pre></td></tr></table> -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mus-sound-close-output --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundcloseoutput">mus-sound-close-output</a> fd bytes</code> -</td></tr><tr><td></td><td> -This function closes the sound file 'fd', and updates its length indication, if any to be 'bytes' bytes. -If you didn't specify a data-format to <a href="#mussoundopenoutput">mus-sound-open-output</a>, -it defaulted to <code>mus-out-format</code>. -<code>mus-out-format</code> can +<pre class="indented"> +<em class=def id="mussoundcloseoutput">mus-sound-close-output</em> fd bytes +</pre> + +<p>This function closes the sound file 'fd', and updates its length indication, if any to be 'bytes' bytes. +If you didn't specify a sample-type to <a href="#mussoundopenoutput">mus-sound-open-output</a>, +it defaulted to mus-out-format. +mus-out-format can currently be either ints, floats, or doubles, depending on how you've configured Snd, so it's safest -to use <code>(<a href="#musbytespersample">mus-bytes-per-sample</a> mus-out-format)</code> +to use (<a href="#musbytespersample">mus-bytes-per-sample</a> mus-out-format) for the number of bytes per sample. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mus-sound-comment --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundcomment">mus-sound-comment</a> filename</code> -</td></tr><tr><td></td><td> -mus-sound-comment returns the comment in the header of the file 'filename'. -<pre> - :<em class=typing>(with-sound (:comment "this is a comment") (fm-violin 0 1 440 .1))</em> - <em class=listener>"test.snd"</em> - :<em class=typing>(mus-sound-comment "test.snd")</em> - <em class=listener>"this is a comment"</em> +<pre class="indented"> +<em class=def id="mussoundcomment">mus-sound-comment</em> filename </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<p>mus-sound-comment returns the comment in the header of the file 'filename'. +</p> -<!-- mus-sound-data-format --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussounddataformat">mus-sound-data-format</a> filename</code> -</td></tr><tr><td></td><td> -mus-sound-data-format returns the data format (e.g. <code>mus-bshort</code>) of the file 'filename'. -<pre> - :<em class=typing>(mus-data-format->string (mus-sound-data-format "oboe.snd"))</em> - <em class=listener>"mus-bshort"</em> +<pre class="indented"> +> (with-sound (:comment "this is a comment") (fm-violin 0 1 440 .1)) +"test.snd" +> (mus-sound-comment "test.snd") +"this is a comment" </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- mus-sound-data-location --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussounddatalocation">mus-sound-data-location</a> filename</code> -</td></tr><tr><td></td><td> -This is the location in bytes of the first sample in the file 'filename'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussounddatumsize">mus-sound-datum-size</a> filename</code> -</td></tr><tr><td></td><td> -This returns the size in bytes of each sample in 'filename'. -It is equivalent to <code>(mus-bytes-per-sample (mus-sound-data-format filename))</code>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundduration">mus-sound-duration</a> filename</code> -</td></tr><tr><td></td><td> -This returns the duration in seconds of the sound data in the file 'filename'. -<pre> - :<em class=typing>(mus-sound-duration "oboe.snd")</em> - <em class=listener>2.30512475967407</em> +<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"> +> (mus-sound-duration "oboe.snd") +2.30512475967407 </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- mus-sound-forget --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundforget">mus-sound-forget</a> filename</code> -</td></tr><tr><td></td><td> -mus-sound-forget removes the file 'filename' from the sndlib sound cache. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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> -<!-- mus-sound-frames --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundframes">mus-sound-frames</a> filename</code> -</td></tr><tr><td></td><td> -mus-sound-frames returns the number of frames of sound data in the file 'filename' according to its header +<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). -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mus-sound-header-type --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundheadertype">mus-sound-header-type</a> filename</code> -</td></tr><tr><td></td><td> -This returns the header type (e.g. <code>mus-aifc</code>) of the file 'filename'. -<pre> - :<em class=typing>(mus-header-type->string (mus-sound-header-type "oboe.snd"))</em> - <em class=listener>"mus-next"</em> +<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"> +> (mus-header-type->string (mus-sound-header-type "oboe.snd")) +"mus-next" </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- mus-sound-length --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundlength">mus-sound-length</a> filename</code> -</td></tr><tr><td></td><td> -mus-sound-length returns the number of bytes of sound data in the file 'filename'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundloopinfo">mus-sound-loop-info</a> filename</code> -</td></tr><tr><td></td><td> -This function refers to the "loop" info that is sometimes found in some headers (aifc, wav etc). +<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. -<pre> - :<em class=typing>(mus-sound-loop-info "~/sf1/forest.aiff")</em> - <em class=listener>(24981 144332 0 0 60 0 1 0)</em> +</p> + +<pre class="indented"> +> (mus-sound-loop-info "~/sf1/forest.aiff") +(24981 144332 0 0 60 0 1 0) </pre> -The loop info is a list of + +<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>. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mus-sound-mark-info --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundmarkinfo">mus-sound-mark-info</a> filename</code> -</td></tr><tr><td></td><td> -This function refers to the "mark" info that is sometimes found in aifc and aiff headers. +<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: -<pre> - :<em class=typing>(mus-sound-mark-info "/home/bil/sf1/forest.aiff")</em> - <em class=listener>((4 1) (3 0) (2 144332) (1 24981))</em> - :<em class=typing>(mus-sound-loop-info "/home/bil/sf1/forest.aiff")</em> - <em class=listener>(24981 144332 0 0 60 0 1 0)</em> +</p> + +<pre class="indented"> +> (mus-sound-mark-info "/home/bil/sf1/forest.aiff") +((4 1) (3 0) (2 144332) (1 24981)) +> (mus-sound-loop-info "/home/bil/sf1/forest.aiff") +(24981 144332 0 0 60 0 1 0) </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- mus-sound-maxamp --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundmaxamp">mus-sound-maxamp</a> filename</code> -</td></tr><tr><td></td><td> -mus-sound-maxamp returns a list of max amps and locations thereof. The corresponding set! +<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. -<pre> - :<em class=typing>(mus-sound-maxamp "oboe.snd")</em> - <em class=listener>(24971 0.147247314453125)</em> - ;; oboe's maxamp is .147 first encountered at sample 24971 - :<em class=typing>(mus-sound-maxamp "2a.snd")</em> - <em class=listener>(933 0.0999755859375 2827 0.0999755859375)</em> - ;; 2a's maxamps are 0.1 in each channel at sample 933 in chan 0, 2827 in chan 1 +</p> + +<pre class="indented"> +> (mus-sound-maxamp "oboe.snd") +(24971 0.147247314453125) +;; oboe's maxamp is .147 first encountered at sample 24971 +> (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> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- mus-sound-maxamp-exists? --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundmaxampexists">mus-sound-maxamp-exists?</a> filename</code> -</td></tr><tr><td></td><td> -This function returns #t if the sound's maxamp data is available +<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. -<pre> - :<em class=typing>(mus-sound-maxamp-exists? "/home/bil/test/sound/away.snd")</em> - <em class=listener>#f</em> - :<em class=typing>(mus-sound-maxamp "/home/bil/test/sound/away.snd")</em> - <em class=listener>(14562264 0.463623046875 14557044 0.404571533203125)</em> - :<em class=typing>(mus-sound-maxamp-exists? "/home/bil/test/sound/away.snd")</em> - <em class=listener>#t</em> +</p> + +<pre class="indented"> +> (mus-sound-maxamp-exists? "/home/bil/test/sound/away.snd") +#f +> (mus-sound-maxamp "/home/bil/test/sound/away.snd") +(14562264 0.463623046875 14557044 0.404571533203125) +> (mus-sound-maxamp-exists? "/home/bil/test/sound/away.snd") +#t </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- mus-sound-open-input --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundopeninput">mus-sound-open-input</a> filename</code> -</td></tr><tr><td></td><td> -mus-sound-open-input opens the sound file 'filename' and returns an integer for use with +<pre class="indented"> +<em class=def id="mussoundopeninput">mus-sound-open-input</em> filename +</pre> + +<p>mus-sound-open-input opens the sound file 'filename' and returns an integer for use with <a href="#mussoundread">mus-sound-read</a> and <a href="#mussoundcloseinput">mus-sound-close-input</a>. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mus-sound-open-output --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundopenoutput">mus-sound-open-output</a> filename <em class=narg>(srate 44100) (chans 1) data-format header-type comment</em></code> -</td></tr><tr><td></td><td> -mus-sound-open-output creates a new sound file with the indicated attributes, and returns an integer +<pre class="indented"> +<em class=def id="mussoundopenoutput">mus-sound-open-output</em> filename (srate 44100) (chans 1) sample-type header-type comment +</pre> + +<p>mus-sound-open-output creates a new sound file with the indicated attributes, and returns an integer for use with <a href="#mussoundwrite">mus-sound-write</a> and <a href="#mussoundcloseoutput">mus-sound-close-output</a>. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundprune">mus-sound-prune</a></code> -</td></tr><tr><td></td><td> -mus-sound-prune removes all defunct (non-existent) files from the sound cache. This is primarily intended for internal testing (snd-test.scm). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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-read --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundread">mus-sound-read</a> fd beg end chans sd</code> -</td></tr><tr><td></td><td> -mus-sound-read reads data from the sound file 'fd', loading the sound-data object 'sd' from 'beg' -to 'end'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="mussoundread">mus-sound-read</em> fd beg-in-file num-to-read chans sd +</pre> + +<p>mus-sound-read reads data from the sound file 'fd', starting at frample 'beg-in-file' (frample 0 is the first), +loading num-to-read samples into the float-vector 'sd' starting from 0 in that vector. +</p> +<div class="spacer"></div> <!-- mus-sound-reopen-output --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundreopenoutput">mus-sound-reopen-output</a> filename <em class=narg>(chans 1) data-format header-type data-location</em></code> -</td></tr><tr><td></td><td> -mus-sound-reopen-output reopens the sound file 'filename', ready to continue writing output. -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="mussoundreopenoutput">mus-sound-reopen-output</em> filename (chans 1) sample-type header-type data-location +</pre> + +<p>mus-sound-reopen-output reopens the sound file 'filename', ready to continue writing output. +</p> +<div class="spacer"></div> <!-- mus-sound-report-cache --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundreportcache">mus-sound-report-cache</a> file</code> -</td></tr><tr><td></td><td> -This function prints the current sound header data table to the file given or stdout if none is specified. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundsamples">mus-sound-samples</a> filename</code> -</td></tr><tr><td></td><td> -mus-sound-samples returns the number of samples in the sound file 'filename' according to its header. -<pre> - :<em class=typing>(mus-sound-samples "oboe.snd")</em> - <em class=listener>50828</em> +<pre class="indented"> +<em class=def id="mussoundsamples">mus-sound-samples</em> filename </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<p>mus-sound-samples returns the number of samples in the sound file 'filename' according to its header. +</p> + +<pre class="indented"> +> (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"> +> (mus-sample-type->string (mus-sound-sample-type "oboe.snd")) +"mus-bshort" +</pre> +<div class="spacer"></div> -<!-- mus-sound-seek-frame --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundseekframe">mus-sound-seek-frame</a> fd frame</code> -</td></tr><tr><td></td><td> -mus-sound-seek-frame moves the input or output reading point to 'frame' in the sound file 'fd'. -</td></tr><tr><td colspan=2 height=16></td></tr> + +<!-- mus-sound-seek-frample --> +<pre class="indented"> +<em class=def id="mussoundseekframple">mus-sound-seek-frample</em> fd frample +</pre> + +<p>mus-sound-seek-frample moves the input or output reading point to 'frample' in the sound file 'fd'. +</p> +<div class="spacer"></div> <!-- mus-sound-srate --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundsrate">mus-sound-srate</a> filename</code> -</td></tr><tr><td></td><td> -mus-sound-srate returns the sampling rate of 'filename'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundtypespecifier">mus-sound-type-specifier</a> filename</code> -</td></tr><tr><td></td><td> -This is the original type indication of 'filename'. This is only useful in internal testing. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundwrite">mus-sound-write</a> fd beg end chans sd</code> -</td></tr><tr><td></td><td> -mus-sound-write writes data from the sound-data object 'sd' to the sound file 'fd'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="mussoundwrite">mus-sound-write</em> fd beg end chans sd +</pre> + +<p>mus-sound-write writes data from the float-vector 'sd' to the sound file 'fd'. +</p> +<div class="spacer"></div> <!-- mus-sound-write-date --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mussoundwritedate">mus-sound-write-date</a> filename</code> -</td></tr><tr><td></td><td> -This returns the sound's write date: -</td></tr><tr><td></td><td> -<pre> - :<em class=typing>(strftime "%d-%b %H:%M %Z" (localtime (mus-sound-write-date "oboe.snd")))</em> - <em class=listener>"18-Oct 06:56 PDT"</em> +<pre class="indented"> +<em class=def id="mussoundwritedate">mus-sound-write-date</em> filename </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> -</table> +<p>This returns the sound's write date: +</p> + +<pre class="indented"> +> (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>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> -<table border=0 cellpadding=5 hspace=20><tr><td><pre> -<A NAME="sndinfo"></a>(define info +<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->string (channels file)) ", srate: " (number->string (srate file)) - ", " (<a class=quiet href="#musheadertypename" onmouseout="UnTip()" onmouseover="Tip(extsnd_musheadertypename_tip)">mus-header-type-name</a> (<a class=quiet href="#mussoundheadertype" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussoundheadertype_tip)">mus-sound-header-type</a> file)) - ", " (<a class=quiet href="#musdataformatname" onmouseout="UnTip()" onmouseover="Tip(extsnd_musdataformatname_tip)">mus-data-format-name</a> (<a class=quiet href="#mussounddataformat" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussounddataformat_tip)">mus-sound-data-format</a> 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->string - (/ (<a class=quiet href="#mussoundsamples" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussoundsamples_tip)">mus-sound-samples</a> file) + (/ (<a class=quiet href="#mussoundsamples">mus-sound-samples</a> file) (* (channels file) (srate file))))))) -</pre></td></tr></table> -<br> -<br> -<br> -<table width="50%" border=0><tr><td bgcolor="lightgreen" valign="middle"><h3><A NAME="sndmarks">Marks</a></h3></td></tr></table> +</pre> + -<A NAME="markstuff"></a> -<p>A mark is an object that refers to a particular sample. -Each mark has an associated sample number (<a class=quiet href="#marksample" onmouseout="UnTip()" onmouseover="Tip(extsnd_marksample_tip)">mark-sample</a>), -name (<a class=quiet href="#markname" onmouseout="UnTip()" onmouseover="Tip(extsnd_markname_tip)">mark-name</a>), and sync value (<a class=quiet href="#marksync" onmouseout="UnTip()" onmouseover="Tip(extsnd_marksync_tip)">mark-sync</a>). + +<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 -------------------------------- --> +<!-- MARKS TABLE --> +<div class="spacer"></div> -<table border=0 cellspacing=4 cellpadding=6 hspace=10> - <!-- add-mark --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="addmark">add-mark</a> <em class=narg>sample snd chn name sync</em></code> -</td></tr><tr><td width=30><br></td><td> -add-mark adds a mark at the position 'sample', returning the new mark. -<pre> - :<em class=typing>(define m1 (add-mark 1234))</em> - <em class=listener>m1</em> - :<em class=typing>m1</em> - <em class=listener>#<mark 0></em> - :<em class=typing>(mark-sample m1)</em> - <em class=listener>1234</em> -</pre> -The mark-name can be set via 'name', and the mark-sync field via 'sync'. +<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"> +> (define m1 (add-mark 1234)) +m1 +> m1 +#<mark 0> +> (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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- delete-mark --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="deletemark">delete-mark</a> mark</code> -</td></tr><tr><td></td><td> -delete-mark deletes the mark. Mark additions and deletions follow the +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- delete-marks --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="deletemarks">delete-marks</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This function deletes all marks in the given channel. It could be defined in Scheme as: -<pre> - (for-each - (lambda (m) - (delete-mark m)) - (<a class=quiet href="#emarks" onmouseout="UnTip()" onmouseover="Tip(extsnd_emarks_tip)">marks</a> (or snd (<a class=quiet href="#selectedsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>)) (or chn (<a class=quiet href="#selectedchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedchannel_tip)">selected-channel</a>)))) +<pre class="indented"> +<em class=def id="deletemarks">delete-marks</em> snd chn </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="findmark">find-mark</a> samp <em class=narg>snd chn edpos</em></code> -</td></tr><tr><td></td><td> -find-mark returns the mark at sample 'samp' or #f if none is found. +<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->id</a> in marks.scm finds a named mark in any channel (a global version of find-mark). -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- integer->mark --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="integertomark">integer->mark</a> i</code> -</td></tr><tr><td></td><td> +<pre class="indented"> +<em class=def id="integertomark">integer->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->integer</a>, exist mainly to convert old code to the current style", but that was premature. The mark-as-integer approach was handy @@ -4648,185 +4804,229 @@ 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->mark" over and over. One way out is to define -a #-reader that sees something like "#m12" and expands that into <code>(integer->mark 12)</code>: +a #-reader that sees something like "#m12" and expands that into (integer->mark 12): </p> -<pre> -> <em class=typing>(set! <a href="s7.html#sharpreaders">*#readers*</a> + +<pre class="indented"> +> (set! <a href="s7.html#sharpreaders">*#readers*</a> (cons (cons #\m (lambda (str) (integer->mark (string->number (substring str 1))))) - *#readers*))</em> -<em class=listener>((#\m . #<closure>))</em> -> <em class=typing>#m1</em> -<em class=listener>#<mark 1></em> -> <em class=typing>(mark-sample #m1)</em> -<em class=listener>38694</em> + *#readers*)) +((#\m . #<lambda (str)>)) +> #m1 +#<mark 1> +> (mark-sample #m1) +38694 </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- mark->integer --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="marktointeger">mark->integer</a> mark</code> -</td></tr><tr><td></td><td> -This is the counterpart to <a href="#integertomark">integer->mark</a>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="marktointeger">mark->integer</em> mark +</pre> + +<p>This is the counterpart to <a href="#integertomark">integer->mark</a>. +</p> +<div class="spacer"></div> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><em class=emdef><a href="#markcolor">mark-color</a></em></code> -</td></tr><tr><td></td><td> -This sets the color of mark indicator; the default is red. +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><em class=emdef><a href="#markcontext">mark-context</a></em></code> -</td></tr><tr><td></td><td> -This is the graphics context to use to draw a mark (XOR mode). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="markhome">mark-home</a> mark</code> -</td></tr><tr><td></td><td> -mark-home is a list with the sound and channel that hold the mark. -<pre> - :<em class=typing>(marks 0 0)</em> ; what marks are in snd 0, chn 0? - <em class=listener>(#<mark 0>)</em> ; just one - :<em class=typing>(mark-home (car (marks 0 0)))</em> ; what is that mark's snd/chn? - <em class=listener>(#<sound 0> 0)</em> +<pre class="indented"> +<em class=def id="markhome">mark-home</em> mark </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>mark-home is a list with the sound and channel that hold the mark. +</p> + +<pre class="indented"> +> (marks 0 0) ; what marks are in snd 0, chn 0? +(#<mark 0>) ; just one +> (mark-home (car (marks 0 0))) ; what is that mark's snd/chn? +(#<sound 0> 0) +</pre> +<div class="spacer"></div> <!-- mark-name --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="markname">mark-name</a> mark</code> -</td></tr><tr><td></td><td> -This is the name of the mark. -<pre> - :<em class=typing>(define m1 (add-mark 1234 0 0 "a name"))</em> - <em class=listener>m1</em> - :<em class=typing>(mark-name m1)</em> - <em class=listener>"a name"</em> - :<em class=typing>(set! (mark-name m1) "a new name")</em> - <em class=listener>"a new name"</em> - :<em class=typing>(mark-name m1)</em> - <em class=listener>"a new name"</em> +<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"> +> (define m1 (add-mark 1234 0 0 "a name")) +m1 +> (mark-name m1) +"a name" +> (set! (mark-name m1) "a new name") +"a new name" +> (mark-name m1) +"a new name" </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- mark-properties --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="markproperties">mark-properties</a> mark</code> -</td></tr><tr><td></td><td> -mark-properties is a property list associated with a mark. +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mark-property --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="markproperty">mark-property</a> key mark</code> -</td></tr><tr><td></td><td> -mark-property accesses the property 'key' in the property list associated with the mark. -<pre> - :<em class=typing>(set! (mark-property :weight m0) 2.5)</em> ; m0 is the mark - <em class=listener>2.5</em> - :<em class=typing>(mark-property :weight m0)</em> - <em class=listener>2.5</em> +<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"> +> (set! (mark-property :weight m0) 2.5) ; m0 is the mark +2.5 +> (mark-property :weight m0) +2.5 </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- mark-sample --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="marksample">mark-sample</a> mark <em class=narg>edpos</em></code> -</td></tr><tr><td></td><td> -mark-sample is the sample number (a location) marked by the mark at edit history position 'edpos'. -<pre> - :<em class=typing>(mark-sample m1)</em> - <em class=listener>1234</em> - :<em class=typing>(set! (mark-sample m1) 4321)</em> - <em class=listener>4321</em> - :<em class=typing>(mark-sample m1)</em> - <em class=listener>4321</em> -</pre> -It might be more consistent with other Snd names to call this mark-position, but I wanted to emphasize +<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"> +> (mark-sample m1) +1234 +> (set! (mark-sample m1) 4321) +4321 +> (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: -<br> - -<img src="pix/mark1.png" align=left vspace=20 hspace=20 alt="marks" onmouseout="UnTip()" onmouseover="Tip('This is a recording of a man saying "now the same piece is played".<br>The three marks are set at the start of three of the words.<br>To play from a mark, click the red triangle at the bottom.<br>To reposition a mark, drag the upper rectangle.')"> +</p> -</td></tr><tr><td colspan=2 height=16></td></tr> +<img class="indented" src="pix/mark1.png" alt="marks"> +<div class="spacer"></div> <!-- mark-sync --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="marksync">mark-sync</a> mark</code> -</td></tr><tr><td></td><td> -This is the +<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>. -<br><br> -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 <code>(set! (mark-sync ...)...)</code> +</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 <code>(start-sync)</code>, then click each of the marks that you want grouped together, then <code>(stop-sync)</code>. +instead; you type (start-sync), then click each of the marks that you want grouped together, then (stop-sync). +</p> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define mark-sync-number 0) -(define (start-sync) (set! mark-sync-number (+ (<a class=quiet href="#marksyncmax" onmouseout="UnTip()" onmouseover="Tip(extsnd_marksyncmax_tip)">mark-sync-max</a>) 1))) +(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" onmouseout="UnTip()" onmouseover="Tip(extsnd_markclickhook_tip)">mark-click-hook</a> click-to-sync) -</pre></td></tr></table> +(hook-push <a class=quiet href="#markclickhook">mark-click-hook</a> click-to-sync) +</pre> -Now control-click and drag one of them, and all of them move together deleting data, or +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mark-sync-max --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="marksyncmax">mark-sync-max</a></code> -</td></tr><tr><td></td><td> -This is the maximum mark sync value seen so far. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="marktagheight">mark-tag-height</a></code> -</td></tr><tr><td></td><td> -When a mark is drawn, it has a horizontal rectangle at the top, then a vertical line, then a triangle. +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mark-tag-width --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="marktagwidth">mark-tag-width</a></code> -</td></tr><tr><td></td><td> -This is the +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- marks --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="emarks">marks</a> <em class=narg>snd chn edpos</em></code> -</td></tr><tr><td></td><td> -This function returns a list of mark ids in the given channel at the edit history position 'edpos'. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define (how-many-marks-in-channel snd chn) (length (<em class=red>marks</em> snd chn))) @@ -4834,64 +5034,77 @@ each sound and its channels. (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_sounds_tip)">sounds</a>)))) -</pre></td></tr></table> + (apply + (map how-many-marks-in-sound (<a class=quiet href="#sounds">sounds</a>)))) +</pre> -If the marks function is called +<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. -<br><br> -Say we have two sounds open, 2 marks in the first (a mono sound), and one -in the 2nd channel of the 2nd (a stereo sound): -<pre> - :<em class=typing>(marks 0 0)</em> - <em class=listener>(#<mark 1> #<mark 0>)</em> ; these are mark id's, as returned by the add-mark function for example - :<em class=typing>(marks 1)</em> - <em class=listener>(() (#<mark 2>))</em> ; no mark in channel 0, one in channel 1 - :<em class=typing>(marks)</em> - <em class=listener>(((#<mark 1> #<mark 0>)) (() (#<mark 2>)))</em> +</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"> +> (marks 0 0) +(#<mark 1> #<mark 0>) ; these are mark id's, as returned by the add-mark function for example +> (marks 1) +(() (#<mark 2>)) ; no mark in channel 0, one in channel 1 +> (marks) +(((#<mark 1> #<mark 0>)) (() (#<mark 2>))) </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- mark? --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="markp">mark?</a> obj</code> -</td></tr><tr><td></td><td> -mark? returns #t if 'obj' is a mark and is active (that is, if it is present in a currently open channel). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="savemarks">save-marks</a> <em class=narg>snd filename</em></code> -</td></tr><tr><td></td><td> -save-marks saves the given sound's marks, writing a Scheme, Ruby, or Forth source file named either 'filename' or +<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 <sound's file-name>.marks. It returns the file name or #f if there are no marks to save. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><em class=emdef><a href="#showmarks">show-marks</a></em></code> -</td></tr><tr><td></td><td> -show-marks is #t if marks are being displayed. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="syncdmarks">syncd-marks</a> sync</code> -</td></tr><tr><td></td><td> -syncd-marks returns a list of marks that share the mark-sync value 'sync'. +<pre class="indented"> +<em class=def id="syncdmarks">syncd-marks</em> sync +</pre> -<table border=0 cellpadding=5><tr><td><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" onmouseout="UnTip()" onmouseover="Tip(extsnd_marksample_tip)">mark-sample</a> m) (+ (<a class=quiet href="#marksample" onmouseout="UnTip()" onmouseover="Tip(extsnd_marksample_tip)">mark-sample</a> m) diff))) + (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></td></tr></table> -</td></tr> +</pre> +<div class="spacer"></div> -</table> <!-- INDEX markstuff:Marking --> <p> @@ -4899,35 +5112,34 @@ See <a href="sndscm.html#marksdoc">marks.scm</a> for more examples including: </p> -<TABLE border=3 bordercolor="tan" hspace=20><tr><td width=500> +<TABLE class="method"> +<tr><th class="title"><a class=quiet href="extsnd.html#sndmarks">Marks</a></th></tr><tr><td> <blockquote><small> -<br> -global find-mark: <a href="sndscm.html#marknametoid">mark-name->id</a><br> +find mark in any sound: <a href="sndscm.html#marknametoid">mark-name->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> -evaluate function between marks: <a href="sndscm.html#evalbetweenmarks">eval-between-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> -loop continuously between the two specified marks: <a href="sndscm.html#loopbetweenmarks">loop-between-marks</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="#markproperty">mark-property</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> -<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> -<br> -<br> -<table width="50%" border=0><tr><td bgcolor="lightgreen" valign="middle"><h3><A NAME="sndmixes">Mixes</a></h3></td></tr></table> + + + +<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>). @@ -4935,90 +5147,102 @@ If the mix operation is tagged, you can then operate on that data through a numb the Mix Dialog, various hooks, and various mouse-related actions. </p> - -<table width="35%" border=0><tr><td bgcolor="#EEFDEE" valign="middle"><h4>Mixes</h4></td></tr></table> - <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-vct for example). In the old days, mixes were identified by integers, so for conversion you can use mix->integer and integer->mix. Say we have a mix object stored in the variable "id": </p> -<pre> - ><em class=listener>(set! (mix-amp id) .5)</em> - <em class=typing>.5</em> + +<pre class="indented"> +> (set! (mix-amp id) .5) +.5 </pre> + <p>This sets the mix's amplitude scaler to .5. </p> -<!-- -------------------------------- MIX FUNCTION TABLE -------------------------------- --> +<!-- MIX FUNCTION TABLE --> + +<div class="spacer"></div> -<table border=0 cellspacing=4 cellpadding=6 hspace=10> <!-- integer->mix --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="integertomix">integer->mix</a> i</code> -</td></tr><tr><td></td><td> -In olden times, a mix was handled in Snd code as an integer; nowadays, it's an object. +<pre class="indented"> +<em class=def id="integertomix">integer->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->integer</a>, exist mainly to convert old code to the current style. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mix->integer --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixtointeger">mix->integer</a> mix</code> -</td></tr><tr><td></td><td> -This is the counterpart to <a href="#integertomix">integer->mix</a>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="mixtointeger">mix->integer</em> mix +</pre> + +<p>This is the counterpart to <a href="#integertomix">integer->mix</a>. +</p> +<div class="spacer"></div> <!-- mix --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mix">mix</a> file <em class=narg>samp in-chan snd chn with-mix-tags auto-delete</em></code> -</td></tr><tr><td width=30></td><td> +<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> - (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 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 src="pix/mix1.png" alt="mixes" vspace=10 onmouseout="UnTip()" onmouseover="Tip('the mix tag is the red rectangle at the left end of the mix waveform.<br>The number under it is that mix\'s id.')"> -<br> -Now we can drag either of the red tags to move the mixed sounds, call up the View:Mixes dialog to edit them, +<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: -<br> -<img src="pix/mix2.png" alt="mixes" vspace=10> -<br> -We can use <a href="sndscm.html#dlocsigdoc">dlocsig</a> in conjunction with mix to move the mixed-in sound: +</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> -<table border=0 cellpadding=5 vspace=20><tr><td><pre> +<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 (<a name="mixmovesound">mix-move-sound</a> start-time file path) +(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" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussoundduration_tip)">mus-sound-duration</a> file)) - (rd (<a class=quiet href="#makesampler" onmouseout="UnTip()" onmouseover="Tip(extsnd_makesampler_tip)">make-sampler</a> 0 file)) - (start (<a class=quiet href="sndclm.html#secondstosamples" onmouseout="UnTip()" onmouseover="Tip(sndclm_secondstosamples_tip)">seconds->samples</a> start-time)) - (tmp-sound (<a class=quiet href="sndscm.html#sound-let" onmouseout="UnTip()" onmouseover="Tip(sndscm_sound_let_tip)">with-temp-sound</a> (:channels (<a class=quiet href="#channels" onmouseout="UnTip()" onmouseover="Tip(extsnd_channels_tip)">channels</a>) :srate (srate file)) + (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->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. @@ -5031,108 +5255,134 @@ We can use <a href="sndscm.html#dlocsigdoc">dlocsig</a> in conjunction with mix (dloc (car vals)) (beg (cadr vals)) (end (caddr vals))) - (run - (do ((i beg (+ 1 i))) + (do ((i beg (+ i 1))) ((= i end)) - (<em class=red>dlocsig</em> dloc i (<a class=quiet href="#readsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_readsample_tip)">read-sample</a> rd)))))))) + (<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_withmixtags_tip)">with-mix-tags</a>) #t))) + (<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></td></tr></table> -</td></tr><tr><td colspan=2></td></tr> +</pre> +<div class="spacer"></div> <!-- mixes --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixes">mixes</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -mixes returns a list of the mix objects associated with the given channel. +<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 2nd channel of the 2nd (a stereo sound): -<pre> - :<em class=typing>(mixes 0 0)</em> - <em class=listener>(#<mix 0> #<mix 2>)</em> ; these are mix objects, as returned by the mix function for example - :<em class=typing>(mixes 1)</em> - <em class=listener>(() (#<mix 1>))</em> ; no mix in channel 0, one in channel 1 - :<em class=typing>(mixes)</em> - <em class=listener>(((#<mix 0> #<mix 2>)) (() (#<mix 1>)))</em> +in the second channel of the second (a stereo sound): +</p> + +<pre class="indented"> +> (mixes 0 0) +(#<mix 0> #<mix 2>) ; these are mix objects, as returned by the mix function for example +> (mixes 1) +(() (#<mix 1>)) ; no mix in channel 0, one in channel 1 +> (mixes) +(((#<mix 0> #<mix 2>)) (() (#<mix 1>))) </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- mix-amp --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixamp">mix-amp</a> mix</code> -</td></tr><tr><td></td><td> -mix-amp is the amplitude scaler applied to the mix. To make mix mx half as loud: -<pre> - (set! (mix-amp mx) .5) +<pre class="indented"> +<em class=def id="mixamp">mix-amp</em> mix </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixampenv">mix-amp-env</a> mix</code> -</td></tr><tr><td></td><td> -mix-amp-env is the +<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. -<pre> - (set! (mix-amp-env mx) '(0 0 1 1)) +</p> + +<pre class="indented"> +(set! (mix-amp-env mx) '(0 0 1 1)) </pre> -sets mix mx's envelope to a ramp. -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>sets mix mx's envelope to a ramp. +</p> +<div class="spacer"></div> <!-- mix-color --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixcolor">mix-color</a> mix</code> -</td></tr><tr><td></td><td> -This is the color of mix waveforms; it defaults to dark-gray. +<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: <code>(set! (mix-color) red)</code> sets all mix waveforms to -red; but <code>(set! (mix-color mx) red)</code> sets only mix mx's waveform to red. -</td></tr><tr><td colspan=2 height=16></td></tr> +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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixlength">mix-length</a> mix</code> -</td></tr><tr><td></td><td> -mix-length returns the mix's length in samples. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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--> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixhome">mix-home</a> mix</code> -</td></tr><tr><td></td><td> -mix-home returns a list containing the mix's output sound and channel number, and the input original filename (if any), and input channel. -<pre> - :<em class=typing>(define mx (mix "pistol.snd" 1000))</em> - <em class=listener>#<mix 0></em> - :<em class=typing>(mix-home mx)</em> - <em class=listener>(#<sound 0> 0 "/home/bil/cl/pistol.snd" 0)</em> - ;; (list output-sound-index output-channel input-filename input-channel) - :<em class=typing>(set! mx (mix-vct (make-vct 100 .1) 2000))</em> - <em class=listener>#<mix 1></em> - :<em class=typing>(mix-home mx)</em> - <em class=listener>(#<sound 0> 0 #f 0)</em> - ;; #f: no input file +<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"> +> (define mx (mix "pistol.snd" 1000)) +#<mix 0> +> (mix-home mx) +(#<sound 0> 0 "/home/bil/cl/pistol.snd" 0) +;; (list output-sound-index output-channel input-filename input-channel) +> (set! mx (mix-vct (make-vct 100 .1) 2000)) +#<mix 1> +> (mix-home mx) +(#<sound 0> 0 #f 0) +;; #f: no input file </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- mix-name --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixname">mix-name</a> mix</code> -</td></tr><tr><td></td><td> -mix-name is the mix's name, if any. The mix name is displayed near the mix tag. +<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->id</a>. Here's an example that uses the mix name and the tag location (mix-tag-y) to provide some pitch feedback: +</p> -<table border=0 cellpadding=5 vspace=5><tr><td><pre> +<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")) @@ -5140,34 +5390,34 @@ feedback: (round (* 100 (- 1.0 (/ (log (/ freq lo)) (* (log 2.0) octs)))))) (let ((violin-sync 1) - (violin-color (<a class=quiet href="#makecolor" onmouseout="UnTip()" onmouseover="Tip(extsnd_makecolor_tip)">make-color</a> 0 0 1)) ; blue + (violin-color (<a class=quiet href="#makecolor">make-color</a> 0 0 1)) ; blue (cello-sync 2) - (cello-color (<a class=quiet href="#makecolor" onmouseout="UnTip()" onmouseover="Tip(extsnd_makecolor_tip)">make-color</a> 0 1 0)) ; green - (index (<a class=quiet href="#newsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_newsound_tip)">new-sound</a> "test.snd" :channels 1 :size (* 44100 22)))) + (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_mix_tip)">mix</a> (<a class=quiet href="sndscm.html#withtempsound" onmouseout="UnTip()" onmouseover="Tip(sndscm_withtempsound_tip)">with-temp-sound</a> () ; write instrument output to temp sound - (<a class=quiet href="sndscm.html#fmviolin" onmouseout="UnTip()" onmouseover="Tip(sndscm_fmviolin_tip)">fm-violin</a> 0 dur (<a class=quiet href="sndscm.html#tofrequency" onmouseout="UnTip()" onmouseover="Tip(sndscm_tofrequency_tip)">->frequency</a> freq #t) amp)) ; our favorite FM instrument - (<a class=quiet href="sndscm.html#tosample" onmouseout="UnTip()" onmouseover="Tip(sndscm_tosample_tip)">->sample</a> beg) 0 index 0 ; mix start, file in-chan, sound, channel + (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">->frequency</a> freq #t) amp)) ; our favorite FM instrument + (<a class=quiet href="sndscm.html#tosample">->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->string freq))) - (set! (<a class=quiet href="#mixsync" onmouseout="UnTip()" onmouseover="Tip(extsnd_mixsync_tip)">mix-sync</a> id) violin-sync) - (set! (<a class=quiet href="#mixcolor" onmouseout="UnTip()" onmouseover="Tip(extsnd_mixcolor_tip)">mix-color</a> id) violin-color) - (set! (<a class=quiet href="#mixtagy" onmouseout="UnTip()" onmouseover="Tip(extsnd_mixtagy_tip)">mix-tag-y</a> id) (frequency->tag-y (<a class=quiet href="sndscm.html#tofrequency" onmouseout="UnTip()" onmouseover="Tip(sndscm_tofrequency_tip)">->frequency</a> freq #t) (<a class=quiet href="sndscm.html#tofrequency" onmouseout="UnTip()" onmouseover="Tip(sndscm_tofrequency_tip)">->frequency</a> 'c2) 3)))) + (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->tag-y (<a class=quiet href="sndscm.html#tofrequency">->frequency</a> freq #t) (<a class=quiet href="sndscm.html#tofrequency">->frequency</a> 'c2) 3)))) (define (cello beg dur freq amp) - (let ((id (<a class=quiet href="#mix" onmouseout="UnTip()" onmouseover="Tip(extsnd_mix_tip)">mix</a> (<a class=quiet href="sndscm.html#withtempsound" onmouseout="UnTip()" onmouseover="Tip(sndscm_withtempsound_tip)">with-temp-sound</a> () - (<a class=quiet href="sndscm.html#fmviolin" onmouseout="UnTip()" onmouseover="Tip(sndscm_fmviolin_tip)">fm-violin</a> 0 dur (<a class=quiet href="sndscm.html#tofrequency" onmouseout="UnTip()" onmouseover="Tip(sndscm_tofrequency_tip)">->frequency</a> freq #t) amp :fm-index 1.5)) - (<a class=quiet href="sndscm.html#tosample" onmouseout="UnTip()" onmouseover="Tip(sndscm_tosample_tip)">->sample</a> beg) 0 index 0 + (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">->frequency</a> freq #t) amp :fm-index 1.5)) + (<a class=quiet href="sndscm.html#tosample">->sample</a> beg) 0 index 0 #t #t))) (if (symbol? freq) (set! (<em class=red>mix-name</em> id) (symbol->string freq))) - (set! (<a class=quiet href="#mixsync" onmouseout="UnTip()" onmouseover="Tip(extsnd_mixsync_tip)">mix-sync</a> id) cello-sync) - (set! (<a class=quiet href="#mixcolor" onmouseout="UnTip()" onmouseover="Tip(extsnd_mixcolor_tip)">mix-color</a> id) cello-color) - (set! (<a class=quiet href="#mixtagy" onmouseout="UnTip()" onmouseover="Tip(extsnd_mixtagy_tip)">mix-tag-y</a> id) (frequency->tag-y (<a class=quiet href="sndscm.html#tofrequency" onmouseout="UnTip()" onmouseover="Tip(sndscm_tofrequency_tip)">->frequency</a> freq #t) (<a class=quiet href="sndscm.html#tofrequency" onmouseout="UnTip()" onmouseover="Tip(sndscm_tofrequency_tip)">->frequency</a> 'c2) 3)))) + (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->tag-y (<a class=quiet href="sndscm.html#tofrequency">->frequency</a> freq #t) (<a class=quiet href="sndscm.html#tofrequency">->frequency</a> 'c2) 3)))) - (<a class=quiet href="#asoneedit" onmouseout="UnTip()" onmouseover="Tip(extsnd_asoneedit_tip)">as-one-edit</a> + (<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) @@ -5180,816 +5430,994 @@ feedback: (violin 9 3 'd4 .2) (cello 9 3 'b2 .2)))) -</pre></td></tr></table> -<img src="pix/mixname.png" alt="mix name example" vspace=10> -<p> -But note names are a bother to read; musglyphs.scm has code to display notes using CMN glyphs. -<A NAME="waltzexample">Here</a> we use the draw-mix-hook to display our notes as a score: +</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 src="pix/mixcmn.png" alt="mix CMN example" vspace=10> + +<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> -<table border=0 cellpadding=5 vspace=5><tr><td><pre> + +<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" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_sampletofile_tip)">make-sample->file</a> "violins.snd" 1 <a class=quiet href="#dataformat" onmouseout="UnTip()" onmouseover="Tip(extsnd_muslfloat_tip)">mus-lfloat</a> mus-next)) - (cellos (<a class=quiet href="sndclm.html#make-sampletofile" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_sampletofile_tip)">make-sample->file</a> "cellos.snd" 1 <a class=quiet href="#dataformat" onmouseout="UnTip()" onmouseover="Tip(extsnd_muslfloat_tip)">mus-lfloat</a> mus-next))) +(let ((violins (<a class=quiet href="sndclm.html#make-sampletofile">make-sample->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->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" onmouseout="UnTip()" onmouseover="Tip(sndscm_withtempsound_tip)">with-temp-sound</a> (:continue-old-file #t :output "violins.snd") - (<a class=quiet href="sndscm.html#fmviolin" onmouseout="UnTip()" onmouseover="Tip(sndscm_fmviolin_tip)">fm-violin</a> beg dur (<a class=quiet href="sndscm.html#tofrequency" onmouseout="UnTip()" onmouseover="Tip(sndscm_tofrequency_tip)">->frequency</a> freq #t) 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">->frequency</a> freq #t) amp))) (define (cello beg dur freq amp) - (<a class=quiet href="sndscm.html#withtempsound" onmouseout="UnTip()" onmouseover="Tip(sndscm_withtempsound_tip)">with-temp-sound</a> (:continue-old-file #t :output "cellos.snd") - (<a class=quiet href="sndscm.html#fmviolin" onmouseout="UnTip()" onmouseover="Tip(sndscm_fmviolin_tip)">fm-violin</a> beg dur (<a class=quiet href="sndscm.html#tofrequency" onmouseout="UnTip()" onmouseover="Tip(sndscm_tofrequency_tip)">->frequency</a> freq #t) amp :fm-index 1.5))) + (<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">->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 - (let ((index (<a class=quiet href="#newsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_newsound_tip)">new-sound</a> "test.snd" :channels 1))) ; our overall output file - (<a class=quiet href="#mix" onmouseout="UnTip()" onmouseover="Tip(extsnd_mix_tip)">mix</a> "violins.snd") - (<a class=quiet href="#mix" onmouseout="UnTip()" onmouseover="Tip(extsnd_mix_tip)">mix</a> "cellos.snd")) - - (<a class=quiet href="sndclm.html#mus-close" onmouseout="UnTip()" onmouseover="Tip(sndclm_mus_close_tip)">mus-close</a> violins) - (<a class=quiet href="sndclm.html#mus-close" onmouseout="UnTip()" onmouseover="Tip(sndclm_mus_close_tip)">mus-close</a> cellos)) -</pre></td></tr></table> + (<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> -</td></tr><tr><td colspan=2 height=32></td></tr> +<div class="spacer"></div> <!-- mix-position --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixposition">mix-position</a> mix</code> -</td></tr><tr><td></td><td> -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: -<pre> - (set! (mix-position mx) 200) +<pre class="indented"> +<em class=def id="mixposition">mix-position</em> mix </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="mixproperties">mix-properties</a> mix</code> -</td></tr><tr><td></td><td> -mix-properties is a property list associated with a mix. +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="spacer"></div> <!-- mix-property --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="mixproperty">mix-property</a> key mix</code> -</td></tr><tr><td></td><td> -mix-property associates a property with a mix. -<pre> - :<em class=typing>(set! (mix-property :info mx) "this is a mix")</em> - <em class=listener>"this is a mix"</em> - :<em class=typing>(mix-property :info mx)</em> - <em class=listener>"this is a mix"</em> +<pre class="indented"> +<em class=def id="mixproperty">mix-property</em> key mix </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>mix-property associates a property with a mix. +</p> + +<pre class="indented"> +> (set! (mix-property :info mx) "this is a mix") +"this is a mix" +> (mix-property :info mx) +"this is a mix" +</pre> +<div class="spacer"></div> <!-- mix-region --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixregion">mix-region</a> samp <em class=narg>reg snd chn reg-chan</em></code> -</td></tr><tr><td></td><td> -mix-region mixes region 'reg's' channel 'reg-chan' into the given channel starting at sample 'samp' ('samp' defaults to the cursor sample). +<pre class="indented"> +<em class=def id="mixregion">mix-region</em> samp reg 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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mix-selection --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><em class=emdef>mix-selection</em> <em class=narg>beg snd chn selection-chan</em></code> -</td></tr><tr><td></td><td> -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 <code>(mix-selection (cursor))</code>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixspeed">mix-speed</a> mix</code> -</td></tr><tr><td></td><td> -mix-speed is the speed (resampling ratio) of 'mix'; 1.0 (the default) means no resampling takes place; +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mix-sync --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixsync">mix-sync</a> mix</code> -</td></tr><tr><td></td><td> -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> +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mix-sync-max --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixsyncmax">mix-sync-max</a></code> -</td></tr><tr><td></td><td> -This is the maximum mix sync value seen so far. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixtagheight">mix-tag-height</a></code> -</td></tr><tr><td></td><td> -This is the mix tag height (the vertical extent of the tag rectangle) in pixels (the default is 14). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixtagwidth">mix-tag-width</a></code> -</td></tr><tr><td></td><td> -This is the mix tag width in pixels (the default is 6). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixtagy">mix-tag-y</a> mix</code> -</td></tr><tr><td></td><td> -This is the mix tag y (vertical) offset; 0 (the default) is the top of the graph, so +<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: -<pre> - (set! (mix-tag-y mix-id) - (round (* 100 (- 1.0 (/ (log (/ freq 40.0)) (* (log 2.0) 7)))))) +</p> + +<pre class="indented"> +(set! (mix-tag-y mix-id) (round (* 100 (- 1.0 (/ (log (/ freq 40.0)) (* (log 2.0) 7)))))) </pre> -See, for example, check-mix-tags in sndscm.html. -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>See, for example, check-mix-tags in sndscm.html. +</p> +<div class="spacer"></div> <!-- mix-vct --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixvct">mix-vct</a> vct <em class=narg>beg snd chn with-mix-tags origin</em></code> -</td></tr><tr><td></td><td> -mix-vct is one of the basic mixing functions. It +<pre class="indented"> +<em class=def id="mixvct">mix-vct</em> vct beg snd chn with-mix-tags origin +</pre> + +<p>mix-vct is one of the basic mixing functions. It mixes the contents of 'vct' 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-vct returns the id of the new mix, or -1 (a simple mix, no tag). -<pre> - :<em class=typing>(channel->vct 1000 3)</em> ; what are these 3 samples before the mix? - <em class=listener>#<vct[len=3]: -0.065 -0.059 -0.060></em> - :<em class=typing>(define mx (mix-vct (vct .1 .2 .3) 1000))</em> ; add these 3 values - <em class=listener>#<mix 3></em> - :<em class=typing>(channel->vct 1000 3)</em> ; now we hope they were added... - <em class=listener>#<vct[len=3]: 0.035 0.141 0.240></em> - :<em class=typing>(mix-position mx)</em> ; and the new mix starts at 1000 - <em class=listener>1000</em> - :<em class=typing>(length mx)</em> ; and its length is 3 samples - <em class=listener>3</em> - :<em class=typing>(mix-vct (with-sound (:output (make-vct 44100)) (fm-violin 0 1 440 .1)))</em> - <em class=listener>#<mix 4></em> -</pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mix-waveform-height --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixwaveformheight">mix-waveform-height</a></code> -</td></tr><tr><td></td><td> -This is the maximum height in pixels of mix waveforms. The default is 20 (see <a href="#showmixwaveforms">show-mix-waveforms</a>). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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? --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixp">mix?</a> obj</code> -</td></tr><tr><td></td><td> -mix? returns #t if 'obj' is a mix object and it is accessible in a channel's edit list. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="savemix">save-mix</a> mix filename</code> -</td></tr><tr><td></td><td> -save-mix saves a given mix's data in the file 'filename'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="withmixtags">with-mix-tags</a></code> -</td></tr><tr><td></td><td> -If with-mix-tags is #f (the default is #t), newly mixed data does not have a mix id or tag associated with it. -</td></tr> +<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> -</table> <!-- INDEX sndmixes:Mixing --> -<br> -<TABLE border=3 bordercolor="tan" hspace=20><tr><td> + +<TABLE class="method"> +<tr><th class="title"><a class=quiet href="extsnd.html#sndmixes">Mixing</a></th></tr><tr><td> <blockquote><small> -<br> -mix sound file: <a href="#mix">mix</a> or drag-and-drop it where you want it mixed<br> +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="#mixregion">mix-region</a><br> -mix selection: <a href="#mixselection">mix-selection</a><br> -mix vct: <a href="#mixvct">mix-vct</a><br> -mix sound-data: <a href="sndscm.html#mixsounddata">mix-sound-data</a><br> -mix a frame: <a href="sndscm.html#mixframe">mix-frame</a><br> +mix region: <a href="extsnd.html#mixregion">mix-region</a><br> +mix selection: <a href="extsnd.html#mixselection">mix-selection</a><br> +mix vct: <a href="extsnd.html#mixvct">mix-vct</a><br> enveloped mix: see <a href="sndscm.html#envelopedmix">enveloped-mix</a> in extensions.scm<br> -read mix samples: <a href="#makemixsampler">make-mix-sampler</a><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 vct: <a href="sndscm.html#mixtovct">mix->vct</a><br> -save mix data in file: <a href="#savemix">save-mix</a><br> -mix property list: <a href="#mixproperty">mix-property</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="#mixmovesound">mix-move-sound</a><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> -<br> </small></blockquote> </td></tr></TABLE> -<br><br> -<table width="50%" border=0><tr><td bgcolor="lightgreen" valign="middle"><h3><A NAME="sndregions">Regions and Selections</a></h3></td></tr></table> -<br> -<table width="35%" border=0><tr><td bgcolor="#EEFDEE" valign="middle"><h4>Regions</h4></td></tr></table> +<div class="header" id="sndregions">Regions and Selections</div> -<p>A region is a saved portion of sound data. Use the View:Region browser to inspect, edit, and save regions. +<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 -------------------------------- --> +<!-- REGION TABLE --> + +<div class="spacer"></div> -<A NAME="regionstuff"></a> -<table border=0 cellspacing=4 cellpadding=6 hspace=10> <!-- forget-region --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="forgetregion">forget-region</a> reg</code> -</td></tr><tr><td width=30><br></td><td> -forget-region deletes region 'reg', removing it from the region stack. This does not affect any of the +<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, -<pre> - (for-each <em class=red>forget-region</em> (<a class=quiet href="#eregions" onmouseout="UnTip()" onmouseover="Tip(extsnd_eregions_tip)">regions</a>)) +</p> + +<pre class="indented"> +(for-each <em class=red>forget-region</em> (<a class=quiet href="#eregions">regions</a>)) </pre> -I called this forget-region because delete-region seemed ambiguous, especially given delete-selection. -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>I called this forget-region because delete-region seemed ambiguous, especially given delete-selection. +</p> +<div class="spacer"></div> <!-- insert-region --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="insertregion">insert-region</a> reg beg <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -insert-region inserts region 'reg' at sample 'beg' in the given channel. The following +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define* (<a name="rotatechannel">rotate-channel</a> (samps 1) snd chn) - (let* ((ind (or snd (<a class=quiet href="#selectedsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>) (car (<a class=quiet href="#sounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_sounds_tip)">sounds</a>)))) - (chan (or chn (<a class=quiet href="#selectedchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedchannel_tip)">selected-channel</a>) 0))) +<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_asoneedit_tip)">as-one-edit</a> + (<a class=quiet href="#asoneedit">as-one-edit</a> (lambda () - (<a class=quiet href="#deletesamples" onmouseout="UnTip()" onmouseover="Tip(extsnd_deletesamples_tip)">delete-samples</a> 0 samps ind chan) - (<em class=red>insert-region</em> reg (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a> ind chan)))) + (<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></td></tr></table></td></tr><tr><td colspan=2 height=16></td></tr> +</pre> +<div class="spacer"></div> <!-- integer->region --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="integertoregion">integer->region</a> i</code> -</td></tr><tr><td></td><td> -In olden times, a region was handled in Snd code as an integer; nowadays, it's an object. +<pre class="indented"> +<em class=def id="integertoregion">integer->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->integer</a>, exist mainly to convert old code to the current style. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- make-region --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="makeregion">make-region</a> <em class=narg>beg end snd chn</em></code> -</td></tr><tr><td></td><td> -make-region creates a new region spanning the samples 'beg' to 'end' in the given channel. +<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_sync_tip)">sync</a> fields into account. -</td></tr><tr><td colspan=2 height=16></td></tr> +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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a href="#makeregionsampler">make-region-sampler</a> reg <em class=narg>start chn (dir 1)</em></code> -</td></tr><tr><td></td><td> -This creates a <a href="#samplers">sampler</a> reading the region's channel 'chn' starting at sample 'start' within that region. +<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). -</td></tr> -<tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> + <!-- mix-region --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><em class=emdef>mix-region</em> reg <em class=narg>samp snd chn</em></code> -</td></tr><tr><td></td><td> -mix-region mixes region 'reg' into the given channel starting at sample 'samp' (defaulting to the cursor location). +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- region-chans --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="regionchans">region-chans</a> reg</code> -</td></tr><tr><td></td><td> -This returns the number of channels in the region 'reg'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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-frames --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="regionframes">region-frames</a> reg <em class=narg>(chan 0)</em></code> -</td></tr><tr><td></td><td> -region-frames returns the number of frames in the region 'reg'. -<pre> - :<em class=typing>(make-region 100 200)</em> - <em class=listener>#<region 1></em> - :<em class=typing>(region-frames (integer->region 1))</em> - <em class=listener>101</em> + +<!-- region-framples --> +<pre class="indented"> +<em class=def id="regionframples">region-framples</em> reg (chan 0) </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>region-framples returns the number of framples in the region 'reg'. +</p> + +<pre class="indented"> +> (make-region 100 200) +#<region 1> +> (region-framples (integer->region 1)) +101 +</pre> +<div class="spacer"></div> <!-- region-graph-style --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="regiongraphstyle">region-graph-style</a></code> -</td></tr><tr><td></td><td> -region-graph-style is the graph drawing choice for the region dialog's graph. +<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: -<pre> - graph-lines graph-dots graph-filled graph-lollipops graph-dots-and-lines +</p> + +<pre class="indented"> +graph-lines graph-dots graph-filled graph-lollipops graph-dots-and-lines </pre> -<code>graph-lines</code> is the default. -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>graph-lines is the default. +</p> +<div class="spacer"></div> <!-- region-home --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="regionhome">region-home</a> reg</code> -</td></tr><tr><td></td><td> -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 frames. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="regiontointeger">region->integer</a> region</code> -</td></tr><tr><td></td><td> -This is the counterpart to <a href="#integertoregion">integer->region</a>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="regiontointeger">region->integer</em> region +</pre> + +<p>This is the counterpart to <a href="#integertoregion">integer->region</a>. +</p> +<div class="spacer"></div> <!-- region-maxamp --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="regionmaxamp">region-maxamp</a> reg</code> -</td></tr><tr><td></td><td> -region-maxamp is the peak amplitude of the samples in the region 'reg'. -<pre> - :<em class=typing>(region-maxamp (integer->region 1))</em> - <em class=listener>4.8828125e-4</em> +<pre class="indented"> +<em class=def id="regionmaxamp">region-maxamp</em> reg </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>region-maxamp is the peak amplitude of the samples in the region 'reg'. +</p> + +<pre class="indented"> +> (region-maxamp (integer->region 1)) +4.8828125e-4 +</pre> +<div class="spacer"></div> <!-- region-maxamp-position --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="regionmaxampposition">region-maxamp-position</a> reg</code> -</td></tr><tr><td></td><td> -region-maxamp-position returns the location (a sample number) of the peak amplitude of the region 'reg'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="regionposition">region-position</a> reg <em class=narg>chan</em></code> -</td></tr><tr><td></td><td> -region-position returns the begin time of the region's channel 'chan' in the original sound. -<pre> - :<em class=typing>(make-region 1000 2000)</em> - <em class=listener>2</em> - :<em class=typing>(region-position (integer->region 2))</em> - <em class=listener>1000</em> +<pre class="indented"> +<em class=def id="regionposition">region-position</em> reg chan </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>region-position returns the begin time of the region's channel 'chan' in the original sound. +</p> + +<pre class="indented"> +> (make-region 1000 2000) +2 +> (region-position (integer->region 2)) +1000 +</pre> +<div class="spacer"></div> <!-- region-sample --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="regionsample">region-sample</a> reg samp <em class=narg>chan</em></code> -</td></tr><tr><td></td><td> -region-sample returns the value of the sample 'samp' in channel 'chan' of the region 'reg'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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->vct --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="regiontovct">region->vct</a> reg <em class=narg>samp samps chan v</em></code> -</td></tr><tr><td></td><td> -region->vct returns a vct containing 'samps' samples starting at 'samp' in channel 'chan' of the region 'reg'. +<pre class="indented"> +<em class=def id="regiontovct">region->vct</em> reg samp samps chan v +</pre> + +<p>region->vct returns a vct containing 'samps' samples starting at 'samp' in channel 'chan' of the region 'reg'. If 'v' (a vct) is provided, it is filled, rather than creating a new vct. +</p> -<table border=0 cellpadding=5><tr><td><pre> +<pre class="indented"> (define (region-rms n) (let* ((data (<em class=red>region->vct</em> (integer->region 0) 0 #f n)) (len (length data))) - (sqrt (/ (<a class=quiet href="sndclm.html#dot-product" onmouseout="UnTip()" onmouseover="Tip(sndclm_dot_product_tip)">dot-product</a> data data len) len)))) -</pre></td></tr></table> -</td></tr><tr><td colspan=2 height=16></td></tr> + (sqrt (/ (<a class=quiet href="sndclm.html#dot-product">dot-product</a> data data len) len)))) +</pre> +<div class="spacer"></div> <!-- region-srate --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="regionsrate">region-srate</a> reg</code> -</td></tr><tr><td></td><td> -region-srate returns the sampling rate of the data that makes up the region 'reg'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="eregions">regions</a></code> -</td></tr><tr><td></td><td> -regions returns a list of active regions. The most recently created region is <code>(car (regions))</code>. -<code>(map region-frames (regions))</code> returns a list of region lengths. +<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>. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- region? --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="regionok">region?</a> reg</code> -</td></tr><tr><td></td><td> -region? returns #t if the region 'reg' exists. There is a limit to how many regions Snd tries to +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- save-region --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="saveregion">save-region</a> reg :file <em class=narg>:header-type :data-format :comment</em></code> -</td></tr><tr><td></td><td> -save-region saves the region 'reg' in 'file' in the given data format and header type. +<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: -<pre> - (save-region reg "reg0.snd") - (save-region reg :file "reg0.snd" :header-type mus-next) - (save-region reg "reg0.snd" mus-next <a class=quiet href="#dataformat" onmouseout="UnTip()" onmouseover="Tip(extsnd_musbfloat_tip)">mus-bfloat</a> "a comment") - (save-region reg :file "reg0.snd" :comment "a comment" :data-format <a class=quiet href="#dataformat" onmouseout="UnTip()" onmouseover="Tip(extsnd_musbfloat_tip)">mus-bfloat</a>) +</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> -</td></tr> -</table> -<br> <!-- INDEX regionstuff:Regions --> -<TABLE border=3 bordercolor="tan" hspace=20><tr><td> -<small><blockquote> -Max length of region list: <a href="#maxregions">max-regions</a><br> -Whether selection creates a region: <a href="#selectioncreatesregion">selection-creates-region</a><br> + +<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: <a href="#viewregionsdialog">view-regions-dialog</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> -<a href="sndscm.html#regiontoframe">region->frame</a><br> -<a href="sndscm.html#regiontosounddata">region->sound-data</a><br> -<a href="sndscm.html#makeregionframereader">make-region-frame-reader</a><br> -<br> -</blockquote></small> +</small></blockquote> </td></tr></TABLE> -<br><br> -<table width="35%" border=0><tr><td bgcolor="#EEFDEE" valign="middle"><h4>Selections</h4></td></tr></table> +<!-- SELECTION TABLE --> +<div class="spacer"></div> -<!-- -------------------------------- SELECTION TABLE -------------------------------- --> -<br> -<A NAME="selectionstuff"></a> -<table border=0 cellspacing=4 cellpadding=6 hspace=10> <!-- convolve-selection-with --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="convolveselectionwith">convolve-selection-with</a> file <em class=narg>amp</em></code> -</td></tr><tr><td width=30><br></td><td> -convolve-selection-with convolves the current selection with 'file', replacing the selection with the result. +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- delete-selection --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="deleteselection">delete-selection</a></code> -</td></tr><tr><td></td><td> -delete-selection deletes the selection, equivalent to the Edit:Delete selection menu choice. -</td></tr> -<tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="deleteselectionandsmooth">delete-selection-and-smooth</a></code> -</td></tr><tr><td></td><td> -delete-selection-and-smooth deletes the selection, then tries to make the splice smooth. -</td></tr> -<tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="envselection">env-selection</a> envelope <em class=narg>env-base</em></code> -</td></tr><tr><td></td><td> -env-selection applies 'envelope' to the selection. (as an amplitude envelope). +<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: -<pre> - (env-selection '(0 0 1 1 2 0)) - (env-selection (<a class=quiet href="sndclm.html#make-env" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_env_tip)">make-env</a> '(0 0 1 1 2 0) :length (<a class=quiet href="#selectionframes" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectionframes_tip)">selection-frames</a>))) +</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> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- filter-selection --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="filterselection">filter-selection</a> env <em class=narg>order truncate</em></code> -</td></tr><tr><td></td><td> -filter-selection applies an FIR filter of order 'order' and frequency response 'env' +<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 vct 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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- insert-selection --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="insertselection">insert-selection</a> <em class=narg>beg snd chn</em></code> -</td></tr><tr><td></td><td> -insert-selection inserts a copy of the selection starting at 'beg' in the given channel (that is, it pastes in the 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 <code>(insert-selection (cursor))</code>. -</td></tr><tr><td colspan=2 height=16></td></tr> +The Edit:Insert selection menu choice is essentially (insert-selection (cursor)). +</p> +<div class="spacer"></div> <!-- mix-selection --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixselection">mix-selection</a> <em class=narg>beg snd chn selection-channel</em></code> -</td></tr><tr><td></td><td> -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 <code>(mix-selection (cursor))</code>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="reverseselection">reverse-selection</a></code> -</td></tr><tr><td></td><td> -reverse-selection reverses the selection. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="saveselection">save-selection</a> <em class=narg>:file (:header-type mus-next) :data-format :srate :comment :channel</em></code> -</td></tr><tr><td></td><td> -save-selection saves the selection in 'file'. If 'channel' is given, it saves only that channel. - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define (brksnd dur base) - "(brksnd dur base) divides the current sound into dur-sized pieces, - saving them in files named 'base'.n: (brksnd 1.0 \"sec\")" - (let ((hop (floor (* (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a>) dur))) - (len (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a>)) - (old-sync (<a class=quiet href="#sync" onmouseout="UnTip()" onmouseover="Tip(extsnd_sync_tip)">sync</a>))) - (set! (<a class=quiet href="#sync" onmouseout="UnTip()" onmouseover="Tip(extsnd_sync_tip)">sync</a>) 1) ; save all chans - (do ((i 0 (+ i hop)) - (j 0 (+ 1 j))) - ((>= i len)) - (<a class=quiet href="sndscm.html#makeselection" onmouseout="UnTip()" onmouseover="Tip(sndscm_makeselection_tip)">make-selection</a> i (+ i hop)) ; in extensions.scm - (<em class=red>save-selection</em> (string-append base "." (number->string j)))) - (set! (<a class=quiet href="#sync" onmouseout="UnTip()" onmouseover="Tip(extsnd_sync_tip)">sync</a>) old-sync))) -</pre></td></tr></table> - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define* (<a name="extractchannels">extract-channels</a> :rest chans) +<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>)) + (old-sync (<a class=quiet href="#sync">sync</a>))) + (set! (<a class=quiet href="#sync">sync</a>) 1) ; save all chans + (do ((i 0 (+ i hop)) + (j 0 (+ j 1))) + ((>= 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->string j)))) + (set! (<a class=quiet href="#sync">sync</a>) old-sync))))) +</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" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>) (car (<a class=quiet href="#sounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_sounds_tip)">sounds</a>))))) - (if (<a class=quiet href="#soundp" onmouseout="UnTip()" onmouseover="Tip(extsnd_soundp_tip)">sound?</a> snd) + (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectionmember_tip)">selection-member?</a> snd chan) #t) - (set! (<a class=quiet href="#selectionposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectionposition_tip)">selection-position</a> snd chan) 0) - (set! (<a class=quiet href="#selectionframes" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectionframes_tip)">selection-frames</a> snd chan) (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a> snd 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></td></tr></table> -</td></tr><tr><td colspan=2 height=16></td></tr> +</pre> +<div class="spacer"></div> <!-- scale-selection-by --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="scaleselectionby">scale-selection-by</a> scalers</code> -</td></tr><tr><td></td><td> -scale-selection-by scales (multiplies) the selection by 'scalers' which can be either a float, +<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 vct. In a multichannel selection, each member of the vct or list -is applied to the next channel in the selection. <code>(scale-selection-by '(0.0 2.0))</code> scales -the first channel by 0.0, the second (if any) by 2.0. <code>(scale-selection-by 2.0)</code> scales +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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- scale-selection-to --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="scaleselectionto">scale-selection-to</a> <em class=narg>norms</em></code> -</td></tr><tr><td></td><td> -scale-selection-to normalizes the selection to peak amplitude 'norms' which can be either a float, +<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 vct. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- select-all --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="selectall">select-all</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This function selects all samples in the given channel. +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- selection --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="selection">selection</a></code> -</td></tr><tr><td></td><td> +<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> - :<em class=typing>(define selobj (selection))</em> - <em class=listener>selobj</em> - :<em class=typing>selobj</em> - <em class=listener>#<selection 1></em> - :<em class=typing>(selection-chans)</em> - <em class=listener>1</em> - :<em class=typing>(channels selobj)</em> - <em class=listener>1</em> + +<pre class="indented"> +> (define selobj (selection)) +selobj +> selobj +#<selection 1> +> (selection-chans) +1 +> (channels selobj) +1 </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- selection-chans --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="selectionchans">selection-chans</a></code> -</td></tr><tr><td></td><td> -selection-chans returns the number of channels in the current selection. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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> -<!-- selection-frames --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="selectionframes">selection-frames</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -selection-frames returns the number of frames in the current selection (its length in samples). +<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: -<pre> - :<em class=typing>(select-all)</em> ; grab all of current channel - <em class=listener>#<region 1></em> - :<em class=typing>(selection-frames)</em> - <em class=listener>55240</em> - :<em class=typing>(set! (selection-frames) 10000)</em> ; unselect all but the starting 10000 - <em class=listener>10000</em> - :<em class=typing>(selection-frames)</em> - <em class=listener>10000</em> - :<em class=typing>(set! (selection-frames) (* 2 (selection-frames)))</em> ; double the selection length - <em class=listener>20000</em> +</p> + +<pre class="indented"> +> (select-all) ; grab all of current channel +#<region 1> +> (selection-framples) +55240 +> (set! (selection-framples) 10000) ; unselect all but the starting 10000 +10000 +> (selection-framples) +10000 +> (set! (selection-framples) (* 2 (selection-framples))) ; double the selection length +20000 </pre> -See also <a href="sndscm.html#makeselection">make-selection</a>. -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>See also <a href="sndscm.html#makeselection">make-selection</a>. +</p> +<div class="spacer"></div> <!-- selection-maxamp --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="selectionmaxamp">selection-maxamp</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -selection-maxamp returns the peak amplitude of the selection in the given channel. +<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: -<pre> - (<a class=quiet href="#bindkey" onmouseout="UnTip()" onmouseover="Tip(extsnd_bindkey_tip)">bind-key</a> #\m 0 - (lambda () - (set! (<a class=quiet href="#ybounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_ybounds_tip)">y-bounds</a> (<a class=quiet href="#selectedsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>) (<a class=quiet href="#selectedchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedchannel_tip)">selected-channel</a>)) (list 0 (<em class=red>selection-maxamp</em>)))) - #t) +</p> - (<a class=quiet href="#bindkey" onmouseout="UnTip()" onmouseover="Tip(extsnd_bindkey_tip)">bind-key</a> #\m 4 - (lambda () - (set! (<a class=quiet href="#ybounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_ybounds_tip)">y-bounds</a> (<a class=quiet href="#selectedsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>) (<a class=quiet href="#selectedchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedchannel_tip)">selected-channel</a>)) (list -1.0 1.0))) - #t) +<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> -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 + +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- selection-maxamp-position --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="selectionmaxampposition">selection-maxamp-position</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -selection-maxamp-position returns the location (a sample number) of the peak amplitude of the selection in the given channel. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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? --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="selectionmember">selection-member?</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -selection-member? returns #t if the given channel has data that is currently selected. +<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 -<pre> - (set! (<em class=red>selection-member?</em> #t) #f) +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> -ie equivalent to unselect-all. -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>i.e. equivalent to unselect-all. +</p> +<div class="spacer"></div> <!-- selection->mix --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="selectiontomix">selection->mix</a></code> -</td></tr><tr><td></td><td> -selection->mix turns the current selection into a mix, or into several sync'd mixes if the selection +<pre class="indented"> +<em class=def id="selectiontomix">selection->mix</em> +</pre> + +<p>selection->mix turns the current selection into a mix, or into several sync'd mixes if the selection has more than one channel. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- selection-position --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="selectionposition">selection-position</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -selection-position is the sample where selection begins. +<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="#selectionframes" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectionframes_tip)">selection-frames</a>) changes to reflect the +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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- selection-srate --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="selectionsrate">selection-srate</a></code> -</td></tr><tr><td></td><td> -This function returns the selection srate. There's some arbitrariness in this if the sounds that make up the selection have different sampling rates. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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? --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="selectionok">selection?</a> obj</code> -</td></tr><tr><td></td><td> -selection? returns #t if there is a 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. -<pre> - :<em class=typing>(select-all)</em> - <em class=listener>#<region 2></em> - :<em class=typing>(selection?)</em> - <em class=listener>#t</em> - :<em class=typing>(set! (selection-member? #t) #f)</em> - <em class=listener>#f</em> - :<em class=typing>(selection?)</em> - <em class=listener>#f</em> +</p> + +<pre class="indented"> +> (select-all) +#<region 2> +> (selection?) +#t +> (set! (selection-member? #t) #f) +#f +> (selection?) +#f </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- show-selection --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="showselection">show-selection</a></code> -</td></tr><tr><td></td><td> -show-selection finds the bounds of the current selection (in all channels), and +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- smooth-selection --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="smoothselection">smooth-selection</a></code> -</td></tr><tr><td></td><td> -smooth-selection applies a smoothing function to the selection, producing a sinusoid between +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- src-selection --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="srcsoundselection">src-selection</a> num-or-env <em class=narg>base</em></code> -</td></tr><tr><td></td><td> -src-selection applies sampling rate conversion to the 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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- unselect-all --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="unselectall">unselect-all</a></code> -</td></tr><tr><td></td><td> -If there is currently a selection, this deactivates (unselects) it. -</td></tr> +<pre class="indented"> +<em class=def id="unselectall">unselect-all</em> +</pre> + +<p>If there is currently a selection, this deactivates (unselects) it. +</p> -</table> -<br> <!-- INDEX selectionstuff:Selections --> -<TABLE border=3 bordercolor="tan" hspace=20><tr><td> -<small><blockquote> -show the current selection: <a href="#showselection">show-selection</a><br> -color of selected portion: <a href="#selectioncolor">selection-color</a><br> -set whether creating a selection creates a region: <a href="#selectioncreatesregion">selection-creates-region</a><br> -fft graph refers to the selection: <a href="#showselectiontransform">show-selection-transform</a><br> -hook called when selection stops playing: <a href="#stopplayingselectionhook">stop-playing-selection-hook</a><br> + +<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> -evaluate func on each sample of selection: <a href="sndscm.html#evaloverselection">eval-over-selection</a> (map-selection in effect)<br> -selection members as list of lists of sounds and channels: <a href="sndscm.html#selectionmembers">selection-members</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="#deleteselectionandsmooth">delete-selection-and-smooth</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> @@ -5998,35 +6426,35 @@ append selection: <a href="sndscm.html#menusdoc">append-selection</a><br> write selection to a file: <a href="sndscm.html#menusdoc">selection->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="#filterselection">filter-selection</a>, <a href="sndscm.html#filterselectionandsmooth">filter-selection-and-smooth</a><br> -turn the selection into a mix: <a href="#selectiontomix">selection->mix</a><br> -unselect everything: <a href="#unselectall">unselect-all</a><br> -<br> -</blockquote></small> +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->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-frames. +<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> -<table border=0 cellpadding=5 hspace=20><tr><td><pre> + +<pre class="indented"> (define (make-section . members) ;; each member is '(beg dur snd chn) (append (list 'Section) members)) (define (section-for-each func section) ;; call func on each member of the section - (<a class=quiet href="#asoneedit" onmouseout="UnTip()" onmouseover="Tip(extsnd_asoneedit_tip)">as-one-edit</a> (lambda () (for-each func (cdr 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" onmouseout="UnTip()" onmouseover="Tip(extsnd_scalechannel_tip)">scale-channel</a> (append (list .5) sect))) + (apply <a class=quiet href="#scalechannel">scale-channel</a> (append (list .5) sect))) (make-section (list 0 10000 0 0) (list 30000 10000 0 0))) -</pre></td></tr></table> +</pre> + -<br><br><br> -<table width="50%" border=0><tr><td bgcolor="lightgreen" valign="middle"><h3><A NAME="sndsounds">Sounds and channels</a></h3></td></tr></table> +<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 @@ -6034,37 +6462,29 @@ 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, <code>(set! (amp-control-bounds) '(0.0 2.0))</code> +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 -<code>(set! (amp-control-bounds snd) '(0.0 2.0))</code> sets it only for the sound referred to by 'snd'. +(set! (amp-control-bounds snd) '(0.0 2.0)) sets it only for the sound referred to by 'snd'. </p> -<p>Many of the procedures also have an 'edpos' argument (standing for "edit position"). +<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), the constant <a name="currenteditposition">current-edit-position</a> (the default), or a function -of two arguments, the sound and the channel number. The function should return the -desired edit history position. In most cases, you should only refer to edits in the past -(that is, 'edpos' should be less than or equal to the current edit-position); in a few -situations, you can make use of data in the "redo" section of the edit-history list, but -nothing is guaranteed. +the operation is applied), or the constant current-edit-position. </p> -<table border=1 hspace=100 cellpadding=10> -<tr><td> -<p> -<A NAME="regularizedargs"></a> +<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_sync_tip)">sync</a> field is followed, and so on. Rather than make a bunch of backwards +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" onmouseout="UnTip()" onmouseover="Tip(extsnd_sync_tip)">sync</a> field is ignored, an unspecified sound argument applies only to the +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> +<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 @@ -6073,8 +6493,8 @@ The following substitutions can be made: <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="#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="#vcttochannel">vct->channel</a> vct 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 @@ -6082,36 +6502,36 @@ The following substitutions can be made: <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" onmouseout="UnTip()" onmouseover="Tip(extsnd_makesampler_tip)">make-sampler</a> which confusingly interpolates +<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> (define* (read-channel (beg 0) snd chn edpos (direction 1)) - (<a class=quiet href="#makesampler" onmouseout="UnTip()" onmouseover="Tip(extsnd_makesampler_tip)">make-sampler</a> beg snd chn direction edpos)) + +<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: -<code>(pad-channel 100 0 snd chn 2)</code>? +(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): <code>(scale-channel 1.0 0 #f snd chn 2)</code> +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> -</td></tr></table> - -<br> -<!-- -------------------------------- SOUND AND CHANNEL TABLE -------------------------------- --> +<!-- SOUND AND CHANNEL TABLE --> +<div class="separator"></div> -<table border=0 cellspacing=4 cellpadding=6 hspace=10> <!-- add-player --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="addplayer">add-player</a> player <em class=narg>start end edpos stop-proc out-chan</em></code> -</td></tr><tr><td width=30></td><td> -add-player adds 'player' to the play-list (see <a href="#makeplayer">make-player</a>). +<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 @@ -6120,23 +6540,27 @@ The 'out-chan' argument is the audio output channel to send the data to; it defa 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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- axis-info --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="axisinfo">axis-info</a> <em class=narg>snd chn grf</em></code> -</td></tr><tr><td><br></td><td> -axis-info returns a list describing the specified axis: -<pre> - (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 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> -This can be +<p>This can be useful if you're drawing arbitrary figures in a graph. 'grf' defaults to -<code>time-graph</code>; the other choices are <code>transform-graph</code> and <code>lisp-graph</code>. +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). @@ -6146,108 +6570,92 @@ several channels share one drawing area. You can use it to translate mouse coor to channel number in that situation. For example, <a href="#xtoposition">x->position</a> could be: +</p> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define (x->position-1 x snd chn) - (let* ((axinfo (<em class=red>axis-info</em> snd chn <a class=quiet onmouseout="UnTip()" onmouseover="Tip(extsnd_time_graph_tip)">time-graph</a>)) - (x0 (list-ref axinfo 2)) - (x1 (list-ref axinfo 4)) - (axis-left (list-ref axinfo 10)) - (axis-right (list-ref axinfo 12))) + (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></td></tr></table> +</pre> -Here's a key binding that uses axis-info to save every channel's graph position upon "Page Down", +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(<a class=quiet href="#bindkey" onmouseout="UnTip()" onmouseover="Tip(extsnd_bindkey_tip)">bind-key</a> "Page_Down" 0 +<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_filename_tip)">file-name</a> snd)))) - (do ((i 0 (+ 1 i))) - ((= i (<a class=quiet href="#channels" onmouseout="UnTip()" onmouseover="Tip(extsnd_channels_tip)">channels</a> snd)) data) + (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_sounds_tip)">sounds</a>)))) - (<a class=quiet href="#bindkey" onmouseout="UnTip()" onmouseover="Tip(extsnd_bindkey_tip)">bind-key</a> "Page_Up" 0 + (<a class=quiet href="#sounds">sounds</a>)))) + (<a class=quiet href="#bindkey">bind-key</a> "Page_Up" 0 (lambda () (if last-page-state (for-each (lambda (lst) - (let ((snd (list-ref lst 0)) - (name (list-ref lst 1))) - (if (and (<a class=quiet href="#soundp" onmouseout="UnTip()" onmouseover="Tip(extsnd_soundp_tip)">sound?</a> snd) - (string=? (<a class=quiet href="#filename" onmouseout="UnTip()" onmouseover="Tip(extsnd_filename_tip)">file-name</a> snd) name)) + (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 (list-ref chan-data 0)) - (x0 (list-ref chan-data 3)) - (x1 (list-ref chan-data 5)) - (y0 (list-ref chan-data 4)) - (y1 (list-ref chan-data 6))) - (set! (<a class=quiet href="#xbounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_xbounds_tip)">x-bounds</a> snd chn) (list x0 x1)) - (set! (<a class=quiet href="#ybounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_ybounds_tip)">y-bounds</a> snd chn) (list y0 y1)))) + (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></td></tr></table> -</td></tr><tr><td colspan=2 height=18></td></tr> +</pre> +<div class="separator"></div> <!-- beats-per-measure --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="beatspermeasure">beats-per-measure</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -The x axis labelling of the time domain waveform can be in measures -(<a class=quiet href="#xaxisstyle" onmouseout="UnTip()" onmouseover="Tip(extsnd_xaxisstyle_tip)">x-axis-style</a> = <code>x-axis-in-measures</code>); this variable sets the number of 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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- beats-per-minute --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="beatsperminute">beats-per-minute</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -The x axis labelling of the time domain waveform can be in beats -(<a class=quiet href="#xaxisstyle" onmouseout="UnTip()" onmouseover="Tip(extsnd_xaxisstyle_tip)">x-axis-style</a> = <code>x-axis-in-beats</code>) or in measures -(<code>x-axis-in-measures</code>); this variable sets the number of beats per minute. -The default is 60.0, making it the same as <code>x-axis-in-seconds</code>. -See <a href="#snpmark">snap-mark-to-beat</a>, or <a href="sndscm.html#snapmixtobeat">snap-mix-to-beat</a>. -</td></tr><tr><td colspan=2 height=18></td></tr> - - -<!-- bomb --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="bomb">bomb</a> <em class=narg>snd on</em></code> -</td></tr><tr><td></td><td> -bomb displays an exploding bomb icon next to 'snd's' name (in the minibuffer area). Set 'on' to #f to erase the bomb. Each time bomb -is called, the bomb icon moves to the next image in its sequence (showing the bomb's fuse burning down), -restarting the sequence whenever it reaches the end. This icon is used when a sound and its underlying file -get out of sync somehow (<a href="#autoupdate">auto-update</a>). - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define show-bomb - (lambda (n speed) - (if (> n 0) - (begin - (<em class=red>bomb</em>) - (<a class=quiet href="#gin" onmouseout="UnTip()" onmouseover="Tip(extsnd_gin_tip)">in</a> speed (lambda () (show-bomb (- n 1) speed)))) - (<em class=red>bomb</em> 0 #f)))) +<pre class="indented"> +<em class=def id="beatsperminute">beats-per-minute</em> snd chn +</pre> -(show-bomb 15 200) ; there are 15 images in the sequence -</pre></td></tr></table> -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="channelampenvs">channel-amp-envs</a> <em class=narg>file chan size peak-file-func work-proc-func</em></code> -</td></tr><tr><td></td><td> -channel-amp-envs returns two vcts of length 'size' containing the peak-amp envelopes of the channel 'chan' of file 'file'. +<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 vcts 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. @@ -6255,304 +6663,339 @@ The arguments to 'peak-file-func' are the file and the channel. If it returns a 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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- channel-data --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="channeldata">channel-data</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -channel-data provides very low-level access to the data currently in the given channel's sample buffers. +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- channel-properties --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="channelproperties">channel-properties</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -channel-properties is a property list associated with a channel. It is set to '() at the time a sound is opened, so +<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. -<br><br> -Traditionally in Lisp, a property list has been treated as an association list. This is a 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: -<pre> - (cons (cons key value) a-list) +</p> + +<pre class="indented"> +(cons (cons key value) a-list) </pre> -In Common Lisp, property lists have other properties, so to speak, but channel-properties (and + +<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). -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- channel-property --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="channelproperty">channel-property</a> key snd chn</code> -</td></tr><tr><td></td><td> -channel-property returns the value associated with 'key' in the given channel's +<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. -<pre> - Scheme: - :<em class=typing>(set! (channel-property 'info 0 0) "this is sound 0, first channel")</em> - <em class=listener>"this is sound 0, first channel"</em> - :<em class=typing>(channel-property 'info 0 0)</em> - <em class=listener>"this is sound 0, first channel"</em> - - Ruby: - ><em class=typing>set_channel_property(:info, "this is info", 0, 0)</em> - <em class=listener>this is info</em> - ><em class=typing>channel_property(:info, 0, 0)</em> - <em class=listener>this is info</em> - - Forth: - ><em class=typing>'info "this is info" 0 0 set-channel-property</em> - <em class=listener>'( '( 'info . this is info ) )</em> - ><em class=typing>'info 0 0 channel-property</em> - <em class=listener>this is info</em> -</pre> -The property list is convenient because the associated information goes away automatically +</p> + +<pre class="indented"> +Scheme: +> (set! (channel-property 'info 0 0) "this is sound 0, first channel") +"this is sound 0, first channel" +> (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>. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- channel-style --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="channelstyle">channel-style</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -channel-style reflects the value of the '<a href="snd.html#unitebutton">unite</a>' button in multichannel files. -Possible values are <code>channels-separate</code>, <code>channels-combined</code> (the default), and <code>channels-superimposed</code>. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(hook-push <a class=quiet href="#afteropenhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_afteropenhook_tip)">after-open-hook</a> - (lambda (snd) - (if (> (<a class=quiet href="#chans" onmouseout="UnTip()" onmouseover="Tip(extsnd_chans_tip)">channels</a> snd) 4) - (set! (<em class=red>channel-style</em> snd) <a class=quiet href="#channelstyle" onmouseout="UnTip()" onmouseover="Tip(extsnd_channelstyle_tip)">channels-combined</a>)))) -</pre></td></tr></table> -</td></tr><tr><td colspan=2 height=18></td></tr> +<pre class="indented"> +(hook-push <a class=quiet href="#afteropenhook">after-open-hook</a> + (lambda (hook) + (if (> (<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->vct --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="channeltovct">channel->vct</a> <em class=narg>beg dur snd chn edpos</em></code> -</td></tr><tr><td></td><td> -channel->vct returns a vct with the specified data. In Ruby, the "->" in a function name is translated to "2", +<pre class="indented"> +<em class=def id="channeltovct">channel->vct</em> beg dur snd chn edpos +</pre> + +<p id="selection2vct">channel->vct returns a vct with the specified data. In Ruby, the "->" in a function name is translated to "2", so the function call is: -<pre> v = channel2vct(0, 100) +</p> + +<pre class="indented"> v = channel2vct(0, 100) </pre> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -<A NAME="selection2vct"></a>(define* (selection->vct snd chn) - (if (<a class=quiet href="#selectionmember" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectionmember_tip)">selection-member?</a> snd chn) - (<em class=red>channel->vct</em> (<a class=quiet href="#selectionposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectionposition_tip)">selection-position</a> snd chn) - (<a class=quiet href="#selectionframes" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectionframes_tip)">selection-frames</a> snd chn) +<pre class="indented"> +(define* (selection->vct snd chn) + (if (<a class=quiet href="#selectionmember">selection-member?</a> snd chn) + (<em class=red>channel->vct</em> (<a class=quiet href="#selectionposition">selection-position</a> snd chn) + (<a class=quiet href="#selectionframples">selection-framples</a> snd chn) snd chn) - (if (<a class=quiet href="#selectionok" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectionok_tip)">selection?</a>) - (throw 'no-such-channel + (if (<a class=quiet href="#selectionok">selection?</a>) + (error 'no-such-channel (list "selection->vct" - (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "snd ~A channel ~D is not a member of the selection" snd chn))) - (throw 'no-active-selection (list "selection->vct"))))) -</pre></td></tr></table> -See also mark-explode in marks.scm. -</td></tr><tr><td colspan=2 height=18></td></tr> + (<a class=quiet>format</a> #f "snd ~A channel ~D is not a member of the selection" snd chn))) + (error 'no-active-selection (list "selection->vct"))))) +</pre> + +<p>See also mark-explode in marks.scm. +</p> +<div class="separator"></div> <!-- channels --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="channels">channels</a> <em class=narg>snd</em></code> -<br><code><a class=def name="chans">chans</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This function returns the number of channels in 'snd'. It can be set, but the result is a new +<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: -<code>(set! (channels) 2)</code>; this is not undo-able (except by calling it again with the +(set! (channels) 2); this is not undo-able (except by calling it again with the original number of channels — the data is not touched). -</td></tr><tr><td colspan=2 height=18></td></tr> - - -<!-- clear-minibuffer --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="clearminibuffer">clear-minibuffer</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This clears the sound's minibuffer area (both the text and the error message widgets). -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- clm-channel --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="clmchannel">clm-channel</a> clm-gen <em class=narg>beg dur snd chn edpos overlap origin</em></code> -</td></tr><tr><td></td><td> -clm-channel applies 'clm-gen' to the given channel starting +<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_regularizedargs_tip)">regularized</a> functions, but it can also be used directly: +This is used by some of the <a class=quiet href="#regularizedargs">regularized</a> functions, but it can also be used directly: +</p> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>) (car (<a class=quiet href="#sounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_sounds_tip)">sounds</a>)))) - (chn (or nchn (<a class=quiet href="#selectedchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedchannel_tip)">selected-channel</a>))) - (dur (or ndur (- (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a> snd chn) beg))) + (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_makesampler_tip)">make-sampler</a> beg snd chn 1 edpos)) - (cgen (<a class=quiet href="sndclm.html#make-convolve" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_convolve_tip)">make-convolve</a> :filter kernel + (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_readsample_tip)">read-sample</a> reader))))) + (<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_freesampler_tip)">free-sampler</a> reader))) + (<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" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_two_zero_tip)">make-two-zero</a> 1 -1))) -(define (wobble) (<em class=red>clm-channel</em> (<a class=quiet href="sndclm.html#make-ncos" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_ncos_tip)">make-ncos</a> 50 3))) -(define (hold-nose) (<em class=red>clm-channel</em> (<a class=quiet href="sndclm.html#make-ncos" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_ncos_tip)">make-ncos</a> 1 3))) -(define (bad-reception) (<em class=red>clm-channel</em> (<a class=quiet href="sndclm.html#make-ncos" onmouseout="UnTip()" onmouseover="Tip(sndclm_ncos_tip)">make-ncos</a> 10 5))) -</pre></td></tr></table> -</td></tr><tr><td colspan=2 height=18></td></tr> +(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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="closesound">close-sound</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This closes 'snd' (the same as the File:Close menu item). To close all sounds: -<pre> - (close-sound #t) - ;; equivalent to: - (for-each close-sound (<a class=quiet href="#sounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_sounds_tip)">sounds</a>)) +<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> -Before the sound is actually closed, <a class=quiet href="#beforeclosehook" onmouseout="UnTip()" onmouseover="Tip(extsnd_beforeclosehook_tip)">before-close-hook</a> -is called, then <a class=quiet href="#closehook" onmouseout="UnTip()" onmouseover="Tip(extsnd_closehook_tip)">close-hook</a>, + +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- comment --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="comment">comment</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This returns the sound's comment, if any; when a sound is opened, the comment is taken from the file's header +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- main-index |convolvewith:convolution reverb --> <!-- convolve-with --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="convolvewith">convolve-with</a> file <em class=narg>amp snd chn edpos</em></code> -</td></tr><tr><td></td><td> -This convolves the given channel (or the currently sync'd data) +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define conrev (lambda (impulse amp) (<em class=red>convolve-with</em> impulse amp) - (<a class=quiet href="#savesoundas" onmouseout="UnTip()" onmouseover="Tip(extsnd_savesoundas_tip)">save-sound-as</a> "reverb.snd") ;let mix scalers set reverb amount - (<a class=quiet href="#revertsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_revertsound_tip)">revert-sound</a>) + (<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></td></tr></table> -</td></tr><tr><td colspan=2 height=18></td></tr> +</pre> +<div class="separator"></div> <!-- count-matches --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="countmatches">count-matches</a> proc <em class=narg>sample snd chn edpos</em></code> -</td></tr><tr><td></td><td> -This returns how many samples satisfy the function 'proc'; 'proc' should +<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. -<pre> - Scheme: (count-matches (lambda (y) (> y .1))) - - Ruby: count_matches(lambda do |y| y > 0.1 end) +</p> - Forth: lambda: <{ y }> y 0.1 f- f0< ; count-matches +<pre class="indented"> +Scheme: (count-matches (lambda (y) (> y .1))) +Ruby: count_matches(lambda do |y| y > 0.1 end) +Forth: lambda: <{ y }> y 0.1 f- f0< ; count-matches </pre> -count-matches is modelled after Emacs. It could be defined along these lines: +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define (count-matches proc) - (let ((count 0)) - (<a class=quiet href="#scanchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_scanchannel_tip)">scan-channel</a> - (lambda (y) - (if (proc y) (set! count (+ count 1))) - #f)) - count)) -</pre></td></tr></table> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- cursor --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="cursor">cursor</a> <em class=narg>snd chn edpos</em></code> -</td></tr><tr><td></td><td> -This returns the cursor location (as a sample number; the first sample is numbered 0) in channel 'chn' of 'snd'. +<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. +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 --> -<A NAME="cursorexamples"></a> -<br> -<TABLE border=3 bordercolor="tan" hspace=20 vspace=10><tr><td> +<TABLE class="method"> +<tr><th class="title">Cursor</th></tr> +<tr><td> <blockquote><small> -<br> -Tracking cursor: <a href="#withtrackingcursor">with-tracking-cursor</a> (cursor-follows-play was the old name)<br> -Change cursor shape or size: <a href="#cursorstyle">cursor-style</a>, <a href="#cursorsize">cursor-size</a><br> +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="#withverbosecursor">with-verbose cursor</a><br> -<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> -</td></tr><tr><td colspan=2 height=18></td></tr> - +<div class="separator"></div> -<!-- cursor-follows-play --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="cursorfollowsplay">cursor-follows-play</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This is #t if the cursor is following along in the sound as it plays. The new name of this variable -is <a href="#withtrackingcursor">with-tracking-cursor</a>. -</td></tr><tr><td colspan=2 height=18></td></tr> <!-- cursor-position --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="cursorposition">cursor-position</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This gives the current cursor position as a list (x y). +<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->x</a> and <a href="#positiontoy">position->y</a>: -<pre> - (<a class=quiet href="#positiontox" onmouseout="UnTip()" onmouseover="Tip(extsnd_positiontox_tip)">position->x</a> (car (cursor-position))) - ;; equals: - (/ (<a class=quiet href="#cursor" onmouseout="UnTip()" onmouseover="Tip(extsnd_cursor_tip)">cursor</a>) (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a>)) +</p> + +<pre class="indented"> +(<a class=quiet href="#positiontox">position->x</a> (car (cursor-position))) +;; equals: +(/ (<a class=quiet href="#cursor">cursor</a>) (<a class=quiet href="#srate">srate</a>)) </pre> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- cursor-size --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="cursorsize">cursor-size</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This gives the cursor size in pixels; it defaults to 15. <code>(set! (cursor-size) 30)</code> makes the cursor twice as big as usual. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="cursorstyle">cursor-style</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -The cursor style is <code>cursor-cross</code>, <code>cursor-line</code>, or a cursor-drawing function. +<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 @@ -6562,199 +7005,138 @@ 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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define (<A NAME="xcursor">x-cursor</a> snd chn ax) +<pre class="indented"> +(define (x-cursor snd chn ax) (let* ((point (<em class=red>cursor-position</em>)) (x (car point)) (y (cadr point)) (size (<em class=red>cursor-size</em>)) (cr (make-cairo (car (channel-widgets snd chn))))) ; needed in Gtk, ignored in Motif - (<a class=quiet href="#drawline" onmouseout="UnTip()" onmouseover="Tip(extsnd_drawline_tip)">draw-line</a> (- x size) (- y size) (+ x size) (+ y size) snd chn <em class=red>cursor-context</em> cr) - (<a class=quiet href="#drawline" onmouseout="UnTip()" onmouseover="Tip(extsnd_drawline_tip)">draw-line</a> (- x size) (+ y size) (+ x size) (- y size) snd chn <em class=red>cursor-context</em> cr) + (<a class=quiet href="#drawline">draw-line</a> (- x size) (- y size) (+ x size) (+ y size) snd chn <em class=red>cursor-context</em> cr) + (<a class=quiet href="#drawline">draw-line</a> (- x size) (+ y size) (+ x size) (- y size) snd chn <em class=red>cursor-context</em> cr) (free-cairo cr))) (set! (<em class=red>cursor-style</em>) x-cursor) -</pre></td></tr></table> -</td></tr><tr><td colspan=2 height=18></td></tr> - - -<!-- data-format --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="dataformat">data-format</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This returns the sound's data format — the encoding used for the sound samples (e.g. mus-bshort). - -<br><br> -The standard formats nowadays are <code>mus-bshort</code> (big-endian 16-bit integers), <code>mus-bfloat</code> -(32-bit big-endian floats), and <code>mus-bint</code> (32-bit big-endian integers), and the -corresponding little-endian versions: <code>mus-lshort</code>, <code>mus-lfloat</code>, and <code>mus-lint</code>. -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: <code>mus-mulaw</code> and <code>mus-alaw</code> (kludges for a kind of 8-bit float), -<code>mus-byte</code> and <code>mus-ubyte</code> (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 — Perry Cook's book "Real Sound Synthesis" -has examples. - -<br><br> -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" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a>, <a class=quiet href="#datalocation" onmouseout="UnTip()" onmouseover="Tip(extsnd_datalocation_tip)">data-location</a>, -<a class=quiet href="#headertype" onmouseout="UnTip()" onmouseover="Tip(extsnd_headertype_tip)">header-type</a>, and <a class=quiet href="#channels" onmouseout="UnTip()" onmouseover="Tip(extsnd_channels_tip)">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, -<pre> - (set! (data-format) <a class=quiet href="#dataformat" onmouseout="UnTip()" onmouseover="Tip(extsnd_dataformat_tip)">mus-ubyte</a>) </pre> -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" onmouseout="UnTip()" onmouseover="Tip(extsnd_ybounds_tip)">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" onmouseout="UnTip()" onmouseover="Tip(extsnd_ybounds_tip)">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: - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(hook-push <a class=quiet href="#afteropenhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_afteropenhook_tip)">after-open-hook</a> - (lambda (snd) - ;; this could also (alternatively) set the y-bounds as above - (if (= (<em class=red>data-format</em> snd) mus-lint) - (set! (<em class=red>data-format</em> snd) mus-lintn)))) -</pre></td></tr></table> - -or (an alternative that sets the underlying database entry, rather than the current in-Snd choice): - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(hook-push <a class=quiet href="#openhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_openhook_tip)">open-hook</a> - (lambda (name) - (if (= (<a class=quiet href="#mussounddataformat" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussounddataformat_tip)">mus-sound-data-format</a> name) mus-lint) - (set! (<a class=quiet href="#mussounddataformat" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussounddataformat_tip)">mus-sound-data-format</a> name) mus-lintn)) - #f)) -</pre></td></tr></table> - -If you set any of these fields, the sound's index may change (there can be an embedded <a class=quiet href="#updatesound" onmouseout="UnTip()" onmouseover="Tip(extsnd_updatesound_tip)">update-sound</a>). -To deal with MPEG, OGG, Flac, or Speex files, see examp.scm (<a class=quiet href="sndscm.html#mpg" onmouseout="UnTip()" onmouseover="Tip(sndscm_mpg_tip)">mpg</a>) or misc.scm (mpg123 and ogg123). -Octave/WaveLab ASCII files can be translated by read-ascii (examp.scm). -<br><br> -To turn a data-format number into a string, use <a href="#musdataformatname">mus-data-format-name</a>. To get -the data format of some sound file, use <a href="#mussounddataformat">mus-sound-data-format</a>. -The default output (<a class=quiet href="#newsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_newsound_tip)">new-sound</a>, and -<a class=quiet href="#savesoundas" onmouseout="UnTip()" onmouseover="Tip(extsnd_savesoundas_tip)">save-sound-as</a>) data-format is <a href="#defaultoutputdataformat">default-output-data-format</a>. -To change a sound file's data-format, use <a href="#savesoundas">save-sound-as</a>. -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- data-location --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="datalocation">data-location</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This gives the location (in bytes) of the sound samples in the file represented by 'snd'. In a raw (headerless) file, +<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 — it is a law of nature that you will forget the original setting!), the underlying file is immediately rewritten. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- data-size --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="datasize">data-size</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This gives the size (in bytes) of the sound data in the file represented by 'snd'. +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- delete-sample --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="deletesample">delete-sample</a> samp <em class=narg>snd chn edpos</em></code> -</td></tr><tr><td></td><td> -This deletes sample 'samp' in the given channel. +<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 --> -<A NAME="deletionexamples"></a> -<br><br> -<TABLE border=3 bordercolor="tan" hspace=20><tr><td> -<small><blockquote> -delete a file: use the Scheme function delete-file, Ruby's File.delete, or Forth's file-delete<br> -delete a region: <a href="#forgetregion">forget-region</a><br> -delete the currently selected samples: <a href="#deleteselection">delete-selection</a><br> -delete the selection and smooth the splice: <a href="#deleteselectionandsmooth">delete-selection-and-smooth</a><br> -delete a mark or all marks: <a href="#deletemark">delete-mark</a><br> -delete a colormap: <a href="#deletecolormap">delete-colormap</a><br> -delete samples: <a href="#deletesamples">delete-samples</a><br> +<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="#mussoundforget">mus-sound-forget</a><br> -remove a menu item: <a href="#removefrommenu">remove-from-menu</a> or remove-main-menu in snd-motif.scm<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> Scheme delete funcs: remove-if assoc-remove! hash-remove! delete-if! delete! string-delete<br> -<br> -</blockquote></small> +</small></blockquote> </td></tr></TABLE> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> + + <!-- delete-samples --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="deletesamples">delete-samples</a> samp samps <em class=narg>snd chn edpos</em></code> -</td></tr><tr><td></td><td> -This deletes a block of samples. The deleted portion starts at sample 'samp' and runs for 'samps' samples. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="deletesamplesandsmooth">delete-samples-and-smooth</a> samp samps <em class=narg>snd chn edpos</em></code> -</td></tr><tr><td></td><td> -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. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="dotsize">dot-size</a> <em class=narg>snd chn</em></code> -</td></tr> -<tr><td></td><td> -This gives the size in pixels of dots when graphing with dots (default: 1); this affects <a href="#graphstyle">graph-styles</a> such as <code>graph-lollipops</code>. See <a href="#graphhook">graph-hook</a> or auto-dot in examp.scm. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="envchannel">env-channel</a> clm-env-gen <em class=narg>beg dur snd chn edpos</em></code> -</td></tr><tr><td></td><td> -env-channel is the <a class=quiet href="#regularizedargs" onmouseout="UnTip()" onmouseover="Tip(extsnd_regularizedargs_tip)">regularized</a> version of <a href="#envsound">env-sound</a>. 'clm-env-gen' +<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: -<pre> - (let ((dur (/ (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a>) (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a>)))) - (<em class=red>env-channel</em> (list 0 0 .1 1 (- dur .1) 1 dur 0))) +</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> -<A NAME="envexamples"></a> +<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="#defvar">defvar</a> (for CLM/Snd intercompatibility), -or with <a href="#defineenvelope">define-envelope</a>. +It can be declared via define just like any other variable, or with <a href="#defineenvelope">define-envelope</a>. +</p> + + <!-- INDEX envexamples:Envelopes --> -<br><br> -<TABLE border=3 bordercolor="tan" hspace=20><tr><td> +<TABLE class="method"> +<tr><th class="title">Envelopes</th></tr><tr><td> <blockquote><small> -<br> -envelopes in Snd:<br> 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> @@ -6764,55 +7146,60 @@ 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="#cosinechannelviaptree">cosine-channel-via-ptree</a>, <a href="sndclm.html#bellcurve">bell-curve</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="#powenvchannel">powenv-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> -<br> </small></blockquote> </td></tr></TABLE> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> + <!-- env-channel-with-base --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="envchannelwithbase">env-channel-with-base</a> envelope-or-env-gen <em class=narg>base beg dur snd chn edpos</em></code> -</td></tr><tr><td></td><td> -env-channel-with-base is a slight variation on env-channel. There are times when it's a bother +<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. -</td></tr> -<tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> + <!-- env-sound --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="envsound">env-sound</a> envelope <em class=narg>samp samps env-base snd chn edpos</em></code> -</td></tr><tr><td></td><td> -env-sound applies the amplitude 'envelope' to the given channel starting +<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 hspace=20 cellpadding=5><tr><td> -<img src="pix/ampenv1.png" alt="ampenvs" vpsace=10> -</td><td> -<pre> -(env-sound '(0 0 1 1 2 0)) - -env_sound([0.0, 0.0, 1.0, 1.0, 2.0, 0.0]) - -'( 0.0 0.0 1.0 1.0 2.0 0.0 ) env-sound -</pre> +<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> -As mentioned in <a href="sndclm.html#make-env">sndclm.html</a>, + +<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 @@ -6822,54 +7209,63 @@ out), and 'env-base' > 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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define (compare-exp k) - (let ((e (<a class=quiet href="sndclm.html#make-env" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_env_tip)">make-env</a> (list 0 1 1 (exp (- k))) :base (exp k) :length 11))) + (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndprint_tip)">snd-print</a> (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "~A ~A~%" (<a class=quiet href="sndclm.html#env" onmouseout="UnTip()" onmouseover="Tip(sndclm_env_tip)">env</a> e) (exp (* (- k) (/ i 10.0)))))))) -</pre></td></tr></table> + (<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> -If 'envelope' is a CLM env generator, 'env-base' +<p>If 'envelope' is a CLM env generator, 'env-base' is ignored. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- fft-log-frequency --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="fftlogfrequency">fft-log-frequency</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This returns whether the spectrum frequency axis is logarithmic (#t) or linear (#f, the default). If logarithmic, the lower end +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- fft-log-magnitude --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="fftlogmagnitude">fft-log-magnitude</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This returns whether the spectrum magnitude axis is in decibels (#t) or linear (#f, the default). If in decibels, the +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- fft-window --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="fftwindow">fft-window</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This sets the choice of fft data window (default: <code>blackman2-window</code>) -<pre> - 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 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 @@ -6877,101 +7273,113 @@ Fredric J. Harris, "On the Use of Windows for Harmonic Analysis with the Discret 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> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- fft-window-alpha --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="fftalpha">fft-window-alpha</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -The ultraspherical window has two "family" parameters; the one named "mu" is called "beta" here, +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- fft-window-beta --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="fftbeta">fft-window-beta</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -Some fft windows have a parameter, often named alpha or beta, that chooses one from a family of possible windows. +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- fft-with-phases --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="fftwithphases">fft-with-phases</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This returns whether the single FFT display includes phase information (the default is #f). -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="filename">file-name</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This returns the sound's complete (or "absolute") file name; the directory is included; see <a href="#shortfilename">short-file-name</a> +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- filter-channel --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="filterchannel">filter-channel</a> env <em class=narg>order beg dur snd chn edpos trunc origin</em></code> -</td></tr><tr><td></td><td> -The regularized version of filter-sound. If the end of the filtered portion is not the end of the sound, +<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 vct containing the desired coefficients. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- filter-sound --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="filtersound">filter-sound</a> env <em class=narg>order snd chn edpos origin</em></code> -</td></tr><tr><td></td><td> -filter-sound applies an FIR filter of order 'order' (actually one more than the nominal order) +<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 vct 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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<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> (<a class=quiet href="#vct" onmouseout="UnTip()" onmouseover="Tip(extsnd_vct_tip)">vct</a> .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" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_fir_filter_tip)">make-fir-filter</a> 6 (<a class=quiet href="#vct" onmouseout="UnTip()" onmouseover="Tip(extsnd_vct_tip)">vct</a> .1 .2 .3 .3 .2 .1))) ; CLM FIR filter -(<em class=red>filter-sound</em> (<a class=quiet href="sndclm.html#make-delay" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_delay_tip)">make-delay</a> 120)) ; CLM delay (same as insert-silence) -(<em class=red>filter-sound</em> (<a class=quiet href="sndclm.html#make-formant" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_formant_tip)">make-formant</a> 1200 .99)) ; CLM formant -(<em class=red>filter-sound</em> (<a class=quiet href="sndclm.html#make-filter" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_filter_tip)">make-filter</a> 2 (<a class=quiet href="#vct" onmouseout="UnTip()" onmouseover="Tip(extsnd_vct_tip)">vct</a> 1 -1) (<a class=quiet href="#vct" onmouseout="UnTip()" onmouseover="Tip(extsnd_vct_tip)">vct</a> 0 -0.99))) ; remove DC -</pre></td></tr></table> - -If you want to use the cascade filter structure, rather than the canonical +(<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> - (define (<a class=quiet href="sndscm.html#makebiquad" onmouseout="UnTip()" onmouseover="Tip(sndscm_makebiquad_tip)">make-biquad</a> a0 a1 a2 b1 b2) - (<a class=quiet href="sndclm.html#make-filter" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_filter_tip)">make-filter</a> 3 (<a class=quiet href="#vct" onmouseout="UnTip()" onmouseover="Tip(extsnd_vct_tip)">vct</a> a0 a1 a2) (<a class=quiet href="#vct" onmouseout="UnTip()" onmouseover="Tip(extsnd_vct_tip)">vct</a> 0.0 b1 b2))) +<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> -If you have coefficients for the cascade form, but have no scruples about using +<p>If you have coefficients for the cascade form, but have no scruples about using some other form, see cascade->canonical in dsp.scm, and the examples that follow. -<br><br> +</p> <!-- INDEX filtersinsnd:Filters --> -<TABLE border=3 bordercolor="tan" hspace=20> -<tr><td> -<blockquote><small> -<br> -<A NAME="filtersinsnd">Filters</a> in Snd:<br> -filter a sound: <a href="#filtersound">filter-sound</a>, <a href="#filterchannel">filter-channel</a>, and <a href="#clmchannel">clm-channel</a><br> -filter the selection: <a href="#filterselection">filter-selection</a>, <a href="sndscm.html#filterselectionandsmooth">filter-selection-and-smooth</a><br> + +<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> @@ -6982,7 +7390,7 @@ Butterworth filters: <a href="sndscm.html#makebutter">make-butter-high-pass</a>, 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, clean-channel in clean.scm, or stereo-flute in clm-ins.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> @@ -6995,142 +7403,116 @@ draw frequency response: use <a href="snd.html#editenvelope">envelope editor</a> 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> -FIR filter as virtual edit: <a href="sndscm.html#virtualfilterchannel">virtual-filter-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> -Scheme srfi-1 filter function: %filter.<br> -<br> </small></blockquote> -</td></tr> -</TABLE> -</td></tr><tr><td colspan=2 height=18></td></tr> - - -<!-- find-channel --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="findchannel">find-channel</a> proc <em class=narg>sample snd chn edpos</em></code> -</td></tr><tr><td></td><td> -This function finds the sample that satisfies the function 'proc'. 'sample' -determines where to start the search. - -<pre> -><em class=typing>(find-channel (lambda (y) (> y .1)))</em> -<em class=listener>4423</em> - -><em class=typing>lambda: <{ y }> 0.1 y f< ; find-channel</em> -<em class=listener>4423</em> -</pre> - -I didn't bring out the search direction (find-channel is built on scan-channel which assumes it is -scanning forwards), but it's not hard to write a function to find in reverse: +</td></tr></TABLE> +<div class="separator"></div> -<pre> -(define* (<A NAME="findchannelinreverse">find-channel-in-reverse</A> proc beg snd chn edpos) - (let* ((sample (or beg (- (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a> snd chn) 1))) ; or cursor? - (reader (<a class=quiet href="#makesampler" onmouseout="UnTip()" onmouseover="Tip(extsnd_makesampler_tip)">make-sampler</a> sample snd chn -1 edpos)) - (result #f)) - (do ((i sample (- i 1))) - ((or result (< i 0)) - (and result - (list result (+ 1 i)))) - (set! result (proc (reader)))))) -</pre> <!-- INDEX searchexamples:Searching --> -<A NAME="searchexamples"></a> -<TABLE border=3 bordercolor="tan" hspace=20 vspace=10><tr><td> -<blockquote><small> -<br> -find a mark: <a href="#findmark">find-mark</a><br> +<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="#findsound">find-sound</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> -Search via continuation: <a href="#scanagain">scan-again</a><br> -Explicit access to search procedures: <a href="#searchprocedure">search-procedure</a><br> -The Find dialog: <a href="snd.html#editoperations">Find</a> or <a href="#finddialog">find-dialog</a><br> -find silence: <a href="#mapsilence">map-silence</a>, scramble-channel in examp.scm<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> -see also <a href="#countmatches">count-matches</a> and <a href="#scanchannel">scan-channel</a><br> -search a multichannel sound: <a href="sndscm.html#scansound">scan-sound</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> -<br> </small></blockquote> </td></tr></TABLE> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- find-sound --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="findsound">find-sound</a> filename <em class=narg>nth</em></code> -</td></tr><tr><td></td><td> -find-sound returns the sound object of 'filename' or +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_shortfilename_tip)">short-file-name</a> snd) name) - (string=? (<a class=quiet href="#filename" onmouseout="UnTip()" onmouseover="Tip(extsnd_filename_tip)">file-name</a> snd) name)) + (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_sounds_tip)">sounds</a>)) + (<a class=quiet href="#sounds">sounds</a>)) #f))) -</pre></td></tr></table> +</pre> -See files-popup-buffer, open-next-file-in-directory, and the "Buffer Menu" code in examp.scm. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="finishprogressreport">finish-progress-report</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This ends an on-going progress report (a visual indication of how far along some time-consuming process is). +<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>. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> -<!-- frames --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="frames">frames</a> <em class=narg>snd chn edpos</em></code> -</td></tr><tr><td></td><td> -This returns current length in samples of the channel 'chn'. Used with set!, this either truncates +<!-- 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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- free-player --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="freeplayer">free-player</a> player</code> -</td></tr><tr><td></td><td> -free-player frees all resources associated with 'player' and remove it from the play-list. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="graph">graph</a> data <em class=narg>xlabel x0 x1 y0 y1 snd chn force-display show-axes-choice</em></code> -</td></tr><tr><td></td><td> -This function displays a graph of 'data' in a separate display per channel. The x axis +<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'. -<pre> - (graph (<a class=quiet href="#vct" onmouseout="UnTip()" onmouseover="Tip(extsnd_vct_tip)">vct</a> 0 .1 .2 .3 .4 .3 .2 .1 0) "roof") +</p> + +<pre class="indented"> +(graph (float-vector 0 .1 .2 .3 .4 .3 .2 .1 0) "roof") </pre> -The current slider values can be read from <a href="#xpositionslider">x-position-slider</a>, + +<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 vcts; 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). @@ -7138,70 +7520,78 @@ 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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define <A NAME="xdisplayenergy">display-energy</A> +<pre class="indented"> +(define display-energy ;; y-zoom-slider controls the graph amp (lambda (snd chn) - "display time domain data as energy" - (let* ((ls (<a class=quiet href="#leftsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_leftsample_tip)">left-sample</a>)) - (rs (<a class=quiet href="#rightsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_rightsample_tip)">right-sample</a>)) - (datal (<a class=quiet href="#makegraphdata" onmouseout="UnTip()" onmouseover="Tip(extsnd_makegraphdata_tip)">make-graph-data</a> snd chn)) - (data (if (<a class=quiet href="#vctp" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctp_tip)">vct?</a> datal) datal (cadr datal))) - (len (length data)) - (sr (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a> snd)) - (y-max (<a class=quiet href="#yzoomslider" onmouseout="UnTip()" onmouseover="Tip(extsnd_yzoomslider_tip)">y-zoom-slider</a> snd chn))) - (<a class=quiet href="#vctmultiply" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctmultiply_tip)">vct-multiply!</a> data data) + (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> display-energy) -</pre></td></tr></table> -<img src="pix/energy.png" alt="picture of examp.scm in action"> -</td></tr><tr><td colspan=2 height=18></td></tr> +(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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="graphstyle">graph-style</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -graph-style determines how sound data is displayed (default: <code>graph-lines</code>). +<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: -<pre> - graph-lines graph-dots graph-filled graph-lollipops graph-dots-and-lines +</p> + +<pre class="indented"> +graph-lines graph-dots graph-filled graph-lollipops graph-dots-and-lines </pre> -In the set! case, if no 'snd' is specified, all graph-styles are set to the + +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- graphs-horizontal --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="graphshorizontal">graphs-horizontal</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This determines whether channel graphs (the time domain, spectrum, and lisp graphs) -are arranged -<A class=quiet onmouseout="UnTip()" onmouseover="Tip('<img src=\'pix/bgd.png\' width=\'540\' height=\'360\'>', TITLE, '<code>(set! (graphs-horizontal) #f)</code>', ABOVE, true)">vertically</A> +<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). -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- grid-density --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="griddensity">grid-density</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This controls the spacing of axis ticks; the default is 1.0. If grid-density is less than 1.0, more ticks are squeezed +<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>). -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- header-type --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="headertype">header-type</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This returns the header type (e.g. <code>mus-aiff</code>) of the file that underlies 'snd'. +<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, @@ -7211,178 +7601,203 @@ Snd can read about 60 header types, and write 7 or so. 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 <code>mus-next</code> because it is simple, -and can handle any data format that Snd can write (whereas each of the others is restricted in this regard). -The writable header types are <code>mus-next</code>, <code>mus-nist</code>, -<code>mus-aiff</code> (obsolete, rarely needed), <code>mus-aifc</code>, <code>mus-riff</code>, <code>mus-rf64</code>, <code>mus-caff</code>, -<code>mus-ircam</code>, and <code>mus-raw</code> (no header). For technical descriptions of the headers, +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. -<br><br> -To turn a header type number into a string, use <a href="#musheadertypename">mus-header-type-name</a>. To get +</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" onmouseout="UnTip()" onmouseover="Tip(extsnd_newsound_tip)">new-sound</a>, and -<a class=quiet href="#savesoundas" onmouseout="UnTip()" onmouseover="Tip(extsnd_savesoundas_tip)">save-sound-as</a>) header type is <a href="#defaultoutputheadertype">default-output-header-type</a>. -<br><br> -To read or write your own headers (or some header that isn't built-in), +(<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). -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- insert-sample --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="insertsample">insert-sample</a> samp value <em class=narg>snd chn edpos</em></code> -</td></tr><tr><td></td><td> -This inserts sample 'value' at sample 'samp' in the given channel +<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 --> -<A NAME="insertionexamples"></a> -<TABLE border=3 bordercolor="tan" hspace=20 vspace=10><tr><td> -<small><blockquote> +<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="#padchannel">pad-channel</a>, <a href="#insertsilence">insert-silence</a>, <a href="sndscm.html#padsound">pad-sound</a><br> -insert a region: <a href="#insertregion">insert-region</a><br> -insert the selection: <a href="#insertselection">insert-selection</a><br> -insert a vct of samples: <a href="#insertsamples">insert-samples</a>, <a href="sndscm.html#insertvct">insert-vct</a><br> -insert a sound: <a href="#insertsound">insert-sound</a> or <a href="#insertfiledialog">insert-file-dialog</a><br> -append a sound and silence: <a href="#appendsound">append-sound</a><br> -insert a frame: <a href="sndscm.html#insertframe">insert-frame</a><br> -insert sound-data: <a href="sndscm.html#insertsounddata">insert-sound-data</a><br> -</blockquote></small> +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 vct 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> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> + <!-- insert-samples --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="insertsamples">insert-samples</a> samp samps data <em class=narg>snd chn edpos auto-delete origin</em></code> -</td></tr><tr><td></td><td> -This inserts 'samps' samples of 'data' (normally a vct) starting at sample 'samp' in the given channel. +<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 vct) starting at sample 'samp' in the given channel. 'data' can be a filename. -The regularized version of this is:<br> -<pre> - (define* (<a class=quiet href="sndscm.html#insertchannel" onmouseout="UnTip()" onmouseover="Tip(sndscm_insertchannel_tip)">insert-channel</a> data beg dur snd chn edpos) - (insert-samples beg dur data snd chn edpos)) +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> -To insert a block of samples of a given value: <code>(insert-samples beg dur (<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> dur val))</code> + +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- insert-silence --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="insertsilence">insert-silence</a> beg num <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This inserts 'num' zeros at 'beg' in the given channel. <a href="#padchannel">pad-channel</a> is the regularized version, +<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_sync_tip)">sync</a> -field, whereas <a class=quiet href="#padchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_padchannel_tip)">pad-channel</a> ignores it). -</td></tr><tr><td colspan=2 height=18></td></tr> +'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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="insertsound">insert-sound</a> file <em class=narg>beg in-chan snd chn edpos auto-delete</em></code> -</td></tr><tr><td></td><td> -This inserts channel 'in-chan' of 'file' at sample 'beg' in the given channel. +<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: -<pre> - (define* (<a name="appendsound">append-sound</a> file (silence 1.0)) - (<em class=red>insert-sound</em> file (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a>)) - (<em class=red>insert-silence</em> (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a>) (round (* (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a>) 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> -'file' is not deleted by Snd unless 'auto-delete' is #t. -</td></tr><tr><td colspan=2 height=18></td></tr> + +<p>'file' is not deleted by Snd unless 'auto-delete' is #t. +</p> +<div class="separator"></div> <!-- integer->sound --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="integertosound">integer->sound</a> i</code> -</td></tr><tr><td></td><td> -In olden times, a sound was handled in Snd code as an integer; nowadays, it's an object (although the integer approach still works). +<pre class="indented"> +<em class=def id="integertosound">integer->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->integer</a>, exist mainly to convert old code to the current style. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="separator"></div> <!-- left-sample --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="leftsample">left-sample</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This returns the position in samples of the left edge of the time domain +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define (<a class=quiet href="sndscm.html#windowsamples" onmouseout="UnTip()" onmouseover="Tip(sndscm_windowsamples_tip)">window-samples</a>) +<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 (+ 1 (- wr wl))))) -</pre></td></tr></table> +</pre> -See also <a href="#moveonepixel">move-one-pixel</a>. +<p id="movingwindows">See also <a href="#moveonepixel">move-one-pixel</a>. +</p> <!-- INDEX movingwindows:Window size and position --> -<A NAME="movingwindows"></a> -<TABLE border=3 bordercolor="tan" hspace=20 vspace=10><tr><td> +<TABLE class="method"> +<tr><th class="title">Time Domain Display</th></tr><tr><td> <blockquote><small> -<br> -time domain window:<br> Built-in keyboard commands: <a href="snd.html#movewindow">Moving the Window</a><br> -Specialized keyboard commands: <a href="#bindkey">bind-key</a><br> -Window size: <a href="#xzoomslider">x-zoom-slider</a>, <a href="#zoomonepixel">zoom-one-pixel</a>, <br> -Window position: <a href="#xpositionslider">x-position-slider</a>, <a href="#moveonepixel">move-one-pixel</a><br> -Window left edge: <a href="#leftsample">left-sample</a><br> -Window right edge: <a href="#rightsample">right-sample</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="#spectrumend">spectrum-end</a><br> -window start: <a href="#spectrumstart">spectrum-start</a><br> -relation to time domain: <a href="#beforetransformhook">before-transform-hook</a><br> -selection fft: <a href="#showselectiontransform">show-selection-transform</a><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="#axisinfo">axis-info</a><br> -<br> +Axis description: <a href="extsnd.html#axisinfo">axis-info</a><br> </small></blockquote> </td></tr></TABLE> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- lisp-graph? --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="lispgraphp">lisp-graph?</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -lisp-graph? returns #t if the lisp-generated graph is currently displayed ("lisp" here means any extension language). +<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>. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- lisp-graph-style --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="lispgraphstyle">lisp-graph-style</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This determines how lisp-generated data is displayed. +<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: -<pre> - graph-lines graph-dots graph-filled graph-lollipops graph-dots-and-lines +</p> + +<pre class="indented"> +graph-lines graph-dots graph-filled graph-lollipops graph-dots-and-lines </pre> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- make-player --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="makeplayer">make-player</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This function makes a new player associated with the given channel. +<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 @@ -7392,60 +7807,54 @@ the play with <a href="#startplaying">start-playing</a>, and stop it prematurely <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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define play-with-amps (lambda (sound . amps) - (let ((chans (<a class=quiet href="#chans" onmouseout="UnTip()" onmouseover="Tip(extsnd_chans_tip)">channels</a> sound))) + (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_ampcontrol_tip)">amp-control</a> player) (list-ref amps 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" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a> sound))))) + (<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></td></tr></table> -</td></tr> +</pre> -<tr><td></td><td> -See play-with-envs in enved.scm, +<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>. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- make-variable-graph --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="makevariablegraph">make-variable-graph</a> container <em class=narg>name length srate</em></code> -</td></tr><tr><td></td><td> -make-variable-graph is a part of the <a href="sndscm.html#variabledisplay" onmouseout="UnTip()" onmouseover="Tip('<img src=\'pix/vardpy.png\' width=\'250\' height=\'250\'>', TITLE, 'make-variable-display in snd-motif', ABOVE, true)">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>. -See oscope.scm. -</td></tr><tr><td colspan=2 height=18></td></tr> - +<pre class="indented"> +<em class=def id="makevariablegraph">make-variable-graph</em> container name length srate +</pre> -<!-- map-chan --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def>map-chan</a> func <em class=narg>start end edname snd chn edpos</em></code> -</td></tr><tr><td></td><td> -map-chan applies 'func' to samples in the specified channel. -It is the old ("irregular") version of <a href="#mapchannel">map-channel</a>. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="mapchannel">map-channel</a> func <em class=narg>beg dur snd chn edpos origin</em></code> -</td></tr><tr><td></td><td> -map-channel is one of the standard ways to change a sound. It applies 'func' to each sample +<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. -<br><br> -'func', a procedure of one argument (the current sample), +</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, @@ -7458,20 +7867,20 @@ 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: -<br> +</p> -<pre> +<pre class="indented"> Scheme: - ><em class=typing>(map-channel (lambda (y) (+ y 0.2)))</em> - <em class=listener>0</em> +> (map-channel (lambda (y) (+ y 0.2))) +0 Ruby: - ><em class=typing>map_channel(lambda do |y| y + 0.2 end)</em> - <em class=listener>-0.0015869140625</em> +>map_channel(lambda do |y| y + 0.2 end) +-0.0015869140625 Forth: - ><em class=typing>lambda: <{ y }> y 0.2 f+ ; map-channel</em> - <em class=listener>-0.00158691</em> +>lambda: <{ y }> y 0.2 f+ ; map-channel +-0.00158691 </pre> <p> @@ -7480,21 +7889,21 @@ 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> -<em class=listener>></em> <em class=typing>(let ((y0 0.0)) (map-channel (lambda (y) (let ((diff (- y y0))) (set! y0 y) diff))))</em> -<em class=listener>0</em> -<em class=listener>></em> <em class=typing>(let ((y0 0.0)) (map-channel (lambda (y) (let ((add (+ y y0))) (set! y0 add) add))))</em> -<em class=listener>0</em> -<em class=listener>></em> <em class=typing>(let ((rd (make-sampler 0 0 0 1 0))) (map-channel (lambda (y) (- y (rd)))))</em> -<em class=listener>0</em> ; the sampler is reading the unedited form of the sound -<em class=listener>></em> <em class=typing>(maxamp)</em> ; i.e. how big is the biggest difference -<em class=listener>0.0</em> -</pre> - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define* (<A NAME="cosinechannel">cosine-channel</a> (beg 0) dur snd chn edpos) +<pre class="indented"> +> (let ((y0 0.0)) (map-channel (lambda (y) (let ((diff (- y y0))) (set! y0 y) diff)))) +0 +> (let ((y0 0.0)) (map-channel (lambda (y) (let ((add (+ y y0))) (set! y0 add) add)))) +0 +> (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 +> (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) (<em class=red>map-channel</em> - (let* ((samps (or dur (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a> snd chn))) + (let* ((samps (or dur (<a class=quiet href="#framples">framples</a> snd chn))) (incr (/ pi samps)) (angle (* -0.5 pi))) (lambda (y) @@ -7502,34 +7911,37 @@ then check to see how close our reconstruction is to the original: (set! angle (+ angle incr)) val))) beg dur snd chn edpos)) -</pre></td></tr></table> +</pre> -Here's a slightly more involved example; +<p id="mapsilence">Here's a slightly more involved example; we define a function that finds silent portions and replaces them with something: +</p> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define (<A NAME="mapsilence">map-silence</a> in-silence replacement) - (let ((buffer (<a class=quiet href="sndclm.html#make-moving-average" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_moving_average_tip)">make-moving-average</a> 128)) +<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) - (let ((sum-of-squares (<a class=quiet href="sndclm.html#moving-average" onmouseout="UnTip()" onmouseover="Tip(sndclm_moving_average_tip)">moving-average</a> buffer (* y y)))) + (let ((sum-of-squares (<a class=quiet href="sndclm.html#moving-average">moving-average</a> buffer (* y y)))) (if (> sum-of-squares 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></td></tr></table> +</pre> -Here we're using 'buffer', a CLM <a href="sndclm.html#moving-average">moving-average</a> generator, to track the +<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. -<br><br> -It is possible to break out of a map, flushing any edits, via call-with-current-continuation: +</p> + +<p>It is possible to break out of a map, flushing any edits, via call-with-current-continuation: +</p> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define ctr 0) (call-with-current-continuation (lambda (return) @@ -7538,10 +7950,12 @@ It is possible to break out of a map, flushing any edits, via call-with-current- (if (> ctr 100) (return "quitting!") val))))) -</pre></td></tr></table> +</pre> -It is also possible to stop, then continue map-channel: -<table border=0 cellpadding=5 vspace=10><tr><td><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 @@ -7549,258 +7963,296 @@ It is also possible to stop, then continue map-channel: (if (> y 1.0) (begin (set! go-on stop) - (throw 'oops))))) + (error 'oops))))) .2)) -</pre></td></tr></table> +</pre> -If this hits a sample > 1.0, it will print 'oops and put the continuation in the variable 'go-on'. -<code>(go-on)</code> will continue where you left off. (I'm not sure how far this can be pushed, or +<p>If this hits a sample > 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 — you may end up with unclosed files and so on). -<br><br> -If the editing action is not mapping something over the current sound, it is +</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 <a class=quiet href="#vcttochannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_vcttochannel_tip)">vct->channel</a> for example). +will fit in memory (as in using float-vector->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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define* (map-sound-chans proc (beg 0) dur snd edpos origin) - (do ((i 0 (+ 1 i))) - ((= i (<a class=quiet href="#chans" onmouseout="UnTip()" onmouseover="Tip(extsnd_chans_tip)">channels</a> snd))) + (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></td></tr></table> +</pre> -An esoteric aside: map-channel sets up the sampler before calling the procedure, so if that procedure edits +<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,<br><pre> +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" onmouseout="UnTip()" onmouseover="Tip(extsnd_sample_tip)">sample</a> 0) 1.0)) + (if first (set! (<a class=quiet href="#sample">sample</a> 0) 1.0)) (set! first #f) (* y 2)))) </pre> -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" onmouseout="UnTip()" onmouseover="Tip(extsnd_sample_tip)">sample</a> 0) 1.0)</code> which the map-channel ignores. -</td></tr><tr><td colspan=2 height=18></td></tr> + +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="maxamp">maxamp</a> <em class=narg>snd chn edpos</em></code> -</td></tr><tr><td></td><td> -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" onmouseout="UnTip()" onmouseover="Tip(extsnd_scaleto_tip)">scale-to</a>. - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define (maxamp-all) - "(maxamp-all) returns the current maxamp of all currently open sounds" - (apply max (map (lambda (snd) (apply max (<em class=red>maxamp</em> snd #t))) (<a class=quiet href="#sounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_sounds_tip)">sounds</a>)))) -</pre></td></tr></table> +<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 --> -<A NAME="maxampexamples"></a> -<TABLE border=3 bordercolor="tan" hspace=20 vspace=10><tr><td> -<blockquote><small> -<br> -Sound file maxamp: <a href="#mussoundmaxamp">mus-sound-maxamp</a><br> -Region maxamp: <a href="#regionmaxamp">region-maxamp</a><br> -Selection maxamp: <a href="#selectionmaxamp">selection-maxamp</a><br> -Sound data object maxamp: <a href="#sounddatamaxamp">sound-data-maxamp</a><br> -Vct maxamp: <a href="#vctpeak">vct-peak</a><br> -To set the y axis bounds to reflect the channel's maxamp: <a href="#ybounds">y-bounds</a><br> +<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="#maxampposition">maxamp-position</a>, <a href="#regionmaxampposition">region-maxamp-position</a>, <a href="#selectionmaxampposition">selection-maxamp-position</a> -<br><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> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> + <!-- maxamp-position --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="maxampposition">maxamp-position</a> <em class=narg>snd chn edpos</em></code> -</td></tr><tr><td></td><td> -This gives the location (sample number) of the maximum sample in the given channel. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="maxfftpeaks">max-transform-peaks</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This returns the maximum number of transform peaks reported. +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- min-dB --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="mindb">min-dB</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This sets the minimum dB value displayed in various graphs (the default is -60.0). +<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). -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- new-sound --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="newsound">new-sound</a> <em class=narg>:file :header-type :data-format :srate :channels :comment :size</em></code> -</td></tr><tr><td></td><td> -new-sound creates a new sound named 'file'. The following function opens a new sound named "test.snd", +<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': -<pre> - (define (init-sound val dur) - (let ((ind (<em class=red>new-sound</em> "test.snd" :size dur))) - (<a class=quiet href="#mapchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_mapchannel_tip)">map-channel</a> (lambda (y) val)) - ind)) +</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> -If the 'header-type' and other + +<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. Data formats are (b=big-endian, l=little, u=unsigned): -<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 +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> -Header-types are: -<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 + +<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> -To be informed whenever a new sound is created, use <a href="#newsoundhook">new-sound-hook</a> (see ws.scm). -</td></tr><tr><td colspan=2 height=18></td></tr> + +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="normalizechannel">normalize-channel</a> norm <em class=narg>beg dur snd chn edpos</em></code> -</td></tr><tr><td></td><td> -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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- open-raw-sound --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="openrawsound">open-raw-sound</a> <em class=narg>:file :channels :srate :data-format</em></code> -</td></tr><tr><td></td><td> -This opens 'file' as a raw (no header) sound in the layout specified. -If the file has a header, it is not ignored (use <code>(set! (<a class=quiet href="#dataformat" onmouseout="UnTip()" onmouseover="Tip(extsnd_dataformat_tip)">data-format</a> ...))</code> +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define mpg - (lambda (mpgfile rawfile chans) - "(<a class=quiet href="sndscm.html#mpg" onmouseout="UnTip()" onmouseover="Tip(sndscm_mpg_tip)">mpg</a> file tmpname chans) converts file from MPEG-3 to raw 16-bit samples using mpg123" - (system (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "mpg123 -s ~A > ~A" mpgfile rawfile)) - (<em class=red>open-raw-sound</em> rawfile 1 44100 (if (<a class=quiet onmouseout="UnTip()" onmouseover="Tip('little-endian? returns #t if the host uses that byte order')">little-endian?</a>) <a class=quiet href="#dataformat" onmouseout="UnTip()" onmouseover="Tip(extsnd_muslshort_tip)">mus-lshort</a> <a class=quiet href="#dataformat" onmouseout="UnTip()" onmouseover="Tip(extsnd_musbshort_tip)">mus-bshort</a>)))) -</pre></td></tr></table> + (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 > ~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> -There's a more elaborate version of this function in examp.scm. See also <a href="#openrawsoundhook">open-raw-sound-hook</a>. -</td></tr><tr><td colspan=2 height=18></td></tr> <!-- open-sound --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="opensound">open-sound</a> filename</code> -</td></tr><tr><td></td><td> -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" onmouseout="UnTip()" onmouseover="Tip(extsnd_readonly_tip)">read-only</a> by hand. <a class=quiet href="#closesound" onmouseout="UnTip()" onmouseover="Tip(extsnd_closesound_tip)">close-sound</a> +<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_duringopenhook_tip)">during-open-hook</a>, <a class=quiet href="#openhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_openhook_tip)">open-hook</a>, -<a class=quiet href="#afteropenhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_afteropenhook_tip)">after-open-hook</a>, -<a class=quiet href="#initialgraphhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_initialgraphhook_tip)">initial-graph-hook</a>, <a class=quiet href="#openrawsoundhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_openrawsoundhook_tip)">open-raw-sound-hook</a>. +<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: -<pre> - bad header?: <a class=quiet href="#badheaderhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_badheaderhook_tip)">bad-header-hook</a> — can cancel request - no header?: <a class=quiet href="#openrawsoundhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_openrawsoundhook_tip)">open-raw-sound-hook</a> — can cancel request - file ok: - <a class=quiet href="#openhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_openhook_tip)">open-hook</a> — can change filename - file opened (no data read yet) - <a class=quiet href="#duringopenhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_duringopenhook_tip)">during-open-hook</a> (can set prescaling etc) - data read, no graphics yet - <a class=quiet href="#afteropenhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_afteropenhook_tip)">after-open-hook</a> - <a class=quiet href="#initialgraphhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_initialgraphhook_tip)">initial-graph-hook</a> -</pre> -There are -other ways to get at sound file data: <a class=quiet href="#makesampler" onmouseout="UnTip()" onmouseover="Tip(extsnd_makesampler_tip)">make-sampler</a> can be given a filename, +</p> + +<pre class="indented"> +bad header?: <a class=quiet href="#badheaderhook">bad-header-hook</a> — can cancel request +no header?: <a class=quiet href="#openrawsoundhook">open-raw-sound-hook</a> — can cancel request +file ok: + <a class=quiet href="#openhook">open-hook</a> — 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->vct in examp.scm; -<a class=quiet href="#mussoundopeninput" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussoundopeninput_tip)">mus-sound-open-input</a> and +<a class=quiet href="#mussoundopeninput">mus-sound-open-input</a> and there are a variety of CLM-based functions such as -<a class=quiet href="sndclm.html#filetosample" onmouseout="UnTip()" onmouseover="Tip(sndclm_filetosample_tip)">file->sample</a> and -<a class=quiet href="sndclm.html#filetoarray" onmouseout="UnTip()" onmouseover="Tip(sndclm_filetoarray_tip)">file->array</a>. -</td></tr><tr><td colspan=2 height=18></td></tr> +<a class=quiet href="sndclm.html#filetosample">file->sample</a> and +<a class=quiet href="sndclm.html#filetoarray">file->array</a>. +</p> +<div class="separator"></div> <!-- pad-channel --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="padchannel">pad-channel</a> beg dur <em class=narg>snd chn edpos</em></code> -</td></tr><tr><td></td><td> -pad-channel inserts 'dur' zeros at 'beg' in the given channel. This is the <a class=quiet href="#regularizedargs" onmouseout="UnTip()" onmouseover="Tip(extsnd_regularizedargs_tip)">regularized</a> +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define* (<A NAME="blockchannel">block-channel</a> value (beg 0) dur snd chn edpos) - (<em class=red>pad-channel</em> beg dur snd chn edpos) ; insert 'dur' samples, ptree-channel sets their values - (<a class=quiet href="#ptreechannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_ptreechannel_tip)">ptree-channel</a> (lambda (y) value) beg dur snd chn)) -</pre></td></tr></table> - -We could also use map-channel here (rather than ptree-channel), but this version -uses only virtual edits, so no matter how big the block of samples we insert, -no disk space or memory is needed. -The multichannel version is <a href="sndscm.html#padsound">pad-sound</a> in frame.scm. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="pausing">pausing</a></code> -</td></tr><tr><td></td><td> -pausing is #t if sound output is currently paused. You can unpause the sound by setting pausing to #f, +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(<a class=quiet href="#bindkey" onmouseout="UnTip()" onmouseover="Tip(extsnd_bindkey_tip)">bind-key</a> (char->integer #\p) 0 +<pre class="indented"> +(<a class=quiet href="#bindkey">bind-key</a> (char->integer #\p) 0 (lambda () - (if (<em class=red>pausing</em>) (<a class=quiet href="#stopplaying" onmouseout="UnTip()" onmouseover="Tip(extsnd_stopplaying_tip)">stop-playing</a>)) - (<a class=quiet href="#play" onmouseout="UnTip()" onmouseover="Tip(extsnd_play_tip)">play</a>))) -</pre></td></tr></table> -</td></tr><tr><td colspan=2 height=18></td></tr> + (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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="peaks">peaks</a> <em class=narg>file snd chn</em></code> -</td></tr><tr><td></td><td> -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 -(where it can be selected and pasted elsewhere). The maximum number of peaks reported is set +<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> -(hook-push <a class=quiet href="#aftertransformhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_aftertransformhook_tip)">after-transform-hook</a> (lambda (a b c) - (<em class=red>peaks</em>))) ; post a detailed list of peaks after each FFT +<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> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- play --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="play">play</a> <em class=narg>object :start :end :channel :edit-position :out-channel :with-sync :wait :stop :srate :channels</em></code> -</td></tr><tr><td></td><td> +<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. @@ -7816,70 +8268,80 @@ Not all the keyword arguments apply in all cases, though I hope to fill in the t 'srate' and 'channels' are for one special case, described below. </p> -<pre> - (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_cursor_tip)">cursor</a>)) ; play starting from the cursor - (play (integer->sound 1) (round (* 3.0 (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">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" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">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->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" onmouseout="UnTip()" onmouseover="Tip(extsnd_marksample_tip)">mark-sample</a> (integer->mark 0)) :end (<a class=quiet href="#marksample" onmouseout="UnTip()" onmouseover="Tip(extsnd_marksample_tip)">mark-sample</a> (integer->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 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->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->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->mark 0)) :end (<a class=quiet href="#marksample">mark-sample</a> (integer->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> - (play (selected-sound) 0 :stop (lambda (reason) ; if interrupted, say so in the listener - (if (not (= reason 0)) - (<a class=quiet href="#sndprint" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndprint_tip)">snd-print</a> ";play interrupted")))) + +<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> - (play (selected-sound) :edit-position (- (<a class=quiet href="#editposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_editposition_tip)">edit-position</a>) 1)) + +<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> -<table border=0 cellpadding=5><tr><td><pre> + +<pre class="indented"> (define (play-from-cursor current) - (<em class=red>play</em> (selected-sound) (<a class=quiet href="#cursor" onmouseout="UnTip()" onmouseover="Tip(extsnd_cursor_tip)">cursor</a>) :edit-position (if current #f (- (<a class=quiet href="#editposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_editposition_tip)">edit-position</a>) 1)))) + (<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_bindkey_tip)">bind-key</a> (char->integer #\p) 0 - (lambda () "play from cursor" (play-from-cursor #t) <a class=quiet onmouseout="UnTip()" onmouseover="Tip(extsnd_keyboard_no_action_tip)">keyboard-no-action</a>)) +(<a class=quiet href="#bindkey">bind-key</a> (char->integer #\p) 0 + (lambda () "play from cursor" (play-from-cursor #t) <a class=quiet>keyboard-no-action</a>)) -(<a class=quiet href="#bindkey" onmouseout="UnTip()" onmouseover="Tip(extsnd_bindkey_tip)">bind-key</a> (char->integer #\P) 0 - (lambda () "play previous version from cursor" (play-from-cursor #f) <a class=quiet onmouseout="UnTip()" onmouseover="Tip(extsnd_keyboard_no_action_tip)">keyboard-no-action</a>)) -</pre></td></tr></table> -<p> +(<a class=quiet href="#bindkey">bind-key</a> (char->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> -<table border=0 cellpadding=5><tr><td><pre> -(define (<A NAME="pfc">pfc</a>) - (let ((old-tracking (<a class=quiet href="#withtrackingcursor" onmouseout="UnTip()" onmouseover="Tip(extsnd_withtrackingcursor_tip)">with-tracking-cursor</a>))) - (set! (<a class=quiet href="#withtrackingcursor" onmouseout="UnTip()" onmouseover="Tip(extsnd_withtrackingcursor_tip)">with-tracking-cursor</a>) #t) - (hook-push <a class=quiet href="#stopplayinghook" onmouseout="UnTip()" onmouseover="Tip(extsnd_stopplayinghook_tip)">stop-playing-hook</a> - (lambda (snd) - (set! (<a class=quiet href="#withtrackingcursor" onmouseout="UnTip()" onmouseover="Tip(extsnd_withtrackingcursor_tip)">with-tracking-cursor</a>) old-tracking))) - (<em class=red>play</em> (selected-sound) (<a class=quiet href="#cursor" onmouseout="UnTip()" onmouseover="Tip(extsnd_cursor_tip)">cursor</a>)))) -</pre></td></tr></table> + +<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> -<table border=0 cellpadding=5><tr><td><pre> + +<pre class="indented"> (bind-key #\o 0 (lambda () ; send oboe.snd to chan 0 (play "oboe.snd" :out-channel 0))) @@ -7896,27 +8358,30 @@ than the various inputs. ;;; Now type o and p in the sound pane until you want to quit, then (stop-playing) -</pre></td></tr></table> +</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> -<table border=0 cellpadding=5><tr><td><pre> -(define (play-sine freq amp) - "(play-sine freq amp) plays a 1 second sinewave at freq and amp" - (let* ((len 22050) - (osc (<a class=quiet href="sndclm.html#make-oscil" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_oscil_tip)">make-oscil</a> freq))) - (<em class=red>play</em> (lambda () - (set! len (- len 1)) - (if (<= len 0) ; we've sent 22050 samples, so it's time to stop - #f - (* amp (<a class=quiet href="sndclm.html#oscil" onmouseout="UnTip()" onmouseover="Tip(sndclm_oscil_tip)">oscil</a> osc))))))) -</pre></td></tr></table> + +<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> -<table border=0 cellpadding=5><tr><td><pre> + +<pre class="indented"> (define (play-skipping-silence file) (let ((buffer (make-moving-average 128)) (silence (/ .001 128)) @@ -7927,139 +8392,141 @@ function option to time the playing of each mix in a sequence of mixes. Another (let loop () (set! y (rd)) (set! sum-of-squares (moving-average buffer (* y y))) - (if (sampler-at-end? rd) - #f - (if (> sum-of-squares silence) - y - (loop)))))))) -</pre></td></tr></table> - + (and (not (sampler-at-end? rd)) + (if (> sum-of-squares silence) + y + (loop)))))))) +</pre> <!-- INDEX playexamples:Playing --> -<A NAME="playexamples"></a> -<TABLE border=3 bordercolor="tan" hspace=20 vspace=10><tr><td> -<small><blockquote> -play one channel: (play sound-object :channel n), play button in control panel or files dialog<br> +<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="#pfc">pfc</a> 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 triangle (control-click for all chans)<br> -play continuously between two marks: <a href="sndscm.html#loopbetweenmarks">loop-it</a><br> -stop playing: C-g, C-t, <a href="#stopplaying">stop-playing</a>, set <a href="#playing">playing</a> to #f<br> -pause or resume playback: space, set <a href="#pausing">pausing</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="#extendedpiano">bind-key</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="#makeplayer">make-player</a> and related functions, <a href="sndscm.html#playsyncdmarks">play-syncd-marks</a><br> -send arbitrary data to the DAC: <a href="#musaudiowrite">mus-audio-write</a>, <a href="sndscm.html#startdac">start-dac</a><br> -play after sending the data through some function: <a href="sndscm.html#playsound">play-sound</a><br> -play with applied amplitude envelope: <a href="sndscm.html#playwithenvs">play-with-envs</a>, <a href="sndscm.html#playpanned">play-panned</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> -<br> -</blockquote></small> +</small></blockquote> </td></tr></TABLE> -<A NAME="stopplayreasons"></a> - -<p> +<p id="stopplayreasons"> The "reasons" that might be passed to the stop-procedure are: </p> -<pre> - 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 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> - when a play request occurs: <a class=quiet href="#startplayinghook" onmouseout="UnTip()" onmouseover="Tip(extsnd_startplayinghook_tip)">start-playing-hook</a> — can cancel the request, - also <a class=quiet href="#startplayingselectionhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_startplayingselectionhook_tip)">start-playing-selection-hook</a> - (any number of sounds can be playing at once) - as each buffer is sent to the audio device: <a class=quiet href="#playhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_playhook_tip)">play-hook</a> and <a class=quiet href="#dachook" onmouseout="UnTip()" onmouseover="Tip(extsnd_dachook_tip)">dac-hook</a> - as each sound ends: <a class=quiet href="#stopplayinghook" onmouseout="UnTip()" onmouseover="Tip(extsnd_stopplayinghook_tip)">stop-playing-hook</a>, <a class=quiet href="#stopplayingselectionhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_stopplayingselectionhook_tip)">stop-playing-selection-hook</a> - close audio device: <a class=quiet href="#stopdachook" onmouseout="UnTip()" onmouseover="Tip(extsnd_stopdachook_tip)">stop-dac-hook</a> + +<pre class="indented"> +when a play request occurs: <a class=quiet href="#startplayinghook">start-playing-hook</a> — 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> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- player-home --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="playerhome">player-home</a> player</code> -</td></tr><tr><td></td><td> -This returns a list of the sound and channel number associated with <a href="#makeplayer">player</a>. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="playing">playing</a></code> -</td></tr><tr><td></td><td> -This returns #t if sound output is currently in progress. You can also start playing by setting playing to #t (equivalent +<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>). -playing only notices Snd-instigated "play" processes; -<a href="#musaudioopenoutput">mus-audio-open-output</a> is invisible to it. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- players --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="players">players</a></code> -</td></tr><tr><td></td><td> -This returns a list of currently active <a href="#makeplayer">players</a>. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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? --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="playerQ">player?</a> obj</code> -</td></tr><tr><td></td><td> -This returns #t if 'obj' is an active <a href="#makeplayer">player</a>. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="positiontox">position->x</a> xpos <em class=narg>snd chn axis</em></code> -</td></tr><tr><td></td><td> -This returns the x axis value that corresponds to the graph (screen pixel) position 'xpos'. +<pre class="indented"> +<em class=def id="positiontox">position->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, -<pre> - (round (* (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a> snd) (position->x x snd chn))) +</p> + +<pre class="indented"> +(round (* (<a class=quiet href="#srate">srate</a> snd) (position->x x snd chn))) </pre> -See gui.scm for examples. -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- position->y --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="positiontoy">position->y</a> ypos <em class=narg>snd chn axis</em></code> -</td></tr><tr><td></td><td> -This returns the y axis value that corresponds to the graph (screen pixel) position 'ypos'. -See gui.scm for examples. -</td></tr><tr><td colspan=2 height=18></td></tr> +<pre class="indented"> +<em class=def id="positiontoy">position->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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="progressreport">progress-report</a> pct <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -The functions <a href="#startprogressreport">start-progress-report</a>, progress-report, and +<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 @@ -8067,950 +8534,591 @@ 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 minibuffer using 'name' to identify itself. -</td></tr><tr><td colspan=2 height=18></td></tr> - - -<!-- prompt-in-minibuffer --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="promptinminibuffer">prompt-in-minibuffer</a> msg <em class=narg>callback snd raw</em></code> -</td></tr><tr><td></td><td> -This posts 'msg' in the sound's minibuffer and when you respond, -it calls 'callback' with the response as the callback's argument. -If 'callback' is specified it should be either #f or a function of -one argument: the raw response if 'raw' is #t, otherwise the evaluated response. -For example, the following fragment asks for -a yes-or-no response, then takes some action: - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> - (define* (yes-or-no question action-if-yes action-if-no snd) - (<em class=red>prompt-in-minibuffer</em> question - (lambda (response) - (<a class=quiet href="#clearminibuffer" onmouseout="UnTip()" onmouseover="Tip(extsnd_clearminibuffer_tip)">clear-minibuffer</a>) - (if (string=? response "yes") - (action-if-yes snd) - (action-if-no snd))) - snd #t)) -</pre></td></tr></table> - -See eval-over-selection in <a href="sndscm.html#extensionsdoc">extensions.scm</a> for a more useful example. -We could also use a continuation here: - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define (prompt msg default) - (call-with-current-continuation - (lambda (rsvp) - (<em class=red>prompt-in-minibuffer</em> msg rsvp) - default))) -</pre></td></tr></table> - -The 'raw' argument is useful when we want to prompt for yes or no, without forcing the -user to put the answer in double quotes. In the next example, we replace Snd's -built-in C-x k action (which immediately closes the sound) with one that is -more like Emacs (it prompts for confirmation first): - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(<a class=quiet href="#bindkey" onmouseout="UnTip()" onmouseover="Tip(extsnd_bindkey_tip)">bind-key</a> (char->integer #\k) 0 - (lambda () - "close sound" - (<a class=quiet href="#clearminibuffer" onmouseout="UnTip()" onmouseover="Tip(extsnd_clearminibuffer_tip)">clear-minibuffer</a>) - (<em class=red>prompt-in-minibuffer</em> - (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "close ~S (cr=yes)?" (<a class=quiet href="#shortfilename" onmouseout="UnTip()" onmouseover="Tip(extsnd_shortfilename_tip)">short-file-name</a>)) - (lambda (response) - (if (or (not (string? response)) - (= (string-length response) 0) - (char=? (string-ref response 0) #\y)) - (<a class=quiet href="#closesound" onmouseout="UnTip()" onmouseover="Tip(extsnd_closesound_tip)">close-sound</a>))) - #f ; selected sound - #t)) ; treat as string (i.e. don't require double quotes) - #t) ; C-x ... -</pre></td></tr></table></td></tr> -<tr><td colspan=2 height=18></td></tr> - - -<!-- INDEX ptreechannel:Virtual Edits --> -<!-- ptree-channel --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="ptreechannel">ptree-channel</a> proc <em class=narg>beg dur snd chn edpos env-too init-func origin</em></code> -</td></tr><tr><td></td><td> -ptree-channel -applies the function 'proc' as a 'virtual edit'; that is, the effect of 'proc' -comes about as an implicit change in the way the data is read. - -<br><br> -To be less Orphic: -all the data accesses in Snd go through the edit-history list. The currently -active member of that list -chooses a channel data accessor based on the type of edit. A multiply by 2, for -example, does not multiply anything by 2 internally; it just chooses -the accessor that multiplies by 2 on any read. Since every other data access goes through this reader, from any other -point of view, the data has been multiplied. These accessors make it -unnecessary to save any data in temp files or internal arrays, and editing the edit-history list is very -fast — we just tack a new accessor choice onto the edit-history list, so the edit operation -appears to be instantaneous and memory-less. Lots of other operations -are already being done this way in Snd (deletions, scaling, most -envelopes, some channel swaps, etc). ptree-channel extends the idea to (nearly) arbitrary -functions. When you call -<pre> - (ptree-channel (lambda (y) (* y 2))) -</pre> -which has the same effect as -<pre> - (<a class=quiet href="#mapchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_mapchannel_tip)">map-channel</a> (lambda (y) (* y 2))) -</pre> -the -optimizer makes the parse-tree that represents <code>(lambda (y) (* y 2))</code>, then the -data accessor system uses that parse-tree every time the data is -read. -<br><br> - -If the argument 'env-too' is #t, -the same function is applied to the peak env values to get the new version of the peak env data. -The default is #f, and should be #t only if the old max and min values as processed through 'proc' -will be the new max and min values. -Snd uses the peak env values when the graph of the sound covers very large amounts of data. -If 'env-too' is #f, a background process is launched reading all the sound data through -'proc'; this can be time-consuming, so if you're viewing a half-hour of sound data, -it can take awhile for the ptree-channel results to be displayed. -<br><br> - -Here is an example that adds a constant to each sample in a file. -<pre> - (define* (offset-channel dc (beg 0) dur snd chn edpos) - (<em class=red>ptree-channel</em> (lambda (y) (+ y dc)) beg dur snd chn edpos <em class=red>#t</em>)) -</pre> -The actual edit that takes place is <code>(+ y dc)</code>; that is, 'dc' is added to -every sample. As subsequent editing takes place, the entries representing the 'offset-channel' -call can become thoroughly fragmented. -If your editing operation has any state (i.e. needs to -know where it is in the data), you need to add an 'init-func' (the 8th argument to ptree-channel). -The 'init-func' takes two arguments, the begin time of the read operation, relative to -the original start of the fragment, and the original fragment duration (both in samples). -It should return -the information the main function ('proc' above) needs to -handle the current fragment correctly. Global variables are not guaranteed to -be set within the body of 'proc', so use a vct for local values that change -as the read operation progresses. -<br><br> - -The other new argument to 'proc' -is the read direction; the read operations can change direction at any -time, and any ptree-channel function needs to know how to deal with that. -So, in the complicated, 3 argument case, -the sequence of operations is: -a read is requested, 'init-func' is called with the read start point (relative to the -original segment start), -it returns any state that 'proc' may need -to refer to, then each time a sample is needed from the current sample -reader, 'proc' is called passing it the current underlying sample, the return value of 'init-func', -and the read direction. -Here is an example that mixes a sine wave into the current channel: - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define* (sine-channel freq amp (beg 0) dur snd chn edpos) - (<em class=red>ptree-channel</em> - (lambda (y data forward) - (let* ((angle (data 0)) - (incr (data 1)) - (val (+ y (* (data 2) (sin angle))))) - (if forward - (set! (data 0) (+ angle incr)) - (set! (data 0) (- angle incr))) - val)) - beg dur snd chn edpos #f - (lambda (frag-beg frag-dur) - (let ((incr (/ (* 2 pi freq) (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a>)))) - (<a class=quiet href="#vct" onmouseout="UnTip()" onmouseover="Tip(extsnd_vct_tip)">vct</a> (<a class=quiet onmouseout="UnTip()" onmouseover="Tip('fmod is mod with float arguments')">fmod</a> (* frag-beg incr) (* 2 pi)) incr amp))))) ; fmod from C -</pre></td></tr></table> - -In the normal case, -this function just mixes in a sine wave: <code>(+ y (* (data 2) (sin angle)))</code> -where the amplitude scaler is stored in <code>(data 2)</code>. In subsequent -reads, the init-func sets up a vct with the current phase (dependent on the frequency -and the fragment begin sample), the phase increment (dependent on the frequency), and -the amplitude (passed as an argument to sine-channel, but stored in the vct since -the outer function's arguments won't be accessible in the main function ('proc')). -See 'sine-ramp' in extensions.scm for another example. -<br><br> - -In our 'sine-channel' function, we passed #f as the 'env-too' argument, -to make sure Snd doesn't blithely apply the sine mix to the peak amplitude -envelopes. When 'env-too' is #t, -'proc' is evaluated over the peak env data, rather than the -original data. This makes redisplay much faster whenever a lot of data -is being displayed, but only works if the function's output at the peak -env min and max values are still the min and max values in the actual -data (this is the case in the sinusoidal envelope, sine-ramp, mentioned above). -When 'proc' is being called to calculate the new peak env, -the duration passed to the init-func is the envelope size. -Here is a -version of cosine-channel given under -<a href="#mapchannel">map-channel</a> that can handle peak-envs: - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define* (<A NAME="cosinechannelviaptree">cosine-channel-via-ptree</a> (beg 0) dur snd chn edpos) - ;; vct: angle increment - (<em class=red>ptree-channel</em> - (lambda (y data forward) - (let* ((angle (data 0)) - (incr (data 1)) - (val (* y (cos angle)))) - (if forward - (set! (data 0) (+ angle incr)) - (set! (data 0) (- angle incr))) - val)) - beg dur snd chn edpos <em class=red>#t</em> - (lambda (frag-beg frag-dur) - (let ((incr (/ pi <em class=red>frag-dur</em>))) - (<a class=quiet href="#vct" onmouseout="UnTip()" onmouseover="Tip(extsnd_vct_tip)">vct</a> (+ (* -0.5 pi) (* frag-beg incr)) - incr))))) -</pre></td></tr></table> - -If the underlying data -has too many previous ptree operations (more than <a href="#maxvirtualptrees">max-virtual-ptrees</a>), map-channel is called instead and the new -data is saved in the normal manner. - -<br><br> - -If no 'init-func' is specified, the editing procedure ('proc') should not assume anything about -the context in which it is called; in this case, there's no way for 'proc' to know where it starts, or when it is being restarted, -or which direction it is running, so, -the following call: - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> - (let ((ctr 0)) - (<em class=red>ptree-channel</em> (lambda (y) - (set! ctr (+ 1 ctr)) - (* ctr .0001)))) -</pre></td></tr></table> - -will never reset ctr to 0! Every time a portion of the data is read by Snd, the samples will be -higher. But, the notion of an accessor that returns a different thing each time a sample -is accessed is not foolish: - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define* (dither-channel (amount .00006) beg dur snd chn edpos) - (let ((dither (* .5 amount))) - (<em class=red>ptree-channel</em> - (lambda (y) - (+ y (<a class=quiet href="sndclm.html#mus-random" onmouseout="UnTip()" onmouseover="Tip(sndclm_mus_random_tip)">mus-random</a> dither) (<a class=quiet href="sndclm.html#mus-random" onmouseout="UnTip()" onmouseover="Tip(sndclm_mus_random_tip)">mus-random</a> dither))) - beg dur snd chn edpos #t))) -</pre></td></tr></table> - -This gives a slightly different take on the sound each time you look at it or listen to it; -the dithering is never exactly the same. But if the details of the noise don't -matter (presumably the case with dithering), the difference is unproblematic. You're editing a sort -of mobile in sound (analogous to mobile sculpture). -<br><br> -One major limitation of ptree-channel with an 'init-func' is that <a href="#savestate">save-state</a> -currently doesn't know how to save the enclosing environment along with the init-func. So, - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> - (let ((outer 0.5)) - (<em class=red>ptree-channel</em> (lambda (y data forward) - (<a class=quiet href="#declare" onmouseout="UnTip()" onmouseover="Tip(extsnd_declare_tip)">declare</a> (y real) (data float) (forward boolean)) - (* y data)) - 0 #f ind 0 #f #f - (lambda (pos dur) - outer))) -</pre></td></tr></table> - -will not save the "outer" declaration in the saved state file. -This is a general problem with save-state; there's no obvious way in Scheme to -save the current closure as text. -You can fix the saved state file by hand (it is just Scheme, Ruby, or Forth code, of course), -but that's not a very elegant solution. -<br><br> - -The real limitation in using ptree-channel, however, arises from the fact that the read direction -can not only be backwards, but it can also change at any time. In conjunction with -the fragmentation during editing, this makes it -hard to use CLM generators, or anything that depends on previous samples. -Since the run macro (on which ptree-channel depends) is currently limited in -the kinds of vector or list elements it can decipher, you're pretty tightly -constricted in this context. -The read direction argument can be ignored if you know you're not going to read backwards. -The only hidden reverse read is in the src generator where a negative increment can be -generated in a variety of ways (for example, src driven by oscil). A one zero filter -could in this case be: - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> - (<em class=red>ptree-channel</em> (lambda (y data forward) - (let ((val (* 0.5 (+ y (data 0))))) - (set! (data 0) y) - val)) - 0 (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a>) ind 0 #f #f ; "ind" is the sound - (let ((edpos (<a class=quiet href="#editposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_editposition_tip)">edit-position</a> ind 0))) - (lambda (pos dur) - (<a class=quiet href="#vct" onmouseout="UnTip()" onmouseover="Tip(extsnd_vct_tip)">vct</a> (if (= pos 0) 0.0 - (<a class=quiet href="#sample" onmouseout="UnTip()" onmouseover="Tip(extsnd_sample_tip)">sample</a> (- pos 1) ind 0 edpos)))))) -</pre></td></tr></table> - -See also virtual-filter-channel in snd-test.scm; it uses the optional third argument to the init function -to set up the filter state correctly, and has code to run the filter backwards if necessary. -Here are several more examples: - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define* (ptree-scale scl (beg 0) dur snd chn edpos) - "ptree-channel version of scale-channel" - (<em class=red>ptree-channel</em> - (lambda (y) - (* scl y)) - beg dur snd chn edpos #t)) - -(define* (ptree-xramp r0 r1 ubase (beg 0) dur snd chn edpos) - "exponential version of ramp-channel" - ;; this is essentially what CLM's exponential envelope generator is doing - ;; to accommodate C, it uses (exp (* power (log base))) prescaling power by (log base) - (let* ((base (if (> r0 r1) (/ 1.0 ubase) ubase))) - (<em class=red>ptree-channel</em> - (lambda (y data forward) - (let* ((lr0 (data 0)) - (lbase (data 1)) - (incr (data 2)) - (scl (data 3)) - (power (data 4)) - (val (* y (+ lr0 (* scl (- (expt lbase power) 1.0)))))) - (if forward - (set! (data 4) (+ power incr)) - (set! (data 4) (- power incr))) - val)) - beg dur snd chn edpos #t - (lambda (frag-beg frag-dur) - ;; r0, base, incr, (/ (- r1 r0) (- base 1.0)), current power - (<a class=quiet href="#vct" onmouseout="UnTip()" onmouseover="Tip(extsnd_vct_tip)">vct</a> r0 - base - (/ 1.0 frag-dur) - (/ (- r1 r0) (- base 1.0)) - (/ frag-beg frag-dur)))))) - -(define* (virtual-mix file beg snd chn) - (let ((len (<a class=quiet href="#mussoundframes" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussoundframes_tip)">mus-sound-frames</a> file))) - (<em class=red>ptree-channel</em> - (lambda (y state forward) - (<a class=quiet href="#declare" onmouseout="UnTip()" onmouseover="Tip(extsnd_declare_tip)">declare</a> (y real) (state sampler) (forward boolean)) - (+ y (if forward (<a class=quiet href="#nextsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_nextsample_tip)">next-sample</a> state) (<a class=quiet href="#previoussample" onmouseout="UnTip()" onmouseover="Tip(extsnd_previoussample_tip)">previous-sample</a> state)))) - beg len snd chn -1 #f - (lambda (frag-beg frag-dur) - (<a class=quiet href="#makesampler" onmouseout="UnTip()" onmouseover="Tip(extsnd_makesampler_tip)">make-sampler</a> frag-beg file))))) - -</pre></td></tr></table> - -To handle an envelope in a ptree-channel application, it's probably -easiest to split it up into a sequence of ramps, each ramp keeping track -of its local begin point and increment. This is how sine-env-channel -works, not to mention the built-in linear and exponential envelopes. -The underlying procedure is <a href="sndscm.html#anyenvchannel">any-env-channel</a> -which needs only the segment connecting function, and handles the rest itself. -Here is an implementation of Anders Vinjar's power-envelope (a list -of breakpoints with an added base for each segment), that splits -the envelope into a sequence of <a href="#xrampchannel">xramp-channel</a> -calls. It also uses <a href="#asoneedit">as-one-edit</a> to make the -result appear to be one operation in the edit history list. - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -<A NAME="powenvchannel"></a>(define* (powenv-channel envelope (beg 0) dur snd chn edpos) - ;; envelope with a separate base for each segment: - ;; (powenv-channel '(0 0 .325 1 1 32.0 2 0 32.0)) - (let* ((curbeg beg) - (fulldur (or dur (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a> snd chn edpos))) - (len (length envelope)) - (x1 (car envelope)) - (xrange (- (list-ref envelope (- len 3)) x1)) - (y1 (cadr envelope)) - (base (caddr envelope)) - (x0 0.0) - (y0 0.0)) - (if (= len 3) - (<a class=quiet href="#scalechannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_scalechannel_tip)">scale-channel</a> y1 beg dur snd chn edpos) - (<em class=red>as-one-edit</em> - (lambda () - (do ((i 3 (+ i 3))) - ((= i len)) - (set! x0 x1) - (set! y0 y1) - (set! x1 (list-ref envelope i)) - (set! y1 (list-ref envelope (+ i 1))) - (let* ((curdur (round (* fulldur (/ (- x1 x0) xrange))))) - (<em class=red>xramp-channel</em> y0 y1 base curbeg curdur snd chn edpos) - (set! curbeg (+ curbeg curdur))) - (set! base (list-ref envelope (+ i 2))))))))) -</pre></td></tr></table> - -If the init-func returns something other than a vct, you need to declare its type -for the run macro. There are several examples in snd-test.scm. - - -<table border=3 bordercolor="tan" hspace=20 vspace=20><tr><td> -<blockquote><small> -<br> -more ptree-channel examples:<br> -smoothing: smooth-channel-via-ptree (examp.scm)<br> -compander: <a href="sndscm.html#compandchannel">compand-channel</a> (examp.scm)<br> -insert a block of arbitrary-valued samples: <a href="#blockchannel">block-channel</a><br> -sinusoidal ramp: <a href="sndscm.html#sineramp">sine-ramp</a> (extensions.scm)<br> -sinusoidal envelope: <a href="sndscm.html#sineenvchannel">sine-env-channel</a> (extensions.scm)<br> -CLM-style contrast-enhancement: <a href="sndscm.html#contrastchannel">contrast-channel</a> (extensions.scm)<br> -add a constant to every sample: <a href="sndscm.html#offsetchannel">offset-channel</a> (extensions.scm)<br> -ring modulation: ring-modulate-channel (examp.scm)<br> -delay by n samples (an experiment!): delay-channel in extensions.scm<br> -dithering: <a href="sndscm.html#ditherchannel">dither-channel</a> (extensions.scm)<br> -FIR filter: <a href="sndscm.html#virtualfilterchannel">virtual-filter-channel</a> (examp.scm)<br> -<br> -</small></blockquote> -</td></tr></table> -</td></tr><tr><td colspan=2 height=18></td></tr> +the sound's status area using 'name' to identify itself. +</p> +<div class="separator"></div> + + <!-- ramp-channel --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="rampchannel">ramp-channel</a> rmp0 rmp1 <em class=narg>beg dur snd chn edpos</em></code> -</td></tr><tr><td></td><td> -ramp-channel is a slight extension of scale-channel. It scales samples in the given sound/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'. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- read-only --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="readonly">read-only</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This returns #t if 'snd' is read-only, #f otherwise. If you open +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- redo --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="redo">redo</a> <em class=narg>edits snd chn</em></code> -</td></tr><tr><td></td><td> -This re-activates 'edits' edits (the default is 1) in the given channel. -Redo follows the <a class=quiet href="#sync" onmouseout="UnTip()" onmouseover="Tip(extsnd_sync_tip)">sync</a> field if it +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define* (<a name="redochannel">redo-channel</a> (<a class=quiet href="#edits" onmouseout="UnTip()" onmouseover="Tip(extsnd_edits_tip)">edits</a> 1) snd chn) - (if (and snd (not (= (<a class=quiet href="#sync" onmouseout="UnTip()" onmouseover="Tip(extsnd_sync_tip)">sync</a> snd) 0)) chn) - (set! (<a class=quiet href="#editposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_editposition_tip)">edit-position</a> snd chn) (+ (<a class=quiet href="#editposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_editposition_tip)">edit-position</a> snd chn) edits)) +<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></td></tr></table> +</pre> -redo moves forward in the edit history list, whereas +<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>. -<br><br> -In Ruby, redo is a part of the loop handling, so Snd's redo is renamed redo_edit. -<a name="redoedit">redo-edit</a> also exists in Scheme, for consistency. -</td></tr><tr><td colspan=2 height=18></td></tr> - +</p> -<!-- report-in-minibuffer --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="reportinminibuffer">report-in-minibuffer</a> msg <em class=narg>snd as-error</em></code> -</td></tr><tr><td></td><td> -This posts 'msg' in the sound's minibuffer. The 'minibuffer' is the text widget between the sound's filename and the buttons -on the right, beneath the graph. It is intended to mimic Emacs' minibuffer, being useful mainly for short, -temporary messages. C-g clears it, as does <a href="#clearminibuffer">clear-minibuffer</a>. -If 'as-error' is #t, the message is placed in the minibuffer error label, rather than in the usual text area. -See also <a href="#promptinminibuffer">prompt-in-minibuffer</a>. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="reversechannel">reverse-channel</a> <em class=narg>beg dur snd chn edpos</em></code> -</td></tr><tr><td></td><td> -reverse-channel is the <a class=quiet href="#regularizedargs" onmouseout="UnTip()" onmouseover="Tip(extsnd_regularizedargs_tip)">regularized</a> version of <a href="#reversesound">reverse-sound</a>. +<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 --> -<A NAME="reverseexamples"></a> -<TABLE border=3 bordercolor="tan" hspace=20 vspace=10><tr><td> +<TABLE class="method"> +<tr><th class="title">Reversing</th></tr><tr><td> <blockquote><small> -<br> -reverse selected portion: <a href="#reverseselection">reverse-selection</a><br> -read samples in reverse: use <a href="#makesampler">make-sampler</a> with direction -1<br> -reverse at new sampling rate: use <a href="#srcchannel">src-channel</a> with a negative ratio<br> -Reverse in control panel: <a href="snd.html#speed">control panel</a> and <a href="#speedcontrol">speed-control</a> variable<br> +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="#sillyreverse">silly-reverse</a><br> -reverse order of channels: <a href="#reversechannels">reverse-channels</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 Forth: string-reverse, in Ruby: reverse<br> -reverse a vct: <a href="#vctreverse">vct-reverse!</a><br> -reverse a frame: <a href="sndscm.html#framereverse">frame-reverse</a><br> -<br> +reverse a string: in Ruby: reverse<br> +reverse vct: <a href="extsnd.html#vctreverse">vct-reverse!</a><br> </small></blockquote> </td></tr></TABLE> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> + <!-- reverse-sound --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="reversesound">reverse-sound</a> <em class=narg>snd chn edpos</em></code> -</td></tr><tr><td></td><td> -reverse-sound reverses the sound data in the given channel. There are some interesting non-causal effects you can get with this: +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define* (<A NAME="sillyreverse">silly-reverse</a> snd) - (let* ((len (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a> snd 0)) - (fsize (expt 2 (ceiling (/ (log len) (log 2))))) - (rl (<a class=quiet href="#channeltovct" onmouseout="UnTip()" onmouseover="Tip(extsnd_channeltovct_tip)">channel->vct</a> 0 fsize snd 0)) - (im (<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> fsize))) - (<a class=quiet href="sndclm.html#fft" onmouseout="UnTip()" onmouseover="Tip(sndclm_fft_tip)">mus-fft</a> rl im fsize) - (<a class=quiet href="sndclm.html#fft" onmouseout="UnTip()" onmouseover="Tip(sndclm_fft_tip)">mus-fft</a> rl im fsize) - (<a class=quiet href="#vctscale" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctscale_tip)">vct-scale!</a> rl (/ 1.0 fsize)) - (<a class=quiet href="#vcttochannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_vcttochannel_tip)">vct->channel</a> (<a class=quiet href="#vctsubseq" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctsubseq_tip)">vct-subseq</a> rl (- fsize len) fsize) 0 len snd 0))) -</pre></td></tr></table> -</td></tr><tr><td colspan=2 height=18></td></tr> +<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->float-vector 0 fsize snd 0)) + (im (make-float-vector fsize 0.0))) + (<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->channel (float-vector-subseq rl (- fsize len) fsize) 0 len snd 0))) +</pre> +<div class="separator"></div> <!-- revert-sound --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="revertsound">revert-sound</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This reverts 'snd' to its saved (unedited) state. A channel-specific version: -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_editposition_tip)">edit-position</a> snd chn) 0)) -</pre></td></tr></table> -</td></tr><tr><td colspan=2 height=18></td></tr> + (set! (<a class=quiet href="#editposition">edit-position</a> snd chn) 0)) +</pre> +<div class="separator"></div> <!-- right-sample --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="rightsample">right-sample</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This returns the position (in samples) of right edge of the time domain waveform. See <a href="#leftsample">left-sample</a>, +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> -<!-- run --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="run">run</a> thunk</code> -</td></tr><tr><td></td><td> -<p>run is the Snd equivalent of the CL/CLM run macro. You can wrap it around a numerically-intensive -block of code, and the result will usually run 10 to 20 times faster. In the context of <a href="sndscm.html#wsdoc">with-sound</a>, run is used -to speed up instrument bodies. My timing tests indicate that Snd+Run instruments are within a factor of two to four -of the speed of CL+run+C in CLM. Currently, only s7 supports this optimization. +<!-- 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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define (ws-sine freq) - (let ((o (<a class=quiet href="sndclm.html#make-oscil" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_oscil_tip)">make-oscil</a> freq))) - (<em class=red>run</em> - (do ((i 0 (+ 1 i))) - ((= i 100)) - (<a class=quiet href="sndclm.html#outa" onmouseout="UnTip()" onmouseover="Tip(sndclm_outa_tip)">outa</a> i (<a class=quiet href="sndclm.html#oscil" onmouseout="UnTip()" onmouseover="Tip(sndclm_oscil_tip)">oscil</a> o)))))) + +<pre class="indented"> +Scheme: (set! (sample 100) .5) +Ruby: set_sample(100, 0.5) +Forth: 100 0.5 set-sample </pre> -<p>In the past, the argument to run had to be a "thunk", a procedure of no arguments; -this style of use is still supported. + +<p>'samp' defaults to the current cursor location. If 'chn' is #t, sample returns a list of all the +samples at 'samp', so: </p> -</td></tr></table> -<A NAME="declare"></A> -Functions embedded within run may need to declare the type of their arguments; run assumes each variable has one type (integer by default) throughout its life. -So, the following code -displays "0", rather than "3.14": +<pre class="indented"> +(define* (frample samp snd edpos) + (apply float-vector (sample samp snd #t edpos))) +</pre> -<pre> - (run (let ((x 3.14)) (define (a b) (display b)) (a x))) +<div class="separator"></div> + + +<!-- samples --> +<pre class="indented"> +<em class=def id="samples">samples</em> samp samps snd chn edpos </pre> -The "b" argument to "a" is assumed to be an integer, and passing in a float -causes nothing but confusion. To get this code to work right: +<p>This returns a vct 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> - (run (let ((x 3.14)) (define (a b) (<em class=red>declare</em> (b real)) (display b)) (a x))) +<pre class="indented"> +> (samples 1000 10) +#<vct[len=10]: 0.033 0.035 0.034 0.031 0.026 0.020 0.013 0.009 0.005 0.004> +> (set! (samples 1000 10) (make-vct 10 .1)) +#<vct[len=10]: 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100> </pre> +<div class="separator"></div> -The current declarable types include any <a href="sndclm.html#defgenerator">defgenerator</a> type and: -<pre> - int float boolean char string list symbol keyword vct sampler mix-sampler - sound-data clm float-vector int-vector vct-vector list-vector clm-vector +<!-- sample-type --> +<pre class="indented"> +<em class=def id="sampletype">sample-type</em> snd </pre> -declare is modelled after Common Lisp's declare; it is specific to run. -<br><br> -The use of the run macro is hidden in many contexts: <a class=quiet href="#mapchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_mapchannel_tip)">map-channel</a>, -<a class=quiet href="#findchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_findchannel_tip)">find-channel</a>, etc. Internally the Snd run macro -uses 64-bit ints and doubles. -See <a href="#optimization">optimization</a> -for some timings. In Ruby, it's possible to use the <a href="http://www.zenspider.com/Languages/Ruby/">RubyInline</a> module instead. -</td></tr><tr><td colspan=2 height=18></td></tr> +<p>This returns the sound's sample type — 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 — Perry Cook's book "Real Sound Synthesis" +has examples. +</p> -<!-- sample --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sample">sample</a> <em class=narg>samp snd chn edpos</em></code> -</td></tr><tr><td></td><td> -This function gives the value of sample 'samp' in the given channel. -<pre> - Scheme: (set! (sample 100) .5) +<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> - Ruby: set_sample(100, 0.5) +<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> - Forth: 100 0.5 set-sample +<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> -If the desired sample happens to fall outside the current buffer -for the indicated channel, sample grinds to a halt — if you're -running a loop through a bunch of samples, use the <a href="#samplers">samplers</a> -or <a href="#channeltovct">channel->vct</a> instead. 'samp' defaults to the current cursor location. -</td></tr><tr><td colspan=2 height=18></td></tr> +<p>or (an alternative that sets the underlying database entry, rather than the current in-Snd choice): +</p> -<!-- samples --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="samples">samples</a> <em class=narg>samp samps snd chn edpos</em></code> -</td></tr><tr><td></td><td> -This returns a vct of 'samps' samples starting at 'samp' in the given channel. -'samp' defaults to 0. 'samps' defaults to frames - '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>): -<pre> - <em class=listener>:</em><em class=typing>(samples 1000 10)</em> - <em class=listener>#<vct[len=10]: 0.033 0.035 0.034 0.031 0.026 0.020 0.013 0.009 0.005 0.004></em> - <em class=listener>:</em><em class=typing>(set! (samples 1000 10) (make-vct 10 .1))</em> - <em class=listener>#<vct[len=10]: 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100 0.100></em> +<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> -</td></tr><tr><td colspan=2 height=18></td></tr> + +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="savesound">save-sound</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -save-sound saves 'snd', writing the current state of the sound to its underlying sound file, (like the File menu's Save option). +<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 --> -<A NAME="saveexamples"></a> -<TABLE border=3 bordercolor="tan" hspace=20 vspace=10><tr><td> -<small><blockquote> -save all sounds: <code>(for-each save-sound (sounds))</code><br> -save a sound under a different name: <a href="#savesoundas">save-sound-as</a><br> -extract one channel from a sound: <a href="#extractchannel">extract-channel</a><br> -extract a set of channels from a sound: <a href="#extractchannels">extract-channels</a><br> -save a sound in a different format or header: <a href="#savesoundas">save-sound-as</a><br> -backup edits automatically: <a href="sndscm.html#autosave">autosave</a><br> -check first for unsaved edits: <a href="#askaboutunsavededits">ask-about-unsaved-edits</a><br> -save Snd's complete state (unsaved edits and all): <a href="#savestate">save-state</a>, <a href="#savedir">save-dir</a>, <a href="#savestatehook">save-state-hook</a>, <a href="#savestatefile">save-state-file</a><br> -save the selection: <a href="#saveselection">save-selection</a><br> -save a region: <a href="#saveregion">save-region</a><br> -save a mix: <a href="#savemix">save-mix</a><br> -save the control panel state: <a href="#savecontrols">save-controls</a><br> -save currently defined envelopes (envelope editor): <a href="#saveenvelopes">save-envelopes</a><br> -start the file save dialog: <a href="#savesounddialog">save-sound-dialog</a><br> -start the selection save dialog: <a href="#saveselectiondialog">save-selection-dialog</a><br> -start the region save dialog: <a href="#saveregiondialog">save-region-dialog</a><br> -save the current listener text: <a href="#savelistener">save-listener</a><br> -save keyboard macros: <a href="#savemacros">save-macros</a><br> -save marks: <a href="#savemarks">save-marks</a><br> -save just the edit history: <a href="#saveedithistory">save-edit-history</a><br> +<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="#remembersoundstate">remember-sound-state</a><br> -save the current fft peak info: <a href="#peaks">peaks</a><br> -</blockquote></small> +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> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> + <!-- save-sound-as --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="savesoundas">save-sound-as</a> <em class=narg>:file :sound :header-type :data-format :srate :channel :edit-position :comment</em></code> -</td></tr><tr><td></td><td> -This saves 'sound' as 'file' (like the 'File:Save as' menu option). If 'channel' is specified, +<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 :data-format -is given, the sound file is written using that data format. +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. -<pre> - (save-sound-as "test.snd" :data-format mus-bdouble :header-type mus-aifc) +</p> + +<pre class="indented"> +(save-sound-as "test.snd" :sample-type mus-bdouble :header-type mus-aifc) </pre> -saves the currently selected sound as an AIFC file using big-endian doubles for the samples. -<br><br> -To start a parallel editing branch on a given file, you could: -<pre> - (save-sound-as "test.snd") (<a class=quiet href="#opensound" onmouseout="UnTip()" onmouseover="Tip(extsnd_opensound_tip)">open-sound</a> "test.snd") + +<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> -To define an explicit channel extraction function:<br> -<pre> - Scheme: - (define (<a name="extractchannel">extract-channel</a> filename snd chn) (<em class=red>save-sound-as</em> filename snd :channel chn)) +<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 +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 ; +Forth: +: extract-channel { filename snd chn } filename snd :channel chn save-sound-as ; </pre> -The hooks called during a save operation are: -<pre> - <a class=quiet href="#beforesaveashook" onmouseout="UnTip()" onmouseover="Tip(extsnd_beforesaveashook_tip)">before-save-as-hook</a> — can cancel the request or set its output parameters - <a class=quiet href="#savehook" onmouseout="UnTip()" onmouseover="Tip(extsnd_savehook_tip)">save-hook</a> - sound saved - if any sample is clipped during save, <a class=quiet href="#cliphook" onmouseout="UnTip()" onmouseover="Tip(extsnd_cliphook_tip)">clip-hook</a> - <a class=quiet href="#aftersaveashook" onmouseout="UnTip()" onmouseover="Tip(extsnd_aftersaveashook_tip)">after-save-as-hook</a> + +<p>The hooks called during a save operation are: +</p> + +<pre class="indented"> +<a class=quiet href="#beforesaveashook">before-save-as-hook</a> — 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> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- scale-by --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="scaleby">scale-by</a> scalers <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -scale-by <a href="snd.html#scaling">scales</a> the amplitude of 'snd' by 'scalers'. Unlike most of these functions, +<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 vct. 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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- scale-channel --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="scalechannel">scale-channel</a> scl <em class=narg>beg dur snd chn edpos</em></code> -</td></tr><tr><td></td><td> -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'. -The multichannel version is <a href="sndscm.html#scalesound">scale-sound</a> in frame.scm. <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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (scale-channel 2.0) -(<a class=quiet href="#scaleby" onmouseout="UnTip()" onmouseover="Tip(extsnd_scaleby_tip)">scale-by</a> 2.0) -(<a class=quiet href="#mapchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_mapchannel_tip)">map-channel</a> (lambda (val) (* val 2.0))) -(set! (<a class=quiet href="#maxamp" onmouseout="UnTip()" onmouseover="Tip(extsnd_maxamp_tip)">maxamp</a>) (* 2 (<a class=quiet href="#maxamp" onmouseout="UnTip()" onmouseover="Tip(extsnd_maxamp_tip)">maxamp</a>))) -(<a class=quiet href="#envsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_envsound_tip)">env-sound</a> '(0 2 1 2)) -(<a class=quiet href="#envchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_envchannel_tip)">env-channel</a> (<a class=quiet href="sndclm.html#make-env" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_env_tip)">make-env</a> '(0 1 1 1) :scaler 2.0 :length (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a>))) -(<a class=quiet href="#clmchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_clmchannel_tip)">clm-channel</a> (<a class=quiet href="sndclm.html#make-one-zero" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_one_zero_tip)">make-one-zero</a> :a0 2.0 :a1 0.0)) -(<a class=quiet href="#filterchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_filterchannel_tip)">filter-channel</a> (<a class=quiet href="#vct" onmouseout="UnTip()" onmouseover="Tip(extsnd_vct_tip)">vct</a> 2.0) 1) -(<a class=quiet href="#vcttochannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_vcttochannel_tip)">vct->channel</a> (<a class=quiet href="#vctscale" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctscale_tip)">vct-scale!</a> (<a class=quiet href="#channeltovct" onmouseout="UnTip()" onmouseover="Tip(extsnd_channeltovct_tip)">channel->vct</a>) 2.0) 0) -(<a class=quiet href="sndscm.html#sounddatatosound" onmouseout="UnTip()" onmouseover="Tip(sndscm_sounddatatosound_tip)">sound-data->sound</a> (<a class=quiet href="#sounddata*" onmouseout="UnTip()" onmouseover="Tip(extsnd_sounddata_times_tip)">sound-data*</a> (<a class=quiet href="sndscm.html#soundtosounddata" onmouseout="UnTip()" onmouseover="Tip(sndscm_soundtosounddata_tip)">sound->sound-data</a>) 2.0)) -(begin (<a class=quiet href="#selectall" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectall_tip)">select-all</a>) (<a class=quiet href="#mixselection" onmouseout="UnTip()" onmouseover="Tip(extsnd_mixselection_tip)">mix-selection</a> 0)) -(begin (<a class=quiet href="#selectall" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectall_tip)">select-all</a>) (<a class=quiet href="#scaleselectionby" onmouseout="UnTip()" onmouseover="Tip(extsnd_scaleselectionby_tip)">scale-selection-by</a> 2.0)) -(begin (<a class=quiet href="#savesoundas" onmouseout="UnTip()" onmouseover="Tip(extsnd_savesoundas_tip)">save-sound-as</a> "temp.snd") (<a class=quiet href="#mix" onmouseout="UnTip()" onmouseover="Tip(extsnd_mix_tip)">mix</a> "temp.snd" 0) (delete-file "temp.snd")) - -(let ((flt (<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> 8))) +(<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->channel (float-vector-scale! (channel->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 0.0))) (set! (flt 0) 2.0) - (let ((cnv (<a class=quiet href="sndclm.html#make-convolve" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_convolve_tip)">make-convolve</a> :filter flt)) - (sf (<a class=quiet href="#makesampler" onmouseout="UnTip()" onmouseover="Tip(extsnd_makesampler_tip)">make-sampler</a> 0))) - (<a class=quiet href="#mapchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_mapchannel_tip)">map-channel</a> + (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" onmouseout="UnTip()" onmouseover="Tip(sndclm_convolve_tip)">convolve</a> cnv (lambda (dir) - (<a class=quiet href="#readsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_readsample_tip)">read-sample</a> sf))))))) + (<a class=quiet href="sndclm.html#convolve">convolve</a> cnv (lambda (dir) + (<a class=quiet href="#readsample">read-sample</a> sf))))))) -(<a class=quiet href="#vcttochannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_vcttochannel_tip)">vct->channel</a> (<a class=quiet href="sndscm.html#polydoc" onmouseout="UnTip()" onmouseover="Tip(sndscm_poly_times_tip)">poly*</a> (<a class=quiet href="#channeltovct" onmouseout="UnTip()" onmouseover="Tip(extsnd_channeltovct_tip)">channel->vct</a> 0 (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a>)) (<a class=quiet href="#vct" onmouseout="UnTip()" onmouseover="Tip(extsnd_vct_tip)">vct</a> 2.0))) ; poly.scm (sound = polynomial coeffs) +(float-vector->channel (<a class=quiet href="sndscm.html#polydoc">poly*</a> (channel->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="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a>)) +(let* ((len (<a class=quiet href="#framples">framples</a>)) (fsize (expt 2 (ceiling (/ (log len) (log 2))))) - (rl (<a class=quiet href="#channeltovct" onmouseout="UnTip()" onmouseover="Tip(extsnd_channeltovct_tip)">channel->vct</a> 0 fsize)) - (im (<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> fsize))) - (<a class=quiet href="sndclm.html#fft" onmouseout="UnTip()" onmouseover="Tip(sndclm_fft_tip)">mus-fft</a> rl im fsize) - (<a class=quiet href="sndclm.html#fft" onmouseout="UnTip()" onmouseover="Tip(sndclm_fft_tip)">mus-fft</a> rl im fsize) - (<a class=quiet href="sndclm.html#fft" onmouseout="UnTip()" onmouseover="Tip(sndclm_fft_tip)">mus-fft</a> rl im fsize) - (<a class=quiet href="sndclm.html#fft" onmouseout="UnTip()" onmouseover="Tip(sndclm_fft_tip)">mus-fft</a> rl im fsize) - (<a class=quiet href="#vcttochannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_vcttochannel_tip)">vct->channel</a> (<a class=quiet href="#vctscale" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctscale_tip)">vct-scale!</a> rl (/ 2.0 (* fsize fsize))) 0 len)) - -(do ((i 0 (+ 1 i))) - ((= i (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a>))) + (rl (channel->float-vector 0 fsize)) + (im (make-float-vector fsize 0.0))) + (<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->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! — it involves a separate edit on each sample - (set! (<a class=quiet href="#sample" onmouseout="UnTip()" onmouseover="Tip(extsnd_sample_tip)">sample</a> i) (* 2 (<a class=quiet href="#sample" onmouseout="UnTip()" onmouseover="Tip(extsnd_sample_tip)">sample</a> i)))) + (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_sample_tip)">sample</a> ctr) (* 2.0 (<a class=quiet href="#sample" onmouseout="UnTip()" onmouseover="Tip(extsnd_sample_tip)">sample</a> ctr))) + (set! (<a class=quiet href="#sample">sample</a> ctr) (* 2.0 (<a class=quiet href="#sample">sample</a> ctr))) (set! ctr (+ ctr 2)) (if (<= ctr end) (them us))))) us)))) - ((make-scaler 0 (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a>)) - (make-scaler 1 (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a>)))) -</pre></td></tr></table> -</td></tr> + ((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? --> -<tr><td colspan=2 height=18></td></tr> + <!-- scale-to --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="scaleto">scale-to</a> <em class=narg>norms snd chn</em></code> -</td></tr><tr><td></td><td> -scale-to <a href="snd.html#scaling">normalizes</a> 'snd' to 'norms' (following <a class=quiet href="#sync" onmouseout="UnTip()" onmouseover="Tip(extsnd_sync_tip)">sync</a> as in <a href="#scaleby">scale-by</a>). -<code>(scale-to 0.5)</code> scales the current channel so that its maxamp is 0.5. +<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 vct. -</td></tr><tr><td colspan=2 height=18></td></tr> - +</p> +<div class="separator"></div> -<!-- scan-chan --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def>scan-chan</a> func <em class=narg>start end snd chn edpos</em></code> -</td></tr><tr><td></td><td> -scan-chan applies 'func' to samples in the specified channel. -It is the old ("irregular") version of <a href="#scanchannel">scan-channel</a>. -</td></tr><tr><td colspan=2 height=18></td></tr> <!-- scan-channel --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="scanchannel">scan-channel</a> func <em class=narg>beg dur snd chn edpos</em></code> -</td></tr><tr><td></td><td> -scan-channel "scans" the data in the specified channel between the given sample numbers (the default +<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 (>= pos end) + (func (next-sample rd))) + (and (< 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 from sample 0 to the end looking for any sample greater than -.1:<br> -<pre> -><em class=typing>(scan-channel (lambda (y) (> y .1)))</em> -<em class=listener>4423</em> -</pre> -In this case, we found such a sample at position 4423.<br> -<pre> -(define every-sample? - (lambda (proc) - (let ((baddy (<em class=red>scan-channel</em> (lambda (y) - (not (proc y)))))) - (if baddy (set! (<a class=quiet href="#cursor" onmouseout="UnTip()" onmouseover="Tip(extsnd_cursor_tip)">cursor</a>) baddy)) - (not baddy)))) - -><em class=typing>(every-sample? (lambda (y) (< y .5)))</em> -<em class=listener>#t</em> -</pre> -To scan all the channels of a multichannel sound in parallel, see -<a href="sndscm.html#scansound">scan-sound</a>. -<br><br> -In scan-channel, find, and count-matches (all the same underlying procedure), an attempt to jump back -into a previous call will not work. That is, - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(let ((not-a-good-idea #f)) - (<em class=red>scan-channel</em> (lambda (y) - (call-with-current-continuation - (lambda (call) - (set! not-a-good-idea call))) - (> y .001))) - (not-a-good-idea)) -</pre></td></tr></table> - -will die with a segfault (this is fixable, with much effort and grumbling). If you want a continuable search, use a sampler: - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define reader #f) -(define last-proc #f) -(define (<A NAME="scanagain">scan-again</a>) - (if (<a class=quiet href="#sampleratendQ" onmouseout="UnTip()" onmouseover="Tip(extsnd_sampleratendQ_tip)">sampler-at-end?</a> reader) - #f - (let ((val (last-proc (reader)))) - (if val - (list val (- (<a class=quiet href="#samplerposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_samplerposition_tip)">sampler-position</a> reader) 1)) - (scan-again))))) -(define (my-scan-chan proc) - (set! last-proc proc) - (set! reader (<a class=quiet href="#makesampler" onmouseout="UnTip()" onmouseover="Tip(extsnd_makesampler_tip)">make-sampler</a> 0)) - (scan-again)) -</pre></td></tr></table> - -Now <code>(my-scan-chan (lambda (y) (> y .1)))</code> finds the first such sample, and -subsequent <code>(scan-again)</code> calls continue the search where the last call left off. -</td></tr><tr><td colspan=2 height=18></td></tr> - +current channel looking for any sample greater than .1: +</p> -<!-- search-procedure --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="searchprocedure">search-procedure</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This gives the current global or sound-local (if 'snd' is specified) search procedure. -<pre> - (set! (<a class=quiet href="#searchprocedure" onmouseout="UnTip()" onmouseover="Tip(extsnd_searchprocedure_tip)">search-procedure</a>) (lambda (y) (> y .1))) +<pre class="indented"> +> (scan-channel (lambda (y) (> y .1))) +4423 </pre> -</td></tr><tr><td colspan=2 height=18></td></tr> + +<div class="separator"></div> <!-- selected-channel --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="selectedchannel">selected-channel</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -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'. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="selectedsound">selected-sound</a></code> -</td></tr><tr><td></td><td> -This returns the currently selected sound; you can set it to select a sound. It returns #f is there is no selected sound. -<pre> - (or (<a class=quiet href="#selectedsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>) - (and (not (null? (<a class=quiet href="#sounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_sounds_tip)">sounds</a>))) - (car (<a class=quiet href="#sounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_sounds_tip)">sounds</a>)))) +<pre class="indented"> +<em class=def id="selectedsound">selected-sound</em> </pre> -returns the currently selected sound, if any, and failing that, any other sound that is currently open. -</td></tr><tr><td colspan=2 height=18></td></tr> + +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="selectchannel">select-channel</a> <em class=narg>chn</em></code> -</td></tr><tr><td></td><td> -This selects channel 'chn' in the currently selected sound; -equivalent to <code>(set! (<a class=quiet href="#selectedchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedchannel_tip)">selected-channel</a>) chn)</code>. +<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>. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- select-sound --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="selectsound">select-sound</a> snd</code> -</td></tr><tr><td></td><td> -This selects sound 'snd' (a sound object or an index); equivalent to <code>(set! (<a class=quiet href="#selectedsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>) snd)</code>. +<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>. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- set-samples --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="setsamples">set-samples</a> samp samps data <em class=narg>snd chn trunc edname infile-chan edpos auto-delete</em></code> -</td></tr><tr><td></td><td> -set-samples (and its related (set! (samples...)...) form) set the given channel's samples starting from +<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'. -<pre> - (set! (samples 0 100) (make-vct 100 .1)) - (set-samples 0 100 (make-vct 100 .1)) +</p> +<pre class="indented"> +(set! (samples 0 100) (make-vct 100 .1)) +(set-samples 0 100 (make-vct 100 .1)) </pre> -both change all samples between 0 and 100 to be 0.1. + +<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. -<pre> - (set-samples 10000 20000 "oboe.snd") +</p> + +<pre class="indented"> +(set-samples 10000 20000 "oboe.snd") </pre> -replaces 10000 samples with data from oboe.snd. + +<p>replaces 10000 samples with data from oboe.snd. If 'data' is a vct, set-samples is identical to <a href="#vcttochannel">vct->channel</a>. If 'trunc' is #t and 'samp' is 0, the sound is truncated (if necessary) to reflect the end of 'data'. @@ -9019,70 +9127,74 @@ 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). -<br><br> -The form (set! (<a class=quiet href="#samples" onmouseout="UnTip()" onmouseover="Tip(extsnd_samples_tip)">samples</a> samp samps 'snd chn trunc edname infile-chan edpos auto-delete') data) can also be used. -'env-sound-interp' in examp.scm has an example of the file version, using -sound-data objects and mus-sound-write to create a temporary file, but -it's probably simpler to use <a href="sndscm.html#withsound">with-sound</a> (see also linear-src-channel in dsp.scm): +</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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define (step-src) - (let* ((rd (<a class=quiet href="#makesampler" onmouseout="UnTip()" onmouseover="Tip(extsnd_makesampler_tip)">make-sampler</a> 0)) - (o (<a class=quiet href="sndclm.html#make-oscil" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_oscil_tip)">make-oscil</a> 2205.0)) - (s (<a class=quiet href="sndclm.html#make-src" onmouseout="UnTip()" onmouseover="Tip(sndclm_make_src_tip)">make-src</a> :srate 0.0)) - (incr (+ 2.0 (<a class=quiet href="sndclm.html#oscil" onmouseout="UnTip()" onmouseover="Tip(sndclm_oscil_tip)">oscil</a> o))) - (tempfile (<em class=red>with-sound</em> (:output (<a class=quiet href="#sndtempnam" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndtempnam_tip)">snd-tempnam</a>) :srate (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a>) :to-snd #f) - (<a class=quiet href="#run">run</a> - (do ((samp 0 (+ 1 samp))) - ((<a class=quiet href="#sampleratendQ" onmouseout="UnTip()" onmouseover="Tip(extsnd_sampleratendQ_tip)">sampler-at-end?</a> rd)) - (<a class=quiet href="sndclm.html#out-any" onmouseout="UnTip()" onmouseover="Tip(sndclm_out_any_tip)">out-any</a> samp (<a class=quiet href="sndclm.html#src" onmouseout="UnTip()" onmouseover="Tip(sndclm_src_tip)">src</a> s incr (lambda (dir) (<a class=quiet href="#readsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_readsample_tip)">read-sample</a> rd))) 0) - (if (= (modulo samp 2205) 0) - (set! incr (+ 2.0 (<a class=quiet href="sndclm.html#oscil" onmouseout="UnTip()" onmouseover="Tip(sndclm_oscil_tip)">oscil</a> o)))))))) - (len (<a class=quiet href="#mussoundframes" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussoundframes_tip)">mus-sound-frames</a> tempfile))) + (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))))))) + (len (<a class=quiet href="#mussoundframples">mus-sound-framples</a> tempfile))) (<em class=red>set-samples</em> 0 (- len 1) tempfile #f #f #t "step-src" 0 #f #t))) -</pre></td></tr></table> -</td></tr><tr><td colspan=2 height=18></td></tr> +</pre> +<div class="separator"></div> <!-- short-file-name --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="shortfilename">short-file-name</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This returns the brief (no directory) form of the sound's filename. +<pre class="indented"> +<em class=def id="shortfilename">short-file-name</em> snd +</pre> -<pre> - ><em class=typing>(open-sound "oboe.snd")</em> - <em class=listener>#<sound 0></em> - ><em class=typing>(file-name (integer->sound 0))</em> - <em class=listener>"/home/bil/cl/oboe.snd"</em> - ><em class=typing>(short-file-name (integer->sound 0))</em> - <em class=listener>"oboe.snd"</em> +<p>This returns the brief (no directory) form of the sound's filename. +</p> + +<pre class="indented"> +> (open-sound "oboe.snd") +#<sound 0> +> (file-name (integer->sound 0)) +"/home/bil/cl/oboe.snd" +> (short-file-name (integer->sound 0)) +"oboe.snd" </pre> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- show-axes --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="showaxes">show-axes</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This determines what axes are displayed. -If show-axes is <code>show-all-axes</code> (the default), both the x and y axes are displayed; if it is <code>show-x-axis</code>, +<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. -<code>show-no-axes</code> omits both x and y axes. To remove the x axis label, use -either <code>show-x-axis-unlabelled</code> or <code>show-all-axes-unlabelled</code>. -To omit all the x axis labels and ticks (but include the y axis as usual) use <code>show-bare-x-axis</code>. +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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- show-grid --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="showgrid">show-grid</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -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>. -<br><br> -<img src="pix/grid.png" alt="grid" onmouseout="UnTip()" onmouseover="Tip('<pre>snd -horizontal now.snd now.snd<br>(set! (show-grid) #t)<br>(set! (grid-density 1) 0.2)</pre>')"> -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 @@ -9094,407 +9206,476 @@ If show-grid is #t (the default is #f), a background grid is displayed (default --> + <!-- show-marks --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="showmarks">show-marks</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -If show-marks is #t (the default), marks are displayed. This is the '<a href="snd.html#marks">Show marks</a>' View menu option. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="showmixwaveforms">show-mix-waveforms</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -If show-mix-waveforms is #t (the default), a mixed sound is displayed as a separate waveform above the main data. The rectangular tag +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- show-sonogram-cursor --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="showsonogramcursor">show-sonogram-cursor</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -If show-sonogram-cursor is #t (the default is #f), the cursor is also displayed in the sonogram. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="showtransformpeaks">show-transform-peaks</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -If show-transform-peaks is #t (the default is #f), transform peak information is included in the transform display. +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- show-y-zero --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="showyzero">show-y-zero</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -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. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="smoothchannel">smooth-channel</a> <em class=narg>beg dur snd chn edpos</em></code> -</td></tr><tr><td></td><td> -smooth-channel is the <a class=quiet href="#regularizedargs" onmouseout="UnTip()" onmouseover="Tip(extsnd_regularizedargs_tip)">regularized</a> version of <a href="#smoothsound">smooth-sound</a>. -smooth-channel-via-ptree in examp.scm is the virtual form. +<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 --> -<A NAME="smoothexamples"></a> -<TABLE border=3 bordercolor="tan" hspace=20 vspace=10><tr><td> -<small><blockquote> -smooth all channels: <a href="#smoothsound">smooth-sound</a><br> -smooth selection: <a href="#smoothselection">smooth-selection</a><br> -delete the selection and smooth the splice: <a href="#deleteselectionandsmooth">delete-selection-and-smooth</a><br> -smoothing as virtual op: smooth-channel-via-ptree in examp.scm<br> +<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="#filtersinsnd">filter</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> -</blockquote></small> +</small></blockquote> </td></tr></TABLE> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> + <!-- smooth-sound --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="smoothsound">smooth-sound</a> <em class=narg>beg num snd chn</em></code> -</td></tr><tr><td></td><td> -smooth-sound applies a smoothing function to the indicated data. This produces a sinusoid between -the end points: +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define (smoother y0 y1 num) - "go sinusoidally from y0 to y1 over num samps" - (let ((v (<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> (+ 1 num))) + (let ((v (make-float-vector (+ 1 num) 0.0)) (angle (if (> y1 y0) pi 0.0)) (off (* .5 (+ y0 y1))) (scale (* 0.5 (abs (- y1 y0))))) - (do ((i 0 (+ 1 i))) + (do ((i 0 (+ i 1))) ((= i num) v) (set! (v i) (+ off (* scale (cos (+ angle (* i (/ pi num)))))))))) -</pre></td></tr></table> +</pre> -<img src="pix/click.png" alt="smoother"> -<br> -For a fancier version, see fft-smoother in examp.scm. See also <a href="sndscm.html#removeclicks">remove-clicks</a> in examp.scm. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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? --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="soundp">sound?</a> snd</code> -</td></tr><tr><td></td><td> -sound? returns #t if 'snd' refers to an open sound. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="soundfontinfo">soundfont-info</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This returns a list of lists describing 'snd' as a soundfont. Each inner list +<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. -<pre> - :<em class=typing>(soundfont-info)</em> - <em class=listener>(("BrSteel_E4" 0 65390 65458) ("BrSteel_B2" 65490 131458 131637) ...)</em> +</p> + +<pre class="indented"> +> (soundfont-info) +(("BrSteel_E4" 0 65390 65458) ("BrSteel_B2" 65490 131458 131637) ...) </pre> -To set a named mark at the start of each sound with un-named marks -at the loop points: -<table border=0 cellpadding=10><tr><td> -<table border=0><tr><td><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) (letrec ((sf2it (lambda (lst) - (if (not (null? lst)) + (if (pair? lst) (let* ((vals (car lst)) - (m1 (<a class=quiet href="#addmark" onmouseout="UnTip()" onmouseover="Tip(extsnd_addmark_tip)">add-mark</a> (cadr vals)))) - (set! (<a class=quiet href="#markname" onmouseout="UnTip()" onmouseover="Tip(extsnd_markname_tip)">mark-name</a> m1) (car vals))) - (<a class=quiet href="#addmark" onmouseout="UnTip()" onmouseover="Tip(extsnd_addmark_tip)">add-mark</a> (caddr vals)) - (<a class=quiet href="#addmark" onmouseout="UnTip()" onmouseover="Tip(extsnd_addmark_tip)">add-mark</a> (cadddr vals)) - (sf2it (cdr lst)))))) + (m1 (<a class=quiet href="#addmark">add-mark</a> (cadr vals)))) + (set! (<a class=quiet href="#markname">mark-name</a> m1) (car vals)) + (<a class=quiet href="#addmark">add-mark</a> (caddr vals)) + (<a class=quiet href="#addmark">add-mark</a> (cadddr vals)) + (sf2it (cdr lst))))))) (sf2it (<em class=red>soundfont-info</em>)))) -</pre></td></tr></table> -</td><td> -<img src="pix/bongo.png" alt="soundfont marks"> -</td></tr></table> +</pre> -See also explode-sf2 in examp.scm. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="soundtointeger">sound->integer</a> sound</code> -</td></tr><tr><td></td><td> -This is the counterpart to <a href="#integertosound">integer->sound</a>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="soundtointeger">sound->integer</em> sound +</pre> + +<p>This is the counterpart to <a href="#integertosound">integer->sound</a>. +</p> +<div class="separator"></div> <!-- sound-loop-info --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="soundloopinfo">sound-loop-info</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This gives info about loop points from the sound's header. The loop info is a list of +<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. -<pre> - :<em class=typing>(sound-loop-info)</em> - <em class=listener>(24981 144332 0 0 60 0 1 0)</em> +</p> + +<pre class="indented"> +> (sound-loop-info) +(24981 144332 0 0 60 0 1 0) </pre> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- sound-properties --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="soundproperties">sound-properties</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This is a property list associated with the given sound. It is set to '() at the time a sound is opened. The accessor +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- sound-property --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="soundproperty">sound-property</a> key snd</code> -</td></tr><tr><td></td><td> -sound-property provides access to a sound's <a href="#soundproperties">property list</a>. +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="separator"></div> <!-- sounds --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sounds">sounds</a></code> -</td></tr><tr><td></td><td> -sounds returns a list of currently active 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)): -<pre> - (map maxamp (sounds)) +</p> + +<pre class="indented"> +(map maxamp (sounds)) </pre> -Or, if + +<p>Or, if the return value is not needed: -<pre> - (for-each (lambda (snd) (display (<a class=quiet href="#shortfilename" onmouseout="UnTip()" onmouseover="Tip(extsnd_shortfilename_tip)">short-file-name</a> snd))) (sounds)) +</p> + +<pre class="indented"> +(for-each (lambda (snd) (display (<a class=quiet href="#shortfilename">short-file-name</a> snd))) (sounds)) </pre> -This can be + +<p>This can be extended to provide a complete list of sounds and channels (since many Snd functions take the "snd chn" arguments): +</p> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define (all-chans) - (let ((sndlist '()) - (chnlist '())) + (let ((sndlist ()) + (chnlist ())) (for-each (lambda (snd) - (do ((i (- (<a class=quiet href="#channels" onmouseout="UnTip()" onmouseover="Tip(extsnd_channels_tip)">channels</a> snd) 1) (- i 1))) + (do ((i (- (<a class=quiet href="#channels">channels</a> snd) 1) (- i 1))) ((< 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" onmouseout="UnTip()" onmouseover="Tip(extsnd_maxamp_tip)">maxamp</a> (all-chans)) -</pre></td></tr></table> -</td></tr><tr><td colspan=2 height=18></td></tr> +(apply map <a class=quiet href="#maxamp">maxamp</a> (all-chans)) +</pre> +<div class="separator"></div> <!-- spectrum-end --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="spectrumend">spectrum-end</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is the amount of the frequency domain to include in the spectrum +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- spectro-hop --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="spectrohop">spectro-hop</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is the distance (in pixels) moved between successive spectrogram traces +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- spectrum-start --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="spectrumstart">spectrum-start</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is the start point of the frequency domain in the spectrum +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- spectro-x-angle --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="spectroxangle">spectro-x-angle</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -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. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="spectroxscale">spectro-x-scale</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is the scaler (stretch amount) along the spectrogram x axis (the is default 1.0, in GL: 1.5). -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="spectroyangle">spectro-y-angle</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is the spectrogram y axis viewing angle (the default is 0.0, in GL: 320.0). -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="spectroyscale">spectro-y-scale</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is the scaler (stretch amount) for the spectrogram y axis (the default is 1.0). -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="spectrozangle">spectro-z-angle</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is the spectrogram viewing angle for the z axis (the default is 358.0, in GL: 0.0). -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="spectrozscale">spectro-z-scale</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is the scaler (stretch amount) for the z axis (the default is 0.1, in GL: 1.0). -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="squelchupdate">squelch-update</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is #t if graphic updates are currently squelched (turned off). If you're doing a sequence of edits where intermediate +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<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></td></tr></table> -</td></tr> +</pre> +<div class="separator"></div> <!-- srate --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="srate">srate</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This is the sound's sampling rate. If you set this to a new value, update-sound is called to +<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 (data-format, etc), but it can be annoying. -<br><br> -There are several srates floating around in Snd. +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" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussoundsrate_tip)">mus-sound-srate</a> filename)</code> returns a sound file's sampling rate. -<code>mus-srate</code> is associated with the CLM package (setting the implicit srate for oscil etc). -<code>default-output-srate</code> is the default sampling rate used when opening new files. -<code>enved-srate</code> is a constant that can be assigned to the envelope editor's <code>enved-target</code> (to apply an envelope to the sampling rate). -<code>region-srate</code> is the sampling rate associated with a region. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="srcchannel">src-channel</a> num-or-env <em class=narg>beg dur snd chn edpos</em></code> -</td></tr><tr><td></td><td> -src-channel preforms sampling rate conversion using 'warped sinc interpolation'. The +<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. -<code>(src-channel 2.0)</code> makes the sound go twice as fast. -This is the <a class=quiet href="#regularizedargs" onmouseout="UnTip()" onmouseover="Tip(extsnd_regularizedargs_tip)">regularized</a> version of <a href="#srcsound">src-sound</a>. -<pre> - <em class=listener>:</em><em class=typing>(frames)</em> ; current duration - <em class=listener>50828</em> - <em class=listener>:</em><em class=typing>(src-channel 2.0)</em> ; make it half as long - <em class=listener>2.0</em> - <em class=listener>:</em><em class=typing>(frames)</em> - <em class=listener>25415</em> - <em class=listener>:</em><em class=typing>(src-channel '(0 .5 1 1))</em> ; start slow and speed up - <em class=listener>(0 0.5 1 1)</em> - <em class=listener>:</em><em class=typing>(frames)</em> - <em class=listener>35235</em> - <em class=listener>:</em><em class=typing>(src-channel (make-env '(0 .5 1 1) :length 20000))</em> ; stick at 1 after sample 20000 - <em class=listener>#<env linear, pass: 35236 (dur: 20000), index: 1, scaler: 1.0000, offset: 0.0000, ...></em> - <em class=listener>:</em><em class=typing>(frames)</em> - <em class=listener>42964</em> +(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"> +> (framples) ; current duration +50828 +> (src-channel 2.0) ; make it half as long +2.0 +> (framples) +25415 +> (src-channel '(0 .5 1 1)) ; start slow and speed up +(0 0.5 1 1) +> (framples) +35235 +> (src-channel (make-env '(0 .5 1 1) :length 20000)) ; stick at 1 after sample 20000 +#<env linear, pass: 35236 (dur: 20000), index: 1, scaler: 1.0000, offset: 0.0000, ...> +> (framples) +42964 </pre> <!-- INDEX resampleexamples:Resampling --> -<A NAME="resampleexamples"></a> -<TABLE border=3 bordercolor="tan" hspace=20 vspace=10><tr><td> -<small><blockquote> -resample all chans: <a href="#srcsound">src-sound</a><br> -resample selection: <a href="#srcsoundselection">src-selection</a><br> -resample mix: speed control in <a href="snd.html#mixdialog">Mix dialog</a> (also <a href="#applycontrols">apply-controls</a>)<br> +<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="#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 (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> ("Forbidden Planet"), flange and chorus in dsp.scm and new-effects.scm<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="#setsamples">step-src</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> -<br> -</blockquote></small> +</small></blockquote> </td></tr></TABLE> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> + <!-- src-sound --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="srcsound">src-sound</a> num-or-env <em class=narg>base snd chn edpos</em></code> -</td></tr><tr><td></td><td> -src-sound performs sampling rate conversion using 'warped sinc interpolation'. The +<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. -<code>(src-sound 2.0)</code> speeds the sound up by a factor -of 2 (transposes it up an octave), whereas <code>(src-sound 0.5)</code> +(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). -<code>(src-sound '(0 1 1 2))</code> starts at the original speed, then +(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. -<br><br> -'num-or-env' can also be a CLM env generator (its duration should +</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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<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, @@ -9503,7 +9684,7 @@ how long the resultant note will be given an src envelope: ;;; tempo curve, so we use log(x) as integral of 1/x and ;;; take into account the local notion of "x". -(define (<a class=quiet NAME="exsrcduration">src-duration</a> e) +(define (<em class="noem">src-duration</em> e) (let* ((len (length e)) (ex0 (e 0)) (ex1 (e (- len 2))) @@ -9527,140 +9708,177 @@ how long the resultant note will be given an src envelope: ;;; (src-duration '(0 .5 .5 3 .6 1 .7 .1 .8 1.5 1 1)) -> 1.02474349685432 ;;; here we're using this in the Snd listener: -<em class=listener>></em><em class=typing>(frames)</em> -<em class=listener>220501</em> -<em class=listener>></em><em class=typing>(src-duration '(0 1 1 2))</em> -<em class=listener>0.693147180559945</em> -<em class=listener>></em><em class=typing>(src-sound '(0 1 1 2))</em> ; should be about .693 * 220500 frames -<em class=listener>(0 1 1 2)</em> -<em class=listener>></em><em class=typing>(frames)</em> -<em class=listener>152842</em> -<em class=listener>></em><em class=typing>(/ 152842.0 220501)</em> -<em class=listener>0.693157854159392</em><em class=typing></em> ; tada! -</pre></td></tr></table> - -The inverse, so to speak, of this is <a href="sndscm.html#srcfitenvelope">src-fit-envelope</a>: -<pre> +> (framples) +220501 +> (src-duration '(0 1 1 2)) +0.693147180559945 +> (src-sound '(0 1 1 2)) ; should be about .693 * 220500 framples +(0 1 1 2) +> (framples) +152842 +> (/ 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> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- start-playing --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="startplaying">start-playing</a> <em class=narg>chans srate background</em></code> -</td></tr><tr><td></td><td> -If a <a href="#makeplayer">play-list</a> is waiting, this starts it. 'chans' defaults to 1, +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- start-progress-report --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="startprogressreport">start-progress-report</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This starts a <a href="#progressreport">progress-report</a>. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="stopplayer">stop-player</a> player</code> -</td></tr><tr><td></td><td> -This removes 'player' from the current play-list (see <a href="#makeplayer">make-player</a>). -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="stopplaying">stop-playing</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -If 'snd' is playing, this stops it. +<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>. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- swap-channels --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="swapchannels">swap-channels</a> <em class=narg>snd1 chn1 snd2 chn2 beg dur edpos0 edpos1</em></code> -</td></tr><tr><td></td><td> -This swaps the indicated channels, between 'beg' and 'beg' + 'dur'. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define* (<a name="reversechannels">reverse-channels</a> snd) - (let* ((ind (or snd (<a class=quiet href="#selectedsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>) (car (<a class=quiet href="#sounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_sounds_tip)">sounds</a>)))) - (chns (<a class=quiet href="#channels" onmouseout="UnTip()" onmouseover="Tip(extsnd_channels_tip)">channels</a> ind))) +<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))) (let ((swaps (floor (/ chns 2)))) - (<a class=quiet href="#asoneedit" onmouseout="UnTip()" onmouseover="Tip(extsnd_asoneedit_tip)">as-one-edit</a> + (<a class=quiet href="#asoneedit">as-one-edit</a> (lambda () - (do ((i 0 (+ 1 i)) + (do ((i 0 (+ i 1)) (j (- chns 1) (- j 1))) ((= i swaps)) (<em class=red>swap-channels</em> ind i ind j))))))) -</pre></td></tr></table> +</pre> -Channel rotation is similar, though slightly more work; see scramble-channels in examp.scm. +<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->stereo</a> in extensions.scm for an example. Another example is swap-selection-channels in examp.scm. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- sync --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sync">sync</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -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 +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- sync-max --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="syncmax">sync-max</a></code> -</td></tr><tr><td></td><td> -This is the maximum <a href="#sync">sync</a> setting seen so far — it provides a painless way to get a sync value that +<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 — it provides a painless way to get a sync value that is guaranteed to be unique. To sync all currently open sounds: -<pre> - (let ((new-sync (+ 1 (<em class=red>sync-max</em>)))) - (for-each (lambda (snd) (set! (<a class=quiet href="#sync" onmouseout="UnTip()" onmouseover="Tip(extsnd_sync_tip)">sync</a> snd) new-sync)) (<a class=quiet href="#sounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_sounds_tip)">sounds</a>))) +</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> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- time-graph? --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="timegraphp">time-graph?</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is #t if the time domain graph is being displayed (the 'w' button). -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="timegraphstyle">time-graph-style</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This determines how time-domain data is displayed. +<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: -<pre> - graph-lines graph-dots graph-filled graph-lollipops graph-dots-and-lines +</p> + +<pre class="indented"> +graph-lines graph-dots graph-filled graph-lollipops graph-dots-and-lines - (set! (time-graph-style 0 4) graph-lollipops) +(set! (time-graph-style 0 4) graph-lollipops) </pre> -<img src="pix/graphstyle.png" alt="graph styles"> -</td></tr><tr><td colspan=2 height=18></td></tr> +<img class="indented" src="pix/graphstyle.png" alt="graph styles"> + +<div class="separator"></div> <!-- -(with-sound (:channels 5) (do ((i 0 (+ 1 i))) ((= i 5)) (fm-violin 0 .4 (* (+ 1 i) 100) .1 :degree (* i 72)))) -(do ((i 0 (+ 1 i))) ((= i 5)) (set! (time-graph-style 0 i) i)) +(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)) @@ -9673,77 +9891,88 @@ The choices are: <!-- time-graph-type --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="timegraphtype">time-graph-type</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -If time-graph-type is <code>graph-as-wavogram</code>, the time domain waveform is displayed as a -'<a href="snd.html#wavogram" onmouseout="UnTip()" onmouseover="Tip('<img src=\'pix/wavo.png\' width=\'640\' height=\'250\'>', TITLE, 'graph-as-wavogram', ABOVE, true)">wavogram</a>'. -The default is <code>graph-once</code>. See also <a href="#wavohop">wavo-hop</a> and <a href="#wavotrace">wavo-trace</a>. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="trackingcursorstyle">tracking-cursor-style</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -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 <code>cursor-cross</code> or <code>cursor-line</code> (the default). If you want some other shape, +<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). -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> -<!-- transform-frames --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="transformframes">transform-frames</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This returns either 0 if there is no transform, <a href="#transformsize">transform-size</a> if -<a href="#transformgraphtype">transform-graph-type</a> is <code>graph-once</code>, +<!-- 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> - <em class=listener>:</em><em class=typing>(set! (transform-graph?) #t)</em> ; turn on fft display - <em class=listener>#t</em> - <em class=listener>:</em><em class=typing>(transform-frames)</em> - <em class=listener>512</em> - <em class=listener>:</em><em class=typing>(set! (transform-graph-type) graph-as-sonogram)</em> - <em class=listener>1</em> ; 1 = graph-as-sonogram - <em class=listener>:</em><em class=typing>(transform-frames)</em> - <em class=listener>(1.0 375 256)</em> ; 1.0 -> full spectrum displayed - <em class=listener>:</em><em class=typing>(set! (transform-graph?) #f)</em> ; turn off fft display - <em class=listener>#f</em> - <em class=listener>:</em><em class=typing>(transform-frames)</em> - <em class=listener>0</em> +<pre class="indented"> +> (set! (transform-graph?) #t) ; turn on fft display +#t +> (transform-framples) +512 +> (set! (transform-graph-type) graph-as-sonogram) +1 ; 1 = graph-as-sonogram +> (transform-framples) +(1.0 375 256) ; 1.0 -> full spectrum displayed +> (set! (transform-graph?) #f) ; turn off fft display +#f +> (transform-framples) +0 </pre> - -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- transform-graph? --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="transformgraphp">transform-graph?</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is #t if the given channel is displaying a spectrum (the 'f' button). -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="transformgraphstyle">transform-graph-style</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This determines how frequency-domain data is displayed. +<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: -<pre> - graph-lines graph-dots graph-filled graph-lollipops graph-dots-and-lines +</p> + +<pre class="indented"> +graph-lines graph-dots graph-filled graph-lollipops graph-dots-and-lines </pre> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- transform-graph-type --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="transformgraphtype">transform-graph-type</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This determines the choice of spectral display. The choices are (default) <code>graph-once</code> (a single FFT), -<code>graph-as-sonogram</code>, and <code>graph-as-spectrogram</code>. +<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. @@ -9751,370 +9980,433 @@ Currently, the <a href="#fftlogfrequency">fft-log-frequency</a> and <a href="#no 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). -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- transform-normalization --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="normalizefft">transform-normalization</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is the transform normalization choice (default: <code>normalize-by-channel</code>). -If it is <code>normalize-by-channel</code> or <code>normalize-by-sound</code>, spectral data is -normalized to 1.0 before display. If <code>dont-normalize</code>, you get the +<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 — Snd tries to choose a y axis limit that makes successive displays move smoothly. -The other choice is <code>normalize-globally</code> (i.e. across all sounds). -</td></tr><tr><td colspan=2 height=18></td></tr> +The other choice is normalize-globally (i.e. across all sounds). +</p> +<div class="separator"></div> <!-- transform-sample --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="transformsample">transform-sample</a> <em class=narg>bin slice snd chn</em></code> -</td></tr><tr><td></td><td> -This is the current value of the transform (if any) in 'bin' and (if a +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- transform-size --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="transformsize">transform-size</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is the fft size (the default size is 512). It should be a power of 2. +<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, -<code>(expt 2 26)</code> is apparently too large), FFTW exits Snd! There is currently +(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 — 2^30 is probably the transform-size limit. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- transform-type --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="transformtype">transform-type</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is the spectrum transform type (the default is <code>fourier-transform</code>). -<pre> - fourier-transform wavelet-transform haar-transform - autocorrelation walsh-transform cepstrum +<pre class="indented"> +<em class=def id="transformtype">transform-type</em> snd chn </pre> -</td></tr><tr><td colspan=2 height=18></td></tr> + +<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->vct --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="transformtovct">transform->vct</a> <em class=narg>snd chn v</em></code> -</td></tr><tr><td></td><td> -This returns a vct with the transform data from the given channel. +<pre class="indented"> +<em class=def id="transformtovct">transform->vct</em> snd chn v +</pre> + +<p>This returns a vct with the transform data from the given channel. If 'v' (a vct) is provided, it is filled, rather than creating a new vct. See <a href="#fftpeak">fft-peak</a> for an example. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="undo">undo</a> <em class=narg>edits snd chn</em></code> -</td></tr><tr><td></td><td> -This undoes 'edits' edits (the default is 1) in the given channel. -Undo follows the <a class=quiet href="#sync" onmouseout="UnTip()" onmouseover="Tip(extsnd_sync_tip)">sync</a> field if it +<!-- 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: -<br> -<pre> -(define* (<a name="undochannel">undo-channel</a> (<a class=quiet href="#edits" onmouseout="UnTip()" onmouseover="Tip(extsnd_edits_tip)">edits</a> 1) snd chn) - (if (and snd (not (= (<a class=quiet href="#sync" onmouseout="UnTip()" onmouseover="Tip(extsnd_sync_tip)">sync</a> snd) 0)) chn) - (set! (<a class=quiet href="#editposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_editposition_tip)">edit-position</a> snd chn) - (max 0 (- (<a class=quiet href="#editposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_editposition_tip)">edit-position</a> snd chn) edits))) +</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> -See also <a href="#undohook">undo-hook</a>. +<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, <a name="undoedit">undo-edit</a>). +undo can also be accessed under the name undo_edit (in Scheme, undo-edit). +</p> <!-- INDEX undoexamples:Undo and Redo --> -<A NAME="undoexamples"></a> -<TABLE border=3 bordercolor="tan" hspace=20 vspace=10><tr><td> -<small><blockquote> -undo all edits: <a href="#revertsound">revert-sound</a><br> -specialize undo: <a href="#undohook">undo-hook</a><br> -protect against undo: <a href="#edithook">edit-hook</a><br> -redo edit: <a href="#redo">redo</a> and <a href="#redochannel">redo-channel</a><br> -move around in edit list: <a href="#editposition">edit-position</a> and <a href="#currenteditposition">current-edit-position</a><br> -About edit lists: <a href="#editlists">Edit lists</a><br><br> -</blockquote></small> - +<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> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> + <!-- update-lisp-graph --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="updatelispgraph">update-lisp-graph</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -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. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="updatesound">update-sound</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This causes Snd to update 'snd' (it re-reads the data from disk, flushing any pending edits). In some cases (primarily involving +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- update-time-graph --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="updatetimegraph">update-time-graph</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This forces Snd to redisplay 'chn's' time domain graph. See color-samples in draw.scm. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="updatetransformgraph">update-transform-graph</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This forces Snd to redisplay 'chn's' fft graph. For historical reasons, it also forces the current transform to completion. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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? --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="variablegraphp">variable-graph?</a> index</code> -</td></tr><tr><td></td><td> -This returns #t if 'index' refers to a variable graph (see <a href="#makevariablegraph" onmouseout="UnTip()" onmouseover="Tip('<img src=\'pix/vardpy.png\' width=\'250\' height=\'250\'>', TITLE, 'make-variable-display in snd-motif', ABOVE, true)">make-variable-graph</a>). -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="viewsound">view-sound</a> filename</code> -</td></tr><tr><td></td><td> -This opens 'filename' read-only (you can edit the sound within Snd, but you can't overwrite the original sound). -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="wavelettype">wavelet-type</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -If <a href="#transformtype">transform-type</a> is <code>wavelet-transform</code>, wavelet-type selects which +<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). -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- wavo-hop --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="wavohop">wavo-hop</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This sets the distance upward (in pixels) between wavogram traces; that is, +<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>. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- wavo-trace --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="wavotrace">wavo-trace</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This sets the length (in samples) of each wavogram trace (the default is 64). See <a href="#timegraphtype">time-graph-type</a>. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="withverbosecursor">with-verbose-cursor</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -If with-verbose-cursor is #t, the cursor's position and other information is constantly -displayed in the minibuffer. This is the View:Verbose cursor option +<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). -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- x-axis-label --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="xaxislabel">x-axis-label</a> <em class=narg>snd chn context</em></code> -</td></tr><tr><td></td><td> -This is the current x axis label. 'context' is one of <code>time-graph</code> (the default), <code>lisp-graph</code>, or -<code>transform-graph</code>. -<pre> - :<em class=typing>(x-axis-label)</em> - <em class=listener>"time"</em> - :<em class=typing>(set! (x-axis-label) "tempus")</em> - <em class=listener>"tempus"</em> +<pre class="indented"> +<em class=def id="xaxislabel">x-axis-label</em> snd chn context </pre> -</td></tr><tr><td colspan=2 height=18></td></tr> + +<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"> +> (x-axis-label) +"time" +> (set! (x-axis-label) "tempus") +"tempus" +</pre> +<div class="separator"></div> <!-- x-axis-style --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="xaxisstyle">x-axis-style</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -x-axis-style is the View menu 'X-axis units' option (the default value is <code>x-axis-in-seconds</code>). +<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 -(<code>x-axis-in-seconds</code>), in samples (<code>x-axis-in-samples</code>), expressed -as a percentage of the overall duration (<code>x-axis-as-percentage</code>, useful in envelope definitions), as a beat number (<code>x-axis-in-beats</code>), -as a measure number (<code>x-axis-in-measures</code>), or in digital clock format (DD:HH:MM:SS.ddd) (<code>x-axis-as-clock</code>, useful in +(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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- x-bounds --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="xbounds">x-bounds</a> <em class=narg>snd chn axis</em></code> -</td></tr><tr><td></td><td> -This returns <code>(list x0 x1)</code>, the current x axis bounds in seconds. To display the entire sound: -<pre> - (set! (x-bounds) (/ (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a>) (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a>))) +<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> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- x->position --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="xtoposition">x->position</a> x <em class=narg>snd chn axis</em></code> -</td></tr><tr><td></td><td> -This returns the graph (screen pixel) position that corresponds to the x axis value 'x'. -'axis' is one of <code>time-graph</code> (the default), <code>lisp-graph</code>, or <code>transform-graph</code>. +<pre class="indented"> +<em class=def id="xtoposition">x->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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- x-position-slider --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="xpositionslider">x-position-slider</a> <em class=narg>snd chn</em></code> -</td></tr> -<tr><td></td><td> +<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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- x-zoom-slider --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="xzoomslider">x-zoom-slider</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is the value of x axis zoom slider. See <a href="#zoomonepixel">zoom-one-pixel</a>. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="xrampchannel">xramp-channel</a> rmp0 rmp1 <em class=narg>base beg dur snd chn edpos</em></code> -</td></tr><tr><td></td><td> -xramp-channel is a slight extension of <a href="#rampchannel">ramp-channel</a>. It scales samples in the given sound/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'. -<pre> - (xramp-channel 0.0 1.0 32.0) +</p> + +<pre class="indented"> +(xramp-channel 0.0 1.0 32.0) </pre> -</td></tr><tr><td colspan=2 height=18></td></tr> +<div class="separator"></div> <!-- y-axis-label --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="yaxislabel">y-axis-label</a> <em class=narg>snd chn context</em></code> -</td></tr><tr><td></td><td> -This is the current y axis label. 'context' is one of <code>time-graph</code> (the default), <code>lisp-graph</code>, or <code>transform-graph</code>. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="ybounds">y-bounds</a> <em class=narg>snd chn axis</em></code> -</td></tr><tr><td></td><td> -This returns <code>(list y0 y1)</code>, the current y axis bounds. -To set the bounds to reflect the channel's maxamp, use <code>(set! (y-bounds) '())</code>. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(let ((maxval (apply max (<a class=quiet href="#maxamp" onmouseout="UnTip()" onmouseover="Tip(extsnd_maxamp_tip)">maxamp</a> #f #t)))) - (do ((i 0 (+ 1 i))) - ((= i (<a class=quiet href="#chans" onmouseout="UnTip()" onmouseover="Tip(extsnd_chans_tip)">channels</a>))) +<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></td></tr></table> +</pre> -Or to set each channel to its own maxamp: +<p>Or to set each channel to its own maxamp: +</p> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(do ((i 0 (+ 1 i))) - ((= i (<a class=quiet href="#chans" onmouseout="UnTip()" onmouseover="Tip(extsnd_chans_tip)">channels</a>))) - (let ((maxval (<a class=quiet href="#maxamp" onmouseout="UnTip()" onmouseover="Tip(extsnd_maxamp_tip)">maxamp</a> #f i))) +<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></td></tr></table> -</td></tr><tr><td colspan=2 height=18></td></tr> +</pre> +<div class="separator"></div> <!-- y->position --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="ytoposition">y->position</a> y <em class=narg>snd chn axis</em></code> -</td></tr><tr><td></td><td> -This returns the graph (screen pixel) position that corresponds to the y axis value 'y'. -'axis' is one of <code>time-graph</code> (the default), <code>lisp-graph</code>, or <code>transform-graph</code>. +<pre class="indented"> +<em class=def id="ytoposition">y->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. -</td></tr><tr><td colspan=2 height=18></td></tr> +</p> +<div class="separator"></div> <!-- y-position-slider --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="ypositionslider">y-position-slider</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is the value of y axis position slider. See zync in snd-motif.scm. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="yzoomslider">y-zoom-slider</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This is the value of y axis zoom slider. See <a href="#xdisplayenergy">display-energy</a>, or zync in snd-motif.scm. -</td></tr><tr><td colspan=2 height=18></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="zeropad">zero-pad</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -zero-pad is the fft zero pad size as a multiple of the fft size; <code>(set! (zero-pad) 1)</code> +<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> -<table cellpadding=5><tr><td> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(<a class=quiet href="#bindkey" onmouseout="UnTip()" onmouseover="Tip(extsnd_bindkey_tip)">bind-key</a> (char->integer #\p) 0 +<pre class="indented"> +(<a class=quiet href="#bindkey">bind-key</a> (char->integer #\p) 0 (lambda () - "increase zero-pad" (set! (zero-pad) (+ (<em class=red>zero-pad</em>) 1)) - (<a class=quiet href="#updatetransformgraph" onmouseout="UnTip()" onmouseover="Tip(extsnd_updatetransformgraph_tip)">update-transform-graph</a>))) + (<a class=quiet href="#updatetransformgraph">update-transform-graph</a>))) -(<a class=quiet href="#bindkey" onmouseout="UnTip()" onmouseover="Tip(extsnd_bindkey_tip)">bind-key</a> (char->integer #\m) 0 +(<a class=quiet href="#bindkey">bind-key</a> (char->integer #\m) 0 (lambda () - "decrease zero-pad" (set! (zero-pad) (- (<em class=red>zero-pad</em>) 1)) - (<a class=quiet href="#updatetransformgraph" onmouseout="UnTip()" onmouseover="Tip(extsnd_updatetransformgraph_tip)">update-transform-graph</a>))) -</pre></td></tr></table> -</td><td> -<img src="pix/pad1.png" alt="more pads"></td> -</tr></table> + (<a class=quiet href="#updatetransformgraph">update-transform-graph</a>))) +</pre> + +<img class="indented" src="pix/pad1.png" alt="more pads"> -</td></tr> -</table><!-- end of main sound/channel table --> -<br><br> -<table width="35%" border=0><tr><td bgcolor="#EEFDEE" valign="middle"><h4><A NAME="customcontrols">the control panel</a></h4></td></tr></table> + +<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'), @@ -10122,6 +10414,7 @@ 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 @@ -10134,401 +10427,484 @@ 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> -<!-- -------------------------------- CONTROL PANEL -------------------------------- --> -<table border=0 cellspacing=4 cellpadding=6 hspace=10> +<div class="spacer"></div> +<!-- CONTROL PANEL --> <!-- amp-control --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="ampcontrol">amp-control</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td width=30><br></td><td> -The current amp value. +<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_applycontrols_tip)">apply-controls</a> and playback. -</td></tr><tr><td colspan=2 height=16></td></tr> +<a class=quiet href="#applycontrols">apply-controls</a> and playback. +</p> +<div class="spacer"></div> <!-- amp-control-bounds --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="ampcontrolbounds">amp-control-bounds</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The amp-control min and max amounts as a list. The default is +<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, View:Files, and Record dialogs. -</td></tr><tr><td colspan=2 height=16></td></tr> +If no 'snd' argument is given, this also affects the Mix and View:Files dialogs. +</p> +<div class="spacer"></div> <!-- apply-controls --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="applycontrols">apply-controls</a> <em class=narg>snd target beg dur</em></code> -</td></tr><tr><td></td><td> -Apply the current control panel state as an edit. +<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: <code>(apply-controls 0 0 (<a class=quiet href="#marksample" onmouseout="UnTip()" onmouseover="Tip(extsnd_marksample_tip)">mark-sample</a> m))</code> starts from the given mark. +'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 border=0 vspace=10><tr><td> -<table border=0 cellpadding=5><tr><td><pre> -(define expnd - (lambda (amt) - (set! (<a class=quiet href="#expandcontrolp" onmouseout="UnTip()" onmouseover="Tip(extsnd_expandcontrolp_tip)">expand-control?</a>) #t) - (set! (<a class=quiet href="#expandcontrol" onmouseout="UnTip()" onmouseover="Tip(extsnd_expandcontrol_tip)">expand-control</a>) amt) - (<em class=red>apply-controls</em>))) -</pre></td></tr></table> - -</td><td width=20> -</td><td> -<table border=0 cellpadding=5><tr><td bgcolor="Beige"><pre> +<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></td></tr></table> - -</td><td width=20> -</td><td> -<table border=0 cellpadding=5><tr><td bgcolor="LightGreen"><pre> +</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></td></tr></table> +</pre> +</div> </td></tr></table> -For many examples see new-effects.scm. -</td></tr><tr><td colspan=2 height=16></td></tr> +<p>For many examples see new-effects.scm. +</p> +<div class="spacer"></div> <!-- controls->channel --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="controlstochannel">controls->channel</a> <em class=narg>settings beg dur snd chn origin</em></code> -</td></tr><tr><td></td><td> -This sets up the sound's controls to reflect 'settings' (unspecified settings are not changed), then applies the controls as +<pre class="indented"> +<em class=def id="controlstochannel">controls->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: -<pre> - (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)) +</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> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- contrast-control --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="contrastcontrol">contrast-control</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The <a class=quiet href="snd.html#contrast">contrast</a> amount. +<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). -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- contrast-control-amp --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="contrastcontrolamp">contrast-control-amp</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The <a class=quiet href="snd.html#contrast">contrast-control-amp</a> (a prescaler on the contrast-enhancement to get the +<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). -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- contrast-control-bounds --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="contrastcontrolbounds">contrast-control-bounds</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The contrast-control min and max amounts as a list. The default is +<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). -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- contrast-control? --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="contrastcontrolp">contrast-control?</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -#t if the <a class=quiet href="snd.html#contrast">contrast</a> button is set (i.e. the contrast compander is active). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="expandcontrol">expand-control</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The <a class=quiet href="snd.html#expand">expansion</a> amount. This sets the ratio between the +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- expand-control-bounds --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="expandcontrolbounds">expand-control-bounds</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The expand-control min and max amounts as a list. The default is +<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). -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- expand-control-hop --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="expandcontrolhop">expand-control-hop</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The <a class=quiet href="snd.html#expand">expansion</a> hop amount in seconds (the distance between successive grains). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="expandcontroljitter">expand-control-jitter</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The <a class=quiet href="snd.html#expand">expansion</a> grain timing jitter. This defaults to .1; if you set it +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- expand-control-length --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="expandcontrollength">expand-control-length</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The <a class=quiet href="snd.html#expand">expansion</a> segment (grain) length in seconds. The longer the grain, +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- expand-control-ramp --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="expandcontrolramp">expand-control-ramp</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The <a class=quiet href="snd.html#expand">expansion</a> ramp amount (between 0 and .5). +<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 — .001 gives a rattling effect. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- expand-control? --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="expandcontrolp">expand-control?</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -#t if the expand button is set (i.e. the expansion effect is active). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="filtercontrolcoeffs">filter-control-coeffs</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The <a class=quiet href="snd.html#filtercontrol">filter</a> coefficients (read-only currently). It is +<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 vct suitable for use with the <a href="sndclm.html#filter">filter generator</a> or with <a href="#filtersound">filter-sound</a>. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- filter-control-envelope --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="filtercontrolenvelope">filter-control-envelope</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The <a class=quiet href="snd.html#filtercontrol">filter</a> (frequency reponse) envelope (a list of breakpoints). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 reponse) envelope (a list of breakpoints). +</p> +<div class="spacer"></div> <!-- filter-control-in-dB --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="filtercontrolindB">filter-control-in-dB</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The <a class=quiet href="snd.html#filtercontrol">filter</a> dB button. If #t, the filter (frequency) envelope +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- filter-control-in-hz --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="filtercontrolinhz">filter-control-in-hz</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -If #t, the filter frequency response envelope x axis is in Hz, otherwise 0 to 1.0 (where 1.0 corresponds to srate/2). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="filtercontrolorder">filter-control-order</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The <a class=quiet href="snd.html#filtercontrol">filter</a> order. This affects how much computing +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- filter-control-waveform-color --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="filterwaveformcolor">filter-control-waveform-color</a></code> -</td></tr><tr><td></td><td> -The filter frequency response waveform color. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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? --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="filtercontrolp">filter-control?</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -#t if the filter button is set (i.e. the filter is active). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="resetcontrols">reset-controls</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -Set all the controls to their default state. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="restorecontrols">restore-controls</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -Set all the +<pre class="indented"> +<em class=def id="restorecontrols">restore-controls</em> snd +</pre> + +<p>Set all the controls to the last saved state. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> + <!-- reverb-control-decay --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="reverbdecay">reverb-control-decay</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The length (in seconds) of the reverberation after the sound has +<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). -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- reverb-control-feedback --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="reverbcontrolfeedback">reverb-control-feedback</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The reverb feedback coefficient. The more feedback, the happier Elvis. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="reverbcontrollength">reverb-control-length</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The <a class=quiet href="snd.html#reverb">reverb</a> delay line length scaler. Longer reverb simulates, to some +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- reverb-control-length-bounds --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="reverbcontrollengthbounds">reverb-control-length-bounds</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The reverb-control-length min and max amounts as a list. The default is +<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). -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- reverb-control-lowpass --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="reverbcontrollowpass">reverb-control-lowpass</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The reverb low pass filter coefficient. (This filter is in the feedback loop). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="reverbcontrolscale">reverb-control-scale</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The <a class=quiet href="snd.html#reverb">reverb</a> amount (the amount of the direct signal sent to the reverb). +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- reverb-control-scale-bounds --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="reverbcontrolscalebounds">reverb-control-scale-bounds</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The reverb-control-scale min and max amounts as a list. The default is +<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). -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- reverb-control? --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="reverbcontrolp">reverb-control?</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -#t if the reverb button is set (i.e. the reverberator is active). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="savecontrols">save-controls</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This remembers the current control -settings for a later <a class=quiet href="#restorecontrols" onmouseout="UnTip()" onmouseover="Tip(extsnd_restorecontrols_tip)">restore-controls</a>. In new-effects.scm, the effects that use the control panel +<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: -<pre> - (<em class=red>save-controls</em>) - (reset-controls) - ;;; now set the ones that are of interest for the current effect - (apply-controls) - (restore-controls) +</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> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- show-controls --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="showcontrols">show-controls</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -#t if the sound's control panel is currently open. +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- speed-control --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="speedcontrol">speed-control</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -current <a class=quiet href="snd.html#speed">speed</a> (sampling rate conversion factor). A speed of 2 plays the sound twice as fast. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="speedcontrolbounds">speed-control-bounds</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The speed-control min and max amounts as a list. The default is +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- speed-control-style --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="speedstyle">speed-control-style</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The speed control can be interpreted as a -float, (<code>speed-control-as-float</code>, the default), as a ratio -of relatively small integers (<code>speed-control-as-ratio</code>), or as a step in a -microtonal scale (<code>speed-control-as-semitone</code>). +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- speed-control-tones --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="speedtones">speed-control-tones</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -The number of tones per octave in the <code>speed-control-as-semitone</code> speed +<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). -</td></tr><tr><td colspan=2 height=16></td></tr> -</table> +</p> +<div class="spacer"></div> <p> @@ -10536,19 +10912,21 @@ 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>(list-ref (<a href="#soundwidgets">sound-widgets</a>) 2)</code>. +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> -<br> + + + <!-- INDEX editlists:Edit lists --> <!-- Edit Lists --> -<br> -<table width="35%" border=0><tr><td bgcolor="#EEFDEE" valign="middle"><h4><A NAME="editlists">Edit Lists</a></h4></td></tr></table> + +<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 @@ -10559,227 +10937,247 @@ pointer to the current edit history position); all the positions are accessible 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 -------------------------------- --> - -<table border=0 cellspacing=4 cellpadding=6 hspace=10> +<!-- EDIT-LIST TABLE --> <!-- as-one-edit --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="asoneedit">as-one-edit</a> func <em class=narg>origin</em></code> -</td></tr><tr><td width=30></td><td> -call 'func', a function of no arguments, treating it as +<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 border=0 vspace=10><tr><td> -<table border=0 cellpadding=5><tr><td> -<pre> +<table> +<tr><td> +<div class="scheme"> +<pre class="indented"> (<em class=red>as-one-edit</em> (lambda () - (set! (<a class=quiet href="#sample" onmouseout="UnTip()" onmouseover="Tip(extsnd_sample_tip)">sample</a> 100) .1) - (set! (<a class=quiet href="#sample" onmouseout="UnTip()" onmouseover="Tip(extsnd_sample_tip)">sample</a> 200) .2))) + (set! (<a class=quiet href="#sample">sample</a> 100) .1) + (set! (<a class=quiet href="#sample">sample</a> 200) .2))) </pre> -</td></tr></table> - -</td><td width=20> -</td><td> -<table border=0 cellpadding=5><tr><td bgcolor="beige"> -<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> -</td></tr></table> - -</td><td width=20> -</td><td> -<table border=0 cellpadding=5><tr><td bgcolor="lightgreen"> -<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> -</td></tr></table> - -</td></tr> -<tr><td></td><td> -See mix.scm for many examples. If you want to save and restore Snd's state after using as-one-edit, you need to +<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 — unlikely to be what you want. -</td></tr><tr><td></td><td></td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- display-edits --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="displayedits">display-edits</a> <em class=narg>snd chn edpos with-source</em></code> -</td></tr><tr><td></td><td> -This returns the current edit list contents as a string. If 'edpos' is specified, only that position is described. -'with-source' (default: #t) determines whether ptree source code is included in the output. -<pre> - :<em class=typing>(open-sound "oboe.snd")</em> - <em class=listener>#<sound 0></em> - :<em class=typing>(scale-channel 2.0)</em> - <em class=listener>2.0</em> - :<em class=typing>(pad-channel 100 200)</em> - <em class=listener>100</em> - :<em class=typing>(display-edits 0 0 1)</em> ; show just edit 1 (the scale-channel call) - <em class=listener>" - (scale 0 50828) ; scale-channel 2.000 0 #f [1:2]: - (at 0, cp->sounds[0][0:50827, 2.000]) [file: /home/bil/cl/oboe.snd[0]] - (at 50828, end_mark) - "</em> -</pre> -</td></tr><tr><td></td><td></td></tr><tr><td colspan=2 height=16></td></tr> +<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"> +> (open-sound "oboe.snd") +#<sound 0> +> (scale-channel 2.0) +2.0 +> (pad-channel 100 200) +100 +> (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->sounds[0][0:50827, 2.000]) [file: /home/bil/cl/oboe.snd[0]] + (at 50828, end_mark) +" +</pre> +<div class="spacer"></div> <!-- edit-fragment --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="editfragment">edit-fragment</a> <em class=narg>edpos snd chn</em></code> -</td></tr><tr><td></td><td> -This returns a list similar to that displayed in the edit history window giving +<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. -<pre> - :<em class=typing>(edit-fragment 2 0 0)</em> ; continuing example above - <em class=listener>("pad-channel" "zero" 100 200)</em> +</p> + +<pre class="indented"> +> (edit-fragment 2 0 0) ; continuing example above +("pad-channel" "zero" 100 200) </pre> -</td></tr><tr><td></td><td></td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> + <!-- edit-list->function --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="editlisttofunction">edit-list->function</a> <em class=narg>snd chn start end</em></code> -</td></tr><tr><td></td><td> -This returns a function encapsulating the current edit history list, providing a way to save an edit +<pre class="indented"> +<em class=def id="editlisttofunction">edit-list->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. -<pre> - :<em class=typing>(define our-edits (</em><em class=red>edit-list->function</em><em class=typing>))</em> ; same example as above - <em class=listener>#<unspecified></em> - :<em class=typing>our-edits</em> - <em class=listener>#<procedure our-edits ((snd chn) (scale-channel 2.0 0 #f snd chn) (pad-channel 100 200 snd chn))></em> - :<em class=typing>(undo 2)</em> - <em class=listener>2</em> - :<em class=typing>(our-edits 0 0)</em> - <em class=listener>100</em> +</p> + +<pre class="indented"> +> (define our-edits (<em class=red>edit-list->function</em>)) ; same example as above +#<unspecified> +> our-edits +#<procedure our-edits ((snd chn) (scale-channel 2.0 0 #f snd chn) (pad-channel 100 200 snd chn))> +> (undo 2) +2 +> (our-edits 0 0) +100 </pre> -In Ruby: -<pre> - :<em class=typing>open_sound "oboe.snd"</em> - <em class=listener>0</em> - :<em class=typing>scale_channel 2.0</em> - <em class=listener>2.0</em> - :<em class=typing>pad_channel 100, 200</em> - <em class=listener>100</em> - :<em class=typing>our_edits = edit_list2function</em> - <em class=listener>#<Proc:0x40c713ec@(eval):2></em> - :<em class=typing>our_edits.source</em> - <em class=listener>Proc.new {|snd, chn| scale_channel(2.000, 0, false, snd, chn); pad_channel(100, 200, snd, chn) }</em> - :<em class=typing>undo 2</em> - <em class=listener>2</em> - :<em class=typing>our_edits.call(0, 0)</em> - <em class=listener>100</em> -</pre> - -In Forth: -<pre> - snd> <em class=typing>"oboe.snd" open-sound</em> - <em class=listener>0</em> - snd> <em class=typing>2.0 scale-channel</em> - <em class=listener>2.0</em> - snd> <em class=typing>100 200 pad-channel</em> - <em class=listener>100</em> - snd> <em class=typing>0 0 edit-list->function value our-edits</em> - <em class=listener>nil</em> - snd> <em class=typing>our-edits proc-source-ref</em> - <em class=listener>lambda: { snd chn } 2.000 0 #f snd chn scale-channel drop 100 200 snd chn pad-channel drop ; 2 make-proc</em> - snd> <em class=typing>2 undo</em> - <em class=listener>2</em> - snd> <em class=typing>our-edits '( 0 0 ) run-proc</em> - <em class=listener>#f</em> -</pre> -</td></tr><tr><td></td><td></td></tr><tr><td colspan=2 height=16></td></tr> +<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 +#<Proc:0x40c713ec@(eval):2> +: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> "oboe.snd" open-sound +0 +snd> 2.0 scale-channel +2.0 +snd> 100 200 pad-channel +100 +snd> 0 0 edit-list->function value our-edits +nil +snd> 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> 2 undo +2 +snd> our-edits '( 0 0 ) run-proc +#f +</pre> +<div class="spacer"></div> <!-- edit-position --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="editposition">edit-position</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -The current position in the edit history list; it can be set: <code>(set! (edit-position) 0)</code> is equivalent -to <code>(<a class=quiet href="#revertsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_revertsound_tip)">revert-sound</a>)</code> in a mono sound. +<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>. -</td></tr><tr><td></td><td></td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- edit-properties --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="editproperties">edit-properties</a> <em class=narg>snd chn edpos</em></code> -</td></tr><tr><td></td><td> -Each entry in a channel's edit history list has a property list (similar to the +<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. -</td></tr><tr><td></td><td></td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- edit-property --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="editproperty">edit-property</a> key snd chn edpos</code> -</td></tr><tr><td></td><td> -edit-property returns the value associated with 'key' in the given channel's edit history list +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- edits --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="edits">edits</a> <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -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, <code>(edits)</code> returns <code>(list 2 0)</code>. -</td></tr><tr><td></td><td></td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="edittree">edit-tree</a> <em class=narg>snd chn edpos</em></code> -</td></tr><tr><td></td><td> -This returns a list of lists completely describing current edit list. +<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> - (list global-position data-number local-position local-end scaler ramp0 ramp1 type) +<pre class="indented"> +(list global-position data-number local-position local-end scaler ramp0 ramp1 type) </pre> -If 'data-number' is -2, it marks the end of the list. In our example above (the scale-channel/pad-channel sequence): +<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> - :<em class=typing>(edit-tree)</em> - <em class=listener>((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))</em> +<pre class="indented"> +> (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> - -</td></tr><tr><td></td><td></td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- save-edit-history --> +<pre class="indented"> +<em class=def id="saveedithistory">save-edit-history</em> filename snd chn +</pre> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="saveedithistory">save-edit-history</a> filename <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This function saves the current edit lists in 'filename'. +<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. @@ -10789,47 +11187,47 @@ 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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define sfile 0) -(define* (<a name="clonesoundas">clone-sound-as</a> new-name snd) - (let* ((tmpf (<a class=quiet href="#sndtempnam" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndtempnam_tip)">snd-tempnam</a>)) +(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" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>)))) - (if (not (string? (<a class=quiet href="#savedir" onmouseout="UnTip()" onmouseover="Tip(extsnd_savedir_tip)">save-dir</a>))) (set! (<a class=quiet href="#savedir" onmouseout="UnTip()" onmouseover="Tip(extsnd_savedir_tip)">save-dir</a>) "/tmp")) + (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_filename_tip)">file-name</a> oldsnd) new-name) - (set! sfile (<a class=quiet href="#opensound" onmouseout="UnTip()" onmouseover="Tip(extsnd_opensound_tip)">open-sound</a> new-name)) + (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></td></tr></table> +</pre> -We can also use save-edit-history (with some trouble) to split a sound off +<p>We can also use save-edit-history (with some trouble) to split a sound off into an independent Snd process: +</p> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define* (separate-sound snd) - (let* ((tmpf (<a class=quiet href="#sndtempnam" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndtempnam_tip)">snd-tempnam</a>)) + (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>))) - (name (<a class=quiet href="#filename" onmouseout="UnTip()" onmouseover="Tip(extsnd_filename_tip)">file-name</a> oldsnd))) - (if (not (string? (<a class=quiet href="#savedir" onmouseout="UnTip()" onmouseover="Tip(extsnd_savedir_tip)">save-dir</a>))) (set! (<a class=quiet href="#savedir" onmouseout="UnTip()" onmouseover="Tip(extsnd_savedir_tip)">save-dir</a>) "/tmp")) + (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_closesound_tip)">close-sound</a> oldsnd) + (<a class=quiet href="#closesound">close-sound</a> oldsnd) (with-output-to-file scm1 (lambda () - (display (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "(define sfile (<a class=quiet href="#opensound" onmouseout="UnTip()" onmouseover="Tip(extsnd_opensound_tip)">open-sound</a> ~S))~%" name)) - (display (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "(load ~S)~%" scm)))) - (system (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "snd ~A &" scm1)))) -</pre></td></tr></table> - -</td></tr><tr><td></td><td></td></tr> + (<a class=quiet>format</a> #t "(define sfile (<a class=quiet href="#opensound">open-sound</a> ~S))~%" name) + (<a class=quiet>format</a> #t "(load ~S)~%" scm))) + (system (<a class=quiet>format</a> #f "snd ~A &" scm1)))) +</pre> +<div class="separator"></div> -</table> <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. @@ -10839,24 +11237,25 @@ 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> +put in it something like: +</p> -<table border=0 cellpadding=5 hspace=20><tr><td><pre> -(let ((myfile (<a class=quiet href="#newsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_newsound_tip)">new-sound</a> "mysound.snd" mus-aifc-sound-file <a class=quiet href="#dataformat" onmouseout="UnTip()" onmouseover="Tip(extsnd_musbshort_tip)">mus-bshort</a> 44100 2 "this is my sound"))) +<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_mix_tip)">mix</a> "oboe.snd" 0 0 myfile 0) + (<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_mix_tip)">mix</a> "oboe.snd" 0 0 myfile 0 #f) to forego the editable mix - (<a class=quiet href="#mix" onmouseout="UnTip()" onmouseover="Tip(extsnd_mix_tip)">mix</a> "pistol.snd" 0 0 myfile 1) + ;; 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" onmouseout="UnTip()" onmouseover="Tip(extsnd_mix_tip)">mix</a> "fyow.snd" 10000 0 myfile 0) + (<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_mix_tip)">mix</a> "cardinal.snd" 20000 0 myfile 1) + (<a class=quiet href="#mix">mix</a> "cardinal.snd" 20000 0 myfile 1) ;; etc ) -</pre></td></tr></table> +</pre> -<p>Now start Snd: <code>snd -l myfile.scm</code> and voila! +<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. @@ -10869,21 +11268,21 @@ other such text. <!-- Transforms --> -<br> -<table width="80%" border=0><tr><td bgcolor="lightsteelblue" valign="middle"><h3><A NAME="sndtransforms">Transforms</a></h3></td></tr></table> + +<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 -------------------------------- --> - -<table border=0 cellspacing=4 cellpadding=6 hspace=10> +<!-- TRANSFORM TABLE --> <!-- add-transform --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="addtransform">add-transform</a> name xlabel lo hi transform</code> -</td></tr><tr><td width=30></td><td> -add-transform adds a transform to the transform choices (alongside fourier-transform, etc). 'name' is the name +<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 @@ -10892,56 +11291,62 @@ can be used to get the current data. Do not free the sampler! The function should return a vct 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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (<em class=red>add-transform</em> "histogram" "bins" 0.0 1.0 (lambda (len fd) - (let ((v (<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> len)) + (let ((v (make-float-vector len 0.0)) (steps (/ len 16)) (step (/ 1.0 len))) - (do ((i 0 (+ 1 i))) + (do ((i 0 (+ i 1))) ((= i len) v) - (let* ((val (<a class=quiet href="#readsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_readsample_tip)">read-sample</a> fd)) + (let* ((val (<a class=quiet href="#readsample">read-sample</a> fd)) (bin (floor (* (abs val) 16.0)))) - (do ((j 0 (+ 1 j))) + (do ((j 0 (+ j 1))) ((= j steps)) (set! (v (+ j bin)) (+ step (v (+ j bin)))))))))) -</pre></td></tr></table> +</pre> -If GSL is included in Snd, the following code ties in the (slow) Hankel transform: +<p>If GSL is included in Snd, the following code ties in the (slow) Hankel transform: +</p> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (<em class=red>add-transform</em> "Hankel" "Hankel" 0.0 1.0 (lambda (n rd) - (let ((v (<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> n))) - (do ((i 0 (+ 1 i))) ((= i n)) (set! (v i) (rd))) + (let ((v (make-float-vector n 0.0))) + (do ((i 0 (+ i 1))) ((= i n)) (set! (v i) (rd))) (gsl-dht n v 1.0 1.0) v))) -</pre></td></tr></table></td></tr><tr><td colspan=2 height=16></td></tr> +</pre> +<div class="spacer"></div> <!-- delete-transform --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="deletetransform">delete-transform</a> type</code> -</td></tr><tr><td></td><td> -This removes a transform that was added via <a class=quiet href="#addtransform" onmouseout="UnTip()" onmouseover="Tip(extsnd_addtransform_tip)">add-transform</a>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="fft">fft</a> rl im <em class=narg>sgn</em></code> -</td></tr><tr><td></td><td> -<p> -This performs an FFT on vcts 'rl' and 'im' (the real and imaginary parts of the +<pre class="indented"> +<em class=def id="fft">fft</em> rl im sgn +</pre> + +<p>This performs an FFT on vcts '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 <a name="musfft">mus-fft</a> in Snd. +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 vcts 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> + +<pre class="indented"> (define (fft->sines amps phases) (let* ((len (length phases)) (fft-size (expt 2 (+ 10 (ceiling (log len 2))))) @@ -10956,69 +11361,84 @@ and initial-phase: (<em class=red>fft</em> rl im -1) rl)) </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- integer->transform --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="integertotransform">integer->transform</a> i</code> -</td></tr><tr><td></td><td> -This function returns the transform (type object) corresponding to a given integer. -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="integertotransform">integer->transform</em> i +</pre> + +<p>This function returns the transform (type object) corresponding to a given integer. +</p> +<div class="spacer"></div> <!-- snd-spectrum --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sndspectrum">snd-spectrum</a> data <em class=narg>window length (linear #t) (beta 0.0) in-place (normalized #t)</em></code> -</td></tr><tr><td></td><td> -This returns the spectrum (as a vct) of 'data' (also a vct) using the fft window 'win'. +<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 vct) of 'data' (also a vct) using the fft window 'win'. 'length' is the number of samples of data. -<pre> - (let ((spectr (snd-spectrum data rectangular-window (<a class=quiet href="#transformsize" onmouseout="UnTip()" onmouseover="Tip(extsnd_transformsize_tip)">transform-size</a>)))) - ...) +</p> + +<pre class="indented"> +(let ((spectr (snd-spectrum data rectangular-window (<a class=quiet href="#transformsize">transform-size</a>)))) + ...) </pre> -If 'linear' is #f (its default is #t), the spectrum is in dB. + +<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 vct. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- transform->integer --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="transformtointeger">transform->integer</a> transform-object</code> -</td></tr><tr><td></td><td> -This function returns the integer corresponding to a given transform type object (e.g. fourier-transform). -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="transformtointeger">transform->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? --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="transformp">transform?</a> object</code> -</td></tr><tr><td></td><td> -This returns #t if 'object' is a transform object. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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> -</table> -<p>Other related variables and functions:</p> -<table cellpadding=0 cellspacing=1 border=0 hspace=20> -<tr><td width=200><a href="#transformgraphp"><small>transform-graph?</small></a></td><td width=200><a href="#showtransformpeaks"><small>show-transform-peaks</small></a></td><td><a href="#transformsample"><small>transform-sample</small></a></td></tr> -<tr><td><a href="#fftbeta"><small>fft-window-beta</small></a></td><td><a href="#showselectiontransform"><small>show-selection-transform</small></a></td><td><a href="#transformtovct"><small>transform->vct</small></a></td></tr> -<tr><td><a href="#aftertransformhook"><small>after-transform-hook</small></a></td><td><a href="#spectrumend"><small>spectrum-end</small></a></td><td><a href="#transformframes"><small>transform-frames</small></a></td></tr> -<tr><td><a href="#fftlogfrequency"><small>fft-log-frequency</small></a></td><td><a href="#spectrohop"><small>spectro-hop</small></a></td><td><a href="#transformtype"><small>transform-type</small></a></td></tr> -<tr><td><a href="#fftlogmagnitude"><small>fft-log-magnitude</small></a></td><td><a href="#spectrumstart"><small>spectrum-start</small></a></td><td><a href="#updatetransformgraph"><small>update-transform-graph</small></a></td></tr> -<tr><td><a href="#transformsize"><small>transform-size</small></a></td><td><a href="#spectroxangle"><small>spectro-x-angle</small></a></td><td><a href="#normalizefft"><small>transform-normalization</small></a></td></tr> -<tr><td><a href="#transformgraphtype"><small>transform-graph-type</small></a></td><td><a href="#spectroxscale"><small>spectro-x-scale</small></a></td><td><a href="#zeropad"><small>zero-pad</small></a></td></tr> -<tr><td><a href="#fftwindow"><small>fft-window</small></a></td><td><a href="#spectroyangle"><small>spectro-y-angle</small></a></td><td><a href="#wavelettype"><small>wavelet-type</small></a></td></tr> -<tr><td><a href="#maxfftpeaks"><small>max-transform-peaks</small></a></td><td><a href="#spectroyscale"><small>spectro-y-scale</small></a></td><td><a href="#spectrozscale"><small>spectro-z-scale</small></a></td></tr> -<tr><td><a href="#mindb"><small>min-dB</small></a></td><td><a href="#spectrozangle"><small>spectro-z-angle</small></a></td><td></td></tr> -</table> -<p>Some FFT-based effects and editing functions: +<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="#transformtovct">transform->vct</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 --> -<A NAME="fftexamples"></a> -<TABLE border=3 bordercolor="tan" hspace=20><tr><td> -<small><blockquote> + +<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> @@ -11043,19 +11463,19 @@ 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> -Waterfall real-time spectrograph: <a href="sndscm.html#startwaterfall">start-waterfall</a><br> -Simple rt spectrum: <a href="sndscm.html#showinputfft">show-input-fft</a>, <a href="sndscm.html#showdraggableinputfft">show-draggable-input-fft</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> -</blockquote></small> +</small></blockquote> </td></tr></TABLE> -<br> + + + <!-- Dialogs --> -<br> -<table width="80%" border=0><tr><td bgcolor="lightsteelblue" valign="middle"><h3><A NAME="snddialogs">Dialogs and Other Widgets</a></h3></td></tr></table> + +<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. @@ -11064,40 +11484,45 @@ 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, -<code>(color-orientation-dialog)</code> puts the color/orientation dialog on the screen. If you're trying instead to +(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 that defaults to #t. If #f, the dialog is created, if need be, but not started. -install-searcher in snd-motif.scm, which adds customized file filtering code -to the File:Open dialog, first makes sure the dialog exists with <code>(open-file-dialog #f)</code>. +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 --> -<!-- -------------------------------- DIALOG TABLE -------------------------------- --> -<table border=0 cellspacing=4 cellpadding=6 hspace=10> <!-- add-directory-to-view-files-list --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="adddirectorytoviewfileslist">add-directory-to-view-files-list</a> dir <em class=narg>dialog</em></code> -</td></tr><tr><td></td><td> -This adds the sound files in directory 'dir' to the list of files in the View:Files dialog. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="addfiletoviewfileslist">add-file-to-view-files-list</a> file <em class=narg>dialog</em></code> -</td></tr><tr><td></td><td> -This adds 'file' to the list of files in the View:Files dialog. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="addfilefilter">add-file-filter</a> name func</code> -</td></tr><tr><td></td><td> -This adds 'func' to the file filter list under the name 'name'. The file filter list is a list +<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 @@ -11106,375 +11531,448 @@ 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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (<em class=red>add-file-filter</em> - "mono" + "mono files" (lambda (a) - "filter out all but mono sound files" - (and (<a class=quiet href="#soundfilep" onmouseout="UnTip()" onmouseover="Tip(extsnd_soundfilep_tip)">sound-file?</a> a) + (and (<a class=quiet href="#soundfilep">sound-file?</a> a) (= (channels a) 1)))) -</pre></td></tr></table></td></tr> -<tr><td colspan=2 height=16></td></tr> +</pre> +<div class="spacer"></div> + <!-- add-file-sorter --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="addfilesorter">add-file-sorter</a> name func</code> -</td></tr><tr><td></td><td> -This adds 'func' to the file-sorter list under the name 'name'. Some dialog file lists include +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (<em class=red>add-file-sorter</em> "duration" (lambda (a b) - "sort by duration from short to long" - (let ((dur1 (<a class=quiet href="#mussoundduration" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussoundduration_tip)">mus-sound-duration</a> a)) - (dur2 (<a class=quiet href="#mussoundduration" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussoundduration_tip)">mus-sound-duration</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))) (if (> dur1 dur2) 1 (if (< dur1 dur2) -1 0))))) -</pre></td></tr></table></td></tr> -<tr><td colspan=2 height=16></td></tr> +</pre> +<div class="spacer"></div> + <!-- add-sound-file-extension --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="addsoundfileextension">add-sound-file-extension</a> ext</code> -</td></tr><tr><td></td><td> -This adds 'ext' to the list of (case sensitive) sound file extensions used by <a href="#soundfilesindirectory">sound-files-in-directory</a>. +<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: -<pre> - (add-sound-file-extension "ogg") +</p> + +<pre class="indented"> + (add-sound-file-extension "ogg") </pre> -The list itself is <a href="#soundfileextensions">sound-file-extensions</a>. + +<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>. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- add-to-main-menu --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="addtomainmenu">add-to-main-menu</a> menu-label <em class=narg>update-callback</em></code> -</td></tr><tr><td></td><td> -This adds a new top-level menu named 'menu-label' and returns its menu index. The index +<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. -<pre> - Scheme: - (define new-menu (add-to-main-menu "New Menu")) - (<a class=quiet href="#addtomenu" onmouseout="UnTip()" onmouseover="Tip(extsnd_addtomenu_tip)">add-to-menu</a> new-menu "First Item" (lambda () (<a class=quiet href="#sndprint" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndprint_tip)">snd-print</a> ";item 1"))) - (<a class=quiet href="#addtomenu" onmouseout="UnTip()" onmouseover="Tip(extsnd_addtomenu_tip)">add-to-menu</a> new-menu "Second Item" (lambda () (<a class=quiet href="#sndprint" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndprint_tip)">snd-print</a> ";item 2"))) +</p> - 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) +<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"))) - Forth: - "New Menu" add-to-main-menu constant new-menu drop - new-menu "First Item" lambda: <{ }> "item1" snd-print ; undef add-to-menu drop - new-menu "Second Item" lambda: <{ }> "item2" snd-print ; undef add-to-menu drop +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: <{ }> "item1" snd-print ; undef add-to-menu drop +new-menu "Second Item" lambda: <{ }> "item2" snd-print ; undef add-to-menu drop </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- add-to-menu --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="addtomenu">add-to-menu</a> top-menu menu-label callback <em class=narg>position</em></code> -</td></tr><tr><td></td><td> -This adds the menu 'menu-label' to the top-level menu whose index is +<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. -<pre> - (<em class=red>add-to-menu</em> 1 "Stop Playing" - (lambda () (<a class=quiet href="#stopplaying" onmouseout="UnTip()" onmouseover="Tip(extsnd_stopplaying_tip)">stop-playing</a>))) +</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" onmouseout="UnTip()" onmouseover="Tip(extsnd_windowheight_tip)">window-height</a>) (/ (<a class=quiet href="#windowheight" onmouseout="UnTip()" onmouseover="Tip(extsnd_windowheight_tip)">window-height</a>) 2)))) -</pre></td></tr> -<tr><td></td><td> -</td></tr><tr><td colspan=2 height=16></td></tr> + (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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="channelwidgets">channel-widgets</a></code> -</td></tr><tr><td></td><td> -channel-widgets returns a list of various widgets associated with a given channel: -<pre> - 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 - ------ the rest only in Gtk+ - 11..16: adjustment widgets associated with the zoom and position sliders -</pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 +------ the rest only in Gtk+ +11..16: adjustment widgets associated with the zoom and position sliders +</pre> +<div class="spacer"></div> <!-- clear-listener --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="clearlistener">clear-listener</a></code> -</td></tr><tr><td width=30></td><td> -This deletes all listener text from the beginning to the cursor position (C-M-g is bound to this function). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="colororientationdialog">color-orientation-dialog</a> <em class=narg>managed</em></code> -</td></tr><tr><td width=30></td><td> -This creates and (if 'managed' which defaults to #t) activates the Color/Orientation dialog; it returns the dialog widget. -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="colororientationdialog">color-orientation-dialog</em> managed +</pre> + +<p>This creates and (if 'managed' which defaults to #t) activates the Color/Orientation dialog; it returns the dialog widget. +</p> +<div class="spacer"></div> <!-- define-envelope --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="defineenvelope">define-envelope</a> name data <em class=narg>(base 1.0)</em></code> -</td></tr><tr><td></td><td> -This adds an envelope to the envelope editor's list, under the name 'name', using the list of breakpoints -'data', and the optional 'base'. If the 'base' is omitted, this is the same as <a href="#defvar">defvar</a>. -<pre> - 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 class="indented"> +<em class=def id="defineenvelope">define-envelope</em> name data (base 1.0) </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<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> -<!-- defvar --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="defvar">defvar</a> var val</code> -</td></tr><tr><td></td><td> -This is the same as <code>(define var val)</code> except that the envelope editor keeps track -of 'var' thereafter and treats lists as envelopes. -defvar exists in this context so that Snd and CLM can share envelope files. -<pre> - (defvar a-func '(0 0 1 1)) +<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> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- delete-file-filter --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="deletefilefilter">delete-file-filter</a> index</code> -</td></tr><tr><td></td><td> -This removes the file filter function associated with 'index' from the file filter list. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="deletefilesorter">delete-file-sorter</a> index</code> -</td></tr><tr><td></td><td> -This removes the file sorter function associated with 'index' from the file sorter list. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="dialogwidgets">dialog-widgets</a></code> -</td></tr><tr><td></td><td> -dialog-widgets returns a list of dialog widgets (or lists thereof, or #f if none yet): -<pre> - 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 - 18: File: Recorder 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> -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="editheaderdialog">edit-header-dialog</a> <em class=narg>snd</em></code> -</td></tr><tr><td></td><td> -This starts the Edit Header dialog on 'snd', returning the dialog widget. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="envedbase">enved-base</a> </code> -</td></tr><tr><td></td><td> -This is the envelope editor exponential base value. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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? --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="envedclipping">enved-clip?</a></code> -</td></tr><tr><td></td><td> -This reflects the state of the envelope editor 'clip' button. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="enveddialog">enved-dialog</a></code> -</td></tr><tr><td></td><td> -This starts the envelope editor dialog, returning the dialog widget. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="envedenvelope">enved-envelope</a></code> -</td></tr><tr><td></td><td> -This is the envelope (a list of breakpoints) in the envelope editor's graph window. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="filterenv">enved-filter</a></code> -</td></tr><tr><td></td><td> -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 +<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: -<pre> +</p> + +<pre class="indented"> (set! (<em class=red>enved-filter)</em> #f) - (set! (<a class=quiet href="#envedwaving" onmouseout="UnTip()" onmouseover="Tip(extsnd_envedwaving_tip)">enved-wave?</a>) #t) - (set! (<a class=quiet href="#envedtarget" onmouseout="UnTip()" onmouseover="Tip(extsnd_envedtarget_tip)">enved-target</a>) <a class=quiet href="#envedtarget" onmouseout="UnTip()" onmouseover="Tip(extsnd_envedtarget_tip)">enved-spectrum</a>) -</pre></td></tr> + (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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="filterenvorder">enved-filter-order</a></code> -</td></tr><tr><td></td><td> -This is the order of the envelope editor's FIR filter (the default is 40). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="envedin-dB">enved-in-dB</a></code> -</td></tr><tr><td></td><td> -This reflects the state of the envelope editor 'dB' button (it defaults to #f). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="envedpower">enved-power</a></code> -</td></tr><tr><td></td><td> -This is the envelope editor's base scale range (it defaults to 3.0). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="envedstyle">enved-style</a></code> -</td></tr><tr><td></td><td> -This is the envelope editor choice for connecting breakpoints. It can be <code>envelope-linear</code> (the default), or -<code>envelope-exponential</code>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="envedtarget">enved-target</a></code> -</td></tr><tr><td></td><td> -This determines how the envelope editor's current envelope is applied to the selected data. -The choices are <code>enved-amplitude</code>, <code>enved-srate</code> and <code>enved-spectrum</code>. +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- enved-waveform-color --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="envedwaveformcolor">enved-waveform-color</a></code> -</td></tr><tr><td></td><td> -This is the color of the waveform displayed in envelope editor (the default is blue). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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? --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="envedwaving">enved-wave?</a></code> -</td></tr><tr><td></td><td> -This reflects the state of the envelope editor 'wave' button. +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- find-dialog --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="finddialog">find-dialog</a> <em class=narg>managed text</em></code> -</td></tr><tr><td></td><td> -This creates and (if 'managed' which defaults to #t) starts the Edit:Find dialog, returning the dialog widget. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td bgcolor="#f2f4ff" colspan=2> -<code><a class=def name="focuswidget">focus-widget</a> widget</code> -</td></tr><tr><td></td><td> -This gives 'widget' "focus" — it becomes the active widget, receiving keystrokes and so on. -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="focuswidget">focus-widget</em> widget +</pre> + +<p>This gives 'widget' "focus" — it becomes the active widget, receiving keystrokes and so on. +</p> +<div class="spacer"></div> <!-- gl-graph->ps --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="glgraphtops">gl-graph->ps</a> <em class=narg>file (type 0) snd chn</em></code> -</td></tr><tr><td></td><td> -This creates a Postscript picture of the current openGL display in snd's channel chn (a spectrogram). +<pre class="indented"> +<em class=def id="glgraphtops">gl-graph->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). -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- goto-listener-end --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="gotolistenerend">goto-listener-end</a></code> -</td></tr><tr><td></td><td> -This moves the cursor to the end of the listener text, and scrolls the window so that it is visible. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="graphtops">graph->ps</a> file</code> -</td></tr><tr><td></td><td> -This creates a Postscript picture of the current display. +<pre class="indented"> +<em class=def id="graphtops">graph->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>. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- help-dialog --> -<tr><td colspan=2 valign=top><code><a class=def name="helpdialog">help-dialog</a> subject help-string <em class=narg>xrefs urls</em></code> -</td></tr><tr><td></td><td> -This starts the help dialog with the title 'subject' and help area text 'help', returning the dialog widget. +<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. -<pre> - (help-dialog "xyzzy" "are we having fUn?") -</pre> There are many examples in new-effects.scm. +</p> -<table border=0 cellpadding=5 vspace=10><tr><td> -<pre> -(defmacro with-snd-help (form) +<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 () @@ -11484,745 +11982,899 @@ There are many examples in new-effects.scm. (let* ((func (if (string=? "set!" (substring (cadr args) 0 4)) (substring (cadr args) 5) (cadr args))) - (help (<a class=quiet href="#sndhelp" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndhelp_tip)">snd-help</a> func))) + (help (<a class=quiet href="#sndhelp">snd-help</a> func))) (if help (<em class=red>help-dialog</em> func help)))) args))) </pre> -</td></tr></table> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- hide-widget --> -<tr><td bgcolor="#f2f4ff" colspan=2> -<code><a class=def name="hidewidget">hide-widget</a> widget</code> -</td></tr><tr><td></td><td> -This hides (unmanages) '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): -<pre> - (<a class=quiet href="#hidewidget" onmouseout="UnTip()" onmouseover="Tip(extsnd_hidewidget_tip)">hide-widget</a> (list-ref (<a class=quiet href="#channelwidgets" onmouseout="UnTip()" onmouseover="Tip(extsnd_channelwidgets_tip)">channel-widgets</a>) 4)) +</p> + +<pre class="indented"> +(<a class=quiet href="#hidewidget">hide-widget</a> ((<a class=quiet href="#channelwidgets">channel-widgets</a>) 4)) </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- info-dialog --> -<tr><td colspan=2 valign=top><code><a class=def name="infodialog">info-dialog</a> subject info</code> -</td></tr><tr><td></td><td> -This starts the info dialog with the title 'subject' and body 'info' returning the dialog widget. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="insertfiledialog">insert-file-dialog</a> <em class=narg>managed</em></code> -</td></tr><tr><td></td><td> -This creates and (if 'managed' which defaults to #t) activates the File:Insert dialog, returning the dialog widget. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="listenercolor">listener-color</a></code> -</td></tr><tr><td></td><td> -This is the background color of listener. -<pre> - (set! (listener-color) (<a class=quiet href="#makecolor" onmouseout="UnTip()" onmouseover="Tip(extsnd_makecolor_tip)">make-color</a> 0 0 0)) +<pre class="indented"> +<em class=def id="listenercolor">listener-color</em> </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<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> + +<p>This determines whether the listener displays the code with syntax highlights in the Gtk version of Snd. +The colors can be changed with colorizer-colors. +</p> +<div class="spacer"></div> <!-- listener-font --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="listenerfont">listener-font</a></code> -</td></tr><tr><td></td><td> -This is the listener font. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="listenerprompt">listener-prompt</a></code> -</td></tr><tr><td></td><td> -This is the listener prompt which defaults to ">". I like ":" better (as you can see in many of the examples in this file), +<pre class="indented"> +<em class=def id="listenerprompt">listener-prompt</em> +</pre> + +<p>This is the listener prompt which defaults to ">". I like ":" better (as you can see in many of the examples in this file), so in ~/.snd_s7 I have this line: -<pre> - (set! (listener-prompt) ":") +</p> + +<pre class="indented"> +(set! (listener-prompt) ":") </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- listener-selection --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="listenerselection">listener-selection</a></code> -</td></tr><tr><td></td><td> +<pre class="indented"> +<em class=def id="listenerselection">listener-selection</em> +</pre> -listener-selection returns the currently selected text in the listener, or #f if there isn't any. The following code +<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: -<pre> - (<a class=quiet href="#bindkey" onmouseout="UnTip()" onmouseover="Tip(extsnd_bindkey_tip)">bind-key</a> #\h 0 +</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 () - "start help dialog based on listener selected text" (let ((subject (<em class=red>listener-selection</em>))) - (if subject - (<a class=quiet href="#helpdialog" onmouseout="UnTip()" onmouseover="Tip(extsnd_helpdialog_tip)">help-dialog</a> subject (<a class=quiet href="#sndhelp" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndhelp_tip)">snd-help</a> subject)))))) + (if subject + (<a class=quiet href="#helpdialog">help-dialog</a> subject (<a class=quiet href="#sndhelp">snd-help</a> subject))))))) </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- listener-text-color --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="listenertextcolor">listener-text-color</a></code> -</td></tr><tr><td></td><td> -This is the text color in the listener. For red text on a black background: -<pre> - (set! (listener-color) (make-color 0 0 0)) ; in Gtk, maybe a bad idea — the cursor remains black... - (set! (listener-text-color) (make-color 1 0 0)) +<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> + +<pre class="indented"> +(set! (listener-color) (make-color 0 0 0)) ; in Gtk, maybe a bad idea — the cursor remains black... +(set! (listener-text-color) (make-color 1 0 0)) </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- main-menu --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mainmenu">main-menu</a> menu</code> -</td></tr><tr><td></td><td> -main-menu returns the top-level 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: -<pre> - 0: File menu - 1: Edit menu - 2: View menu - 3: Options menu - 4: Help menu - and others as added by add-main-menu +</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> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- main-widgets --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mainwidgets">main-widgets</a></code> -</td></tr><tr><td></td><td> -main-widgets returns a list of the top-level widgets in Snd (#f if not created): -<pre> - 0: top-level-application ; XtAppContext in Motif, top level window in Gtk+ - 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 class="indented"> +<em class=def id="mainwidgets">main-widgets</em> </pre> -For example, to get at Snd's main shell widget: -<pre> - Scheme: (cadr (main-widgets)) - Ruby: main_widgets.cadr - Forth: main-widgets cadr +<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, top level window in Gtk+ +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> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>In Gtk 3.1 or later, we can use this to fire up a modal font chooser dialog: +</p> + +<pre class="indented"> +> (define (get-font) + (with-let *gtk* + (let ((fonts (gtk_font_chooser_dialog_new "fonts" (GTK_WINDOW (cadr (<em class=red>main-widgets</em>)))))) + (let ((response (gtk_dialog_run (GTK_DIALOG fonts)))) ; don't return until a choice is made + (let ((name (if (= response GTK_RESPONSE_OK) ; (cancel = GTK_RESPONSE_CANCEL) + (gtk_font_chooser_get_font (GTK_FONT_CHOOSER fonts)) + 'no-font-selected))) ; perhaps pass in the current value instead? + (gtk_widget_destroy (GTK_WIDGET fonts)) ; clean up after the dialog + name))))) ; return new font +get-font + +> (set! (listener-font) (get-font)) +"Monospace Bold Italic 10" +</pre> + + +<div class="spacer"></div> <!-- menu-widgets --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="menuwidgets">menu-widgets</a></code> -</td></tr><tr><td></td><td> -menu-widgets returns the top-level menu widgets (cascade menus in Motif or menu bars in Gtk+) +<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 or menu bars in Gtk+) as a list: -<pre> - 0: top-level-menu-bar - 1: file-menu - 2: edit-menu - 3: view-menu - 4: options-menu - 5: help-menu -</pre> -See snd-motif.scm, snd-gtk.scm, kmenu.scm, and new-effects.scm for various examples. +</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, snd-gtk.scm, and new-effects.scm for various examples. Manipulating menus can be tricky in both Motif and Gtk; 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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mix-dialog-mix --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixdialogmix">mix-dialog-mix</a></code> -</td></tr><tr><td></td><td> -This is the id (mix object) of the mix displayed by the mix dialog. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="mixfiledialog">mix-file-dialog</a> <em class=narg>managed</em></code> -</td></tr><tr><td></td><td> -This creates and (if 'managed' which defaults to #t) activates the File:Mix 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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- new-sound-dialog --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="newsounddialog">new-sound-dialog</a> <em class=narg>managed</em></code> -</td></tr><tr><td></td><td> -This creates and (if 'managed' which defaults to #t) +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- open-file-dialog --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="openfiledialog">open-file-dialog</a> <em class=narg>managed</em></code> -</td></tr><tr><td></td><td> -This creates and (if 'managed' which defaults to #t) activates the File:Open 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. -If the xm module is loaded, we could add our own info via: - -<table border=0 cellpadding=5 vspace=10><tr><td><pre> - (let* ((dialog (<em class=red>open-file-dialog</em> #f)) - (rc (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(sndscm_findchild_tip)">find-child</a> dialog "info-rc2")) ; holds the info labels if a sound file is selected - (label (XtCreateManagedWidget "file-preview-info" xmLabelWidgetClass rc - (list XmNbackground (<a class=quiet href="#highlightcolor" onmouseout="UnTip()" onmouseover="Tip(extsnd_highlightcolor_tip)">highlight-color</a>))))) - (XtAddCallback (XmFileSelectionBoxGetChild dialog XmDIALOG_LIST) - XmNbrowseSelectionCallback - (lambda (widget context info) - (let ((file (cadr (XmStringGetLtoR (.item info) XmFONTLIST_DEFAULT_TAG)))) - (XtVaSetValues label - (list XmNlabelString - (XmStringCreateLtoR (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "~A: no comment" file) - XmFONTLIST_DEFAULT_TAG))))) - #f)) -</pre></td></tr></table></td></tr> -<tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- preferences-dialog --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="preferencesdialog">preferences-dialog</a></code> -</td></tr><tr><td></td><td> -This activates the Options:Preferences dialog. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="printdialog">print-dialog</a> <em class=narg>managed direct-to-printer</em></code> -</td></tr><tr><td></td><td> -This creates and (if 'managed' which defaults to #t) activates the File:Print dialog, returning the dialog widget. -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- print-dialog --> +<pre class="indented"> +<em class=def id="printdialog">print-dialog</em> managed direct-to-printer +</pre> -<!-- recorder-dialog --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="recorderdialog">recorder-dialog</a></code> -</td></tr><tr><td></td><td> -This starts the <a href="snd.html#recordfile">recorder</a> window, returning the dialog widget. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="removefrommenu">remove-from-menu</a> top-menu menu-label</code> -</td></tr><tr><td></td><td> -This removes the menu 'menu-label' from the top top-level menu whose index is 'top-menu'. See examp.scm or snd-motif.scm. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="resetlistenercursor">reset-listener-cursor</a></code> -</td></tr><tr><td></td><td> -This resets the listener cursor to the default pointer shape. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="saveasdialogautocomment">save-as-dialog-auto-comment</a></code> -</td></tr><tr><td></td><td> -This is the 'auto' button in the Save-as dialogs. If set, a comment is automatically +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- save-as-dialog-src --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="saveasdialogsrc">save-as-dialog-src</a></code> -</td></tr><tr><td></td><td> -This is the 'src' button in the Save-as dialogs. If set, sampling rate conversion +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- save-envelopes --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="saveenvelopes">save-envelopes</a> filename</code> -</td></tr><tr><td></td><td> -This saves the envelope editor envelopes in 'filename'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="savelistener">save-listener</a> filename</code> -</td></tr><tr><td></td><td> -This saves the listener contents in 'filename'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="saveregiondialog">save-region-dialog</a> <em class=narg>managed</em></code> -</td></tr><tr><td></td><td> -This creates and (if 'managed' which defaults to #t) +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- save-selection-dialog --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="saveselectiondialog">save-selection-dialog</a> <em class=narg>managed</em></code> -</td></tr><tr><td></td><td> -This creates and (if 'managed' which defaults to #t) +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- save-sound-dialog --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="savesounddialog">save-sound-dialog</a> <em class=narg>managed</em></code> -</td></tr><tr><td></td><td> -This creates and (if 'managed' which defaults to #t) +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- show-listener --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="showlistener">show-listener</a></code> -</td></tr><tr><td></td><td> -If show-listener is set to #t, Snd opens the listener pane; otherwise it closes the listener. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td bgcolor="#f2f4ff" colspan=2> -<code><a class=def name="showwidget">show-widget</a> widget</code> -</td></tr><tr><td></td><td> -This shows (manages) 'widget'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="soundfileextensions">sound-file-extensions</a></code> -</td></tr><tr><td></td><td> -This is the list of sound file extensions used by the "just-sounds" buttons and +<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: -<pre> - (set! (sound-file-extensions) - (list "snd" "aiff" "aif" "wav" "au" "aifc" "voc" "wve" "WAV" "sf2" "rf64" "caf")) +</p> + +<pre class="indented"> +(set! (sound-file-extensions) + (list "snd" "aiff" "aif" "wav" "au" "aifc" "voc" "wve" "WAV" "sf2" "rf64" "caf")) </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- sound-file? --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="soundfilep">sound-file?</a> filename</code> -</td></tr><tr><td></td><td> -This returns #t if 'filename' has an extension that matches one in the <a href="#soundfileextensions">sound-file-extensions</a> list. -<pre> - :<em class=typing>(sound-file? "oboe.snd")</em> - <em class=listener>#t</em> - :<em class=typing>(sound-file? "extsnd.html")</em> - <em class=listener>#f</em> +<pre class="indented"> +<em class=def id="soundfilep">sound-file?</em> filename </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<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"> +> (sound-file? "oboe.snd") +#t +> (sound-file? "extsnd.html") +#f +</pre> +<div class="spacer"></div> <!-- sound-files-in-directory --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="soundfilesindirectory">sound-files-in-directory</a> <em class=narg>dir</em></code> -</td></tr><tr><td></td><td> -This returns a list of the sound files found in 'dir'. A file is considered a sound if it has data and +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (for-each (lambda (filename) - (if (and (= (<a class=quiet href="#mussoundheadertype" onmouseout="UnTip()" onmouseover="Tip(extsnd_mussoundheadertype_tip)">mus-sound-header-type</a> filename) <a class=quiet href="#headertype" onmouseout="UnTip()" onmouseover="Tip(extsnd_headertype_tip)">mus-aifc</a>) + (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndprint_tip)">snd-print</a> (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "~%~A" filename)))) + (<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></td></tr></table> +</pre> -See also <a href="sndscm.html#mapsoundfiles">map-sound-files</a> in extensions.scm. -</td></tr><tr><td colspan=2 height=16></td></tr> +<p>See also <a href="sndscm.html#mapsoundfiles">map-sound-files</a> in extensions.scm. +</p> +<div class="spacer"></div> <!-- sound-widgets --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="soundwidgets">sound-widgets</a></code> -</td></tr><tr><td></td><td> -sound-widgets returns a list of various widgets specific to a given sound: -<pre> - 0: main-pane - 1: name-label ; sound's file name - 2: control-panel - 3: minibuffer - 4: play button - 5: filter-graph ; control panel drawing area for filter envelope - 6: unite button ; invisible in mono sounds - 7: minibuffer-label ; prompt area for the minibuffer - 8: name-icon ; hour-glass or whatever - 9: sync button -</pre> - -For example, we can read and write the minibuffer: -<pre> - Scheme: - :<em class=typing>(report-in-minibuffer "this is a test")</em> - <em class=listener>"this is a test"</em> - :<em class=typing>(widget-text (list-ref (sound-widgets) 3))</em> - <em class=listener>"this is a test"</em> +<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: +> (status-report "this is a test") +"this is a test" +> (widget-text ((sound-widgets) 3)) +"this is a test" - Ruby: - :<em class=typing>report_in_minibuffer("this is a test")</em> - <em class=listener>this is a test</em> - :<em class=typing>widget_text(sound_widgets()[3])</em> - <em class=listener>this is a test</em> +Ruby: +:status_report("this is a test") +this is a test +:widget_text(sound_widgets()[3]) +this is a test - Forth: - <em class=listener>snd></em> <em class=typing>"this is a test" report-in-minibuffer</em> - <em class=listener>this is a test</em> - <em class=listener>snd></em> <em class=typing>0 sound-widgets 3 list-ref widget-text</em> - <em class=listener>this is a test</em> +Forth: +snd> "this is a test" status-report +this is a test +snd> 0 sound-widgets 3 list-ref widget-text +this is a test </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- transform-dialog --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="transformdialog">transform-dialog</a> <em class=narg>managed</em></code> -</td></tr><tr><td></td><td> -This creates and (if 'managed' which defaults to #t) activates the Options:Transform dialog, returning the dialog widget. -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="transformdialog">transform-dialog</em> managed +</pre> + +<p>This creates and (if 'managed' which defaults to #t) activates the Options:Transform dialog, returning the dialog widget. +</p> +<div class="spacer"></div> <!-- view-files-amp --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="viewfilesamp">view-files-amp</a> dialog</code> -</td></tr><tr><td></td><td> -This is the value of the amplitude slider in the View:Files dialog. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="viewfilesampenv">view-files-amp-env</a> dialog</code> -</td></tr><tr><td></td><td> -This is the amplitude envelope displayed in the View:Files dialog. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="viewfilesdialog">view-files-dialog</a> <em class=narg>managed</em></code> -</td></tr><tr><td></td><td> -This creates and (if 'managed' which defaults to #t) activates a +<pre class="indented"> +<em class=def id="viewfilesdialog">view-files-dialog</em> managed [Motif only] +</pre> + +<p>This creates and (if 'managed' which defaults to #t) activates a View:Files <a href="snd.html#viewfiles">dialog</a> and returns the dialog widget. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- view-files-files --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="viewfilesfiles">view-files-files</a> dialog</code> -</td></tr><tr><td></td><td> -This is the file list (a list of strings) of a View:Files dialog. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="viewfilesselectedfiles">view-files-selected-files</a> dialog</code> -</td></tr><tr><td></td><td> -This is the list of selected files (a list of strings) in a View:Files dialog. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="viewfilessort">view-files-sort</a> dialog</code> -</td></tr><tr><td></td><td> -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), +<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: -<pre> - (set! (view-files-sort (list-ref (<a class=quiet href="#dialogwidgets" onmouseout="UnTip()" onmouseover="Tip(extsnd_dialogwidgets_tip)">dialog-widgets</a>) 8)) 2) ; 2=new..old +</p> + +<pre class="indented"> + (set! (view-files-sort ((<a class=quiet href="#dialogwidgets">dialog-widgets</a>) 8)) 2) ; 2=new..old </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- view-files-speed --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="viewfilesspeed">view-files-speed</a> dialog</code> -</td></tr><tr><td></td><td> -This is the value of the speed slider in a View:Files dialog. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="viewfilesspeedstyle">view-files-speed-style</a> dialog</code> -</td></tr><tr><td></td><td> -This is the speed style choice in a View:Files dialog. It is one of <code>speed-control-as-float</code> (the default), -<code>speed-control-as-ratio</code>, or <code>speed-control-as-semitone</code>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="viewmixesdialog">view-mixes-dialog</a></code> -</td></tr><tr><td></td><td> -This creates and activates the View:Mixes Dialog, returning the dialog widget. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="viewregionsdialog">view-regions-dialog</a></code> -</td></tr><tr><td></td><td> -This starts the <a href="snd.html#regionbrowser">region browser</a> (a no-op if there are no regions), and returns the dialog widget. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td bgcolor="#f2f4ff" colspan=2> -<code><a class=def name="widgetposition">widget-position</a> widget</code> -</td></tr><tr><td></td><td> -This returns a list giving the widget's x and y coordinates (in pixels). It can be set to reposition the widget. +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- widget-size --> -<tr><td bgcolor="#f2f4ff" colspan=2> -<code><a class=def name="widgetsize">widget-size</a> widget</code> -</td></tr><tr><td></td><td> -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. -<pre> - (set! (<a class=quiet href="#widgetposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_widgetposition_tip)">widget-position</a> (cadr (<a class=quiet href="#mainwidgets" onmouseout="UnTip()" onmouseover="Tip(extsnd_mainwidgets_tip)">main-widgets</a>))) (list 300 100)) +<pre class="indented"> +<em class=def id="widgetsize">widget-size</em> widget </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<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 --> -<tr><td bgcolor="#f2f4ff" colspan=2> -<code><a class=def name="widgettext">widget-text</a> widget</code> -</td></tr><tr><td></td><td> -This returns the text widget's text. It can be set. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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> -</table> -<!-- end of dialog table --> -<br> -<table width="80%" border=0><tr><td bgcolor="lightsteelblue" valign="middle"><h3><A NAME="sndmisc">Miscellaneous functions</a></h3></td></tr></table> -<p>These functions don't seem to fit anywhere else:</p> +<div class="header" id="sndmisc">Miscellaneous functions</div> -<!-- -------------------------------- MISCELLANEOUS TABLE -------------------------------- --> +<!-- MISCELLANEOUS TABLE --> +<div class="spacer"></div> -<table border=0 cellspacing=4 cellpadding=6 hspace=10> <!-- abort --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="abort">abort</a></code> -</td></tr><tr><td width=30><br></td><td> -This exits Snd via "abort", presumably to fall into the C debugger. To stop some on-going Snd operation, +<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>. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- add-source-file-extension --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="addsourcefileextension">add-source-file-extension</a> ext</code> -</td></tr><tr><td><br></td><td> -add-source-file-extension adds 'ext' to the list of source file extensions. -<pre> - (add-source-file-extension "rbs") +<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> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- bes-* --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><A class=def NAME="besj0">bes-j0</A> x</code><br> -<code><em class=emdef>bes-j1</em> x</code><br> -<code><em class=emdef>bes-jn</em> n x</code><br> -<code><em class=emdef>bes-y0</em> x</code><br> -<code><em class=emdef>bes-y1</em> x</code><br> -<code><em class=emdef>bes-yn</em> n x</code><br> -<code><em class=emdef>bes-i0</em> n x</code><br> -<code><em class=emdef>bes-i1</em> n x</code> ; from GSL<br> -<code><em class=emdef>bes-in</em> n x</code><br> -<code><em class=emdef>bes-k0</em> x</code><br> -<code><em class=emdef>bes-k1</em> x</code><br> -<code><em class=emdef>bes-kn</em> n x</code><br> -</td></tr><tr><td></td><td> -If the Bessel functions are available from the math library (or GSL), these are J0 and friends. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="bindkey">bind-key</a> key state func <em class=narg>extended origin</em></code> -</td></tr><tr><td></td><td> +<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. -If you include a documentation string in the function, it is included in the Help menu's Key Bindings output. -<br><br> -The function ('func' above) should take zero or one arguments and +</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: -<pre> - cursor-in-view cursor-on-left cursor-on-right cursor-in-middle keyboard-no-action +</p> + +<pre class="indented"> +cursor-in-view cursor-on-left cursor-on-right cursor-in-middle keyboard-no-action </pre> -If the function takes one argument, + +<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. -<br><br> -The modifier 'state' is a combination of control = 4 and meta = 8. +</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 <X11/xkeysymdef.h>, and in Gtk in gdk/gdkkeysyms.h; in both cases, remove the XK_ or GDK_ prefix. So, for example, the key marked "Page Down" is named "Page_Down" in both tables. Similarly "+" is "plus". +</p> -<pre> - Scheme: (bind-key "End" 0 (lambda () "view full sound" (set! (<a class=quiet href="#xbounds" onmouseout="UnTip()" onmouseover="Tip(extsnd_xbounds_tip)">x-bounds</a>) (list 0.0 (/ (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a>) (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a>)))))) +<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, frames.to_f / srate.to_f]) end) + 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 frames #f srate f/ 2 >list set-x-bounds ; 0 make-proc bind-key + Forth: "End" 0 lambda: 0.0 #f #f #f framples #f srate f/ 2 >list set-x-bounds ; 0 make-proc bind-key </pre> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (<em class=red>bind-key</em> "Home" 0 (lambda () - "move cursor and window to current edit" - (let ((ed (<a class=quiet href="#editfragment" onmouseout="UnTip()" onmouseover="Tip(extsnd_editfragment_tip)">edit-fragment</a>))) - (<a class=quiet href="#reportinminibuffer" onmouseout="UnTip()" onmouseover="Tip(extsnd_reportinminibuffer_tip)">report-in-minibuffer</a> (<a class=quiet onmouseout="UnTip()" onmouseover="Tip(scheme_format_tip)">format</a> #f "~A" ed)) - (set! (<a class=quiet href="#cursor" onmouseout="UnTip()" onmouseover="Tip(extsnd_cursor_tip)">cursor</a>) (caddr ed)) + (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 () - "move cursor to left edge of window" cursor-on-left) #f "#\\p->cursor-on-left") (<em class=red>bind-key</em> #\v 4 (lambda () - "move ahead one window" - (if (< (<a class=quiet href="#rightsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_rightsample_tip)">right-sample</a>) (<a class=quiet href="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a>)) - (set! (<a class=quiet href="#leftsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_leftsample_tip)">left-sample</a>) (<a class=quiet href="#rightsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_rightsample_tip)">right-sample</a>))) + (if (< (<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 () - "remove click" - (set! (<a class=quiet href="#sample" onmouseout="UnTip()" onmouseover="Tip(extsnd_sample_tip)">sample</a> (<a class=quiet href="#cursor" onmouseout="UnTip()" onmouseover="Tip(extsnd_cursor_tip)">cursor</a>)) (* 0.5 (+ (<a class=quiet href="#sample" onmouseout="UnTip()" onmouseover="Tip(extsnd_sample_tip)">sample</a> (- (<a class=quiet href="#cursor" onmouseout="UnTip()" onmouseover="Tip(extsnd_cursor_tip)">cursor</a>) 1)) (<a class=quiet href="#sample" onmouseout="UnTip()" onmouseover="Tip(extsnd_sample_tip)">sample</a> (+ 1 (<a class=quiet href="#cursor" onmouseout="UnTip()" onmouseover="Tip(extsnd_cursor_tip)">cursor</a>)))))) + (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></td></tr></table> +</pre> -<A NAME="extendedpiano"></A>We can use bind-key to turn the keyboard into a sort of extended piano: +<p id="extendedpiano">We can use bind-key to turn the keyboard into a sort of extended piano: +</p> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (<em class=red>bind-key</em> #\o 0 - (lambda () "play oboe.snd" - (<a class=quiet href="#play" onmouseout="UnTip()" onmouseover="Tip(extsnd_play_tip)">play</a> "oboe.snd") + (lambda () + (<a class=quiet href="#play">play</a> "oboe.snd") keyboard-no-action)) (<em class=red>bind-key</em> #\p 0 - (lambda () "play pistol.snd" - (<a class=quiet href="#play" onmouseout="UnTip()" onmouseover="Tip(extsnd_play_tip)">play</a> "pistol.snd") + (lambda () + (<a class=quiet href="#play">play</a> "pistol.snd") keyboard-no-action)) -</pre></td></tr></table> +</pre> -Now each time we hit "o", "oboe.snd" plays, etc. Or say we want to move +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (<em class=red>bind-key</em> #\l 0 - (lambda () "move window forward 2 samples" - (set! (<a class=quiet href="#leftsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_leftsample_tip)">left-sample</a> 0 0) (+ 2 (<a class=quiet href="#leftsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_leftsample_tip)">left-sample</a> 0 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></td></tr></table> +</pre> -Or, more useful perhaps, have C-c set the cursor at a particular sample: +<p>Or, more useful perhaps, have C-c set the cursor at a particular sample: +</p> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (<em class=red>bind-key</em> #\c 4 - (lambda (arg) "move cursor to arg" - (set! (<a class=quiet href="#cursor" onmouseout="UnTip()" onmouseover="Tip(extsnd_cursor_tip)">cursor</a>) arg) + (lambda (arg) + (set! (<a class=quiet href="#cursor">cursor</a>) arg) cursor-in-middle)) -</pre></td></tr></table> +</pre> -A similar set rebinds the arrow keys to give much more precise window position and size control: +<p id="moveonepixel">A similar set rebinds the arrow keys to give much more precise window position and size control: +</p> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define (<a NAME="moveonepixel">move-one-pixel</a> s c right) - (let* ((ax (<a class=quiet href="#axisinfo" onmouseout="UnTip()" onmouseover="Tip(extsnd_axisinfo_tip)">axis-info</a> s c <a class=quiet onmouseout="UnTip()" onmouseover="Tip(extsnd_time_graph_tip)">time-graph</a>)) - (lo (list-ref ax 0)) - (hi (list-ref ax 1)) - (lo-pix (list-ref ax 10)) - (hi-pix (list-ref ax 12)) +<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="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a> s c)) hi) + (- (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_leftsample_tip)">left-sample</a>) (+ lo change)) + (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 back one pixel" - (move-one-pixel (<a class=quiet href="#selectedsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>) (<a class=quiet href="#selectedchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedchannel_tip)">selected-channel</a>) #f))) + (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 forward one pixel" - (move-one-pixel (<a class=quiet href="#selectedsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>) (<a class=quiet href="#selectedchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedchannel_tip)">selected-channel</a>) #t))) - - -(define (<a NAME="zoomonepixel">zoom-one-pixel</a> s c in) - (let* ((ax (<a class=quiet href="#axisinfo" onmouseout="UnTip()" onmouseover="Tip(extsnd_axisinfo_tip)">axis-info</a> s c <a class=quiet onmouseout="UnTip()" onmouseover="Tip(extsnd_time_graph_tip)">time-graph</a>)) - (lo (list-ref ax 0)) - (hi (list-ref ax 1)) - (lo-pix (list-ref ax 10)) - (hi-pix (list-ref ax 12)) + (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="#frames" onmouseout="UnTip()" onmouseover="Tip(extsnd_frames_tip)">frames</a> s c))) + (len (<a class=quiet href="#framples">framples</a> s c))) (if in (if (> (- hi-pix lo-pix) samps-per-pixel) (begin - (set! (<a class=quiet href="#leftsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_leftsample_tip)">left-sample</a>) (+ lo samps-per-pixel)) - (set! (<a class=quiet href="#xzoomslider" onmouseout="UnTip()" onmouseover="Tip(extsnd_xzoomslider_tip)">x-zoom-slider</a>) + (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_leftsample_tip)">left-sample</a>) (max 0 (- lo samps-per-pixel))) - (set! (<a class=quiet href="#xzoomslider" onmouseout="UnTip()" onmouseover="Tip(extsnd_xzoomslider_tip)">x-zoom-slider</a>) + (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 out one pixel" - (zoom-one-pixel (<a class=quiet href="#selectedsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>) (<a class=quiet href="#selectedchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedchannel_tip)">selected-channel</a>) #f))) + (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 in one pixel" - (zoom-one-pixel (<a class=quiet href="#selectedsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>) (<a class=quiet href="#selectedchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedchannel_tip)">selected-channel</a>) #t))) -</pre></td></tr></table> + (zoom-one-pixel (<a class=quiet href="#selectedsound">selected-sound</a>) (<a class=quiet href="#selectedchannel">selected-channel</a>) #t))) +</pre> -The key bindings set by bind-key are active only when the active widget is a graph; when the listener is receiving +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(XtAppAddActions (car (<a class=quiet href="#mainwidgets" onmouseout="UnTip()" onmouseover="Tip(extsnd_mainwidgets_tip)">main-widgets</a>)) (list (list "hiho" (lambda args (<a class=quiet href="#sndprint" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndprint_tip)">snd-print</a> "hiho"))))) -(XtOverrideTranslations (list-ref (<a class=quiet href="#mainwidgets" onmouseout="UnTip()" onmouseover="Tip(extsnd_mainwidgets_tip)">main-widgets</a>) 4) (XtParseTranslationTable "Ctrl <Key>i: hiho()\n")) -</pre></td></tr></table> +<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 <Key>i: hiho()\n")) +</pre> -Since neither Motif nor Gtk explicitly support an Emacs-like extended mode, we have to go to +<p>Since neither Motif nor Gtk 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 either Motif or Gtk: +</p> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> - +<pre class="indented"> ;;; Motif version: (define extended #f) ; our extended mode flag -(XtAddEventHandler (list-ref (<a class=quiet href="#mainwidgets" onmouseout="UnTip()" onmouseover="Tip(extsnd_mainwidgets_tip)">main-widgets</a>) 4) KeyPressMask #f +(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) @@ -12236,7 +12888,7 @@ in either Motif or Gtk: (begin (if (and extended (= (cadr keysym) 102)) ; C-x C-f - (<a class=quiet href="#openfiledialog" onmouseout="UnTip()" onmouseover="Tip(extsnd_openfiledialog_tip)">open-file-dialog</a>)) + (<a class=quiet href="#openfiledialog">open-file-dialog</a>)) (set! extended #f))))))) @@ -12244,7 +12896,7 @@ in either Motif or Gtk: (define extended #f) ; our extended mode flag -(let ((listener (list-ref (<a class=quiet href="#mainwidgets" onmouseout="UnTip()" onmouseover="Tip(extsnd_mainwidgets_tip)">main-widgets</a>) 4))) +(let ((listener ((<a class=quiet href="#mainwidgets">main-widgets</a>) 4))) (g_signal_connect_closure_by_id (GPOINTER listener) (g_signal_lookup "key_press_event" (G_OBJECT_TYPE (G_OBJECT listener))) @@ -12260,20 +12912,20 @@ in either Motif or Gtk: (begin (if (and extended (= key 102)) - (<a class=quiet href="#openfiledialog" onmouseout="UnTip()" onmouseover="Tip(extsnd_openfiledialog_tip)">open-file-dialog</a>)) + (<a class=quiet href="#openfiledialog">open-file-dialog</a>)) (set! extended #f)))) #f)) #f #f) #f)) -</pre></td></tr></table> - -</td></tr><tr><td colspan=2 height=16></td></tr> +</pre> +<div class="separator"></div> <!-- break --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="break">break</a></code> -</td></tr><tr><td></td><td> +<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 @@ -12281,117 +12933,100 @@ 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> -<pre> - <em class=typing>(define (outer arg1) - (let ((y 123)) - (define (hiho arg) - (let ((x 32) - (y "a string") - (z (vct .1 .2 .3))) - (break) - (display y) - (+ x (string-length y) (z 1)))) - (hiho 1) - (break) - (* y 2)))</em> - - <em class=listener>></em> <em class=typing>(outer 456)</em> - <em class=listener>hiho></em> - <em class=listener>snd-top-level</em> - <em class=listener>hiho></em> <em class=typing>x</em> - <em class=listener>32</em> - <em class=listener>hiho></em> <em class=typing>arg</em> - <em class=listener>1</em> - <em class=listener>hiho></em> <em class=typing>y</em> - <em class=listener>"a string"</em> - <em class=listener>hiho></em> <em class=typing>(break-ok)</em> - <em class=listener>></em> - <em class=listener>outer></em> - <em class=listener>snd-top-level</em> - <em class=listener>outer></em> <em class=typing>y</em> - <em class=listener>123</em> - <em class=listener>outer></em> <em class=typing>(break-ok)</em> - <em class=listener>></em> - <em class=listener>246</em> -</pre> -<p>To get a stack trace at the point of the break, <code>(stacktrace break-ok)</code>. -</p> -</td></tr><tr><td colspan=2 height=16></td></tr> - +<div class="spacer"></div> <!-- c-g? --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="cgp">c-g?</a></code> -</td></tr><tr><td></td><td> -This checks for C-g to interrupt an on-going computation, and lets other UI +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- erf --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><em class=emdef>erf</em> x</code><br> -<code><em class=emdef>erfc</em> n x</code><br> -</td></tr><tr><td></td><td> -These are the erf and erfc functions from the math library. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="exit">exit</a> <em class=narg>exit-value</em></code> -</td></tr><tr><td></td><td> -This exits Snd. Scheme's exit function is renamed %exit. In Forth, this function is snd-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: -<pre> - <a class=quiet href="#beforeexithook" onmouseout="UnTip()" onmouseover="Tip(extsnd_beforeexithook_tip)">before-exit-hook</a> — can cancel exit request - <a class=quiet href="#exithook" onmouseout="UnTip()" onmouseover="Tip(extsnd_exithook_tip)">exit-hook</a> - Snd cleans up and exits +</p> + +<pre class="indented"> +<a class=quiet href="#beforeexithook">before-exit-hook</a> — can cancel exit request +<a class=quiet href="#exithook">exit-hook</a> +Snd cleans up and exits </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- fmod --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><em class=emdef>fmod</em> x y</code> -</td></tr><tr><td></td><td> -fmod is mod with float arguments: -<pre> - ><em class=typing>(fmod 2.5 1.4)</em> - <em class=listener>1.1</em> +<pre class="indented"> +<em class=emdef>fmod</em> x y +</pre> + +<p>fmod is mod with float arguments: +</p> + +<pre class="indented"> +> (fmod 2.5 1.4) +1.1 </pre> -In Scheme, it is a synonym for modulo. -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>In Scheme, fmod is a synonym for modulo. +</p> +<div class="spacer"></div> <!-- gc-off --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="gcoff">gc-off</a></code> -</td></tr><tr><td></td><td> -gc-off turns garbage collection off, if possible. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="gcon">gc-on</a></code> -</td></tr><tr><td></td><td> -gc-on turns garbage collection on. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="gin">in</a> <em class=narg>ms thunk</em></code> -</td></tr><tr><td></td><td> -'ms' milliseconds from now, evaluate 'thunk', a function of no arguments. In Ruby, this -is named "<a name="callin">call_in</a>". -<pre> - (<em class=red>in</em> 5000 (lambda () (<a class=quiet href="#sndprint" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndprint_tip)">snd-print</a> "boo!"))) +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define (at hour minute func) (let* ((cur-time (localtime (current-time))) (cur-minute (cur-time 1)) @@ -12400,152 +13035,186 @@ is named "<a name="callin">call_in</a>". (then (+ (* hour 60) minute))) (<em class=red>in</em> (* 1000 60 (- then now)) func))) -(at 15 11 (lambda () (<a class=quiet href="#sndprint" onmouseout="UnTip()" onmouseover="Tip(extsnd_sndprint_tip)">snd-print</a> "it's 3:11 pm!"))) -</pre></td></tr></table></td></tr> -<tr><td colspan=2 height=16></td></tr> +(at 15 11 (lambda () (<a class=quiet href="#sndprint">snd-print</a> "it's 3:11 pm!"))) +</pre> +<div class="spacer"></div> + <!-- key --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="key">key</a> key state <em class=narg>snd chn</em></code> -</td></tr><tr><td></td><td> -This executes the keyboard command 'key' with modifier keys 'state'. +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- key-binding --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="keybinding">key-binding</a> key <em class=narg>(state 0) extended</em></code> -</td></tr><tr><td></td><td> -This returns the user-defined (not built-in) procedure, if any, currently bound to 'key' with 'state' and 'extended' flags. +<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. -<pre> - :<em class=typing>(key-binding "Right" 0)</em> - <em class=listener>#<procedure #f (() "move one pixel forward" (move-one-pixel (selected-sound) (selected-channel) #t))></em> +</p> + +<pre class="indented"> +> (key-binding "Right" 0) +#<procedure #f (() "move one pixel forward" (move-one-pixel (selected-sound) (selected-channel) #t))> </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- lgamma --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><em class=emdef>lgamma</em> x</code><br> -</td></tr><tr><td></td><td> -This is the lgamma function from the math library. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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? --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="littleendianp">little-endian?</a></code> -</td></tr><tr><td></td><td> -This returns #t if underlying machine is little endian. -</td></tr><tr><td colspan=2 height=16></td></tr> +<!-- little-endian? --> +<pre class="indented"> +<em class=def id="littleendianp">little-endian?</em> +</pre> -<!-- save-macros --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="savemacros">save-macros</a> filename</code> -</td></tr><tr><td></td><td> -This saves all currently defined <a href="snd.html#kbdmacros">keyboard macros</a> in 'filename'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<p>This returns #t if underlying machine is little endian. +</p> +<div class="spacer"></div> <!-- save-state --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="savestate">save-state</a> filename</code> -</td></tr><tr><td></td><td> -This saves the current state of Snd in 'filename'. The saved-state file is a Scheme/Ruby/Forth program that when loaded +<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. -<br><br> -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 — -see also <a href="#ptreechannel">ptree-channel</a> in this regard. +</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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- script-arg --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="scriptarg">script-arg</a></code> -</td></tr><tr><td></td><td> -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. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="scriptargs">script-args</a></code> -</td></tr><tr><td></td><td> -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. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="snderror">snd-error</a> str</code> -</td></tr><tr><td></td><td> -This throws 'snd-error with the error message 'str'. It provides a way to dive directly into +<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>. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- snd-help --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sndhelp">snd-help</a> obj <em class=narg>(formatted #t)</em></code> -</td></tr><tr><td></td><td> -This returns the help text associated with 'obj': -<pre> - Scheme: - :<em class=typing>(snd-help 'open-sound)</em> ; or "open-sound" - <em class=listener>"(open-sound filename) opens filename (as if opened from File:Open menu option), - and returns the new sound's index"</em> +<pre class="indented"> +<em class=def id="sndhelp">snd-help</em> obj (formatted #t) +</pre> - Ruby: - :<em class=typing>snd_help("close_sound")</em> ; or :open_sound - <em class=listener>close_sound((snd false)): close snd</em> +<p>This returns the help text associated with 'obj': +</p> - Forth: - snd> <em class=typing>"revert-sound" snd-help</em> - <em class=listener>(revert-sound (snd #f)): revert snd to its unedited state (undo all)</em> +<pre class="indented"> +Scheme: +> (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> -If no help string can be found, or if the name doesn't come close to any currently defined name, + +<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: -<pre> - :<em class=typing>(snd-help "volterra-filter")</em> - <em class=listener>"volterra-filter is not defined; it appears to be defined in: - /home/bil/cl/dsp.scm:1936:(define (volterra-filter flt x) <!-- ) --> - and documented at sndscm.html#volterrafilter"</em> +</p> + +<pre class="indented"> +> (snd-help "volterra-filter") +"volterra-filter is not defined; it appears to be defined in: +/home/bil/cl/dsp.scm:1936> (define (volterra-filter flt x) <!-- ) --> +and documented at sndscm.html#volterrafilter" </pre> -snd-help tries to be smart about minor mispellings: -<pre> - :<em class=typing>(snd-help "close-soud")</em> - <em class=listener>"(close-sound (snd #f)): close snd - Other possibilities: - close-sound is defined; it is documented at extsnd.html#closesound"</em> + +<p>snd-help tries to be smart about minor mispellings: +</p> + +<pre class="indented"> +> (snd-help "close-soud") +"(close-sound (snd #f)): close snd +Other possibilities: +close-sound is defined; it is documented at extsnd.html#closesound" </pre> -To go to the + +<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. -<br><br> -Normally snd-help adds carriage-returns to fit the current size of the listener; to +</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). -</td></tr><tr><td colspan=2 height=16></td></tr> +</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* --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sndopenedsound">*snd-opened-sound*</a></code> -</td></tr><tr><td></td><td> -When a sound file is opened, Snd looks for a file with the same +<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 @@ -12554,117 +13223,132 @@ or whatever that you want associated with a particular sound. Confusingly enough, this is a variable, unlike all the others — 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: <code>(set! (show-grid *snd-opened-sound*) #t)</code>. When "now.snd" is +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". -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- snd-print --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sndprint">snd-print</a> str</code> -</td></tr><tr><td></td><td> -This displays 'str' in the listener, then returns 'str'. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sndtempnam">snd-tempnam</a></code> -</td></tr><tr><td></td><td> -This returns a new temp file name using Snd's <a href="#tempdir">temp-dir</a>. -<pre> - <em class=listener>:</em><em class=typing>(temp-dir)</em> - <em class=listener>"/home/bil/zap/tmp"</em> - <em class=listener>:</em><em class=typing>(snd-tempnam)</em> - <em class=listener>"/home/bil/zap/tmp/snd_7000_2.snd"</em> +<pre class="indented"> +<em class=def id="sndtempnam">snd-tempnam</em> </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>This returns a new temp file name using Snd's <a href="#tempdir">temp-dir</a>. +</p> + +<pre class="indented"> +> (temp-dir) +"/home/bil/zap/tmp" +> (snd-tempnam) +"/home/bil/zap/tmp/snd_7000_2.snd" +</pre> +<div class="spacer"></div> <!-- snd-url --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sndurl">snd-url</a> name</code> -</td></tr><tr><td></td><td> -This is the url (in the Snd documentation) corresponding to 'name'; 'name' can be a string or a symbol. -<pre> - <em class=listener>:</em><em class=typing>(snd-url 'open-sound)</em> - <em class=listener>"extsnd.html#opensound"</em> +<pre class="indented"> +<em class=def id="sndurl">snd-url</em> name </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>This is the url (in the Snd documentation) corresponding to 'name'; 'name' can be a string or a symbol. +</p> + +<pre class="indented"> +> (snd-url 'open-sound) +"extsnd.html#opensound" +</pre> +<div class="spacer"></div> <!-- snd-urls --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sndurls">snd-urls</a></code> -</td></tr><tr><td></td><td> -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. -<pre> - :<em class=typing>(assoc "open-sound" (snd-urls))</em> - <em class=listener>: ("open-sound" . "extsnd.html#opensound")</em> +<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"> +> (assoc "open-sound" (snd-urls)) +("open-sound" . "extsnd.html#opensound") </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- snd-warning --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sndwarning">snd-warning</a> str</code> -</td></tr><tr><td></td><td> -This posts a 'str' in the minibuffer and returns 'str'. +<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>. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- unbind-key --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="unbindkey">unbind-key</a> key state <em class=narg>extended</em></code> -</td></tr><tr><td></td><td> -This causes 'key' with modifiers 'state' and 'extended' to revert to its built-in default. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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> -</table> -<br> +<!-- CONSTANTS --> -<!-- ---------------------------------------- CONSTANTS ---------------------------------------- --> +<div class="header" id="sndconstants">Constants</div> -<table width="80%" border=0><tr><td bgcolor="lightsteelblue" valign="middle"><h3><A NAME="sndconstants">Constants</a></h3></td></tr></table> +<p id="musoutformat"><b>Sndlib</b> (see <a href="sndlib.html#sndlibxen">sndlib.html</a> for a complete list): +</p> -<p><b>Sndlib</b> (see <a href="sndlib.html#sndlibxen">sndlib.html</a> for a complete list):</p> -<pre> - 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 +<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-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 - <a name="musoutformat">mus-out-format</a> +mus-out-format </pre> <p><b>Time domain graph type</b> (<a href="#timegraphtype">time-graph-type</a>):</p> -<pre> - graph-once <a class=quiet href="snd.html#wavogram" onmouseout="UnTip()" onmouseover="Tip('<img src=\'pix/wavo.png\' width=\'640\' height=\'250\'>', TITLE, 'graph-as-wavogram', ABOVE, true)">graph-as-wavogram</a> +<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> +<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> - <a name="fouriertransform">fourier-transform</a> wavelet-transform cepstrum haar-transform +<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> +<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> +<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 @@ -12678,63 +13362,63 @@ This causes 'key' with modifiers 'state' and 'extended' to revert to its built-i </pre> <p><b>Zoom Focus</b> style (<a href="#zoomfocusstyle">zoom-focus-style</a>):</p> -<pre> +<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> +<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> +<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> - <a name="channelstyleconstants">channels-separate</a> channels-combined channels-superimposed +<pre class="indented"> + channels-separate channels-combined channels-superimposed </pre> <p><b>Envelope Editor</b> target (<a href="#envedtarget">enved-target</a>):</p> -<pre> +<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> +<pre class="indented"> envelope-linear envelope-exponential </pre> <p><b>Graph Line</b> style (<a href="#graphstyle">graph-style</a>):</p> -<pre> - <a name="graphlines">graph-lines</a> graph-dots graph-filled graph-lollipops +<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> - <a name="cursorchoices">cursor-in-view</a> cursor-on-left cursor-on-right cursor-in-middle keyboard-no-action +<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> +<pre class="indented"> cursor-cross cursor-line </pre> <p><b>Axis placement</b> choice (<a href="#showaxes">show-axes</a>):</p> -<pre> +<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->position</a> etc):</p> -<pre> +<pre class="indented"> time-graph transform-graph lisp-graph </pre> <p><b>Colormap</b> choice (<a href="#colormap">colormap</a>):</p> -<pre> +<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 @@ -12742,16 +13426,16 @@ This causes 'key' with modifiers 'state' and 'extended' to revert to its built-i </pre> <p><b>Graphics context</b> choice (<a href="#graphdata">graph-data</a>)</p> -<pre> +<pre class="indented"> copy-context cursor-context selection-context mark-context </pre> -<br> -<!-- ---------------------------------------- ERRORS ---------------------------------------- --> -<table width="80%" border=0><tr><td bgcolor="lightsteelblue" valign="middle"><h3><A NAME="snderrors">Errors and Debugging</a></h3></td></tr></table> +<!-- 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) @@ -12760,27 +13444,34 @@ 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> - ><em class=typing>(selection-position)</em> - <em class=listener>selection-position: no-active-selection</em> - ><em class=typing>asdf</em> - <em class=listener>Unbound variable: asdf</em> + +<pre class="indented"> +> (selection-position) +selection-position: no-active-selection +> 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> -><em class=typing>(catch 'no-active-selection - (lambda () - (+ 1 (<a class=quiet href="#selectionposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectionposition_tip)">selection-position</a>))) - (lambda (tag val) 0))</em> -<em class=listener>0</em> +In the case of 'no-active-selection, we set up our own handler for that as follows: +</p> + +<pre class="indented"> +> (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 -<code>(+ 1 (<a class=quiet href="#selectionposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectionposition_tip)">selection-position</a>))</code>. Scheme has a number +(+ 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> +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 @@ -12790,55 +13481,61 @@ etc. The Snd-specific errors are:</p> 'gsl-error 'no-such-key 'no-such-direction 'cannot-parse 'no-such-colormap </pre> -<p><code>bad-arity</code> is jargon indicating that a procedure has been passed the -wrong number of arguments. <code>gsl-error</code> indicates that the GSL + +<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> -(defmacro without-errors (func) +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> +throws the error 'no-such-file: +</p> + +<pre class="indented"> (define look-for-file (lambda (file) (or (file-exists? file) - (throw 'no-such-file (list "look-for-file" 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. <code>(throw 'snd-top-level)</code>. +or whatever and find yourself back at the top level. (throw 'snd-top-level). </p> -<br> -<table width="50%" border=0><tr><td bgcolor="EEFDEE" valign="middle"><h4>s7 debugging</h4></td></tr></table> + +<div class="innermostheader">s7 debugging</div> <p>When s7 hits an error, it prints out a stacktrace as well as the error message. -The variable *error-info* has additional info. You can also trace functions, and +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> -<br> -<table width="50%" border=0><tr><td bgcolor="EEFDEE" valign="middle"><h4>Forth debugging</h4></td></tr></table> +<div class="innermostheader">Forth debugging</div> <p>See the debugging section in the fth documentation. </p> -<br> -<table width="50%" border=0><tr><td bgcolor="EEFDEE" valign="middle"><h4>Ruby debugging</h4></td></tr></table> + +<div class="innermostheader">Ruby debugging</div> <p> -<code>$DEBUG = true</code> turns on the Ruby debugger. +$DEBUG = true turns on the Ruby debugger. </p> -<br> -<table width="50%" border=0><tr><td bgcolor="EEFDEE" valign="middle"><h4><A NAME="cdebugging">C debugging</a></h4></td></tr></table> + +<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 @@ -12846,33 +13543,38 @@ 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> - gdb snd core - where + +<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> - gdb snd - run + +<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 Gtk, run --g-fatal-errors. If Snd gets hung -and you need to type C-C to get out, +and you need to type C-C to get out (that is, C-g doesn't interrupt the loop), </p> -<pre> - gdb snd - break exit - run + +<pre class="indented"> +gdb snd +break exit +run </pre> -<br> -<table width="80%" border=0><tr><td bgcolor="lightsteelblue" valign="middle"><h3><A NAME="appearance">Customizing Snd's appearance</a></h3></td></tr></table> + +<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 @@ -12884,167 +13586,115 @@ There are a variety of functions and variables related to widget colors and so f </p> -<!-- ---------------------------------------- COLORS ---------------------------------------- --> +<!-- COLORS --> -<table width="60%" border=0><tr><td bgcolor="lightgreen" valign="middle"><h4><A NAME="colors">Colors</a></h4></td></tr></table> +<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> - ><em class=typing>(define blue (<a class=quiet href="#makecolor" onmouseout="UnTip()" onmouseover="Tip(extsnd_makecolor_tip)">make-color</a> 0 0 1))</em> +object is created via make-color: +</p> + +<pre class="indented"> +> (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> - ><em class=typing>(set! (<a class=quiet href="#basiccolor" onmouseout="UnTip()" onmouseover="Tip(extsnd_basiccolor_tip)">basic-color</a>) blue)</em> + +<pre class="indented"> +> (set! (<a class=quiet href="#basiccolor">basic-color</a>) blue) </pre> <p>The color variables -are:</p> - -<table border=2 bordercolor="#f2f4ff" cellpadding=6 hspace=10><tr><td> -<table border=0 cellpadding=0 cellspacing=0 hspace=20> - -<tr><td bgcolor="#f2f4ff"><code><a class=def name="axiscolor">axis-color</a></code></td><td width=20 bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff"><code>defaults to current data color</code></td><td width=20 bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff">color of axes</td></tr> - -<tr><td><code><a class=def name="basiccolor">basic-color</a></code></td><td></td> - <td><code>ivory2</code></td><td></td> - <td>main Snd color.</td></tr> - -<tr><td bgcolor="#f2f4ff"><code><a class=def name="combineddatacolor">combined-data-color</a></code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff"><code>depends on channel number</code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff">color of channel data if channels-combined</td></tr> - -<tr><td><code><a class=def name="cursorcolor">cursor-color</a></code></td><td></td> - <td><code>red</code></td><td></td> - <td>graph cursor color.</td></tr> - -<tr><td bgcolor="#f2f4ff"><code><a class=def name="datacolor">data-color</a></code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff"><code>black</code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff">color of data in unselected graph.</td></tr> - -<tr><td><code><em class=emdef>enved-waveform-color</em></code></td><td></td> - <td><code>blue</code></td><td></td> - <td>color of waveform displayed in envelope editor.</td></tr> - -<tr><td bgcolor="#f2f4ff"><code><em class=emdef>filter-control-waveform-color</em></code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff"><code>blue</code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff">color of control panel filter waveform.</td></tr> - -<tr><td><code><a class=def name="graphcolor">graph-color</a></code></td><td></td> - <td><code>white</code></td><td></td> - <td>background color of unselected graph.</td></tr> - -<tr><td bgcolor="#f2f4ff"><code><a class=def name="highlightcolor">highlight-color</a></code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff"><code>ivory1</code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff">highlighting color.</td></tr> - -<tr><td><code><em class=emdef>listener-color</em></code></td><td></td> - <td><code>aliceblue</code></td><td></td> - <td>background color of listener.</td></tr> - -<tr><td bgcolor="#f2f4ff"><code><em class=emdef>listener-text-color</em></code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff"><code>black</code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff">text color in listener.</td></tr> - -<tr><td><code><a class=def name="markcolor">mark-color</a></code></td><td></td> - <td><code>red</code></td><td></td> - <td>color of mark indicator.</td></tr> - -<tr><td bgcolor="#f2f4ff"><code><em class=emdef>mix-color</em></code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff"><code>darkgray</code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff">color of mix waveforms.</td></tr> - -<tr><td><code><a class=def name="positioncolor">position-color</a></code></td><td></td> - <td><code>ivory3</code></td><td></td> - <td>position slider color</td></tr> - -<tr><td bgcolor="#f2f4ff"><code><a class=def name="sashcolor">sash-color</a></code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff"><code>lightgreen</code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff">color of paned window sashes.</td></tr> - -<tr><td><code><a class=def name="selecteddatacolor">selected-data-color</a></code></td><td></td> - <td><code>black</code></td><td></td> - <td>color of data in currently selected graph.</td></tr> - -<tr><td bgcolor="#f2f4ff"><code><a class=def name="selectedgraphcolor">selected-graph-color</a></code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff"><code>white</code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff">background color of currently selected graph.</td></tr> - -<tr><td><code><a class=def name="selectioncolor">selection-color</a></code></td><td></td> - <td><code>lightsteelblue1</code></td><td></td> - <td>color of selected portion of graph.</td></tr> - -<tr><td bgcolor="#f2f4ff"><code><a class=def name="textfocuscolor">text-focus-color</a></code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff"><code>white</code></td><td bgcolor="#f2f4ff"></td> - <td bgcolor="#f2f4ff">color of text field when it has focus.</td></tr> - -<tr><td><code><a class=def name="zoomcolor">zoom-color</a></code></td><td></td> - <td><code>ivory4</code></td><td></td> - <td>zoom slider color.</td></tr> +are: +</p> -</table> -</td></tr></table> +<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> - (define beige (<a class=quiet href="#makecolor" onmouseout="UnTip()" onmouseover="Tip(extsnd_makecolor_tip)">make-color</a> 0.96 0.96 0.86)) - (define blue (<a class=quiet href="#makecolor" onmouseout="UnTip()" onmouseover="Tip(extsnd_makecolor_tip)">make-color</a> 0 0 1)) - (set! (<a class=quiet href="#selectedgraphcolor" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedgraphcolor_tip)">selected-graph-color</a>) beige) - (set! (<a class=quiet href="#selecteddatacolor" onmouseout="UnTip()" onmouseover="Tip(extsnd_selecteddatacolor_tip)">selected-data-color</a>) blue) + +<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> - 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 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> - 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 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 <code>channels-combined</code>. +channel's data only if the graphs are superimposed, when <a href="#channelstyle">channel-style</a> is channels-combined. </p> - <!-- INDEX colors:Colors --> -<TABLE border=3 bordercolor="tan" hspace=40 vspace=10><tr><td> -<blockquote><small><br> +<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="#colororientationdialog">color-orientation-dialog</a><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> -fancy widget backgrounds: new-backgrounds.scm in the tutorial<br> -color hook: <a href="#colorhook">color-hook</a><br> -Snd graphics contexts: <a href="#sndgcs">snd-gcs</a><br> -<br></small></blockquote> +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> -<br><br> -<!-- ---------------------------------------- FONTS ---------------------------------------- --> -<table width="60%" border=0><tr><td bgcolor="lightgreen" valign="middle"><h4><A NAME="fonts">Fonts</a></h4></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 @@ -13052,43 +13702,44 @@ desired font. These can be the abbreviated forms such as In Gtk, the font names resemble "Monospace 10", etc. The font variables are: </p> -<table cellpadding=0 cellspacing=0 hspace=20> -<tr><td width=200><code><a class=def name="axislabelfont">axis-label-font</a></code></td><td>used in axis labels</td></tr> -<tr><td><code><a class=def name="axisnumbersfont">axis-numbers-font</a></code></td><td>used in axis tick numbers</td></tr> -<tr><td><code><a class=def name="boldpeaksfont">bold-peaks-font</a></code></td><td>used by fft peaks display</td></tr> -<tr><td><code><a class=def name="peaksfont">peaks-font</a></code></td><td>used by fft peaks display</td></tr> -<tr><td><code><em class=emdef>listener-font</em></code></td><td>listener font</td></tr> -<tr><td><code><a class=def name="tinyfont">tiny-font</a></code></td><td>smallest font used</td></tr> -</table> -<br> -<table border=0 cellpadding=5 hspace=20> -<tr><td><pre> -(set! (<a class=quiet href="#listenerfont" onmouseout="UnTip()" onmouseover="Tip(extsnd_listenerfont_tip)">listener-font</a>) "9x15") -(set! (<a class=quiet href="#axislabelfont" onmouseout="UnTip()" onmouseover="Tip(extsnd_axislabelfont_tip)">axis-label-font</a>) "-*-times-medium-r-normal-*-18-*-*-*-*-*-*-*") -(set! (<a class=quiet href="#axisnumbersfont" onmouseout="UnTip()" onmouseover="Tip(extsnd_axisnumbersfont_tip)">axis-numbers-font</a>) "9x15") -</pre></td></tr></table> + +<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> - ><em class=typing>(set! (axis-label-font) "8x14")</em> - <em class=listener>"-*-times-medium-r-normal-*-18-*-*-*-*-*-*-*"</em> + +<pre class="indented"> +> (set! (axis-label-font) "8x14") +"-*-times-medium-r-normal-*-18-*-*-*-*-*-*-*" </pre> -<br> -<br> -<table width="60%" border=0><tr><td bgcolor="lightgreen" valign="middle"><h4><A NAME="graphics">Graphics</a></h4></td></tr></table> -<!-- -------------------------------- GRAPHICS -------------------------------- --> -<table border=0 cellspacing=4 cellpadding=6 hspace=10> +<div class="header" id="graphics">Graphics</div> + +<!-- GRAPHICS --> +<div class="spacer"></div> <!-- add-colormap --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="addcolormap">add-colormap</a> name func</code> -</td></tr><tr><td></td><td> -add-colormap adds a new colormap to the colormap table, returning the colormap object (for +<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 @@ -13098,316 +13749,371 @@ three vcts, each vct 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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (add-colormap "purple" (lambda (size) - (let ((r (<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> size)) - (g (<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> size)) - (b (<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> size)) + (let ((r (make-float-vector size 0.0)) + (g (make-float-vector size 0.0)) + (b (make-float-vector size 0.0)) (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))) - (do ((i 0 (+ 1 i)) + (do ((i 0 (+ i 1)) (x 0.0 (+ x incr))) ((= i size)) - (set! (r i) (/ (<a class=quiet href="sndscm.html#envelopeinterp" onmouseout="UnTip()" onmouseover="Tip(sndscm_envelopeinterp_tip)">envelope-interp</a> x er) 256.0)) ; from env.scm - (set! (g i) (/ (<a class=quiet href="sndscm.html#envelopeinterp" onmouseout="UnTip()" onmouseover="Tip(sndscm_envelopeinterp_tip)">envelope-interp</a> x eg) 256.0)) - (set! (b i) (/ (<a class=quiet href="sndscm.html#envelopeinterp" onmouseout="UnTip()" onmouseover="Tip(sndscm_envelopeinterp_tip)">envelope-interp</a> x eb) 256.0))) + (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))) (list r g b)))) ;;; another amusing colormap from FractInt: (add-colormap "cos" (lambda (size) - (let ((r (<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> size)) - (g (<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> size)) - (b (<a class=quiet href="#makevct" onmouseout="UnTip()" onmouseover="Tip(extsnd_makevct_tip)">make-vct</a> size)) + (let ((r (make-float-vector size 0.0)) + (g (make-float-vector size 0.0)) + (b (make-float-vector size 0.0)) (incr (/ 3.14159 size))) - (do ((i 0 (+ 1 i)) + (do ((i 0 (+ i 1)) (x 0.0 (+ x incr))) ((= i size)) (set! (r i) (abs (sin (* 1.5 x)))) (set! (g i) (abs (sin (* 3.5 x)))) (set! (b i) (abs (sin (* 2.5 x))))) (list r g b)))) -</pre></td></tr></table> +</pre> <table><tr> <td><img src="pix/coscolor.png" alt="colormaps"></td> -<td><img src="pix/jetcolor.png" alt="colormaps"></td> -<td><img src="pix/hotcolor.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> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- background-gradient --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="backgroundgradient">background-gradient</a></code> -</td></tr><tr><td></td><td> +<pre class="indented"> +<em class=def id="backgroundgradient">background-gradient</em> +</pre> + <p>In Gtk versions of Snd, this is the amount of background color gradient in the channel graphs (0.0, the default, means no gradient). </p> -<img src="pix/bggrad.png" alt="graph with background gradient" vspace=10> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<img class="indented" src="pix/bggrad.png" alt="graph with background gradient"> + +<div class="spacer"></div> <!-- color? --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="colorp">color?</a> obj</code> -</td></tr><tr><td></td><td> -This returns #t if 'obj' is a color (a Pixel in xm jargon); see <a href="#makecolor">make-color</a>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="colortolist">color->list</a> obj</code> -</td></tr><tr><td></td><td> -This returns the rgb color components of 'obj' in a list. -<pre> - <em class=listener>:</em><em class=typing>(color->list (make-color 1 0 0))</em> - <em class=listener>(1.0 0.0 0.0)</em> +<pre class="indented"> +<em class=def id="colortolist">color->list</em> obj </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>This returns the rgb color components of 'obj' in a list. +</p> + +<pre class="indented"> + > (color->list (make-color 1 0 0)) + (1.0 0.0 0.0) +</pre> +<div class="spacer"></div> <!-- color-cutoff --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="colorcutoff">color-cutoff</a></code> -</td></tr><tr><td></td><td> -In spectra, this sets the lowest data value that will be colored (the default is 0.003). Anything less than that +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- color-inverted --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="colorinverted">color-inverted</a></code> -</td></tr><tr><td></td><td> -This reflects the 'invert' button in the View:<a href="snd.html#colorbrowser">Color/Orientation</a> dialog. +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- color-scale --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="colorscale">color-scale</a></code> -</td></tr><tr><td></td><td> -color-scale reflects the darkness setting in the View:<a href="snd.html#colorbrowser">Color/Orientation</a> dialog. +<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 Gtk and Motif. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- colormap --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="colormap">colormap</a></code> -</td></tr><tr><td></td><td> -This is the colormap choice for various displays, most prominently the transform sonogram and spectrogram, +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- colormap-name --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="colormapname">colormap-name</a> index</code> -</td></tr><tr><td></td><td> -colormap-name returns the specified colormap's name. -<pre> - <em class=listener>:</em><em class=typing>(colormap-name (colormap))</em> - <em class=listener>"hot"</em> +<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"> +> (colormap-name (colormap)) +"hot" </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- colormap-ref --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="colormapref">colormap-ref</a> map pos</code> -</td></tr><tr><td></td><td> -colormap-ref returns the rgb values of the colormap 'map' at position 'pos', +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- colormap-size --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="colormapsize">colormap-size</a></code> -</td></tr><tr><td></td><td> -colormap-size returns (or sets) the current number of colors in each colormap. +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- colormap->integer --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="colormaptointeger">colormap->integer</a> colormap-object</code> -</td></tr><tr><td></td><td> -This function returns the integer corresponding to a given colormap. -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="colormaptointeger">colormap->integer</em> colormap-object +</pre> + +<p>This function returns the integer corresponding to a given colormap. +</p> +<div class="spacer"></div> <!-- colormap? --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="colormapp">colormap?</a> object</code> -</td></tr><tr><td></td><td> -colormap? returns #t if 'object' is a usable colormap. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><A class=def NAME="copycontext">copy-context</A></code> -</td></tr><tr><td></td><td> -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 <code>copy-context</code> -copies into the current graph, whereas the <code>cursor-context</code> uses XOR. +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- current-font --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="currentfont">current-font</a> <em class=narg>snd chn context</em></code> -</td></tr><tr><td></td><td> -This is the current font (a Font in Motif, a PangoFontDescription* in Gtk+). -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="currentfont">current-font</em> snd chn context +</pre> + +<p>This is the current font (a Font in Motif, a PangoFontDescription* in Gtk+). +</p> +<div class="spacer"></div> <!-- cursor-context --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><A class=def NAME="cursorcontext">cursor-context</A></code> -</td></tr><tr><td></td><td> -This is the graphics mode (an integer in Snd, not a function) for XOR drawing in the cursor color (for cursors, normally). +<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>. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- delete-colormap --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="deletecolormap">delete-colormap</a> object</code> -</td></tr><tr><td></td><td> -delete-colormap deletes the memory associated with the given colormap. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="drawaxes">draw-axes</a> wid gc label x0 x1 y0 y1 style axes cr</code> -</td></tr><tr><td width=30></td><td> -This draws axes in the widget 'wid', using the graphics context 'gc', with the x-axis label 'label' +<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' (<code>x-axis-in-seconds</code> etc). Whether axes are actually displayed or just implied -depends on 'axes', which defaults to <code>show-all-axes</code>. In Gtk, the cairo_t 'cr' argument is not optional; +'style' (x-axis-in-seconds etc). Whether axes are actually displayed or just implied +depends on 'axes', which defaults to show-all-axes. In Gtk, the cairo_t 'cr' argument is not optional; it is ignored in Motif. draw-axes returns a list of the actual (pixel) axis bounds. See the scanned-synthesis display code in snd-motif.scm, or the local envelope editor code in xm-enved.scm. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- draw-dot --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="drawdot">draw-dot</a> x0 y0 dot-size snd chn context cr</code> -</td></tr><tr><td width=30></td><td> -This draws a dot at ('x0 y0') of diameter 'dot-size' pixels in the specified context. See musglyphs.scm. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="drawdots">draw-dots</a> positions dot-size snd chn context cr</code> -</td></tr><tr><td></td><td> -This draws dots of size 'dot-size' from the (x y) pairs in the vector 'positions' in the specified context. +<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 vcts (which would be more consistent with the rest of Snd) because the values passed are supposed to be short ints. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- draw-line --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="drawline">draw-line</a> x0 y0 x1 y1 snd chn context cr</code> -</td></tr><tr><td></td><td> -This draws a line from ('x0 y0') to ('x1 y1') in the specified context. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="drawlines">draw-lines</a> lines snd chn context cr</code> -</td></tr><tr><td></td><td> -This draws lines following the (x y) pairs in the vector 'lines' in the specified context. +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- draw-string --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="drawstring">draw-string</a> text x0 y0 snd chn context cr</code> -</td></tr><tr><td></td><td> -This draws a string ('text') in the current font and foreground color starting at ('x0 y0') in the specified context. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> -(define* (<a name="addcomment">add-comment</a> sample comment snd1 chn1) - (let* ((snd (or snd1 (<a class=quiet href="#selectedsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-sound</a>))) - (chn (or chn1 (<a class=quiet href="#selectedchannel" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedchannel_tip)">selected-channel</a>))) - (old-comments (or (<a class=quiet href="#channelproperty" onmouseout="UnTip()" onmouseover="Tip(sndscm_channelproperty_tip)">channel-property</a> 'comments snd chn) '()))) - (set! (<a class=quiet href="#channelproperty" onmouseout="UnTip()" onmouseover="Tip(sndscm_channelproperty_tip)">channel-property</a> 'comments snd chn) +<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) - (let ((comments (or (<a class=quiet href="#channelproperty" onmouseout="UnTip()" onmouseover="Tip(sndscm_channelproperty_tip)">channel-property</a> 'comments snd chn) '()))) + (let ((comments (or (<a class=quiet href="#channelproperty">channel-property</a> 'comments snd chn) ()))) (for-each - (lambda (<a class=quiet href="#comment" onmouseout="UnTip()" onmouseover="Tip(extsnd_comment_tip)">comment</a>) + (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_leftsample_tip)">left-sample</a> snd chn)) - (rs (<a class=quiet href="#rightsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_rightsample_tip)">right-sample</a> snd chn))) + (ls (<a class=quiet href="#leftsample">left-sample</a> snd chn)) + (rs (<a class=quiet href="#rightsample">right-sample</a> snd chn))) (if (and (< ls samp) (> rs samp)) - (let ((xpos (<a class=quiet href="#xtoposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_xtoposition_tip)">x->position</a> (/ samp (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a>)))) - (ypos (<a class=quiet href="#ytoposition" onmouseout="UnTip()" onmouseover="Tip(extsnd_ytoposition_tip)">y->position</a> (<a class=quiet href="#sample" onmouseout="UnTip()" onmouseover="Tip(extsnd_sample_tip)">sample</a> samp))) + (let ((xpos (<a class=quiet href="#xtoposition">x->position</a> (/ samp (<a class=quiet href="#srate">srate</a>)))) + (ypos (<a class=quiet href="#ytoposition">y->position</a> (<a class=quiet href="#sample">sample</a> samp))) (cr (make-cairo (car (channel-widgets snd chn))))) - (<a class=quiet href="#drawline" onmouseout="UnTip()" onmouseover="Tip(extsnd_drawline_tip)">draw-line</a> xpos 20 xpos (- ypos 4) snd chn time-graph cr) + (<a class=quiet href="#drawline">draw-line</a> xpos 20 xpos (- ypos 4) snd chn time-graph cr) (<em class=red>draw-string</em> text (- xpos (/ text-width 2)) 18 snd chn time-graph cr) (free-cairo cr))))) comments))) -(hook-push <a class=quiet href="#aftergraphhook" onmouseout="UnTip()" onmouseover="Tip(extsnd_aftergraphhook_tip)">after-graph-hook</a> show-comments) -</pre></td></tr></table> -</td></tr><tr><td colspan=2 height=16></td></tr> +(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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="fillrectangle">fill-rectangle</a> x0 y0 width height snd chn context erase cr</code> -</td></tr><tr><td></td><td> -This draws a filled rectangle in the current foreground color from ('x0 y0') of size ('width height'). +<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. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- fill-polygon --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="fillpolygon">fill-polygon</a> points snd chn context cr</code> -</td></tr><tr><td></td><td> -This draws a filled polygon whose vertices are in the vector 'points'. +<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> -<table border=0 cellpadding=5 vspace=10><tr><td><pre> +<pre class="indented"> (define (-> x0 y0 size snd chn cr) - "draw an arrow pointing (from the left) at the point (x0 y0)" + ;; 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) @@ -13419,45 +14125,50 @@ This draws a filled polygon whose vertices are in the vector 'points'. (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" onmouseout="UnTip()" onmouseover="Tip(extsnd_fillrectangle_tip)">fill-rectangle</a> (- x0 (* 4 size)) + (<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></td></tr></table> +</pre> -musglyphs.scm has some elaborate examples that use fill-polygon to draw music notation symbols. -</td></tr><tr><td colspan=2 height=16></td></tr> +<p>musglyphs.scm has some elaborate examples that use fill-polygon to draw music notation symbols. +</p> +<div class="spacer"></div> <!-- foreground-color --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="foregroundcolor">foreground-color</a> <em class=narg>snd chn context</em></code> -</td></tr><tr><td></td><td> -This is the current 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: -<pre> - (set! (foreground-color 0 0 <a class=quiet href="#cursorcontext" onmouseout="UnTip()" onmouseover="Tip(extsnd_cursorcontext_tip)">cursor-context</a>) (<a class=quiet href="#makecolor" onmouseout="UnTip()" onmouseover="Tip(extsnd_makecolor_tip)">make-color</a> 1 0 1)) +</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> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- glSpectrogram --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="glspectrogram">glSpectrogram</a> data gl-list cutoff use-dB min-dB scale br bg bb</code> -</td></tr><tr><td></td><td> -glSpectrogram takes spectrogram data and passes it to openGL. -The <a href="sndscm.html#startwaterfall">waterfall</a> function in snd-gl.scm uses this function. -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="graphdata">graph-data</a> data snd chn context low high graphics-style cr</code> -</td></tr><tr><td></td><td> -<p> -graph-data displays 'data' in the time domain graph of the sound's channel -'chn' using the graphics context 'context' (normally <code>copy-context</code>), placing the +<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, @@ -13465,38 +14176,46 @@ 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 src="pix/redsamps.png" alt="red samples" hspace=20> - -</td></tr><tr><td colspan=2 height=32></td></tr> +<img class="indented" src="pix/redsamps.png" alt="red samples"> +<div class="spacer"></div> <!-- integer->colormap --> -<tr><td colspan=2 bgcolor="#f2f4ff"><code><a class=def name="integertocolormap">integer->colormap</a> i</code> -</td></tr><tr><td></td><td> -This function returns the colormap corresponding to a given integer. -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="integertocolormap">integer->colormap</em> i +</pre> + +<p>This function returns the colormap corresponding to a given integer. +</p> +<div class="spacer"></div> <!-- make-color --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="makecolor">make-color</a> red green blue (alpha 1.0)</code> -</td></tr><tr><td></td><td> -make-color returns a color object using the rgb values 'red', 'green', and 'blue'. Each argument +<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, -<pre> - (make-color 1 0 0) +</p> + +<pre class="indented"> +(make-color 1 0 0) </pre> -returns a red color object. + +<p>returns a red color object. Two colors are equal (i.e. equal? returns #t) if their rgb values are the same. The 'alpha' argument only matters in Gtk. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- make-graph-data --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="makegraphdata">make-graph-data</a> <em class=narg>snd chn edit-position low-sample high-sample</em></code> -</td></tr><tr><td></td><td> -Use make-graph-data to get the currently displayed data (i.e. the waveform displayed +<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 vct (if the graph has one trace), or a @@ -13505,167 +14224,182 @@ list of two vcts (the two sides of the peak envelope graph). '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> -<table border=0 cellpadding=5 vspace=10><tr><td> -<pre> -(define <A NAME="displaydb">display-db</A> +<pre class="indented"> +(define display-db (lambda (snd chn) - "(display-db snd chn) is a lisp-graph-hook function to display the time domain data in dB" (let ((datal (<em class=red>make-graph-data</em> snd chn))) (if datal - (let* ((data (if (<a class=quiet href="#vctp" onmouseout="UnTip()" onmouseover="Tip(extsnd_vctp_tip)">vct?</a> datal) datal (cadr datal))) + (let* ((data (if (float-vector? datal) datal (cadr datal))) (len (length data)) - (sr (<a class=quiet href="#srate" onmouseout="UnTip()" onmouseover="Tip(extsnd_srate_tip)">srate</a> snd))) + (sr (<a class=quiet href="#srate">srate</a> snd))) (define (dB val) (if (< val .001) -60.0 (* 20.0 (log10 val)))) - (do ((i 0 (+ 1 i))) + (do ((i 0 (+ i 1))) ((= i len)) (set! (data i) (+ 60.0 (dB (abs (data i)))))) - (<a class=quiet href="#graph" onmouseout="UnTip()" onmouseover="Tip(extsnd_graph_tip)">graph</a> data "dB" - (/ (<a class=quiet href="#leftsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_leftsample_tip)">left-sample</a> snd chn) sr) (/ (<a class=quiet href="#rightsample" onmouseout="UnTip()" onmouseover="Tip(extsnd_rightsample_tip)">right-sample</a> snd chn) sr) + (<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" onmouseout="UnTip()" onmouseover="Tip(extsnd_lispgraphhook_tip)">lisp-graph-hook</a> display-db) +(hook-push <a class=quiet href="#lispgraphhook">lisp-graph-hook</a> + (lambda (hook) + (display-db (hook 'snd) (hook 'chn)))) </pre> -</td></tr></table> -Here we are taking whatever is displayed in the time domain, and +<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 vct or a list of two vcts), and displays it in any channel's time domain graph using its current graph-style. -</td></tr><tr><td colspan=2 height=16></td></tr> +</p> +<div class="spacer"></div> <!-- mark-context --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><A class=def NAME="markcontext">mark-context</A></code> -</td></tr><tr><td></td><td> -This is the graphics context used to draw a mark (XOR mode). (It is an integer, not a function). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><A class=def NAME="selectioncontext">selection-context</A></code> -</td></tr><tr><td></td><td> -This is the graphics context for XOR drawing in the selection color. (An integer, not a function). -</td></tr><tr><td colspan=2 height=16></td></tr> +<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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sndcolor">snd-color</a> choice</code> -</td></tr><tr><td></td><td> -snd-color returns a Snd built-in color (as a Pixel/GdkPixel); it simplifies +<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/GdkPixel); it simplifies code that wants to follow whatever the current Snd color choices are. The choices are: -<pre> - 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> -</td></tr><tr><td colspan=2 height=16></td></tr> +</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 --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sndfont">snd-font</a> choice</code> -</td></tr><tr><td></td><td> -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 +<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> or <a href="grfsnd.html#sndwithgtk">xg</a> modules. The choices are: -<pre> - 0: <a class=quiet href="#peaksfont" onmouseout="UnTip()" onmouseover="Tip(extsnd_peaksfont_tip)">peaks-font</a> - 1: <a class=quiet href="#boldpeaksfont" onmouseout="UnTip()" onmouseover="Tip(extsnd_boldpeaksfont_tip)">bold-peaks-font</a> - 2: <a class=quiet href="#tinyfont" onmouseout="UnTip()" onmouseover="Tip(extsnd_tinyfont_tip)">tiny-font</a> - 3: <a class=quiet href="#axislabelfont" onmouseout="UnTip()" onmouseover="Tip(extsnd_axislabelfont_tip)">axis-label-font</a> - 4: <a class=quiet href="#axisnumbersfont" onmouseout="UnTip()" onmouseover="Tip(extsnd_axisnumbersfont_tip)">axis-numbers-font</a> - 5: <a class=quiet href="#listenerfont" onmouseout="UnTip()" onmouseover="Tip(extsnd_listenerfont_tip)">listener-font</a> +</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> -See <a href="sndscm.html#displaybarkfft">display-bark-fft</a> in dsp.scm for an example. -</td></tr><tr><td colspan=2 height=16></td></tr> + +<p>See <a href="sndscm.html#displaybarkfft">display-bark-fft</a> in dsp.scm for an example. +</p> +<div class="spacer"></div> <!-- snd-gcs --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="sndgcs">snd-gcs</a></code> -</td></tr><tr><td></td><td> -snd-gcs returns a list of Snd's graphics contexts: -<pre> - 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 +<pre class="indented"> +<em class=def id="sndgcs">snd-gcs</em> +</pre> + +<p>snd-gcs returns a list of Snd's graphics contexts: +</p> - 3: bg=graph-color, fg=cursor-color, XOR (for cursor) - 4: bg=selected-graph-color, fg=cursor-color, XOR (for cursor in selection) +<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 - 5: bg=graph-color, fg=selection-color, XOR (for selection highlighting) - 6: bg=selected-graph-color, fg=selection-color, XOR (selection highlighting) +3: bg=graph-color, fg=cursor-color, XOR (for cursor) +4: bg=selected-graph-color, fg=cursor-color, XOR (for cursor in selection) - 7: bg=data-color, fg=graph-color (to erase data) - 8: bg=selected-data-color, fg=selected-graph-color (erase data in selected channel) +5: bg=graph-color, fg=selection-color, XOR (for selection highlighting) +6: bg=selected-graph-color, fg=selection-color, XOR (selection highlighting) - 9: bg=graph-color, fg=mark-color, XOR (for marks) - 10: bg=selected-graph-color, fg=mark-color, XOR (marks in selected channel) +7: bg=data-color, fg=graph-color (to erase data) +8: bg=selected-data-color, fg=selected-graph-color (erase data in selected channel) - 11: bg=graph-color, fg=mix-color - 12: bg=selected-graph-color, fg=mix-color +9: bg=graph-color, fg=mark-color, XOR (for marks) +0: bg=selected-graph-color, fg=mark-color, XOR (marks in selected channel) - 13: bg=basic-color, fg=black - 14: bg=basic-color, fg=filter-waveform-color +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> -These graphics-contexts make it easier to fit in with whatever color scheme is currently in use. For example, + +<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: -<pre> - (XSetFont dpy - (if (= chn (<a class=quiet href="#selectedsound" onmouseout="UnTip()" onmouseover="Tip(extsnd_selectedsound_tip)">selected-channel</a> snd)) - (cadr (snd-gcs)) - (car (snd-gcs))) - (.fid fs)) +</p> + +<pre class="indented"> + (XSetFont dpy + (if (= chn (<a class=quiet href="#selectedsound">selected-channel</a> snd)) + (cadr (snd-gcs)) + (car (snd-gcs))) + (.fid fs)) </pre> -</td></tr><tr><td colspan=2 height=16></td></tr> +<div class="spacer"></div> <!-- with-gl --> -<tr><td colspan=2 bgcolor="#f2f4ff"> -<code><a class=def name="withgl">with-gl</a></code> -</td></tr><tr><td></td><td> -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 <code>(provided? 'gl)</code>. -</td></tr><tr><td colspan=2 height=16></td></tr> +<pre class="indented"> +<em class=def id="withgl">with-gl</em> +</pre> -</table> +<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> -<br><br> - -<center> -<table bgcolor="aliceblue" border=0 cellspacing=8><tr> -<td><small>related documentation:</small></td> -<td><small><a href="snd.html" onmouseout="UnTip()" onmouseover="Tip(snd_html_tip)">snd.html</a></small></td> -<td><small><a href="grfsnd.html" onmouseout="UnTip()" onmouseover="Tip(grfsnd_html_tip)">grfsnd.html</a></small></td> -<td><small><a href="sndscm.html" onmouseout="UnTip()" onmouseover="Tip(sndscm_html_tip)">sndscm.html</a></small></td> -<td><small><a href="sndclm.html" onmouseout="UnTip()" onmouseover="Tip(sndclm_html_tip)">sndclm.html</a></small></td> -<td><small><a href="fm.html" onmouseout="UnTip()" onmouseover="Tip(fm_html_tip)">fm.html</a></small></td> -<td><small><a href="sndlib.html" onmouseout="UnTip()" onmouseover="Tip(sndlib_html_tip)">sndlib.html</a></small></td> -<td><small><a href="libxm.html" onmouseout="UnTip()" onmouseover="Tip(libxm_html_tip)">libxm.html</a></small></td> -<td><small><a href="s7.html" onmouseout="UnTip()" onmouseover="Tip(s7_html_tip)">s7.html</a></small></td> -<td><small><a href="index.html" onmouseout="UnTip()" onmouseover="Tip(index_html_tip)">index.html</a></small></td> -</tr></table> -</center> +<div class="related"> +related documentation: +<a href="snd.html">snd.html </a> +<a href="grfsnd.html">grfsnd.html </a> +<a href="sndscm.html">sndscm.html </a> +<a href="sndclm.html">sndclm.html </a> +<a href="fm.html">fm.html </a> +<a href="sndlib.html">sndlib.html </a> +<a href="s7.html">s7.html </a> +<a href="index.html">index.html</a> +</div> + </body></html> |