Snd Customization and Extension

Introduction

Snd is a highly customizable, extensible program. The syntax used throughout this documentation is Scheme (a form of lisp) as implemented by the Gnu Guile library. You can also use Ruby, but need to make various minor changes. I've tried to bring out to lisp nearly every portion of Snd, both the signal-processing functions, and much of the user interface. You can, for example, add your own menu choices, editing operations, or graphing alternatives. Nearly everything in Snd can be set in an initialization file, loaded at any time from a file of scheme code or a saved state file, specified via inter-process communication or from stdin from any other program (CLM and Emacs in particular), imbedded in a keyboard macro, or accessed in the lisp listener. 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 this font and Snd's responses are in this font; the Guile case is on the left, the Ruby case is on the right with a blue background):

>(+ 1 2)
3

>1+2
3

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; to exit the listener without using the mouse, type C-g. This is also the way to get back to the listener prompt if it appears to be hung; 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.

Snd Programming

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 called the selection. I originally presented all the functions and variables in an enormous alphabetical list, but that finally became unmanageable. In the following sections, each of the basic entities is treated in a separate section with cross-references where needed. The index provides alphabetical entry.

There are many examples in examp.scm, examp.rb, and snd-test.scm. Extensions to Snd can be found in:

autosave.scm	auto-save (edit backup) support
bess.scm, bess.rb	FM demo (from bess.cl in CLM)
bess1.scm, bess1.rb	FM violin demo (from bess5.cl in CLM)
bird.scm, bird.rb	various North-American birds (from bird.clm)
clm-ins.scm, clm-ins.rb, clm23.scm	various CLM instruments translated to Snd
debug.scm	debugging aids
dlocsig.rb	CLM's dlocsig in Ruby (Michael Scholz)
dlp directory entries	various contributions from Dave Phillips
draw.scm	graphics additions
dsp.scm	various DSP-related procedures
edit-menu.scm	Edit menu additions
edit123.scm, snd_conffile.scm	.snd examples (Tom Roth, Kjetil S. Matheussen)
new-effects.scm, gtk-effects.scm, effects.rb	an Effects menu
env.scm, env.rb	various envelope functions from CLM
enved.scm	envelope editor in lisp graph section
event.scm	xm module stuff for automatic user-interface tests
extensions.scm, extensions.rb	extensions of Snd
fade.scm	frequency-domain cross-fades
fmv.scm	the fm-violin tied to real-time stuff
freverb.scm, freeverb.rb	a reverb
hooks.scm, hooks.rb	functions related to hooks
index.scm, index.rb	snd-help locators
inf-snd.el, DotEmacs	Emacs subjob support (Michael Scholz, Fernando Lopez-Lezcano)
jcrev.scm	John Chowning's reverb
ladspa.scm	Kjetil S. Matheussen's LADSPA GUI-builder and previewer.
maraca.scm	Perry Cook's maraca physical model
marks.scm	functions related to marks
maxf.scm, maxf.rb	Max Mathews resonator
mix.scm	functions related to mixes and tracks
moog.scm	Moog filter (from CLM)
musglyphs.scm	Music notation symbols (from CMN)
nb.scm, nb.rb	Popup File info etc
noise.scm, noise.rb	CLM's noise.ins
oscope.scm	oscilloscope dialog
peak-env.scm	peak envelope support
piano.scm, piano.rb	piano physical model
play.scm	play-related functions
popup.scm, gtk-popup.scm, popup.rb	Popup menu specializations
prc95.scm	Perry Cook's physical model examples (from CLM)
pvoc.scm	phase-vocoder examples
rgb.scm, rgb.rb	color definitions
rmsgain.scm	RMS-based gain and balance (Fabio Furlanete)
rtio.scm, rtio.rb	real-time stuff
rubber.scm, rubber.rb	rubber-sound
singer.scm	Perry Cook's vocal-tract physical model
snd-motif.scm, snd-gtk.scm, snd-xm.rb	Motif/Gtk modules (xm.c, xg.c)
snd-gl.scm	OpenGL examples (gl.c)
snd4\|5\|6\|7.scm	backwards compatibility
spectr.scm, spectr.rb	instrument steady state spectra
strad.scm, strad.rb	string physical model (from CLM)
v.scm, v.rb	fm-violin (from CLM)
ws.scm, ws.rb	with-sound implementation
xm-enved.scm, xm-enved.rb	xm-based envelope editor
zip.scm	the zipper (a cross-fader, sort of) (from CLM)

Customizing Snd's behavior

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

