                                     Snd

                 Bill Schottstaedt (bil@ccrma.stanford.edu)

                           [picture of Snd window]

----------------------------------------------------------------------------
Snd is a sound editor modelled loosely after Emacs and an old, sorely-missed
PDP-10 sound editor named Dpysnd. It can accomodate any number of sounds at
once, each with any number of channels. Each channel is normally displayed
in its own window, with its own cursor, edit history, and marks; each sound
has a 'control panel' to try out various changes quickly, and an expression
parser, used mainly during searches; there is an overall stack of 'regions'
that can be browsed and edited; channels and sounds can be grouped together
during editing; edits can be undone and redone without restriction
('unlimited undo'); Snd can be customized using an Emacs-lisp-like syntax;
it can also be extended with user-supplied editing or display functions
loaded at run time; and it's free; the code is available via anonymous ftp
from ccrma-ftp.stanford.edu as pub/Lisp/snd.tar.gz.

----------------------------------------------------------------------------

Contents

Getting Started
File Operations
     The Display
     Other Options
Editing
     The Active Channel and The Cursor
     Marks
     Regions
     How to ...
     Keyboard Commands
The Control Panel
Customization
Extensions
Planned Enhancements
Index

----------------------------------------------------------------------------

Getting Started

Once compiled and loaded (run make in a shell, or get the executable images
from ccrma-ftp), fire Snd up with

  snd some.snd

where "some.snd" is any available sound file. You should get a window with
the first .1 seconds of the sound displayed as a time domain waveform. Click
the file name at the lower left to get some information about the file.
Click the "f" button, and an fft window appears alongside the waveform. Drag
the upper scale at the bottom of the graph and both graphs are updated as
you move through the file. Drag the lower scale to zoom in or out. Drag the
outer scale (the wider one) on the left to zoom the y axis in or out. The
inner scale moves the y axis up and down; its main use is to move the
waveform out of the way of a mix console. Click the "w" button (to unset the
button) and the time domain waveform goes away. Click "play" to play the
file. "sync" is more complicated -- it is used to group sounds together for
simultaneous editing.

Now return to the time domain form (click "w" and "f"), and click on the
graph itself. A red cursor (a big "+") appears at that point. The cursor is
exactly like an Emacs cursor -- you can delete the sample at the cursor, for
example, by typing control D (abbreviated in this document C-d), or move
back one sample with C-b. To see all the cursor-related commands, go to the
"Help" Menu, and choose "Click for Help". The cursor becomes a question
mark. Move the cursor to the graph portion of the window and click, and a
help window pops up, telling all about it. You can use the same sequence to
get help for anything in the Snd window, even the vertical bar after the
file name.

Now click and drag the mouse through some portion of the graph -- the
portion dragged is highlighted in some way. When you release the mouse
button, the highlighted portion is 'selected' -- it becomes a 'region' that
can be deleted, pasted elsewhere (move the mouse and click the middle
button), played, and operated on in many ways. You'll notice if you make
some change to the data that the file name gets an asterisk, as in Emacs,
and the various 'undo' and 'redo' menu options come to life. Just for
laughs, cut the selection, then click the right mouse button to get the
popup menu, and try Undo followed by Redo. Next type C-m -- this sets a mark
at the current cursor location. C-a goes to the start of the window; C-j
jumps forward to the nearest mark. Click and drag the upper horizontal mark
portion to move the mark; click the triangular lower portion to play from
the mark. Drag the triangular portion to play the data following the mouse.

Finally, go to the View menu and select 'Show controls'. A new portion of
the Snd window is opened, containing a number of controls. Try goofing
around with them while playing the sound. For the more complex cases, the
button on the right side turns the option on or off. The sequence of changes
you make while playing can be remembered (the 'Record' button), replayed
('Replay') or applied to the data as a kind of giant editing operation
('Apply').

----------------------------------------------------------------------------

