C++ voice activity detection

C++ wrapper 0.25.0, core 0.25.0, C++11 or newer. Include aic.hpp and link the matching wrapper/native libraries. Start with the C++ integration guide. All names below are in namespace aic. Check Result and error handling before extracting a factory result. Ordinary C++ allocation or string operations can still throw; SDK status failures use the declared return values.

`aic::Vad`

Owns one native handle. Its destructor releases that handle; do not destroy or move the object while another thread uses it. Construction/destruction can allocate or block, so keep them outside the audio callback. The default constructor and raw-handle constructor are private: use the documented factory.

Member	Contract
`~Vad()`	Releases the native handle if non-null.
`Vad(Vad&& other) noexcept`	Transfers the handle and clears the source. Do not call processing/getter methods on the moved-from object.
`Vad& operator=(Vad&& other) noexcept`	Releases the destination’s old handle, transfers ownership and clears the source. Self-move is guarded; returns `*this`.
`Vad(const Vad&) = delete`	Copy construction is unavailable.
`Vad& operator=(const Vad&) = delete`	Copy assignment is unavailable.

`aic::Vad::create`

static Result<Vad> create(const Model& model, const std::string& license_key,
                              const OtelConfig* otel_config = nullptr);

Creates an owned Vad using a dedicated VAD model and the null-terminated representation of license_key (SDK key or supported bearer token). The object retains model data; no ownership of the Model wrapper is transferred. otel_config is optional and is copied during creation. Returns a checked result; errors include ModelTypeUnsupported, license errors and InternalError. Construction does not initialize audio configuration. Keep it outside the audio callback.

`aic::Vad::initialize`

ErrorCode initialize(uint32_t sample_rate, size_t block_size, bool variable_block_size);

Initializes or reinitializes the object. sample_rate is the host rate in Hz (8,000–192,000); block_size is a positive mono sample count. With variable_block_size=false, input must match exactly; with true, it is the maximum per call. All three arguments are required: there is no config-object overload. Returns Success or AudioConfigUnsupported (or NullPointer for an invalid underlying handle). Failure leaves the object uninitialized. Initialization resets state and allocates; serialize it with processing.

`aic::Vad::process`

ErrorCode process(const float* audio, size_t audio_len);

Reads audio_len mono float32 samples from audio and copies them to an internal buffer. It does not modify the caller’s buffer. On success, read the updated decision through the context. Use normalized samples, nominally -1.0 to 1.0. Returns Success, NullPointer, NotInitialized, AudioConfigMismatch or ProcessingNotAllowed (and internal errors). Do not use a stale VAD decision after a failed call. Keep one instance per stream and serialize its processing calls.

`aic::Vad::terminate_session`

ErrorCode terminate_session();

Requests asynchronous session termination and returns Success (or NullPointer for an invalid underlying handle). Processing may continue until the request is handled. It is a no-op for a credential with no telemetry session. The call neither destroys the object nor proves backend acknowledgment. Stop application processing explicitly, then allow normal destruction. On native targets, terminating the final active session may wait for the shared telemetry tasks to finish. Call it outside the audio callback.

`aic::Vad::create_context`

Result<VadContext> create_context() const;

Creates a separately owned control object with shared state. Check the result before extracting it. The context can outlive its source object, but it cannot process audio after that object is destroyed. Errors include NullPointer and InternalError if a VAD context is unavailable. Context creation allocates.

`aic::VadContext`

Member	Contract
`~VadContext()`	Releases the native handle if non-null.
`VadContext(VadContext&& other) noexcept`	Transfers the handle and clears the source. Do not call processing/getter methods on the moved-from object.
`VadContext& operator=(VadContext&& other) noexcept`	Releases the destination’s old handle, transfers ownership and clears the source. Self-move is guarded; returns `*this`.
`VadContext(const VadContext&) = delete`	Copy construction is unavailable.
`VadContext& operator=(const VadContext&) = delete`	Copy assignment is unavailable.

Context control reads, parameter updates and reset requests use shared state and can run alongside processing. Keep handles alive through all concurrent calls. Credential updates are control-thread operations; destruction is never concurrent-safe.

`aic::VadContext::reset`

ErrorCode reset() const;

Requests processing-state reset for the next audio call and immediately clears the published decision and probability. Audio configuration and parameters remain in place. Returns Success or NullPointer. Coordinate the stream boundary if you require a precise reset position.

