> ## 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.24.0**, core **0.24.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-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     | Probability threshold, 0–1 inclusive. Model-specific default. A higher value requires stronger speech evidence.                                             |
| `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;
}
```