File Operations

  File Menu

    Open:    open a new file                                   (C-x C-f)
    Close:   close a file, flush any unsaved edits             (C-x k)
    Save:    save current edits, overwriting previous version  (C-x C-s)
    Save as: save current edits under a new name, stay in current file
    Revert:  flush edits
    Update:  re-read file (data changed behind Snd's back)
    View:    open file read-only
    Mix:     mix file
    New:     create a new, empty file
    Record: record sound producing a new file
    Print:   produce a Postscript version of current display
    Exit:    leave Snd, flushing all pending edits

Snd operates on sound files. When invoked, Snd scans its arguments for file
names, and opens any it finds.

  snd oboe.snd fyow.snd

If there are no arguments, Snd comes up as a bare menu bar. If a name is
preceded by "-p", it is treated as a directory name and all sound files
found in that directory are preloaded into the previous files list. To load
arbitrary Snd customizations (a session file for example) precede the file
name with "-l". You can also precede a file name with "-remote"; if a Snd
editor is already running, the indicated file is opened in that program;
otherwise a new Snd is started which opens the file. This is intended to be
similar to netscape's -remote switch.

Each sound file in the argument list can include start up information about
the size and location of the initial waveform display.

  snd oboe.snd -s "0.0,0.25,0.75,0.3"

The flag "-s" introduces the size information, followed by a string
containing the values of the x position, y position, x zoom, and y zoom
scrollbars.

A file can be opened from the File menu via Open or View. View opens the
file read-only, whereas Open will allow it to be changed. The equivalent
keyboard command is C-x C-f. You can also drag a sound file's icon and drop
it on top of the Snd icon or the Snd menubar.

In the file selection dialog, there's a button marked 'Sound files only'.
This can be set by default (see Customization). If it is set, only files
that appear to be sound files are included in the directory listing.
Currently Snd uses the file extension to decide whether it is a sound file
-- the acceptable extensions are snd, wav, aiff, au, aifc, voc, wve, and
perhaps others.

Snd uses CLM's file header and data readers/writers so the file and data
types that it can handle are:

read/write:
     NeXT/Sun/DEC/AFsp mulaw and alaw, 8, 16, 24, 32-bit linear, float,
     double
     AIFF/AIFC 8 to 32-bit linear, mulaw and alaw
     RIFF ('wave') 8, 16, and 32-bit linear, 8-bit unsigned, mulaw and alaw
     IRCAM (old style) 16-bit linear, float, mulaw and alaw
     no header, any data format
read-only:
     8SVX 8 and 16-bit linear
     IRCAM Vax float
     EBICSF, INRS, ESPS, SPPACK, ADC (OGI) 16-bit linear
     NIST-SPHERE 16-bit linear, mulaw and alaw
     AVR 8 and 16-bit linear and unsigned
     VOC 8-bit unsigned, 16-bit linear
     Sound Tools 8-bit unsigned
     Turtle Beach SMP, SoundFont 2.0 16-bit linear
     Sound Designer I and II
     PSION alaw, MAUD 8 and 16 bit
     Tandy DeskMate new and old style 8-bit unsigned
     Gravis Ultrasound 16-bit unsigned, Comdisco SPW, Goldwave sample
     Sonic Foundry, DiamondWare
automatically translated to NeXT 16-bit, then read/write:
     IEEE text, Mus10 SAM 16-bit (modes 1 and 4), IBM CVSD
     NIST shortpack, HCOM, Intel ADPCM, MIDI sample dump

'Linear' here means 2's complement integer. The files can have any number of
channels. Data can be either big or little endian. The default output type
is settable as the defaultOutputType resource. A raw data file gets its
srate, chans, and data format information either from the variables
raw-srate and friends (if raw-defaults == 1), or from a dialog window that
pops up when such a file is opened. The files listed as "automatically
translated" are decoded upon being opened, rewritten in NeXT 16-bit format
to a new file with an added (possibly redundant) extension .snd, and that
form is the one the editor sees from then on.

Each file has its own 'pane', a horizontal section of the overall Snd screen
space; within that section, each channel has a pane, and below the channels
is the 'control pane', normally hidden except for the file name and
'minibuffer'. The panes can all be independently raised and lowered by
dragging the pane buttons on the right. The channel that is currently active
(receiving keyboard commands) has a thin black border around the display
portion. Each channel has the four scrollbars setting what portion of the
data is displayed; the 'w' button (normally set) which causes the time
domain waveform to be displayed; and the 'f' button (normally unset) which
includes the frequency domain (FFT) display. There is a third display
settable by user-provided functions; if both the 'w' and 'f' buttons are off
and there is no active user-display function, you get an empty display. For
each sound there is a control panel containing the file name, with an
asterisk if there are unsaved edits, a 'minibuffer' for various kinds of
text-based interactions, a 'sync' button for grouped display and edit
operations, a 'unite' button (if the sound has more than one channel), and a
'play' button to play the current (edited) state of the file. Any number of
files can be played at the same time. The rest of the control panel modifies
how the file is played.

To open a new, empty file, use the New option.

To close a file (flushing any unsaved edits), use the File menu Close
option, or C-x k. This command applies to the file that contains the active
channel, or the top file in the display.

To save the current edited state of a file, use the Save option (to
overwrite the old version of the file), or Save as (to write to a new file,
leaving the old file unchanged). The equivalent keyboard command is C-x C-s
(save). Other related keyboard commands are C-x w (save selection as file),
and C-x C-w (extract and save the current channel as a file). Normally, if
the new file already exists, and it is not currently being edited in Snd, it
is silently overwritten. If you try to overwrite a file, and that file has
active edits in a different Snd window, you'll be asked for confirmation. If
you want Snd to ask before overwriting a file in any case, set the resource
overwriteCheck to 1, or include the expression (overwrite-check) in your
.snd initialization file.

To undo all edits and return to the last saved state of a file, use the
Revert option. The edit history is still available, so you can redo all the
edits in order simply by calling Redo repeatedly.

The Print option fires up the Print dialog. You can send the currently
active graph directly to a printer, or save it as an "encapsulated
Postscript" file. The default name of this file is "snd.eps"; the resource
that overrides this default is named 'epsFile'.

To mix files, see "Mix Files" below.

Finally, to exit Snd cleanly (that is, removing any temporary files, and
cleaning up some system stuff), use the Exit option. Unsaved edits are
silently flushed.

----------------------------------------------------------------------------

The Display

  View Menu

    Show controls:    show/hide the control panel    (C-x C-o, C-x C-c)
    Normalize:        cleanup current Snd display
    Channel style:    separate, combined or superimposed channels
    Info:             describe current file
    Dots:             use dots or lines in the data displays
    Verbose cursor:   describe the current sample every time the cursor moves
    Regions:          a browser to examine the region stack
    Files:            a browser of currently and previously loaded files
    Color:            a browser that sets color schemes
    Orientation:      a browser that sets spectrogram and wavogram orientation
    Groups:           group editor (mixing)
    Show marks:       show or hide current marks
    Show y=0:         show or hide the y=0 line
    X axis units:     x axis labelled in seconds, samples, percent of total

The file display can be modified in various ways. To use dots rather than
connected lines, use the Dots option in the View menu (see also dot-size).
Similarly, to show (or hide) the line Y = 0, use the y=0 option. The Region
browser is described under Regions. To open the control panel, use Show
Controls. You can also drag the associated pane button. When many files are
displayed, and the pane buttons have been in use, the overall display can
become a bit of a mess. To return to a state where each file and channel has
a 'normal' amount of space, use the Normalize option.

The Color and Orientation options activate windows that set various aspects
of the sonogram, spectrogram, and wavogram displays. There are eight or nine
colormaps available along with ways to invert the maps, and scale (darken)
them differently according to screen or printer characteristics. And the
graphs themselves can be rotated and resized. The color variable default
settings produce good output on the SGI but looks cluttered on some Linuces
-- you may have to play around with the lightness scaler and so on to find
reasonable values for your system.

The Info dialog can be left in view and updated with M-v i to reflect the
currently active sound. Except for the header comment, the same information
is displayed in the minibuffer when you click the file name.

The Files option fires up the file browser:

[picture of file browser]

The file browser window shown above provides two lists, one of the currently
active files in Snd, and the other of previously active files. The currently
selected sound is highlighted. The save button saves current edits, if any;
the play button plays the file; and the unlist button removes a file from
the previous files list. Click a current file name, and that sound becomes
the selected sound in the main Snd window. Click a previous file name, and
that file is opened in Snd. The 'update' button runs through the previous
files list checking for files that have been deleted or moved behind Snd's
back. 'Clear' clears the previous files list. The previous files list can be
preloaded via the -p switch to Snd, and the extended commands preload and
preload-file-browser. By preloading your "working set" of sounds, you can
save the bother of picking them up one by one from the clumsy file selection
box.

The Regions option is described below.

----------------------------------------------------------------------------

Other Options

  Options Menu

    FFT size:        length of FFT (defaults to 256)
    Show peaks:      show or hide listing of FFT peaks
    Log freq:        log or linear frequency axis for FFT
    FFT in dB:       log or linear magnitude axis for FFT
    FFT style:       normal FFT, sonogram, or spectrogram
    FFT window:      FFT window choice (defaults to 2nd order Blackman-Harris)
    FFT beta:        FFT window parameter, if relevant
    Zoom style:      where to focus during zooms
    Subsampling off: graph subsampling on or off
    Save options:    save current state of options
    Session:         save current state or load previous session
    Speed style:     control panel speed scrollbar interpretation

The Options Menu applies mainly to the FFT display triggered by setting the
'f' button in the channel window. Most of the options should be
self-explanatory. The FFT is taken from the start (the left edge) of the
current window and is updated as the window bounds change. The fft data is
scaled to fit between 0.0 and 1.0 unless the variable normalize-fft is 0
(its default is 1).

The easiest way to change the colormap and graph orientation of the
spectrogram, wavogram, and sonogram, is to use the Color and Orientation
dialogs from the View menu. You can also use the numeric keypad, macros, or
C-x C-x expressions. In the latter case, sono_max sets the maxmimum
frequency displayed, spectro_[xyz]angle and spectro_[xyz]scale set the
orientation and size of the graphs, and spectro_hop sets the density of
traces. The numeric keypad is mapped to these variables as follows:

    variable         increase           decrease
  sono_max          PageUp (9)          PageDown (3)
  spectro_hop       Add (+)             Subtract (-)  ;also wavo_trace
  spectro_zangle    RightArrow (6)      LeftArrow (4)
  spectro_xangle    Ctrl-UpArrow (8)    Ctrl-DownArrow (2)
  spectro-yangle    Ctrl-RightArrow (6) Ctrl-LeftArrow (4)
  spectro_zscl      UpArrow (8)         DownArrow (2) ;also wavo zscl
  fft_size          Multiply (*)        Divide (/)
  dot_size          Delete (.)          Insert (0)

You can get arbitrarily small or large ffts with the Multiply and Divide
keys. The keypad Enter key resets all the spectrogram variables to their
default values. (In Linux, use the corresponding numbered keys -- add shift
to the key sequences given above).

A somewhat frivolous feature, known to Snd as the "wavogram", mimics the
spectrogram in the time domain. The same rotation commands apply to this
display, with the additional variable wavo_hop which sets the density of the
traces. To get this display (or turn it off) call the M-x function (wavo).
It is important in this case to get the length of each trace correct so
successive peaks more or less line up. The trace length in samples is set by
the variable wavo_trace, or the numeric keypad + and - keys.

When large amounts of data are being displayed, Snd may subsample the data
to speed up the display process. This can introduce artifacts of the
sampling interval on rare occasions. The Subsampling option turns this on or
off. If you are displaying large portions of a sound and notice odd
periodicities in the overall envelope displayed, try turning off subsampling
before drawing any conclusions about the data.

The Save options menu option is best explained as a part of the
customization process described below. It basically sets up an
initialization file for Snd that sets all the options to their current
settings; this is intended to be similar to a .emacs file (its default name
is .snd).

The Zoom style option determines the graph point that tries to remain stable
in the display during an x-axis zoom. The default is to zoom onto the cursor
or the beginning of the current selection if either is visible. You can also
have zoom focus on the left edge, right edge, or midpoint of the current
window.
----------------------------------------------------------------------------

Edit Operations

  Edit Menu
    Undo:            Undo last edit                  (C-x C-u or C-_)
    Redo:            Redo last edit                  (C-x C-r)
    Find:            Global search via find dialog   (C-s, C-r)
    Cut:             Cut (delete) selected portion
    Paste:           Paste (insert) selected portion (C-y, C-x i)
    Mix:             Mix (add) selected portion      (C-x q)
    Play selection:  Play selected portion           (C-x p)
    Save selection:  Save selected portion as file   (C-x w)

Editing in Snd is modelled after Emacs in many regards. Each channel has a
cursor (a big "+"), a set of marks, and a list of edits that have not yet
been saved. Most operations take place at the cursor. Operations can be
applied simultaneously to any other channels or sounds by using the 'sync'
button. And as in Emacs, there is a notion of a region ('selection'), and a
list of saved regions. Operations can be applied either to a sample, a
region, a channel, a file, or any number of files at the same time. Where an
operation has an obvious analog in text editing, I've tried to use the
associated Emacs command. To delete the sample at the cursor, for example,
use C-d.

The following sections describe how to move the cursor and the window; how
to change which channel is active; how to use marks and regions; how to
perform various common editing operations. We end with a description of all
the mouse and keyboard editing commands. The 'control panel' provides more
complex editing operations, but has a chapter to itself.

The Active Channel and The Cursor

The Active Channel

The cursor (and its associated channel) is activated by clicking on the time
domain waveform. The active channel normally has a dark edge around the
graphics portion, as a sort of highlight. It is the window that receives
keyboard commands. You can also move between windows with C-x o (forwards or
backwards).

Moving the Cursor

Any mouse click on the waveform causes the cursor to move to that point. To
move the cursor from the keyboard, use:

  <      move cursor to sample 0
  >      move cursor to last sample
  C-<    move cursor to sample 0
  C->    move cursor to last sample

  C-a    move cursor to window start
  C-e    move cursor to window end
  C-b    move cursor back one sample
  C-f    move cursor ahead one sample

  C-n    move cursor ahead one 'line'
  C-p    move cursor back one 'line'
  C-v    move cursor to mid-window

  C-i    display cursor info
  C-j    go to mark
  C-x j  go to named mark

All keyboard commands accept numerical arguments, as in Emacs. If the
argument is a float, it is multiplied by the sampling rate before being
applied to the command, so C-u 2.1 C-f moves the cursor forward 2.1 seconds
in the data.

Moving the Window

The simplest way to move the window (the portion of the data in the current
graph) is to drag the scrollbars with the mouse. The darker scrollbars zoom
in and out; the lighter bars move the window along the x or y axis. Because
sound files can be enormous, the x axis placement needs some special
handling to make it useful in all cases. To move by a single windowful,
click the arrows on the scrollbar. To move by smaller amounts, use the left
and right arrow keys (or zoom with the up and down arrow keys); the control,
shift, and meta keys are multipliers on this movement -- each key adds a
factor of .5 to the multiple, so to move by .25 windows, press control,
meta, left (or right) arrow. A similar mechanism can be used to zoom quickly
onto a particular point; hold the keys and click the mouse in the waveform
and you'll zoom an increasing amount into the data at that point.

Various keyboard commands provide much more precise control of the window
bounds and placement:

  C-l      position window so cursor is in the middle
  C-x b    position window so cursor is on left margin
  C-x f    position window so cursor is on right margin
  [Down]   zoom out, amount depends on shift, control, and meta
  [Up]     zoom in
  [Left]   move window left
  [Right]  move window right
  C-x l    position selection in mid-view
  C-x v    position window over current selection
  C-x C-b  set x window bounds (preceded by number of leftmost sample)
  C-x C-p  set window size (preceded by size as numeric argument)

As in most other cases, the sample numbers (or sizes) can be floats; if the
argument is not an integer, it is multiplied by the sampling rate before
being applied to the command. So, C-u .1 C-x C-p makes the window display .1
seconds of data.

----------------------------------------------------------------------------

Marks

A mark marks a particular sample in a sound file (not a position in that
file). If we mark a sample, then delete 100 samples before it, the mark
follows the sample, changing its current position in the data. If we delete
the sample, the mark is also deleted; a subsequent undo that returns the
sample also returns its associated mark. I'm not sure this is the right
thing, but it's a lot less stupid than marking a position.

Once set, a mark can be moved (redefined) by dragging the horizontal tab at
the top. Click on the triangle at the bottom to play (or stop playing) from
the mark; drag the triangle to play following the mouse.

A mark can be named or unnamed -- the name is displayed above the horizontal
tab at the top of the window. The following keyboard commands relate to
marks:

  C-m       place (or remove if argument negative) mark at cursor
  C-x /     place named mark at cursor
  C-x C-m   add named mark

  C-j       go to mark
  C-x j     go to named mark

The distance from the cursor to a mark can be used as a numeric argument for
other commands by following C-u with C-m. Any number in-between is the
number of marks to jump forward before getting the distance.

The current marks assoicated with a sound can be saved in a file that Snd
will load automatically later. The session command is the simplest way, but
if you want to save just the marks, use the M-x (save-marks) command.

----------------------------------------------------------------------------

Regions

A region (or selection -- I use the words interchangeably here) is a portion
of the sound data. Regions can be defined by dragging the mouse through a
portion of the data. If the mouse drags off the end of the graph, the x axis
moves, in a sense dragging the data along to try to keep up with the mouse;
the further away the mouse is from the display, the faster the axis moves. A
region can also be defined with keyboard commands, much as in Emacs.
C-[space] starts the region definition and the various cursor moving
commands continue the definition.

Once defined, the selection is added to a stack of currently available
regions (the stack size is normally 16). In many cases, the numeric argument
to the command below chooses which region in that stack to use in the
command. Since it can be hard to remember which region is which, especially
since they are constantly on the move as the stack changes, there is a
region browser, similar to the File browser, invoked from the View menu's
Regions option:

[picture of region browser]

The 'save' button here protects the region from deletion as the region stack
grows. 'Print' produces a Postscript rendition of the current graph
contents, using the default eps output name. 'play' plays the region. The
graphical display shows the waveform with arrows to move around in the
channels of multi-channel regions.

The keyboard commands that apply to regions are:

  C-y         paste in current selection at cursor
  C-[space]   start keyboard-based region definition
  C-x a       apply amplitude envelope to selection
              see also scale-selection-by and scale-selection-to
  C-x c       define selection from cursor to nth mark
  C-x h       apply external function to selection
  C-x i       insert selection
  C-x n       re-evaluate expression over selection
  C-x p       play selection or region (numeric arg selects region)
  C-x q       mix in selection (float arg = scaler)
  C-x w       save selection as file
  C-x x       evaluate expression over selection
  C-x y       prompt for and apply external function to selection

  C-x l       position selection in mid-view
  C-x v       position window over current selection

Currently the inter-process selection passing mechanism is disabled because
it is very buggy, at least in Motif on the SGI. In the best of all worlds,
you would also be able to copy and paste regions between multiple Snd
programs. (The code exists -- I await a working system).

----------------------------------------------------------------------------

How to...

Save, open, close, print
Delete, insert, mix
Multi-channel operations
Amplitude envelopes and scaling
Find
Change samples
Undo, redo, revert
Play
Mix Files
Extend snd
Keyboard macros
Change file format
Extend a file
Miscellaneous commands

Save, open, close, print

Most of these kinds of operations are accessible from the File menu. They
can also be invoked from the keyboard:

  C-x k     close currently selected file
  C-x w     save selection as file
  C-x C-d   print
  C-x C-f   open file
  C-x C-s   save file
  C-x C-w   save currently selected channel as file

The Print command produces an encapsulated PostScript file which can be sent
to directly a printer or saved for later use.

Delete, insert, mix

The fastest way to delete a section is to drag the mouse through it and call
the Edit menu's Cut option. Any active region can be pasted or mixed in
using C-x q and C-x i with a numeric argument (the region number); the
current selection (region 0) can be pasted in by clicking the middle mouse
button. The associated keyboard commands are:

  C-d      delete sample at cursor
  C-k      delete a 'line' -- line_size (128) samples
  C-w      delete current selected portion

  C-o      insert a zero sample at cursor
  C-x i    insert selection at cursor (arg = region number)
  C-x C-i  insert file

  C-y      paste in current selection at cursor

  C-x q    mix in region (float arg scales mix, int arg = region number)
  C-x C-q  mix in file

Multi-channel operations

Normally each operation applies only to the currently active channel. If,
however, its 'sync' button is on, the operations apply to every sound or
channel that also has the sync button set. A multichannel sound also has a
'unite' button to the left of the 'sync' button. If this button is set, all
channels are displayed in one graph; the x and y-axis scrollbars apply to
all the channels at once, as do the 'f' and 'w' buttons; two new scrollbars
appear on the right of the window; the furthest right scrollbar affects the
placement of the window within the overall set of graphs, and the scrollbar
on its left zooms in and out of the overall graph. For stereo files, this is
user-interface overkill, but the hope is to accomodate sounds with many
channels, making it easy to focus on particular portions and so on. The View
menu Channel style option has the same effect but applies to all active
multichannel sounds. Control-click the unite button to get superimposed
channels.

To get multi-channel selections, set the sync button, then define the
selection (by dragging the mouse) in one channel, and the parallel portions
of the other channels will also be selected.

Amplitude envelopes and scaling

An envelope in Snd is a sequence of x y break-point pairs. The x axis range
is arbitrary. For example, to define a triangle curve: '0 0 1 1 2 0'. There
is no (obvious) limit on the number of breakpoints.

To apply an envelope to a sound, use the extended command C-x C-a. If this
command gets a numeric argument, the envelope is applied from the cursor for
that many samples. Otherwise, the envelope is applied to the entire file.

  C-x a     apply amplitude envelope to selection
  C-x C-a   apply amplitude envelope to channel

You can also specify a file name to the C-x C-a prompt. In this case the
envelope breakpoints are read from the file which is assumed to contain an
even number of floats. The corresponding M-x commands are:

  amp-env beg dur scaler env ;beg and dur in samples, env=breakpoints
  amp-envelope env           ;applies from sample 0 to end, scaler=1.0
  selection-amp-envelope env ;same but applied to all of selection

M-x (amp-envelope 0 1 1 0 2 1), for example, ramps the sound down to 0 in
its middle, then ramps back up to the original by the end.

To scale a file or selection by or to some amplitude, use the M-x commands:

  scale-by args
  scale-to args
  scale-selection-by args
  scale-selection-to args

scale-by scales the current sync'd channels by its arguments, and scale-to
scales them to its arguments (a "normalization"). The arguments in each case
are either a list of floats corresponding to each successsive member of the
current set of sync'd channels, or just one argument. In the latter case,
scale-by uses that scaler for all its channels, and scale-to normalizes all
the channels together so that the loudest reaches that amplitude (that is,
scale-to .5) when applied to a stereo file means that both channels are
scaled by the same amount so that the loudest point in the file becomes .5).