`aic::VadContext::set_parameter`

ErrorCode set_parameter(VadParameter parameter, float value) const;

Sets a declared VadParameter to value. Returns Success, NullPointer or ParameterOutOfRange; NaN is out of range. The parameter table below defines units, defaults and accepted ranges.

`aic::VadContext::get_parameter`

float get_parameter(VadParameter parameter) const;

Returns the stored value of a declared parameter. The wrapper asserts C success, rather than returning a Result. A C failure leaves the initialized fallback at zero if assertions are disabled. Do not use invalid enum values or a moved-from context. Duration parameters are in seconds; frame quantization affects the actual decisions.

`aic::VadContext::get_prediction_delay`

size_t get_prediction_delay() const;

Returns the prediction delay in samples at the initialized host rate. Query after successful initialization and again after changing audio configuration. This is not elapsed CPU time. The wrapper asserts C success and has a zero fallback if assertions are disabled.

`aic::VadContext::update_bearer_token`

ErrorCode update_bearer_token(const std::string& token) const;

Replaces local credentials using token.c_str(). Both the original and replacement credentials must use supported JWT form. Returns Success, LicenseFormatInvalid, other license errors or TokenUpdateUnsupported (and NullPointer for an invalid handle). Success does not prove backend acceptance. Run on a control thread. See authentication.

`aic::VadContext::is_speech_detected`

bool is_speech_detected() const;

Returns the latest filtered speech decision. Call Vad::process successfully to advance it. It combines probability threshold, minimum speech duration and hold behavior. The wrapper asserts C success and uses false as its assertion-disabled error fallback.

`aic::VadContext::get_raw_vad_probability`

float get_raw_vad_probability() const;

Returns the latest speech probability before duration filtering. It does not process audio or replace the final speech decision. The wrapper asserts C success and uses zero as its assertion-disabled error fallback.

`aic::EnergyVadContext`

Owns one native handle to an enhancement processor’s energy VAD, which detects speech from the enhanced signal before output mixing and runs no separate model. Detection advances with Processor::process; there is no separate process call. Create it with aic::Processor::create_energy_vad_context; the default and raw-handle constructors are private. All contexts from one processor share state and parameters, and a context may safely outlive its processor, after which its prediction stops updating. Control and query methods are thread-safe and real-time safe. Destruction is not real-time safe and must not overlap calls on the same handle; it releases the handle without destroying the processor or disabling its energy VAD.

Member	Contract
`~EnergyVadContext()`	Releases the native handle if non-null. Deallocates memory; not real-time safe.
`EnergyVadContext(EnergyVadContext&& other) noexcept`	Transfers the handle and clears the source. Do not call methods on the moved-from object.
`EnergyVadContext& operator=(EnergyVadContext&& other) noexcept`	Releases the destination’s old handle, transfers ownership and clears the source. Self-move is guarded; returns `*this`.
`EnergyVadContext(const EnergyVadContext&) = delete`	Copy construction is unavailable.
`EnergyVadContext& operator=(const EnergyVadContext&) = delete`	Copy assignment is unavailable.

`aic::EnergyVadContext::reset`

ErrorCode reset() const;

Clears the energy VAD state and immediately resets the prediction to false. Call it when seeking or when the stream is interrupted. Parameters are retained and the backing processor is not reset; ProcessorContext::reset also resets this VAD. Returns Success or an error code. Thread-safe and real-time safe.

`aic::EnergyVadContext::is_speech_detected`

bool is_speech_detected() const;

Returns the energy VAD’s prediction, false before processing or after a reset. Predictions update during Processor::process and stop updating if the processor stops processing or is destroyed. The prediction lags its input by get_prediction_delay() samples; speech hold and minimum speech duration affect its timing further.

`aic::EnergyVadContext::get_prediction_delay`

size_t get_prediction_delay() const;

Returns the prediction delay in samples for the current audio configuration, covering input reblocking, STFT and enhancement model processing. It equals ProcessorContext::get_audio_delay for the backing processor; energy detection adds no audio delay. Speech hold and minimum speech duration are not included.

`aic::EnergyVadContext::set_parameter`

ErrorCode set_parameter(VadParameter parameter, float value) const;

