Skip to main content
LiveKit Agents is an open-source framework for real-time voice agents that join LiveKit rooms. livekit-plugins-aircaps adds AirCaps Live 1 to it as a speech-to-text plugin. aircaps.STT streams the user’s audio to AirCaps Live 1, sends interim transcripts while the user speaks, and returns the turn’s final transcript the moment the turn ends. Turns end in one of two ways:
  • LiveKit decides (default). The session’s own turn handling (its VAD or turn detector) ends the turn, and the final transcript comes back right away.
  • AirCaps decides. With end_of_turn=True and turn_detection="stt", the model detects the end of each turn itself.

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.
  • A LiveKit project (LiveKit Cloud or your own server) with its URL, API key and API secret.
Each agent conversation holds one AirCaps Live 1 session. Accounts run one session at a time by default, so a second simultaneous call is refused. For more, talk to sales. See Pricing and limits.

Installation

or uv add livekit-plugins-aircaps.

Authentication

The plugin reads your key from the AIRCAPS_API_KEY environment variable. You can also pass it as aircaps.STT(api_key=...).

Quickstart

1

Install the packages

The plugin, plus LiveKit Agents with Silero VAD:
2

Set your API keys

Put them in a .env file beside your agent:
.env
3

Use AirCaps in the AgentSession

LiveKit flushes the stream at the end of each turn, and the final transcript comes back right away. Without a flush, words stay interim until the stream ends, so keep a VAD (or a turn detector) in this mode.
4

Run and talk to it

Save the complete agent below as agent.py, then:
console runs the agent in your terminal with your microphone and speakers. python agent.py dev connects it to your LiveKit project instead, so you can join it from a room. Ask a question, interrupt the answer, and pause mid-sentence to hear how turns end.
agent.py
This is LiveKit’s basic voice agent with AirCaps as its speech-to-text; the LLM and the voice come from LiveKit Inference, so swap in any LLM and TTS plugin you use. Set AIRCAPS_END_OF_TURN=1 to switch it to model-detected end of turn. The same file is in the plugin’s repository as examples/agent.py.

Parameters

Audio is resampled to 16 kHz mono before it is sent.

Turn detection

LiveKit decides (default)

The session’s turn handling ends each turn: its VAD (turn_detection="vad"), LiveKit’s turn detector model, or a manual commit. LiveKit then flushes the stream, the plugin sends finalize to AirCaps, and the turn’s final transcript comes straight back.
Use this mode when you already tune turns in LiveKit, or want the same turn behaviour across STT providers.

AirCaps decides

Turn on end_of_turn and tell the session to follow the STT:
The model decides when the user has finished, from what was said as well as from the pause.
Set endpointing={"min_delay": 0} in this mode. The model’s end of turn has already waited out the user’s pause, and LiveKit’s default adds another 0.5 seconds to every turn.
Keep the VAD: LiveKit still uses it to detect interruptions while the agent speaks.

End-of-turn settings

A mode is a preset. Start with balanced. Any setting given beside a mode overrides that one value.

Changing settings during a call

update_options changes the end-of-turn settings for new streams and for the ones already open:
For example, switch to max_accuracy while the user reads out a card number, then back to balanced.

How it works

  • Before each session the plugin asks AirCaps where to connect (GET /v1/realtime/endpoint), then opens that WebSocket, so audio goes to the server with the lowest latency for your agent.
  • 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.
Not supported by AirCaps Live 1: languages other than English, key terms and speaker labels. The model supports streaming recognition only.

Troubleshooting

The error codes are those of the AirCaps Live 1 protocol.

Resources