Find

Searches in Snd refer to the sound data, and are, in general, patterned
after Emacs. When you type C-s or C-r, the minibuffer below the graph is
activated and you are asked for the search expression. The expression is a
piece of C-like code that describes which sample satisfies the search. For
example, to look for the next sample that is greater than .1, we could type:
y > .1. The cursor then moves to the next such sample, if any. Successive
C-s's or C-r's repeat the search. C-x C-s can redefine the search pattern,
which is also cleared by various other commands, much as in Emacs.

The search (and C-x C-x) expression syntax includes most of C's operators,
the standard math library, as well as many variables internal to Snd. To get
at the current sample's value (the sample that the cursor is sitting on),
use 'y'. 'y(n)' refers to the sample n samples from the current one. 'x' is
the current sample number. 'samples' is the total number of samples.
Similiarly, each of the other channels besides the current one is accessible
as y1..8(n) (where the offset argument is optional); the channels are
assigned to these yn functions in the order they occur in the Snd display
(sounds from top to bottom, channels in order within a sound). As an
example, say you want to find where two channels differ:

  C-s y != y1

Or you want to find where the current channel has three consecutive zeros:

  C-s (y == 0.0) && (y(1) == 0.0) && (y(2) == 0.0)

Normally, the search applies only to the current channel. To search all
active files at once, use the Edit menu's find option.

