AIC Quail VAD

AICQuailVADAnalyzer is a standalone voice activity detection (VAD) analyzer powered by ai-coustics Quail.

Overview

AICQuailVADAnalyzer is a standalone voice activity detection (VAD) analyzer powered by ai-coustics’ dedicated VAD models. Unlike the deprecated AICVADAnalyzer which relied on AICFilter’s internal VAD, this analyzer owns its own dedicated VAD instance 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.

Installation

The AIC Quail VAD analyzer requires additional dependencies:

uv add "pipecat-ai[aic]"

Constructor Parameters

license_key · str · required

ai-coustics SDK license key for authentication. Get your key at developers.ai-coustics.io.

model_id · str | None · default: "\"vad-2.1-xxs-16khz\""

Dedicated VAD model identifier. Defaults to "vad-2.1-xxs-16khz". See artifacts.ai-coustics.io for the catalogue. Ignored if model_path is provided. Enhancement models are rejected by the SDK.

model_path · Path | None · default: "None"

Optional path to a local .aicmodel file. Overrides model_id when set. Useful for offline deployments or custom models.

model_download_dir · Path | None · default: "None"

Directory for downloaded models. Defaults to ~/.cache/pipecat/aic-models.

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

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

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

sample_rate · int | None · default: "None"

Initial sample rate; the pipeline will set this via set_sample_rate once the transport rate is known.

params · VADParams | None · default: "None"

Optional VADParams for the base VAD state machine configuration.

Usage Examples

Basic Usage

The recommended approach for AIC-powered voice detection:

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:

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:

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:

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"),
)

See the AIC Quail VAD example for a complete working example with detailed logging.

Comparison to Deprecated AICVADAnalyzer

Feature	AICQuailVADAnalyzer (Recommended)	AICVADAnalyzer (Deprecated, Removed)
Model	Dedicated VAD models (e.g., vad-2.1-xxs-16khz)	Enhancement model’s internal VAD
Independence	Owns its own VAD instance	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)	Removed in Pipecat 1.6.0

The 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)
• Environment variable: Use AIC_SDK_LICENSE for authentication
• aic-sdk 3.x required: Version 3.1.0+ is included in pipecat-ai[aic]
• Default model is vad-2.1-xxs-16khz, optimized for 16kHz audio
• Model compatibility: The old default quail-vad-2.0-xxs-16khz does not work with aic-sdk 3.0; use models from artifacts.ai-coustics.io
• 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
• The analyzer closes its ai-coustics session when the pipeline stops

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.