Soundmix Framework Reference

Overview

Soundmix Framework works by manipulating clips. A layout file can import audio files as file clips, and mix clips to create compound clips. Once the mixing is complete, the layout file can write clips to files.

Example

Here is a comprehensive example with comments:

;; First, load Soundmix Framework.
(load "soundmix-framework.lsp")

;; Tell the framework which version we are writing for.
;; If the framework is not compatible with that version, the
;; program will print a warning and exit.
(expect-soundmix-framework-version '0.4)

;; Set the output sample rate.
(set-soundmix-framework-sample-rate 44100)

;; Set the output channels. 2 is stereo. To pick mono,
;; use this instead:
;; (set-soundmix-framework-channels 1)
(set-soundmix-framework-channels 2)

;; Set the output processing. In this case, the output
;; is limited to 0dB to prevent overflow. For no output
;; processing use this instead:
;; (set-soundmix-framework-processing :none)
(set-soundmix-framework-processing :limit 0)

;; Import some audio files as file clips.
;; Each argument to defclips should be a (name path) pair.
;; The layout file will refer to the clips by name later.
(defclips
  (minus5 "minus5.wav")
  (plus5 "plus5.wav"))

;; Define times to be used as spaces or playing times later.
;; All times are in seconds.
(deftimes
  (a-space-time 1.5)
  (a-fade-time 0.5)
  (one-second-play-time 1))

;; Define some gains to be used for fades later.
;; All gains are in decibels.
(defgains
  (half-volume -6)
  (another-gain -12))

;; Define a compound clip. A compound clip is a list of
;; commands. Each line will be described in detail.
(defcompound intermediate-clip
  ;; The simplest command is play with a single argument.
  ;; It will play a clip for its duration.
  (play minus5)
  
  ;; The space command inserts silence for the specified
  ;; duration.
  (space a-space-time)
  
  ;; Space can also be used with a numerical argument, which
  ;; is in seconds.
  (space 3)
  
  ;; With the keyword argument :for, play will proceed only
  ;; for the specified duration.
  (play plus5 :for one-second-play-time)
  
  ;; :for can also take a numerical argument in seconds.
  (play plus5 :for 0.5)
  
  ;; Reset starts a clip over from the start, so it can be
  ;; used again.
  (reset plus5)
  
  ;; Clips start at full volume. Fade changes the volume
  ;; over a specified duration while playing the clip.
  ;; Like play, fade takes either a time or a number for
  ;; its :for keyword argument.
  (fade plus5 :to half-volume :for a-fade-time)
  
  ;; If fade's :to keyword can also be a number in decibels.
  ;; This line fades plus5 back to full volume.
  (fade plus5 :to 0 :for 0.5)
  
  ;; Without a :to argument, the clip is faded out to silence.
  (fade plus5 :for 0.2)
  
  ;; Without a :for argument, fade acts like play, playing
  ;; the clip until it ends.
  (fade plus5 :to -12)

  ;; Those are the basic commands. However, they have only
  ;; been shown with one clip at once.

  ;; Reset can be called with any number of clips to reset
  ;; them all.
  (reset minus5 plus5)
  
  ;; Play-2 is like play, but it plays two clips. If no :for
  ;; argument is given, it plays for the minimum remaining
  ;; duration of the clips.
  ;; NOTE: When two clips are played, they are added together,
  ;; which means that high-volume clips are at risk of creating
  ;; overflow when played together. If overflow occurs,
  ;; Soundmix Framework prints a warning.
  (play-2 minus5 plus5 :for 1)
  
  ;; Fade-2 is like fade, but it fades two clips (but not with
  ;; crossfade). Its duration is determined like play-2's when
  ;; called without a :for argument.
  (fade-2 minus5 plus5 :to another-gain :over 0.5)
  
  ;; Those are all the commands currently supported by
  ;; Soundmix Framework.
  )

;; A compound clip can also be used as a clip.
(defcompound example-output
  (play intermediate-clip)
  (reset intermediate-clip)
  (fade intermediate-clip))

;; Finally, write a compound clip to a file.
(write-compound example-output "example.wav")

Implementation

Many details of the implementation can be found as comments in soundmix-framework.lsp. More notes follow.

Lazy Evaluation

Nyquist uses lazy evaluation for its sound objects. This means it does not read samples or do calculations on them until the results are needed. (For example, because the sound is being written to a file.) In addition, if Nyquist's functions hold the only references to a sound object, samples will be discarded when they are no longer needed. This is an important memory optimization, and Soundmix Framework takes advantage of it by not keeping references to sound objects. This allows Soundmix Framework to have modest memory requirements even when operating on very large files.

Configuration

There are three global configuration options in Soundmix Framework:

• Pre-write processing, which sets a global function.
• Sample rate, which uses a global variable along with Nyquist's own sample rate settings.
• Number of channels, which uses the Strategy Pattern.

All these details are abstracted away from the user in favor of a simple procedural interface.

Macros

Soundmix Framework makes use of macros both for implementation and to create a simple interface.

Versioning

Soundmix Framework uses a simple versioning scheme that allows backwards compatibility so long as it does not require changes in framework behavior.