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 (planet gcr/openal))

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

AL_BITS : exact-integer?

AL_BUFFER : exact-integer?

AL_BUFFERS_PROCESSED : exact-integer?

AL_BUFFERS_QUEUED : exact-integer?

AL_BYTE_OFFSET : exact-integer?

AL_CHANNELS : exact-integer?

AL_CONE_INNER_ANGLE : exact-integer?

AL_CONE_OUTER_ANGLE : exact-integer?

AL_CONE_OUTER_GAIN : exact-integer?

AL_DIRECTION : exact-integer?

AL_DISTANCE_MODEL : exact-integer?

AL_DOPPLER_FACTOR : exact-integer?

AL_DOPPLER_VELOCITY : exact-integer?

AL_EXPONENT_DISTANCE : exact-integer?

AL_EXPONENT_DISTANCE_CLAMPED : exact-integer?

AL_EXTENSIONS : exact-integer?

AL_FALSE : exact-integer?

AL_FORMAT_MONO16 : exact-integer?

AL_FORMAT_MONO8 : exact-integer?

AL_FORMAT_STEREO16 : exact-integer?

AL_FORMAT_STEREO8 : exact-integer?

AL_FREQUENCY : exact-integer?

AL_GAIN : exact-integer?

AL_ILLEGAL_COMMAND : exact-integer?

AL_ILLEGAL_ENUM : exact-integer?

AL_INITIAL : exact-integer?

AL_INVALID : exact-integer?

AL_INVALID_ENUM : exact-integer?

AL_INVALID_NAME : exact-integer?

AL_INVALID_OPERATION : exact-integer?

AL_INVALID_VALUE : exact-integer?

AL_INVERSE_DISTANCE : exact-integer?

AL_INVERSE_DISTANCE_CLAMPED : exact-integer?

AL_LINEAR_DISTANCE : exact-integer?

AL_LINEAR_DISTANCE_CLAMPED : exact-integer?

AL_LOOPING : exact-integer?

AL_MAX_DISTANCE : exact-integer?

AL_MAX_GAIN : exact-integer?

AL_MIN_GAIN : exact-integer?

AL_NO_ERROR : exact-integer?

AL_NONE : exact-integer?

AL_ORIENTATION : exact-integer?

AL_OUT_OF_MEMORY : exact-integer?

AL_PAUSED : exact-integer?

AL_PENDING : exact-integer?

AL_PITCH : exact-integer?

AL_PLAYING : exact-integer?

AL_POSITION : exact-integer?

AL_PROCESSED : exact-integer?

AL_REFERENCE_DISTANCE : exact-integer?

AL_RENDERER : exact-integer?

AL_ROLLOFF_FACTOR : exact-integer?

AL_SAMPLE_OFFSET : exact-integer?

AL_SEC_OFFSET : exact-integer?

AL_SIZE : exact-integer?

AL_SOURCE_RELATIVE : exact-integer?

AL_SOURCE_STATE : exact-integer?

AL_SOURCE_TYPE : exact-integer?

AL_SPEED_OF_SOUND : exact-integer?

AL_STATIC : exact-integer?

AL_STOPPED : exact-integer?

AL_STREAMING : exact-integer?

AL_TRUE : exact-integer?

AL_UNDETERMINED : exact-integer?

AL_UNUSED : exact-integer?

AL_VELOCITY : exact-integer?

AL_VENDOR : exact-integer?

AL_VERSION : exact-integer?

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

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

4.1 Buffer properties

4.1.1 C-level buffer getters and setters

4.1.2 Friendly buffer getters and setters

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

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

5.1.1 C-like source getters and setters

5.1.2 Friendly source getters and setters

If you want to build a streaming buffer, don’t use set-source-buffer! or else it may misbehave. You can, however, clear any queued buffers by running (set-source-buffer! source 0).

6 Listener properties

The listener is the single entity in the world that listens for sound from all the sources. When the listener “hears” a source, it sends the output to the current sound device. The volume is adjusted based on the distance between the source and listener, and the sound’s pitch is adjusted based on the velocity and orientation thanks to the doppler effect.

6.1 C-like listener getters and setters

6.2 Friendly listener getters and setters

7 Streaming sound

Each source usually has one buffer attached to it. If this were the only possible way of playing your sound, you would have to either load the entire sound into memory (imagine loading 90 minutes of raw sample data) or manage buffers yourselves, suffering through the inevitable clicks and hisses when OpenAL drains the buffer just before you can replace it.

Thankfully, OpenAL allows you to assign several buffers to a source using a queue of buffer objects. The sound will continue to play as long as there is a buffer left to play from. From time to time, your program should un-queue old buffers, refill them, and queue them at the end of the source’s queue.

You can either manage each source’s low-level buffer queue yourself or use the higher-level port streaming facilities to stream sounds straight from a Racket binary port.

If you intend to build a streaming source with a buffer queue, don’t call set-source-buffer!. Likewise, don’t use this function if you only want an ordinary source backed by a single buffer.