Class thl::AudioFileSink#

class AudioFileSink : public thl::AudioIODeviceCallback #

Inheritance diagram for thl::AudioFileSink:

Collaboration diagram for thl::AudioFileSink:

Audio callback that records input audio to a file.

AudioFileSink implements AudioIODeviceCallback to capture audio input and encode it to a file. It supports various audio formats through the backend encoder interface.

The typical usage pattern is:

Construct an AudioFileSink
Call open_file() with the desired path and format
Register with AudioDeviceManager::addPlaybackCallback()
Call start_recording() to begin capturing audio
Call stop_recording() when done
Call close_file() or let the destructor handle cleanup

File Lifecycle

open_file(), close_file(), start_recording(), and stop_recording() are NOT real-time safe and should only be called from the main thread.
process() writes to the file which involves I/O. While the write itself may block, this is typically acceptable for recording scenarios. For strict real-time requirements, consider buffering to a lock-free queue.

Real-Time Safety

The format parameter in open_file() controls the output file format:

AudioEncodingFormat::WAV (default) - Uncompressed WAV
AudioEncodingFormat::FLAC - FLAC lossless compression

Supported Formats

AudioFileSink recorder;
recorder.open_file("recording.wav", 2, 48000);
manager.addPlaybackCallback(&recorder);
manager.startPlayback();
recorder.start_recording();
// ... record audio ...
recorder.stop_recording();
manager.stopPlayback();

See also

AudioPlayerSource for the complementary playback class

Public Functions

AudioFileSink()#: Constructs an AudioFileSink in the closed state.

~AudioFileSink() override#: Destructs the AudioFileSink, closing any open file.

Warning

NOT real-time safe - may perform file I/O.

AudioFileSink(const AudioFileSink&) = delete#: Copy constructor (deleted - AudioFileSink is non-copyable)

AudioFileSink &operator=(const AudioFileSink&) = delete#: Copy assignment (deleted - AudioFileSink is non-copyable)

bool open_file(const std::string &file_path, uint32_t channels, uint32_t sample_rate, AudioEncodingFormat format = AudioEncodingFormat::WAV)#

Opens a file for audio recording.

Initialises the encoder and prepares the file for writing. Any previously open file is closed first.

Warning

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

Parameters:

file_path – Path to the output file.
channels – Number of audio channels to record.
sample_rate – Sample rate in Hz.
format – Encoding format (default: WAV).

Returns:

true if the file was opened successfully, false otherwise.

void close_file()#

Closes the currently open file.

Stops recording if active and finalises the file. Safe to call even if no file is open.

Warning

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

void start_recording()#

Begins recording audio to the open file.

Has no effect if no file is open. Recording state can be toggled without reopening the file.

Note

Thread-safe - uses atomic operations.

void stop_recording()#

Stops recording audio.

Audio data received after this call will not be written to the file. The file remains open and recording can be resumed with start_recording().

Note

Thread-safe - uses atomic operations.

inline bool is_recording() const#

Checks if audio is currently being recorded.

Note

Thread-safe - uses atomic operations.

Returns:: true if recording is active, false otherwise.

inline bool is_open() const#

Checks if a file is currently open.

Returns:: true if a file is open and ready for recording, false otherwise.

inline uint64_t get_frames_written() const#

Gets the total number of frames written to the file.

Note

Thread-safe - uses atomic operations.

Returns:: Number of audio frames written since the file was opened.

inline float get_peak_level() const#

Gets the peak amplitude of the most recent audio block.

Note

Thread-safe - uses atomic operations.

Returns:: Peak level (0.0 to 1.0+) from the last processed block.

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 input and writes to file if recording.

If recording is active and a file is open, writes the input buffer to the file. The output buffer is not modified.

Note

This method performs file I/O and may block.

Parameters:

output_buffer – Ignored - recording does not produce output.
input_buffer – Audio data to record.
frame_count – Number of frames in the buffer.
num_input_channels – Number of input channels.
num_output_channels – Number of output channels (unused).

virtual void release_resources() override#

Releases resources by closing any open file.

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

Warning

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