1 Introduction racket-audio
racket-audio is a small audio playback toolkit for Racket. It combines high-level asynchronous playback, optional metadata reading, file type sniffing, decoder backends, and libao based output. Most applications should start with the high-level player API and only use the lower-level modules when they need to add a decoder, inspect the playback pipeline, or debug the native FFI boundary.
1.1 APIs for normal users
For ordinary playback, use racket-audio/audio-player. It creates an audio player, starts the worker side, and exposes procedures such as make-audio-player, audio-play!, audio-pause!, audio-stop!, audio-seek!, and audio-quit!. The player is asynchronous: commands return after they have been accepted, while state updates and end-of-stream notifications are delivered through callbacks.
Use racket-audio/taglib when an application needs metadata such as title, artist, album, duration-related properties, generic TagLib properties, or embedded cover art. The module reads metadata into a Racket-side snapshot and does not keep the native TagLib file handle open.
Use racket-audio/audio-sniffer when file type detection should be based on file contents rather than only on extensions. The sniffer is useful before choosing a decoder, validating input, or presenting a likely media type to the user.
The racket-audio/play-test module is not a library API, but it is a useful integration example. In particular, its queue mode, selected with (set-test 'queue), shows how an EOF callback can start the next item in a simple playback queue.
1.2 Lower-level modules for geeks
The modules below are normally used by the player implementation rather than by application code. They are documented because they are useful when extending, debugging, or replacing parts of the pipeline.
racket-audio/audio-placed-player implements the worker side of the high-level player. It is normally run in a Racket place, so the timing-sensitive audio feeder runs in a separate VM, but it can also be run in a thread with async channels for easier debugging.
racket-audio/audio-decoder provides the decoder registry and a uniform open/read/seek/stop interface over concrete decoder backends.
racket-audio/mp3-decoder, racket-audio/flac-decoder, and racket-audio/ffmpeg-decoder are concrete decoder frontends. The FFmpeg path is the general-purpose fallback for formats not handled by the specialised decoders.
racket-audio/libao and racket-audio/libao-async-ffi-racket form the output side: they open the native audio device, queue PCM buffers, apply volume, and feed libao asynchronously.
racket-audio/ffmpeg-ffi, racket-audio/ffmpeg-definitions, and the FFmpeg C backend documentation describe the native FFmpeg boundary, the direct FFI definitions, version-sensitive structures, and the fixed PCM format used by the decoder pipeline.
In short: applications should usually combine racket-audio/audio-player with racket-audio/taglib. The other modules document the machinery underneath: format detection, decoder selection, place-based playback, buffering, native output, and FFmpeg access.