Sets a declared VadParameter to value. VadParameter::Sensitivity takes the energy range, 1.0 to 15.0, on this context. Returns Success, NullPointer or ParameterOutOfRange. All parameters can be changed during processing, from any thread.

`aic::EnergyVadContext::get_parameter`

float get_parameter(VadParameter parameter) const;

Returns the stored value of a declared parameter. Thread-safe and real-time safe.

`aic::VadParameter`

Use only these enum class members, whose underlying type is int.

Member	Value	Range, units and default
`VadParameter::SpeechHoldDuration`	0	Seconds, zero through the model/window-dependent maximum. Model-specific default; holds speech through short gaps. Decisions are quantized to model frames.
`VadParameter::Sensitivity`	1	Meaning depends on the detector. On a `VadContext`, a probability threshold, 0–1 inclusive, where a higher value requires stronger speech evidence. On an `EnergyVadContext`, the energy threshold of the enhanced signal, computed as `10 ^ (-sensitivity)` over 1–15 inclusive, where higher values detect quieter speech. Model-specific default.
`VadParameter::MinimumSpeechDuration`	2	Seconds, 0–1 inclusive. Model-specific default. Requires sustained speech before the decision becomes true.

C++ API index · Streams and state · Audio format

Example: read the decision after processing

Use a valid initialized VAD and its context. The decision getter relies on that valid context.

#include "aic.hpp"

aic::ErrorCode detect_block(aic::Vad& vad, const aic::VadContext& context,
                            const float* audio, size_t count, bool& speech) {
    auto error = vad.process(audio, count);
    if (error != aic::ErrorCode::Success) return error;
    speech = context.is_speech_detected();
    return aic::ErrorCode::Success;
}

SDK

API reference

Upgrades

LiveKit

AI tools

Historical migrations

`aic::Vad`

`aic::Vad::create`

`aic::Vad::initialize`

`aic::Vad::process`

`aic::Vad::terminate_session`

`aic::Vad::create_context`

`aic::VadContext`

`aic::VadContext::reset`

`aic::VadContext::set_parameter`

`aic::VadContext::get_parameter`

`aic::VadContext::get_prediction_delay`

`aic::VadContext::update_bearer_token`

`aic::VadContext::is_speech_detected`

`aic::VadContext::get_raw_vad_probability`

`aic::EnergyVadContext`

`aic::EnergyVadContext::reset`

`aic::EnergyVadContext::is_speech_detected`

`aic::EnergyVadContext::get_prediction_delay`

`aic::EnergyVadContext::set_parameter`

`aic::EnergyVadContext::get_parameter`

`aic::VadParameter`

Example: read the decision after processing

​aic::Vad

​aic::Vad::create

​aic::Vad::initialize

​aic::Vad::process

​aic::Vad::terminate_session

​aic::Vad::create_context

​aic::VadContext

​aic::VadContext::reset

​aic::VadContext::set_parameter

​aic::VadContext::get_parameter

​aic::VadContext::get_prediction_delay

​aic::VadContext::update_bearer_token

​aic::VadContext::is_speech_detected

​aic::VadContext::get_raw_vad_probability

​aic::EnergyVadContext

​aic::EnergyVadContext::reset

​aic::EnergyVadContext::is_speech_detected

​aic::EnergyVadContext::get_prediction_delay

​aic::EnergyVadContext::set_parameter

​aic::EnergyVadContext::get_parameter

​aic::VadParameter

​Related

​Example: read the decision after processing

`aic::Vad`

`aic::Vad::create`

`aic::Vad::initialize`

`aic::Vad::process`

`aic::Vad::terminate_session`

`aic::Vad::create_context`

`aic::VadContext`

`aic::VadContext::reset`

`aic::VadContext::set_parameter`

`aic::VadContext::get_parameter`

`aic::VadContext::get_prediction_delay`

`aic::VadContext::update_bearer_token`

`aic::VadContext::is_speech_detected`

`aic::VadContext::get_raw_vad_probability`

`aic::EnergyVadContext`

`aic::EnergyVadContext::reset`

`aic::EnergyVadContext::is_speech_detected`

`aic::EnergyVadContext::get_prediction_delay`

`aic::EnergyVadContext::set_parameter`

`aic::EnergyVadContext::get_parameter`

`aic::VadParameter`

Related

Example: read the decision after processing