> ## 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.

# AIC Audio Filter

> AICFilter enhances user speech with the ai-coustics SDK, reducing background noise in real-time Pipecat audio.

## 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](https://docs.ai-coustics.com/tutorials/pipecat-quickstart).

> [!NOTE]
>
> This documentation covers **aic-sdk v3.x**. If you're using aic-sdk v2.x or
> v1.x, please see the [Migration Guide](#migration-guides) section below for
> upgrading instructions.

## Installation

The AIC filter requires additional dependencies:

```bash theme={null}
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](https://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](https://artifacts.ai-coustics.io/) for available models.
See the [documentation](https://docs.ai-coustics.com/guides/models) 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** `Path | 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.

## Input Frames

**FilterEnableFrame** `Frame`

Specific control frame to toggle filtering on/off. Queue the frame into the pipeline to toggle the filter used as `audio_in_filter`:

```python theme={null}
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))
```

## Methods

```python theme={null}
aic_filter.set_pre_process_tap(tap)
```

Sets a callable that receives the input audio before enhancement, or removes it when `tap` is `None`. The filter calls `tap(block, sample_rate)` with each float32 block, normalized to `-1.0` to `1.0`, and writes each new block into the same buffer, so the tap must copy any data it keeps. The tap gets no audio when the enhancement processor fails to initialize. The filter does not remove the tap when it stops; the caller that sets it must also remove it. [`AICTytoObserver`](https://docs.pipecat.ai/api-reference/server/utilities/observers/aic-tyto-observer) uses this tap when given the filter as `audio_filter`.

## Usage Examples

### Basic Usage with Quail VAD 2.0

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

```python theme={null}
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.daily.transport 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:

```python theme={null}
from pathlib import Path

from pipecat.audio.filters.aic_filter import AICFilter

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

### Custom Cache Directory

Specify a custom directory for model downloads:

```python theme={null}
from pathlib import Path

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=Path("/opt/aic-models"),
)
```

### With Enhancement Level Control

Control the enhancement strength applied by the model:

```python theme={null}
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:

```python theme={null}
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.fastapi 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(
    websocket=websocket,
    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,
    ),
)
```

> [!NOTE]
>
> See the [AIC filter
> example](https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-aicoustics.py)
> for a complete working example.

## Models

For detailed information about the available models, take a look at the [Models documentation](https://docs.ai-coustics.com/guides/models).

## Audio Flow

```mermaid theme={null}
graph TD
    A[AudioRawFrame] --> B[AICFilter]
    B --> C[STT]
    C --> D[AICQuailVADAnalyzer]
```

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

## Migration Guides

### Migrating from v2 to v3

> [!NOTE]
>
> For the complete aic-sdk migration guide including all API changes, see the
> official [Python 2.5 to 3.0 Migration
> Guide](https://docs.ai-coustics.com/guides/migrations/python-2-5-to-3-0).

#### Migration Steps

1. Update Pipecat to the latest version (aic-sdk v3.4+ is included automatically).
2. **Remove deprecated VAD methods**: The `create_vad_analyzer()` and `get_vad_context()` methods have been removed. Use [`AICQuailVADAnalyzer`](https://docs.pipecat.ai/api-reference/server/services/vad/aic-quail-vad-analyzer) for voice activity detection.
3. Update model selection if needed: The old default `quail-vad-2.0-xxs-16khz` no longer works with aic-sdk 3.0. See [artifacts.ai-coustics.io](https://artifacts.ai-coustics.io/) for current models.

#### Breaking Changes

| v2 Method/Feature | v3 Replacement |
| - | - |
| `create_vad_analyzer()` | Use `AICQuailVADAnalyzer` (removed in v3) |
| `get_vad_context()` | Use `AICQuailVADAnalyzer` for VAD (removed in v3) |
| Old VAD models | `quail-vad-2.0-xxs-16khz` no longer works; use `vad-ms-2.1-xxs-16khz` or other models from artifacts.ai-coustics.io |

### Migrating from v1 to v2

> [!NOTE]
>
> For the complete aic-sdk migration guide including all API changes, see the
> official [Python 1.3 to 2.0 Migration
> Guide](https://docs.ai-coustics.com/guides/migrations/python-1-3-to-2-0#quick-migration-checklist).

#### Migration Steps

1. Update Pipecat to the latest version (aic-sdk v2.3.0+ is included automatically).
2. **Update environment variable**: Change `AIC_LICENSE_KEY` to `AIC_SDK_LICENSE` in your `.env` file.
3. Remove deprecated constructor parameters (`model_type`, `voice_gain`, `noise_gate_enable`).
4. Add `model_id` parameter with an appropriate model (e.g., `"quail-vf-2.0-l-16khz"`).
5. **For VAD**: Replace `aic_filter.create_vad_analyzer()` with `AICQuailVADAnalyzer` for improved accuracy and independence from the enhancement filter.
6. 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](https://developers.ai-coustics.io))
* **Environment variable**: Use `AIC_SDK_LICENSE` (not `AIC_LICENSE_KEY`) for authentication
* **aic-sdk 3.x required**: Version 3.4+ is 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`](https://docs.pipecat.ai/api-reference/server/services/vad/aic-quail-vad-analyzer) for voice activity detection
* The filter closes its ai-coustics session when the pipeline stops
* For available models, visit [artifacts.ai-coustics.io](https://artifacts.ai-coustics.io/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.