#include <audio_source.h>

Public Member Functions
	AudioSource (int sample_rate, int num_channels, int queue_size_ms=0)

	AudioSource (const AudioSource &)=delete

AudioSource &	operator= (const AudioSource &)=delete

	AudioSource (AudioSource &&) noexcept=default

AudioSource &	operator= (AudioSource &&) noexcept=default

int	sample_rate () const noexcept
	The sample rate of the audio source in Hz.

int	num_channels () const noexcept
	The number of audio channels.

std::uint64_t	ffi_handle_id () const noexcept
	Underlying FFI handle ID used in FFI requests.

double	queuedDuration () const noexcept
	Current duration of queued audio (in seconds).

void	clearQueue ()

void	captureFrame (const AudioFrame &frame, int timeout_ms=20)

Detailed Description

Represents a real-time audio source with an internal audio queue.

Constructor & Destructor Documentation

◆ AudioSource()

livekit::AudioSource::AudioSource	(	int	sample_rate,
		int	num_channels,
		int	queue_size_ms = `0`
	)

Create a new native audio source.

Parameters

sample_rate	Sample rate in Hz.
num_channels	Number of channels.
queue_size_ms	Max buffer duration for the internal queue in ms.

Buffering behavior:

queue_size_ms == 0 (recommended for real-time capture): Disables internal buffering entirely. Audio frames are forwarded directly to WebRTC sinks and consumed synchronously.

This mode is optimized for real-time audio capture driven by hardware media callbacks (e.g. microphone capture). The caller is expected to provide fixed-size real-time frames (typically 10 ms per call).

Because the native side consumes frames immediately, this mode minimizes latency and jitter and is the best choice for live capture scenarios.
queue_size_ms > 0 (buffered / blocking mode): Enables an internal queue that buffers audio up to the specified duration. Frames are accumulated and flushed asynchronously once the buffer reaches its threshold.

This mode is intended for non-real-time producers (e.g. TTS engines, file-based audio, or agents generating audio faster or slower than real-time). The buffering layer smooths timing and allows the audio to be streamed out in real time even if the producer is bursty.

queue_size_ms must be a multiple of 10.

Member Function Documentation

◆ captureFrame()

void livekit::AudioSource::captureFrame	(	const AudioFrame &	frame,
		int	timeout_ms = `20`
	)

Push an AudioFrame into the audio source and BLOCK until the FFI callback confirms that the native side has finished processing (consuming) the frame. Safe usage: The frame's internal buffer must remain valid only until this function returns. Because this call blocks until the corresponding FFI callback arrives, the caller may safely destroy or reuse the frame afterward.

Parameters

frame	The audio frame to send. No-op if the frame contains zero samples.
timeout_ms	Maximum time to wait for the FFI callback. If timeout_ms > 0: block up to this duration. A timeout will cause std::runtime_error. If timeout_ms == 0: wait indefinitely until the callback arrives (recommended for production unless the caller needs explicit timeout control).

Blocking semantics: The blocking behavior of this call depends on the buffering mode selected at construction time:

queue_size_ms == 0 (real-time capture mode): Frames are consumed synchronously by the native layer. The FFI callback is invoked immediately as part of the capture call, so this function returns quickly.

This mode relies on the caller being paced by a real-time media callback (e.g. audio hardware interrupt / capture thread). It provides the lowest possible latency and is ideal for live microphone capture.
queue_size_ms > 0 (buffered / non-real-time mode): Frames are queued internally and flushed asynchronously. This function will block until the buffered audio corresponding to this frame has been consumed by the native side and the FFI callback fires.

This mode is best suited for non-real-time audio producers (such as TTS engines or agents) that generate audio independently of real-time pacing, while still streaming audio out in real time.

Safety notes: May throw std::runtime_error if:

the FFI reports an error
a timeout occurs in bounded-wait mode

◆ clearQueue()

void livekit::AudioSource::clearQueue ( )

Clears the internal audio queue on the native side and resets local queue tracking.

The documentation for this class was generated from the following file:

include/livekit/audio_source.h