> ## 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.
# Python voice activity detection
> Python reference for Vad, VadAsync, VadContext and VadParameter in aic-sdk 3.2.0.
**Package:** `aic-sdk==3.2.0`. **Core SDK:** `0.24.0`. Source: [Python wrapper 3.2.0](https://github.com/ai-coustics/aic-sdk-py/tree/cca6f30d448c8e97bf7cfb13d6528a63de8f2c39).
The fragments below use these imports. Supply `license_key` from your approved secret source and use the loaded model and initialized objects described in each section. For a complete file-processing example and tuning guidance, follow the [ai-coustics VAD guide](/models/voice-activity-detection/vad#how-it-works).
```python theme={null}
import typing
import numpy as np
import numpy.typing as npt
from aic_sdk import Model, Processor, ProcessorAsync, ProcessorConfig, Vad, VadAsync, VadContext, VadParameter, OtelConfig
```
`audio` denotes a one-dimensional NumPy `float32` array. Async fragments run inside an async function.
## Vad
class
Stateful voice activity detector (VAD) backed by a dedicated VAD model. Use one instance per independent stream and serialize initialization and processing on each instance. Native resources are released when Python releases the object.
Feed mono audio to [`process()`](/reference/sdk/api/python/vad#vad-process) and read predictions through [`get_context()`](/reference/sdk/api/python/vad#vad-get_context). The audio is not modified; processing only updates the detector's prediction.
When enhancement and VAD run together, feed the VAD the original input audio, not the enhanced output of [`Processor.process()`](/reference/sdk/api/python/enhancement#processor-process). Run both on the same block instead of chaining them:
```python theme={null}
vad.process(audio) # reads the block, does not modify it
enhanced = processor.process(audio) # enhances the same original block
```
**Example**
```python theme={null}
model = Model.from_file("/path/to/vad_model.aicmodel")
config = ProcessorConfig.optimal(model)
vad = Vad(model, license_key, config)
vad_context = vad.get_context()
audio = np.zeros(config.block_size, dtype=np.float32)
vad.process(audio)
print(vad_context.is_speech_detected())
```
### Vad() constructor
```python theme={null}
Vad(
model: Model,
license_key: str,
config: ProcessorConfig | None = None,
otel_config: OtelConfig | None = None,
) -> Vad
```
Creates a voice activity detector.
The model must be a dedicated VAD model, such as `vad-ms-2.1-xxs-16khz`. Enhancement models raise [`ModelTypeUnsupportedError`](/reference/sdk/api/python/errors#modeltypeunsupportederror).
If config is provided, the VAD is initialized immediately. Otherwise, call [`initialize()`](/reference/sdk/api/python/vad#vad-initialize) before processing audio.
**Parameters**
A loaded dedicated VAD model. See [`Model`](/reference/sdk/api/python/models-and-config#model).
SDK key or JWT for the ai-coustics SDK.
Optional audio configuration. See [`ProcessorConfig`](/reference/sdk/api/python/models-and-config#processorconfig).
Optional per-instance OpenTelemetry configuration. See [`OtelConfig`](/reference/sdk/api/python/models-and-config#otelconfig).
### Vad.initialize()
```python theme={null}
def initialize(self, config: ProcessorConfig) -> None
```
Configures the VAD for a sample rate and block size. Unsupported configurations raise `AudioConfigUnsupportedError`.
For the most frequent prediction updates, use [`ProcessorConfig.optimal(model)`](/reference/sdk/api/python/models-and-config#processorconfig-optimal).
**Parameters**
Audio configuration. See [`ProcessorConfig`](/reference/sdk/api/python/models-and-config#processorconfig).
This method allocates memory and is not real-time safe.
### Vad.process()
```python theme={null}
def process(self, audio: npt.NDArray[np.float32]) -> None
```
Accepts a one-dimensional NumPy `float32` array of normalized mono samples. Its length must equal `config.block_size`, or be 1 through `config.block_size` when variable blocks are enabled. Native work releases the GIL. A contiguous array is read directly; a strided view is copied. Do not mutate a shared input while the call runs. Wrong dtype or dimensionality raises `TypeError`.
Returns `None`: VAD processing does not modify the audio. Read the updated prediction through [`get_context()`](/reference/sdk/api/python/vad#vad-get_context).
When enhancement and VAD run together, pass the original input audio here, not the enhanced output of [`Processor.process()`](/reference/sdk/api/python/enhancement#processor-process).
**Raises**
* [`NotInitializedError`](/reference/sdk/api/python/errors#notinitializederror): If the VAD has not been initialized.
* [`AudioConfigMismatchError`](/reference/sdk/api/python/errors#audioconfigmismatcherror): If the block size does not match the configuration.
* [`ProcessingNotAllowedError`](/reference/sdk/api/python/errors#processingnotallowederror): If processing is not authorized.
### Vad.get\_context()
```python theme={null}
def get_context(self) -> VadContext
```
Returns a [`VadContext`](/reference/sdk/api/python/vad#vadcontext) for reading predictions and controlling the VAD.
### Vad.terminate\_session()
```python theme={null}
def terminate_session(self) -> None
```
Terminates the VAD's telemetry session.
Stop submitting audio and treat this session as closed once you request termination. Processing becomes disallowed when the native lifecycle task handles the signal. The call can return before that handling completes when other sessions remain alive; it is not proof of remote usage acknowledgment. The session is also stopped when the object is destroyed.
This method may block and is not real-time safe.
## VadAsync
class
Async voice activity detector backed by a dedicated VAD model.
Awaitable processing runs on the shared SDK processing pool. The constructor and `get_context()` are synchronous; both can block. Omit `config` at construction and await `initialize_async(config)` to initialize asynchronously. Await blocks in stream order and bound pending work. See [async enhancement](/reference/sdk/api/python/enhancement#processorasync) for pool settings and concurrency.
When enhancement and VAD run together, feed the VAD the original input audio, not the enhanced output of [`ProcessorAsync.process_async()`](/reference/sdk/api/python/enhancement#processorasync-process_async).
### VadAsync() constructor
```python theme={null}
VadAsync(
model: Model,
license_key: str,
config: ProcessorConfig | None = None,
otel_config: OtelConfig | None = None,
) -> VadAsync
```
Creates an async voice activity detector.
The model must be a dedicated VAD model, such as `vad-ms-2.1-xxs-16khz`. Enhancement models raise [`ModelTypeUnsupportedError`](/reference/sdk/api/python/errors#modeltypeunsupportederror).
**Parameters**
A loaded dedicated VAD model. See [`Model`](/reference/sdk/api/python/models-and-config#model).
SDK key or JWT for the ai-coustics SDK.
Optional audio configuration. See [`ProcessorConfig`](/reference/sdk/api/python/models-and-config#processorconfig).
Optional per-instance OpenTelemetry configuration. See [`OtelConfig`](/reference/sdk/api/python/models-and-config#otelconfig).
### VadAsync.initialize\_async()
async
```python theme={null}
def initialize_async(self, config: ProcessorConfig) -> typing.Awaitable[None]
```
Returns an awaitable resolving to `None` after initialization. Unsupported configurations raise `AudioConfigUnsupportedError` when awaited. The configuration is copied into the operation.
### VadAsync.process\_async()
async
```python theme={null}
def process_async(self, audio: npt.NDArray[np.float32]) -> typing.Awaitable[None]
```
Copies the one-dimensional NumPy `float32` input before dispatch, then updates the VAD prediction in the background. Await it to obtain `None`. Input remains unchanged; the length, dtype and SDK error rules of `Vad.process()` apply.
After awaiting, read the updated prediction through [`get_context()`](/reference/sdk/api/python/vad#vadasync-get_context).
When enhancement and VAD run together, pass the original input audio here, not the enhanced output of [`ProcessorAsync.process_async()`](/reference/sdk/api/python/enhancement#processorasync-process_async).
### VadAsync.get\_context()
```python theme={null}
def get_context(self) -> VadContext
```
Returns a [`VadContext`](/reference/sdk/api/python/vad#vadcontext) for reading predictions and controlling the VAD.
### VadAsync.terminate\_session\_async()
async
```python theme={null}
def terminate_session_async(self) -> typing.Awaitable[None]
```
Terminates the VAD's telemetry session asynchronously.
Await the returned awaitable and stop submitting audio. Treat the session as closed immediately; native processing becomes disallowed when the lifecycle task handles the signal. Other live sessions can allow termination handling to continue after the awaitable resolves. Await completion does not prove remote usage acknowledgment.
## VadContext
class
Shared control handle for a [`Vad`](/reference/sdk/api/python/vad#vad).
There is no public `VadContext()` constructor. Contexts created by the same Vad reference the same detector. They can be used from any thread while audio is being processed elsewhere.
### VadContext.is\_speech\_detected()
```python theme={null}
def is_speech_detected(self) -> bool
```
Returns the post-processed VAD prediction.
The prediction lags its input by [`get_prediction_delay()`](/reference/sdk/api/python/vad#vadcontext-get_prediction_delay) samples. If the backing Vad stops being processed, the prediction does not update.
### VadContext.raw\_vad\_probability()
```python theme={null}
def raw_vad_probability(self) -> float
```
Returns the VAD model's raw speech probability without SDK post-processing.
The prediction lags its input by [`get_prediction_delay()`](/reference/sdk/api/python/vad#vadcontext-get_prediction_delay) samples.
### VadContext.set\_parameter()
```python theme={null}
def set_parameter(self, parameter: VadParameter, value: float) -> None
```
Modifies a VAD parameter. Out-of-range values, including NaN, raise `ParameterOutOfRangeError`. Query `get_parameter()` for the value used by the current model.
**Parameters**
Parameter to modify. See [`VadParameter`](/reference/sdk/api/python/vad#vadparameter).
New parameter value.
### VadContext.get\_parameter()
```python theme={null}
def get_parameter(self, parameter: VadParameter) -> float
```
Retrieves the current value of a VAD parameter.
### VadContext.parameter()
deprecated
Deprecated. Use [`get_parameter()`](/reference/sdk/api/python/vad#vadcontext-get_parameter) instead.
```python theme={null}
def parameter(self, parameter: VadParameter) -> float
```
### VadContext.get\_prediction\_delay()
```python theme={null}
def get_prediction_delay(self) -> int
```
Returns the total VAD prediction delay in samples.
This includes input reblocking, model processing and buffering overhead for the current configuration. Use it to align speech decisions with the input timeline.
This delay is not applied to the audio: [`Vad.process()`](/reference/sdk/api/python/vad#vad-process) leaves its input untouched. The value only describes how far behind its input the published prediction is, and it is independent of [`ProcessorContext.get_audio_delay()`](/reference/sdk/api/python/enhancement#processorcontext-get_audio_delay).
### VadContext.reset()
```python theme={null}
def reset(self) -> None
```
Clears the VAD's internal state and published predictions.
The VAD remains initialized. Reset clears the published predictions immediately and requests internal processing state reset for the next block. Immediately after `reset()`, [`is_speech_detected()`](/reference/sdk/api/python/vad#vadcontext-is_speech_detected) is False and [`raw_vad_probability()`](/reference/sdk/api/python/vad#vadcontext-raw_vad_probability) is 0.0.
### VadContext.update\_bearer\_token()
```python theme={null}
def update_bearer_token(self, token: str) -> None
```
Replaces the bearer token on the running VAD.
Both the original key and new token must be JWTs. Otherwise `TokenUnsupportedError` is raised. Embedded NUL characters raise `LicenseFormatInvalidError`. A successful update is not proof of backend acceptance; continue handling processing errors.
## VadParameter
enum
Parameter constants for voice activity detection. Use named constants directly; the runtime exposes PyO3 enum-like objects rather than promising standard-library `enum.Enum` iteration or `.value` behavior.
### VadParameter members
#### VadParameter.SpeechHoldDuration
Controls how long the VAD continues to detect speech after the audio signal no longer contains speech.
This affects the stability of speech detected -> not detected transitions.
When the current probability is at or below the threshold, speech remains detected while at least half of the retained history was above threshold. The history spans approximately `speech_hold_duration * 2` seconds. When the current probability is above threshold, the consecutive-frame test uses `MinimumSpeechDuration`.
For example, a `speech_hold_duration` of 0.5 s sustains detection for 0.5 s after speech stops. Additional speech blocks during that period can extend detection until the 50% history threshold is no longer met.
Timing is rounded to the nearest model window: for a 10 ms window, to the nearest multiple of 10 ms. `get_parameter()` returns the stored requested value, not the effective transition timing.
**Range:** 0.0 to 300x model window length (seconds)
**Default:** model-specific
#### VadParameter.Sensitivity
Probability threshold used to decide whether speech is detected.
Dedicated VAD models output a speech probability for each processed audio block. A value above this threshold triggers a speech-detected decision.
**Range:** 0.0–1.0
**Default:** model-specific
#### VadParameter.MinimumSpeechDuration
Controls how long speech needs to be present in the audio signal before the VAD considers it speech.
This affects the stability of speech not detected -> detected transitions.
Timing is rounded to the nearest model window: for a 10 ms window, to the nearest multiple of 10 ms. `get_parameter()` returns the stored requested value, not the effective transition timing.
**Range:** 0.0–1.0 (seconds)
**Default:** model-specific
See the [Python API index](/reference/sdk/api/python/index), [Python guide](/reference/sdk/language-bindings/python) and [troubleshooting](/production/troubleshooting).