Class thl::AudioPlayerSource

class AudioPlayerSource : public thl::AudioIODeviceCallback

Inheritance diagram for thl::AudioPlayerSource:

Collaboration diagram for thl::AudioPlayerSource:

Audio callback that plays back audio from a file using async decoding.

AudioPlayerSource implements AudioIODeviceCallback to decode audio from a file and output it to the audio device. It uses the backend’s resource manager for asynchronous streaming and decoding, making the audio thread read from pre-decoded buffers rather than performing blocking file I/O.

The typical usage pattern is:

1. Construct an AudioPlayerSource

2. Call load_file() with the audio file path

3. Register with AudioDeviceManager::addPlaybackCallback()

4. Call play() to begin playback

5. Call pause() or stop() to control playback

6. Call unload_file() or let the destructor handle cleanup

File Lifecycle

• play() - Starts or resumes playback from the current position

• pause() - Pauses playback, maintaining the current position

• stop() - Stops playback and resets to the beginning

• seek_to_frame() - Seeks to a specific frame position

Playback Control

• load_file(), unload_file(), and seek_to_frame() are NOT real-time safe.

• play(), pause(), and stop() use atomic operations and are safe to call from any thread, though stop() also performs a seek operation.

• process() reads from pre-decoded buffers managed by the resource manager’s background thread, making it suitable for real-time audio processing.

Real-Time Safety

Use set_finished_callback() to be notified when playback reaches the end of the file. The callback is invoked from the audio thread, so it must be real-time safe (no allocations, locks, or blocking).

Finished Callback

AudioPlayerSource player;
player.load_file("audio.wav", 2, 48000);
player.set_finished_callback([]() {
    // Handle end of file (must be RT-safe!)
});
manager.addPlaybackCallback(&player);
manager.startPlayback();
player.play();

See also

AudioIODeviceCallback

See also

AudioFileSink for the complementary recording class

Public Types

using FinishedCallback = std::function<void()>

Callback type invoked when playback reaches the end of the file.

Warning

The callback is invoked from the audio thread and MUST be real-time safe.

Public Functions

AudioPlayerSource()

Constructs an AudioPlayerSource with no file loaded.

Initialises the internal resource manager for async decoding.

~AudioPlayerSource() override

Destructs the AudioPlayerSource, unloading any file.

Warning

NOT real-time safe - waits for background threads to complete.

AudioPlayerSource(const AudioPlayerSource&) = delete

Copy constructor (deleted - AudioPlayerSource is non-copyable)

AudioPlayerSource &operator=(const AudioPlayerSource&) = delete

Copy assignment (deleted - AudioPlayerSource is non-copyable)

bool load_file(const std::string &file_path, uint32_t output_channels, uint32_t output_sample_rate)

Loads an audio file for playback with async streaming.

Initialises the data source with streaming enabled. The resource manager will decode audio on a background thread, allowing the audio thread to read from pre-decoded buffers.

Warning

NOT real-time safe - performs file I/O and allocations.

Parameters:

• file_path – Path to the audio file to load.

• output_channels – Number of output channels (audio will be converted if needed).

• output_sample_rate – Output sample rate in Hz (audio will be resampled if needed).

Returns:

true if the file was loaded successfully, false otherwise.

bool load_from_memory(const void *data, size_t size, uint32_t output_channels, uint32_t output_sample_rate)

Loads audio from an in-memory buffer for playback.

Initialises a streaming data source from the provided memory buffer. The caller must keep the memory alive for the lifetime of this player (or until unload_file() / load_file() / load_from_memory() is called).

Warning

NOT real-time safe - performs allocations.

Parameters:

• data – Pointer to the binary audio data.

• size – Size of the data in bytes.

• output_channels – Number of output channels (audio will be converted if needed).

• output_sample_rate – Output sample rate in Hz (audio will be resampled if needed).

Returns:

true if the data was loaded successfully, false otherwise.

void unload_file()

Unloads the currently loaded file.

Stops playback and releases decoder resources. Safe to call even if no file is loaded.

Warning

NOT real-time safe - waits for background decoding to complete.

void play()

Starts or resumes playback.

Has no effect if no file is loaded. Playback begins from the current position.

Note

Thread-safe - uses atomic operations.

void pause()

Pauses playback.

Playback can be resumed from the current position with play().

Note

Thread-safe - uses atomic operations.

void stop()

Stops playback and resets to the beginning.

Equivalent to pause() followed by seek_to_frame(0). This is a hard stop — audio output stops immediately. Use request_stop() for a click-free fade-out.

Warning

NOT real-time safe - seeking may block.

void request_stop()

Requests a click-free stop with a short fade-out (~1 ms).

Signals the audio thread to ramp the output to zero over kFadeSamples frames. When the fade completes, playback is stopped and the finished callback is invoked. Safe to call from any thread.

Note

Thread-safe — uses atomic operations. The actual stop happens asynchronously on the audio thread.

inline bool is_playing() const

Checks if playback is currently active.

Note

Thread-safe - uses atomic operations.

Returns:

true if playing, false if paused or stopped.

inline bool is_loaded() const

Checks if a file is currently loaded.

Returns:

true if a file is loaded and ready for playback, false otherwise.

void seek_to_frame(uint64_t frame)

Seeks to a specific frame position.

Warning

NOT real-time safe - may trigger buffer refill.

Parameters:

frame – The target frame position (0 = beginning of file).

uint64_t get_current_frame() const

Gets the current playback position in frames.

Returns:

Current frame position, or 0 if no file is loaded.

uint64_t get_total_frames() const

Gets the total length of the loaded file in frames.

Returns:

Total number of frames, or 0 if no file is loaded.

void set_finished_callback(FinishedCallback callback)

Sets a callback to be invoked when playback finishes.

The callback is invoked from the audio thread when playback reaches the end of the file. To receive another notification, playback must be restarted (e.g., with stop() followed by play()).

Warning

The callback runs on the audio thread and MUST be real-time safe. Do not perform allocations, locks, or blocking operations.

Parameters:

callback – The callback function, or nullptr to clear.

virtual void prepare_to_play(uint32_t sample_rate, uint32_t buffer_size) override

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.

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

Processes audio by reading from pre-decoded buffers.

If playing and a file is loaded, reads audio frames from the resource manager’s pre-decoded buffer and writes them to the output buffer. When the end of file is reached, remaining samples are zeroed and the finished callback is invoked.

Note

This method reads from pre-decoded buffers and is real-time safe.

Parameters:

• output_buffer – Buffer to fill with decoded audio.

• input_buffer – Ignored - playback does not use input.

• frame_count – Number of frames to read.

• num_input_channels – Number of input channels (unused).

• num_output_channels – Number of output channels.

virtual void release_resources() override

Releases resources by unloading any loaded file.

Called by AudioDeviceManager when audio is stopped or when this callback is removed.

Warning

NOT real-time safe - performs deallocations.

inline void set_fade_enabled(bool enabled)

inline bool is_fade_enabled() const

Public Static Attributes

static constexpr uint32_t k_fade_samples = 64

Number of frames used for micro fade-in/out (~1.3 ms at 48 kHz).