The available C operators are:

+ - * / > >= < <= == !=
( ) { } += *= /= -= = || && ? : !

The available math library functions are:

log log10 exp cos sin abs (i.e. fabs) pow sqrt
atan acos asin cosh sinh tanh fmod ceil floor

Variables can be defined with 'float'. Snd-internal variables that are
accessible in these expressions include:

  auto_open:     force open window upon activation (default=true)
  explen:        segment length in expand
  exprmp:        ramp size in expand
  exphop:        hop size in expand
  revfb:         reverb volume
  y_max:         y axis bounds
  revlp:         reverb feedback low-pass coefficient
  x:             cursor sample number
  y:             value at cursor (y(n) also)
  y1..8:         value ar cursor (y1(n)) in channel n (counting sounds from top)
  samples:       current length of channel
  srate:         current srate of file
  pi:            3.14159...
  x_max:         x axis bounds
  color_scale:   color scale (darkness setting)
  color_cutoff:  ignore small values?
  revdecay:      length(secs) of reverb decay
  line_size:     length of a 'line' (for C-p etc)
  contrast_amp:  scaler on contrast input
  fft_size:      fft size
  sono_max:      sonogram y axis limit
  sono_color:    sonogram colormap
  spectro_color: spectrogram colormap
  spectro_hop:   density of spectrogram traces
  spectro_xangle:viewing angle of spectrogram (spectro_yangle, spectro_zangle)
  spectro_zscl:  height of peaks in spectrogram (spectro_yscl, spectro_xscl)
  wavo_trace:    wavogram trace length
  normalize_fft: 1 => normalize fft data to max of 1.0
  dot_size:      size of graph dots (default = 1)

The search commands are:

  C-r   find backwards
  C-s   find forwards

Change samples

The simplest changes are:

  C-z       set current sample to zero
  C-x C-z   smooth data using cosine

For more complex operations, you need to use expressions, described under
Find. C-x C-x y = .1 sets the sample at the cursor to .1. To set several
samples to zero, define a selection over the desired samples, then C-x x
y=0. Or use C-u preceding the C-x C-x command. To add a sine wave of
amplitude .1 and frequency 440 Hz to the next 1000 samples, first declare a
float variable (call it xx -- it will hold the phase), then calculate the
sine wave:

  C-x C-x float xx
  C-u 1000 C-x C-x {y += (.1*sin(xx)); xx += (440*pi*2/srate);}

The variables can be predeclared in your initialization file with eval, and
the actual expressions can be pasted into Snd from Emacs, so the simplest
way to keep a useful expression around (until I finally implement functions
in this context), is to include lines such as:

(eval "float phase")
(eval "float freq")
;{y+=(.1*sin(phase)); phase+=(freq*pi*2/srate);}

in your .snd file. Then in Snd, set the freq variable via C-x C-x, and call
the sine wave expression by selecting the text and pasting it into the Snd
minibuffer at the "eval:" prompt. This is admittedly a kludge. I'm trying to
decide whether to extend Snd's little lisp here, or add a C define feature,
or maybe an escape to CLM. See also Extensions below -- it is possible to
add your own arbitrarily complex editing functions to Snd.

Another way to use expressions is to make new sounds from existing ones. Say
we want to make a new sound that is the difference of two others: make a new
file (via the File menu New option, or M-x (new)), make room in it (via C-u
1.0 C-o or whatever), then:

  C-u 1.0 C-x C-x y = y1 - y2

Or say we want to know how many samples in the first second are over .1:
declare some counter, then use the C ? operator:

  C-x C-x float ctr
  C-u 1.0 C-x C-x ctr += (y>.1) ? 1 : 0
  C-x C-x ctr

Undo, redo, revert

Snd supports 'unlimited undo' in the sense that you can move back and forth
in the list of edits without any obvious limit on how long that list can
get. The data displayed is always the edited form thereof. Each editing
operation extends the current edit list; each undo backs up in that list,
and each redo moves forward in the list of previously un-done edits. Besides
the Edit and Popup menu options, there are these keyboard commands:

  C-x r     redo last edit
  C-x u     undo last edit
  C-x C-r   redo last edit
  C-x C-u   undo last edit
  C-_       undo last edit

Revert is the same as undoing all edits.

Play

To play a sound, click the 'play' button. While it is playing, you can click
the button again to stop it, or click some other file's 'play' button to mix
it into the current set of sounds being played. To play from a particular
point, set a mark there, then click its 'play triangle' (the triangular
portion below the x axis). To 'rock the reels', that is to play while
dragging the mouse back and forth, drag the mark's play triangle. The Edit
menu 'Play' option plays the current selection, if any. The Popup menu's
'Play' option plays the currently selected sound. And the region and file
browsers provide play buttons for each of the listed regions or files. If
you hold down the control key when you click 'play', the cursor follows
along as the sound is played. If you stop the play in progress, the cursor
remains where you stopped it, but otherwise returns to its original
position. Type space (without control) to pause and continue during
playback.

In Linux, the soundcard input lines are sometimes left active by default,
causing an amazing amount of hum and whatnot. To try to turn these off, call
the M-x function clear-inputs.

The color of the play button corresponds to the state of the playback:
normal: not playing, blue: playing, green: playing and tracking with the
cursor (if any), red: playback paused.

The keyboard commands for playing are:

  C-q    play current channel starting at the cursor
  C-t    stop playing
  C-x p  play selection or region (numeric arg selects region)

Except in the browsers, what is actually played depends on the control
panel.

Mix Files

Since mixing is the most common and most useful editing operation performed
on sounds, there is relatively elaborate support for it in Snd. Each
individual mix portion has a "mix console", a small box displayed above the
waveform containing various controls. These consoles follow the sync buttons
where relevant. More importantly, consoles can be edited together by
collecting related mix portions into a group, then firing up the Group
Editor (via the View menu Groups option). In a sense, a group can be viewed
as Snd's way of implementing a more normal mixer's "tracks".

To mix in a file, use either the File Mix menu option or the command C-x
C-q. Currently the only difference between these two is that the Mix menu
option tries to take the current sync state into account, whereas the C-x
C-q command does not. To mix a selection, use C-x q. The mix starts at the
current cursor location.

The Mix Console

When a section or file is mixed into the current file a mix console is
associated with it, each output channel getting its own console. The console
is displayed at first as a row of widgets giving the input file name, the
begin and end times of the mixed-in portion (click to change from seconds to
samples), then three icons:

  a speaker:   while pushed, the input is played
  an 'x':      click to remove the console permanently
  a box:       click to open (or close) the console

[picture of mix console]

You can drag the widgets to change the position of the mix. Once opened,
each console presents a pane with an amplitude slider for each input
channel, and a speed control (srate change on the input). The initial state
of the console sets the speed to 1.0, and all the input amplitudes 0.0
except the channel that matches the current output channel, which is set to
1.0 (a straight mix). To return to this state at any time, click the 'amp:'
label. To turn the mix off ('mute' it, set all amps to 0.0), double click
the label; to return to the last settings you made, click it with control or
meta down. Similarly, click the 'speed:' label to reset it to 1.0, and click
it with control or meta to return to your last settings. Each time you
release the mouse button (or click the amp label) counts as another 'edit'
of the file, so it is usually better to use 'undo' and 'redo' in this
context, rather than repeated clicks and shift-clicks. The srate scale is
interpreted in the same way as the sound pane speed control -- as a float
normally, but also, if you like, quantized to semitones or integer ratios.

To change the scale interpretation, set the variables mix-amp-scaler,
mix-speed-scaler, and in the group editor mix-tempo-scaler; all default to
1.0 which gives a scaling from 0 to around 12. These numbers actually scale
an exponent, so (for example) if mix-amp-scaler is set to 0.5, the scale
goes from 0.0 to around 3.5; similarly if mix-tempo-scaler is 0.025, its
scale goes from around .95 to 1.05.

To reduce the mix console to the single letter 'M', double click the file
name. Double click the 'M' to return to the original row of icons. Since
screen space is at a premium, this minimal form of the console can reduce
clutter. You can still drag the 'M' to reposition the mix.

When any edit is performed that changes the file within the mixed portion,
the affected mix consoles are removed from the display, and the only way to
return to them is to undo the offending edit. That is, if you mix a portion,
then cut some part of that portion, the mix will be locked in place from
then on, as if you had clicked the 'x' button on the mix console.

