Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ai-coustics.com/llms.txt

Use this file to discover all available pages before exploring further.

Integrate ai-coustics speech enhancement into your LiveKit voice agents in minutes. The livekit-plugins-ai-coustics package provides real-time noise cancellation optimized for human-to-machine audio, improving transcription accuracy for your AI agents.
The plugin supports two authentication modes:
  • LiveKit Cloud - authenticate via lk cloud auth, no ai-coustics SDK key needed.
  • ai-coustics SDK key - pass your license key directly, suitable for self-hosted environments.

​
Setup Guide

Follow these steps to create a new LiveKit agent project with ai-coustics speech enhancement.
1

Create a LiveKit Cloud account

Sign up at LiveKit Cloud if you don’t already have an account.
A LiveKit Cloud account is required when using the default Auth.livekit_cloud() mode. Run lk cloud auth once to authenticate. If you are running in a self-hosted environment, you can skip this step and pass an ai-coustics SDK key via auth=Auth.ai_coustics_api(license_key="...") instead (see Step 8).
2

Install the LiveKit CLI

Install the LiveKit CLI tool for your platform.
3

Authenticate the CLI

lk cloud auth
Cloud only. This step links the CLI to your LiveKit Cloud account. If you are running in a self-hosted environment, skip this step.
4

Create a new agent project

lk app create --template agent-starter-python my-agent
cd my-agent
5

Add the ai-coustics plugin

uv add livekit-plugins-ai-coustics
6

Install dependencies

uv sync
7

Download model files

uv run src/agent.py download-files
8

Enable speech enhancement

Open src/agent.py and update the session.start() call to include audio enhancement:
from livekit.plugins import ai_coustics

session = AgentSession(
  vad=ai_coustics.VAD(),  # Add ai-coustics VAD to session setup
  # ...
)

await session.start(
    agent=Assistant(),
    room=ctx.room,
    room_options=room_io.RoomOptions(
        audio_input=room_io.AudioInputOptions(  
              # Add ai-coustics audio enhancement to audio input options
              noise_cancellation=ai_coustics.audio_enhancement(
                # - EnhancerModel.QUAIL_VF_L  (best for isolating the foreground speaker)
                # - EnhancerModel.QUAIL_VF_S  (smaller, more efficient version of Quail VF)
                # - EnhancerModel.QUAIL_L     (best for multiple/far-field speakers)
                model=ai_coustics.EnhancerModel.QUAIL_VF_L,
                # auth defaults to Auth.livekit_cloud() - omit it when using LiveKit Cloud.
                # For self-hosted environments, pass your license key explicitly:
                #   auth=ai_coustics.Auth.ai_coustics_api(license_key="YOUR_LICENSE_KEY"),
                # - enhancement_level = 0.5 (conservative, foreground speech is always preserved)
                # - enhancement_level = 0.8 (balanced, optimal word error rate on challenging data)
                # - enhancement_level = 1.0 (aggressive, maximum suppression of interfering speech)
                # More info: https://docs.ai-coustics.com/guides/speech-enhancement-for-asr
                model_parameters=ai_coustics.ModelParameters(enhancement_level=0.8),
                # VAD Parameters Info: https://docs.ai-coustics.com/guides/voice-activity-detection
                vad_settings=ai_coustics.VadSettings(
                  # 0.0 to 1.0 seconds
                  speech_hold_duration=0.03,
                  # 1.0 to 15.0
                  sensitivity=6.0,
                  # 0.0 to 1.0 seconds
                  minimum_speech_duration=0.0,
                )
            ),
        )
    ),
)
9

Run the agent

uv run python src/agent.py console
Your agent is now running with ai-coustics Quail Voice Focus. You can start talking to it directly in the console. The Voice Focus models will elevate the foreground speaker while suppressing both interfering speech and background noise.
10

Voice Focus and Multi-Speaker Support

You can use Quail Voice Focus and Quail for multi-speaker scenarios in this integration. Support for Voice Activity Detection will be added in the future.
11

Self-hosted authentication (optional)

If you are not using LiveKit Cloud, pass your ai-coustics license key directly via the auth parameter:
noise_cancellation=ai_coustics.audio_enhancement(
    model=ai_coustics.EnhancerModel.QUAIL_VF_L,
    auth=ai_coustics.Auth.ai_coustics_api(license_key="YOUR_LICENSE_KEY"),
)
Your license key can be generated on the ai-coustics developer platform.

​
Available Models

The LiveKit plugin does not currently have support for loading model files. Instead, it has a limited selection of models embedded in the plugin itself. The models currently available in the plugin are:
  • Quail L (16 kHz): EnhancerModel.QUAIL_L
  • Quail Voice Focus 2.1 L (16 kHz): EnhancerModel.QUAIL_VF_L
  • Quail Voice Focus 2.1 S (16 kHz): EnhancerModel.QUAIL_VF_S

​
Next Steps

Plugin on PyPI

Discover the LiveKit Plugin documentation.

Quail & Voice Focus

Learn about Quail and Voice Focus models for LiveKit.