Asynchronous libao playback in Racket🔗ℹ

1 Basic example🔗ℹ

The normal live playback path opens the default libao driver. The output bit format may be lower than the requested bit format when libao cannot open the device with the requested precision.

(define h

(ao_create_async 32 44100 2 'native-endian #f))

(define info

(make-buffer-info 'interleaved 32 44100 2 'native-endian))

(when h

(ao_play_async h 1 0.0 180.0 (bytes-length pcm) pcm info)

(ao_stop_async h))

To write to a WAV file instead of the default live device, pass a path string as the last argument to ao_create_async instead of #f .

(define h

(ao_create_async 16 48000 2 'little-endian "test-output.wav"))

2 Playback handles🔗ℹ

The requested format is described by bits, rate, channels and byte-format. If the requested number of bits cannot be opened and the request is wider than 24 or 16 bits, the module tries 24-bit and then 16-bit output. The resulting device precision can be queried with ao_real_output_bits_async.

The result is an asynchronous audio handle, or #f when no device or output file could be opened. Handles should be closed with ao_stop_async. A finalizer is also registered as a safety net, but explicit stopping is the intended lifecycle.

3 Buffer descriptions🔗ℹ

The type field controls whether the incoming buffer is already interleaved. Use 'interleaved or the older name 'ao for ordinary PCM in frame order. Use 'planar or the older name 'flac when each channel is stored as a separate plane. Planar input is copied to an interleaved buffer before it is queued.

Samples are treated as signed integer PCM. sample-bits must describe whole bytes, such as 16, 24 or 32 bits. The conversion code uses the supplied endianness when reading input samples and when writing converted output samples.

4 Queuing audio🔗ℹ

The position values at-second, music-duration and music-id are copied into the queue element. When the worker thread starts playing that element, these values become visible through ao_is_at_second_async, ao_music_duration_async and ao_is_at_music_id_async.

If the input buffer is planar, it is first converted to interleaved PCM. If the input sample width or endianness differs from the opened output device, the sample data is converted before queueing. Small input chunks are collected into larger queue elements of roughly 250 milliseconds, unless the music id changes or the current assembled buffer is full.

5 Playback state🔗ℹ

6 Volume and output format🔗ℹ

Volume is applied by the worker thread immediately before copying the playback chunk to the foreign buffer passed to libao. Scaled samples are clipped to the signed range of the opened output sample width.

7 Implementation strategy🔗ℹ

The module keeps libao as the only native audio backend, but moves the async queue and playback thread from C to Racket. It initializes libao lazily when the first handle or temporary driver query is opened. A small reference count is used so ao_shutdown is called when the last opened handle is closed. A custodian and exit finalizer call shutdown as a last resort.

The worker thread is created with its own thread pool. It waits for queue elements, observes the pause lock, applies volume when necessary, copies the chunk into foreign memory allocated as 'atomic-interior, and calls libao. The foreign ao_play binding is marked as blocking. The combination matters: libao may retain the pointer for the duration of the call, and a blocking foreign call should not receive movable Racket byte storage directly.

Small decoder buffers are combined before reaching libao. The target chunk size is controlled by the internal ao-buf-ms value, currently 250 milliseconds. The buffer reuse pool keeps allocated byte strings around for future chunks, reducing allocation churn in long playback sessions.

The conversion path is intentionally narrow. Planar input is converted to interleaved PCM. Sample width conversion is done with arithmetic shifts, and endianness conversion is handled through Racket byte operations. This backend therefore expects integer PCM with byte-aligned sample widths.

8 Compatibility notes🔗ℹ

The exported names are kept compatible with the old "libao-async-ffi.rkt" layer. In particular, make-BufferInfo_t remains available even though the actual value is a Racket struct, not a C struct. The higher layers can therefore select this module as an implementation backend without changing the playback API.

The queue state functions report the backend’s own administration. They do not query libao for device latency, and they do not know how many samples are already buffered by the operating system or the audio driver.