RSound: An Adequate Sound Engine for Racket
This collection provides a means to represent, read,
write, play, and manipulate sounds. It depends on the clements/portaudio
package to provide bindings to the cross-platform `PortAudio’ library which appears
to run on Linux, Mac, and Windows.
It represents all sounds internally as stereo 16-bit PCM, with all the attendant
advantages (speed, mostly) and disadvantages (clipping).
Does it work on your machine? Try this example (and accept my
apologies if I forget to update the version number):
A note about volume: be careful not to damage your hearing, please. To take a simple example, the sine-wave function generates a sine wave with amplitude 1.0. That translates into the loudest possible sine wave that can be represented. So please set your volume low, and be careful with the headphones. Maybe there should be a parameter that controls the clipping volume. Hmm.
1 Sound Control
These procedures start and stop playing sounds and loops.
Plays an rsound. Plays concurrently with an already-playing sound, if there is one.
Stop all of the the currently playing sounds.
2 Sound I/O
These procedures read and write rsounds from/to disk.
The RSound library reads and writes WAV files only; this means fewer FFI dependencies (the reading & writing is done in Racket), and works on all platforms.
(rs-read path) → rsound? path : path-string?
Reads a WAV file from the given path, returns it as an rsound.
It currently has lots of restrictions (it insists on 16-bit PCM encoding, for instance), but deals with a number of common bizarre conventions that certain WAV files have (PAD chunks, extra blank bytes at the end of the fmt chunk, etc.), and tries to fail relatively gracefully on files it can’t handle.
Reading in a large sound can result in a very large value (~10 Megabytes per minute); for larger sounds, consider reading in only a part of the file, using rs-read/clip.
(rs-read/clip path start finish) → rsound? path : path-string? start : nonnegative-integer? finish : nonnegative-integer?
Reads a portion of a WAV file from a given path, starting at frame start and ending at frame finish.
It currently has lots of restrictions (it insists on 16-bit PCM encoding, for instance), but deals with a number of common bizarre conventions that certain WAV files have (PAD chunks, extra blank bytes at the end of the fmt chunk, etc.), and tries to fail relatively gracefully on files it can’t handle.
(rs-read-frames path) → nonnegative-integer? path : path-string?
Returns the number of frames in the sound indicated by the path. It parses
the header only, and is therefore much faster than reading in the whole sound.
The file must be encoded as a WAV file readable with rsound-read.
(rs-read-sample-rate path) → number? path : path-string?
Returns the sample-rate of the sound indicated by the path. It parses
the header only, and is therefore much faster than reading in the whole sound.
The file must be encoded as a WAV file readable with rs-read.
(rs-write rsound path) → void? rsound : rsound? path : path-string?
Writes an rsound to a WAV file, using stereo 16-bit PCM encoding. It
overwrites an existing file at the given path, if one exists.
3 Rsound Manipulation
These procedures allow the creation, analysis, and manipulation of rsounds.
(struct rsound (data sample-rate) #:extra-constructor-name make-rsound) data : s16vector? sample-rate : nonnegative-number?
Represents a sound.
Returns the length of a sound, in frames.
(rsound-equal? sound1 sound2) → boolean? sound1 : rsound? sound2 : rsound?
Returns #true when the two sounds are (extensionally) equal.
This procedure is necessary because s16vectors don’t natively support equal?.
Returns an rsound of length frames containing silence. This procedure is relatively fast.
(rs-ith/left rsound frame) → nonnegative-integer? rsound : rsound? frame : nonnegative-integer?
Returns the nth sample from the left channel of the rsound, represented as a number in the range -1.0
to 1.0.
(rs-ith/right rsound frame) → nonnegative-integer? rsound : rsound? frame : nonnegative-integer?
Returns the nth sample from the right channel of the rsound, represented as a number in the range -1.0
to 1.0.
(clip rsound start finish) → rsound? rsound : rsound? start : nonnegative-integer? finish : nonnegative-integer?
Returns a new rsound containing the frames in rsound from the startth to the finishth - 1.
This procedure copies the required portion of the sound.
(rs-append* rsounds) → rsound? rsounds : (listof rsound?)
Returns a new rsound containing the given rsounds, appended sequentially. This procedure is relatively
fast. All of the given rsounds must have the same sample-rate.
(rs-overlay rsound-1 rsound-2) → rsound? rsound-1 : rsound? rsound-2 : rsound?
Returns a new rsound containing the two sounds played simultaneously.
Note that unless both sounds have amplitudes less that 0.5, clipping
or wrapping is likely.
(rs-overlay* rsounds) → rsound? rsounds : (listof rsound?)
Returns a new rsound containing all of the sounds played simultaneously.
Note that unless all of the sounds have low amplitudes, clipping
or wrapping is likely.
Returns a new rsound containing all of the given rsounds. Each sound begins at the frame number
indicated by its associated offset. The rsound will be exactly the length required to contain all of
the given sounds.
So, suppose we have two rsounds: one called ’a’, of length 20000, and one called ’b’, of length 10000. Evaluating
(rs-overlay* (list (list a 5000) (list b 0) (list b 11000)))
... would produce a sound of 21000 frames, where each instance of ’b’ overlaps with the central instance of ’a’.
Scale the given sound by multiplying all of its samples by the given scalar.
4 Signals
A signal is a function mapping a frame number to a real number in the range -1.0 to 1.0. There are several built-in functions that produce signals.
(sine-wave frequency sample-rate) → signal? frequency : nonnegative-number? sample-rate : nonnegative-number?
Produces a signal representing a sine wave of the given
frequency, of amplitude 1.0.
(sawtooth-wave frequency sample-rate) → signal? frequency : nonnegative-number? sample-rate : nonnegative-number?
Produces a signal representing a naive sawtooth wave of the given
frequency, of amplitude 1.0. Note that since this is a simple -1.0 up to 1.0 sawtooth wave, it’s got horrible
aliasing all over the spectrum.
(square-wave frequency sample-rate) → signal? frequency : nonnegative-number? sample-rate : nonnegative-number?
Produces a signal representing a naive square wave of the given
frequency, of amplitude 1.0. Note that since this is a simple 1/-1 square wave, it’s got horrible
aliasing all over the spectrum.
Produces a constant signal at amplitude. Inaudible unless used to multiply by
another signal.
In order to listen to them, you can transform them into rsounds, or play them directly:
(mono-signal->rsound frames signal) → rsound? frames : nonnegative-integer? signal : signal?
Builds a sound of length frames at the default sample-rate by calling
signal with integers from 0 up to frames-1. The result should be an inexact
number in the range -1.0 to 1.0. Values outside this range are clipped.
Both channels are identical.
Here’s an example of using it:
(define samplerate 44100) (define sr/inv (/ 1 samplerate)) (define (sig1 t) (* 0.1 (sin (* t 560 twopi sr/inv)))) (define r (mono-signal->rsound (* samplerate 4) sig1)) (play r)
Alternatively, we could use sine-wave to achieve the same result:
(define samplerate (default-sample-rate)) (define r (mono-signal->rsound (* samplerate 4) (scale 0.1 (sine-wave 560 samplerate)))) (play r)
(signals->rsound frames left-fun right-fun) → rsound? frames : nonnegative-integer? left-fun : signal? right-fun : signal?
Builds a stereo sound of length frames by calling
left-fun and right-fun
with integers from 0 up to frames-1. The result should be an inexact
number in the range -1.0 to 1.0. Values outside this range are clipped.
(signal-play signal sample-rate?) → void? signal : signal? sample-rate? : positive-real?
Produces a signal that decays exponentially. After fade-samples, its value is 0.001.
Inaudible unless used to multiply by another signal.
(signal proc args ...) → signal? proc : procedure? args : (listof any/c)
Produces a signal whose values are computed by calling proc with the current frame and the additional
values args.
So, for instance, if we defined the function flatline as
(define (flatline t l) l)
... then (signal flatline 0.4) would produce the same result as (dc-signal 0.4).
There are also a number of functions that combine existing signals, called "signal combinators":
Produces the signal that is the sum of the input signals.
Produces the signal that is the product of the input signals.
We can turn an rsound back into a signal, using rsound->signal:
(rsound->signal/left rsound) → signal? rsound : rsound?
Produces the signal that corresponds to the rsound’s left channel, followed by endless silence. Ah, endless silence.
(rsound->signal/right rsound) → signal? rsound : rsound?
Produces the signal that corresponds to the rsound’s right channel, followed by endless silence. (The silence joke
wouldn’t be funny if I made it again.)
(thresh/signal threshold signal) → signal? threshold : real-number? signal : signal?
Applies a threshold (see thresh, below) to a signal.
(clip&volume volume signal) → signal? volume : real-number? signal : signal?
Clips the signal to a threshold of 1, then multiplies by the given volume.
Where should these go?
(thresh threshold input) → real-number? threshold : real-number? input : real-number?
Produces the number in the range (- threshold) to threshold that is
closest to input. Put differently, it “clips” the input at the threshold.
Finally, here’s a predicate. This could be a full-on contract, but I’m afraid of the overhead.
Is the given value a signal? More precisely, is the given value a procedure whose
arity includes 1?
5 Visualizing Rsounds
| (require (planet clements/rsound:3:=1/draw)) |
(rs-draw rsound #:title title [ #:width width #:height height]) → void? rsound : rsound? title : string? width : nonnegative-integer? = 800 height : nonnegative-integer? = 200
Displays a new window containing a visual representation of the sound as a waveform.
(rsound-fft-draw rsound #:zoom-freq zoom-freq #:title title [ #:width width #:height height]) → void? rsound : rsound? zoom-freq : nonnegative-real? title : string? width : nonnegative-integer? = 800 height : nonnegative-integer? = 200
Draws an fft of the sound by breaking it into windows of 2048 samples and performing an
FFT on each. Each fft is represented as a column of gray rectangles, where darker grays
indicate more of the given frequency band.
(vector-pair-draw/magnitude left right #:title title [ #:width width #:height height]) → void? left : (vectorof complex?) right : (vectorof complex?) title : string? width : nonnegative-integer? = 800 height : nonnegative-integer? = 200
Displays a new window containing a visual representation of the two vectors’ magnitudes
as a waveform. The lines connecting the dots are really somewhat inappropriate in the
frequency domain, but they aid visibility....
(vector-draw/real/imag vec #:title title [ #:width width #:height height]) → void? vec : (vectorof complex?) title : string? width : nonnegative-integer? = 800 height : nonnegative-integer? = 200
Displays a new window containing a visual representation of the vector’s real and imaginary
parts as a waveform.
6 RSound Utilities
(make-harm3tone frequency volume? frames sample-rate) → rsound? frequency : nonnegative-number? volume? : nonnegative-number? frames : nonnegative-integer? sample-rate : nonnegative-number?
Produces an rsound containing a semi-percussive tone of the given frequency, frames, and volume. The tone contains the first
three harmonics of the specified frequency. This function is memoized, so that subsequent calls with the same parameters
will return existing values, rather than recomputing them each time.
(make-tone pitch volume duration) → rsound? pitch : nonnegative-number? volume : nonnegative-number? duration : nonnegative-exact-integer?
given a pitch in Hz, a volume between 0.0 and 1.0, and a duration in frames, return the
rsound consisting of a pure sine wave tone using the specified parameters.
(rsound-fft/left rsound) → (vectorof complex?) rsound : rsound?
Produces the complex-valued vector that represents the fourier transform of the rsound’s left channel.
Since the FFT takes time N*log(N) in the size of the input, running this on rsounds with more than a
few thousand frames is probably going to be slow, unless the number of frames is a power of 2.
(rsound-fft/right rsound) → (vectorof complex?) rsound : rsound?
Produces the complex-valued vector that represents the fourier transform of the rsound’s right channel.
Since the FFT takes time N*log(N) in the size of the input, running this on rsounds with more than a
few thousand frames is probably going to be slow, unless the number of frames is a power of 2
(midi-note-num->pitch note-num) → number? note-num : nonnegative-integer?
Returns the frequency (in Hz) that corresponds to a given midi note number. Here’s the top-secret formula:
440*2^((n-69)/12).
(fir-filter delay-lines) → procedure? delay-lines : (listof (list/c nonnegative-exact-integer? real-number?))
Given a list of delay times (in frames) and amplitudes for each, produces a function that maps signals
to new signals where each frame is the sum of the current signal frame and the multiplied versions of
the delayed input signals (that’s what makes it FIR).
So, for instance,
...would produce a filter that added the current frame to 4/10 of the input frame 13 frames ago and 1/10 of the input frame 4 frames ago.
(iir-filter delay-lines) → procedure? delay-lines : (listof (list/c nonnegative-exact-integer? real-number?))
Given a list of delay times (in frames) and amplitudes for each, produces a function that maps signals
to new signals where each frame is the sum of the current signal frame and the multiplied versions of
the delayed output signals (that’s what makes it IIR).
So, for instance,
...would produce a filter that added the current frame to 4/10 of the output frame 13 frames ago and 1/10 of the output frame 4 frames ago.
7 Frequency Response
This module provides functions to allow the analysis of frequency response on filters specified
either as transfer functions or as lists of poles and zeros. It assumes a sample rate of 44.1 Khz.
(response-plot poly dbrel min-freq max-freq) → void? poly : procedure? dbrel : real? min-freq : real? max-freq : real
Plot the frequency response of a filter, given its transfer function (a function mapping reals to reals).
The dbrel number
indicates how many decibels up the "zero" line should be shifted. The graph starts at min-freq
Hz and goes up to max-freq Hz. Note that aliasing effects may affect the apparent height or
depth of narrow spikes.
Here’s an example of calling this function on a 100-pole comb filter, showing the response from 10KHz
to 11KHz:
(poles&zeros->fun poles zeros) → procedure? poles : (listof real?) zeros : (listof real?)
given a list of poles and zeros in the complex plane, generate the corresponding transfer
function.
Here’s an example of calling this function as part of a call to response-plot, for a filter
with three poles and two zeros, from 0 Hz up to the nyquist frequency, 22.05 KHz:
(response-plot (poles&zeros->fun '(0.5 0.5+0.5i 0.5-0.5i) '(0+1i 0-1i)) 40 0 22050)
8 Filtering
This module provides a dynamic low-pass filter, among other things.
The control signal must produce real numbers in the range 0.01 to 3.0. A small
number produces a low cutoff frequency. The input signal is the audio signal
to be processed. For instance, here’s a time-varying low-pass filtered sawtooth:
(define (control f) (+ 0.5 (* 0.2 (sin (* f 7.123792865282977e-05))))) (define (sawtooth f) (/ (modulo f 220) 220)) (play (mono-signal->rsound 88200 (lpf/dynamic control sawtooth)))
9 Single-cycle sounds
This module provides support for generating tones from single-cycle waveforms.
In particular, it comes with a library of 247 such waveforms, courtesy of
Adventure Kid’s website. Used with
permission. Thanks!
(synth-note family spec midi-note-number duration) → rsound family : string? spec : number-or-path? midi-note-number : natural? duration : natural?
Given a family (currently either "main", "vgame", or "path"), a spec (a number in the first two cases),
a midi note number and a duration in frames, produces an rsound. There’s a (non-configurable)
envelope applied, too.
Example, playing sound #49 from the vgame package for a half-second at middle C:
(synth-note "vgame" 49 60 22010)
(synth-note/raw family spec midi-note-number duration) → rsound family : string? spec : number-or-path? midi-note-number : natural? duration : natural?
Same as above, but no envelope is applied.
10 Stream-based Playing
RSound now provides functions whereby all played sounds use a single stream.
This has the advantage of lower latency and avoids problems on Windows, where
opening a new stream for each sound causes errors.
Plays a given sound at a given (stream-relative) frame.
(current-time/s) → natural?
Returns the current stream-relative frame.
11 Reporting Bugs
For Heaven’s sake, report lots of bugs!