Skip to main content

livekit-plugins-aircaps

PyPI CI

AirCaps AI speech-to-text for LiveKit Agents.

aircaps.STT streams the user's audio to AirCaps Live 1 (aircaps-live-1), a low-latency real-time English speech-to-text model built for voice agents. It sends interim transcripts while the user speaks and the turn's final transcript the moment the turn ends: when LiveKit's turn handling says so, or, with end_of_turn=True, when the model detects it.

Maintained by AirCaps AI, the company that provides AirCaps Live 1.

Installation

pip install livekit-plugins-aircaps

or uv add livekit-plugins-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

By default the session's own turn handling decides when the user has finished speaking. LiveKit flushes the stream at the end of each turn (from its VAD or turn detector, or a manual commit), and the final transcript comes back right away:

from livekit.agents import AgentSession
from livekit.plugins import aircaps, silero

session = AgentSession(
    stt=aircaps.STT(),
    vad=silero.VAD.load(),
    # ... llm, tts, turn_handling, etc.
)

Without a flush, words stay interim until the stream ends, so use a VAD (or a turn detector) in this mode.

Model-detected end of turn

To let the model detect the end of each turn instead, turn on end_of_turn and use the STT's turn detection. The model's end of turn has already waited out the user's pause, so set LiveKit's own endpointing delay to 0 (its default adds 0.5 s to every turn):

from livekit.agents import AgentSession, TurnHandlingOptions
from livekit.plugins import aircaps

session = AgentSession(
    stt=aircaps.STT(end_of_turn=True, end_of_turn_mode="balanced"),
    turn_handling=TurnHandlingOptions(turn_detection="stt", endpointing={"min_delay": 0}),
    # ... llm, tts, vad, etc.
)

Options

Option Default
model "aircaps-live-1" The AirCaps AI model
end_of_turn False Let the model detect the end of each turn
end_of_turn_mode "balanced" "min_latency", "balanced" or "max_accuracy". A mode sets the values below; any of them given beside it overrides that one
end_of_turn_threshold the mode's How sure the model must be that the turn ended, 0.2 to 0.9
min_turn_silence_ms the mode's The shortest pause that can end a turn, 0 to 1000 ms
max_turn_silence_ms the mode's A pause this long always ends the turn, 500 to 5000 ms, or 0 for no limit
vad_threshold the mode's How sure the model's voice detector must be that a sound is speech, 0.3 to 0.9
api_key AIRCAPS_API_KEY AirCaps AI API key
base_url "https://api.aircaps.com" AirCaps AI API address
http_session LiveKit's shared session An aiohttp.ClientSession to use

stt.update_options(...) changes the end-of-turn settings, also for streams already open.

Audio is resampled to 16 kHz mono. The model transcribes English and supports streaming recognition only; key terms and speaker labels are not available.

How it works:

  • Before each session the plugin asks the AirCaps AI API where to connect (GET /v1/realtime/endpoint?model=aircaps-live-1), then opens that WebSocket, so audio goes to the nearest server.
  • A flush sends finalize; the turn's final transcript comes straight back.
  • A dropped or ended session (sessions last up to an hour) is reopened, with a new address lookup. A turn cut short by the drop ends with its text so far.

Running the example

examples/agent.py is LiveKit's basic voice agent with AirCaps AI as its speech-to-text (the LLM and the voice come from LiveKit Inference).

git clone https://github.com/aircaps/livekit-plugins-aircaps.git
cd livekit-plugins-aircaps
cp .env.example .env      # add AIRCAPS_API_KEY and your LiveKit project's URL, key and secret
uv sync --extra example
uv run examples/agent.py console

console runs the agent in your terminal with your microphone and speakers; dev connects it to your LiveKit project. AIRCAPS_END_OF_TURN=1 switches it to model-detected end of turn.

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 LiveKit Agents 1.8.13, on Python 3.10 to 3.13.

Support

Open an issue, or contact AirCaps AI.

License

Apache 2.0, see LICENSE.

Metadata

Release files for livekit-plugins-aircaps 0.1.2

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

Source distribution (sdist)

Source distribution for livekit-plugins-aircaps 0.1.2
File Size Uploaded Provenance Actions
livekit_plugins_aircaps-0.1.2.tar.gz 20.1 kB With provenance Details for livekit_plugins_aircaps-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for livekit-plugins-aircaps 0.1.2
File Interpreter ABI Platform Actions
livekit_plugins_aircaps-0.1.2-py3-none-any.whl Python 3 none any Details for livekit_plugins_aircaps-0.1.2-py3-none-any.whl

Total release size: 37.5 kB

Release files / livekit_plugins_aircaps-0.1.2.tar.gz

Download URL livekit_plugins_aircaps-0.1.2.tar.gz
Size 20.1 kB
Tags Source
SHA-256 checksum
How to use checksums
4adddfe83ebcce9f08f9088f21521fb3f646d8164faed6a0bb01e5a8d984ecc0
BLAKE2b-256 checksum
How to use checksums
0e43b30049acf521271249df5ca3f23f0f908b496bdaf7c03df8f468ade35c9c
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 log

Release files / livekit_plugins_aircaps-0.1.2-py3-none-any.whl

Download URL livekit_plugins_aircaps-0.1.2-py3-none-any.whl
Size 17.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0c90756f13b8b44671f244a83ecdac984b71dd7965b7c9bac08aa9992df8f333
BLAKE2b-256 checksum
How to use checksums
dc53198eb2ef78d7ef0a59f7b8a518ef7f831f9a2a5ec3782ef6447befe4bc6e
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 log

Security for livekit-plugins-aircaps 0.1.2

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 livekit_plugins_aircaps-0.1.2.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 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.2 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