To turn off the constant graphics updates (which can slow down old machines
like mine, and which can also be annoying when you know what you're doing),
set the variable movies to 0 (it is also accessible in the Group Editor).

When a sound is mixed into a file that has its sync button on, the separate
channels are tied together so that as long as the sync button is on, if you
move one mix console the other sync'd consoles move with it. Similarly, any
speed change is reflected automatically in the other consoles; amplitude
changes however, are not copied. To make the sync'd consoles independent,
turn off the sync button. Once unsync'd, the consoles remain independent
unless you 'undo' enough edits to return to the sync'd state.

Normally the console is lined up with its left edge at the beginning of the
mixed segment. You can move the console anywhere within the segment by
placing the cursor at the position you want to mark the left edge of the
console, then control-click in the console title.

To get an indication of the start and end points of the mix segment, set the
group editor "show duration" button, or set the Snd variable
mix-duration-brackets to 1.

Grouped Mixes

To tie together an arbitrary collection of mix consoles, use the 'group'
buttons in the upper right corner of the mixer. Any mixers that share a
button can be changed in parallel using the Group Editor (the Groups option
under the View menu). The group editor gives amplitude control over each
output channel that has a mix that is a member of the group. The speed
control affects the sampling rate, and the tempo control affects the spacing
of the individual members of the group. The play button plays just the group
members.

The group editor envelope fields use the same syntax as other Snd envelopes:
(0 0 1 1) is a ramp, for example, and (0 0 1 1 2 0) is a sort of pyramid.
The envelope data in a given field only takes effect after the field has
been "activated" (normally by a carriage return). The tempo envelope is
interpreted in terms of the current group times using the placement of the
given mix within the group to find the parallel place on the (arbitrary)
tempo envelope x axis. The value of the envelope at that point becomes
another tempo multiplier; that is, these envelopes are not time maps
(perhaps someday!). Since a tempo value of 2 makes things happen twice as
slowly (it essentially multiplies begin times), the tempo envelope causes
things to go faster as it gets closer to zero -- weird! The speed envelope
changes the overall speed of a given segment, but doesn't change within that
segment.

The underlying mix consoles have independent envelopes, but my original plan
to include envelope text fields in the consoles made them too big,
cluttered, and unwieldy; an attempt to make each console a scrollable (or
paned) window failed due to unfortunate limitations in Motif. These could be
overcome, but would require much more programming than I think the issue is
worth. I'm interested in better ideas, if anyone has any. One idea I'm
goofing around with makes the mix matrix entries visicalc-like expressions.

To move the cursor from one mix to the next, in the same manner as C-j moves
through marks, use C-x C-j. You can also use the M-x function mix-position.
The following functions act like lisp structure references (that is, they
return their current value, or set it to a new value if called inside setf):

  mix-position n     mix begin sample
  mix-length n       mix segment length (change at your own risk!)
  mix-anchor n       mix anchor position within segment
  mix-state n        console state
  mix-groups n       which groups mix is associated with (bits)
  mix-amp n m        current mix input scaler on chan m
  mix-speed          current mix speed

The 'n' in each case is the (arbitrary) number of the mix as assigned by
Snd. To get this number, click the console title bar. M-x (setf
(mix-position 1) 1234) moves mix number 1 to sample 1234; M-x (mix-amp 1 0)
returns the current scaler on the first input channel of mix 1. Clicking in
the title bar also causes the console in question to move to the front of
the console stack -- use this to get at consoles that are lying underneath
others nearby.

Similar functions access the group state:

  group-amp n m      group n, amp for chan m
  group-tempo n
  group-speed n
  group-beg n        in seconds (moves all associated mixes)
  group-end n        in seconds (moves all assoicated mixes)

Group Changes and Undo

Since a mix is viewed in Snd as just another edit which you can undo and
redo, and since one mix console can be participating in any number of
groups, and since any number of files can have these grouped mixes active at
once, and since you can ungroup a mix, then undo the related edit, it
becomes a bit of a pain to describe what each sequence of actions will do.
In general, think of a group as simply another kind of 'sync' button. The
Group Editor itself does not follow the undo/redo chains (edits in Snd are
considered to be local to each channel, but the group editor affects all
mixes together, possibly across many channels). Each change to a group
control immediately affects all mixes associated with that group, in each
case as a single edit of each participating channel. Each change to the mix
console takes into account the state of the groups that it is a member of.
Undo of any edit simply undoes the edit -- the mix console will back up one
state, but if the group controls have changed in the meantime, the two are
now out of sync. Similarly, if you remove a mix from a group, the group's
effect upon the mix is removed as well. If it joins a group with current
state, that causes an immediate change in the mixed portion's state. The
tempo control, however, only affects mixes that are under its control when
it is changed (does that make sense? -- the idea is that you might want to
leave a group briefly to fix a local mix position or speed, then rejoin the
group, but in that process you don't want the tempo control to cause the mix
to jump about randomly in time). Similar complications affect the group
envelopes. You can choose whether the envelope is applied over the entire
output duration, or just the group duration; in the latter case, you need to
be aware that adding or removing mixes can change that duration, changing
the effect of the envelope. Group state changes by themselves are not edits
(i.e. if a group has no members, undo and redo will not notice that you've
been fiddling with its amp scalers). If a mix is participating in several
groups, all associated groups affect the mix together (group states are
multiplied, and envelopes are "melded" into something resembling a gathering
of the various envelopes). If a mix is synced to others, and joins or leaves
a group, all the synced mixes follow its lead. All of this can be
summarized: groups act like the sync buttons. And if it's confusing,
consider the alternatives; or better, decide once and for all which mixes
are grouped together, and use only one group per mix. Then everything should
be "intuitive".

Extend the editor

For full details, see the Extensions chapter. The keyboard commands
associated with these external functions are:

  C-h      repeat last external function call
  C-x h    apply external function to selection
  C-x y    prompt for and apply external function to selection
  C-x C-h  external function call
  C-x C-l  load external function from shared library
  C-x C-y  set up external function to be called whenever window changes

Keyboard macros

As in Emacs, C-x ( begins keyboard macro definition, C-x ) ends it, and C-x
e executes the last keyboard macro. Unlike Emacs, C-x C-e prompts for a name
for the last defined macro; Meta-x name invokes the macro "name", the
command save-macros saves all current named macros, and save-macro saves one
(named) macro in the initialization file (normally .snd). You can define
your own macros in that file using the lisp-like customization syntax:

(defmacro jump ()
  (key f 4)
  (show-controls))

moves the cursor ahead one sample and opens the control panel. We can invoke
this in Snd with M-x jump. Use global-set-key to map a single (unmodified)
keystroke to a macro:

  (global-set-key "a" 'hiho)

maps the keystroke "a" (case-sensitive) to the macro "hiho".
global-unset-key removes any macro associated with its key argument. A macro
can call other macros. I may extend the syntax here to include more of Lisp,
but currently a macro is just a list of commands.

Change file format

To change header or data format, use the File or Edit menu Save as option:

[picture of save as dialog]

Choose the header type you want, then the data format, (the data format list
will change depending on the header choice). The File version saves the
current selected file. The Edit version saves the currently selected region.

Extend a File

Normally Snd keeps the current cursor, and therefore most actions you can
perform on the current channel, within the current channel's bounds. The
easiest way to extend the file is to pad it with zeros. Go to the end of the
file, via the C-> command, then use the C-u command with a float argument,
giving the number of seconds to add to the end of the file, followed by C-o
(insert zeros): for example, to add a second, C-> C-u 1.0 C-o. The same
sequence can be used to add silence to the start of a file.

Miscellaneous commands

C-g at any point aborts the current keyboard command sequence, as does any
mouse click.

C-u introduces a numeric argument. Besides the integer and float cases
mentioned several times above, you can also use marks to set the argument.
If the (optional) number after C-u is followed by C-m, the resultant number
passed to the command is the distance (in samples) from the cursor to the
n-th successive mark. That is C-u C-m C-f is the same as C-j.

C-x introduces an 'extended command'. It can be preceded by a numeric
argument or aborted with C-g. C-x halts any on-going region definition.

C-x d prompts for the temporary directory name. Snd saves some editing
operations in temporary files, rather than in-core buffers. If the temporary
directory has been set (in various ways), it is used; otherwise Snd looks
for the TMPDIR environment variable; if it is not found, or is null, the
directory /var/tmp is used.

C-x C-c closes the control panel. C-x C-o opens the panel.

C-x C-x evaluates an expression; C-x C-n re-evaluates it.

----------------------------------------------------------------------------

Keyboard Commands

There are two types of keyboard commands in Snd: those associated with the
Meta ('Alt') key, used as mouse equivalents for various menu options, and
all the rest. The menu-related commands are shown underlined in the menubar.
You type the underlined letter with Meta, then just the letter (no Meta) of
the option you want. The menu-related commands are:

----------------------------------------------------------------------------

 File Menu        Edit Menu             View Menu               Options Menu           Help Menu

M-f o: Open      M-e u: Undo           M-v s: Show controls    M-o s: FFT size     M-h c: Click for help
M-f c: Close     M-e r: Redo           M-v n: Normalize        M-o p: Show peaks   M-h o: Overview
M-f s: Save      M-e f: Find           M-v c: Channel style    M-o l: Log freq            FFT
M-f a: Save as   M-e c: Cut            M-v i: Info             M-o d: FFT in dB           Find
M-f r: Revert    M-e p: Paste          M-v d: Dots                    FFT style           Undo and Redo
M-f m: Mix       M-e m: Mix selection         Verbose cursor          Speed style         Sync
M-f u: Update    M-e p: Play selection M-v r: Regions                 Focus style         Speed
M-f n: New       M-e s: Save selection M-v b: Files            M-o o: Subsampling off     Expand
M-f v: View             Edit History          Color            M-o a: Save options        Reverb
M-f p: Print                           M-v o: Orientation      M-o w: FFT window          Contrast
M-f x: Exit                                   Groups           M-o b: FFT beta            Envelope
                                       M-v m: Show marks              Session             Marks
                                       M-v y: Show y=0                                    Mixing
                                              Hide consoles                               Formats
                                              X axis units                                Customization
                                                                                          User functions
----------------------------------------------------------------------------

The rest of the keyboard commands refer to the currently active graph, and
any graphs that are currently sync'd to it. In general, commands are
analogous to Emacs where such an analogy exists; in other cases, an extended
command followed by a key with control affects the current channel whereas
the same key without control affects the selection. Case is not significant.

Most of the commands accept a numeric argument which can be either an
integer or a float; an integer causes the command to be repeated that many
times; the float is usually multiplied by the sound's sampling rate, then
applied that many times. So, for example, C-u 1.0 C-f causes the cursor to
move ahead one second in the sound. The argument can be negative to reverse
the sense of the command, as in Emacs. It is often useful to use the
distance to a mark as a count. If the C-u n command is followed by C-m, the
'n' determines how many marks to move to, then the count returned is the
distance from the cursor to that mark. For example, C-u C-m returns the
number of samples between the cursor and the next mark, so C-u C-m C-z zeros
all the samples between the cursor and the next mark.

The commands are:

  [Down]  zoom out
  [Up]    zoom in
  [Left]  move window left
  [Right] move window right
  [Home]  update current file (re-read data from disk)
  [Space] cancel and deselect selection, return to pre-select position
          if playing, pause or continue playback
  <:      move cursor to sample 0
  >:      move cursor to last sample
  C-<:    move cursor to sample 0
  C->:    move cursor to last sample
  C-a:    move cursor to window start
  C-b:    move cursor back one sample
  C-d:    delete sample at cursor
  C-e:    move cursor to window end
  C-f:    move cursor ahead one sample
  C-g:    abort current command
  C-h:    repeat external function call
  C-i:    display cursor info
  C-j:    go to mark
  C-k:    delete one line's worth of samples
  C-l:    position window so cursor is in the middle
  C-m:    place (or remove) mark at cursor location
  C-n:    move cursor ahead one 'line'
  C-o:    insert one zero sample at cursor
  C-p:    move cursor back one 'line'
  C-q:    play current channel starting at cursor
  C-r:    repeat last search backwards
  C-s:    search according to an expression
  C-t:    stop playing
  C-u:    start count (numerical argument) specification
  C-v:    move cursor to mid-window
  C-w:    delete current region
  C-x:    start extended command (see below)
  C-y:    paste in region
  C-z:    set current sample to 0.0
  C-_:    undo last edit
  C-[Space]: start region definition (arg<0 => cancel and deselect)

The extended commands (preceded by C-x) are:

  a:    apply envelope to selection
  b:    position window so cursor is on left margin
  c:    define selection from cursor to nth mark
  d:    get temp dir name
  e:    execute keyboard macro
  f:    position window so cursor is on right margin
  h:    apply external function to selection
  i:    insert region
  j:    go to named mark
  k:    close file
  l:    position selection in mid-view
  n:    re-evaluate expression over selection
  o:    move to next or previous graph
  p:    play selection or region n
  q:    mix in region
  r:    redo last undone edit
  u:    undo last edit
  v:    position window over current selection
  w:    save selection as file
  x:    evaluate expression over selection
  y:    get and apply external function to selection
  z:    smooth selection
  /:    place named mark
  (:    begin keyboard macro definition
  ):    end keyboard macro definition

  C-a:  apply amplitude envelope
  C-b:  set x window bounds (preceded by first sample number)
  C-c:  hide ("close") controls
  C-d:  print
  C-f:  open file
  C-g:  abort command
  C-h:  external function call
  C-i:  insert file
  C-j:  go to mix console
  C-l:  load user function from shared library
  C-m:  add named mark
  C-n:  re-evaluate expression
  C-o:  show ("open") controls
  C-p:  set window size (preceded by size)
  C-q:  mix in file
  C-r:  redo last undone edit
  C-s:  save file
  C-u:  undo last edit
  C-v:  set window size as percentage of total
  C-w:  save current channel in file
  C-x:  evaluate expression
  C-y:  set up auto-call of external function
  C-z:  smooth using cosine

----------------------------------------------------------------------------

The Control Panel

The control panel is the portion of each sound's display beneath the channel
graphs. It is normally hidden, except for the upper portion that shows the
file name, the sync and play buttons, and the minibuffer (the portion in
between that opens into a text window when activated).

                       [picture of Snd control panel]

The controls are: amp, speed, expand, contrast, reverb, and filter.

'Speed' here refers to the rate at which the sound data is consumed during
playback. Another term might be 'srate'. Snd uses linear interpolation to
perform the speed change (this may improve in the near future -- it's a mere
matter of software). The arrow button on the right determines the direction
we move through the data. The scroll bar position is normally interpreted as
a float between .05 and 20. The Options Speed Style menu (or the speed-style
variable) can change this to use semitones (actually microtones) or
just-intonation ratios. The number of equal divisions to the octave in the
semitone case is set by the variable speed-tones (normally 12).

'Expand' refers to a kind of granular synthesis used to change the tempo of
events in the sound without changing pitch. Successive short slices of the
file are overlapped with the difference in size between the input and output
hops (between successive slices) giving the change in tempo. This doesn't
work in all files -- it sometimes sounds like execrable reverb or is too
buzzy -- but it certainly is more robust than the phase vocoder approach to
the same problem.

There are a variety of variables that control expand's hop sizes, segment
lengths, and overall segment envelopes. These can be set in the minibuffer
via C-x C-x, or in your Snd init file. In the former, the syntax is C-like;
in the latter, Lisp-like. The variables are:

  exprmp: the length (percentage of the grain envelope) of the ramp (.4, 0 to .5)
  explen: the length (seconds) of each slice (.15)
  exphop: the hop size (.05) (also seconds)

The expander is on only if the expand button is set.

The reverberator is a version of Michael McNabb's Nrev. In addition to the
controls in the control pane, you can set the reverb feedback gain and the
coefficient of the low pass filter in the allpass bank. The variables are
'revfb' and 'revlp'. The reverb is on only if the reverb button is set. The
reverb length field takes effect only when the reverb is set up (when the
DAC is started by clicking 'play' when nothing else is being played).

'Contrast enhancement' is my name for a somewhat weird waveshaper or
compander. It phase-modulates a sound, which can in some cases make it sound
sharper or brighter. For softer sounds, it causes only an amplitude change.
To scale a soft sound up before being 'contrasted', use the variable
contrast_amp. The function maxamp (M-x maxamp) returns the channel's max
amp, so the inverse of that is a good first guess for contrast_amp. Contrast
is on only if the contrast button is set.

The filter is an arbitrary order FIR filter specified by giving the
frequency response envelope and order in the text windows provided. You can
also specify the filter coefficients in a file of floats, then load them
into the Snd filter by typing the file name in the filter envelope text
window. The filter is on only if the filter button is set.

The 's' (for 'Save') button saves the current control panel state for a
subsequent 'Restore'. The 'r' (for 'Restore') button returns the control
panel to the state at the time of the last save, or the initial state if
there has been no save.

Except for the filter setting and the reverb length setting, the controls
can be changed as the sound plays. You can record the changes you make by
setting the 'Record' button, and replay the new version later with 'Replay'.
The latter actually takes effect only when play is set in motion. 'Replay'
and 'Record' can be set at the same time, allowing you to add more changes
or override previous ones. To take all the current recorded changes and turn
them into a giant 'edit' of the file, click the 'Apply' button. Apply may
change the length of the file; for example, if reverb is on, the reverb
decay length (revdecay) is added onto the end. Once Apply has taken effect,
the controls section is not currently reset to its clean state, so to hear
the applied version of the sound (i.e. to hear the effect of the edit you
just did by clicking Apply), remember to click the 'r' button to reset the
controls. Maybe this should be the default...

Snd's control panel is not intended to replace mixers or CLM -- I view it as
a quick-and-dirty 'cartooning' facility. After finding useful settings,
you'll want to save the recorded changes and run them through CLM or some
other hi-fi signal processing system.

The keyboard commands associated with the control panel are:

  C-x C-o   show ("open") control panel
  C-x C-c   hide ("close") control panel

----------------------------------------------------------------------------

Customization

Nearly everything in Snd can be set in an initialization file, read after a
system crash from an automatically generated backup file, loaded any time
from a session file, specified via inter-process communciation from any
other program, invoked via M-x, or imbedded in a macro. The syntax used is
lisp-like; the point of view adopted here will be that of someone writing an
intialization file to customize his version of Snd. The same syntax is used
in the backup file (normally called ".snd-backup"), the initialization file
(normally called "~/.snd"), the IPC channel (see snd-test.cl for an example
of the latter), macro definitions, and session files. The commands that Snd
recognizes in these contexts are:

          ;; File Menu
 (open file)              ;open file read/write
 (close file)             ;close file, add to previous files list
 (save file)              ;save current edits to file
 (save-as file1 file2)    ;save current state of file1 as file2
 (revert file)            ;cancel edits, if any, to file
 (view file)              ;open file read-only
 (new)                    ;create new (empty) file
 (print)                  ;print current graphs
 (exit)                   ;exit Snd

          ;; Edit Menu
 (undo n)                 ;undo last n edits in current channel
 (redo n)                 ;redo last n undone edits in current channel
 (find expr)              ;find sample that satisfies expr
 (cut)                    ;delete selected data, add to region stack
 (paste n)                ;paste region n at current cursor position
 (play file) (stop file)  ;play or stop playing file

          ;; View Menu
 (show-marks) (hide-marks);show or hide marks
 (show-y-zero)            ;show or
   (hide-y-zero)          ;  hide the y=0 line (normally hidden)
 (dots) (lines)           ;show waveforns using dots or lines
                          ;dot-size variable (keypad ".") sets size of dot
 (unite) (separate)       ;combine or separate channels in multi-channel sounds
 (normalize)              ;normalize Snd display
 (info)                   ;show sound type, header comment etc
 (show-controls)          ;show or
   (hide-controls)        ;  hide the control panel
 (show-consoles)          ;show or
   (hide-consoles)        ;  hide the mini-mix control panels

          ;; Options Menu
 (show-peaks) (hide-peaks);fft display can include peaks
 (peaks)                  ;place peak data in text window
 (fft-style n)            ;0=normal, 1=sonogram, 2=spectrogram
 (focus-style n)          ;0=window left, 1=window right,
                          ;2=active entity (cursor or region), 3=window middle
 (fft-dB) (fft-linear)    ;choose fft amplitude axis scaling (log or linear)
 (fft-log-freq)           ;choose fft frequency axis scaling (log or
    (fft-linear-freq)     ;  linear)
 (subsampling-on)         ;turn data subsampling on or
    (subsampling-off)     ;  off
 (silent-cursor)          ;turn minibuffer info about cursor position off or
    (verbose-cursor)      ;  on

          ;; Snd as a whole
 (fit-data)               ;show full file and match y axis to data excurion or
   (dont-fit-data)        ;  show first .1 secs and use y axis limits of -1.0 to 1.0
 (default-output-type n)  ;region temp file header choice
 (disconnect)             ;close IPC fifos (named pipes)
 (clear-inputs)           ;try to turn off soundcard input lines (Linux)

          ;; Sound window
 (sound file)             ;return the sound data in file (for CLM)
 (data beg num)           ;return data in current channel (for CLM)
 (goto-sound file)        ;select file
 (goto-channel file chan) ;select channel of file
 (select-sound n)         ;select the nth sound in the current sound list
 (select-channel n)       ;select channel n in current sound
 (sync) (unsync)          ;set or unset sync button of currently selected sound
 (save-controls)          ;save or
   (restore-controls)     ;   restore the control panel settings
 (amp-env beg dur scl env);apply amp env to current synced channels
                          ;   from beg for dur (both in samples) scaled by scl
 (amp-envelope env)       ;same as amp-env but assume 0 to end with scl=1.0
 (selection-amp-envelope env)
 (scale-by ...)           ;amplitude scaling
 (scale-to ...)           ;amplitude scaling

          ;; Channel window
 (x-axis low high)        ;set x axis bounds
 (y-axis max)             ;set y axis max (normally 1.0)
 (axes x0 x1 y0 y1)       ;set x and y axis bounds (floats)
 (maxamp)                 ;return current channel maxamp
 (save-marks)             ;write current marks (sound-relative) to filename.marks
 (goto-mark name)         ;move cursor to named mark
 (mark name)              ;return sample associated with named mark
 (delete-mark)            ;delete mark at cursor
 (setf (mark name) sample);place mark at sample
 (show-fft) (hide-fft)    ;show or hide the fft window
 (show-wave) (hide-wave)  ;show or hide the time-domain waveform

          ;; various browsers
 (preload directory)      ;add sounds in directory to previous files list
                          ;  (preload .) -> preload current directory
 (preload-files-browser list-of-files)
                          ;put list of files in previous files list
                          ;  (preload-file-browser pistol.snd fyow.snd)
 (raw-sound srate chans format defaults)
                          ;set raw data file defaults
 (color-dialog width height)
                          ;start the color dialog (size = width by height)
 (orientation-dialog width height)
                          ;start the orientation dialog
 (file-dialog width height)
                          ;start the file browser
 (just-sounds) (all-files);in the file selection box, either set
                          ;  or unset the just-sounds button

          ;; regions
 (region n)               ;return data of region n
 (setf-region low high)   ;define region from sample low to high
 (insert beg num)         ;insert data at beg for num samples
 (change beg num)         ;change data (new data follows)
 (delete beg num)         ;delete section from beg for num
 (temp-dir dir)           ;set the temporary file directory to dir
 (scale-selection-by ...) ;region amplitude scaling
 (scale-selection-to ...) ;region amplitude scaling
 (copy)                   ;copy region to X/Motif clipboard (normally disabled)

          ;; keyboard
 (command cmd state)      ;mimic keyboard cmd, state: control/shift/meta (4/1/8)
 (key key state)          ;key = char here, not ASCII as in command
 (global-set-key key val) ;map key (no control/meta bits) to macro named val
 (global-unset-key key)   ;unmap key (applies only to keystroke without control or meta bits)

          ;; parser
 (float a)                ;declare a new variable
 (session file)           ;save current Snd state as text file of commands
 (load file)              ;load a file of these commands
                          ;  (e.g. continue earlier session or get saved macros)

 (load-function lib fun)  ;load external function from shared library
 (function fun)           ;call the external function

 (save-macros)            ;save all current macros at end of init file
 (save-macro name)        ;save the current macro under name
 (eval expr)              ;send expr to the C-style parser/evaluator
 (tickle-clm)             ;try to unwedge a stuck CLM-Snd interface
 (report-in-minibuffer str) ;print str in minibuffer of currently active sound
 (append-to-minibuffer str) ;append str to minibuffer contents

The variables that Snd recognizes (in this case) are:

   cursor x                     ;cursor sample number
   y                            ;value of sample at cursor
   window-height window-width   ;Snd overall window size (pixels)
   fft-window fft-size fft-beta ;various fft choices
   normalize-fft                ;whether to normalize fft data to 1.0
   zero-pad                     ;fft zero padding factor (default 0 = none)
   dot-size                     ;if using dots, dot size in pixels
   line-size                    ;number of samples for line-oriented commands
   y-max                        ;y axis limit
   remember-state               ;auto-save flag
   combine-channels             ;combined channels flag
   auto-open                    ;should newly opened file view be normalized
   x-axis-style                 ;seconds, samples, etc
   speed-style                  ;speed control interpretation (0=float, 1=ratio, 2=semitones)
   speed-tones                  ;octave divisions for semitone calculation above
   initial-x0/x1/y0/y1          ;initial axis bounds when file is first read in
                                ;  if initial-x1 == 0, the full file is displayed
   xmax,xmin,ymax,ymin          ;max axis settings
   movies                       ;update waveform as mix console moves
   mix-duration-brackets        ;show mix segment extent
   mix-amp-scaler mix-speed-scaler mix-tempo-scaler
   overwrite-check              ;overwriteCheck resource
   include-cwd                  ;includeCwd resource

        ;; the various control panel settings:
   expand-button contrast-button reverb-button filter-button
   amp speed contrast expand revscl revlen filter-order filter

        ;; associated, but undisplayed variables
   explen exprmp exphop revfb revlp contrast-amp revdecay follow-play

        ;; color and orientation settings
   color-scale sono-max spectro-[xyz]angle spectro-[xyz]scl
   wavo-hop wavo-trace spectro-hop
   color-cutoff color-inverted spectro-color sono-color

        ;; raw (no header) file descriptions
   raw-srate raw-chans raw-format raw-defaults header-type

The operations setf, setq, incf, and decf can be used to change these
variables. 'cursor' refers to the position of the currently active cursor.
'window-height' and 'window-width' refer to the overall main Snd window. The
'x-axis-style' variable controls the ticks and labels on the x axis. The
default (0) is to display seconds; x-axis-style of 1 displays samples, 2
displays the current window in terms of 0.0 to 1.0 (where 1.0 is the end of
the file) -- a sort of percentage. The 'speed-style' variable controls
interpretation of the control panel's srate slider: as a float (the default
= 0), a smalle integer ratio (1) or a semitone (2). 'speed-tones' sets the
number of equal divisions of the octave in the 'semitone' case (normally
12).

The spectrum data is usually normalized to fit between 0.0 to 1.0; if you'd
rather have un-normalized data (the y-axis in this case changes to reflect
the data values, to some extent), set the variable normalize-fft to 0.

In addition, if Snd is connected to an ACL version of CLM, any lisp
expression can be typed to M-x; it will be sent to CLM and the result will
be returned to Snd and printed in the minibuffer (if any). Such expressions
can include such CLM calls as to-snd, so, for example, to run a CLM notelist
and automatically open the result as a new sound all from the Snd minibuffer
(as opposed to doing the same thing from the Lisp listener):

  M-x (to-snd () (fm-violin 0 1 440 .10))

This command runs with-sound with the given note, produces test.snd, or
whatever, then opens that file in Snd.

As an example of an initialization file, say we always want the fft graph
with its associated peaks displayed; and the file browser to default to
listing only sound files; and any multichannel file to combine its channels
into one graph. We create the file "~/.snd" and place in it:

(show-peaks)
(show-fft)
(just-sounds)
(setf combine-channels 1)

The peaks command opens a help window with the fft peak information,
including the unscaled, linear amplitudes.

Saved State and Sessions

If you'd like Snd to start up in the state you left it in upon last exiting
(within reason), set the variable remember-state to 1. This causes Snd to
write the .snd-backup file just before exiting; it will then read that file
the next time it is invoked if it doesn't have any other arguments. At any
time you can save the current state of Snd by calling (session name) where
name is a file name. You can start in this state by calling Snd with this
file name and the "-l" switch: snd -l name. This is called a session file,
but it is in exactly the same format as the initialization file discussed
above, and can be edited, renamed, or whatever. To load such a file after
startup, use the command load: M-x (load name).

Snd resources

There are a few X-style resources that Snd explicity looks for (see Snd.ad):

initFile       "~/.snd"
backupFile     ".snd-backup"
epsFile        "snd.eps"
overwriteCheck 0
groups         6
includeCwd     1

buttonFont     -*-times-medium-r-*-*-14-*-*-*-*-*-iso8859-1
boldbuttonFont -*-times-bold-r-*-*-14-*-*-*-*-*-iso8859-1
axisLabelFont  -*-times-medium-r-normal-*-20-*-*-*-*-*-iso8859-1
axisNumbersFont -*-courier-medium-r-normal-*-14-*-*-*-*-*-iso8859-1
helpTextFont    9x15

useSchemes      none
lightestcolor   ivory1
basiccolor      ivory2
darkcolor       ivory3
darkestcolor    ivory4
textcolor       lightsteelblue1
cursorcolor     cyan ! (in Linux: red)
selectioncolor  ivory4
mixercolor      lightgreen
groupcolor      red

You can experiment with other choices by using the -xrm command line
argument:

  snd -xrm '*Lightestcolor: Red' oboe.snd
  snd -xrm '*AxisNumbersFont: 6x10' oboe.snd
  snd -xrm '*overwriteCheck: 1' oboe.snd
  snd -xrm '*useSchemes: all' -xrm '*scheme: Pacific'
  snd -xrm '*fontList: 9x15' oboe.snd

The color names can be found in /usr/lib/X11/rgb.txt. There's a list of
widget names for Xresource files, now somewhat out-of-date, in the file
snd-widgets.txt. If you use SGI color schemes, the color resources mentioned
above are ignored. If overwriteCheck is 1, Snd asks before overwriting
existing files. If includeCwd is 0, Snd does not pre-load the various file
name prompts with the current working directory.

----------------------------------------------------------------------------

Extensions

You can load your own analysis, editing, or display functions into Snd.
These functions have access to all the sound data and can operate on it in
many ways. There are several examples of user functions in the Snd source
file snd-ufunex.c, normally loaded into sndlib.so during the Snd make
process. These examples should give an idea of how to add your own favorite
functions to Snd. I've tried to provide copious comments in the source to
explain what's going on. Due to limitations in shared object files, the
communication path between Snd and a user function is somewhat peculiar.

The interface is defined in snd-ufun.h; briefly, a user function is loaded
via C-x C-l or the command (load-function library function). In both cases
the arguments are unquoted. For example, the rms function in snd-ufunex.c
can be loaded into Snd with:

C-x C-l sndlib.so,rms

Once loaded, the function can be invoked with:

C-x C-h rms

and thereafter with C-h. If instead, you invoke the function with C-x C-y,
the function will be called automatically thereafter each time the data in
the channel window changes. This can be cancelled by giving a '-' argument
to C-x C-y. Beware of setting up an automatic call to a function that edits
the Snd data! To apply the function to the current selection, use C-x h or
C-x y. Arguments can be passed to the user function:

C-x C-h a_func(4,3.14)

See snd-ufunex.c if you're interested in writing one of these functions.

                     [picture of Snd with user function]

Here we are running the sonogram with sono_max set to .5, and the
autocorrelation function in sndlib.so, invoked with C-x C-y so that it
updates automatically alongside the sonogram.
----------------------------------------------------------------------------

Planned Enhancements

On my list of things to do: integrate Snd much more closely with CLM, with,
in particular, single-value run-time variable display and an edit history
mechanism; add more external functions to sndlib.so -- perhaps more
transforms and some sort of wavelet package; make the fft and user-function
graphics editable; use a fancier sampling rate conversion function if
current machines can keep up with it; enable multiple views of the same
file; add a sine probe tone window; add a graphical envelope definition
window; perhaps add an fft-filtering dialog; look at possible ports to
Windows 95, Openstep, perhaps the Be; add escape-to-Snd applets to this
document; add a record, or CD read option; finish the mix console stuff;
make the file update option more debonair; add displays oriented toward
SMS-style data; improve the filter design function; make separate sounds
superimposable; add arguments to macros; add mark-oriented annotations;
document or perhaps enhance the Matlab connection.

----------------------------------------------------------------------------

Index

                                          Index

        Action           Menu       Keyboard          M-x                 Other
 abort command                    Cg                             mouse click
 amp env                          Cx Ca, Cx a amp-env            scale-to, scale-by
 autocall external
 func                             Cx Cy

 axis bounds                      Cx Cb, Cx   axes, [xy]-axis    -s switch to Snd
                                  Cp
 axis fits data                               fit-data
 call external
 function                         Ch, Cx Ch   function           Cx h -> selection
 center cursor                    Cl, Cv
 center selection                 Cx l
 change samples                   Cz, Cx Cz   change             see also external funcs
 close file          File: Close  Cx k        close
 color               View: Color              color-dialog       color-scale,color-cutoff
                     View:
 combine channels    Channel                  unite, separate    also setf
                     style                                       combine-channels
 compare files

 continue session    Options:                 load               -l switch to Snd
                     Session

 control panel       View: Show   Cx Co, Cx   show-controls      drag pane sash
                     controls     Cc
 count matches
 create new file     File: New                new
 cut selection       Edit: Cut    Cw          cut
 define mark                      Cx /, Cx Cm setf mark          also Cm

 define selection                 C[space],   setf-region        mouse drag
                                  Cx c
 delete mark                      - Cm        delete-mark
 delete samples      Edit: Cut    Cd, Ck      delete             see also external funcs
 describe file       View: Info               info               Popup: Info
                     View:
 describe sample     Verbose      Ci          verbose-cursor     also cursor, y
                     cursor

 dots or lines       View: Dots               dots, lines        dot_size: numberpad '.',
                                                                 '0'

 evaluate expression              Cx Cx, Cx   eval               over region: Cx x, Cx n
                                  Cn

 examine selections  View:                    region
                     Regions
 exit Snd            File: Exit               exit               mwm menu: close or exit
 extend file                      Co

 fft in dB           Options: FFT             fft-db
                     in dB

 fft log freq        Options: Log             fft-log-freq
                     freq
 fft normalization                            normalize-fft      normalize_fft

 fft peaks           Options:                 show-peaks         M-x peaks for full info
                     Show Peaks

 fft size            Options: FFT             fft-size           fft_size: numberpad:
                     size                                        '*', '/'

 fft window          Options: FFT             fft-window
                     window

 fft window parameterOptions: FFT             fft-beta
                     beta

 fft/sono/spectrogramOptions: FFT             fft-style [0]
                     style

 file formats        File: Save               raw-sound          defaultOutputType
                     as
 file lists          View: Files              file-dialog
 find                Edit: Find   Cs or Cr    find
 insert file                      Cx Ci
 insert samples                               insert             see also external funcs
 insert selection    Edit: Paste  Cy or Cx i  paste
 insert zeros                     Co, Cz
 keyboard macros                  C(, Cx e    defmacro           also command, key
 load external
 function                         Cx Cl       load-function

 load session        Options:                 load
                     Session
 max amp                                      maxamp
 mix file            File: Mix    Cx Cq
 mix selection       Edit: Mix    Cx q
 move cursor ahead                Cf, Cn, Ce  incf cursor        also >
 move cursor back                 Cb, Cp, Ca  decf cursor        also <
 move to mark                     Cj, Cx j    goto-mark          Cx j -> named mark
 move to mix                      Cx Cj       mix-position

 move window ahead                [Left], Cx                     scroll bars
                                  f

 move window back                 [Right], Cx                    scroll bars
                                  b
 multichannel ops                             sync               sync button

 normalize display   View:                    normalize          Popup: Normalize
                     Normalize
 numeric arguments                Cu                             see marks as args
 open file           File: Open   Cx Cf       open               Files dialog: click file
 open file read-only File: View               view

 orientation         View:                    orientation-dialog mapped to number pad
                     Orientation
 overwrite check                              overwrite-check    overwriteCheck
 play channel                     Cq, Ct

 play file           Popup: Play              play, stop         File or main window:
                                                                 'play'
 play selection      Edit: Play   Cx p
 preload directory                            preload            -p switch to Snd
 print file          File: Print  Cx Cd       print              epsFile resource
 redo edit           Edit: Redo   Cx Cr       redo               Popup: Redo
 revert file         File: Revert             revert
 save channel                     Cx Cw
 save control state                           save-controls      'save' button
 save file           File: Save   Cx Cs       save               Popup: Save

 save file as        File: Save               save-as            see also overwriteCheck
                     as
 save macros                                  save-macros        also session
 save marks                                   save-marks         also session

 save options        Options:
                     Save options

 save selection      Edit: Save   Cx w
                     selection

 save session        Options:                 session            also remember-state
                     Session
 select sound                     Cx o        goto-sound         File dialog: click file
 show freq domain                             show-fft           'f' button

 show marks          View: Show               show-marks
                     marks
 show time domain                             show-wave          'w' button
 smooth samples                   Cx Cz
 smooth selection                 Cx z

 sonogram            Options: FFT             setf fft-style 1   sono_color,sono_max
                     style

 spectrogram         Options: FFT             setf fft-style 2   orientation, scaling
                     style

 speed units         Options:                 speed-style        speed-tones
                     Speed style

 subsampling         Options:                 subsampling-on
                     Subsampling
 temp directory                   Cx d        temp-dir           TMPDIR or /var/tmp
 undo edit           Edit: Undo   C_ or Cx Cu undo               Popup: Undo
 update file         File: Update [Home]
 wavogram                                     wavo               wavo_trace, wavo_hop

 X axis units        View: X axis             x-axis-style
                     units

 y=0 line            View: Show               show-y-zero
                     y=0

 zoom focus          Options:                 focus-style
                     Zoom style
 zoom window                      [Up],[Down] axes, x-axis       control keys intensify
