AICFilter

Overview

AICFilter is an audio processor that enhances user speech by reducing background noise and improving speech clarity. It inherits from BaseAudioFilter and processes audio frames in real-time using ai-coustics’ speech enhancement technology. To use AIC, you need a license key. Get started at ai-coustics.com.

This documentation covers aic-sdk v2.x. If you’re using aic-sdk v1.x, please see the Migration Guide section below for upgrading instructions.

Installation

The AIC filter requires additional dependencies:

uv add "pipecat-ai[aic]"

Constructor Parameters

license_key

str

required

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

model_id

str | None

default:"None"

Model identifier to download from CDN. Required if model_path is not provided. See artifacts.ai-coustics.io for available models. See the documentation for more detailed information about the models.Examples: "quail-vf-2.0-l-16khz", "quail-vf-l-16khz", "quail-s-16khz", "quail-l-8khz"

model_path

str | None

default:"None"

Path to a local .aicmodel file. If provided, model_id is ignored and no download occurs. Useful for offline deployments or custom models.

model_download_dir

Path | None

default:"None"

Directory for downloading and caching models. Defaults to a cache directory in the user’s home folder.

enhancement_level

float | None

default:"None"

Overall enhancement strength from 0.0 (no enhancement) to 1.0 (maximum enhancement). If None, the model’s default behavior is used. This parameter allows you to control the intensity of the speech enhancement applied by the model.

Methods

create_vad_analyzer

Deprecated in 1.4.0: This method will be removed in Pipecat 1.6.0. Use AICQuailVADAnalyzer instead, which provides a standalone Quail VAD 2.0 model that works independently of the enhancement filter.

Creates an AICVADAnalyzer that uses the AIC model’s built-in voice activity detection.

def create_vad_analyzer(
    *,
    speech_hold_duration: float | None = None,
    minimum_speech_duration: float | None = None,
    sensitivity: float | None = None,
) -> AICVADAnalyzer

VAD Parameters

speech_hold_duration

float | None

default:"None"

Controls for how long the VAD continues to detect speech after the audio signal no longer contains speech (in seconds). Range: 0.0 to 100x model window length, Default (in SDK): 0.05s

minimum_speech_duration

float | None

default:"None"

Controls for how long speech needs to be present in the audio signal before the VAD considers it speech (in seconds). Range: 0.0 to 1.0, Default (in SDK): 0.0s

sensitivity

float | None

default:"None"

Controls the sensitivity (energy threshold) of the VAD. This value is used by the VAD as the threshold a speech audio signal’s energy has to exceed in order to be considered speech. Formula: Energy threshold = 10 ** (-sensitivity) Range: 1.0 to 15.0, Default (in SDK): 6.0

get_vad_context

Returns the VAD context once the processor is initialized. Can be used to dynamically adjust VAD parameters at runtime.

vad_ctx = aic_filter.get_vad_context()
vad_ctx.set_parameter(VadParameter.Sensitivity, 8.0)

Input Frames

FilterEnableFrame

Frame

Specific control frame to toggle filtering on/off

from pipecat.frames.frames import FilterEnableFrame

# Disable speech enhancement
await worker.queue_frame(FilterEnableFrame(False))

# Re-enable speech enhancement
await worker.queue_frame(FilterEnableFrame(True))

Usage Examples

Basic Usage with Quail VAD 2.0

The recommended approach is to use AICFilter for enhancement and AICQuailVADAnalyzer for voice activity detection:

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

Using a Local Model

For offline deployments or when you want to manage model files yourself:

from pipecat.audio.filters.aic_filter import AICFilter

aic_filter = AICFilter(
    license_key=os.environ["AIC_SDK_LICENSE"],
    model_path="/path/to/your/model.aicmodel",
)

Custom Cache Directory

Specify a custom directory for model downloads:

from pipecat.audio.filters.aic_filter import AICFilter

aic_filter = AICFilter(
    license_key=os.environ["AIC_SDK_LICENSE"],
    model_id="quail-s-16khz",
    model_download_dir="/opt/aic-models",
)

With Enhancement Level Control

Control the enhancement strength applied by the model:

from pipecat.audio.filters.aic_filter import AICFilter

