OpenAL: Bindings for the OpenAL sound library🔗 i

1Example: Playing sound from a raw buffer🔗 i

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

#lang racket

(require libopenal-racket)

 

;;Oursounddata

(define sinewave

(list->bytes

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

(inexact->exact

(floor

(+ 128

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

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

;;InitializeOpenAL(seetheOpenALguide)

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

;;MakeourOpenALbuffer

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

;;Copythebytestothisbuffer

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

;;MakeourOpenALsource

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

 

;;Bindourbuffertothesource--8-bitmono

(set-source-buffer! sourcebuffer)

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.

;;Loopforever(withoutthis,thesourcewillplayjustonceandthenstop)

(set-source-looping! sourceAL_TRUE )

 

;;Startplaying

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

;;Waituntilwe'refisishedplaying

(sleep 5)

 

;;Cleanup

(delete-sources! (list source))

(delete-buffers! (list buffer))

(set-current-context #f)

(destroy-context! context)

(close-device! device)

2Example: Playing OGG Vorbis Files🔗 i

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

 

;;InitializeOpenAL(seethedocsforlibopenal-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/11FluxandFlow.ogg")

(printf "Playingfile~a\n"filename)

 

(define m(open-vorbis-filefilename))

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.

;;ToreadthePCMsamples,wemakeaportthatsuppliesuswith

;;thebinarydecompresseddata.

(define vorbis-binary(make-vorbis-input-portm021))

;;OpenALexpects:

;;0(Little-endian)

;;2(Wordsize;16bits)

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

;;MakeourOpenALsource

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

 

;;Startstreaming

(define stream-thread

(stream-port-to-source vorbis-binary

source

AL_FORMAT_STEREO16

(vorbis-frequencym)))

 

;;Startplaying

(play-source source)

 

;;OpenAL'sstream-port-to-sourcereturnsathread,sowaituntilwe're

;;finishedplaying

(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)

3Constants🔗 i

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?

4Device and context management🔗 i

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.

5Buffers🔗 i

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.

6Sources🔗 i

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

7Listener properties🔗 i

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.

8Streaming sound🔗 i

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.

Every poll-interval seconds, the background thread will ensure that the source has num-buffers unprocessed buffers of at most buffer-size bytes each, and the thread will refill processed buffers as necessary to ensure gapless playback.

The port should yield bytes suitable for OpenAL playback, with the given format, and sample rate of frequency (typically 44100).

Just after the last buffer is queued, the thread will run the at-end-of-loop procedure which returns #t if the thread should continue or #f if it should stop once the last buffer finishes. You might use the at-end-of-loop function to seek the port back to the beginning of the file to seamlessly start playing back at the beginning of the file when reaching the end.

The thread will run the cleanup function just before exiting. Use this function to delete the allocated source, close the port, or perhaps to transition to a different screen in your application. Note that this may run up to poll-interval seconds after the sound actually finishes.

If you want to terminate the thread early, just run kill-thread on it. Cleanup will be run automatically.

9Distance models🔗 i

OpenAL defines several models that select how sound is attenuated (softened) over distance.

Without any distance model, the gain remains fixed at 1.

10License🔗 i

The code in this package and this documentation is under the zlib license, reproduced below. Keep in mind that OpenAL itself has many different implementations – some of which are proprietary to Creative Labs and some of which LGPL-licensed.