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

# AICQuailVADAnalyzer

> Standalone Quail VAD voice activity detection analyzer

## Overview

`AICQuailVADAnalyzer` is a standalone voice activity detection (VAD) analyzer powered by ai-coustics' Quail VAD models (Quail VAD 2.0, VF VAD 2.0). Unlike the deprecated `AICVADAnalyzer` which relies on `AICFilter`'s internal VAD, this analyzer owns its own dedicated processor and can be placed anywhere in the pipeline, working independently of audio enhancement.

The analyzer reports the model's continuous raw speech probability (range `0.0` to `1.0`), which is then gated by Pipecat's `VADParams` to determine speech start and stop events. This means speech detection thresholds and timing are controlled by your `VADParams` configuration (`confidence`, `start_secs`, `stop_secs`) rather than by the SDK's internal post-processing.

To use AIC, you need a license key. Get started at [ai-coustics.com](https://docs.ai-coustics.com/tutorials/pipecat-quickstart).

## Installation

The AIC Quail VAD analyzer requires additional dependencies:

```bash theme={null}
uv add "pipecat-ai[aic]"
```

## Constructor Parameters

<ParamField path="license_key" type="str" required>
  ai-coustics SDK license key for authentication. Get your key at
  [developers.ai-coustics.io](https://developers.ai-coustics.io).
</ParamField>

<ParamField path="model_id" type="str | None" default="&#x22;quail-vad-2.0-xxs-16khz&#x22;">
  Quail VAD model identifier. Defaults to the published standalone VAD model
  `"quail-vad-2.0-xxs-16khz"`. See
  [artifacts.ai-coustics.io](https://artifacts.ai-coustics.io/) for the
  catalogue. Ignored if `model_path` is provided.
</ParamField>

<ParamField path="model_path" type="Path | None" default="None">
  Optional path to a local `.aicmodel` file. Overrides `model_id` when set.
  Useful for offline deployments or custom models.
</ParamField>

<ParamField path="model_download_dir" type="Path | None" default="None">
  Directory for downloaded models. Defaults to `~/.cache/pipecat/aic-models`.
</ParamField>

<ParamField path="speech_hold_duration" type="float | None" default="None" deprecated>
  **Deprecated since 1.5.0. Will be removed in 2.0.0.**

  This parameter is ignored. Speech timing is now governed by `VADParams` (`start_secs`/`stop_secs`). Use those parameters instead.
</ParamField>

<ParamField path="minimum_speech_duration" type="float | None" default="None" deprecated>
  **Deprecated since 1.5.0. Will be removed in 2.0.0.**

  This parameter is ignored. Speech timing is now governed by `VADParams` (`start_secs`/`stop_secs`). Use those parameters instead.
</ParamField>

<ParamField path="sensitivity" type="float | None" default="None" deprecated>
  **Deprecated since 1.5.0. Will be removed in 2.0.0.**

  This parameter is ignored. The speech-probability threshold is now governed by `VADParams.confidence`. Use that parameter instead.
</ParamField>

<ParamField path="sample_rate" type="int | None" default="None">
  Initial sample rate; the pipeline will set this via `set_sample_rate` once the
  transport rate is known.
</ParamField>

<ParamField path="params" type="VADParams | None" default="None">
  Optional `VADParams` for the base VAD state machine configuration.
</ParamField>

## Usage Examples

### Basic Usage

The recommended approach for AIC-powered voice detection:

```python theme={null}
import os
from pipecat.audio.filters.aic_filter import AICFilter
from pipecat.audio.vad.aic_quail_vad import AICQuailVADAnalyzer
from pipecat.processors.aggregators.llm_response_universal import (
    LLMContextAggregatorPair,
    LLMUserAggregatorParams,
)
from pipecat.transports.services.daily import DailyTransport, DailyParams

# Create the AIC filter for audio enhancement
aic_filter = AICFilter(
    license_key=os.environ["AIC_SDK_LICENSE"],
    model_id="quail-vf-2.0-l-16khz",
)

# Create standalone Quail VAD 2.0 analyzer
aic_vad = AICQuailVADAnalyzer(
    license_key=os.environ["AIC_SDK_LICENSE"],
)

transport = DailyTransport(
    room_url,
    token,
    "Bot",
    DailyParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        audio_in_filter=aic_filter,
    ),
)

user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
    context,
    user_params=LLMUserAggregatorParams(
        vad_analyzer=aic_vad,
    ),
)
```

### With Custom VAD Parameters

Fine-tune the VAD behavior using `VADParams`:

```python theme={null}
from pipecat.audio.vad.aic_quail_vad import AICQuailVADAnalyzer
from pipecat.audio.vad.vad_analyzer import VADParams

aic_vad = AICQuailVADAnalyzer(
    license_key=os.environ["AIC_SDK_LICENSE"],
    params=VADParams(
        confidence=0.7,      # Speech probability threshold (0.0-1.0)
        start_secs=0.1,     # Seconds of speech before triggering
        stop_secs=0.5,      # Seconds of silence before stopping
    ),
)
```

### VAD-Only (Without Enhancement)

Use Quail VAD without audio enhancement:

```python theme={null}
from pipecat.audio.vad.aic_quail_vad import AICQuailVADAnalyzer
from pipecat.processors.aggregators.llm_response_universal import (
    LLMContextAggregatorPair,
    LLMUserAggregatorParams,
)
from pipecat.transports.services.daily import DailyTransport, DailyParams

# Just VAD, no enhancement filter
aic_vad = AICQuailVADAnalyzer(
    license_key=os.environ["AIC_SDK_LICENSE"],
)

transport = DailyTransport(
    room_url,
    token,
    "Bot",
    DailyParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        # No audio_in_filter - raw audio goes directly to VAD
    ),
)

user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
    context,
    user_params=LLMUserAggregatorParams(
        vad_analyzer=aic_vad,
    ),
)
```

### Using a Local Model

For offline deployments or custom Quail VAD models:

```python theme={null}
from pathlib import Path
from pipecat.audio.vad.aic_quail_vad import AICQuailVADAnalyzer

aic_vad = AICQuailVADAnalyzer(
    license_key=os.environ["AIC_SDK_LICENSE"],
    model_path=Path("/path/to/your/quail-vad-model.aicmodel"),
)
```

<Info>
  See the [AIC Quail VAD
  example](https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-aicoustics-vad-only.py)
  for a complete working example with detailed logging.
</Info>

## Comparison to Deprecated AICVADAnalyzer

| Feature              | AICQuailVADAnalyzer (Recommended)                                    | AICVADAnalyzer (Deprecated)             |
| -------------------- | -------------------------------------------------------------------- | --------------------------------------- |
| **Model**            | Standalone Quail VAD models (Quail VAD 2.0, VF VAD 2.0)              | Enhancement model's internal VAD        |
| **Independence**     | Owns its own processor                                               | Bound to `AICFilter` instance           |
| **Audio path**       | Processes whatever the pipeline feeds it                             | Reads post-enhancement VAD state        |
| **Output**           | Continuous raw probability gated by Pipecat's `VADParams.confidence` | Binary speech flag (0.0/1.0)            |
| **Configuration**    | Controlled by `VADParams` (`confidence`, `start_secs`, `stop_secs`)  | Energy threshold (1.0-15.0)             |
| **Placement**        | Can be placed anywhere in pipeline                                   | Must follow `AICFilter`                 |
| **Use case**         | Noise-robust VAD as primary differentiator                           | Legacy coupling to enhancement pipeline |
| **Removal timeline** | N/A (current recommended approach)                                   | Will be removed in Pipecat 1.6.0        |

The Quail VAD analyzer can work with or without the AIC enhancement filter, providing flexibility in your pipeline architecture.

## Notes

* Requires ai-coustics license key (get one at [developers.ai-coustics.io](https://developers.ai-coustics.io))
* **Environment variable**: Use `AIC_SDK_LICENSE` for authentication
* Default model is `quail-vad-2.0-xxs-16khz`, optimized for 16kHz audio
* Model is downloaded and cached on first use
* Works independently of `AICFilter` - can be used with or without audio enhancement
* Provides noise-robust speech detection in challenging acoustic environments
* Handles PCM\_16 audio format (int16 samples)
* Thread-safe for pipeline processing
* For available models, visit [artifacts.ai-coustics.io](https://artifacts.ai-coustics.io/)

<Warning>
  **Behavior change in Pipecat 1.5.0**: The analyzer now reports the model's
  continuous raw VAD probability instead of a binary speech flag. This means
  `VADParams.confidence` now governs the speech threshold (previously had no
  effect due to the binary output). Existing users should review their
  `VADParams.confidence` setting after upgrading.
</Warning>