10.1 Reader registration🔗ℹ

A reader descriptor stores the extensions handled by a backend together with the procedures used to validate, open, read, seek, and stop that backend, plus an audio-output type.

The exts list contains the filename extensions handled by the reader, without a leading dot. Matching is case-insensitive.

The procedures are used as follows:

• valid? checks whether a file is valid for this reader;

• open opens a decoder for a file;

• reader reads or continues decoding;

• seeker seeks within the audio stream;

• stopper stops an active decode loop.

The ao-type value describes the buffer format exposed to the audio output layer. The source comments mention values such as 'flac and 'ao. The value 'ao means that the buffer can be used directly by the audio-output backend.

The extensions declared in reader are appended to the list returned by audio-known-exts?, and the reader becomes available to audio-open.

This procedure is the extension point for custom audio decoders.

10.2 Audio handles🔗ℹ

For the built-in readers this is usually 'flac, 'mp3, 'opusfile, or 'ffmpeg.

10.3 Known extensions and validation🔗ℹ

The initial list contains the extensions handled by the built-in readers: "flac", "mp3", Opus/Ogg extensions such as "opus", "ogg", and "oga", and the extensions handled by the FFmpeg reader. Additional extensions are added when readers are registered with audio-register-reader!.

10.4 Built-in decoder selection🔗ℹ

The built-in decoder table contains:

• 'flac for FLAC files;

• 'mp3 for MP3 files;

• 'opusfile for Ogg Opus streams through Xiph libopusfile;

• 'ffmpeg for formats handled by the FFmpeg backend.

When a file is opened, the module first asks audio-sniff-format/extension for the detected format. Opus streams are mapped to 'opusfile when libopusfile is available and to 'ffmpeg otherwise.

The Opusfile decoder has one global setting for its PCM output format: current-opusfile-output-format. This setting is re-exported by this module for callers that use only the generic decoder API.

The default is 's16. Set it to 's24 before opening or reading an Opus file when the playback pipeline should receive packed signed 24-bit PCM instead of signed 16-bit PCM.

The argument is converted to a string. If it starts with a dot, that dot is removed. Matching is case-insensitive.

This procedure first derives the filename extension and checks it with audio-valid-ext?. If the extension is known, it then looks up the matching reader and calls that reader’s validity procedure.

10.5 Opening and callbacks🔗ℹ

If audio-file is a path, it is converted to a string before it is passed to the backend open procedure.

This procedure raises an exception if the file is not considered a valid audio file, if the file does not exist, or if no registered reader can be found for the file.

The returned handle stores the selected reader type, the two callback procedures, the reader descriptor, and the driver-specific handle returned by the backend open procedure.

The callback procedures are wrapped before they are passed to the backend.

The stream-info callback is called as:

(cb-stream-info audio-type ao-type handle meta)

where:

• audio-type is the registered reader type, such as 'flac, 'mp3, 'opusfile, or 'ffmpeg;

• ao-type is the audio-output type stored in the reader, such as 'flac or 'ao;

• handle is the generic audio-handle;

• meta is a hash table with stream metadata.

According to the source comments, meta must contain at least:

• 'duration — duration of the audio in seconds, possibly fractional;

• 'bits-per-sample — number of audio bits per sample;

• 'channels — number of audio channels;

• 'sample-rate — number of samples per second per channel;

• 'total-samples — total number of samples in the audio.

The audio callback is called as:

(cb-audio audio-type ao-type handle buf-info buffer buf-size)

where:

• audio-type is the registered reader type;

• ao-type is the audio-output type stored in the reader;

• handle is the generic audio-handle;

• buf-info is a hash table describing the audio buffer;

• buffer is a native buffer containing audio data;

• buf-size is the size of that buffer in bytes.

According to the source comments, the buffer is to be owned and released by the decoder driver. The comments also note that the ao-async backend copies the data.

According to the source comments, buf-info must contain at least:

• 'duration — duration of the audio in seconds, possibly fractional;

• 'bits-per-sample — number of audio bits per sample;

• 'channels — number of audio channels;

• 'sample-rate — number of samples per second per channel;

• 'total-samples — total number of samples in the audio;

• 'sample — the current sample to which the audio buffer applies.

10.6 Reading, seeking, and stopping🔗ℹ

The concrete reader procedure receives the driver-specific handle stored in the generic audio handle. Any result value produced by the backend is discarded.

The percentage argument is passed unchanged to the backend seek procedure.

In this abstraction layer, the parameter represents a relative position in the full audio stream. A backend registered through audio-register-reader! is expected to follow that interpretation.

The concrete stop procedure receives the driver-specific handle stored in the generic audio handle.

10.7 Using custom decoders🔗ℹ

Custom audio decoders can be integrated by constructing a reader descriptor with make-audio-reader and registering it with audio-register-reader!.

A backend integrated through this interface should provide:

• a list of handled filename extensions;

• a file-validity procedure;

• an open procedure that accepts a file path, a stream-info callback, and an audio callback;

• a read procedure that accepts the driver-specific handle;

• a seek procedure that accepts the driver-specific handle and a numeric relative position;

• a stop procedure that accepts the driver-specific handle;

• an audio-output type symbol describing the kind of buffers the backend produces.

Once registered, files with matching extensions can be opened through audio-open in the same way as the built-in FLAC, MP3, Opusfile, and FFmpeg backends.