C voice activity detection

All functions on this page are from C SDK 0.25.0, core 0.25.0. Include aic.h and link the matching native library. Start with the C integration guide. The pointer and error contract applies to every signature below. Error names in prose omit the AIC_ERROR_CODE_ prefix. There are no default C arguments; optional pointers are stated explicitly.

AicVadParameter

All defaults are model-specific. Read the current values through aic_vad_context_get_parameter or aic_energy_vad_context_get_parameter after creation.

Constant	Value	Units and constraints
`AIC_VAD_PARAMETER_SPEECH_HOLD_DURATION`	0	Seconds, from zero to the model/window-dependent maximum. Holds the speech decision through short gaps; internal decisions are quantized to model frames.
`AIC_VAD_PARAMETER_SENSITIVITY`	1	Meaning depends on the detector. On a dedicated VAD model, a probability threshold, 0–1 inclusive, where a higher threshold requires stronger evidence of speech. On an energy VAD (`AicEnergyVadContext`), the energy threshold of the enhanced signal, computed as `10 ^ (-sensitivity)` over 1–15 inclusive, where higher values detect quieter speech.
`AIC_VAD_PARAMETER_MINIMUM_SPEECH_DURATION`	2	Seconds, 0–1 inclusive. Requires sustained speech before the decision becomes true.

Use a dedicated ai-coustics VAD model and mono float32 audio. An enhancement model is not accepted by aic_vad_create; to detect speech with an enhancement model, create an energy VAD handle with aic_energy_vad_context_create instead.

aic_vad_create

enum AicErrorCode aic_vad_create(struct AicVad **vad,
                                 const struct AicModel *model,
                                 const char *license_key,
                                 const struct AicOtelConfig *otel_config);

vad is a writable output slot. model must be a VAD model; license_key is a null-terminated SDK key or supported bearer token. otel_config may be NULL to use environment defaults, or point to AicOtelConfig. The function copies configuration strings and retains model data internally. On success, destroy the owned VAD handle separately. Errors include NULL_POINTER, MODEL_TYPE_UNSUPPORTED, license errors and INTERNAL_ERROR. Construction allocates resources and may start session work; keep it outside an audio callback.

aic_vad_destroy

void aic_vad_destroy(struct AicVad *vad);

Releases vad and its model reference and ends its associated session. NULL is a no-op. Stop processing and other calls that use this handle first. Context handles are independent and must be destroyed separately. Teardown can block; keep it outside an audio callback. No return value.

aic_vad_initialize

enum AicErrorCode aic_vad_initialize(struct AicVad *vad,
                                     uint32_t sample_rate,
                                     size_t block_size,
                                     bool variable_block_size);

Configures vad for sample_rate in Hz (8,000–192,000 inclusive), a positive block_size in mono samples and variable_block_size. With false, every call must supply exactly block_size; with true, that value is the maximum per call. Reinitialization resets processing state. Returns SUCCESS, NULL_POINTER or AUDIO_CONFIG_UNSUPPORTED. A failed initialization leaves the object uninitialized; initialize successfully before processing again. Allocates internal buffers; do not call concurrently with processing.

aic_vad_process

enum AicErrorCode aic_vad_process(struct AicVad *vad,
                                  const float *audio_ptr,
                                  size_t audio_len);

audio_ptr points to audio_len readable contiguous mono float32 samples. The binding copies them to its internal buffer; the caller’s input is unchanged. Processing updates the context’s latest decision and probability. Returns SUCCESS, NULL_POINTER, NOT_INITIALIZED, AUDIO_CONFIG_MISMATCH or PROCESSING_NOT_ALLOWED (and internal failures). Read a fresh decision only after a successful call. Do not process the same object concurrently.

aic_vad_terminate_session

enum AicErrorCode aic_vad_terminate_session(struct AicVad *vad);

Requests termination of the session associated with vad. Returns SUCCESS after requesting it, or NULL_POINTER. Termination is handled asynchronously; a successful return does not prove remote acknowledgment or immediate processing denial. For credentials with no telemetry session, this is a no-op. It does not destroy the handle. Stop application processing explicitly and destroy the object when finished. 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_context_create

enum AicErrorCode aic_vad_context_create(struct AicVadContext **context, const struct AicVad *vad);

context is a writable output slot; vad is the source object. Returns a separately owned context with shared control state. It can outlive the source object, but no new audio is processed after the source is destroyed. Returns SUCCESS or NULL_POINTER (or INTERNAL_ERROR if the VAD context is unavailable). Allocate outside the callback and destroy the context separately.

aic_vad_context_destroy

void aic_vad_context_destroy(struct AicVadContext *context);

Releases context; NULL is a no-op. Stop users of this context handle first. This does not destroy the processing object. No return value.

aic_vad_context_reset

enum AicErrorCode aic_vad_context_reset(const struct AicVadContext *context);

