Skip to main content

pipecat-aircaps

PyPI CI

AirCaps speech-to-text for Pipecat.

AirCapsLiveSTTService streams the user's audio to AirCaps Live 1 (aircaps-live-1), a low-latency English speech-to-text model built for voice agents. It pushes interim transcripts while the user speaks, and when VAD reports the end of speech it asks for the turn's final transcript at once. It can also let the model decide when each turn ends (end_of_turn=True).

Maintained by AirCaps, the company that provides AirCaps Live 1. This is a Pipecat community integration.

Installation

uv add pipecat-aircaps

or pip install pipecat-aircaps.

Prerequisites

An AirCaps API key: sign in to the AirCaps console, open API keys and create one. AirCaps Live 1 is available to every account, one session at a time by default (talk to us for more). The AirCaps Live 1 guide describes the model and its protocol.

export AIRCAPS_API_KEY=...

Usage

import os

from pipecat_aircaps import AirCapsLiveSTTService

stt = AirCapsLiveSTTService(api_key=os.environ["AIRCAPS_API_KEY"])

pipeline = Pipeline(
    [
        transport.input(),
        stt,
        user_aggregator,
        llm,
        tts,
        transport.output(),
        assistant_aggregator,
    ]
)

Use it as you would any Pipecat STT service. It needs VAD frames to know when a turn ends, which the user aggregator provides when it has a VAD analyzer (LLMUserAggregatorParams(vad_analyzer=SileroVADAnalyzer())), as in the example.

Parameter Default
api_key required AirCaps API key
base_url https://api.aircaps.com AirCaps API address
sample_rate pipeline input rate Input audio rate. Audio is resampled to 16 kHz before it is sent
end_of_turn False Let the model detect the end of each turn (see below)
should_interrupt True With end_of_turn: whether a new user turn interrupts the bot
settings model="aircaps-live-1", language=Language.EN, end_of_turn_mode="balanced" AirCapsLiveSTTService.Settings(...)
ttfs_p99_latency 0.25 P99 seconds from end of speech to final transcript, for Pipecat's turn timing. Measure your own with stt-benchmark

How it works:

  • Before each connection the service asks GET /v1/realtime/endpoint?model=aircaps-live-1 where to connect, then opens that WebSocket, so audio goes straight to the model.
  • On VADUserStoppedSpeakingFrame it sends finalize; the final transcript of the turn comes back as one TranscriptionFrame, marked finalized, and Pipecat reports STT TTFB from it.
  • If words arrive that VAD did not hear (a short or quiet word), the service asks for their final itself one second after the last new words, so the user turn they started still ends.
  • A session the server ends (sessions last up to an hour) is reopened automatically.
  • While no audio is sent (for example when the STT is muted), the service pings the session so it stays open.

Model-detected end of turn

stt = AirCapsLiveSTTService(
    api_key=os.environ["AIRCAPS_API_KEY"],
    end_of_turn=True,
    settings=AirCapsLiveSTTService.Settings(end_of_turn_mode="balanced"),
)

With end_of_turn=True the model decides when the user has finished, instead of Pipecat's VAD and turn analyzer:

  • When a turn's first words arrive, the service pushes ProposedUserStartedSpeakingFrame.
  • When the model ends the turn, it pushes the turn's final TranscriptionFrame (finalized), then ProposedUserStoppedSpeakingFrame.
  • The service recommends ExternalUserTurnStrategies, so the user aggregator follows these frames. You don't need a VAD analyzer in the user aggregator for turn ends. If you pass your own user_turn_strategies, they win.

end_of_turn_mode trades speed for certainty: min_latency, balanced (default) or max_accuracy. These settings override single values of the mode (leave them unset to keep the mode's):

Setting Range min_latency / balanced / max_accuracy
end_of_turn_threshold 0.2 to 0.9: how sure the model must be that the turn ended 0.3 / 0.5 / 0.6
min_turn_silence_ms 0 to 1000: the shortest pause that can end a turn 40 / 80 / 400
max_turn_silence_ms 500 to 5000, or 0 for no limit: a pause this long always ends the turn 2560
vad_threshold 0.3 to 0.9: how sure the model's voice detector must be that it hears speech
settings = AirCapsLiveSTTService.Settings(end_of_turn_mode="balanced", min_turn_silence_ms=300)

All of them can be changed with STTUpdateSettingsFrame; the session reopens to apply them.

Not supported by AirCaps Live 1: languages other than English, key terms, speaker labels.

Running the example

examples/voice-agent.py is Pipecat's standard voice agent (OpenAI LLM, Cartesia voice) with AirCaps as its speech-to-text.

git clone https://github.com/aircaps/pipecat-aircaps.git
cd pipecat-aircaps
cp .env.example .env          # add AIRCAPS_API_KEY, OPENAI_API_KEY, CARTESIA_API_KEY
uv sync --extra example
uv run examples/voice-agent.py

Open http://localhost:7860/client and talk to it.

Tests

uv sync
uv run pytest

The tests run against a local fake of the AirCaps API; no key is needed.

Compatibility

Tested with Pipecat v1.16.0, on Python 3.11, 3.12 and 3.13.

Support

Open an issue, or contact AirCaps.

License

BSD 2-Clause, see LICENSE.

Metadata

Release files for pipecat-aircaps 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pipecat-aircaps 0.1.0
File Size Uploaded Provenance Actions
pipecat_aircaps-0.1.0.tar.gz 17.5 kB With provenance Details for pipecat_aircaps-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pipecat-aircaps 0.1.0
File Interpreter ABI Platform Actions
pipecat_aircaps-0.1.0-py3-none-any.whl Python 3 none any Details for pipecat_aircaps-0.1.0-py3-none-any.whl

Total release size: 29.7 kB

Release files / pipecat_aircaps-0.1.0.tar.gz

Download URL pipecat_aircaps-0.1.0.tar.gz
Size 17.5 kB
Tags Source
SHA-256 checksum
How to use checksums
a6f25abaf93ce314b9e761411e52f45ddb32f5d403ab1af60b4135416cbb6caf
BLAKE2b-256 checksum
How to use checksums
eea3def22ab016e91d0aa2c68b7e87bf4039b1328db53e41c894f8e89d65f74b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / pipecat_aircaps-0.1.0-py3-none-any.whl

Download URL pipecat_aircaps-0.1.0-py3-none-any.whl
Size 12.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
beff31f00afbd27f2cc7d842dff210adaa69cec68e4fa4f6728f579cbc747dbb
BLAKE2b-256 checksum
How to use checksums
755b494d7324f4c61625600e5b011d679410630537af6ae850261453556fff71
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for pipecat-aircaps 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pipecat_aircaps-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page