libao
| (require "libao.rkt") | package: racket-sound |
This module provides a small high-level interface to an asynchronous audio output backend. It opens a live output device, queues audio buffers for playback, reports playback position, supports pause and buffer clearing, and exposes a small set of validation predicates.
The central value is an ao-handle, created by ao-open-live. An ao-handle stores the playback configuration together with a native asynchronous player handle.
1 Audio handles
procedure
(ao-handle? v) → boolean?
v : any/c
procedure
(ao-valid? handle) → boolean?
handle : ao-handle?
A handle becomes invalid after ao-close, or when ao-open-live failed to create the native player.
2 Validation predicates
procedure
(ao-valid-bits? bits) → boolean?
bits : any/c
procedure
(ao-valid-rate? rate) → boolean?
rate : any/c
The accepted rates are:
8000, 11025, 16000, 22050,
44100, 48000, 88200, 96000,
176400, 192000, 352800, and
384000.
procedure
(ao-valid-channels? channels) → boolean?
channels : any/c
procedure
(ao-valid-format? format) → boolean?
format : any/c
procedure
(ao-supported-music-format? format) → boolean?
format : any/c
This value is used by ao-play to describe the format of the buffer being queued.
3 Opening and closing
procedure
bits : ao-valid-bits? rate : ao-valid-rate? channels : ao-valid-channels? byte-format : ao-valid-format?
The handle stores the given sample size, sample rate, channel count, and byte format. It then tries to create a native asynchronous player.
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.
procedure
(ao-close handle) → void?
handle : ao-handle?
If the handle already has no native player, this procedure has no effect.
4 Playback
procedure
(ao-play handle music-id at-time-in-s music-duration-s buffer buf-len buf-type) → void? handle : ao-handle? music-id : integer? at-time-in-s : number? music-duration-s : number? buffer : any/c buf-len : integer? buf-type : ao-supported-music-format?
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 buffer format.
The buffer description passed to the native layer is completed with the sample size, sample rate, channel count, and byte format stored in handle.
If handle is not valid, this procedure raises an exception.
A true value pauses playback. #f resumes playback.
procedure
(ao-clear-async handle) → void?
handle : ao-handle?
5 Playback state
procedure
(ao-at-second handle) → number?
handle : ao-handle?
procedure
(ao-at-music-id handle) → integer?
handle : ao-handle?
procedure
(ao-music-duration handle) → number?
handle : ao-handle?
procedure
(ao-bufsize-async handle) → integer?
handle : ao-handle?
6 Volume control
If percentage is an exact integer, it is converted to an inexact number before it is passed to the native layer.
procedure
(ao-volume handle) → number?
handle : ao-handle?
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 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.