Requests processing-state reset for the next call and immediately clears the published speech decision to false and raw probability to zero. Audio configuration and parameter values remain in place. context must be valid. Returns SUCCESS or NULL_POINTER. The shared control operation can run alongside processing; coordinate a stream boundary if you need a precise reset position.

aic_vad_context_set_parameter

enum AicErrorCode aic_vad_context_set_parameter(const struct AicVadContext *context,
                                                enum AicVadParameter parameter,
                                                float value);

Sets parameter to value through shared control state. Use only the declared AicVadParameter values and documented ranges. Returns SUCCESS, NULL_POINTER or PARAMETER_OUT_OF_RANGE; NaN is out of range. Updates may run alongside processing. No ownership transfer.

aic_vad_context_get_parameter

enum AicErrorCode aic_vad_context_get_parameter(const struct AicVadContext *context,
                                                enum AicVadParameter parameter,
                                                float *value);

Writes the current parameter value to the non-null writable value pointer. Use a declared enum value. Returns SUCCESS or NULL_POINTER. Shared control reads can run alongside processing. VAD duration values are stored in seconds; model-frame quantization affects decisions.

aic_vad_context_get_prediction_delay

enum AicErrorCode aic_vad_context_get_prediction_delay(const struct AicVadContext *context,
                                                       size_t *delay);

Writes the current prediction delay to delay, measured in samples at the initialized host rate. Query after successful initialization and again if you reinitialize. Both context and writable delay must be non-null. Returns SUCCESS or NULL_POINTER. This shared metadata read can run alongside processing; it is not elapsed CPU time.

aic_vad_context_update_bearer_token

enum AicErrorCode aic_vad_context_update_bearer_token(const struct AicVadContext *context,
                                                      const char *token);

Updates credentials through context using null-terminated UTF-8 token. Both the original credential and replacement must use the supported JWT form. Returns SUCCESS, NULL_POINTER, LICENSE_FORMAT_INVALID, other license errors or TOKEN_UPDATE_UNSUPPORTED. Success updates local credential state; it does not prove backend acceptance. This is a control-thread operation, not an audio-callback operation. See authentication.

aic_vad_context_is_speech_detected

enum AicErrorCode aic_vad_context_is_speech_detected(const struct AicVadContext *context,
                                                     bool *value);

Writes the latest filtered speech decision into the writable value pointer. Returns SUCCESS or NULL_POINTER. This does not process audio; call aic_vad_process first and check its result. It combines model probability, sensitivity, minimum speech duration and hold behavior. Safe to read alongside processing while the context remains alive.

aic_vad_context_get_raw_vad_probability

enum AicErrorCode aic_vad_context_get_raw_vad_probability(const struct AicVadContext *context,
                                                          float *value);

Writes the latest model speech probability into the writable value pointer. Returns SUCCESS or NULL_POINTER. This is the probability before duration filtering, not the final speech decision. It does not process audio. Safe to read alongside processing while the context remains alive.

aic_energy_vad_context_create

enum AicErrorCode aic_energy_vad_context_create(struct AicEnergyVadContext **context,
                                                const struct AicProcessor *processor);

context is a writable output slot; processor is an enhancement processor. Returns a separately owned handle to that processor’s energy VAD, which detects speech from the enhanced signal before output mixing and runs no separate model. Detection advances with aic_processor_process; there is no separate process call. Every handle from one processor refers to the same energy VAD. Creating a handle keeps enhancement inference active even when the processor is bypassed or its enhancement level is zero, and it stays active for the processor’s lifetime after all handles are destroyed. The handle can outlive the processor, but publishes no new predictions once the processor is destroyed. Returns SUCCESS, NULL_POINTER or MODEL_TYPE_UNSUPPORTED when the processor does not support energy VAD. Allocates memory; keep it outside an audio callback and do not use or destroy the processor from another thread during the call.

aic_energy_vad_context_destroy

void aic_energy_vad_context_destroy(struct AicEnergyVadContext *context);

Releases context; NULL is a no-op. This does not destroy the backing processor or disable its energy VAD; call aic_processor_destroy separately. Stop users of this handle first. Deallocates memory, so keep it outside an audio callback. No return value.

aic_energy_vad_context_reset

enum AicErrorCode aic_energy_vad_context_reset(const struct AicEnergyVadContext *context);

Clears the energy VAD state and the published speech decision. Use it when the stream is interrupted or when seeking. Parameter values are retained and the backing processor is not reset; aic_processor_context_reset also resets the energy VAD. context must be valid. Returns SUCCESS or NULL_POINTER. Real-time safe and callable from any thread.

aic_energy_vad_context_set_parameter

enum AicErrorCode aic_energy_vad_context_set_parameter(const struct AicEnergyVadContext *context,
                                                       enum AicVadParameter parameter,
                                                       float value);

Sets parameter to value. Use the declared AicVadParameter values; AIC_VAD_PARAMETER_SENSITIVITY takes the energy range, 1.0 to 15.0, on this handle. Returns SUCCESS, NULL_POINTER or PARAMETER_OUT_OF_RANGE. All parameters can be changed during processing, from any thread.

