AICFilter

Speech enhancement using ai-coustics’ SDK

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:

pip install "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 · Optional[str] · 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-l-16khz", "quail-s-16khz", "quail-l-8khz"

model_path · Optional[str] · 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 · Optional[Path] · default: "None"

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

Methods

create_vad_analyzer

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

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

VAD Parameters

speech_hold_duration · Optional[float] · 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 · Optional[float] · 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 · Optional[float] · 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 task.queue_frame(FilterEnableFrame(False))

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

Usage Examples

Basic Usage with AIC VAD

The recommended approach is to use AICFilter with its built-in VAD analyzer:

from pipecat.audio.filters.aic_filter import AICFilter
from pipecat.processors.aggregators.llm_response_universal import (
    LLMContextAggregatorPair,
    LLMUserAggregatorParams,
)
from pipecat.transports.services.daily import DailyTransport, DailyParams

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

# Use AIC's integrated VAD
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_filter.create_vad_analyzer(
            speech_hold_duration=0.05,
            minimum_speech_duration=0.0,
            sensitivity=6.0,
        ),
    ),
)

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 Other Transports

The AIC filter works with any Pipecat transport:

from pipecat.audio.filters.aic_filter import AICFilter
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-l-16khz",
)

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_filter.create_vad_analyzer(
            speech_hold_duration=0.05,
            sensitivity=6.0,
        ),
    ),
)

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

1. Update Pipecat to the latest version (aic-sdk v2.x is included automatically).
2. Remove deprecated constructor parameters (model_type, enhancement_level, voice_gain, noise_gate_enable).
3. Add model_id parameter with an appropriate model (e.g., "quail-vf-l-16khz").
4. Update any runtime VAD adjustments to use the new VAD context API.
5. We recommend to use aic_filter.create_vad_analyzer() for improved accuracy.

Breaking Changes

v1 Parameter	v2 Replacement
model_type	model_id (string-based model selection)
enhancement_level	Removed (model-specific behavior)
voice_gain	Removed
noise_gate_enable	Removed

Notes

• Requires ai-coustics license key (get one at developers.ai-coustics.io)
• 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
• Integrated VAD provides better accuracy than standalone VAD when using enhancement
• For available models, visit artifacts.ai-coustics.io