# Set enhancement level to 70% strength
aic_filter = AICFilter(
    license_key=os.environ["AIC_SDK_LICENSE"],
    model_id="quail-vf-l-16khz",
    enhancement_level=0.7,
)

# Use default model behavior (no enhancement_level specified)
aic_filter_default = AICFilter(
    license_key=os.environ["AIC_SDK_LICENSE"],
    model_id="quail-vf-l-16khz",
)

With Other Transports

The AIC filter works with any Pipecat transport:

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.websocket import FastAPIWebsocketTransport, FastAPIWebsocketParams

aic_filter = AICFilter(
    license_key=os.environ["AIC_SDK_LICENSE"],
    model_id="quail-vf-2.0-l-16khz",
)

aic_vad = AICQuailVADAnalyzer(
    license_key=os.environ["AIC_SDK_LICENSE"],
)

transport = FastAPIWebsocketTransport(
    params=FastAPIWebsocketParams(
        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,
    ),
)

See the AIC filter example for a complete working example.

Models

For detailed information about the available models, take a look at the Models documentation.

Audio Flow

The AIC filter enhances audio before it reaches the VAD and STT stages, improving transcription accuracy in noisy environments.

Migration Guide (v1 to v2)

For the complete aic-sdk migration guide including all API changes, see the official Python 1.3 to 2.0 Migration Guide.

Migration Steps

Update Pipecat to the latest version (aic-sdk v2.3.0+ is included automatically).
Update environment variable: Change AIC_LICENSE_KEY to AIC_SDK_LICENSE in your .env file.
Remove deprecated constructor parameters (model_type, voice_gain, noise_gate_enable).
Add model_id parameter with an appropriate model (e.g., "quail-vf-2.0-l-16khz").
For VAD: Replace aic_filter.create_vad_analyzer() with AICQuailVADAnalyzer for improved accuracy and independence from the enhancement filter.
Update any runtime VAD adjustments to use the new VAD context API.

Breaking Changes

v1 Parameter	v2 Replacement
`model_type`	`model_id` (string-based model selection)
`enhancement_level`	Now optional (0.0-1.0 range, applies at initialization and when toggling filter on/off)
`voice_gain`	Removed
`noise_gate_enable`	Removed

Notes

Requires ai-coustics license key (get one at developers.ai-coustics.io)
Environment variable: Use AIC_SDK_LICENSE (not AIC_LICENSE_KEY) for authentication
Voice Focus 2.0 models are supported with aic-sdk 2.1.0+ (included in pipecat-ai[aic])
Models are automatically downloaded and cached on first use
Supports real-time audio processing with low latency
Handles PCM_16 audio format (int16 samples)
Thread-safe for pipeline processing
Can be dynamically enabled/disabled via FilterEnableFrame
For VAD: Use AICQuailVADAnalyzer instead of the deprecated create_vad_analyzer() method
For available models, visit artifacts.ai-coustics.io

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Overview

Installation

Constructor Parameters

Methods

create_vad_analyzer

VAD Parameters

get_vad_context

Input Frames

Usage Examples

Basic Usage with Quail VAD 2.0

Using a Local Model

Custom Cache Directory

With Enhancement Level Control

With Other Transports

Models

Audio Flow

Migration Guide (v1 to v2)

Migration Steps

Breaking Changes

Notes

​Overview

​Installation

​Constructor Parameters

​Methods

​create_vad_analyzer

​VAD Parameters

​get_vad_context

​Input Frames

​Usage Examples

​Basic Usage with Quail VAD 2.0

​Using a Local Model

​Custom Cache Directory

​With Enhancement Level Control

​With Other Transports

​Models

​Audio Flow

​Migration Guide (v1 to v2)

​Migration Steps

​Breaking Changes

​Notes

Overview

Installation

Constructor Parameters

Methods

create_vad_analyzer

VAD Parameters

get_vad_context

Input Frames

Usage Examples

Basic Usage with Quail VAD 2.0

Using a Local Model

Custom Cache Directory

With Enhancement Level Control

With Other Transports

Models

Audio Flow

Migration Guide (v1 to v2)

Migration Steps

Breaking Changes

Notes