aic_energy_vad_context_get_parameter

enum AicErrorCode aic_energy_vad_context_get_parameter(const struct AicEnergyVadContext *context,
                                                       enum AicVadParameter parameter,
                                                       float *value);

Writes the current parameter value to the non-null writable value pointer. Use a declared enum value. Returns SUCCESS or NULL_POINTER. Real-time safe and callable from any thread.

aic_energy_vad_context_is_speech_detected

enum AicErrorCode aic_energy_vad_context_is_speech_detected(const struct AicEnergyVadContext *context,
                                                            bool *value);

Writes the energy VAD’s prediction into the writable value pointer. It is false before audio is processed and after a reset, and stops updating if the backing processor stops being processed. The decision lags its input by aic_energy_vad_context_get_prediction_delay samples; speech hold and minimum speech duration affect its timing further. Returns SUCCESS or NULL_POINTER. Real-time safe and callable from any thread.

aic_energy_vad_context_get_prediction_delay

enum AicErrorCode aic_energy_vad_context_get_prediction_delay(const struct AicEnergyVadContext *context,
                                                              size_t *delay);

Writes the prediction delay in samples to delay, covering input reblocking, STFT and enhancement model processing. It equals aic_processor_context_get_audio_delay for the backing processor; energy detection adds no audio delay. Speech hold and minimum speech duration affect decision timing and are not included. Before initialization the value uses the processor’s optimal block size at its native sample rate. After initialization it is expressed in samples at the rate given to aic_processor_initialize and includes input-buffering latency for the configured block size, which a nonoptimal or variable block size increases. Convert with delay_ms = (delay_samples * 1000) / sample_rate. Both pointers must be non-null. Returns SUCCESS or NULL_POINTER. Real-time safe and callable from any thread. C API index · C examples · Compatibility

Example: read a fresh decision

Use an initialized VAD and its context. The input is read-only; the decision is written only after successful processing.

#include "aic.h"

AicErrorCode detect_block(AicVad *vad, AicVadContext *context,
                          const float *audio, size_t count, bool *speech) {
    AicErrorCode error = aic_vad_process(vad, audio, count);
    if (error != AIC_ERROR_CODE_SUCCESS) return error;
    return aic_vad_context_is_speech_detected(context, speech);
}

SDK

API reference

Upgrades

LiveKit

AI tools

Historical migrations

AicVadParameter

aic_vad_create

aic_vad_destroy

aic_vad_initialize

aic_vad_process

aic_vad_terminate_session

aic_vad_context_create

aic_vad_context_destroy

aic_vad_context_reset

aic_vad_context_set_parameter

aic_vad_context_get_parameter

aic_vad_context_get_prediction_delay

aic_vad_context_update_bearer_token

aic_vad_context_is_speech_detected

aic_vad_context_get_raw_vad_probability

aic_energy_vad_context_create

aic_energy_vad_context_destroy

aic_energy_vad_context_reset

aic_energy_vad_context_set_parameter

aic_energy_vad_context_get_parameter

aic_energy_vad_context_is_speech_detected

aic_energy_vad_context_get_prediction_delay

Example: read a fresh decision

​AicVadParameter

​aic_vad_create

​aic_vad_destroy

​aic_vad_initialize

​aic_vad_process

​aic_vad_terminate_session

​aic_vad_context_create

​aic_vad_context_destroy

​aic_vad_context_reset

​aic_vad_context_set_parameter

​aic_vad_context_get_parameter

​aic_vad_context_get_prediction_delay

​aic_vad_context_update_bearer_token

​aic_vad_context_is_speech_detected

​aic_vad_context_get_raw_vad_probability

​aic_energy_vad_context_create

​aic_energy_vad_context_destroy

​aic_energy_vad_context_reset

​aic_energy_vad_context_set_parameter

​aic_energy_vad_context_get_parameter

​aic_energy_vad_context_is_speech_detected

​aic_energy_vad_context_get_prediction_delay

​Related

​Example: read a fresh decision

AicVadParameter

aic_vad_create

aic_vad_destroy

aic_vad_initialize

aic_vad_process

aic_vad_terminate_session

aic_vad_context_create

aic_vad_context_destroy

aic_vad_context_reset

aic_vad_context_set_parameter

aic_vad_context_get_parameter

aic_vad_context_get_prediction_delay

aic_vad_context_update_bearer_token

aic_vad_context_is_speech_detected

aic_vad_context_get_raw_vad_probability

aic_energy_vad_context_create

aic_energy_vad_context_destroy

aic_energy_vad_context_reset

aic_energy_vad_context_set_parameter

aic_energy_vad_context_get_parameter

aic_energy_vad_context_is_speech_detected

aic_energy_vad_context_get_prediction_delay

Related

Example: read a fresh decision