libao🔗ℹ

1 Audio handles🔗ℹ

A handle becomes invalid after ao-close, or when opening the native player failed.

This can differ from the bit depth requested with ao-open-live or ao-open-file. For example, when 32-bit output is requested but the libao driver only accepts 24-bit output, this function returns 24.

2 Validation predicates🔗ℹ

The accepted rates are:

• 8000, 11025, 16000, 22050

• 44100, 48000, 88200, 96000

• 176400, 192000, 352800, 384000

The symbol does not describe an encoded audio format. It describes the in-memory layout of the PCM buffer passed to ao-play. 'ao means interleaved PCM samples. 'flac means channel-oriented PCM samples, as produced by the FLAC decoder, which must be converted to interleaved PCM before playback.

3 Opening and closing🔗ℹ

This is equivalent to calling ao-open-file with #f as the filename.

The handle stores the requested sample size, sample rate, channel count, and byte format. The native backend first tries to open the device with the requested bit depth. If that fails, it may fall back to a lower bit depth accepted by the selected libao driver.

The requested bit depth describes the buffers supplied by the Racket side. The real device bit depth describes the format accepted by libao and can be inspected with ao-device-bits.

If the native player is created successfully, the returned handle is valid. If player creation fails, the function still returns an ao-handle, but that handle is marked closed and is not valid for playback.

A finalizer is registered for the handle and calls ao-close when the handle is reclaimed.

If filename is #f, the default live libao output device is opened. Otherwise the native backend opens a file output target using the given filename.

The requested bit depth is stored in the handle and describes the input buffers that will be queued with ao-play. The native backend also records the real bit depth accepted by the output device or file backend. Use ao-device-bits to inspect that value.

If the handle already has no native player, this procedure has no effect.

4 Playback🔗ℹ

The music-id argument identifies the music stream associated with the buffer. The arguments at-time-in-s and music-duration-s describe the position and duration, in seconds, associated with the buffer. The arguments buffer and buf-len provide the audio data and its length. The buf-type argument specifies the in-memory PCM layout.

The buffer description passed to the native layer is completed with the requested sample size, sample rate, channel count, and byte format stored in handle.

Two buffer layouts are supported:

• 'ao: interleaved PCM samples, for example L0 R0 L1 R1.

• 'flac: channel-oriented PCM samples, for example one channel buffer for left samples and one channel buffer for right samples.

The native backend converts 'flac buffers to interleaved PCM before playback. It also converts between the requested bit depth and the real device bit depth when needed. This makes it possible to keep decoder output at 32-bit signed integer PCM while still playing on devices that only accept 24-bit or 16-bit integer samples.

The queued buffer is copied by the native backend, so the caller does not need to keep the original buffer alive after ao-play returns.

If handle is not valid, this procedure raises an exception.

A true value pauses playback. #f resumes playback.

5 Playback state🔗ℹ

6 Volume control🔗ℹ

If percentage is an exact integer, it is converted to an inexact number before it is passed to the native layer.

7 Notes🔗ℹ

This module is a higher-level wrapper around the asynchronous FFI layer. It stores the playback configuration in the handle, and reuses that configuration for each call to ao-play.

The requested bit depth and the real device bit depth are deliberately kept separate. The requested value describes the buffers supplied by the Racket side. The real value describes the format accepted by libao.

The module does not expose the handle fields directly. The public API is intentionally small: create a handle, queue buffers, inspect position and buffer state, pause or clear playback, adjust volume, and close the handle.

A typical usage pattern is to open one live handle for a given stream format, queue decoded buffers with ao-play, and query the playback position with ao-at-second while playback proceeds asynchronously.