> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai-coustics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# C++ voice activity detection

> Create a dedicated VAD object and manage its stream state.

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](/reference/sdk/language-bindings/cpp).

All names below are in namespace `aic`. Check [Result and error handling](/reference/sdk/api/cpp/results-and-errors) before extracting a factory result. Ordinary C++ allocation or string operations can still throw; SDK status failures use the declared return values.

<span id="aic-Vad" />

## `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.

<span id="aic-Vad-destructor-Vad" />

<span id="aic-Vad-Vad-move" />

<span id="aic-Vad-operatorassign-move" />

<span id="aic-Vad-Vad-copy" />

<span id="aic-Vad-operatorassign-copy" />

| 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. |

<span id="aic-Vad-create" />

### `aic::Vad::create`

```cpp theme={null}
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.

<span id="aic-Vad-initialize" />

### `aic::Vad::initialize`

```cpp theme={null}
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.

<span id="aic-Vad-process" />

### `aic::Vad::process`

```cpp theme={null}
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.

<span id="aic-Vad-terminate_session" />

### `aic::Vad::terminate_session`

```cpp theme={null}
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.

<span id="aic-Vad-create_context" />

### `aic::Vad::create_context`

```cpp theme={null}
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.

<span id="aic-VadContext" />

## `aic::VadContext`

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.

<span id="aic-VadContext-destructor-VadContext" />

<span id="aic-VadContext-VadContext-move" />

<span id="aic-VadContext-operatorassign-move" />

<span id="aic-VadContext-VadContext-copy" />

<span id="aic-VadContext-operatorassign-copy" />

| 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.

<span id="aic-VadContext-reset" />

### `aic::VadContext::reset`

```cpp theme={null}
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.

<span id="aic-VadContext-set_parameter" />

### `aic::VadContext::set_parameter`

```cpp theme={null}
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.

<span id="aic-VadContext-get_parameter" />

### `aic::VadContext::get_parameter`

```cpp theme={null}
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.

<span id="aic-VadContext-get_prediction_delay" />

### `aic::VadContext::get_prediction_delay`

```cpp theme={null}
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.

<span id="aic-VadContext-update_bearer_token" />

### `aic::VadContext::update_bearer_token`

```cpp theme={null}
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](/models/get-started/authenticate-apps).

<span id="aic-VadContext-is_speech_detected" />

### `aic::VadContext::is_speech_detected`

```cpp theme={null}
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.

<span id="aic-VadContext-get_raw_vad_probability" />

### `aic::VadContext::get_raw_vad_probability`

```cpp theme={null}
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.

<span id="aic-EnergyVadContext" />

## `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`](/reference/sdk/api/cpp/processing#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.

<span id="aic-EnergyVadContext-destructor-EnergyVadContext" />

<span id="aic-EnergyVadContext-EnergyVadContext-move" />

<span id="aic-EnergyVadContext-operatorassign-move" />

<span id="aic-EnergyVadContext-EnergyVadContext-copy" />

<span id="aic-EnergyVadContext-operatorassign-copy" />

| 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. |

<span id="aic-EnergyVadContext-reset" />

### `aic::EnergyVadContext::reset`

```cpp theme={null}
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`](/reference/sdk/api/cpp/processing#aic-ProcessorContext-reset) also resets this VAD. Returns `Success` or an error code. Thread-safe and real-time safe.

<span id="aic-EnergyVadContext-is_speech_detected" />

### `aic::EnergyVadContext::is_speech_detected`

```cpp theme={null}
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.

<span id="aic-EnergyVadContext-get_prediction_delay" />

### `aic::EnergyVadContext::get_prediction_delay`

```cpp theme={null}
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`](/reference/sdk/api/cpp/processing#aic-ProcessorContext-get_audio_delay) for the backing processor; energy detection adds no audio delay. Speech hold and minimum speech duration are not included.

<span id="aic-EnergyVadContext-set_parameter" />

### `aic::EnergyVadContext::set_parameter`

```cpp theme={null}
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.

<span id="aic-EnergyVadContext-get_parameter" />

### `aic::EnergyVadContext::get_parameter`

```cpp theme={null}
float get_parameter(VadParameter parameter) const;
```

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

<span id="aic-VadParameter" />

## `aic::VadParameter`

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

<span id="aic-VadParameter-SpeechHoldDuration" />

<span id="aic-VadParameter-Sensitivity" />

<span id="aic-VadParameter-MinimumSpeechDuration" />

| 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. |

## Related

[C++ API index](/reference/sdk/api/cpp/index) · [Streams and state](/reference/concepts/streams-and-state) · [Audio format](/reference/concepts/audio-format)

## Example: read the decision after processing

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

```cpp theme={null}
#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;
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.