aic_quail_vad

Standalone Quail VAD analyzer for Pipecat.

Runs a standalone Quail VAD-only model from the ai-coustics SDK (e.g. Quail VAD 2.0 or VF VAD 2.0) as a dedicated VAD processor. Unlike pipecat.audio.vad.aic_vad.AICVADAnalyzer, which queries the model-internal VAD of pipecat.audio.filters.aic_filter.AICFilter, this analyzer owns its own aic_sdk.Processor instance and can be placed anywhere in the pipeline.

Classes:

AICQuailVADAnalyzer: Standalone Quail VAD analyzer.

class pipecat.audio.vad.aic_quail_vad.AICQuailVADAnalyzer(*, license_key: str, model_id: str | None = 'quail-vad-2.0-xxs-16khz', model_path: Path | None = None, model_download_dir: Path | None = None, speech_hold_duration: float | None = None, minimum_speech_duration: float | None = None, sensitivity: float | None = None, sample_rate: int | None = None, params: VADParams | None = None)[source]

Bases: VADAnalyzer

Standalone Quail VAD analyzer powered by the ai-coustics SDK.

The analyzer owns a dedicated aic_sdk.Processor initialized with a Quail VAD-only model. Each voice_confidence() call processes one audio window through the processor and returns the model’s raw speech probability in [0.0, 1.0] (aic_sdk.VadContext.raw_vad_probability()). The base VADAnalyzer state machine then gates speech start/stop using its own VADParams (confidence threshold, start_secs, stop_secs), so the SDK’s own VAD post-processing (sensitivity thresholding, speech-hold) is intentionally bypassed — Pipecat owns the thresholding.

Comparison to pipecat.audio.vad.aic_vad.AICVADAnalyzer (deprecated):

  • Model: Quail VAD-only model (e.g. quail-vad-2.0-xxs-16khz); the deprecated analyzer uses the enhancement model’s internal VAD as a side-channel.

  • Audio path: runs on whatever the pipeline feeds it (raw or enhanced). The deprecated analyzer reads post-enhancement VAD state from AICFilter’s processor.

  • Confidence: a continuous raw probability gated by Pipecat’s VADParams.confidence. The deprecated analyzer exposes only a boolean gated by the enhancement model’s energy threshold ([1.0, 15.0]).

  • Coupling: independent — owns its own Processor. The deprecated analyzer is bound to an AICFilter instance.

Example:

analyzer = AICQuailVADAnalyzer(license_key=os.environ["AIC_SDK_LICENSE"])
# ``set_sample_rate`` is invoked by the pipeline once the transport
# sample rate is known.
__init__(*, license_key: str, model_id: str | None = 'quail-vad-2.0-xxs-16khz', model_path: Path | None = None, model_download_dir: Path | None = None, speech_hold_duration: float | None = None, minimum_speech_duration: float | None = None, sensitivity: float | None = None, sample_rate: int | None = None, params: VADParams | None = None) → None[source]

Initialize the Quail VAD analyzer.

Loads the model eagerly so the cold-start CDN download happens at construction time (typically before the event loop starts), rather than on the first set_sample_rate() call from a running pipeline.

Parameters:

  • license_key – ai-coustics SDK license key.

  • model_id – Quail VAD model identifier. Defaults to the published standalone VAD model "quail-vad-2.0-xxs-16khz". See https://artifacts.ai-coustics.io/ for the catalogue. Ignored if model_path is provided.

  • model_path – Optional path to a local .aicmodel file. Overrides model_id when set.

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

  • speech_hold_duration –

    Deprecated; no longer used. Speech timing is governed by Pipecat’s VADParams.

    Deprecated since version 1.5.0: Use VADParams (start_secs/stop_secs) instead. speech_hold_duration is ignored and will be removed in 2.0.0.

  • minimum_speech_duration –

    Deprecated; no longer used. Speech timing is governed by Pipecat’s VADParams.

    Deprecated since version 1.5.0: Use VADParams (start_secs/stop_secs) instead. minimum_speech_duration is ignored and will be removed in 2.0.0.

  • sensitivity –

    Deprecated; no longer used. The speech-probability threshold is now governed by Pipecat’s VADParams.confidence.

    Deprecated since version 1.5.0: Use VADParams (confidence) instead. sensitivity is ignored and will be removed in 2.0.0.

  • sample_rate – Initial sample rate; the pipeline will set this via set_sample_rate() once the transport rate is known.

  • params – Optional VADParams for the base state machine.

Raises:

ValueError – If neither model_id nor model_path is provided.

set_sample_rate(sample_rate: int) → None[source]

Set the sample rate. Recreates the SDK processor if the rate changed.

Initializes the processor before delegating to the base class so the base’s internal sizing uses the correct num_frames_required() (driven by the model’s optimal frame count) instead of the pre-init fallback. If processor initialization fails, the previous processor/state is restored so the analyzer stays usable at its old sample rate rather than half-initialized.

Parameters:

sample_rate – Audio sample rate in Hz.

num_frames_required() → int[source]

Return the number of int16 frames per analysis window.

voice_confidence(buffer: bytes) → float[source]

Run the Quail VAD model on one audio window.

Parameters:

buffer – int16 little-endian audio samples for one window of num_frames_required() samples.

Returns:

The model’s raw speech probability in [0.0, 1.0]. The base VADAnalyzer compares this against VADParams.confidence to decide speech. Returns 0.0 if the processor is not yet initialized (i.e. set_sample_rate() has not run), if the buffer size does not match the expected window, or if an SDK inference error occurs.

async cleanup() → None[source]

Release the dedicated Processor and Model handles.

Concurrency contract: callers must ensure no voice_confidence() call is in flight when cleanup runs. The pipeline always orders cleanup after the source-stream stop, so in normal pipeline use this is guaranteed. If you invoke cleanup from outside that ordering, drain or cancel any in-flight analyze_audio() work first.