pipecat-aircaps
AirCaps AI 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 AI, 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 AI API key: sign in to the AirCaps AI 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 AI API key |
base_url |
https://api.aircaps.com |
AirCaps AI 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-1where to connect, then opens that WebSocket, so audio goes straight to the model. - On
VADUserStoppedSpeakingFrameit sendsfinalize; the final transcript of the turn comes back as oneTranscriptionFrame, 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), thenProposedUserStoppedSpeakingFrame. - 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 ownuser_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 AI 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 AI 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 AI.
License
BSD 2-Clause, see LICENSE.
Metadata
Release files for pipecat-aircaps 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pipecat_aircaps-0.1.1.tar.gz | 17.6 kB | With provenance | Details for pipecat_aircaps-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pipecat_aircaps-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for pipecat_aircaps-0.1.1-py3-none-any.whl |
Total release size: 29.8 kB
Release files / pipecat_aircaps-0.1.1.tar.gz
| Download URL | pipecat_aircaps-0.1.1.tar.gz |
|---|---|
| Size | 17.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
97ee2ee64ee907dba1bfe3f4fc7140eb4f397b8a980fd3dae72a3796c629e105
|
|
BLAKE2b-256 checksum How to use checksums |
52aafdfa1ef3adef2a5ff4a951ed96e02ee1a9c3b887dc2a0138f220a816eb1e
|
| 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 20, 2026.
Transparency logRelease files / pipecat_aircaps-0.1.1-py3-none-any.whl
| Download URL | pipecat_aircaps-0.1.1-py3-none-any.whl |
|---|---|
| Size | 12.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aac0d8e34e456e53f934337f672ab6b35bc1643752ab576c5d480923bc47745f
|
|
BLAKE2b-256 checksum How to use checksums |
32c4c745a61346e2658d2721409710d2d0877b4d4ff4d0626cc16d0325787b48
|
| 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 20, 2026.
Transparency logSecurity for pipecat-aircaps 0.1.1
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.
Attestation for pipecat_aircaps-0.1.1.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 20, 2026.
Transparency logA 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.