OpenAL: Bindings for the OpenAL sound library🔗ℹ

1 Example: Playing sound from a raw buffer🔗ℹ

In this example, we play an 8-bit sine wave generated from a bytestring.

#lang racket

(require libopenal-racket)

;; Our sound data

(define sinewave

(list->bytes

(for/list ([i (in-range 0 (* 2 pi) 0.07)])

(inexact->exact

(floor

(+ 128

(* (sin i) 64)))))))

First, we must open the sound device and create a context for it:

;; Initialize OpenAL (see the OpenAL guide)

(define device (open-device #f))

(define context (create-context device))

(set-current-context context)

Once we have a device context, we must create a buffer to hold our sound data.

;; Make our OpenAL buffer

(define buffer (car (gen-buffers 1)))

;; Copy the bytes to this buffer

(buffer-data buffer

AL_FORMAT_MONO8

sinewave

44100)

In this example, each unsigned byte of sinewave is a separate 8-bit sound sample. Realistically, a real-world application would want to use 16-bit samples, but this grainy, ugly example is fine for us.

Once our data is safe in an OpenAL buffer, we make a source and play it. Note that OpenAL internally copies that data – we are free to mutate it however we like after the call to buffer-data.

;; Make our OpenAL source

(define source (car (gen-sources 1)))

;; Bind our buffer to the source -- 8-bit mono

(set-source-buffer! source buffer)

OpenAL allows us to define several simultaneously playing sources. Though a single source can only have one buffer, note that a buffer can be bound to several sources at the same time to save space.

Now that we have a source and a sound buffer to play, we can set our source to play the data from the sound buffer.

;; Loop forever (without this, the source will play just once and then stop)

(set-source-looping! source AL_TRUE)

;; Start playing

(play-source source)

OpenAL uses a separate OS-level thread to play sounds. The play-source call will exit instantly and our sound will continue to play in the background until we choose to stop it.

;; Wait until we're fisished playing

(sleep 5)

;; Clean up

(delete-sources! (list source))

(delete-buffers! (list buffer))

(set-current-context #f)

(destroy-context! context)

(close-device! device)

2 Example: Playing OGG Vorbis Files🔗ℹ

OpenAL works great with the (planet gcr/libvorbisfile) package, and this is no accident. This example shows you how to stream a vorbis file straight to an OpenAL source without loading it into a buffer like we did above.

First, we must dig out the spellbook and incant the OpenAL Summoning Mantra:

#lang racket

(require libopenal-racket

(planet gcr/libvorbisfile))

;; Initialize OpenAL (see the docs for libopenal-racket)

(define device (open-device #f))

(define context (create-context device))

(set-current-context context)

From here, it’s not rocket science to open a vorbis file and query basic information about it.

(define filename "/home/gcr/Music/Lights/Siberia/11 Flux and Flow.ogg")

(printf "Playing file ~a\n" filename)

(define m (open-vorbis-file filename))

To read the sound data, we use libvorbisfile’s make-vorbis-input-port function to create a port that decodes the sound data into binary bytes on-demand.

;; To read the PCM  samples, we make a port that supplies us with

;; the binary decompressed data.

(define vorbis-binary (make-vorbis-input-port m 0 2 1))

;; OpenAL expects:

;; 0 (Little-endian)

;; 2 (Word size; 16 bits)

;; 1 (Signed)

Now that we have a port that gives us raw sample data, we can stream it straight to an OpenAL source. This avoids reading the entire file into memory – each block of sound is decoded right as it’s needed.

;; Make our OpenAL source

(define source (car (gen-sources 1)))

;; Start streaming

(define stream-thread

(stream-port-to-source vorbis-binary

source

AL_FORMAT_STEREO16

(vorbis-frequency m)))

;; Start playing

(play-source source)

;; OpenAL's stream-port-to-source returns a thread, so wait until we're

;; finished playing

(thread-wait stream-thread)

Once we’re done, we should clean up our OpenAL mess:

(set-current-context #f)

(destroy-context! context)

(close-device! device)

You should probably close the vorbis file when you’re finished.

(close-vorbis-file! m)

3 Constants🔗ℹ

All constants defined in al.h and alc.h are re-exported under their usual names. See the OpenAL Programmer’s Guide for information about what each constant means.

value AL_BITS : exact-integer?

value AL_BUFFER : exact-integer?

value AL_BUFFERS_PROCESSED : exact-integer?

value AL_BUFFERS_QUEUED : exact-integer?

value AL_BYTE_OFFSET : exact-integer?

value AL_CHANNELS : exact-integer?

value AL_CONE_INNER_ANGLE : exact-integer?

value AL_CONE_OUTER_ANGLE : exact-integer?

value AL_CONE_OUTER_GAIN : exact-integer?

value AL_DIRECTION : exact-integer?

value AL_DISTANCE_MODEL : exact-integer?

value AL_DOPPLER_FACTOR : exact-integer?

value AL_DOPPLER_VELOCITY : exact-integer?

value AL_EXPONENT_DISTANCE : exact-integer?

value AL_EXPONENT_DISTANCE_CLAMPED : exact-integer?

value AL_EXTENSIONS : exact-integer?

value AL_FALSE : exact-integer?

value AL_FORMAT_MONO16 : exact-integer?

value AL_FORMAT_MONO8 : exact-integer?

value AL_FORMAT_STEREO16 : exact-integer?

value AL_FORMAT_STEREO8 : exact-integer?

value AL_FREQUENCY : exact-integer?

value AL_GAIN : exact-integer?

value AL_ILLEGAL_COMMAND : exact-integer?

value AL_ILLEGAL_ENUM : exact-integer?

value AL_INITIAL : exact-integer?

value AL_INVALID : exact-integer?

value AL_INVALID_ENUM : exact-integer?

value AL_INVALID_NAME : exact-integer?

value AL_INVALID_OPERATION : exact-integer?

value AL_INVALID_VALUE : exact-integer?

value AL_INVERSE_DISTANCE : exact-integer?

value AL_INVERSE_DISTANCE_CLAMPED : exact-integer?

value AL_LINEAR_DISTANCE : exact-integer?

value AL_LINEAR_DISTANCE_CLAMPED : exact-integer?

value AL_LOOPING : exact-integer?

value AL_MAX_DISTANCE : exact-integer?

value AL_MAX_GAIN : exact-integer?

value AL_MIN_GAIN : exact-integer?

value AL_NO_ERROR : exact-integer?

value AL_NONE : exact-integer?

value AL_ORIENTATION : exact-integer?

value AL_OUT_OF_MEMORY : exact-integer?

value AL_PAUSED : exact-integer?

value AL_PENDING : exact-integer?

value AL_PITCH : exact-integer?

value AL_PLAYING : exact-integer?

value AL_POSITION : exact-integer?

value AL_PROCESSED : exact-integer?

value AL_REFERENCE_DISTANCE : exact-integer?

value AL_RENDERER : exact-integer?

value AL_ROLLOFF_FACTOR : exact-integer?

value AL_SAMPLE_OFFSET : exact-integer?

value AL_SEC_OFFSET : exact-integer?

value AL_SIZE : exact-integer?

value AL_SOURCE_RELATIVE : exact-integer?

value AL_SOURCE_STATE : exact-integer?

value AL_SOURCE_TYPE : exact-integer?

value AL_SPEED_OF_SOUND : exact-integer?

value AL_STATIC : exact-integer?

value AL_STOPPED : exact-integer?

value AL_STREAMING : exact-integer?

value AL_TRUE : exact-integer?

value AL_UNDETERMINED : exact-integer?

value AL_UNUSED : exact-integer?

value AL_VELOCITY : exact-integer?

value AL_VENDOR : exact-integer?

value AL_VERSION : exact-integer?

4 Device and context management🔗ℹ

With OpenAL, we must manage our own devices and our device contexts. It’s good practice to close all devices at the end of your program – some platforms may get confused.

frequency is the frequency at which the device should record, usually 44100.

format is the requested capture buffer format.

buffersize is the size of the capture buffer.

5 Buffers🔗ℹ

OpenAL buffers hold sound data. They are kept in completely separate memory outside Racket’s garbage collection pool, so you must free buffers yourself when you’re finished with them to avoid memory leaks.

Once you have a buffer, you must load data with buffer-data, bind it to a source with set-source-buffer!, and then play the source with play-source. See the Example: Playing sound from a raw buffer section.

Format should be an OpenAL constant signifying the format of the samples in data. For 8-bit formats, a value of 128 means no DC offset, with 0 and 255 being the extreme DC offsets. For 16-bit formats, samples are signed little-endian 16-bit integers. Stereo formats include interleaved samples, left first.

The frequency of the data is how many samples per second the source should play, usually 44100.

Note that data is automatically copied, not referenced – you can reuse or mutate data however you like after this call.

5.1 Buffer properties🔗ℹ

5.1.1 C-level buffer getters and setters🔗ℹ

5.1.2 Friendly buffer getters and setters🔗ℹ

6 Sources🔗ℹ

Sources are actual playing sounds in the world. Each source can either be bound to a single buffer or can contain a buffer queue that continuously streams sound data.

Sources have a 3D position and velocity in space. This means that OpenAL can optionally apply certain effects such as attenuation (softening far-away sounds) and pitch shifting (the doppler effect).

6.1 Source properties🔗ℹ

These bindings define two “levels” of functions that set and retrieve properties. First, there are the low-level “C-like” functions like alSourcef that allow you to get and set individual properties of sources defined by an OpenAL constant. Alternatively, there are the friendlier functions like set-source-looping! that offer a simpler interface for setting the same properties.

6.1.1 C-like source getters and setters🔗ℹ

6.1.2 Friendly source getters and setters🔗ℹ