RSound: An Adequate Sound Engine for Racket

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 A NOTE ABOUT WINDOWS

Windows is a bit of a pain for developers. If you’re having trouble hearing sounds under windows (high latency, or "Invalid Device" errors), try running diagnose-sound-playing.

2 Sound Control

These procedures start and stop playing sounds and loops.

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

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.

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.

The file must be encoded as a WAV file readable with rsound-read.

The file must be encoded as a WAV file readable with rs-read.

4 Rsound Manipulation

These procedures allow the creation, analysis, and manipulation of rsounds.

This procedure is necessary because s16vectors don’t natively support equal?.

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

5 Signals and Networks

For signal processing, RSound adopts a dataflow-like paradigm. Networks represent interconnected signal-processing nodes, and produce streams of values. They can be connected together using a number of primitives, including the network syntactic form. Networks that have no inputs are called signals.

Here’s a trivial signal:

(network ()

[out 3])

This is the signal that always produces 3.

Here’s another one, that counts upward:

(define counter/sig

(network ()

[counter (+ 1 (prev counter 0))]))

The prev form is special, and is used to refer to the prior value of the signal component.

Note that since we’re adding one immediately, this counter starts at 1.

Here’s another example, that adds together two sine waves, at 34 Hz and 46 Hz, assuming a sample rate of 44.1KHz:

(define sum-of-sines

(network ()

[a (sine-wave 34)]

[b (sine-wave 46)]

[out (+ a b)]))

In order to use a signal with signal-play, it should produce a real number in the range -1.0 to 1.0.

Here’s an example that uses one sine-wave (often called an "LFO") to control the pitch of another one:

(define vibrato-tone

(network ()

[lfo (sine-wave 2)]

[sin (sine-wave (+ 400 (* 50 lfo)))]

[out (* 0.1 sin)]))

(signal-play vibrato-tone)

(sleep 5)

(stop)

There are many built-in signals. Note that these are documented as though they were procedures, but they’re not; they can be used in a procedure-like way in network clauses. Otherwise, they will behave as opaque values; you can pass them to various signal functions, etc.

Also note that all of these assume a fixed sample rate of 44.1 KHz.

Also note that since this is a simple 1/-1 square wave, it’s got horrible aliasing all over the spectrum.

In order to listen to them, you can transform them into rsounds, or play them directly:

Here’s an example of using it:

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.

There are several functions that produce signals.

There are also a number of functions that combine existing signals, called "signal combinators":

We can turn an rsound back into a signal, using rsound->signal:

Where should these go?

Finally, here’s a predicate. This could be a full-on contract, but I’m afraid of the overhead.

6 Visualizing Rsounds

(require (planet clements/rsound:4:=3/draw))

7 RSound Utilities

So, for instance,

(fir-filter (list (list 13 0.4) (list 4 0.1)))

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

So, for instance,

(iir-filter (list (list 13 0.4) (list 4 0.1)))

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

8 Frequency Response

9 Filtering

10 Single-cycle sounds

11 Stream-based Playing

12 Sample Code

An example of a signal that plays two lines, each with randomly changing square-wave tones. This one runs in the Intermediate student language:

(require (planet clements/rsound))

(require (planet clements/rsound/filter))

; scrobble: number number number -> signal

; return a signal that generates square-wave tones, changing

; at the given interval into a new randomly-chosen frequency

; between lo-f and hi-f

(define (scrobble change-interval lo-f hi-f)

(local

[(define freq-range (floor (- hi-f lo-f)))

(define (maybe-change f l)

(cond [(= l 0) (+ lo-f (random freq-range))]

[else f]))]

(network ()

[looper ((loop-ctr change-interval 1))]

[freq (maybe-change (prev freq 400) looper)]

[a (square-wave freq)])))

(define my-signal

(network ()

[a ((scrobble 4000 200 600))]

[b ((scrobble 40000 100 200))]

[lpf-wave (sine-wave 0.1)]

[c (lpf/dynamic (max 0.01 (abs (* 0.5 lpf-wave))) (+ a b))]

[b (* c 0.1)]))

; write 20 seconds to a file, if uncommented:

; (rs-write (signal->rsound (* 20 44100) my-signal) "/tmp/foo.wav")

; play the signal

(signal-play my-signal)

13 Reporting Bugs

For Heaven’s sake, report lots of bugs!