Snd Customization and Extension

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

The syntax used throughout this documentation is Scheme (a form of lisp) as implemented by Guile or Gauche. You can also use Ruby or Forth, but need to make various minor changes. I'm slowly adding parallel Forth and Ruby examples.

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 color and Snd's responses are in this color):

>(+ 1 2)
3

>1+2
3

>1 2 +
3

>(open-sound "oboe.snd")
0

>open_sound("oboe.snd")
0

>"oboe.snd" open-sound
0

>(auto-resize)
#t

>auto_resize
true

>auto-resize
#t

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

>set_auto_resize false
false

>#f set-auto-resize
#f

>(set! (x-bounds) '(0.0 1.0))
(0.0 1.0)

>set_x_bounds([0.0, 1.0])
0.01.0

>'( 0.0 1.0 ) set-x-bounds
'( 0.0 1.0 )

>(load "bird.scm")
#<unspecified>

>load "bird.rb"
true

>"bird.fs" file-eval
0

>(map-channel (lambda (y) (* y 2)))
0

>map_channel(lambda do |y| y * 2 end)
-0.0015869140625

>lambda: <{ y }> y 2.0 f* ; map-channel
-0.00158691

>(define (plus a b) (+ a b))
#<unspecified>

>def plus(a, b) a+b end

>: plus ( a b -- sum ) { a b } a b + ;
nil

>(set! (basic-color) (make-color 1 0 0))
(Pixel 16711680)

>set_basic_color make_color(1, 0, 0)
[:Pixel, 16711680]

>1 0 0 make-color set-basic-color
#<XmRaw: Pixel 0x9d3b430>

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

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 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, examp.fs, and snd-test.scm. Extensions to Snd can be found in:

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

(define (unsaved-edits? 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! before-exit-hook (lambda () (unsaved-edits? (sounds))))

Now when Snd is told to exit, it checks before-exit-hook, runs unsaved-edits?, and if the latter returns #t, if prints a worried message in the minibuffer, and refuses to 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:

  Scheme: (auto-resize)
  Ruby:   auto_resize()
  Forth:  auto-resize

and set via:

  Scheme: (set! (auto-resize) #f)
  Ruby:   set_auto_resize(false)
  Forth:  #f set-auto-resize

The variables are presented as a special kind of function, rather than as bare variables, mainly to ensure that Snd's response to the assignment is immediate. The statement (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.

The variables affecting Snd's overall behavior are:

    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-next mus-aifc mus-riff mus-rf64 mus-nist mus-raw mus-ircam mus-aiff 
    mus-soundfont mus-bicsf mus-voc mus-svx mus-caff

Scheme:

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

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

Ruby:
def inches_to_ps(inches) 
  inches * 72 
end
def cm_to_ps(cm) 
  cm * 72.0 / 2.54 
end

Forth:
: inches-to-ps { inches } 
  inches 72 f* 
;
: cm-to-ps { cm } 
  cm 2.54 f/ 72 f* 
;

    0:  no optimization (use the standard Scheme parser/evaluator)
    1:  optimize simple stuff (if complex result possible, give up)
    2:  assume nothing will return a complex number
    3:  if an undefined variable is encountered, try to guess its type
    4:  make questionable assumptions about variable types
    5:  make dangerous assumptions about variable locations (for set!)
    6:  try to splice in user-defined functions

    (add-hook! optimization-hook (lambda (n) (display (format #f "opt: ~A~%" n))))

    >(set! (print-length) 3)
    3
    >(make-vct 10 .1)
    #<vct[len=10]: 0.100 0.100 0.100 ...>

  Scheme: (cadr (widget-size (cadr (main-widgets))))

  Ruby:   widget_size(main_widgets.cadr).cadr

  Forth:  main-widgets cadr widget-size cadr

    (car (widget-position (cadr (main-widgets))))

    (set! (zoom-focus-style) (lambda (snd chn zx x0 x1 range) (- x1 (* zx range))))

When some user-interface action takes place, code is called that responds to that action; these functions are sometimes called callbacks; the variable that holds a list of such callbacks is known as a hook. A hook provides a way to customize user-interface actions. The hook itself is list of functions. The 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":

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

  Ruby:   $name_click_hook.add_hook!("print") do |snd| snd_print("hi"); true end

  Forth:  name-click-hook lambda: <{ snd }> "hi" snd-print drop #t ; add-hook!

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 ("progn", the name coming 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 invocation. There are a variety of hook-related functions in hooks.scm.

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

    Open filename
        bad header?: bad-header-hook — can cancel request
        no header?:  open-raw-sound-hook — can cancel request
        file ok: 
             open-hook — can change filename
             file opened (no data read yet)
                 during-open-hook (can set prescaling etc)
             data read, no graphics yet
             after-open-hook
             initial-graph-hook
    
    
    Save current sound
        before-save-as-hook — can cancel the request or set its output parameters
        save-hook
            sound saved
              if any sample is clipped during save, clip-hook
        after-save-as-hook


    Play sound
        when a play request occurs: start-playing-hook — can cancel the request, also start-playing-selection-hook
            (any number of sounds can be playing at once)
        as each buffer is sent to the audio device: play-hook and dac-hook
        as each sound ends: stop-playing-hook, stop-playing-selection-hook
        close audio device: stop-dac-hook
    

    Close sound
        before-close-hook — can cancel close
        close-hook (sound is still open)
        sound closed
    
    
    Save current Snd ("session") state
        save-state-hook — can change output filename (crummy name is an historical artifact)
        output save-state file opened
            before-save-state-hook
            Snd saves its state
            after-save-state-hook
        output closed
    
    
    Exit Snd
        before-exit-hook — can cancel exit request
        exit-hook
        Snd cleans up and exits

You can find out what's on a given hook with the following (which is mostly adding carriage returns to the printout from hook->list):

(define (describe-hook hook)
  (for-each 
    (lambda (n) 
      (snd-print (format #f "~A~%" n)))
    (reverse (hook->list hook))))

Here's the Ruby version of some of the hook-related functions:

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

And some Forth examples, taken from Mike Scholz's documentation:

    open-hook ' open-buffer 1 make-proc add-hook!
    open-hook "open-buffer" remove-hook!
    open-hook reset-hook!
    open-hook hook->list
    
    2 "A simple hook." create-hook my-new-hook
    my-new-hook ' + 2 make-proc add-hook!
    my-new-hook '( 2 3 ) run-hook
    help my-new-hook             

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

In the following list of hooks, the arguments after the hook name refer to the arguments to the functions invoked by the hook. That is, after-apply-controls-hook (snd) means that the functions on the after-apply-controls-hook list each take one argument, a sound index. If the argument list is followed by some indication such as "[or]", that means the various hook function values are or-d together.

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

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

(define (report-fft-peak snd chn scale)
  (if (and (transform-graph?) 
           (= (transform-graph-type) graph-once))
      (report-in-minibuffer 
        (number->string (/ (* 2 (vct-peak (transform->vct snd chn))) 
                           (transform-size snd chn))))))
(add-hook! after-transform-hook report-fft-peak)

    (add-hook! bad-header-hook (lambda (n) #t)) ; don't open bogus-looking files

(add-hook! before-save-as-hook
  (lambda (index filename selection sr type format comment)
    (if (not (= sr (srate index)))
        (let ((chns (chans index)))
	  (do ((i 0 (1+ i)))
	      ((= i chns))
	    (src-channel (exact->inexact (/ (srate index) sr)) 0 #f index i))
	  (save-sound-as filename index :header-type type :data-format format :srate sr :comment comment) 
	  ;; hook won't be invoked recursively
	  (do ((i 0 (1+ i)))
	      ((= i chns))
	    (undo 1 index i))
	  #t) ; tell Snd that the sound is already saved
	#f)))

(add-hook! before-save-state-hook
  (lambda (name) 
    (with-output-to-file name
      (lambda ()
        (display (format #f ";this comment will be at the top of the saved state file.~%~%"))
	#t))))

(add-hook! before-transform-hook
  (lambda (snd chn)        ; 0.5 * (left + right) = midpoint
    (inexact->exact (round (* 0.5 (+ (right-sample snd chn) (left-sample snd chn)))))))

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

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

$close_hook.add_hook!("play") do |snd| 
  system("aplay wood16.wav")
end

    (add-hook! drop-hook (lambda (filename) (mix filename) #t)) ; return #t = we already dealt with the drop

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

    0: reopen a temporarily closed file (internal to Snd — normally invisible)
    1: sound-open, File:open etc — the normal path to open a sound
    2: copy reader — another internal case; this happens if a sound is played and edited at the same time
    3: insert sound (File:Insert etc)
    4: re-read after an edit (file changed, etc — an invisible editing case)
    5: open temp file after an edit (another invisible editing case)
    6: mix sound (File:Mix etc)

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

    (add-hook! exit-hook (lambda () (for-each save-peak-env-info (sounds))))

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

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

    (list x0 x1 y0 y1 label ymin ymax)

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

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

(add-hook! initial-graph-hook
  (lambda (snd chn dur)
    (if (or (mus-sound-maxamp-exists? (file-name snd))
            (< (frames snd chn) 10000000))
	(let* ((amp-vals (mus-sound-maxamp (file-name snd)))
	       (max-val (max 1.0 (list-ref amp-vals (+ (* chn 2) 1)))))
               ;; max amp data is list: (sample value sample value ...)
	  (list 0.0 dur (- max-val) max-val)) ; these are the new y-axis limits
	(list 0.0 dur -1.0 1.0))))            ; max amp unknown, so use defaults

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

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

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

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

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

(add-hook! mix-click-hook
  (lambda (n)
    (set! (mix-amp n) 0.0)
    #t))

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

    (add-hook! mix-drag-hook (lambda (id x y) (update-transform-graph)))

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

(add-hook! mouse-click-hook
  (lambda (snd chn button state x y axis)
    (if (and (= axis time-graph)
	     (or (= button 4) (= button 5))) ; mouse scroll wheel
	(let ((midpoint (* 0.5 (apply + (x-bounds))))
	      (dur (/ (frames) (srate)))
	      (range (if (= button 4)
			 (* -0.25 (apply - (x-bounds))) ; zoom in
			 (abs (apply - (x-bounds))))))  ; zoom out
	  (set! (x-bounds) (list (max 0.0 (- midpoint range))
				 (min dur (+ midpoint range))))))
    #f))

mouse-click-hook lambda: <{ snd chn button state x y axis -- }> 
 axis time-graph = if 
   $" freq: %.3f" '( snd chn #f cursor  snd chn spot-freq ) string-format 
   snd #f report-in-minibuffer 
 else 
   #f 
 then 
; add-hook! 

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

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

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

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

(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

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

(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) ; now open-sound will read the new .au file
	    #f)
	#f)))

    (add-hook! open-raw-sound-hook (lambda (file choices) (list 1 44100 mus-lshort)))