Class thl::AudioIODeviceCallback

class AudioIODeviceCallback

Inheritance diagram for thl::AudioIODeviceCallback:

Abstract interface for receiving audio I/O callbacks from an AudioDeviceManager.

AudioIODeviceCallback defines the interface for objects that process audio data. Implementations receive audio input buffers and produce audio output through the process() method, which is called from the audio thread.

The process() method is called from the audio thread and must be real-time safe:

• No memory allocation

• No blocking operations (locks, I/O, system calls)

• No unbounded loops

• Deterministic execution time

Real-Time Safety

The prepare_to_play() and release_resources() methods are called from the main thread and may perform allocations and other non-real-time-safe operations.

To use this interface:

1. Derive from AudioIODeviceCallback and implement process()

2. Optionally override prepare_to_play() for initialisation

3. Optionally override release_resources() for cleanup

4. Register the callback with AudioDeviceManager::addPlaybackCallback(), addCaptureCallback(), or addDuplexCallback()

Usage

class MyProcessor : public AudioIODeviceCallback {
public:
    void process(float* output, const float* input,
                 uint32_t frame_count,
                 uint32_t num_input_channels,
                 uint32_t num_output_channels) override {
        // Process audio here (real-time safe!)
        if (!output || !input) return;
        for (uint32_t i = 0; i < frame_count * num_output_channels; ++i) {
            output[i] = input[i] * 0.5f;  // Simple gain reduction
        }
    }
};

See also

AudioDeviceManager::addPlaybackCallback()

See also

AudioDeviceManager::removePlaybackCallback()

See also

AudioDeviceManager::addCaptureCallback()

See also

AudioDeviceManager::removeCaptureCallback()

See also

AudioDeviceManager::addDuplexCallback()

See also

AudioDeviceManager::removeDuplexCallback()

Subclassed by thl::AudioFileSink, thl::AudioPlayerSource

Public Functions

virtual ~AudioIODeviceCallback() = default

Virtual destructor for proper cleanup of derived classes.

virtual void process(float *output_buffer, const float *input_buffer, uint32_t frame_count, uint32_t num_input_channels, uint32_t num_output_channels) = 0

Processes audio data from input to output buffers.

This method is called repeatedly from the audio thread to process audio. The output buffer should be filled with audio data; it may contain uninitialised data on entry.

Warning

MUST BE REAL-TIME SAFE - Called from the audio thread. No allocations, locks, or blocking operations allowed.

Parameters:

• output_buffer – Pointer to the interleaved output buffer to fill. Size is frame_count * num_output_channels floats. May be nullptr if no output device is active.

• input_buffer – Pointer to the interleaved input buffer containing captured audio. Size is frame_count * num_input_channels floats. May be nullptr if no input device is active.

• frame_count – Number of audio frames to process. Each frame contains num_input_channels/num_output_channels samples.

• num_input_channels – Number of input channels (interleaved).

• num_output_channels – Number of output channels (interleaved).

inline virtual void prepare_to_play(uint32_t sample_rate, uint32_t buffer_size)

Called before audio processing begins to allow resource preparation.

Override this method to allocate buffers, initialise DSP state, or perform other setup that depends on the audio configuration. This is called from the main thread when the audio device is started.

Note

Called from the main thread - may perform allocations and blocking operations.

Note

Default implementation does nothing.

Parameters:

• sample_rate – The sample rate at which audio will be processed (e.g., 44100, 48000).

• buffer_size – The number of frames that will be passed to each process() call.

inline virtual void release_resources()

Called when audio processing stops to allow resource cleanup.

Override this method to release buffers, reset DSP state, or perform other cleanup. This is called from the main thread when the audio device is stopped or when this callback is removed from the device manager.

Note

Called from the main thread - may perform deallocations and blocking operations.

Note

Default implementation does nothing.