Skip to main content

livekit-plugins-aircaps

PyPI CI

AirCaps 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, the company that provides AirCaps Live 1.

Installation

pip install livekit-plugins-aircaps

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

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 AirCaps 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 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 API key
base_url "https://api.aircaps.com" AirCaps 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 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 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 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.

License

Apache 2.0, see LICENSE.

Metadata

Release files for livekit-plugins-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)

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

Built distribution (wheel)

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

Total release size: 37.3 kB

Release files / livekit_plugins_aircaps-0.1.1.tar.gz

Download URL livekit_plugins_aircaps-0.1.1.tar.gz
Size 19.9 kB
Tags Source
SHA-256 checksum
How to use checksums
4535efc11affbee06351b2cf66803afc8331032db2e305beaab0ee8bfe3d32f9
BLAKE2b-256 checksum
How to use checksums
9656eb598cb421ba2ce18216ce4e1f39d47260cb0e8a3308f56a020d19249f69
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.1-py3-none-any.whl

Download URL livekit_plugins_aircaps-0.1.1-py3-none-any.whl
Size 17.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8cb2101bdb42fa2052c8c3a4701cb21f42636808e8a730b03fabc34d7ac4579f
BLAKE2b-256 checksum
How to use checksums
417a7a3a6d0963fda61e926e2a9fb0edb7e696b543ebeca2df809a10be3d23f4
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.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.

Select from 2 files

Attestation for livekit_plugins_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 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.1 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