(define unsaved-edits?
  (lambda (lst)
    (if (not (null? lst))
	(if (> (car (edits (car lst))) 0)
	    (begin
	      (report-in-minibuffer "there are unsaved edits")
	      #t)
	    (unsaved-edits? (cdr lst)))
	#f)))

(add-hook! exit-hook (lambda () (unsaved-edits? (sounds))))

Now when Snd is told to exit, it checks exit-hook, runs unsaved-edits?, and if the latter returns #t, if prints a worried message in the minibuffer, and refuses to exit. Similar hooks customize actions such as closing a sound (close-hook), clicking a mark (mark-click-hook), pressing a key (key-press-hook), and so on.

The global variables handle various customizations that aren't callback-oriented. For example, as panes (sounds) come and go, Snd's overall size may change (this is partly determined by the window manager, but is also up to Snd); many people find this distracting -- they would rather that the overall window stick to one size. The Snd variable associated with this is "auto-resize"; it can be accessed as follows (we're typing to the listener here, as described above):

>(auto-resize)
#t
>(set! (auto-resize) #f)
#f

>auto_resize
true
>set_auto_resize false
false

As this illustrates, variables in Snd are accessed as though each were a function, and set using set!. auto-resize's current value is accessed via (auto-resize), and set to a new value via (set! (auto-resize) #f). #t is Scheme for true (often 1 in C, t in Lisp, true in Ruby), #f is false (0 in C, nil in Lisp, false in Ruby). 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.

Global variables

The variables affecting Snd's overall behavior are:

ask-before-overwrite #f

should Snd ask before overwriting an existing file.

audio-input-device mus-audio-default

Audio input device (for the recorder).

audio-output-device mus-audio-default

Audio output device (for the play button).

auto-resize #t

should Snd window resize upon open/close (see AutoResize and blathering above).

auto-update #f

should Snd update a file automatically if it (the file) changes on disk due to some other process.

auto-update-interval 60

Time (seconds) between background checks for changed file on disk (see auto-update). If 0.0, the auto-update background process is turned off.

cursor-location-offset 0.05

Offset (in samples) between Snd's notion of the location of the tracking cursor (cursor-follows-play 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.

cursor-update-interval 0.05

Time (seconds) between cursor updates if cursor-follows-play.

dac-combines-channels #t

if #t, and the current sound has more channels than are supported by the available audio hardware, mix 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.

dac-size 256

Audio output buffer size (not always meaningful). See play-with-envs in enved.scm or play-sound in play.scm. When the various control panel controls are changed, 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).

data-clipped #f

If #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 causes wrap-around which makes the out-of-range values very obvious.

default-output-chans 1

The default number of channels when a new or temporary file is created, or a save dialog is opened.

default-output-format mus-bshort

The default data format when a new or temporary file is created, or a save dialog is opened. (mus-bshort is from sndlib, standing for 16-bit big-endian data). Use mus-out-format for fastest IO.

default-output-srate 22050

The default srate when a new or temporary file is created, or a save dialog is opened.

default-output-type mus-next

The default header type when a new file is created, or a save dialog is opened. (mus-next stands for the NeXT/Sun sound file header).

emacs-style-save-as #f

After File:Save-as dialog option, should Snd remain with the current file (#f) or go to the new file (#t).

eps-bottom-margin 0.0

bottom margin used in snd.eps, created by the Print command. PostScript units are 1/72 of an inch (a "point" in printer jargon); an inch is 2.54 cm:

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

(define (cm-to-ps cm) 
  (* cm (/ 72.0 2.54)))

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.

eps-file "snd.eps"

Name of the Postscript file produced by the File Print option.

eps-left-margin 0.0

left margin used in snd.eps, created by the Print command.

eps-size 1.0

scaler used in snd.eps (Print command) for overall picture size.

graph-cursor XC_crosshair (34)

The kind of cursor displayed following the mouse in the data graph. The X cursors are declared in /usr/X11R6/include/X11/cursorfont.h or some such file.

ladspa-dir #f

Name of directory for LADSPA plugin libraries (can override or replace LADSPA_PATH). See Snd and LADSPA.

log-freq-start 32.0

start freq used in 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 spectro-start variable every time you wanted to flip between log and linear displays. log-freq-start to the rescue? (In earlier versions of Snd I tried to kludge around this by pre-multiplying the frequencies by some big number, thereby shifting everything up in log space, but I decided that was a worse kludge than log-freq-start).

max-regions 16

Maximum size of the region list; the number of regions that are accessible.

minibuffer-history-length 8

Maximum length of minibuffer and listener M-p/M-n history lists.

optimization 0

If non-zero, try to optimize simple lambda forms passed to the searches and so forth. This depends partly on the optargs module (not available in the correct form before Guile 1.5), only applies to Guile (not Ruby), and is highly experimental. The actual values of the optimization switch are:

0:	no use of parse trees at all (use the standard Guile parser/evaluator)
1:	allow simple ops (if complex result possible, give up)
2:	assume nothing will return a complex number
3:	if undefined global variable encountered, try to determine eventual type from context
4:	make dangerous assumptions about variable types
5:	make dangerous assumptions about variable locations (for set!)
6:	try to splice in user-defined functions (buggy!)

Currently, the optimizer is able to speed up Scheme code by factors between 8 and 20; see snd-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. One dangerous assumption involved in local variables (optimization = 5) is that such a variable might be a continuation set within the run-optimized code, but then called from outside that block. This (obviously!) won't work, but it's too much trouble to try to trap it in the context of run. Here are some representative results; the first number is the unoptimized time, the second is the optimized time, the third is the speed-up ratio:

singer	1225	55	22	abs sin	447	36	12	jcrev	505	44	11
vct-ref	413	31	13	-1	269	21	13	expsnd	158	16	10
let if	372	36	10	*2	274	20	14	fm vln	206	16	13

run-safety 0

If run-safety is not 0, code is added by the run macro to perform various error checks, much as in CLM with *clm-safety*.

save-dir #f

Name of directory for saved-state files.

If #f, all saved-state is placed (as text) in the saved-snd.scm file. If you've edited a sound file, this can be unwieldy because each changed sample is saved as text! By setting save-dir, Snd instead places the necessary intermediate files in save-dir, with the file names in the saved-state file. The assumption here is that you won't mess with the save-dir files until you no longer want to restart that version of Snd. (set! (save-dir) "/tmp").

save-state-file "saved-snd.scm"

The default saved state file name.

selection-creates-region #t

If #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.

show-backtrace #f

If #t, show backtrace automatically upon error.

show-indices #f

If #t, each sound's name is preceded by its index (in the sound pane).

show-selection-transform #f

If #t, display the transform of the current active selection, if any. (Thie sonogram and spectrogram displays ignore this flag because they assume their time axis matches that of the time domain graph).

sinc-width 10

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 (src-sound '(0 3 1 1)) with sinc-width at 4.

temp-dir #f

Name of directory for temporary files. #f usually means "/tmp" or "/var/tmp". See snd-tempnam, and autosave.scm.

trap-segfault #t

If #t, try 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!

window-height 0

The current Snd window height in pixels. This is the same as
(cadr (widget-size (cadr (main-widgets))))
except at startup when the window-height function and friends defer the set 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 (set! (window-height) 300) or some such number.

window-width 0

The current Snd window width in pixels.

window-x -1

The current Snd window left side in pixels. This is (usually) the same as
(car (widget-position (cadr (main-widgets))))

window-y -1

The current Snd window upper side in pixels (X numbering starts at 0 at the top).

with-background-processes #t

Determines whether Snd should use background (idle time) processes for ffts and so forth. (Intended primarily for auto-testing).

with-relative-panes #t

If this flag is set 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?).

zoom-focus-style zoom-focus-active

This determines what a zoom action focuses (centers) on. The choices are zoom-focus-left, zoom-focus-right, zoom-focus-active, and zoom-focus-middle. See Zoom options.

Hooks

When some user-interface action takes place, code is called that responds to that action; these functions are sometimes called callbacks; in Guile the variable that holds a list of such callbacks is known as a hook. A hook provides a way to customize user-interface actions. The hook itself is list of functions. The Guile function add-hook! adds a function to a hook's list, remove-hook! removes a function, and reset-hook! clears out the list. For example, the hook that is checked when you click the sound's name in the minibuffer is name-click-hook. We can cause that action to print "hi" in the listener by:

>(add-hook! name-click-hook (lambda (snd) (snd-print "hi") #t))

If there is more than one function attached to a hook, some of the hooks "or" the functions together (marked or below); 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 (named "progn" from Common Lisp), 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 invocatiion. In the list below the arguments after the hook name refer to the arguments to the functions invoked by the hook. That is, after-apply-hook (snd) means that the functions on the after-apply-hook list each take one argument, a sound index.

In Ruby, the hook is a global variable that holds either a procedure or is false.

after-apply-hook (snd)

called when 'Apply' finishes. add-amp-controls in snd-motif.scm uses this hook to reset any added amplitude sliders to 1.0 when Apply finishes.

after-graph-hook (snd chn)

called after a graph is updated or redisplayed; see display-samps-in-red, draw-smpte-label in snd-motif.scm, or add-comment.

after-open-hook (snd)

called just before a newly opened sound's window is displayed. This 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, and filled graphs:

(add-hook! after-open-hook
  (lambda (snd)
    (if (> (channels snd) 1)
        (begin
          (set! (sync snd) (1+ snd)) ; 0 = #f
          (set! (channel-style snd) channels-combined)
          (set! (graph-style snd) graph-filled)))))

See also C-x b support in examp.scm, remember-sound-state in extensions.scm, enved.scm, and various examples in snd-motif.scm.

after-save-state-hook (filename)

called after Snd has saved its state (save-state). 'filename' is the (otherwise complete) saved state program. See ws-save-state in ws.scm or remember-sound-state in extensions.scm. Both use this sequence:

(lambda (filename)
  (let ((fd (open filename (logior O_RDWR O_APPEND)))) ; open to write at the end
    (format fd "~%~%;;; save-state stuff here ~%")
    ...
    (close fd)))

bad-header-hook (filename) or

called if a file has a bogus-looking header. Return #t to give up on that file.

(add-hook! bad-header-hook (lambda (n) #t))

before-transform-hook (snd chn) progn

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

(add-hook! before-transform-hook
  (lambda (s c) 
    (inexact->exact 
      (* .5 (+ (right-sample s c) (left-sample s c))))))

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

(define fft-position #f)
(add-hook! before-transform-hook (lambda (snd chn) fft-position))
(add-hook! mark-drag-hook (lambda (id)
                            (set! fft-position (mark-sample id))
                            (update-transform-graph)))

close-hook (snd) or

called each time a file is closed (before the close). If it returns #t, the file is not closed.

(add-hook! close-hook
  (lambda (snd) 
    (system \"sndplay wood16.wav\")
    #f))

close-hook is used in autosave.scm, examp.scm, extensions.scm, and peak-env.scm; see, for example, check-for-unsaved-edits or remember-sound-state in extensions.scm.

color-hook () progn

called whenever one of the variables associated with the color dialog changes. See start-waterfall in snd-gl.scm.

dac-hook (data) progn

called just before data is sent to DAC passing data as sound-data object. See with-level-meters in snd-motif.scm.

draw-mark-hook (id) progn

called before a mark is drawn (in XOR mode). If the hook returns #t, the mark is not drawn. mark-sync-color in snd-motif.scm uses this hook to draw sync'd marks in some other color than the current mark-color.

drop-hook (filename) or

called each time Snd receives a drag-and-drop event, passing the hook the filename. If it returns #t, the file is not opened. If you drag the file icon to the menubar, Snd opens it as if you had called open-sound. If you drag it 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:

(add-hook! drop-hook (lambda (filename) (mix filename) #t))

snd-motif.scm has examples that add a drop callback to an arbitrary widget, or change an existing callback (to pass the sound index and channel number to the drop callback function, bypassing drop-hook).

during-open-hook (fd name reason)

called after file is opened, but before data has been read. This provides an opportunity to set sndlib prescaling values:

(add-hook! during-open-hook
  (lambda (fd name reason)
    (if (= (mus-sound-header-type name) mus-raw)
        (set! (mus-file-prescaler fd) 500.0))))

The prescaling affects only sound data made up of floats or doubles.

enved-hook (env pt new-x new-y reason) cascade

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 is reason which 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 stretch-envelope from env.scm:

(add-hook! enved-hook
  (lambda (env pt x y reason)
    (if (= reason enved-move-point)
        (if (and (> x 0.0) (< x (envelope-last-x env))) ; from env.scm
            (let* ((old-x (list-ref env (* pt 2)))
                   (new-env (stretch-envelope env old-x x)))
              (list-set! new-env (+ (* pt 2) 1) y)
              new-env)
            env)
        #f)))

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"; I like the latter.

exit-hook () or

called upon exit. If it returns #t, Snd does not exit. This can be used to check for unsaved edits, or to perform cleanup activities (see autosave.scm, extensions.scm, or unsaved-edits?). Guile's exit-hook is shadowed by this variable.

graph-hook (snd chn y0 y1) or

called each time a graph is updated or redisplayed. If it returns #t, the display is not updated. See examp.scm for many examples.

(add-hook! graph-hook
  (lambda (snd chn y0 y1)
    "set the dot size depending on the number of samples being displayed"
    (let ((dots (- (right-sample snd chn) (left-sample snd chn))))
      (if (> dots 100) 
	  (set! (dot-size snd chn) 1)
	(if (> dots 50)
	    (set! (dot-size snd chn) 2)
	  (if (> dots 25)
	      (set! (dot-size snd chn) 3)
	    (set! (dot-size snd chn) 5))))
      #f)))

help-hook (subject help-string) cascade

called from snd-help with the current help subject and default help-string. Say we want the index.scm procedure 'html' called any time snd-help is called (from C-? for example):

(add-hook! help-hook (lambda (subject help) (html subject) #f))

If there is more than one hook function, each function's result is passed as input to the next function.

initial-graph-hook (snd chn dur) or

called the first time a given channel is displayed. If it returns a list, the list's contents are interpreted as:
'(x0 x1 y0 y1 label ymin ymax)
(all values optional), where these numbers set the initial axis limits and settings. The default (empty hook) is equivalent to:

(add-hook! initial-graph-hook (lambda (snd chn dur) (list 0.0 0.1 -1.0 1.0 "time" -1.0 1.0)))

The dur argument is the total length in seconds of the channel, so to cause the entire sound to be displayed initially:

(add-hook! initial-graph-hook (lambda (snd chn dur) (list 0.0 dur)))

To get the data limits (rather than the default -1.0 to 1.0 as above), you can use mus-sound-maxamp, 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 only if it is already available:

(add-hook! initial-graph-hook
  (lambda (snd chn dur)
    (if (mus-sound-maxamp-exists? (file-name snd))
	(let* ((amp-vals (mus-sound-maxamp (file-name snd)))
	       (max-val (list-ref amp-vals (+ (* chn 2) 1))))
	  (list 0.0 dur (- max-val) max-val))
	(list 0.0 dur -1.0 1.0))))

A similar problem affects the dur argument. If the file is very long, Snd starts a background process reading its data to get an overall amplitude envelope of the file, and this envelope is what it actually displays when you zoom out to look at the entire sound. If you set x1 to dur, you effectively get two such processes contending for access to the data. One way around this is to save the envelope (a "peak envelope" in Snd's nomenclature); load peak-env.scm to make this process automatic.

just-sounds-hook (filename) or

called on each file (after the sound file extension check) if the just-sounds button is set. Return #f to filter out filename.

(add-hook! just-sounds-hook
  (lambda (name) ;display only stereo files in file selection dialog
    (and (not (= (mus-sound-header-type name) mus-raw))
         ;;any unrecognized file is considered "raw"
         (= (mus-sound-chans name) 2))))

This works only in Motif or Gtk versions 2.3 and higher.

key-press-hook (snd chn key state) or

called upon key press while the mouse is in the lisp graph. If it returns #t, the key press is not passed to the main handler. state refers to the control, meta, and shift keys. start-enveloping in enved.scm uses this hook to add C-g and C-. support to the channel-specific envelope editors.

lisp-graph-hook (snd chn) progn

called just before the lisp graph is updated or redisplayed (see display-db). If it 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:

(add-hook! lisp-graph-hook
	   (lambda (snd chn)
	     (lambda ()
	       (draw-string "hi" 
			    (x->position 0.5 snd chn lisp-graph) 
			    (y->position 0.0 snd chn lisp-graph)
			    snd chn))))

listener-click-hook (textpos)

called when a click occurs in the listener; the argument is the position in the text where the click occurred. See click-for-listener-help in draw.scm.

mark-click-hook (id) progn

called when a mark is clicked; return #t to squelch default minibuffer mark identification. The following hook function is used in with-marked-sound in ws.scm to display arbitrary info about a note.

(add-hook! mark-click-hook
  (lambda (n) 
    (if (not (defined? 'mark-properties)) (load "marks.scm"))
    (info-dialog "Mark Help"
      (format #f "Mark ~D~A:~%  sample: ~D = ~,3F secs~A~A"
	      n 
	      (let ((name (mark-name n)))
   	        (if (> (string-length name) 0)
		    (format #f " (~S)" name)
		    ""))
	      (mark-sample n)
	      (/ (mark-sample n) (srate (car (mark-home n))))
	      (if (not (= (mark-sync n) 0))
	        (format #f "~%  sync: ~A" (mark-sync n))
	        "")
	      (let ((props (mark-properties n)))
	        (if (and (list? props)
		         (not (null? props)))
	          (format #f "~%  properties: '~A" props)
	          ""))))
    #t))

mark-drag-hook (id)

called when a mark is dragged.

(define (report-mark-location id)
  ;; print current mark location in minibuffer
  (let ((samp (mark-sample id))
        (sndchn (mark-home id)))
    (report-in-minibuffer 
      (format #f "mark ~D: sample: ~D (~,3F) ~A[~D]: ~,3F"
              id samp 
              (/ samp (srate (car sndchn))) 
              (short-file-name (car sndchn))
              (cadr sndchn)
	      (sample samp (car sndchn) (cadr sndchn))))))
(add-hook! mark-drag-hook report-mark-location)

mark-drag-triangle-hook (id x time dragged-before) progn

called when a mark play triangle is dragged. The smoothness of the response to the drag motion is largely determined by dac-size. dragged-before is #f when the drag starts and #t thereafter. x is the mouse x location in the current graph. time is the uninterpreted time at which the drag event was reported. id is the mark id. If the hook returns #t, Snd takes no further action. To set up to play, then interpret the motion yourself, return #f on the first call, and #t thereafter:

(let ((first-x 0))
  (add-hook! mark-drag-triangle-hook
    (lambda (id x time dragged-before)
      (if (not dragged-before)
	  (set! first-x x)
	  (set! (speed-control) (/ (- x first-x) 16.0)))
      dragged-before)))

mark-hook (id snd chn reason)

called when a mark is added, deleted, or moved (but not while moving). 'id' can be -1 (i.e. no specific mark). '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 mark-sync is active, the hook is called on each syncd mark.

(define (snap-mark-to-beat)
  ;; when a mark is dragged, its end position is always on a beat
  (let ((mark-release 4))
    (add-hook! mark-hook
      (lambda (mrk snd chn reason)
        (if (= reason mark-release)
            (let* ((samp (mark-sample mrk))
	           (bps (/ (beats-per-minute snd chn) 60.0))
		   (sr (srate snd))
		   (beat (floor (/ (* samp bps) sr)))
		   (lower (inexact->exact (/ (* beat sr) bps)))
		   (higher (inexact->exact (/ (* (1+ beat) sr) bps))))
	      (set! (mark-sample mrk)
	      (if (< (- samp lower) (- higher samp))
		  lower
 		  higher))))))))

mix-click-hook (id) progn

called when a mix tag is clicked; return #t to omit the default action which is to print the mix id in the minibuffer. A more informative version is mix-click-info in mix.scm. Here's an example that sets the mix amps to 0 if you click it (see mix-click-sets-amp in mix.scm for a fancier version):

(add-hook! mix-click-hook
  (lambda (n)
    (do ((i 0 (1+ i)))
	((= i (mix-chans n)))
      (set! (mix-amp n i) 0.0))
    #t))

mix-drag-hook (id)

called when a mix is dragged.

(add-hook! mix-drag-hook
  (lambda (n) 
    (report-in-minibuffer 
      (format #f "mix ~A at ~D: ~,3F" n (mix-position n) (/ (mix-position n) (srate))))))

mix-release-hook (id samps) progn

called after a mix has been dragged by the mouse to a new position (id = mix id, samps = total samples moved during the drag). If it returns #t, the actual remix is the hook's responsibility. See snap-mix-to-beat in mix.scm.

mouse-click-hook (snd chn button state x y axis) or

called upon a mouse button release or click (with various exceptions). If it returns #t, the click is ignored by Snd. See the current-window-location procedures in draw.scm. Here's a simpler example:

(define (click-to-center snd chn button state x y axis)
  ;; if mouse click in time domain graph, set cursor as normally, but also center the window
  (if (= axis time-graph)
      (let ((samp (inexact->exact (* (srate snd) (position->x x snd chn)))))
	(set! (cursor snd chn) samp)
	(set! (right-sample snd chn) 
          (- samp (inexact->exact (* .5 (- (left-sample snd chn) (right-sample snd chn))))))
	(update-time-graph)
	#t)
      #f))

(add-hook! mouse-click-hook click-to-center)

;;; this example disables button 2 -> insert selection
(add-hook! mouse-click-hook
  (lambda (snd chn button state x y axis)
    (and (= axis time-graph) (= button 2))))

mouse-drag-hook (snd chn button state x y)

called when the mouse is dragged within the lisp graph (see enved.scm or rtio.scm).

mouse-enter-graph-hook (snd chn)

called when the mouse enters a channel's drawing area (graph pane).

(add-hook! mouse-enter-graph-hook
  (lambda (snd chn) 
    (snd-print (format #f "~A[~A]" (short-file-name snd) chn))))

mouse-enter-label-hook (type position name)

called when a file viewer or region label is entered by the mouse. The 'type' is 0 for the current files list, 1 for previous files, and 2 for regions. The 'position' is the scrolled list position of the label. The label itself is 'label'. We could use the finfo procedure in examp.scm to popup file info as follows:

(add-hook! mouse-enter-label-hook
  (lambda (type position name)
    (if (not (= type 2))
        (info-dialog name (finfo name)))))

See also files-popup-buffer in examp.scm

mouse-enter-listener-hook (widget)

called when the mouse enters the lisp 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 could define the following hook procedures:

(add-hook! mouse-enter-graph-hook
  (lambda (snd chn)
    (if (sound? snd) (focus-widget (car (channel-widgets snd chn))))))

(add-hook! mouse-enter-listener-hook
  (lambda (widget)
    (focus-widget widget)))

I much prefer this style of operation.

mouse-enter-text-hook (widget)

called when the mouse enters a text widget (this is the third of the pointer-focus hooks).

(add-hook! mouse-enter-text-hook
  (lambda (w)
    (focus-widget w)))

mouse-leave-graph-hook (snd chn)

called when the mouse leaves a channel's drawing area (graph pane).

mouse-leave-label-hook (type position name)

called when the mouse exits one of the labels covered by mouse-enter-label-hook. (See nb.scm)

mouse-leave-listener-hook (widget)

called when the mouse leaves the lisp listener pane.

mouse-leave-text-hook (widget)

called when the mouse leaves a text widget.

mouse-press-hook (snd chn button state x y)

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 position->x and position->y).

mus-error-hook (error-type error-message) or

called upon mus-error. If it returns #t, Snd ignores the error (it assumes you've handled it via the hook). This hook is used in play-sound in play.scm to flush an error message that the Snd ALSA support code generates (or used to generate). 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:

(add-hook! mus-error-hook
  (lambda (typ msg)
    (and (= typ 0)         ; it's mus_print, not mus_error
         (display msg))))  ; display returns some non-#f result, I assume

name-click-hook (snd) or

called when the sound name is clicked. If it returns #t, the usual informative minibuffer babbling is squelched.

(add-hook! name-click-hook
  (lambda (snd) ; toggle read-only
    (set! (read-only snd) (not (read-only snd)))
    #t))

new-sound-hook (filename)

called whenever a new sound file is being created. sound-let 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.

new-widget-hook (widget)

called each time a dialog or a new set of channel or sound widgets is created. This is used in snd-motif.scm (paint-all) to make sure all newly created widgets have the same background pixmaps.

open-hook (filename) or

called each time a file is opened (before the actual open). If it returns #t, the file is not opened. If it returns a string (a filename), that file is opened instead of the original one.

(add-hook! open-hook
  (lambda (filename)
    (if (= (mus-sound-header-type filename) mus-raw)
        ;; 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 (format #f "ogg123 -d au -f ~A ~A" aufile filename))
	      aufile)
	    #f)
	#f)))

Snd's objects

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. One of the most commonly used is the vct. But before launching into vcts, I need to explain a few things about the following documentation.

In the following lists, optional arguments are in italics (although netscape sometimes displays them in bold face for some reason). Each sound has an associated index used to refer to it in all the functions. This arbitrary number is more or less related to the sound's position in the display of sounds (if the variable show-indices is #t, the index is displayed in front of the sound's name). In the argument lists below, snd as an argument refers to the sound's index, and defaults to the currently selected sound. Similarly, chn is the channel number, starting from 0, and defaults to the currently selected channel. So if there's only one sound active (say its index is 0), and it has only one channel, (cursor) (cursor 0), and (cursor 0 0) all refer to the same thing. If you want to refer to the currently selected sound, either use #f as the sound index or selected-sound.

Some functions take optional-key arguments, as in CLM. These are marked "&optional-key" below, followed by the keywords themselves. As in CLM, the keywords can be omitted.

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

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

Vcts

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 vct can be viewed as a vector; to make one, call make-vct. It is freed by the garbage collector when it can't be referenced any further. To get an element of a vct, use vct-ref; similarly vct-set! sets an element (the "!" appended to the setter functions is standard in Scheme; another is the use of "?" where Common Lisp is more likely to use "-p"). Once created, a vct can be passed to a variety of built-in functions:

  (define hi (make-vct 100))
  (vct-fill! hi 3.14)
  (vct-scale! hi -1.0)

Now our vct hi has 100 -3.14's.

`list->vct (lst)`
	return vct with elements of list lst. Equivalent to `(apply vct lst)`.
`make-vct (len (initial-element 0.0))`
	create vct of size len.
`sound-data->vct (sdobj (chan 0) (v #f))`
	place sound-data channel data in vct, returning v or the new vct.
`vct args...`
	list->vct with args as the list: `(vct 1 2 3)` = `(list->vct '(1 2 3))`
`vct? (v)`
	#t if v is a vct.
`vct-add! (v1 v2 (off 0))`
	element-wise add: `v1[i + off] += v2[i]`, returns v1.
`vct-copy (v)`
	return a copy of v.
`vct-fill! (v val)`
	set each element of v to val, `v[i] = val`, returns v.
`vct-length (v)`
	return length of v.
`vct-map (thunk v0 vcts...)`
	map 'thunk' (which should return a frame) into the vcts passed as trailing args.
`vct-map! (v proc)`
	set each element of v to the value returned by (proc); `(vct-map! v (lambda () 3.0))` is the same as `(vct-fill! v 3.0)`.
`vct-move! (v new old (backwards #f))`

	`v[new++] = v[old++]`, returns v (if backwards is #t, `v[new--] = v[old--]`)
`vct-multiply! (v1 v2)`
	element-wise multiply: `v1[i] *= v2[i]`, returns v1.
`vct-offset! (v val)`
	add val to each element of v: `v[i] += val`, returns v.
`vct-peak (v)`
	maximum of absolute value of all elements of v
`vct-ref (v pos)`
	element pos in v: `v[pos]`.
`vct-reverse! (v (size #f))`
	reverse contents of v (in-place), return v. Reverse around size if given.
`vct-scale! (v scl)`
	multiply each element of v by scl: `v[i] *= scl`, returns v.
`vct-set! (v pos val)`
	set element pos of v to val: `v[pos] = val`. same as `(set! (vct-ref v pos) val)`.
`vct-subtract! (v1 v2)`
	element-wise subtract: `v1[i] -= v2[i]`, returns v1.
`vct-subseq (v start (end len) (nv #f))`
	return a new vct (or nv if given) with the elements of v between start and end inclusive. end defaults to the end of v.
`vct->channel (v (beg 0) (dur len) (snd #f) (chn #f) (edpos #f) (origin #f))`
	set the samples from beg to beg+dur from the values in v.
`vct->list (v)`
	return list with elements of v
`vct->sound-data (v sd (chan 0))`
	place vct v data in sound-data sd, returning sd
`vct->sound-file (fd v vals)`
	write vals floats from v to fd. This is intended for use with open-sound-file
`vct->string (v)`
	return 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.
`vct->vector (v)`
	return vector with elements of v
`vector->vct (vect)`
	return vct with elements of vector vect

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:

  region->vct
  transform->vct
  channel->vct
  mix->vct
  sound-data->vct
  track->vct
  vector->vct
  selection->vct

We could combine some of these vct functions to implement Horner's rule (the polynomial generator) over an entire channel:

(define (vct-polynomial v coeffs)
  (let* ((v-len (vct-length v))
	 (num-coeffs (vct-length coeffs))
	 (new-v (make-vct v-len (vct-ref coeffs (1- num-coeffs)))))
    (do ((i (- num-coeffs 2) (1- i)))
	((< i 0))
      (vct-offset! (vct-multiply! new-v v) (vct-ref coeffs i)))
    new-v))

(define* (channel-polynomial coeffs #:optional snd chn)
  (let ((len (frames snd chn)))
    (vct->channel (vct-polynomial (channel->vct 0 len snd chn) coeffs) 0 len snd chn)))

;;; (channel-polynomial (vct 0.0 .5)) = x*.5
;;; (channel-polynomial (vct 0.0 1.0 1.0 1.0)) = x*x*x + x*x + x

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

  (vct-map! out-data (lambda () 
                       (convolve cnv (lambda (dir) 
                                       (read-sample sf)))))

in the cnvtest function in examp.scm is calling the convolve generator and assigning the result to each successive member of the out-data vct. We can use vcts to write new sound files:

  open-sound-file (name chans srate comment)   ; returns fd
  vct->sound-file (fd vct vals)                ; writes vals floats to fd
  close-sound-file (fd vals)

After opening the file, loop through the data calling channel->vct, deal with the vct data as desired, write the samples to the file via vct->sound-file, then when finished, close-sound-file. If the new data is to replace the old, call (set! (samples...) data) with the new sound file's name; otherwise call insert-samples.

If you have Guile 1.4.1 or later, it's possible to access a vct's elements with the syntax (v index), equivalent to (vct-ref v index), but without some of the type checks. This is using a feature called "applicable smobs" in Guile. The clm generators also use this syntax:

  >(define hi (make-oscil 440.0))
  #<unspecified>
  >(hi)
  0.0
  >(oscil hi)
  0.125050634145737

It's no accident that the generator's type (i.e. oscil or whatever) is hidden here. We can make a generator that is either an oscil or a sawtooth-wave:

  >(define sine-or-sawtooth
     (lambda (sine)
        (let ((gen ((if sine make-oscil make-sawtooth-wave) 440.0)))
           (lambda (fm)
              (gen fm)))))
  #<unspecified>
  >(define osc (sine-or-sawtooth #t))
  #<unspecified>
  >(osc 0.0)
  0.0
  >(osc 0.0)
  0.125050634145737

Sound-data and Sndlib

Another sound data object is the sound-data array used in Sndlib.

`make-sound-data (chans frames)`
	return a sound-data object with chans arrays, each of length frames
`sound-data-ref (obj chan frame)`
	return (as a float) the sample in channel chan at location frame
`sound-data-set! (obj chan frame val)`
	set obj's sample at frame in chan to (the float) val
`sound-data? (obj)`
	#t if obj is of type sound-data
`sound-data-length (obj)`
	length (in samples) of each channel of data in obj
`sound-data-maxamp (obj)`
	list of maxamps (one for each channel) of data in obj
`sound-data-chans (obj)`
	number of channels of data in obj
`sound-data->sound-data (sd-in sd-out beg dur cycle)`
	copy sound-data sd-in's data from 0 for dur frames into 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).
`sound-data->vct (sdobj chan vobj)`
	copy sound-data channel data into vct
`vct->sound-data (vobj sdobj chan)`
	copy vct data into sound-data

All of the underlying sound library (Sndlib) functions are available, as well as most of (CLM). See play.scm and rtio.scm. The most important Sndlib functions for Snd are:

mus-audio-close (line)

close audio port line

mus-audio-describe ()

describe audio hardware state (in help window)

mus-audio-mixer-read (device field channel vals)

read current state of device's field:

  mus-audio-amp         mus-audio-srate    mus-audio-channel mus-audio-format
  mus-audio-imix        mus-audio-igain    mus-audio-reclev  mus-audio-pcm 
  mus-audio-ogain       mus-audio-line     mus-audio-synth   mus-audio-bass
  mus-audio-direction   mus-audio-port     mus-audio-pcm2    mus-audio-treble
  mus-audio-samples-per-channel

vals should be a vct big enough to handle the returned data (the channel argument normally is the size).

mus-audio-mixer-write (device field channel vals)

set state of device's field.

;;; here we get the microphone volume, then set it to .5
(define vals (make-vct 32))
(mus-audio-mixer-read mus-audio-microphone mus-audio-amp 0 vals)
(vct-ref vals 0)
(vct-set! vals 0 .5)
(mus-audio-mixer-write mus-audio-microphone mus-audio-amp 0 vals)
;;; now set the 2 "igain" fields to 1
(vct-set! vals 0 1.0)
(vct-set! vals 1 1.0)
(mus-audio-mixer-write mus-audio-mixer mus-audio-igain 2 vals)

mus-audio-open-input (device srate chans format bufsize)

open audio port device ready for input. Return -1 if the open failed. device is one of:

  mus-audio-default      mus-audio-duplex-default   mus-audio-line-out
  mus-audio-microphone   mus-audio-speakers         mus-audio-dac-out    
  mus-audio-aes-in       mus-audio-digital-in       mus-audio-digital-out
  mus-audio-aes-out      mus-audio-dac-filter       mus-audio-mixer
  mus-audio-line2        mus-audio-line3            mus-audio-aux-input 
  mus-audio-line-in      mus-audio-aux-output       mus-audio-adat-in
  mus-audio-adat-out     mus-audio-line1            mus-audio-cd 
  mus-audio-spdif-in     mus-audio-spdif-out

mus-audio-open-output (device srate chans format bufsize)

open audio port device ready for output. Return -1 if the open failed.

mus-audio-read (line sdata frames)

read frames of data into sound-data object sdata from port line. The in-coming data format is set by the corresponding mus-audio-open-input call and is translated to the sound-data format (internally known as mus_sample_t) by mus-audio-read.

mus-audio-report ()

return a string describing the current audio hardware state. mus-audio-describe prints out the same string.

mus-audio-sun-outputs (speakers headphones line-out)

(Sun only) set the current Sun audio outputs. Each entry should be either 0 (turn off device) or 1 (turn it on).

mus-audio-write (line sdata frames)

write frames of data from sound-data sdata to audio port line. As with mus-audio-read, the out-going data format is set by mus-audio-open-output, and the sound-data's data is translated to that format by mus-audio-write.

mus-bytes-per-sample (data-format)

number of bytes in each sample of data-format.

mus-data-format-name (format)

convert format from an integer to a string, e.g. "16-bit big endian linear". The sndlib data formats are:

  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

mus-error-to-string (error)

return a brief string description of error (a mus-error return type).

mus-expand-filename (name)

expand name into its 'absolute' pathname; that is, replace '~' with the current home directory, and whatever else seems appropriate.

mus-file-data-clipped ()

The default low-level clipping choice while accessing sound data. The default is #f which makes clipping very obvious (it will cause wrap-around).

mus-file-prescaler (fd)

The prescaling value for reading data from the sndlib file descriptor fd. If you're reading float data that is extremely soft (i.e. max amp below .001), the transfer to integer form in sndlib 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 the set of mus-file-prescaler should come just after opening the sound file, but before trying to read any data, you need to use it in the context of during-open-hook.

mus-header-type-name (type)

convert type, an integer, to a string, e.g. "AIFF". Some of the sndlib header types are:

  mus-next  mus-aifc  mus-riff  mus-nist  mus-raw  mus-ircam  mus-aiff 
  mus-bicsf mus-soundfont mus-voc mus-svx mus-unsupported

mus-make-error (error-string)

make a new 'mus-error choice, returning its id

mus-sound-chans (filename)

number of channels in filename (settable)

mus-sound-close-input (fd)

close sound file

mus-sound-close-output (fd bytes)

close sound file and update its length indication, if any

mus-sound-comment (filename)

header comment, if any

mus-sound-data-format (filename)

data format (e.g. mus-bshort) (settable)

mus-sound-data-location (filename)

location of first sample (bytes) (settable)

mus-sound-datum-size (filename)

size in bytes of each sample in filename.

mus-sound-duration (filename)

duration of sound in seconds

mus-sound-forget (filename)

remove filename from the sound cache (presumably the file has been deleted or something).

mus-sound-frames (filename)

frames of sound according to header (can be incorrect)

mus-sound-header-type (filename)

header type (e.g. mus-aifc) (settable)

mus-sound-length (filename)

true file length (bytes)

mus-sound-loop-info (filename)

loop info. mark-loops in examp.scm uses this to place a mark at each loop point.

mus-sound-maxamp (filename)

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.

mus-sound-maxamp-exists? (filename)

#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.

mus-sound-open-input (filename)

open filename (a sound file) returning an integer ("fd" below)

mus-sound-open-output (filename srate chans data-format header-type comment)

create a new sound file with the indicated attributes, return "fd"

mus-sound-prune ()

remove all defunct (non-existent) files from the sound cache.

mus-sound-read (fd beg end chans sdata)

read data from sound file fd loading the data array from beg to end. sdata is a sound-data object that should be able to accommodate the read

mus-sound-reopen-output (filename chans data-format header-type data-location)

reopen filename, ready to continue output.

mus-sound-report-cache (file)

print the current sound header data table to the file given or stdout if none is specified.

mus-sound-samples (filename)

number of samples in sound according to header (can be incorrect) (settable)

mus-sound-seek-frame (fd frame)

move to frame in sound file fd

mus-sound-srate (filename)

sampling rate (settable)

mus-sound-type-specifier (filename)

original type indication of filename.

mus-sound-write (fd beg end chans sdata)

write data to sound file fd

mus-sound-write-date (filename)

sound's write date:

    :(strftime "%d-%b %H:%M %Z" (localtime (mus-sound-write-date "oboe.snd")))
    "18-Oct 06:56 PDT"

mus-audio-set-oss-buffers (num size)

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

See Sndlib 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.

The following function uses the sndlib functions to mimic the 'info' popup menu option (see examp.scm for a version that uses format):

(define info 
  (lambda (file)
    (string-append 
     file
     ": chans: " (number->string (mus-sound-chans file))
     ", srate: " (number->string (mus-sound-srate file))
     ", " (mus-header-type-name (mus-sound-header-type file))
     ", " (mus-data-format-name (mus-sound-data-format file))
     ", len: " (number->string 
                (/ (mus-sound-samples file) 
                   (* (mus-sound-chans file) (mus-sound-srate file)))))))

Sample-readers

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

A standard way to add something to the current data is:

   ...
   (sf (make-sample-reader start))
   ...
   (vct-map! out-data (lambda () (+ (read-sample sf) <new stuff>)))
   (free-sample-reader sf)
   (vct->channel out-data start)

This is equivalent to the clm call

  (outa (+ start i) <new-stuff>)

but is applied as an edit to the current state in Snd.

There is a similar set of functions giving access to the mix data. make-mix-sample-reader returns a mix reader for the desired mix, mix-sample-reader? returns #t if its argument in a mix sample reader, and read-mix-sample returns the next sample (before it is mixed into the output). Mixes can be collected into tracks, so there are also make-track-sample-reader, track-sample-reader?, and read-track-sample.

copy-sample-reader (obj)

return a copy of obj (any kind of sample-reader).

copy file: in Guile: copy-file, in Ruby: File.copy or File.syscopy
copy string: in Guile: string-copy
copy list: in Guile: list-copy or copy-tree
copy vct: vct-copy, vct->vector
copy mix: copy-mix, mix->vct
copy track: copy-track, track->vct
copy sample reader: copy-sample-reader
copy (clone) current sound edit state: clone-sound-as
copy channel data: channel->vct, or save-sound-as
copy selection data: selection->vct or save-selection
copy region data: region->vct, region->vct, or save-region
copy transform data: transform->vct
copy sound-data: sound-data->vct
copy vector: vector->vct
copy random state: Guile: copy-random-state, or use mus-rand-seed

free-sample-reader (obj)

release sample-reader obj (any kind of reader). You never need to call this function because the garbage collector handles the sample-reader object, but it doesn't hurt anything.

make-mix-sample-reader (mix beg)

create a mix-sample-reader reading mix starting (in the mix input) at beg which defaults to 0. See mix->vct in mix.scm.

make-region-sample-reader (start reg chn dir)

create a sample-reader reading region reg's channel chn. It is not safe to assume this reader will return zeros beyond the region boundaries.

make-sample-reader (start snd chn dir pos)

create a sample-reader reading snd's channel chn starting at sample start with initial read direction dir (1=forward, -1=backward). pos is the edit history position to read (defaults to current position). One use of pos is to get the difference between two edits:

(define snd-diff
  (lambda () ;assume mono, get diff between current state and previous
    (let* ((index (selected-sound))
           (edit-pos (edit-position index))
           (previous-edit (make-sample-reader 0 0 index 1 (1- edit-pos))))
      (lambda (x)
        (- x (read-sample previous-edit)) #f))))

(map-channel (snd-diff))

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

snd can also be a filename (a string); in this way a sample-reader can read external sounds without going to the trouble of loading them into Snd.

(define reader (make-sample-reader 100 "oboe.snd")).

make-track-sample-reader (track chn beg)

create a track-sample-reader reading track. beg is the starting point of the reader within the track.

mix-sample-reader? (obj)

#t if obj is a mix-sample-reader.

next-sample (obj)

return next sample (reading forward) read by sample-reader obj.

previous-sample (obj)

return previous sample in stream read by sample-reader obj.

read-mix-sample (obj)

return next sample read by mix-sample-reader obj.

read-region-sample (obj)

return next sample read by region-sample-reader obj.

(define* (region->vct reg #:optional (chn 0))
  (if (region? reg)
      (if (< chn (region-chans reg))
	  (let* ((reader (make-region-sample-reader 0 reg chn))
		 (len (region-frames reg))
		 (data (make-vct len)))
	    (do ((i 0 (1+ i)))
		((= i len) data)
	      (vct-set! data i (reader))))
	  (throw 'no-such-channel (list "region->vct" reg chn)))
      (throw 'no-such-region (list "region->vct" reg))))

read-sample (obj)

return next sample (reading in the direction set by make-sample-reader) from sample-reader obj.

read-track-sample (obj)

return next sample read by track-sample-reader obj.

region-sample-reader? (obj)

#t if obj is a region sample-reader.

sample-reader-at-end? (obj)

#t if sample-reader 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. See scan-again and find-zero.

sample-reader-home (obj)

if obj is a sound sample reader, return a list with the sound index and channel number associated with obj. If it is a mix reader, return the mix's id. If it is a track reader, return a list with the track id and channel number.

sample-reader-position (obj)

current (sample-wise) location of sample-reader obj (any kind of reader). See scan-again.

sample-reader? (obj)

#t if obj is a sample-reader.

track-sample-reader? (obj)

#t if obj is a track-sample-reader.

The read-sample functions can be omitted: (reader) is the same as (read-sample reader).

There are two Snd-specific CLM-style generators that redirect CLM instrument input (via in-any, ina, etc) to Snd data, snd->sample and xen->sample. Instruments that use ina or file->sample to read *reverb* or some similar stream can be redirected elsewhere by these two functions. After implementing these, I realized the CLM instruments could just as easily use temporary files; I'm not sure these have any real use after all.

`make-snd->sample (snd edpos)`
	create a Snd data reader for CLM's in-any, file->sample, etc.
`make-xen->sample (reader)`
	create a function-based input method for CLM's input generators. reader is a function of two arguments, the sample and the channel (much as in ina).
`snd->sample (gen frame chan)`
	Return the next sample from the data accessed by gen, similar to file->sample. If reverb is a snd->sample generator, for example, ina and file->sample actually call snd->sample.
`snd->sample? (obj)`
	#t if obj is a snd->sample generator.
`xen->sample (gen frame chan)`
	Similar to snd->sample, but the accessor is a xen->sample generator.
`xen->sample? (obj)`
	#t if obj is a xen->sample generator.

Marks

A mark is an object that refers to a particular sample. Each mark has an associated sample number (mark-sample), name (mark-name), sync value (mark-sync), and a globally unique id number (returned by find-mark or add-mark). See Marks for an overview and key bindings associated with marks.

add-mark (sample snd chn)

add mark at sample, returning mark id. If sample is out-of-range, add-mark throws 'no-such-sample.

delete-mark (id)

delete mark id (- C-m).

delete-marks (snd chn)

delete all marks in snd's channel chn.

draw-mark-hook (id)

called before a mark is drawn (discussed in the Hooks section).

find-mark (samp snd chn edpos)

return identifier of the mark at sample samp or #f if none. This identifier is used in calls such as mark-sample. Since marks can move around during editing, a unique 'tag' is needed to refer to a particular mark. samp can also be a string; in this case find-mark looks for a mark of that name. mark-name->id in marks.scm finds a named mark in any channel (a global version of find-mark).

mark-click-hook (id)

called when a mark is clicked (discussed in the Hooks section).

mark-color

color of mark indicator (default: red).

mark-context

graphics context to use to draw a mark (XOR mode).

mark-home (id)

a list with the sound index and channel that hold mark id. mark-home provides a way to go from a mark to its sound and channel; the inverse function is marks.

mark-hook (id snd chn reason)

called when a mark is added, deleted, moved (discussed in the Hooks section).

mark-name (id)

name of mark id.

(define* (add-named-mark samp name #:optional snd chn)
  (let ((m (add-mark samp snd chn)))
    (set! (mark-name m) name)
    m))

mark-sample (id pos)

sample (number) marked by mark id at edit history position pos; also (set! (mark-sample id) samp). 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.

mark-sync (id)

mark id's sync value (default is 0). The sync value is very similar to the mix track number or the sound sync field; it 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 syncd-marks; to find an unused sync value use mark-sync-max.

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 uses the mark-clicked-hook instead; you type (start-sync), then click the set of marks to sync, then (stop-sync).

(define mark-sync-number 0)
(define (start-sync) (set! mark-sync-number (+ (mark-sync-max) 1)))
(define (stop-sync) (set! mark-sync-number 0))
(define (click-to-sync id) (set! (mark-sync id) mark-sync-number) #f)
(add-hook! mark-click-hook click-to-sync)

Now control-click and drag one of them, and all move together deleting data, or inserting zeros; or click the "play" triangle, and all play together starting from the respective marks (which need not be in separate channels).

mark-sync-max ()

max mark sync value seen so far (intended as a way to get a unique sync value).

marks (snd chn pos)

list of mark ids in snd's channel chn at edit history position pos. If chn and pos 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.

(define (how-many-marks-in-channel snd chn)
  (length (marks snd chn)))

(define (how-many-marks-in-sound snd)
  (apply + (map length (marks snd))))

(define (how-many-marks)
  (apply + (map how-many-marks-in-sound (sounds))))

marks without any argument, or with just a sound index returns a list of lists; each inner list is the list of current marks (ids) active in that channel, ordered by sample number. If the channel argument is specified, marks returns just the list of mark ids. If the edit history position is given, the list of ids reflects the mark list at that time in the edit history. See describe-marks in marks.scm.

mark? (id)

#t if mark id is active (that is, present in an active channel).

save-marks (snd filename)

save snd's marks, writing a Scheme or Ruby source file named either filename or <snd's file-name>.marks; return the file name or #f if no marks.

show-marks

#t if marks are being (or to be) displayed.

syncd-marks (sync)

a list of marks (the mark id's) that share the mark-sync value sync.

(define (move-syncd-marks sync diff)
  (for-each 
    (lambda (m) 
      (set! (mark-sample m) (+ (mark-sample m) diff))) 
    (syncd-marks sync)))

See marks.scm for more examples including:

global find-mark: mark-name->id
mark history: describe-mark
synchronize marks by inserting silences: syncup
squeeze selection between marks: fit-selection-between-marks
insert silence before marks: pad-marks
move syncd marks: move-syncd-marks
play starting from syncd marks: play-syncd-marks
evaluate function between marks: eval-between-marks
place marks at selection start and end: snap-marks
define selection via marks: define-selection-via-marks
force dragged mark to land on a beat: snap-mark-to-beat
loop continuously between the two specified marks: loop-between-marks
split sound into separate files based on mark placement: mark-explode
mark property lists: mark-property
save mark properties in saved state file: save-mark-properties
show mark properties upon click: mark-click-info

Other examples can be found in Dave Phillips' dlp/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).

Mixes and Tracks

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 with-mix-tags). If the mix operation is tagged, you can then operate on that data through a number of functions, the Mix Dialog, various hooks, and various mouse-related actions. These mixes can be grouped into "tracks", which have a very similar set of functions.

Mixes

A mix is an object that represents a channel of a sound mix. Each mix object has a unique identifier called its id that identifies it in the following functions. A track is a list of mixes that are treated in many ways as a single big mix. Say we have a mix whose id is 123:

>(mix-chans 123)
1
>(set! (mix-amp 123 0) .5)
.5

This sets mix 123's channel 0 amplitude scaler to .5.

`copy-mix (mix beg)`
	copy mix, placing the copy at beg which defaults to the copied mix's position. The new mix's track is set to 0.
`delete-mix (mix)`
	delete mix (set amps to 0.0).
`mix (file samp in-chan snd chn with-mix-tags auto-delete (track 0))`
	mix file's channel in-chan starting at samp in snd's channel chn. if only the file argument is given, this is equivalent to the File menu's Mix option; the mix start sample in this case depends on the cursor location. mix returns the id of the first channel's mix (subsequent channels simply increment this number). If sync is off and in-chan is not #t, only the first channel is mixed. If with-mix-tags is #f (default is #t), the data is simply mixed without creating any mix tags. track is the newly created mix's track number.
`mixes (snd chn pos)`
	a list of currently active mixes in snd's channel chn at history pos.
`mix-amp (mix chan)`
	amplitude of mix's channel chan.
`mix-amp-env (mix chan)`
	amplitude envelope of mix's channel chan (a list of breakpoints). To reset this to its default (null) state, use #f. `(set! (mix-amp-env 0 0) '(0 0 1 1))` sets mix 0's 0-chan envelope to a ramp.
`mix-chans (mix)`
	chans in mix.
`mix-color()`
	color of mix waveforms (defaults to dark-gray). The set form, `(set! (mix-color) ...)`, has an optional second argument; if you want to set just a particular mix's color, give the id of the mix as that argument: `(set! (mix-color) red)` sets all mix waveforms to red; but `(set! (mix-color 3) red)` sets only mix 3's waveform to red.
`mix-frames (mix)`
	mix's length in samples (not settable).
`mix-home (mix)`
	a list of the sound index and channel number affected by mix.
`mix-inverted? (mix)`
	#t if mix should invert track amp-env values (for panning).
`mix-locked? (mix)`
	#t if mix is locked. A mix is automatically locked (i.e. made immovable) if an edit operation affects some portion of the data that the mix also affects. For example, if you delete a portion of a sound that has actively mixed data, the associated mix tag goes away until you undo that deletion.
`mix-position (mix)`
	position (a sample number) of mix.
`mix-region (samp reg snd chn track)`
	Mix in region reg at sample samp (defaulting to the cursor sample), in snd's channel chn. mix-region returns the id of the first channel's mix (subsequent channels simply increment this number). See also pan-mix-region in mix.scm.
`mix-selection (beg snd chn)`
	mix (add) selection starting at beg in snd's channel chn. Return new mix id. See also pan-mix-selection in mix.scm.
`mix-speed (mix)`
	speed (resampling ratio) of mix; 1.0 (default) means no resampling; 2.0 reads the mix data twice as fast.
`mix-tag-height ()`
	mix tag height in pixels (default: 14)
`mix-tag-position (mix)`
	tagposition (tag) position (within the mix) of mix; a sample number.
`mix-tag-width ()`
	mix tag width in pixels (default: 6)
`mix-tag-y (mix)`
	tag y offset in graph of mix (default 0). The x offset of the tag is determined by mix-tag-position. To place all the mixes in track 1 at the same height above the waveform: `(for-each (lambda (n) (set! (mix-tag-y n) 20)) (track 1))`.
`mix-track (mix)`
	mix track (0 = none). A "track" is a list of associated mixes.
`mix-vct (vct beg snd chn with-mix-tags origin track)`
	mix the contents of vct into snd's channel chn starting at frame beg. Return the id of the new mix, or -1 if some error occurred. If with-mix-tags is #f (default is #t), the data is simply mixed without creating any mix tags, and without returning a mix id. If track is the id of an existing track, the subsequent mix is placed in that track. See also pan-mix-vct in mix.scm.
`mix-waveform-height()`
	Max height (pixels) of mix waveforms; default is 20 (see show-mix-waveforms).
`mix? (id)`
	#t if id is an active mix.
`play-mix (mix beg)`
	play mix mix. 'beg' is where to start playing within the mix. This function does not return until the play is complete or interrupted (it is similar to play-and-wait, rather than play).
`with-mix-tags()`
	If #f (default #t), automatically lock each new mix; the default is to place a tag above each mix so that it can be easily moved around.

mix sound file: mix or drag-and-drop it where you want it mixed
mix channel: see mix-channel in extensions.scm
mix region: mix-region
mix selection: mix-selection
mix vct: mix-vct
enveloped mix: see enveloped-mix in extensions.scm
read mix samples: make-mix-sample-reader
mix data maxamp: mix-maxamp
mix data to vct: mix->vct
save mix data in file: save-mix
mix property list: mix-property in mix.scm
pan mono sound into stereo: see place-sound in examp.scm
pan mix file with envelope: pan-mix
pan mix selection: pan-mix-selection
pan mix region: pan-mix-region
pan mix vct: pan-mix-vct
the mix dialog: Mix Dialog
use pan-mix in File:Mix dialog: use-pan-mix-in-mix-menu
mix menu: see dlp/mix-menu.scm
cross-fade in frequency: cross-fade and dissolve-fade in fade.scm
zipper cross-fade: zipper.scm
snap mix to beat after drag: snap-mix-to-beat
delete all mixes: delete-all-mixes

Tracks

A track is a list of mixes, each member mix having its track set to the track id. The make-track function takes the initial mixes, returning the track id (an integer). The track function returns the list of mixes that are members of the given track. The rest of the track functions take the track id as their initial argument. A track has much the same structure as a mix: an amplitude, speed, amplitude envelope, track, position, and so on. If its track field is not 0, the entire track is a member of the given track, just as a mix would be. Tracks provide a mechanism to group mixes, for panning, global envelopes, and so on. If a mix is dragged, and it is part of a track, all the mixes in that track move with it. Tracks can be nested indefinitely, so multi-level phrase operations are relatively easy.

`copy-track (track beg)`
	copy track, placing the copy at beg which defaults to the copied track's position. The new track's track is set to 0.
`delete-track (track-id)`
	Delete track track-id (set its amp to 0.0).
`free-track (track-id)`
	Free track track-id; this frees the memory associated with the track and is not undoable. To free all tracks: `(for-each free-track (tracks))`.
`lock-track (track-id)`
	Lock track id (lock all its associated mixes). One reason to lock a track would be to preserve its overall amp-env despite some subsequent editing that changes the nominal track length.
`make-track (mix-ids...)`
	Create new track, returning its id. You can add a mix to the track subsequently by setting mix-track. `(make-track 1 3)` creates a new track with mixes 1 and 3. A mix can be a member (directly) of only one track, so if its track field is already set, and it is included as an argument to make-track, the previous setting is cancelled. If the previous track had an amplitude envelope, this can cause its remaining mixes to be re-enveloped.
`play-track (track-id chn beg)`
	play track track. If chn is #t, play all associated mixes, even if in different sounds. 'beg' is where to start playing within the track. This function does not return until the play is complete or interrupted (it is similar to play-and-wait, rather than play).
`track (track-id chn)`
	Return a list of the mixes currently in track track-id.
`tracks (track-id)`
	Return a list of the current tracks that have active mixes. Old, empty tracks are not currently garbage collected; to free one, use free-track.
`track? (track-id)`
	Return #t if track-id refers to an active (not deleted) track.
`track-amp (track-id)`
	Track amp.
`track-amp-env (track-id)`
	Track amp env; this is a list of breakpoint pairs, not a CLM env generator. The amplitude envelope is applied over the entire track; each mix's resultant amp env is the result of multiplying its env (if any) by the portion of the track env that happens to fall over it. Use #f to reset it to the default (null) envelope. Anything that changes the track's bounds causes the track envelope to be reapplied; there are many ways this can happen implicitly: set mix-track, mix-position, mix-speed (of a constituent mix), track-position, track-speed, and track-tempo; even make-track if it steals away one of our member mixes. If a mix in a track has set the mix-inverted? flag, the first track envelope in its track chain is inverted, thereby interpreting the track envelope as a panning control.
`track-chans (track-id)`
	chans associated with track track-id. Each such channel has at least one active mix that is a member of the given track.
`track-color (track-id)`
	The track-color refers to the color of the mix waveform (the thing displayed to the right of the tag). :(define hi (make-track 0 1)) #<unspecified> :(set! (track-color 1) (make-color 0 0 1)) (#<color: (0.00 0.00 1.00)> #<color: (0.00 0.00 1.00)>)
`track-frames (track-id chn)`
	Track frames (length in samples).
`track-position (track-id chn)`
	Track position (minimum member mix position). If you set track-position, all the member mixes are moved by the same amount to make the minimum mix position coincide with the new track-position. If you include the channel number when setting the track-position, only that channel's mixes that are members of the track are moved. :(track-position 1) 10748 :(mix-position 0) 10748 :(mix-position 1) 23287 :(set! (track-position 1) 1500) 1500 :(mix-position 0) 1500 :(mix-position 1) 14039
`track-speed (track-id)`
	Track speed. This affects the resampling of each mix, not the speed at which the mixes occur (the latter is controlled by track-tempo).
`track-tempo (track-id)`
	Track tempo. This affects the spacing between mixes; a higher track-tempo corresponds to tighter spacing between mixes.
`track-track (track-id)`
	Track track. Tracks can be grouped within other tracks and so on.

place track in vct: track->vct
place track in file: save-track
filter track data: filter-track
transpose track: transpose-track
change track tempo: retempo-track
maxamp of track data: track-maxamp
track property list: track-property
reverse track: reverse-track
the track dialog: The Mix Dialog
various other dialogs for track operations: dlp/mix-menu.scm and dlp/track-colors.scm

Regions and Selections

A region is a saved portion of sound data. There is a dialog, the View:Region browser, to inspect 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. Each region has a unique id returned by make-region and shown beside the region name in the Region Browser. Most of the region arguments default to the current region (the top of the regions stack).

forget-region (reg)

"forget" (delete) region reg, removing it from the region stack. To delete all regions, (for-each forget-region (regions)). I called this forget-region because delete-region seemed ambiguous, especially given delete-selection.

insert-region (beg reg snd chn)

insert region reg at sample beg in snd's channel chn. The following function uses insert-region (and other region functions) to rotate the samples in a channel:

(define* (rotate-channel #:optional (samps 1) snd chn)
  (let* ((ind (or snd (selected-sound) (car (sounds))))
	 (chan (or chn (selected-channel) 0)))
    (let ((reg (make-region 0 (1- samps) ind chan)))
      (as-one-edit
       (lambda ()
	 (delete-samples 0 samps ind chan)
	 (insert-region (frames ind chan) reg)))
      (forget-region reg))))

make-region (beg end snd chn)

create a new region spanning samples beg to end in snd's channel chn. return region's id. If no arguments are given, the selection is used. If chn is #t, all chans are included, taking the snd sync field into account if it's not 0.

make-region-sample-reader (start reg chn dir)

create a sample-reader reading region reg's channel chn.

mix-region (samp reg snd chn track)

Mix in region reg at sample samp (defaulting to the cursor sample), in snd's channel chn. mix-region returns the id of the first channel's mix (subsequent channels simply increment this number). See also pan-mix-region in mix.scm.

play-region (reg wait stop-func)

play region reg; if wait is #t, play to the end before returning. (See play.scm).

region-chans (reg)

number of channels in region reg.

region-frames (reg chan)

number of samples (per channel) in region reg.

region-graph-style (style)

graph drawing choice for the region dialog's graph.

region-maxamp (reg)

maximum amplitude of region reg.

region-position (reg chan)

Begin time of region reg's channel chan in the original sound.

region-sample (samp reg chn)

value of sample samp in region reg in channel chn.

region->vct (samp samps reg chn v)

return a vct containing samps samples starting at samp in region reg's channel chn. If v (a vct) is provided, it is filled, rather than creating a new vct.

(define (region-rms n)
  (let* ((data (region->vct 0 0 n)) ; len=0 => entire region
	 (len (vct-length data)))
    (sqrt (/ (dot-product data data len) len))))

region-srate (reg)

original (nominal) sampling rate of region reg.

regions ()

list of ids of regions currently active. The most recently created region is (car (regions)). (map region-frames (regions)) returns a list of region lengths.

region? (reg)

#t if region reg exists. There is a limit to how many regions Snd tries to keep track of (max-regions); when necessary, the least-recently created region is deleted.

save-region (reg &optional-key :file (:header-type mus-next) :data-format :comment)

save region reg in file in data format (default is mus-bshort), header type (default is mus-next), and comment. Return the output filename. The arguments after reg are optional-key args (that is, they are normal keyword arguments, but the keywords are optional). The following calls are equivalent:

(save-region 2 "reg0.snd")
(save-region 2 :file "reg0.snd" :header-type mus-next)
(save-region 2 "reg0.snd" mus-next mus-bfloat "a comment")
(save-region 2 :file "reg0.snd" :comment "a comment" :data-format mus-bfloat)

Max length of region list: max-regions
Whether selection creates a region: selection-creates-region
To play region repeatedly: play-region-forever
Start region browser from Scheme: view-regions-dialog
All about regions: regions
The region dialog: region browser
Region rms amp: region-rms
region-play-list and region-play-sequence in examp.scm

convolve-selection-with (file amp)

convolve the selection with file.

delete-selection ()

delete the selection.

env-selection (envelope env-base)

apply envelope to the selection. envelope can also be a CLM env generator (in this case, env-base is ignored).

filter-selection (env order truncate)

apply 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 filter-sound). If truncate is #t (its default), the filter output is truncated at the selection end. If #f, the extra output (order samples) is mixed into the stuff following the selection.

insert-selection (beg snd chn)

insert selection starting at beg in snd's channel chn.

mix-selection (beg snd chn)

mix (add) selection starting at beg in snd's channel chn. Return new mix id. See also pan-mix-selection in mix.scm.

play-selection (wait pos stop-proc)

play the selection. pos sets the edit position. If wait is #t, the function does not return until the play has completed. If stop-proc is a procedure of one argument, it is called when the play process stops. The argument provides the reason the play is stopping; it will be 0 if the play completed normally.

reverse-selection ()

reverse the selection.

save-selection (&optional-key :file (:header-type mus-next) :data-format :srate :comment :channel)

save the selection in file. If channel is given, save only that channel. See popup.scm for an example.

(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 (inexact->exact (* (srate) dur)))
	(len (frames))
        (old-sync (sync)))
    (set! (sync) 1) ; save all chans
    (do ((i 0 (+ i hop))
	 (j 0 (1+ j)))
	((>= i len))
      (make-selection i (+ i hop)) ; in extensions.scm
      (save-selection (string-append base "." (number->string j))))
    (set! (sync) old-sync)))

(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 (selected-sound) (car (sounds)))))
    (if (sound? snd)
	(begin
	  (for-each
	   (lambda (chan)
	     (set! (selection-member? snd chan) #t)
	     (set! (selection-position snd chan) 0)
	     (set! (selection-frames snd chan) (frames snd chan)))
	   chans)
	  (save-selection "test.snd")))))

scale-selection-by (scalers)

scale the selection by scalers which can be either a float, a list of floats, or a vct. In a multi-channel selection, each member of the vct or list is applied to the next channel in the selection. (scale-selection-by '(0.0 2.0)) scales the first channel by 0.0, the second (if any) by 2.0. (scale-selection-by 2.0) scales all channels by 2.0. Normally the order of channels follows the order of the sound indices.

scale-selection-to (norms)

normalize the selection to norms which can be either a float, a list of floats, or a vct.

select-all (snd chn)

select all samples in snd's channel chn. If a region is created, return the region's id.

selection-chans ()

selection channels.

selection-frames (snd chn)

selection length in samples. You can set this to move the selection end point.

selection-maxamp (snd chn)

maximum amplitude of selection in the given channel.

selection-member? (snd chn)

#t if snd's chn is member of active selection. (This is settable). See make-selection in extensions.scm. If snd is #t and the new value is #f, the entire selection is deactivated.

selection-position (snd chn)

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 (selection-frames) changes to reflect the moved origin. See make-selection in extensions.scm.

selection-srate ()

selection srate. There's some arbitrariness in this if the sounds that make up the selection have different sampling rates.

selection? ()

#t if there is a selection.

smooth-selection ()

apply a smoothing function to the selection. This produces a sinusoid between the end points.

src-selection (num-or-env base)

apply sampling rate conversion to the selection; this is the same as src-sound but applied to selection.

color of selected portion: selection-color
set whether creating a selection creates a region: selection-creates-region
fft graph refers to the selection: show-selection-transform
hook called when selection stops playing: stop-playing-selection-hook
swap chans in selected portion: swap-selection-channels
replace portion with selection: replace-with-selection
select portion via function: make-selection
evaluate func on each sample of selection: eval-over-selection (map-selection in effect)
selection members as list of lists of sound indices and channels: selection-members
rms of selection data: selection-rms
delete selection and smooth the splice: delete-selection-and-smooth
select portion between two marks: define-selection-via-marks
place marks at selection start and end: snap-marks
squeeze selection between marks: fit-selection-between-marks
add context-sensitive popup menu specific to selection: add-selection-popup
delete selection and write it to a file: cut-selection->new
append selection: append-selection
write selection to a file: selection->new
notch filter selection: notch-selection
undo select-all.: deselect-all
hook called when selection created or deleted.: selection-changed-hook

The selected portion can be chosen, independent of any region, by setting selection-position and selection-frames. It's easy to extend the notion of a selection to an arbitrary list of sound portions:

(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
  (as-one-edit (lambda () (for-each func (cdr section)))))

;; an example that scales each member of the section by .5
(section-for-each 
 (lambda (sect)
   (apply scale-channel (append (list .5) sect)))
 (make-section (list 0 10000 0 0) (list 30000 10000 0 0)))

Sounds and channels

This is the heart of Snd; we've waded through all the ancillary junk, and we've finally reached the functions that actually edit sounds! Most of these functions take both a sound index 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; this possibility is identified below by marking the arguments as snd or snd chn; in such a case, if the snd argument is #t, the channel defaults to the selected channel. In cases where it makes sense, if the snd argument is omitted, the reference is to the global default value. So, (set! (amp-control-bounds) '(0.0 2.0)) sets the global amp control (slider) bounds to be between 0.0 and 2.0, whereas (set! (amp-control-bounds snd) '(0.0 2.0)) sets it only for the sound referred to by 'snd'.

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 current-edit-position (the default), or a function of two arguments, the sound index 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.

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 #f signals application to all channels or just the selected one, whether the sync 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 index, channel number, and edit position, possibly preceded by one argument, and sometimes followed by an edit history name or 'ring time' (overlap). The sync 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:

convolve-with file amp s c e clm-channel convolve-gen beg dur s c e env-sound env beg dur base s c e env-channel env beg dur s c e filter-sound env order s c e clm-channel clm-filter-gen beg dur s c e overlap or filter-channel env order beg dur s c e trunc insert-silence beg dur s c pad-channel beg dur s c e insert-sound file beg filechn s c e insert-channel filedat beg dur s c e mix file beg filechn s c with-tags mix-channel filedat beg dur s c e play beg s c sync end e play-channel beg dur s c e redo edits s c redo-channel edits s c reverse-sound s c e reverse-channel beg dur s c e scale-by scls s c scale-channel scl beg dur s c e scale-to scls s c normalize-channel norm beg dur s c e set-samples beg dur data s c trunc origin fchan vct->channel vct beg dur s c e smooth-sound beg dur s c smooth-channel beg dur s c e src-sound num base s c e src-channel ratio-or-env beg dur s c e undo edits s c undo-channel edits s c apply-ladspa reader dat dur origin ladspa-channel dat beg dur s c e

Another case that might deserve "regularization" is make-sample-reader which confusingly interpolates the direction argument between the channel and edit-position:
 (define* (read-channel #:optional (beg 0) snd chn edpos (direction 1))
   (make-sample-reader beg snd chn direction edpos))

add-player (player start end pos stop-proc out-chan)

add player to the play-list (see make-player). If pos is given, play at that edit position. See play-with-envs in enved.scm, play-syncd-marks in marks.scm, or start-dac in play.scm. If stop-proc is a procedure of one argument, it is called when the play process stops. The argument provides the reason the play is stopping; it will be 0 if the play completed normally. The out-chan argument is the audio output channel to send the data to; it defaults to the channel number of the player's channel in the containing sound (that is, the default is to send channel 1 data to channel 1 of the DAC, and so on).

(define* (play-mono-as-stereo #:optional snd)
  "(play-mono-as-stereo snd) sends the channel 0 data in 'snd' to all available DAC channels."
  (let ((vals (make-vct 3))
	(end (frames snd)))
    (mus-audio-mixer-read mus-audio-default mus-audio-channel 3 vals)
    (let ((chans (max (inexact-<exact (vct-ref vals 0)) 2)))       ; assume stereo is out there
      (do ((chan 0 (1+ chan)))                                      ; get a player for each output channel
	  ((= chan chans))
	(let ((player (make-player snd 0)))
	  (add-player player 0 end current-edit-position #f chan)))
      (start-playing chans (srate snd)))))

axis-info (snd chn grf)

return a list describing the specified axis: '(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). This might be useful if you're drawing arbitrary figures in a graph. grf defaults to time-graph; the other choices are transform-graph and lisp-graph. The procedure x->position could be defined as:

(define (x->position-1 x snd chn)
  (let* ((axinfo (axis-info snd chn time-graph))
	 (x0 (list-ref axinfo 2))
	 (x1 (list-ref axinfo 4))
	 (axis-left (list-ref axinfo 10))
	 (axis-right (list-ref axinfo 12)))
    (inexact->exact 
     (+ axis-left
	(* (- x x0) 
	   (/ (- axis-right axis-left)
	      (- x1 x0)))))))

x0 is the time in seconds corresponding to the left-sample (the left edge of the graph). Similarly y0 is the lower y axis limit as a sample value (i.e. -1.0). x-max is the sound's duration in seconds (x-min is always 0.0). The "positions" are pixel values, in drawing area coordinates; these give the position of the graph in the drawing area. y-offset refers to "united" graphs where several channels share one drawing area. You can use it to translate mouse coordinates to channel number in that situation. See draw-smpte-label in snd-motif.scm, or make-current-window-display in draw.scm.

beats-per-minute (snd chn)

The x axis labelling of the time domain waveform can be in beats (x-axis-style = x-axis-in-beats); this variable sets the number of beats per minute. The default is 60.0, making it the same as x-axis-in-seconds. See snap-mark-to-beat, or snap-mix-to-beat.

bomb (snd on)

display bomb icon in snd's minibuffer. Set on to #f to erase 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.

(define show-bomb 
  (lambda (n speed) 
    (if (> n 0) 
	(begin 
	  (bomb) 
	  (in speed (lambda () (show-bomb (- n 1) speed))))
	(bomb 0 #f))))

(show-bomb 20 200)

channel-amp-envs (file chan size peak-file-func work-proc-func)

This procedure returns two vcts of length 'size' containing y vals (min and max) of file's channel chan's amp envs. 'peak-file-func' if any is used to get the name of the associated peak-env-info 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 index (an integer), pts is an edit-position, and the current amp envs (if any) are returned. peak-file-func's args are the file and the channel. If it returns a string, that is treated as the filename to read to get the peak info. work-proc-func's args are the filename, the channel and the current peak. make-sound-icon in make-sound-box in snd-motif.scm uses this function to draw the little thumbnail graph for each sound icon.

channel-data (snd chn)

channel-data provides very low-level access to the data currently in the given channel's sample buffers. It is used by the variable-display mechanism to show graphs of variable values (normally in an instrument). channel-data only works with sound indices returned by make-variable-display. See make-variable-display in snd-motif.scm.

channel-properties (snd chn)

A property list associated with the given channel. It is set to '() at the time a sound is opened. The accessor channel-property is provided in extensions.scm. See enved.scm (which uses the property 'enved-envelope), or draw.scm (the properties 'colored-samples and 'insert-envelope).

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 assoc can be used to search the list for a given key's value; a new key-value pair can be added with:

(cons (cons key value) a-list)

In Common Lisp, property lists have other properties, so to speak, but channel-properties (and sound-properties) can be handled in any way you like. See channel-sync in extensions.scm for a brief example.

channel-style (snd)

The state of the 'unite' button in multi-channel files. Values are channels-separate, channels-combined, and channels-superimposed. The following code sets the 'unite' button if the current sound has more than 4 channels:

(add-hook! after-open-hook 
  (lambda (snd)
    (if (> (chans snd) 4)
        (set! (channel-style snd) channels-combined))))

channel->vct (beg dur snd chn edpos)

return vct with the specified data.

(define* (selection->vct #:optional snd chn)
  (if (selection-member? snd chn)
      (channel->vct (selection-position snd chn)
		    (selection-frames snd chn)
		    snd chn)
      (if (selection?)
          (throw 'no-such-channel 
                 (list "selection->vct"
     	               (format #f "snd ~D channel ~D is not a member of the selection" snd chn)))
	  (throw 'no-active-selection (list "selection->vct")))))

the control panel

The control panel makes it easy to try out various quick effects without editing anything. You can change volume ('amp'), pitch ('speed'), tempo ('expand'), reverb amount ('reverb'), simulated room size ('reverb len'), brightness ('contrast'), and dullness ('filter'). To treat a current setting as an edit operation, call apply-controls. For more on the effects themselves (and a pretty picture!), see the discussion in snd.html.

The control panel normally processes samples as follows: if the sampling rate conversion is on (the 'Speed' control is not 1.0), it applies srate conversion to the incoming sample; the next stage is the expansion function, if the 'Expand' toggle button is set; this value is passed next to the Contrast function, if it is running, and then the result is scaled by the Amp slider's value. The filter is run next, if it's on, and finally the sample is scaled by the reverb slider and passed to the reverb, if any, which adds its result to the sample; the final result is sent to the speakers. The control panel procedures are:

amp-control (snd chn)

The current amp value. It is possible to use these controls (in "real-time") in your own functions. See amprt in examp.scm for a simple 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 apply-controls and playback.

amp-control-bounds (snd)

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, Track, and Record dialogs.

apply-controls (snd target beg dur)

Apply the current control panel state as an edit. target can be 0=sound, 1=channel, 2=selection. beg sets where in samples the apply starts: (apply-controls 0 0 (mark-sample 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:

(define expnd 
  (lambda (amt) 
    (set! (expand-control?) #t) 
    (set! (expand-control) amt) 
    (apply-controls)))

For many examples see new-effects.scm.

controls->channel (settings beg dur snd chn edpos origin)

sets up snd'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:

(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))

where each entry can also be #f or an empty list.

contrast-control (snd)

The contrast amount. The contrast-enhancement 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).

contrast-control-amp (snd)

The contrast-control-amp (a prescaler on the contrast-enhancement to get the full effect of the compander).

contrast-control-bounds (snd)

The contrast-control min and max amounts as a list. The default is (list 0.0 10.0).

contrast-control? (snd)

#t if the contrast button is set (i.e. the contrast compander is active).

expand-control (snd)

The expansion amount. This sets the ratio between the output and input grain spacing. If it is greater than 1.0, the result is longer.

expand-control-bounds (snd)

The expand-control min and max amounts as a list. The default is (list 0.001 20.0).

expand-control-hop (snd)

The expansion hop amount in seconds (the distance between successive grains).

expand-control-jitter (snd)

The expansion grain timing jitter. This defaults to .1; if you set it to too small a number (0.0 for example), you'll probably notice (unwanted) notch-filter effects.

expand-control-length (snd)

The expansion segment (grain) length in seconds. The longer the grain, the more reverberated or slurred the effect.

expand-control-ramp (snd)

The expansion ramp amount (between 0 and .5). This affects the smoothness of the grain overlaps -- .001 gives a rattling effect.

expand-control? (snd)

#t if the expand button is set (i.e. the expansion effect is active).

filter-control-coeffs (snd)

The filter coefficients (read-only currently). It is a vct suitable for use with the filter generator or with filter-sound.

filter-control-envelope (snd)

The filter (frequency reponse) envelope (a list of breakpoints).

filter-control-in-dB (snd)

The filter dB button. If #t, the filter (frequency) envelope graph is displayed in dB.

filter-control-in-hz (snd)

If #t, filter frequency response envelope (sound control panel) x axis is in Hz, otherwise 0 to 1.0 (where 1.0 corresponds to srate/2).

filter-control-order (snd)

The filter 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.

filter-control-waveform-color

The filter frequency response waveform color.

filter-control? (snd)

#t if the filter button is set (i.e. the filter is active).

reset-controls (snd)

Set all the controls to their default state.

restore-controls (snd)

Set all the controls to the last saved state.

reverb-control-decay (snd)

The length (seconds) of the reverberation after the sound has finished (default: 1.0).

reverb-control-feedback (snd)

The reverb feedback coefficient. The more feedback, the happier Elvis.

reverb-control-length (snd)

The reverb delay line length scaler. Longer reverb simulates, to some extent, a bigger hall.

reverb-control-length-bounds (snd)

The reverb-control-length min and max amounts as a list. The default is (list 0.0 5.0).

reverb-control-lowpass (snd)

The reverb low pass filter coefficient. (This filter is in the feedback loop).

reverb-control-scale (snd)

The reverb amount (the amount of the direct signal sent to the reverb). You can never have enough reverb.

reverb-control-scale-bounds (snd)

The reverb-control-scale min and max amounts as a list. The default is (list 0.0 4.0).

reverb-control? (snd)

#t if the reverb button is set (i.e. the reverberator is active).

save-controls (snd)

Remember the current control settings for a later restore-controls. In new-effects.scm, the effects that use the control panel internally (post-expsrc-dialog, for example) can save and restore the current state via:

(save-controls)
(reset-controls)
;;; now set the ones that are of interest for the current effect
(apply-controls)
(restore-controls)

show-controls (snd)

#t if snd's control panel is currently open. If set to #t, snd's control panel is opened, else it is closed.

speed-control (snd)

current speed. A speed of 2 plays the sound twice as fast.

speed-control-bounds (snd)

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 Track.

speed-control-style (snd)

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).

speed-control-tones (snd)

The number of tones per octave in the speed-control-as-semitone speed style (default: 12).

make-hidden-controls-dialog in snd-motif.scm sets up 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 (list-ref (sound-widgets) 2). You can add or remove controls; add-amp-controls in snd-motif.scm sets up a separate amp slider for each channel in the current sound. disable-control-panel disables (hides) the entire panel.

Edit Lists

An edit list (in other editors this is called an "edit decision list", I guess because it sounds decisive) describes the edit history of a channel. When, for example, you type C-d, nothing actually happens to any data, despite the fact that the graph no longer shows that sample, it's omitted when you play the channel, and so on. Instead, a descriptor is appended to the edit history of that channel saying "sample n was deleted". Undo and redo move around in this list (they simply move the pointer to the current edit history position); all the positions are accessible just like the current one, and are exposed in many functions described above via the pos or edpos arguments. The edit list functions are:

as-one-edit (func origin)

apply 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. Returns result of 'func'.

(as-one-edit 
  (lambda () 
    (set! (sample 100) .1) 
    (set! (sample 200) .2)))

See mix.scm for many examples. If you want to save 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 'func'; the default is to copy the last edit history string and use its associated bounds -- unlikely to be what you want.

display-edits (snd chn edpos with-source)

return 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.

edit-fragment (num snd chn)

return 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 num is omitted, edit-fragment returns the currently active edit.

edit-list->function (snd chn start end)

return a function encapsulating the current edit history list. This provides 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. Eventually I'll add user interface support for this "sound spreadsheet" approach to editing. This facility is not finished! The function returned takes 2 arguments, a sound index and channel number.

edit-position (snd chn)

current position in the edit history list; can be set. (set! (edit-position) 0) is equivalent to (revert-sound). See make-sample-reader.

edits (snd chn)

return 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).

edit-tree (snd chn pos)

return a list of lists completely describing current edit list. Each inner list has the form
'(global-position data-number local-position local-end scaler ramp0 ramp1 type).
If data-number is -2, it marks the end of the list. The following function uses this information to highlight the changed portions of a given sound.

(define (show-original snd chn)
  ;; draw a bar above unchanged portions of a sound
  (define (check-fragment tree ls rs)
    (let* ((fragment (car tree))       ; current edit list fragment
           (pos (car fragment))        ; its position in sound
           (dat (cadr fragment))
           (scl (list-ref fragment 4)))
      (if (and (= dat 0)               ; original sound
               (= scl 1.0))            ; unscaled
          (let ((nxtpos (car (cadr tree))))
            (if (and (<= pos rs)
                     (>= nxtpos ls))   ; fragment is at least partially visible
                (let ((x0pos (x->position (/ (max ls pos) (srate))))
                      (x1pos (x->position (/ (min rs nxtpos) (srate)))))
                  (fill-rectangle x0pos 2 (- x1pos x0pos) 5)))))
      (if (and (cdr tree)              ; go to next fragment
               (not (= (cadr (car tree)) -2)))
          (check-fragment (cdr tree) ls rs))))
   (check-fragment (edit-tree snd chn)
                   (left-sample snd chn)
                   (right-sample snd chn)))
(add-hook! after-graph-hook show-original)

save-edit-history (filename snd chn)

save current edit list(s) in filename. If chn is omitted, all snd's channels are saved; if snd is omitted, all edit lists are saved. If the underlying files are not subsequently changed, you can load this file to restore the current edit list state. save-edit-history returns #t if all went well. The following function makes an exact copy of the state (edit lists and all) of the given sound, providing a way to fork an edit path (geez, what jargon!). The idea here is to copy the complete edit state into a new sound so that two or more edit sequences can be compared.

(define sfile 0)

(define* (clone-sound-as new-name #:optional snd)
  (let* ((tmpf (snd-tempnam))
	 (scm (string-append (substring tmpf 0 (- (string-length tmpf) 3)) "scm"))
	 (oldsnd (or snd (selected-sound))))
    (if (not (string? (save-dir))) (set! (save-dir) "/tmp"))
    (save-edit-history scm oldsnd)
    (copy-file (file-name oldsnd) new-name)
    (set! sfile (open-sound new-name))
    (load scm)
    (delete-file scm)
    sfile))

It is sometimes more convenient to edit the edit history lists directly, than to run Snd and invoke the "Save State" menu option. To save a particular sound's or channel's edit list(s), use the function save-edit-history. These lists are simply Scheme or Ruby programs, just like anything else discussed in this document. You could even write them from scratch. Say we want to make a stereo file that consists of four mono files mixed at various points; we know where they should go, and we have religious objections to using a graphical user interface. So we create myfile.scm, and put in it something like:

(let ((myfile (new-sound "mysound.snd" mus-aifc-sound-file mus-bshort 44100 2 "this is my sound")))
	;; this is equivalent to the New file menu option
  (mix "oboe.snd" 0 0 myfile 0)
  ;; this mixes in the mono file oboe.snd at sample 0 in channel 0
  ;; use (mix "oboe.snd" 0 0 myfile 0 #f) to forego the editable mix
  (mix "pistol.snd" 0 0 myfile 1)
  ;; now pistol.snd is at sample 0 in channel 1
  (mix "fyow.snd" 10000 0 myfile 0)
  ;; add in fyow.snd at sample 10000 in the first channel
  (mix "cardinal.snd" 20000 0 myfile 1)
  ;; etc
  )

Now start Snd: snd -l myfile.scm and voila! Files like this can contain any arbitrary code, calling anything in Snd or anywhere else for that matter; you have a CLM-like notelist reader to describe sound file edits. Similarly, when you save Snd's state (via the Save State menu option or by calling the function save-state), the result is a program that can be edited just like any other such text.

Many editing operations within Snd actually only affect the current edit lists. For example, if you delete a portion of a sound, the only thing that happens is that the edit list of that sound is updated to reflect the jump over the deleted portion. Similarly, all scaling operations, silences, envelopes, and simple cases of channel swaps only affect the edit list. This means that ideally such operations are instantaneous and take no disk space no matter how large the sound being edited (in other cases we have to save at least the changed portion of the sound). ptree-channel (still in the experimental stages) extends this part of Snd to (almost) arbitrary functions.

Transforms

Except for add-transform, the transform functions and variables have been treated above, so this is just a list of them with cross-references.

add-transform (name xlabel lo hi transform)

add-transform adds a transform to the transform tables. name is the name to use in the transform dialog. xlabel is the x axis label of the resultant graph. lo and hi set which portion of the returned data to graph (normally 0.0 to 1.0). proc is a function of two arguments, the length of the desired transform, and a sample-reader that can be used to get the current data. Do not free the sample-reader! The function should return a vct containing the transform data. add-transform returns the new transform's transform-type. Here's an example that displays a histogram of the current values in 16 bins:

(add-transform "histogram" "bins" 0.0 1.0 
  (lambda (len fd)
    (let ((v (make-vct len))
          (steps (/ len 16))
          (step (/ 1.0 len)))
      (do ((i 0 (1+ i))) 
          ((= i len) v)
        (let* ((val (read-sample fd))
               (bin (inexact->exact (* (abs val) 16.0))))
          (do ((j 0 (1+ j))) 
              ((= j steps))
            (vct-set! v 
                      (+ j bin) 
                      (+ step (vct-ref v (+ j bin))))))))))

And an example that ties the Hilbert transform in dsp.scm into the user-interface:

(add-transform "Hilbert" "Hilbert" 0.0 1.0
  (lambda (len fd)
    (let ((flt (make-hilbert-transform 40)))
      (do ((i 0 (1+ i))) ; preload first samples
	  ((= i 40))
	(fir-filter flt (read-sample fd)))
      (vct-map! 
       (make-vct len) 
       (lambda () 
	 (fir-filter flt (read-sample fd)))))))

autocorrelate (data)

return the (in place) autocorrelation of data (a vct). See spot-freq in dsp.scm, or rubber.scm.

fft (rl im sgn)

perform 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; (default 1). The CLM fft 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.

Other related variables and functions:

transform-graph?	show-transform-peaks	transform-sample
fft-window-beta	show-selection-transform	transform->vct
transform-hook	spectro-cutoff	transform-frames
fft-log-frequency	spectro-hop	transform-type
fft-log-magnitude	spectro-start	update-transform-graph
transform-size	spectro-x-angle	transform-normalization
transform-graph-type	spectro-x-scale	zero-pad
fft-window	spectro-y-angle	wavelet-type
max-transform-peaks	spectro-y-scale	spectro-z-scale
min-dB	spectro-z-angle

And some of the fft-based effects/editing functions:

CLM fft function: mus-fft
CLM spectrum: spectrum
Snd spectrum: snd-spectrum
Cross Correlation: correlate
FFT window: make-fft-window
Dolph-Chebyshev window in Scheme: dolph
Hartley transform in Scheme: dht
Spectral edit dialog: Envelope Editor

fft-based filter: fft-edit, fft-env-edit, fft-env-interp, fft-squelch, fft-cancel
phase-vocoder: phase-vocoder. pvoc
transposition via fft: down-oct
phase rotation via fft: zero-phase, rotate-phase
duration change via autocorrelation: rubber-sound
smoothing via fft: fft-smoother
cross-synthesis: cross-synthesis
voiced->unvoiced effect: voiced->unvoiced
noise reduction: Noise Reduction, notch-channel, anoi
spectral modeling: pins
polynomial approach to spectral multiplies (convolution): spectral-polynomial

Superimpose ffts: superimpose-ffts
Waterfall real-time spectrograph: start-waterfall
Simple rt spectrum: show-input-fft, show-draggable-input-fft
More transforms: fractional-fourier-transform, z-transform in dsp.scm
3D (single) fft display: complexify

Dialogs

The built-in dialogs, accessible from the main menu, provide the standard, but very clumsy ways to open and save sounds, edit envelopes and headers, and set various global variables. In addition, many other dialogs are implemented in various Scheme/Ruby files. The following functions refer to the built-in dialogs. Functions such as color-dialog normally create and start the dialog in question; that is, (color-dialog) puts the color 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 (be '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 (open-file-dialog #f).

color-dialog (managed)

Create and (if managed which defaults to #t) activate the Color dialog. Return the dialog widget.

define-envelope (name data (base 1.0))

Add 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 defvar. (define-envelope ramp '(0 0 1 1)).

edit-header-dialog (snd)

start the Edit Header dialog on snd, return the dialog widget.

enved-base ()

envelope editor exponential base value (1.0)

enved-clip? ()

envelope editor 'clip' button (restricts mouse motion) (#f)

enved-dialog ()

start the Envelope editor dialog, return the dialog widget.

enved-envelope ()

current envelope in the envelope editor's graph window (list).

enved-filter ()

The type of the Envelope editor's filter. (default #t: FIR, #f is FFT). To get the fft display in the envelope editor as the default:

(define (enved-fft)
  (set! (enved-filter) #f)
  (set! (enved-wave?) #t)
  (set! (enved-target) enved-spectrum)
  (add-hook! after-open-hook (lambda (snd)
			       (set! (transform-size snd) 
				     (expt 2 (ceiling (/ (log (max 1 (frames snd)))
							 (log 2.0))))))))

enved-filter-order ()

The order of the envelope editor's FIR filter. (default is 40)

enved-in-dB ()

envelope editor 'dB' button (#f)

enved-power ()

envelope editor base scale range (9.0^power). (3.0)

enved-style ()

envelope editor choice for connecting breakpoints. Can be envelope-linear (the default), or envelope-exponential.

enved-target ()

Determines how the envelope editor's current envelope is applied to the currently selected data. The choices are enved-amplitude, enved-srate and enved-spectrum.

enved-waveform-color ()

color of waveform displayed in envelope editor. (default is blue).

enved-wave? ()

envelope editor 'wave' button. The wave shown is the time domain display, even when filtering.

find-dialog (managed)

create and (if managed which defaults to #t) start the Edit:Find dialog, return the dialog widget.

help-dialog (subject help-string xrefs urls)

start the help dialog with title subject and body 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.

(help-dialog "xyzzy" "are we having fUn?")

There are many examples in new-effects.scm.

(defmacro with-snd-help (form)
  ;; if an error occurs while evaluating form, try to start the help dialog with some relevant help
  `(catch #t 
	  (lambda ()
	    ,form)
	  (lambda args
	    (if (and args (cadr args) (string? (cadr args)))
		(let* ((func (if (string=? "set!" (substring (cadr args) 0 4))
				(substring (cadr args) 5)
				(cadr args)))
		       (help (snd-help func)))
		  (if help (help-dialog func help))))
	    args)))

html-dir ()

The directory to search for documentation if an HTML reader is in use. See html in index.scm.

html-program ()

The program to use to read HTML files (defaults to "mozilla", but can also be "netscape"). On the Mac, you need to give the full path to the executable image: "/Applications/Safari.app/Contents/MacOS/Safari". See html in index.scm.

info-dialog (subject info)

start the info dialog with title subject and body info. Return the dialog widget.

(info-dialog "xyzzy" "are we having fUn?")

just-sounds ()

In Motif and in Gtk versions 2.3 or later, if just-sounds is #t, the file lists displayed by the file selection dialogs are filtered to show just sound files (see add-sound-file-extension and just-sounds-hook).

listener-color ()

background color of lisp listener. (set! (listener-color) (make-color 0 0 0)) is good too.

listener-font ()

listener font.

listener-prompt ()

lisp listener prompt (defaults to ">").

listener-text-color ()

text color in lisp listener.

mix-dialog-mix ()

the id of the mix displayed by the mix dialog

mix-file-dialog (managed)

create and (if managed which defaults to #t) activate the File:Mix dialog. Return the dialog widget.

open-file-dialog (managed)

create and (if managed which defaults to #t) activate the File:Open dialog (see snd-motif.scm for examples). Return the dialog widget. If the xm module is loaded, we could add our own info via:

  (let* ((dialog (open-file-dialog #f))
	 (rc (find-child dialog "info-rc2")) ; holds the info labels if a sound file is selected
	 (label (XtCreateManagedWidget "file-preview-info" xmLabelWidgetClass rc (list XmNbackground (highlight-color)))))
    (XtAddCallback (XmFileSelectionBoxGetChild dialog XmDIALOG_LIST)
		   XmNbrowseSelectionCallback
		   (lambda (widget context info)
		     (let ((file (cadr (XmStringGetLtoR (.item info) XmFONTLIST_DEFAULT_TAG))))
		       (XtVaSetValues label
				      (list XmNlabelString
					    (XmStringCreateLtoR (format #f "~A: no comment" file)
								XmFONTLIST_DEFAULT_TAG)))))
		   #f))

orientation-dialog (managed)

Create and (if managed which defaults to #t) activate the Orientation dialog. Return the dialog widget.

previous-files-sort ()

The sort function choice in the View:Files dialog (0=unsorted, 1=name, 2=date, 3=size, 4=entry, 5=user procedure).

previous-files-sort-procedure ()

Procedure used to sort files in the files dialog. It takes one argument, the list of files, and should return that list, sorted as it pleases. The following sorts the list by decreasing max amp:

(set! (previous-files-sort-procedure)
  (lambda (lst)
    (sort lst 
	  (lambda (a b)
	    (define (mxall mxcur mxlst)
	      (if (null? mxlst)
		  mxcur
		  (mxall (max mxcur (cadr mxlst)) (cddr mxlst))))
	    (let ((mxa (mus-sound-maxamp a))
		  (mxb (mus-sound-maxamp b)))
	      (or (null? mxb)
		  (and (not (null? mxa))
		       (> (mxall 0.0 mxa)
			  (mxall 0.0 mxb)))))))))

print-dialog (managed)

Create and (if managed which defaults to #t) activate the File:Print dialog. Return the dialog widget.

print-length ()

number of elements of lists and vectors that are printed. default: 12.

recorder-autoload ()

The 'autoload' button in the recorder dialog. default: #f.

recorder-buffer-size ()

The size of the recorder input buffer (there's a trade-off between responsiveness and clicks in some cases).

recorder-dialog ()

start the recorder window, return the dialog widget.

recorder-file ()

Default recorder output file name.

recorder-file-hook (name)

Called when 'Record' is pressed, passed the current recorder output filename. If it returns a string, that becomes the output filename.

(add-hook! recorder-file-hook
  (lambda (name)
    (let* ((header (recorder-out-type))
	   (extension (if (or (= header mus-aifc) (= header mus-aiff)) ".aif"
			  (if (= header mus-next) ".snd"
			      ".wav"))))
      (if name
	  (let ((len (string-length name)))
	    (do ((i 0 (1+ i)))
		((or (= i len)
		     (char=? (string-ref name i) #\.))
		 (string-append (if (> i 1)
				    (substring name 0 i)
				    "test")
				extension))))
	  (string-append "test" extension)))))

recorder-gain (gain)

recorder input (soundcard-audio) gain gain.

recorder-in-amp (in out)

recorder input channel in to output channel out amplitude.

recorder-in-chans ()

Recorder input channels. (default: 0 = ask the audio card how many channels it can handle)

recorder-in-device ()

Input device for recorder.

(set! (recorder-in-device) mus-audio-line-in)

recorder-in-format ()

Incoming data format for the recorder. default 16-bit linear.

recorder-max-duration ()

Recorder max output file length.

recorder-out-amp (out)

recorder file output channel out amplitude.

recorder-out-chans ()

Recorder output file channels. (default: 2)

recorder-out-format ()

recorder output file data format.

recorder-out-type ()

recorder output file header type.

recorder-srate ()

Recorder sampling rate.

recorder-trigger ()

Recorder auto-trigger value.

save-listener (filename)

save listener text in filename.

save-selection-dialog (managed)

create and (if managed which defaults to #t) start the Edit Save-as dialog (to save the current selection), return the dialog widget.

save-sound-dialog (managed)

create and (if managed which defaults to #t) start the File Save-as dialog (to save the currently selected sound), return the dialog widget.

show-listener ()

if #t, open the lisp listener pane, else close it. For backwards compatibility, if called outside set!, it opens the pane.

spectro-cutoff ()

The amount of the frequency domain to include in the spectrum display. This number changes as you drag the frequency axis. This is the slider labelled '% of spectrum' in the View Orientation dialog. Its default value is 1.0.

spectro-hop ()

The distance (pixels) moved between successive spectrogram traces. This is the slider labelled 'hop' in the Orientation dialog. default: 4.

spectro-start ()

The starting point of the frequency domain in the spectrum display. default: 0.0

spectro-x-angle ()

Default spectrogram x-axis viewing angle. default: 90.0

spectro-x-scale ()

Default scaler (stretch) along the spectrogram x axis. default: 1.0

spectro-y-angle ()

Same for y-axis. default: 0.0

spectro-y-scale ()

Same for y-axis. default: 1.0

spectro-z-angle ()

Same for z-axis. default: -2.0

spectro-z-scale ()

Same for z-axis. default: 0.1

tempo-control-bounds ()

Track dialog tempo slider bounds (defaults to (list 0.0 8.0)).

track-dialog-track ()

the id of the track currently displayed by the track dialog.

transform-dialog (managed)

create and (if managed which defaults to #t) activate the Options:Transform dialog. Return the dialog widget.

view-files-dialog (managed)

create and (if managed which defaults to #t) activate the View:Files list of current and previous files (not the file browser), and return the dialog widget.

view-mixes-dialog ()

create and activate the Mix Dialog, return the dialog widget.

view-regions-dialog ()

start the region browser (a no-op if there are no regions). Return the dialog widget.

view-tracks-dialog ()

create and activate the Track dialog, return the dialog widget.

vu-font ()

The "vu-" variables refer to the VU meters in the recorder. vu-font is the font used to label the meters. It is normally "courier".

vu-font-size ()

recorder VU meter label font size. (1.0)

vu-size ()

overall size of the recorder VU meters. (1.0)

yes-or-no? (ques)

modal error dialog, #t if user clicks "yes", otherwise #f.

In normal use, this is a very annoying thing to call because it forces everything to stop until the poor user clicks a button; in Snd, it's used for questions like "destroy disk?". While developing code, however, yes-or-no? can be a very handy way to stop and restart a computation. Say we're trying to get remove-clicks in examp.scm to work, and can't see why a click is being missed. We can use yes-or-no? to step through the samples one at a time, breaking out of the computation at any time (the ellipses here mark code omissions -- see the original for details):

    (call-with-current-continuation
     (lambda (return)
       (do ((ctr loc (1+ ctr)))
	   ((= ctr len) #f)
	...
	 (let ((local-max (max .1 (vct-peak samps))))
	   (snd-print (format #f "~A " local-max))
	   (if (yes-or-no? "continue?")
	       (if (and (> (abs (- samp0 samp1)) local-max)
                        ...
		   (return (1- ctr)))
	       (return #f)
               ...

But this is kinda dumb; we really should use a continuation here:

    (call-with-current-continuation
     (lambda (return)
       (do ((ctr loc (1+ ctr)))
	   ((= ctr len) #f)
         ...
	 (let ((local-max (max .1 (vct-peak samps))))
	   (call-with-current-continuation
	    (lambda (go-on)
	      (snd-print (format #f "~A: ~A (~A) " ctr local-max samp2))
	      (return go-on)
	      (if (and (> (abs (- samp0 samp1)) local-max)
                  ...
		  (return (1- ctr))

Now save the continuation after the first call, and whenever you want to pick up where you last left off, call it as a function of no arguments. This method leaves all the rest of Snd operational (in particular the listener), whereas yes-or-no? tries to freeze everything until you click its button.

Here is a partial list of the dialogs scattered around Snd.


Open file		File:Open and File:View	open-file-dialog, open-hook, open-sound
	install-searcher	Add colors and a filter to file menu
	keep-file-dialog-open-upon-ok	don't close Open dialog upon "ok"
	select-file	add a custom file dialog to File menu
Save sound		File:Save as	save-sound-dialog, save-hook, save-sound-as
Mix sound		File:Mix	mix
Record		File:Record	recorder-dialog, recorder-file-hook
Create a new file		File:New	new-sound-hook, new-sound
Print		File:Print	print-dialog
Find globally		Edit:Find	find-dialog, find
	listener completions dialog
	add-find-to-listener
Save selection		Edit:Save selection	save-selection-dialog, save-selection
Edit envelope		Edit:Envelope	enved-dialog, enved-hook, define-envelope
Edit header		Edit:Header	edit-header-dialog, bad-header-hook
	raw sound confirmation dialog
	bogus header repair dialog
View mixes and tracks		View:Mixes and View:Tracks	view-mixes-dialog, view-tracks-dialog
View regions		View:Regions	view-regions-dialog
View previously loaded files		View:Files	view-files-dialog
	nb	post info about each file as mouse passes over it
	make-sound-box	show available sounds in a box full of icons
Spectrogram color scheme		View:Color	color-dialog, colormap and its friends
Spectrogram viewing angle		View:Orientation	orientation-dialog, spectro-x-angle and its friends
Errors		View:Error history
FFT choices		Options:Transforms	transform-dialog, transform-size and its friends
Help choices		Help:*	help-dialog, snd-help, help-hook
Effects choices		Effects:*	effects menu
Ladspa choices		Ladspa:*	install-ladspa-menues, ladspa-dir, apply-ladspa
Rename or delete sound		File:Rename and File:Delete	add-rename-option, add-delete-option
Demand a yes or no answer			yes-or-no?
Font choice		View:Select font	make-font-selector-dialog, axis-label-font and its friends
Color choice		View:Select file	make-color-selector-dialog, basic-color and its friends
Access more controls		Options:More controls	make-hidden-controls-dialog, expand-control-ramp and its friends
Realtime FM violin controls			create-fmv-dialog, the fm-violin
with-sound variable display			make-variable-display

The main menus can be extended, and new menus added with the following functions:

add-to-main-menu (menu-label update-callback)

add a new top-level menu named menu-label and return its menu index. This 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. new-effects.scm calls this function to add a new "Effects" menu to the top level menubar.

  >(add-to-main-menu "Tools")
  5

add-to-menu (top-menu menu-label callback position)

add menu menu-label to top-level menu whose index is top-menu with the callback function callback. Return the new menu label widget. The built-in Snd menus are numbered from 0 ('File') to 5 ('Popup'); 'Help' is menu 4. 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.

  (add-to-menu 1 "Stop Playing" 
    (lambda () (stop-playing)))


  (add-to-menu 5 "Reduce height" 
    (lambda () (set! (window-height) (/ (window-height) 2))))

As a slightly more elaborate example, the following adds a Delete option to the File menu:

(add-to-menu 0 "Delete" ; add Delete option to File menu
	     (lambda ()
	       ;; close current sound and delete it (after requesting confirmation)
	       (if (selected-sound)
		   (let ((filename (file-name)))
		     (close-sound)
		     (if (yes-or-no? (format #f "delete ~S?" filename))
			 (delete-file filename)))))
	     8) ; place after File:New

remove-from-menu (top-menu menu-label)

remove menu menu-label from the top top-level menu whose index is top-menu. See examp.scm or snd-motif.scm.

I may change these menu handlers to use the menu-widgets list and more general functions; let me know what you'd like to be able to do!

Miscellaneous functions

These functions don't seem to fit anywhere else:

abort ()

exit Snd via "abort", presumably to fall into the C debugger (gdb). To stop some on-going Snd operation, use C-g.

add-sound-file-extension (ext)

add ext to the list of (case sensitive) sound file extensions used by sound-files-in-directory. The initial list is ("snd" "aiff" "aif" "wav" "au" "aifc" "voc" "wve" "WAV" "sf2"). To add "ogg" as a recognized extension: (add-sound-file-extension "ogg")
A Scheme implementation: add-sound-file-extension-1.

bind-key (key state func extended origin)

Cause key (an integer) with modifiers state (and preceding C-x if extended) to evaluate func when the graph widget has keyboard "focus". 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.

(bind-key (char->integer #\a) 4 
          (lambda () 
            "print 'hi' in listener"
            (snd-print \"hi\") 
            cursor-in-view))

(bind-key (char->integer #\p) 0 
          (lambda () 
            "move cursor to left edge of window"
            cursor-on-left)
          #f "#\\p->cursor-on-left")

(bind-key (char->integer #\v) 4
	  (lambda ()
            "move ahead one window"
	    (if (< (right-sample) (frames))
		(set! (left-sample) (right-sample)))
	    keyboard-no-action))

(bind-key (char->integer #\v) 0 
          (lambda () 
            "remove click" 
            (set! (sample (cursor)) (* 0.5 (+ (sample (1- (cursor))) (sample (1+ (cursor)))))) 
            cursor-in-view))

The modifier state is a combination of control = 4 and meta = 8, so the first bind-key above causes C-a to print "hi" in the lisp listener. The value returned should be one of the cursor choices telling Snd what action (if any) to take after evaluating code. Possible return values are:

  cursor-in-view  cursor-on-left  cursor-on-right  cursor-in-middle  keyboard-no-action

The function bound to a key can take either no arguments (as above), or one argument. In the latter case, the argument is the count (the C-u number prefixed to the keyboard command) defaulting to 1 if no prefix is typed. For example, there used to be a "line-size" variable setting how how many samples to jump for the C-p and C-n keys. We can implement the same idea:

(define line-size 128)
(bind-key (char->integer #\n) 4 
  (lambda (arg) "move cursor ahead 128 samples" (set! (cursor) (+ (cursor) (* line-size arg)))))
(bind-key (char->integer #\p) 4 
  (lambda (arg) "move cursor back 128 samples" (set! (cursor) (- (cursor) (* line-size arg)))))

We can use bind-key to turn the keyboard into a sort of extended piano:

(bind-key (char->integer #\o) 0 
  (lambda () "play oboe.snd"
    (play "oboe.snd") 
    keyboard-no-action))

(bind-key (char->integer #\p) 0 
  (lambda () "play pistol.snd"
    (play "pistol.snd") 
    keyboard-no-action))

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":

(bind-key (char->integer #\l) 0 
  (lambda () "move window forward 2 samples"
    (set! (left-sample 0 0) (+ 2 (left-sample 0 0))) 
    keyboard-no-action))

Or, more useful perhaps, have C-c set the cursor at a particular sample:

(bind-key (char->integer #\c) 4
  (lambda (arg) "move cursor to arg"
    (set! (cursor) arg) 
    cursor-in-middle))

The key codes can usually be found in the X header file X11R6/include/X11/keysymdef.h The End key if #xff57, so we could bind it to cause the full sound to be displayed:

  (bind-key #xff57 0 (lambda () "view full sound" (set! (x-bounds) (list 0.0 (/ (frames) (srate))))))

A similar set rebinds the arrow keys to give much more precise window position and size control:

(define (move-one-pixel s c right)
  (let* ((ax (axis-info s c time-graph))
	 (lo (list-ref ax 0))
	 (hi (list-ref ax 1))
	 (lo-pix (list-ref ax 10))
	 (hi-pix (list-ref ax 12))
	 (samps-per-pixel (max 1 (inexact->exact (/ (- hi lo) (- hi-pix lo-pix)))))
	 (change (if right 
                     (- (min (+ hi samps-per-pixel) (frames s c)) hi)
                     (- (max 0 (- lo samps-per-pixel)) lo))))
    (set! (left-sample) (+ lo change))
    keyboard-no-action))

(bind-key #xff51 0 (lambda () "move back one pixel" (move-one-pixel (selected-sound) (selected-channel) #f)))    ;left
(bind-key #xff53 0 (lambda () "move forward one pixel" (move-one-pixel (selected-sound) (selected-channel) #t))) ;right


(define (zoom-one-pixel s c in)
  (let* ((ax (axis-info s c time-graph))
	 (lo (list-ref ax 0))
	 (hi (list-ref ax 1))
	 (lo-pix (list-ref ax 10))
	 (hi-pix (list-ref ax 12))
	 (samps-per-pixel (max 1 (inexact->exact (/ (- hi lo) (- hi-pix lo-pix)))))
	 (len (frames s c)))
    (if in
	(if (> (- hi-pix lo-pix) samps-per-pixel)
	    (begin
	      (set! (left-sample) (+ lo samps-per-pixel))
	      (set! (x-zoom-slider) (exact->inexact (/ (max samps-per-pixel (- hi lo (* 2 samps-per-pixel))) len)))))
	(begin
	  (set! (left-sample) (max 0 (- lo samps-per-pixel)))
	  (set! (x-zoom-slider) (exact->inexact (/ (min len (+ (- hi lo) (* 2 samps-per-pixel))) len)))))
    keyboard-no-action))

(bind-key #xff52 0 (lambda () "zoom out one pixel" (zoom-one-pixel (selected-sound) (selected-channel) #f))) ;up
(bind-key #xff54 0 (lambda () "zoom in one pixel" (zoom-one-pixel (selected-sound) (selected-channel) #t)))  ;down

The emacs-style line-oriented commands C-p, C-n, and C-k aren't very useful in Snd, since there's no reason for 128 samples to consititute the audio analog of a line of text. In the next example, we rebind them to treat same-sense zero-crossings as line markers:

(define (find-zero forwards)
  (let* ((loc (cursor))
	 (twice #f)
	 (dir (if forwards 1 -1))
	 (reader (make-sample-reader loc #f #f dir))
	 (val (read-sample)))
    (while (not (or (c-g?)
		    (and forwards (sample-reader-at-end? reader))
		    (and (not forwards) (= loc 0))))
      (let ((newval (read-sample reader)))
	(set! loc (+ loc dir))
	(if (or (and (>= val 0.0) (< newval 0.0))
		(and (< val 0.0) (>= newval 0.0)))
	    (if twice
		(break loc)
		(begin
		  (set! val newval)
		  (set! twice #t))))))
    loc))

(define (delete-to-zero forwards)
  (let ((loc (cursor))
	(zero-loc (find-zero forwards)))
    (if (not (= loc zero-loc))
	(if forwards
	    (delete-samples (cursor) (- zero-loc loc))
	    (begin
	      (delete-samples zero-loc (- loc zero-loc))
	      (set! (cursor) zero-loc))))))

(define (go-to-zero forwards)
  (set! (cursor) (find-zero forwards)))

(bind-key (char->integer #\k) 4 (lambda (arg) 
                                  "delete to next zero crossing"
				  (do ((i 0 (1+ i))) 
				      ((= i (abs arg)))
				    (delete-to-zero (> arg 0)))))
(bind-key (char->integer #\n) 4 (lambda (arg) 
                                  "go to next zero crossing"
				  (do ((i 0 (1+ i))) 
				      ((= i (abs arg)))
				    (go-to-zero (> arg 0)))))
(bind-key (char->integer #\p) 4 (lambda (arg) 
                                  "go to previous zero crossing"
				  (do ((i 0 (1+ i))) 
				      ((= i (abs arg)))
				    (go-to-zero (< arg 0)))))

Most of the predefined key definitions are given in Keyboard Commands. 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):

(XtAppAddActions (car (main-widgets)) (list (list "hiho" (lambda args (snd-print "hiho")))))
(XtOverrideTranslations (list-ref (main-widgets) 4) (XtParseTranslationTable "Ctrl <Key>i: hiho()\n"))

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:


;;; Motif version:

(define extended #f)     ; our extended mode flag

(XtAddEventHandler (list-ref (main-widgets) 4) KeyPressMask #f 
  (lambda (w context event go)
    (let* ((bits (.state event))
	   (keysym (XKeycodeToKeysym (XtDisplay w)
				    (.keycode event)
				    (if (not (= (logand bits ShiftMask) 0)) 1 0))))
      (if (= (logand bits ControlMask) 0)
	  (set! extended #f)
	  ;; got C-<something>
	  (if (= (cadr keysym) 120) ; C-x
	      (set! extended #t)
	      (begin
		(if (and extended
			 (= (cadr keysym) 102)) ; C-x C-f
		    (open-file-dialog))
		(set! extended #f)))))))


;;; Gtk version:

(define extended #f)     ; our extended mode flag

(let ((listener (list-ref (main-widgets) 4)))
  (g_signal_connect_closure_by_id 
   (GPOINTER listener)
   (g_signal_lookup "key_press_event" (G_OBJECT_TYPE (GTK_OBJECT listener)))
   0
   (g_cclosure_new (lambda (w event data)
		     (let ((bits (.state (GDK_EVENT_KEY event)))
			   (key (.keyval (GDK_EVENT_KEY event))))
		       (if (= (logand bits GDK_CONTROL_MASK) 0)
			   (set! extended #f)
			   ;; got C-<something>
			   (if (= key 120) ; C-x
			       (set! extended #t)
			       (begin
				 (if (and extended
					  (= key 102))
				     (open-file-dialog))
				 (set! extended #f))))
		       #f))
		   #f #f)
   #f))

See edit123.scm and snd_conffile.scm for many more examples of bind-key.

clear-listener ()

delete listener text from the beginning to the cursor position (C-M-g is bound to this function).

close-sound-file (fd bytes)

close file (opened by open-sound-file) updating header to report bytes bytes of data. This refers to data files handled directly, not sounds displayed in Snd (the latter are handled by open-sound and close-sound). See save-track in mix.scm.

c-g? ()

check for C-g to interrupt an on-going computation, and let other UI events through. c-g? is especially useful in loops; we could define our own safe 'while' loop as follows (this is a slight revision of Guile's while macro from ice-9/boot-9.scm):

(defmacro safe-while (cond . body)
  `(letrec ((break (lambda val (apply throw 'break val)))
	    (continue (lambda () (if (c-g?) 
				     (break 'interrupted)
				     (or (not ,cond) 
					 (begin (begin ,@ body) 
						(continue)))))))
     (catch 'break
	    (lambda () (continue))
	    (lambda v (cadr v)))))

Here's a version of "do" that is interruptible and continuable. c-g? provides the interrupt, and call-with-current-continuation provides the continuation. To continue running an interrupted do?, (do-go-on).

(define do-go-on-continuation #f)
(define (do-go-on)
  (if (continuation? do-go-on-continuation) ; a Snd function -- should be provided by Guile!
      (do-go-on-continuation #f)
      ";sorry! can't continue"))

(defmacro do? (inits ends . body)
  `(do ,inits
       ((or (and ,(car ends)
		 (begin 
		   (set! do-go-on-continuation #f) ; clear obsolete continuation
		   #t))
	    (and (c-g?)                            ; got C-g -- set continuation
		 (call-with-current-continuation
		  (lambda (go-on)
		    (set! do-go-on-continuation go-on)))))
	,(and (not (null? (cdr ends)))
	      (cadr ends)))
     ,@body))

See examp.scm and play.scm for other examples.

c-g! ()

simulate typing C-g (intended for use with bind-key to remap C-g).

dac-is-running ()

#t if sound output is currently in progress. dac-is-running only notices Snd-instigated "play" processes; if you open the DAC via mus-audio-open-output and send it output via mus-audio-write, dac-is-running will not notice.

defvar (var val)

same as (define var val) except that the envelope editor keeps track of var thereafter and treats lists as envelopes. (defvar is a macro). defvar exists in this context so that Snd and CLM can share envelope files; non-CLM users might prefer define-envelope. (defvar a-func '(0 0 1 1)).

equalize-panes (snd)

equalize Snd panes as in the View menu Equalize Panes option. If the snd argument is given, only that sound's panes are affected. This function is specific to the Motif version of Snd.

(add-hook! after-open-hook 
  (lambda (n) (if (> (channels n) 3) (equalize-panes))))

exit (exit-value)

exit Snd. Guile's exit function is renamed %exit.

goto-listener-end

move the cursor to the end of the listener text, and scroll the window so that it is visible. See ws.scm for examples.

graph->ps (file)

create Postscript picture of current display. file defaults to eps-file.

in (ms thunk)

ms milliseconds from now, evaluate thunk, a function of no arguments. In Ruby, this is named "call_in".

(in 5000 (lambda () (snd-print "boo!")))

(define (at hour minute func)
  (let* ((cur-time (localtime (current-time)))
	 (cur-minute (vector-ref cur-time 1))
	 (cur-hour (vector-ref cur-time 2))
	 (now (+ (* cur-hour 60) cur-minute))
	 (then (+ (* hour 60) minute)))
    (in (* 1000 60 (- then now)) func)))

(at 15 11 (lambda () (snd-print "it's 3:11 pm!")))

key (key state snd chn)

execute the keyboard command key with modifier keys state. state is the bitwise OR of shift: 1, control: 4, meta: 8

key-binding (key (state 0) extended)

the user-defined (not built-in) procedure, if any, currently bound to key+state+extended. state is the bitwise OR of shift: 1, control: 4, meta: 8. extended is #t if the command is preceded by C-x.

listener-selection ()

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:

  (bind-key (char->integer #\h) 0 
    (lambda ()
      "start help dialog based on listener selected text"
      (let ((subject (listener-selection)))
	(if subject
            (help-dialog subject (snd-help subject))))))

But it's probably more convenient to use the listener-click-hook and click-for-listener-help (draw.scm).

little-endian? ()

return #t if underlying machine is little endian.

memo-sound

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 memo-sound is set to the newly opened sound's index. This supports the snd-memo feature in CLM, but can be used independently of CLM to store marks, selections, or whatever that you want associated with a particular sound. Confusingly enough, this is a variable, unlike all the others -- that is, you refer to it directly, not as a procedure call. Say we have a sound file "now.snd", and we want it to use the grid-graph whenever it is viewed. We make "now.snd.scm" and put in it: (set! (show-grid memo-sound) #t). When now.snd is opened, so is now.snd.scm, with memo-sound holding the index of now.snd. There are other fancier ways to do this (e.g. remember-sound-state).

open-sound-file (&optional-key :file :channels :srate :comment :header-type)

Open (create) a sound file file (file name defaults to "test.snd" or "test.wav"). It is assumed that the data will be floats in the native format (written by the caller interleaving channels), and that the file will be closed by close-sound-file. One simple way to write the data is to call vct->sound-file. open-sound-file opens an output file external to Snd, whereas open-sound loads a file into Snd for editing.

  (let ((fd (open-sound-file "hiho.snd" 1 :srate 22050 :comment "hiho is from snd-test")))
    (vct->sound-file fd v2 10) ; v2 has 10 samples of sound data, presumably
    (close-sound-file fd 10))

preload-directory (dir)

preload sound files from directory dir (see -p). Preloading a file means placing it in the list of previous files in the View menu's View Files dialog. By preloading all the files you might want to use, you can use that dialog to access them conveniently. See nb.scm.

preload-file (file)

preload file, placing it in the View menu's View Files dialog as a previous file (as if you had opened and closed it).

reset-listener-cursor

reset the listener cursor to the default pointer shape

save-envelopes (filename)

save envelope editor contents in filename.

save-listener (filename)

save listener contents in filename.

save-macros (filename)

save keyboard macros in filename or in Snd's init file (~/.snd) if filename is omitted.

save-options (filename)

save options (Snd global variable settings) in filename. Perhaps "save-defaults" would be a better name.

save-state (filename)

save current state of Snd in filename. The saved-state file is a Scheme or Ruby program that when loaded into Snd, recreates the state of Snd (as far as possible) at the point of the save. 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 ptree-channel in this regard. If you call save-state with active regions, and have the region browser running all the time, and subsequently want to back up the the saved state, it's safer to delete all the regions first (via forget-region), then load the saved-state file. save-state-hook is called during the saving process (once on each temp file), and and after-save-state-hook is called afterwards.

script-arg ()

current startup argument number (normally 1). See Snd as a script engine and snd-test.scm.

script-args ()

startup arguments as a list of strings. See Snd as a script engine and snd-test.scm.

snd-apropos (name)

return possible completions of name, a string or a symbol.

:(snd-apropos "mouse-enter")
"(guile): mouse-enter-graph-hook
(guile): mouse-enter-label-hook
(guile): mouse-enter-listener-hook"

snd-error (str)

reports the error message str in the Error dialog, saves str in the error history list (see View:Error History), and returns str. See also mus-error-hook and snd-error-hook.

snd-help (obj (formatted #t))

return (as a string) the help text associated with obj:

:(snd-help 'open-sound)
"(open-sound filename) opens filename (as if opened from File:Open menu option), 
and returns the new file's index"

To go to the HTML documentation for a given object, load index.scm and use the html function. To get a more global help function (i.e. one that knows about Scheme built-ins and so forth), (use-modules (ice-9 session)). This loads Guile's help (and apropos) support which uses 'regexps' and so forth.

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. click-for-listener-help in draw.scm uses this to put off formatting the help string until the help dialog (rather than the listener) gets it.

snd-loaded-files

A variable (not a function), a list containing the full names of (nearly) all the files currently loaded into Snd. The Guile boot file may be missing from the list.

snd-print (str)

displays str in lisp the listener, then returns str. (This is intended as a debugging aid -- there's still nothing like a lowly print statement).

snd-remember-paths

A variable (not a function); if #t (its default is #f), Snd adds code to the Guile %load-hook that makes sure the current file's path is included in %load-path when load or load-from-path is called. This makes it possible to use load-from-path inside a Scheme file when you don't know in advance where that file will reside at load time.

snd-spectrum (data window length linear beta in-place normalized)

return the spectrum (as a vct) of data (also a vct) using fft-window win. length is the number of samples of data. (let ((spectr (snd-spectrum data rectangular-window (transform-size)))) ...) 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.

snd-tempnam ()

return a new temp file name using Snd's temp-dir.

:(temp-dir)
"/home/bil/zap/tmp"
:(snd-tempnam)
"/home/bil/zap/tmp/snd_7000_2.snd"

snd-url (name)

return the url (in the Snd documentation) corresponding to name; name can be a string or a symbol.

:(snd-url 'open-sound)
"extsnd.html#opensound"

snd-urls ()

return a list of lists each inner list containing a Snd function name (as a string) and its associated url in the Snd documentation.

:(assoc "open-sound" (snd-urls))
: ("open-sound" . "extsnd.html#opensound")

snd-version ()

Snd version: a string, normally a date. version is a Guile function.

snd-warning (str)

post a warning message, str, in the minibuffer, and return str. See also snd-warning-hook.

sound-files-in-directory (dir)

return a list of sound file names. A file is considered a sound if it has data and its extension is on the sound file extension list (see add-sound-file-extension). 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:

(for-each
  (lambda (filename)
    (if (and (= (mus-sound-header-type filename) mus-aifc)
             (= (mus-sound-chans filename) 2))
        (snd-print (format #f "~%~A" filename))))
  (sound-files-in-directory))

See also map-sound-files in snd4.scm, and map-sound-files in extensions.scm.

unbind-key (key state extended)

cause key with modifiers state to be a no-op (or to revert to its built-in default).

widget-position (widget)

return a list giving the widget x and y coordinates (pixels). Can be set. See Snd widgets below, and nb.scm where it uses the current window position to try to find a convenient place for the help dialog.

widget-size (widget)

return a list giving the widget width and height (pixels). Can be set. See nb.scm and examp.scm.

window-property (known-atom property)

window-property returns or (via set!) changes an X-window's property; title-with-date in examp.scm uses this function to put the date and time in the Snd title bar.

Constants

Sndlib (see sndlib.html for a complete list):

  mus-next mus-aifc mus-riff mus-nist mus-raw mus-ircam mus-aiff
  mus-bicsf mus-soundfont mus-voc mus-svx

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

  mus-out-format

Time domain graph type (time-graph-type):

  graph-once  graph-as-wavogram

Transform graph type (the Transform Options Display choice, transform-graph-type):

  graph-once  graph-as-sonogram  graph-as-spectrogram

Transform type (transform-type):

  fourier-transform  wavelet-transform   cepstrum   haar-transform
  autocorrelation    walsh-transform

Transform normalization (transform-normalization):

  dont-normalize     normalize-by-channel    normalize-by-sound    normalize-globally

FFT Window type (fft-window):

  rectangular-window     hann(ing)-window      welch-window         parzen-window
  bartlett-window        hamming-window        blackman2-window     blackman3-window
  blackman4-window       exponential-window    riemann-window       kaiser-window
  cauchy-window          poisson-window        gaussian-window      tukey-window
  dolph-chebyshev-window hann-poisson-window   connes-window

Zoom Focus style (zoom-focus-style):

  zoom-focus-left    zoom-focus-right   zoom-focus-active zoom-focus-middle

X-axis Label (x-axis-style):

  x-axis-in-seconds  x-axis-in-samples  x-axis-as-percentage  x-axis-in-beats

Speed Control style (speed-control-style):

  speed-control-as-float     speed-control-as-ratio     speed-control-as-semitone

Channel Combination style (channel-style):

  channels-separate  channels-combined  channels-superimposed

Envelope Editor target (enved-target):

  enved-amplitude      enved-spectrum       enved-srate

Envelope Editor ramp choice (enved-style):

  envelope-linear   envelope-exponential

Graph Line style (graph-style):

  graph-lines        graph-dots         graph-filled      graph-lollipops
  graph-dots-and-lines

Key binding cursor action (bind-key):

  cursor-in-view     cursor-on-left     cursor-on-right   cursor-in-middle  keyboard-no-action

Cursor style (cursor-style):

  cursor-cross   cursor-line

Axis placement choice (show-axes):

  show-all-axes  show-no-axes  show-x-axis  show-all-axes-unlabelled  show-x-axis-unlabelled

Graph id (for y->position etc):

  time-graph     transform-graph     lisp-graph

Colormap choice (colormap, defined in rgb.scm):

  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

Errors and Debugging

When something goes awry, the various functions can throw an error (a symbol) which is normally caught by the default error handler (this is a kind of goto but without the embarrassment). It prints out some message, and sometimes appends a stack trace. So, as a simple example, selection-position throws 'no-active-selection if there isn't a selection:

>(selection-position)
selection-position: no-active-selection
>asdf
Unbound variable: asdf

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:

>(catch 'no-active-selection 
       (lambda () 
         (+ 1 (selection-position))) 
       (lambda (tag val) 0))
0

Here we've caught 'no-active-selection (if it occurs within the first thunk's body), and return 0 if it occurs; otherwise we return (+ 1 (selection-position)). Scheme (Guile) has a number of errors such as 'out-of-range, 'wrong-type-arg, 'numerical-overflow, etc. The Snd-specific errors are:

'no-such-channel 'no-such-sound  'no-such-mark       'no-such-mix
'no-such-menu    'no-such-file   'no-such-region     'no-such-sample
'no-such-edit    'cannot-save    'no-such-envelope   'no-active-selection
'no-such-widget  'mus-error      'no-such-track      'bad-arity
'cannot-print    'no-such-axis   'no-such-player     'no-such-graphics-context
'no-such-color   'no-such-widget 'no-such-plugin     'no-data
'gsl-error       'no-such-key    'no-such-direction  'cannot-parse
'no-such-colormap

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:

(defmacro without-errors (func)
  `(catch #t 
	  (lambda ()
	    ,func)
	  (lambda args (car args))))

You can use these errors in your code, if you like, or add your own. The following throws the error 'no-such-file:

(define look-for-file
  (lambda (file)
    (or (file-exists? file)
	(throw 'no-such-file (list "look-for-file" file)))))

The mix.scm track functions can return 'no-such-track if a given track has no mixes.

There is one special catch: 'snd-top-level. This is used by the debuggers to exit the current context, returning up a level in the stack of listeners. Normally that means you jump out of a breakpoint or whatever and find yourself back at the top level. (throw 'snd-top-level).

There are a variety of debugging aids supplied by Guile, including a backtrace facility. To be sure all Guile's debugging support code is loaded,

  (use-modules (ice-9 debug))

Now when an error occurs, you can call (snd-debug) and fall into the debugger. The debugger in Snd is just the normal listener, but you also have some stacks and continuations lying around. These can be examined via bt (backtrace) and lv (local variables).

If you're getting a stack overflow, and you're sure it's not a case of infinite recursion,

(debug-set! stack 0)

turns off the (very conservative) stack overflow check. If for some reason the backtrace information doesn't include a file name or line number, you can watch the load process by setting %load-verbosely to #t.

If you hit a bug in Snd's C code, you'll need to use gdb (or dbx on the SGI) 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:

gdb snd core
where

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

gdb snd
run

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,

gdb snd
break exit
run

Customizing Snd's appearance

Snd's overall appearance is controlled first by the startup switches that choose the outermost widget; normally this is a paned window with a sound in each pane; -separate puts each sound in a separate window, and -notebook puts each sound on a separate page of a notebook widget. Similarly -horizontal and -vertical determine which way the outer panes are laid out. There are a variety of functions and variables related to widget colors and so forth.

Colors

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:

>(define blue (make-color 0 0 1))

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 rgb.scm. The overall widget background color is basic-color.

>(set! (basic-color) blue)

The color variables are:

`basic-color`	`ivory2`	main Snd color.
`cursor-color`	`red`	cursor color.
`data-color`	`black`	color of data in unselected graph.
`doit-button-color`	`palegreen2`	color of Ok and Apply buttons.
`doit-again-button-color`	`darkolivegreen1`	color of Undo&Apply buttons.
`enved-waveform-color`	`blue`	color of waveform displayed in envelope editor.
`filter-control-waveform-color`	`blue`	color of control panel filter waveform.
`graph-color`	`white`	background color of unselected graph.
`help-button-color`	`lightsteelblue2`	color of Help buttons.
`highlight-color`	`ivory1`	highlighting color.
`listener-color`	`aliceblue`	background color of lisp listener.
`listener-text-color`	`black`	text color in lisp listener.
`mark-color`	`red`	color of mark indicator.
`mix-color`	`darkgray`	color of mix waveforms.
`position-color`	`ivory3`	position slider color
`pushed-button-color`	`lightsteelblue1`	color of pushed button.
`quit-button-color`	`indianred`	color of Dismiss and Cancel buttons.
`reset-button-color`	`goldenrod1`	color of Reset buttons.
`sash-color`	`lightgreen`	color of paned window sashes.
`selected-data-color`	`black`	color of data in currently selected graph.
`selected-graph-color`	`white`	background color of currently selected graph.
`selection-color`	`lightsteelblue1`	color of selected portion of graph.
`text-focus-color`	`white`	color of text field when it has focus.
`zoom-color`	`ivory4`	zoom slider color.

I have these lines in my ~/.snd file:

    (define beige (make-color 0.96 0.96 0.86))
    (define blue (make-color 0 0 1))
    (set! (selected-graph-color) beige)
    (set! (selected-data-color) blue)

In addition, the various transforms can be displayed using colormaps. The following variables and functions control this:

`color-cutoff`	0.003	In spectra, sets the lowest data value that will be colored.
`color-inverted`	#t	The 'invert' button in the color dialog, negated (hunh?!).
`color-scale`	0.5	The darkness setting in the color dialog, divided by 100.
`colormap`	0	Colormap choice for various displays (see the Color dialog, or samples-via-colormap in draw.scm). The built-in maps (from 0 to 15) are: black-and-white, gray, hot, cool, bone, copper, pink, jet, prism, autumn, winter, spring, summer, rainbow, and flag. These names are defined (with '-colormap' appended) in rgb.scm and rgb.rb.

The color object handlers are:

`color? (obj)`	#t if obj is a color (this is the same as Pixel? in xm), (see make-color).
`color->list (obj)`	return list (r g b) of color components.
`make-color (r g b)`	return a color object using the red/green/blue values. If the object is called as a function, it returns the list of rgb values. If, for example, blue is a defined color, `(blue)` is the same as `(color->list blue)`. Two colors are equal (i.e. equal? returns #t) if their rgb values are the same.

Other color-related stuff:
X/Motif color resources: Snd Resources
Color names: rgb.scm, rgb.rb
colors in the file dialogs: install-searcher-with-colors in snd-motif.scm
color-dialog: color-dialog
colored samples: display-colored-samples and others in draw.scm
colored edits: display-previous-edits in draw.scm
colored tracks: dlp/track-colors.scm in the tutorial
colored marks: mark-sync-color in snd-motif.scm
colors in rxvt: red-text et al in examp.scm
flashing colors: flash-selected-data in examp.scm
openGL: snd-gl.scm, Snd and OpenGL
fancy widget backgrounds: dlp/new-backgrounds.scm in the tutorial
root window color: set-root-window-color in snd-motif.scm
color hookcolor-hook
Snd graphics contexts: snd-gcs

Fonts

Fonts in Snd are strings containing a description of the desired font. These can be the abbreviated forms such as "8x14" or a full X font name such as "-misc-fixed-bold-r-normal--*-140-*-*-*-*-*-*". (In Gtk, the font names resemble "Monospace 10" etc). The font variables are:

`axis-label-font`	used in axis labels
`axis-numbers-font`	used in axis tick numbers
`bold-peaks-font`	used by fft peaks display
`peaks-font`	used by ffy peaks display
`listener-font`	listener font
`tiny-font`	smallest font used

(set! (listener-font) "9x15")
(set! (axis-label-font) "-*-times-medium-r-normal-*-18-*-*-*-*-*-*-*")
(set! (axis-numbers-font) "9x15")

See also load-font and current-font below. In Gtk2, Pango-style names are used for the fonts: "Monospace 8" for example. If the requested font can't be loaded, the set! statement returns the old (unchanged) font name.

>(set! (axis-label-font) "8x14")
"-*-times-medium-r-normal-*-18-*-*-*-*-*-*-*"

Widgets

Snd can be built with Motif, Gtk, or no GUI; other toolkits might be supported in the future. Unfortunately, each toolkit has its own way of handling widgets. I originally started implementing a Snd-specific layer of calls that would work in any supported toolkit, but then changed direction and decided to implement the libxm connection. This left the earlier graphics functions dangling; they are still useful, but they probably should not be built-in. I'm currently planning to move them to Scheme/Ruby. But, for now, here are some of them:

`widget-position (widget)`	return a list giving the widget x and y positions
`widget-size (widget)`	return a list giving the widget width and height. The corresponding set! forms also take a list: `(set! (widget-position (cadr (main-widgets))) (list 300 100))`
`widget-text (widget)`	return or set the contents of text widget
`show-widget (widget)`	show (manage) widget
`hide-widget (widget)`	hide (unmanage) widget
`focus-widget (widget)`	give widget keyboard focus

`main-menu (menu)`
`main-widgets ()`
`menu-widgets ()`
`sound-widgets (snd)`
`channel-widgets (snd chn)`
`dialog-widgets ()`

The four "-widgets" procedures return lists of possibly useful widgets:

  main-widgets:    '(0:top-level-application 1:top-level-shell 2:main-pane 3:main-sound-pane 
                     4:listener-pane 5:notebook-outer-pane)

  menu-widgets:    '(0:top-level-menu-bar 1:file-menu 2:edit-menu 3:view-menu 
                     4:options-menu 5:help-menu, 6:default popup menu)

  sound-widgets:   '(0:main-pane 1:name-label 2:control-panel 3:minibuffer 
                     4:play 5:filter-graph 6:unite 7:minibuffer-label 8:name-icon 9:sync)

  channel-widgets: '(0:graph 1:w-button 2:f-button 3:x-position 4:y-position 
                     5:x-zoom 6:y-zoom 7:edit history list 
                     8:right(united-chans) y-position 9:right y-zoom) + others in gtk

  dialog-widgets:  '(0:color_dialog 1:orientation_dialog 2:enved_dialog 3:error_dialog 
                     4:yes_or_no_dialog 5:transform_dialog 6:file_open_dialog 
                     7:file_save_as_dialog 8:view_files_dialog 9:raw_data_dialog 
                     10:new_file_dialog 11:file_mix_dialog 12:edit_header_dialog 
                     13:find_dialog 14:help_dialog 15:completion_dialog 16:view_mixes_dialog
                     17:print_dialog 18:recorder_dialog 19:view_regions_dialog, 20:info_dialog
                     21:view_tracks_dialog)

dialog-widgets entries are #f for any dialog that has not yet been created. In gtk, the first element of the main-widgets list is the top level shell's window.

To remove the y-position slider (which is only there for looks):

  (hide-widget (list-ref (channel-widgets) 4))

See also snd-motif.scm, new-effects.scm, and examp.scm.

Graphics

It is possible to draw directly on any of the channel graphs. Simple examples include the show-original after-graph-hook function, and the x-cursor function that draws an "x" shaped cursor. The lowest level procedures are:

add-colormap (name func)

add-colormap adds a new colormap to the colormap table, returning its index (for use with colormap or colormap-ref). name is the name displayed in the Color Dialog's list of colormaps. func is a function of one argument, the desired colormap size; it will be called whenever the new colormap's values are needed or the colormap size changes, so that the colormap needs to be recomputed. It should return a list of three 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):

(add-colormap "purple" 
  (lambda (size) 
    (let ((r (make-vct size))
	  (g (make-vct size))
	  (b (make-vct size))
	  (incr (exact->inexact (/ 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))
	   (x 0.0 (+ x incr)))
	  ((= i size))
        (vct-set! r i (exact->inexact (/ (envelope-interp x er) 256.0)))
        (vct-set! g i (exact->inexact (/ (envelope-interp x eg) 256.0)))
        (vct-set! b i (exact->inexact (/ (envelope-interp x eb) 256.0))))
      (list r g b))))

;;; another amusing colormap from FractInt:
(add-colormap "cos" 
  (lambda (size) 
    (let ((r (make-vct size))
	  (g (make-vct size))
	  (b (make-vct size))
	  (incr (exact->inexact (/ 3.14159 size))))
      (do ((i 0 (1+ i))
	   (x 0.0 (+ x incr)))
	  ((= i size))
	(vct-set! r i (abs (sin (* 1.5 x))))
	(vct-set! g i (abs (sin (* 3.5 x))))
	(vct-set! b i (abs (sin (* 2.5 x)))))
      (list r g b))))

colormap-name (index)

colormap-name returns the specified colormap's name.

colormap-ref (map pos)

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 samples-via-colormap in draw.scm.

colormap-size ()

colormap-size returns (or sets) the current number of colors in each colormap. The default is 512.

copy-context

the graphics mode 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. See draw.scm or display-samps-in-red.

current-font (snd chn context)

return the current font (also settable).

cursor-context

the graphics mode for XOR drawing in the cursor color (for cursors, normally). See x-cursor or foreground-color.

delete-colormap (index)

delete-colormap deletes the colormap represented by index.

draw-axes (wid gc label x0 x1 y0 y1 style axes)

draw axes in the widget wid, using the graphics context gc, with the x-axis label label going from x0 to x1 (floats) along the x axis, y0 to y1 along the y axis, with x-axis-style style (x-axis-in-seconds etc); which axes are actually displayed or just implied depends on axes (it defaults to show-all-axes). Return 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.

draw-dot (x0 y0 dot-size snd chn context)

draw a dot at (x0 y0) of dot-size pixels diameter in the given graph. See musglyphs.scm.

draw-dots (positions dot-size snd chn context)

draw dots of size dot-size from the (x y) pairs in the vector positions in the given 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. The xm and xg modules have made these functions obsolete.

draw-line (x0 y0 x1 y1 snd chn context)

draw a line from (x0 y0) to (x1 y1) in the given context. See show-hiho below.

draw-lines (lines size snd chn context)

draw lines following the (x y) pairs in the vector lines in the given graphics context (copy-context is the default). See make-current-window-display in draw.scm. make-bezier-1 in musglyphs.scm can be used to draw Bezier curves.

draw-string (text x0 y0 snd chn context)

draw a string (text) in the current font and foreground color starting at (x0 y0) in the given graphics context. The next procedures use the channel-property list (extensions.scm) to maintain a list of sample-oriented comments, displaying a given comment if its associated sample is currently in the time-domain graph:

(define* (add-comment sample comment #:optional snd1 chn1)
  (let* ((snd (or snd1 (selected-sound)))
	 (chn (or chn1 (selected-channel)))
	 (old-comments (or (channel-property 'comments snd chn) '())))
    (set! (channel-property 'comments snd chn)
	  (cons (list sample comment)
		old-comments))))
	  
(define (show-comments snd chn)
  (let ((comments (or (channel-property 'comments snd chn) '())))
    (for-each
     (lambda (comment)
       (let* ((samp (car comment))
	      (text (cadr comment))
	      (text-width (* 6 (string-length text)))
	      (ls (left-sample snd chn))
	      (rs (right-sample snd chn)))
	 (if (and (< ls samp)
		  (> rs samp))
	     (let ((xpos (x->position (/ samp (srate))))
		   (ypos (y->position (sample samp))))
	       (draw-line xpos 20 xpos (- ypos 4))
	       (draw-string text (- xpos (/ text-width 2)) 18)))))
     comments)))

(add-hook! after-graph-hook show-comments)

fill-rectangle (x0 y0 width height snd chn context)

draws a filled rectangle in the current foreground color from (x0 y0) of size (width height). See draw.scm, snd-motif.scm, or show-original.

fill-polygon (points snd chn context)

draws a filled polygon whose vertices are in the vector points.

(define (-> x0 y0 size snd chn)
  "draw an arrow pointing (from the left) at the point (x0 y0)"
  (let ((points (make-vector 8)))
    (define (point i x y)
      (vector-set! points (* i 2) x)
      (vector-set! points (+ (* i 2) 1) y))
    (define (arrow-head x y)
      (point 0 x y)
      (point 1 (- x (* 2 size)) (- y size))
      (point 2 (- x (* 2 size)) (+ y size))
      (point 3 x y)
      (fill-polygon points snd chn))
    (arrow-head x0 y0)
    (fill-rectangle (- x0 (* 4 size)) 
		    (inexact->exact (- y0 (* .4 size)))
		    (* 2 size)
		    (inexact->exact (* .8 size))
                    snd chn)))

musglyphs.scm has some elaborate examples that use fill-polygon to draw music notation symbols.

foreground-color (snd chn context)

return the current foreground color (also settable). The following gives us a green cursor:

  (set! (foreground-color 0 0 cursor-context) (make-color 1 0 1))

We can goof around with colors and fonts:

(define new-font (load-font "-*-helvetica-bold-r-*-*-14-*-*-*-*-*-*-*"))

(define show-hiho
  ;; show a red "hiho" in the helvetica bold font on a gray background
  (lambda (snd chn)
    (let ((ls (left-sample snd chn))
          (rs (right-sample snd chn)))
      (if (and (< ls 1000)
               (> rs 1000))
	  (let ((pos (x->position (/ 1000.0 (srate))))
		(old-color (foreground-color)))
	    (set! (foreground-color) (make-color .75 .75 .75))
            (fill-rectangle pos 10 50 20)
	    (set! (foreground-color) (make-color 1 0 0))
	    (if new-font (set! (current-font) new-font))
            (draw-string "hiho" (+ pos 5) 24)
	    (set! (foreground-color) old-color))))))

glSpectrogram (data gl-list cutoff use-dB min-dB scale br bg bb)

glSpectrogram takes spectrogram data and passes it to openGL. The waterfall function in snd-gl.scm uses this function.

graph-data (data snd chn context low high graphics-style)

graph-data displays data in the time domain graph of snd's channel chn using the graphics context context (normally copy-context), placing the data in the recipient's graph between points low and high in the drawing mode (graphics-style). With this function and make-graph-data we can overlay sounds, overlay different versions of the same sound, place a portion of a sound over another at an arbitrary point, and so on (see draw.scm):

(define (display-samps-in-red snd chn)
  "display samples 1000 to 2000 in red whenever they're in the current view"
  (let ((left (left-sample snd chn))
	(right (right-sample snd chn))
	(old-color (foreground-color snd chn))
	(red (make-color 1 0 0)))
    (if (and (< left 2000)
	     (> right 1000))
	(let* ((data (make-graph-data snd chn)))
	  (if (vct? data)                      ;the simple, one-sided graph case
	      (let* ((samps (- (min right 2000)
			       (max left 1000)))
		     (offset (max 0 (- 1000 left)))
		     (new-data (vct-subseq data offset (+ offset samps))))
		(set! (foreground-color snd chn) red)
		(graph-data new-data snd chn copy-context (max 1000 left) (min 2000 right))
		(set! (foreground-color snd chn) old-color))
	      (let* ((low-data (car data))     ;the two-sided envelope graph case
		     (high-data (cadr data))
                     ;; we need to place the red portion correctly in the current graph
                     ;; so the following is getting the "bin" numbers associated with 
                     ;; samples 1000 and 2000
		     (size (vct-length low-data))
		     (samps (- right left))
		     (left-offset (max 0 (- 1000 left)))
		     (left-bin (inexact->exact (/ (* size left-offset) samps)))
		     (right-offset (- (min 2000 right) left))
		     (right-bin (inexact->exact (/ (* size right-offset) samps)))
		     (new-low-data (vct-subseq low-data left-bin right-bin))
		     (new-high-data (vct-subseq high-data left-bin right-bin)))
		(set! (foreground-color snd chn) red)
		(graph-data 
                  (list new-low-data new-high-data) snd chn copy-context left-bin right-bin)
		(set! (foreground-color snd chn) old-color)))))))

(add-hook! after-graph-hook display-samps-in-red)

load-font (font-name)

load the font font-name (an X-style font spec), and return a handle for it (for current-font).

  (define new-font (load-font "-*-helvetica-bold-r-*-*-14-*-*-*-*-*-*-*"))

load-font could be (should have been!) defined using the xm module as:

(define (load-font name)
  (let ((fs (XLoadQueryFont (XtDisplay (cadr (main-widgets))) name)))
    (and (XFontStruct? fs) (.fid fs))))

make-graph-data (snd chn edit-position low-sample high-sample)

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 list of two vcts (the two sides of the peak envelope graph). edit-position defaults to the current edit history position, low-sample defaults to the current window left sample, and high-sample defaults to the current rightmost sample. The result can be used in the lisp graph:

(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 (make-graph-data snd chn)))
      (if datal
          (let* ((data (if (vct? datal) datal (cadr datal)))
                 (len (vct-length data))
                 (sr (srate snd)))
            (define (dB val)
	      (if (< val .001)
	          -60.0
	          (* 20.0 (log10 val))))
            (do ((i 0 (1+ i)))
	        ((= i len))
	      (vct-set! data i (+ 60.0 (dB (abs (vct-ref data i))))))
              (graph data "dB" 
	            (/ (left-sample snd chn) sr) (/ (right-sample snd chn) sr)  
	            0.0 60.0
	            snd chn))))))

(add-hook! lisp-graph-hook display-db)

Here we are taking whatever is displayed in the time domain, and presenting the same thing in dB in the lisp graph. display-energy in examp.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.

mark-context

the graphics context to use to draw a mark (XOR mode).

selection-context

the graphics context for XOR drawing in the selection color.

send-netscape (url)

Start netscape, if necessary, and tell it to go to the location 'url'. The actual HTML reader invoked is determined by html-program, but it's currently assumed that netscape/mozilla url syntax can be used to jump to the desired url.

snd-gcs

snd-gcs returns a list of Snd's graphics contexts (intended for use with the xm module in snd-motif.scm): (0)basic (1)selected_basic (2)combined (3)cursor (4)selected_cursor (5)selection (6)selected_selection (7)erase (8)selected_erase (9)mark (10)selected_mark (11)mix (12)selected_mix (13)fltenv_basic (14)fltenv_data.

with-gl

If #t and GL is loaded, use GL where possible (default is #t if HAVE_GL).

Snd Customization and Extension

Introduction

Channel-specific hooks:

Mixes

Tracks