livekit-plugins-aircaps 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- livekit/plugins/aircaps/__init__.py +46 -0
- livekit/plugins/aircaps/log.py +3 -0
- livekit/plugins/aircaps/models.py +19 -0
- livekit/plugins/aircaps/py.typed +0 -0
- livekit/plugins/aircaps/stt.py +592 -0
- livekit/plugins/aircaps/version.py +15 -0
- livekit_plugins_aircaps-0.1.0.dist-info/METADATA +165 -0
- livekit_plugins_aircaps-0.1.0.dist-info/RECORD +10 -0
- livekit_plugins_aircaps-0.1.0.dist-info/WHEEL +4 -0
- livekit_plugins_aircaps-0.1.0.dist-info/licenses/LICENSE +202 -0
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Copyright 2026 AirCaps
|
|
2
|
+
#
|
|
3
|
+
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
4
|
+
# you may not use this file except in compliance with the License.
|
|
5
|
+
# You may obtain a copy of the License at
|
|
6
|
+
#
|
|
7
|
+
# http://www.apache.org/licenses/LICENSE-2.0
|
|
8
|
+
#
|
|
9
|
+
# Unless required by applicable law or agreed to in writing, software
|
|
10
|
+
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
11
|
+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
12
|
+
# See the License for the specific language governing permissions and
|
|
13
|
+
# limitations under the License.
|
|
14
|
+
|
|
15
|
+
"""AirCaps plugin for LiveKit Agents
|
|
16
|
+
|
|
17
|
+
Streaming speech-to-text with AirCaps Live.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
from .models import EndOfTurnMode, STTModels
|
|
21
|
+
from .stt import STT, SpeechStream, STTOptions
|
|
22
|
+
from .version import __version__
|
|
23
|
+
|
|
24
|
+
__all__ = ["STT", "SpeechStream", "STTOptions", "STTModels", "EndOfTurnMode", "__version__"]
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
from livekit.agents import Plugin
|
|
28
|
+
|
|
29
|
+
from .log import logger
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class AirCapsPlugin(Plugin):
|
|
33
|
+
def __init__(self) -> None:
|
|
34
|
+
super().__init__(__name__, __version__, __package__, logger)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
Plugin.register_plugin(AirCapsPlugin())
|
|
38
|
+
|
|
39
|
+
# Cleanup docs of unexported modules
|
|
40
|
+
_module = dir()
|
|
41
|
+
NOT_IN_ALL = [m for m in _module if m not in __all__]
|
|
42
|
+
|
|
43
|
+
__pdoc__ = {}
|
|
44
|
+
|
|
45
|
+
for n in NOT_IN_ALL:
|
|
46
|
+
__pdoc__[n] = False
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Copyright 2026 AirCaps
|
|
2
|
+
#
|
|
3
|
+
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
4
|
+
# you may not use this file except in compliance with the License.
|
|
5
|
+
# You may obtain a copy of the License at
|
|
6
|
+
#
|
|
7
|
+
# http://www.apache.org/licenses/LICENSE-2.0
|
|
8
|
+
#
|
|
9
|
+
# Unless required by applicable law or agreed to in writing, software
|
|
10
|
+
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
11
|
+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
12
|
+
# See the License for the specific language governing permissions and
|
|
13
|
+
# limitations under the License.
|
|
14
|
+
|
|
15
|
+
from typing import Literal
|
|
16
|
+
|
|
17
|
+
STTModels = Literal["aircaps-live-1"]
|
|
18
|
+
|
|
19
|
+
EndOfTurnMode = Literal["min_latency", "balanced", "max_accuracy"]
|
|
File without changes
|
|
@@ -0,0 +1,592 @@
|
|
|
1
|
+
# Copyright 2026 AirCaps
|
|
2
|
+
#
|
|
3
|
+
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
4
|
+
# you may not use this file except in compliance with the License.
|
|
5
|
+
# You may obtain a copy of the License at
|
|
6
|
+
#
|
|
7
|
+
# http://www.apache.org/licenses/LICENSE-2.0
|
|
8
|
+
#
|
|
9
|
+
# Unless required by applicable law or agreed to in writing, software
|
|
10
|
+
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
11
|
+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
12
|
+
# See the License for the specific language governing permissions and
|
|
13
|
+
# limitations under the License.
|
|
14
|
+
|
|
15
|
+
"""AirCaps Live speech-to-text.
|
|
16
|
+
|
|
17
|
+
Each stream is one AirCaps session: the plugin asks the AirCaps API where to
|
|
18
|
+
connect, opens a WebSocket there, sends 16 kHz mono PCM16 and turns the
|
|
19
|
+
session's transcript events into LiveKit speech events.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from __future__ import annotations
|
|
23
|
+
|
|
24
|
+
import asyncio
|
|
25
|
+
import contextlib
|
|
26
|
+
import dataclasses
|
|
27
|
+
import json
|
|
28
|
+
import os
|
|
29
|
+
import weakref
|
|
30
|
+
from dataclasses import dataclass
|
|
31
|
+
from typing import Any
|
|
32
|
+
|
|
33
|
+
import aiohttp
|
|
34
|
+
|
|
35
|
+
from livekit.agents import (
|
|
36
|
+
DEFAULT_API_CONNECT_OPTIONS,
|
|
37
|
+
APIConnectionError,
|
|
38
|
+
APIConnectOptions,
|
|
39
|
+
APIStatusError,
|
|
40
|
+
APITimeoutError,
|
|
41
|
+
LanguageCode,
|
|
42
|
+
stt,
|
|
43
|
+
utils,
|
|
44
|
+
)
|
|
45
|
+
from livekit.agents.types import NOT_GIVEN, NotGivenOr
|
|
46
|
+
from livekit.agents.utils import AudioBuffer, is_given
|
|
47
|
+
|
|
48
|
+
from .log import logger
|
|
49
|
+
from .models import EndOfTurnMode, STTModels
|
|
50
|
+
|
|
51
|
+
SAMPLE_RATE = 16000
|
|
52
|
+
"""The model takes 16 kHz mono PCM16; other input rates are resampled to it."""
|
|
53
|
+
|
|
54
|
+
_CHUNK_SAMPLES = SAMPLE_RATE // 50 # 20 ms of audio per WebSocket frame
|
|
55
|
+
_DEFAULT_BASE_URL = "https://api.aircaps.com"
|
|
56
|
+
|
|
57
|
+
# The server refuses audio sent more than 2 s ahead of real time, counted from just after
|
|
58
|
+
# `ready` (a 1.75 s burst at `ready` passes, 1.9 s does not). Audio is paced to stay within
|
|
59
|
+
# _MAX_BURST_S, and a (re)connection sends at most _MAX_BACKLOG_S of the audio that queued
|
|
60
|
+
# while it connected: older audio could only be sent late, adding its length to the latency
|
|
61
|
+
# of every later transcript.
|
|
62
|
+
_MAX_BURST_S = 1.5
|
|
63
|
+
_MAX_BACKLOG_S = 1.25
|
|
64
|
+
|
|
65
|
+
# The server closes a session that receives nothing for 45 s.
|
|
66
|
+
_KEEPALIVE_INTERVAL_S = 20.0
|
|
67
|
+
|
|
68
|
+
# The model may punctuate the end of the previous turn once it hears more ("evening"
|
|
69
|
+
# becomes "evening. Actually ..."): that punctuation belongs to the previous turn.
|
|
70
|
+
_LEADING_PUNCTUATION = " .,!?;:"
|
|
71
|
+
|
|
72
|
+
# Session errors that a new attempt does not fix.
|
|
73
|
+
_PERMANENT_ERRORS = frozenset(
|
|
74
|
+
{
|
|
75
|
+
"unauthorized",
|
|
76
|
+
"unsupported_model",
|
|
77
|
+
"unsupported_option",
|
|
78
|
+
"invalid_start",
|
|
79
|
+
"invalid_message",
|
|
80
|
+
"invalid_audio_frame",
|
|
81
|
+
"frame_too_large",
|
|
82
|
+
}
|
|
83
|
+
)
|
|
84
|
+
|
|
85
|
+
_END_OF_TURN_OVERRIDES = (
|
|
86
|
+
"end_of_turn_threshold",
|
|
87
|
+
"min_turn_silence_ms",
|
|
88
|
+
"max_turn_silence_ms",
|
|
89
|
+
"vad_threshold",
|
|
90
|
+
)
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
@dataclass
|
|
94
|
+
class STTOptions:
|
|
95
|
+
model: STTModels | str
|
|
96
|
+
end_of_turn: bool
|
|
97
|
+
end_of_turn_mode: EndOfTurnMode
|
|
98
|
+
end_of_turn_threshold: NotGivenOr[float]
|
|
99
|
+
min_turn_silence_ms: NotGivenOr[int]
|
|
100
|
+
max_turn_silence_ms: NotGivenOr[int]
|
|
101
|
+
vad_threshold: NotGivenOr[float]
|
|
102
|
+
|
|
103
|
+
def end_of_turn_fields(self) -> dict[str, Any]:
|
|
104
|
+
"""The end-of-turn fields of a ``start`` or ``configure`` message."""
|
|
105
|
+
if not self.end_of_turn:
|
|
106
|
+
return {"end_of_turn": False}
|
|
107
|
+
fields: dict[str, Any] = {"end_of_turn": True, "end_of_turn_mode": self.end_of_turn_mode}
|
|
108
|
+
for name in _END_OF_TURN_OVERRIDES:
|
|
109
|
+
value = getattr(self, name)
|
|
110
|
+
if is_given(value):
|
|
111
|
+
fields[name] = value
|
|
112
|
+
return fields
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
class STT(stt.STT):
|
|
116
|
+
def __init__(
|
|
117
|
+
self,
|
|
118
|
+
*,
|
|
119
|
+
model: STTModels | str = "aircaps-live-1",
|
|
120
|
+
end_of_turn: bool = False,
|
|
121
|
+
end_of_turn_mode: EndOfTurnMode = "balanced",
|
|
122
|
+
end_of_turn_threshold: NotGivenOr[float] = NOT_GIVEN,
|
|
123
|
+
min_turn_silence_ms: NotGivenOr[int] = NOT_GIVEN,
|
|
124
|
+
max_turn_silence_ms: NotGivenOr[int] = NOT_GIVEN,
|
|
125
|
+
vad_threshold: NotGivenOr[float] = NOT_GIVEN,
|
|
126
|
+
api_key: NotGivenOr[str] = NOT_GIVEN,
|
|
127
|
+
base_url: str = _DEFAULT_BASE_URL,
|
|
128
|
+
http_session: aiohttp.ClientSession | None = None,
|
|
129
|
+
) -> None:
|
|
130
|
+
"""Create a new instance of AirCaps Live STT.
|
|
131
|
+
|
|
132
|
+
Turns end in one of two ways. By default the session's turn handling decides:
|
|
133
|
+
LiveKit flushes the stream when its VAD or turn detector says the user stopped
|
|
134
|
+
speaking, and the final transcript comes back at once. With ``end_of_turn=True``
|
|
135
|
+
the model detects the end of each turn itself; use it with
|
|
136
|
+
``turn_detection="stt"`` on the ``AgentSession``.
|
|
137
|
+
|
|
138
|
+
Args:
|
|
139
|
+
model: The AirCaps model. Defaults to ``"aircaps-live-1"``.
|
|
140
|
+
end_of_turn: Let the model detect the end of each turn. Defaults to False.
|
|
141
|
+
end_of_turn_mode: With ``end_of_turn``, how the model trades speed for
|
|
142
|
+
certainty: ``"min_latency"``, ``"balanced"`` (default) or ``"max_accuracy"``.
|
|
143
|
+
The settings below override single values of the mode.
|
|
144
|
+
end_of_turn_threshold: How sure the model must be that the turn ended,
|
|
145
|
+
0.2 to 0.9.
|
|
146
|
+
min_turn_silence_ms: The shortest pause that can end a turn, 0 to 1000 ms.
|
|
147
|
+
max_turn_silence_ms: A pause this long always ends the turn, 500 to 5000 ms,
|
|
148
|
+
or 0 for no limit.
|
|
149
|
+
vad_threshold: How sure the model's voice detector must be that a sound is
|
|
150
|
+
speech, 0.3 to 0.9.
|
|
151
|
+
api_key: AirCaps API key. Defaults to the ``AIRCAPS_API_KEY`` environment
|
|
152
|
+
variable.
|
|
153
|
+
base_url: The AirCaps API address. Defaults to ``"https://api.aircaps.com"``.
|
|
154
|
+
http_session: Optional aiohttp session to use for requests.
|
|
155
|
+
"""
|
|
156
|
+
super().__init__(
|
|
157
|
+
capabilities=stt.STTCapabilities(
|
|
158
|
+
streaming=True,
|
|
159
|
+
interim_results=True,
|
|
160
|
+
offline_recognize=False,
|
|
161
|
+
manual_flush=True,
|
|
162
|
+
)
|
|
163
|
+
)
|
|
164
|
+
aircaps_api_key = api_key if is_given(api_key) else os.environ.get("AIRCAPS_API_KEY")
|
|
165
|
+
if not aircaps_api_key:
|
|
166
|
+
raise ValueError(
|
|
167
|
+
"AirCaps API key is required, either as argument or set "
|
|
168
|
+
"AIRCAPS_API_KEY environment variable"
|
|
169
|
+
)
|
|
170
|
+
self._api_key = aircaps_api_key
|
|
171
|
+
self._base_url = base_url.rstrip("/")
|
|
172
|
+
self._opts = STTOptions(
|
|
173
|
+
model=model,
|
|
174
|
+
end_of_turn=end_of_turn,
|
|
175
|
+
end_of_turn_mode=end_of_turn_mode,
|
|
176
|
+
end_of_turn_threshold=end_of_turn_threshold,
|
|
177
|
+
min_turn_silence_ms=min_turn_silence_ms,
|
|
178
|
+
max_turn_silence_ms=max_turn_silence_ms,
|
|
179
|
+
vad_threshold=vad_threshold,
|
|
180
|
+
)
|
|
181
|
+
self._session = http_session
|
|
182
|
+
self._streams = weakref.WeakSet[SpeechStream]()
|
|
183
|
+
|
|
184
|
+
@property
|
|
185
|
+
def model(self) -> str:
|
|
186
|
+
return self._opts.model
|
|
187
|
+
|
|
188
|
+
@property
|
|
189
|
+
def provider(self) -> str:
|
|
190
|
+
return "AirCaps"
|
|
191
|
+
|
|
192
|
+
def _ensure_session(self) -> aiohttp.ClientSession:
|
|
193
|
+
if not self._session:
|
|
194
|
+
self._session = utils.http_context.http_session()
|
|
195
|
+
return self._session
|
|
196
|
+
|
|
197
|
+
async def _recognize_impl(
|
|
198
|
+
self,
|
|
199
|
+
buffer: AudioBuffer,
|
|
200
|
+
*,
|
|
201
|
+
language: NotGivenOr[str] = NOT_GIVEN,
|
|
202
|
+
conn_options: APIConnectOptions,
|
|
203
|
+
) -> stt.SpeechEvent:
|
|
204
|
+
raise NotImplementedError("AirCaps Live STT supports streaming recognition only")
|
|
205
|
+
|
|
206
|
+
def stream(
|
|
207
|
+
self,
|
|
208
|
+
*,
|
|
209
|
+
language: NotGivenOr[str] = NOT_GIVEN,
|
|
210
|
+
conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS,
|
|
211
|
+
) -> SpeechStream:
|
|
212
|
+
"""Open a streaming session. ``language`` is not used: the model transcribes English."""
|
|
213
|
+
stream = SpeechStream(
|
|
214
|
+
stt=self,
|
|
215
|
+
opts=dataclasses.replace(self._opts),
|
|
216
|
+
conn_options=conn_options,
|
|
217
|
+
api_key=self._api_key,
|
|
218
|
+
base_url=self._base_url,
|
|
219
|
+
http_session=self._ensure_session(),
|
|
220
|
+
)
|
|
221
|
+
self._streams.add(stream)
|
|
222
|
+
return stream
|
|
223
|
+
|
|
224
|
+
def update_options(
|
|
225
|
+
self,
|
|
226
|
+
*,
|
|
227
|
+
end_of_turn: NotGivenOr[bool] = NOT_GIVEN,
|
|
228
|
+
end_of_turn_mode: NotGivenOr[EndOfTurnMode] = NOT_GIVEN,
|
|
229
|
+
end_of_turn_threshold: NotGivenOr[float] = NOT_GIVEN,
|
|
230
|
+
min_turn_silence_ms: NotGivenOr[int] = NOT_GIVEN,
|
|
231
|
+
max_turn_silence_ms: NotGivenOr[int] = NOT_GIVEN,
|
|
232
|
+
vad_threshold: NotGivenOr[float] = NOT_GIVEN,
|
|
233
|
+
) -> None:
|
|
234
|
+
"""Change the end-of-turn settings, for new streams and for open ones mid-session.
|
|
235
|
+
|
|
236
|
+
Args:
|
|
237
|
+
end_of_turn: Let the model detect the end of each turn.
|
|
238
|
+
end_of_turn_mode: ``"min_latency"``, ``"balanced"`` or ``"max_accuracy"``.
|
|
239
|
+
end_of_turn_threshold: How sure the model must be that the turn ended, 0.2 to 0.9.
|
|
240
|
+
min_turn_silence_ms: The shortest pause that can end a turn, 0 to 1000 ms.
|
|
241
|
+
max_turn_silence_ms: A pause this long always ends the turn, 500 to 5000 ms,
|
|
242
|
+
or 0 for no limit.
|
|
243
|
+
vad_threshold: How sure the model's voice detector must be that a sound is
|
|
244
|
+
speech, 0.3 to 0.9.
|
|
245
|
+
"""
|
|
246
|
+
changes: dict[str, Any] = {
|
|
247
|
+
name: value
|
|
248
|
+
for name, value in (
|
|
249
|
+
("end_of_turn", end_of_turn),
|
|
250
|
+
("end_of_turn_mode", end_of_turn_mode),
|
|
251
|
+
("end_of_turn_threshold", end_of_turn_threshold),
|
|
252
|
+
("min_turn_silence_ms", min_turn_silence_ms),
|
|
253
|
+
("max_turn_silence_ms", max_turn_silence_ms),
|
|
254
|
+
("vad_threshold", vad_threshold),
|
|
255
|
+
)
|
|
256
|
+
if is_given(value)
|
|
257
|
+
}
|
|
258
|
+
if not changes:
|
|
259
|
+
return
|
|
260
|
+
self._opts = dataclasses.replace(self._opts, **changes)
|
|
261
|
+
for stream in self._streams:
|
|
262
|
+
stream._update_options(changes)
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
class SpeechStream(stt.SpeechStream):
|
|
266
|
+
def __init__(
|
|
267
|
+
self,
|
|
268
|
+
*,
|
|
269
|
+
stt: STT,
|
|
270
|
+
opts: STTOptions,
|
|
271
|
+
conn_options: APIConnectOptions,
|
|
272
|
+
api_key: str,
|
|
273
|
+
base_url: str,
|
|
274
|
+
http_session: aiohttp.ClientSession,
|
|
275
|
+
) -> None:
|
|
276
|
+
super().__init__(stt=stt, conn_options=conn_options, sample_rate=SAMPLE_RATE)
|
|
277
|
+
self._opts = opts
|
|
278
|
+
self._api_key = api_key
|
|
279
|
+
self._base_url = base_url
|
|
280
|
+
self._session = http_session
|
|
281
|
+
# `configure` messages for the open session
|
|
282
|
+
self._control_ch = utils.aio.Chan[str]()
|
|
283
|
+
self._usage_s = 0.0 # audio sent and not yet reported
|
|
284
|
+
# per session: the transcript so far, and how much of it the last final covered
|
|
285
|
+
self._text = ""
|
|
286
|
+
self._final_length = 0
|
|
287
|
+
self._last_interim = ""
|
|
288
|
+
self._in_turn = False
|
|
289
|
+
|
|
290
|
+
def _update_options(self, changes: dict[str, Any]) -> None:
|
|
291
|
+
self._opts = dataclasses.replace(self._opts, **changes)
|
|
292
|
+
# a session that is not open yet starts with the new options
|
|
293
|
+
self._control_ch.send_nowait(
|
|
294
|
+
json.dumps({"type": "configure", **self._opts.end_of_turn_fields()})
|
|
295
|
+
)
|
|
296
|
+
|
|
297
|
+
async def _run(self) -> None:
|
|
298
|
+
# control messages queued before this session opened are covered by its start message
|
|
299
|
+
while not self._control_ch.empty():
|
|
300
|
+
self._control_ch.recv_nowait()
|
|
301
|
+
ws, monitor = await self._connect()
|
|
302
|
+
self._text, self._final_length, self._last_interim = "", 0, ""
|
|
303
|
+
closing = False # `finish` sent: the session ends with `finished`
|
|
304
|
+
|
|
305
|
+
async def send_task() -> None:
|
|
306
|
+
nonlocal closing
|
|
307
|
+
loop = asyncio.get_running_loop()
|
|
308
|
+
started = loop.time()
|
|
309
|
+
sent_s = 0.0
|
|
310
|
+
audio_bstream = utils.audio.AudioByteStream(
|
|
311
|
+
sample_rate=SAMPLE_RATE, num_channels=1, samples_per_channel=_CHUNK_SAMPLES
|
|
312
|
+
)
|
|
313
|
+
backlog = self._take_backlog()
|
|
314
|
+
try:
|
|
315
|
+
while True:
|
|
316
|
+
if backlog:
|
|
317
|
+
data = backlog.pop(0)
|
|
318
|
+
else:
|
|
319
|
+
try:
|
|
320
|
+
data = await self._input_ch.recv()
|
|
321
|
+
except utils.aio.ChanClosed:
|
|
322
|
+
break
|
|
323
|
+
if isinstance(data, self._FlushSentinel):
|
|
324
|
+
frames = audio_bstream.flush()
|
|
325
|
+
else:
|
|
326
|
+
frames = audio_bstream.write(data.data.tobytes())
|
|
327
|
+
for frame in frames:
|
|
328
|
+
ahead = sent_s + frame.duration - (loop.time() - started)
|
|
329
|
+
if ahead > _MAX_BURST_S:
|
|
330
|
+
await asyncio.sleep(ahead - _MAX_BURST_S)
|
|
331
|
+
await ws.send_bytes(frame.data.tobytes())
|
|
332
|
+
sent_s += frame.duration
|
|
333
|
+
self._usage_s += frame.duration
|
|
334
|
+
if isinstance(data, self._FlushSentinel):
|
|
335
|
+
await ws.send_str(json.dumps({"type": "finalize"}))
|
|
336
|
+
|
|
337
|
+
closing = True
|
|
338
|
+
await ws.send_str(json.dumps({"type": "finish"}))
|
|
339
|
+
except (aiohttp.ClientError, ConnectionError) as e:
|
|
340
|
+
raise APIConnectionError("AirCaps connection closed unexpectedly") from e
|
|
341
|
+
|
|
342
|
+
# a failed send of these ends nothing: the receive side reports the closed connection
|
|
343
|
+
async def control_task() -> None:
|
|
344
|
+
async for message in self._control_ch:
|
|
345
|
+
if not closing:
|
|
346
|
+
with contextlib.suppress(aiohttp.ClientError, ConnectionError):
|
|
347
|
+
await ws.send_str(message)
|
|
348
|
+
|
|
349
|
+
async def keepalive_task() -> None:
|
|
350
|
+
while not closing:
|
|
351
|
+
await asyncio.sleep(_KEEPALIVE_INTERVAL_S)
|
|
352
|
+
if not closing:
|
|
353
|
+
with contextlib.suppress(aiohttp.ClientError, ConnectionError):
|
|
354
|
+
await ws.send_str(json.dumps({"type": "ping"}))
|
|
355
|
+
|
|
356
|
+
async def recv_task() -> None:
|
|
357
|
+
while True:
|
|
358
|
+
msg = await monitor.receive()
|
|
359
|
+
if msg.type in (
|
|
360
|
+
aiohttp.WSMsgType.CLOSED,
|
|
361
|
+
aiohttp.WSMsgType.CLOSE,
|
|
362
|
+
aiohttp.WSMsgType.CLOSING,
|
|
363
|
+
):
|
|
364
|
+
if closing:
|
|
365
|
+
return
|
|
366
|
+
raise APIStatusError(
|
|
367
|
+
"AirCaps connection closed unexpectedly",
|
|
368
|
+
status_code=ws.close_code or -1,
|
|
369
|
+
body=f"{msg.data=} {msg.extra=}",
|
|
370
|
+
retryable=True,
|
|
371
|
+
)
|
|
372
|
+
if msg.type != aiohttp.WSMsgType.TEXT:
|
|
373
|
+
continue
|
|
374
|
+
try:
|
|
375
|
+
data = json.loads(msg.data)
|
|
376
|
+
except ValueError:
|
|
377
|
+
logger.warning("AirCaps sent a message that is not JSON")
|
|
378
|
+
continue
|
|
379
|
+
kind = data.get("type")
|
|
380
|
+
if kind == "transcript":
|
|
381
|
+
self._mark_provider_progress()
|
|
382
|
+
self._on_transcript(data)
|
|
383
|
+
elif kind == "finished":
|
|
384
|
+
return
|
|
385
|
+
elif kind == "error":
|
|
386
|
+
raise _session_error(data, ws.close_code)
|
|
387
|
+
elif kind == "session_limit":
|
|
388
|
+
# the server ends the session next; the stream then opens a new one
|
|
389
|
+
logger.warning("AirCaps session limit: %s", data.get("message"))
|
|
390
|
+
|
|
391
|
+
tasks = [
|
|
392
|
+
asyncio.create_task(send_task(), name="AirCaps.send"),
|
|
393
|
+
asyncio.create_task(recv_task(), name="AirCaps.recv"),
|
|
394
|
+
asyncio.create_task(control_task(), name="AirCaps.control"),
|
|
395
|
+
asyncio.create_task(keepalive_task(), name="AirCaps.keepalive"),
|
|
396
|
+
]
|
|
397
|
+
try:
|
|
398
|
+
# the session is over when the receive side sees `finished`, or either side fails
|
|
399
|
+
done, _ = await asyncio.wait(tasks[:2], return_when=asyncio.FIRST_COMPLETED)
|
|
400
|
+
for task in done:
|
|
401
|
+
task.result()
|
|
402
|
+
if tasks[1] not in done:
|
|
403
|
+
await tasks[1]
|
|
404
|
+
elif not closing:
|
|
405
|
+
raise APIConnectionError("AirCaps ended the session")
|
|
406
|
+
finally:
|
|
407
|
+
await utils.aio.gracefully_cancel(*tasks)
|
|
408
|
+
await ws.close()
|
|
409
|
+
# a turn lives in one session: one cut short ends with its text so far
|
|
410
|
+
self._end_turn(self._turn_text())
|
|
411
|
+
|
|
412
|
+
async def _connect(
|
|
413
|
+
self,
|
|
414
|
+
) -> tuple[aiohttp.ClientWebSocketResponse, utils.aio.WebSocketMonitor]:
|
|
415
|
+
"""Look up the session address, open the WebSocket and wait until the session is ready.
|
|
416
|
+
|
|
417
|
+
The address is looked up before every session: it is the server with the lowest
|
|
418
|
+
latency that can take a session now, and can differ from one session to the next.
|
|
419
|
+
"""
|
|
420
|
+
headers = {"Authorization": f"Bearer {self._api_key}"}
|
|
421
|
+
try:
|
|
422
|
+
async with self._session.get(
|
|
423
|
+
f"{self._base_url}/v1/realtime/endpoint",
|
|
424
|
+
params={"model": self._opts.model},
|
|
425
|
+
headers=headers,
|
|
426
|
+
timeout=aiohttp.ClientTimeout(total=self._conn_options.timeout),
|
|
427
|
+
) as resp:
|
|
428
|
+
text = await resp.text()
|
|
429
|
+
try:
|
|
430
|
+
body = json.loads(text)
|
|
431
|
+
except ValueError:
|
|
432
|
+
body = text
|
|
433
|
+
if resp.status != 200:
|
|
434
|
+
raise APIStatusError(
|
|
435
|
+
f"AirCaps endpoint lookup failed: {_error_message(body)}",
|
|
436
|
+
status_code=resp.status,
|
|
437
|
+
body=body,
|
|
438
|
+
)
|
|
439
|
+
url = body["websocket_url"]
|
|
440
|
+
ws = await asyncio.wait_for(
|
|
441
|
+
self._session.ws_connect(url, headers=headers, autoping=False),
|
|
442
|
+
self._conn_options.timeout,
|
|
443
|
+
)
|
|
444
|
+
except aiohttp.WSServerHandshakeError as e:
|
|
445
|
+
raise APIStatusError(
|
|
446
|
+
"AirCaps refused the connection", status_code=e.status, body=e.message
|
|
447
|
+
) from e
|
|
448
|
+
except asyncio.TimeoutError as e:
|
|
449
|
+
raise APITimeoutError("AirCaps connection timed out") from e
|
|
450
|
+
except (aiohttp.ClientError, KeyError, TypeError) as e:
|
|
451
|
+
raise APIConnectionError("failed to connect to AirCaps") from e
|
|
452
|
+
|
|
453
|
+
start = {
|
|
454
|
+
"type": "start",
|
|
455
|
+
"model": self._opts.model,
|
|
456
|
+
"encoding": "pcm_s16le",
|
|
457
|
+
"sample_rate": SAMPLE_RATE,
|
|
458
|
+
"channels": 1,
|
|
459
|
+
}
|
|
460
|
+
if self._opts.end_of_turn:
|
|
461
|
+
start.update(self._opts.end_of_turn_fields())
|
|
462
|
+
monitor = utils.aio.WebSocketMonitor(
|
|
463
|
+
ws, liveness_timeout=self._conn_options.liveness_timeout
|
|
464
|
+
)
|
|
465
|
+
|
|
466
|
+
async def ready() -> None:
|
|
467
|
+
# status messages can come before `ready`; audio must not
|
|
468
|
+
while True:
|
|
469
|
+
msg = await monitor.receive()
|
|
470
|
+
if msg.type != aiohttp.WSMsgType.TEXT:
|
|
471
|
+
raise APIStatusError(
|
|
472
|
+
"AirCaps closed the session before it was ready",
|
|
473
|
+
status_code=ws.close_code or -1,
|
|
474
|
+
retryable=True,
|
|
475
|
+
)
|
|
476
|
+
data = json.loads(msg.data)
|
|
477
|
+
if data.get("type") == "ready":
|
|
478
|
+
return
|
|
479
|
+
if data.get("type") == "error":
|
|
480
|
+
raise _session_error(data, ws.close_code)
|
|
481
|
+
|
|
482
|
+
try:
|
|
483
|
+
await ws.send_str(json.dumps(start))
|
|
484
|
+
await asyncio.wait_for(ready(), self._conn_options.timeout)
|
|
485
|
+
except BaseException as e:
|
|
486
|
+
await ws.close()
|
|
487
|
+
if isinstance(e, asyncio.TimeoutError):
|
|
488
|
+
raise APITimeoutError("AirCaps session was not ready in time") from e
|
|
489
|
+
if isinstance(e, (aiohttp.ClientError, ConnectionError, ValueError)):
|
|
490
|
+
raise APIConnectionError("AirCaps session failed to start") from e
|
|
491
|
+
raise
|
|
492
|
+
return ws, monitor
|
|
493
|
+
|
|
494
|
+
def _take_backlog(self) -> list[Any]:
|
|
495
|
+
"""Take the input queued so far, keeping at most _MAX_BACKLOG_S of its newest audio."""
|
|
496
|
+
queued: list[Any] = []
|
|
497
|
+
while not self._input_ch.empty():
|
|
498
|
+
queued.append(self._input_ch.recv_nowait())
|
|
499
|
+
audio_s = sum(item.duration for item in queued if not isinstance(item, self._FlushSentinel))
|
|
500
|
+
dropped_s = 0.0
|
|
501
|
+
kept: list[Any] = []
|
|
502
|
+
for item in queued:
|
|
503
|
+
if (
|
|
504
|
+
not isinstance(item, self._FlushSentinel)
|
|
505
|
+
and audio_s - dropped_s > _MAX_BACKLOG_S + 1e-6
|
|
506
|
+
):
|
|
507
|
+
dropped_s += item.duration
|
|
508
|
+
continue
|
|
509
|
+
kept.append(item)
|
|
510
|
+
if dropped_s:
|
|
511
|
+
logger.warning(
|
|
512
|
+
"dropped %.1f s of audio that queued while connecting to AirCaps", dropped_s
|
|
513
|
+
)
|
|
514
|
+
return kept
|
|
515
|
+
|
|
516
|
+
def _turn_text(self) -> str:
|
|
517
|
+
"""The current turn's words: the transcript after the last final."""
|
|
518
|
+
turn = self._text[self._final_length :].lstrip(_LEADING_PUNCTUATION).strip()
|
|
519
|
+
# punctuation alone is not speech: the model can add "?" to the end of the previous
|
|
520
|
+
# turn after its final
|
|
521
|
+
return turn if any(c.isalnum() for c in turn) else ""
|
|
522
|
+
|
|
523
|
+
def _on_transcript(self, data: dict[str, Any]) -> None:
|
|
524
|
+
# each event carries the session's whole transcript; the characters before the last
|
|
525
|
+
# final never change, so the current turn is the rest
|
|
526
|
+
self._text = str(data.get("text") or "")
|
|
527
|
+
turn = self._turn_text()
|
|
528
|
+
if turn and not self._in_turn:
|
|
529
|
+
self._in_turn = True
|
|
530
|
+
self._event_ch.send_nowait(stt.SpeechEvent(type=stt.SpeechEventType.START_OF_SPEECH))
|
|
531
|
+
|
|
532
|
+
if not data.get("is_final"):
|
|
533
|
+
if turn and turn != self._last_interim:
|
|
534
|
+
self._last_interim = turn
|
|
535
|
+
self._event_ch.send_nowait(
|
|
536
|
+
stt.SpeechEvent(
|
|
537
|
+
type=stt.SpeechEventType.INTERIM_TRANSCRIPT,
|
|
538
|
+
alternatives=[_speech_data(turn)],
|
|
539
|
+
)
|
|
540
|
+
)
|
|
541
|
+
return
|
|
542
|
+
|
|
543
|
+
# the answer to a flush, or the model ended the turn: all of the text is final
|
|
544
|
+
self._final_length = len(self._text)
|
|
545
|
+
self._end_turn(turn, final=True)
|
|
546
|
+
|
|
547
|
+
def _end_turn(self, turn: str, *, final: bool = False) -> None:
|
|
548
|
+
"""Send the turn's final transcript and close the turn.
|
|
549
|
+
|
|
550
|
+
``final`` is False for a turn cut short by its session ending: it is closed only
|
|
551
|
+
when it has words. A final with no words still answers a flush.
|
|
552
|
+
"""
|
|
553
|
+
self._last_interim = ""
|
|
554
|
+
if self._usage_s:
|
|
555
|
+
self._event_ch.send_nowait(
|
|
556
|
+
stt.SpeechEvent(
|
|
557
|
+
type=stt.SpeechEventType.RECOGNITION_USAGE,
|
|
558
|
+
recognition_usage=stt.RecognitionUsage(audio_duration=self._usage_s),
|
|
559
|
+
)
|
|
560
|
+
)
|
|
561
|
+
self._usage_s = 0.0
|
|
562
|
+
if final or turn:
|
|
563
|
+
self._event_ch.send_nowait(
|
|
564
|
+
stt.SpeechEvent(
|
|
565
|
+
type=stt.SpeechEventType.FINAL_TRANSCRIPT,
|
|
566
|
+
alternatives=[_speech_data(turn)],
|
|
567
|
+
)
|
|
568
|
+
)
|
|
569
|
+
if self._in_turn:
|
|
570
|
+
self._in_turn = False
|
|
571
|
+
self._event_ch.send_nowait(stt.SpeechEvent(type=stt.SpeechEventType.END_OF_SPEECH))
|
|
572
|
+
|
|
573
|
+
|
|
574
|
+
def _speech_data(text: str) -> stt.SpeechData:
|
|
575
|
+
return stt.SpeechData(language=LanguageCode("en"), text=text)
|
|
576
|
+
|
|
577
|
+
|
|
578
|
+
def _error_message(body: Any) -> str:
|
|
579
|
+
error = body.get("error") if isinstance(body, dict) else None
|
|
580
|
+
if isinstance(error, dict):
|
|
581
|
+
return f"{error.get('code', 'error')}: {error.get('message', '')}"
|
|
582
|
+
return str(body)
|
|
583
|
+
|
|
584
|
+
|
|
585
|
+
def _session_error(data: dict[str, Any], close_code: int | None) -> APIStatusError:
|
|
586
|
+
code = str(data.get("code") or "error")
|
|
587
|
+
return APIStatusError(
|
|
588
|
+
f"AirCaps error {code}: {data.get('message', '')}",
|
|
589
|
+
status_code=close_code or -1,
|
|
590
|
+
body=data,
|
|
591
|
+
retryable=code not in _PERMANENT_ERRORS,
|
|
592
|
+
)
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Copyright 2026 AirCaps
|
|
2
|
+
#
|
|
3
|
+
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
4
|
+
# you may not use this file except in compliance with the License.
|
|
5
|
+
# You may obtain a copy of the License at
|
|
6
|
+
#
|
|
7
|
+
# http://www.apache.org/licenses/LICENSE-2.0
|
|
8
|
+
#
|
|
9
|
+
# Unless required by applicable law or agreed to in writing, software
|
|
10
|
+
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
11
|
+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
12
|
+
# See the License for the specific language governing permissions and
|
|
13
|
+
# limitations under the License.
|
|
14
|
+
|
|
15
|
+
__version__ = "0.1.0"
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: livekit-plugins-aircaps
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: AirCaps Live speech-to-text for LiveKit Agents
|
|
5
|
+
Project-URL: Homepage, https://aircaps.ai
|
|
6
|
+
Project-URL: Documentation, https://aircaps.ai/docs/guides/live-1
|
|
7
|
+
Project-URL: Repository, https://github.com/aircaps/livekit-plugins-aircaps
|
|
8
|
+
Project-URL: Issues, https://github.com/aircaps/livekit-plugins-aircaps/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/aircaps/livekit-plugins-aircaps/blob/main/CHANGELOG.md
|
|
10
|
+
Author: AirCaps
|
|
11
|
+
License-Expression: Apache-2.0
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: agents,aircaps,audio,livekit,realtime,speech-to-text,stt,webrtc
|
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
23
|
+
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
|
|
24
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
25
|
+
Classifier: Typing :: Typed
|
|
26
|
+
Requires-Python: >=3.10.0
|
|
27
|
+
Requires-Dist: livekit-agents<2,>=1.8.13
|
|
28
|
+
Provides-Extra: example
|
|
29
|
+
Requires-Dist: livekit-agents[silero]<2,>=1.8.13; extra == 'example'
|
|
30
|
+
Requires-Dist: python-dotenv; extra == 'example'
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
|
|
33
|
+
# livekit-plugins-aircaps
|
|
34
|
+
|
|
35
|
+
[](https://pypi.org/project/livekit-plugins-aircaps/)
|
|
36
|
+
[](https://github.com/aircaps/livekit-plugins-aircaps/actions/workflows/ci.yml)
|
|
37
|
+
|
|
38
|
+
[AirCaps](https://aircaps.ai) speech-to-text for [LiveKit Agents](https://github.com/livekit/agents).
|
|
39
|
+
|
|
40
|
+
`aircaps.STT` streams the user's audio to **AirCaps Live 1** (`aircaps-live-1`), a low-latency real-time English
|
|
41
|
+
speech-to-text model built for voice agents. It sends interim transcripts while the user speaks and the turn's final
|
|
42
|
+
transcript the moment the turn ends: when LiveKit's turn handling says so, or, with `end_of_turn=True`, when the model
|
|
43
|
+
detects it.
|
|
44
|
+
|
|
45
|
+
Maintained by AirCaps, the company that provides AirCaps Live 1.
|
|
46
|
+
|
|
47
|
+
## Installation
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
pip install livekit-plugins-aircaps
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
or `uv add livekit-plugins-aircaps`.
|
|
54
|
+
|
|
55
|
+
## Prerequisites
|
|
56
|
+
|
|
57
|
+
An AirCaps API key: sign in to the [AirCaps console](https://console.aircaps.ai), open **API keys** and create one.
|
|
58
|
+
AirCaps Live 1 is available to every account, one session at a time by default
|
|
59
|
+
([talk to us](https://aircaps.ai/contact) for more). The [AirCaps Live 1 guide](https://aircaps.ai/docs/guides/live-1)
|
|
60
|
+
describes the model and its protocol.
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
export AIRCAPS_API_KEY=...
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Usage
|
|
67
|
+
|
|
68
|
+
By default the session's own turn handling decides when the user has finished speaking. LiveKit flushes the stream
|
|
69
|
+
at the end of each turn (from its VAD or turn detector, or a manual commit), and the final transcript comes back right
|
|
70
|
+
away:
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
from livekit.agents import AgentSession
|
|
74
|
+
from livekit.plugins import aircaps, silero
|
|
75
|
+
|
|
76
|
+
session = AgentSession(
|
|
77
|
+
stt=aircaps.STT(),
|
|
78
|
+
vad=silero.VAD.load(),
|
|
79
|
+
# ... llm, tts, turn_handling, etc.
|
|
80
|
+
)
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Without a flush, words stay interim until the stream ends, so use a VAD (or a turn detector) in this mode.
|
|
84
|
+
|
|
85
|
+
### Model-detected end of turn
|
|
86
|
+
|
|
87
|
+
To let AirCaps detect the end of each turn instead, turn on `end_of_turn` and use the STT's turn detection. The
|
|
88
|
+
model's end of turn has already waited out the user's pause, so set LiveKit's own endpointing delay to 0 (its default
|
|
89
|
+
adds 0.5 s to every turn):
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
from livekit.agents import AgentSession, TurnHandlingOptions
|
|
93
|
+
from livekit.plugins import aircaps
|
|
94
|
+
|
|
95
|
+
session = AgentSession(
|
|
96
|
+
stt=aircaps.STT(end_of_turn=True, end_of_turn_mode="balanced"),
|
|
97
|
+
turn_handling=TurnHandlingOptions(turn_detection="stt", endpointing={"min_delay": 0}),
|
|
98
|
+
# ... llm, tts, vad, etc.
|
|
99
|
+
)
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Options
|
|
103
|
+
|
|
104
|
+
| Option | Default | |
|
|
105
|
+
| --- | --- | --- |
|
|
106
|
+
| `model` | `"aircaps-live-1"` | The AirCaps model |
|
|
107
|
+
| `end_of_turn` | `False` | Let the model detect the end of each turn |
|
|
108
|
+
| `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 |
|
|
109
|
+
| `end_of_turn_threshold` | the mode's | How sure the model must be that the turn ended, 0.2 to 0.9 |
|
|
110
|
+
| `min_turn_silence_ms` | the mode's | The shortest pause that can end a turn, 0 to 1000 ms |
|
|
111
|
+
| `max_turn_silence_ms` | the mode's | A pause this long always ends the turn, 500 to 5000 ms, or 0 for no limit |
|
|
112
|
+
| `vad_threshold` | the mode's | How sure the model's voice detector must be that a sound is speech, 0.3 to 0.9 |
|
|
113
|
+
| `api_key` | `AIRCAPS_API_KEY` | AirCaps API key |
|
|
114
|
+
| `base_url` | `"https://api.aircaps.com"` | AirCaps API address |
|
|
115
|
+
| `http_session` | LiveKit's shared session | An `aiohttp.ClientSession` to use |
|
|
116
|
+
|
|
117
|
+
`stt.update_options(...)` changes the end-of-turn settings, also for streams already open.
|
|
118
|
+
|
|
119
|
+
Audio is resampled to 16 kHz mono. The model transcribes English and supports streaming recognition only; key terms
|
|
120
|
+
and speaker labels are not available.
|
|
121
|
+
|
|
122
|
+
How it works:
|
|
123
|
+
|
|
124
|
+
- Before each session the plugin asks the AirCaps API where to connect
|
|
125
|
+
(`GET /v1/realtime/endpoint?model=aircaps-live-1`), then opens that WebSocket, so audio goes to the nearest server.
|
|
126
|
+
- A flush sends `finalize`; the turn's final transcript comes straight back.
|
|
127
|
+
- A dropped or ended session (sessions last up to an hour) is reopened, with a new address lookup. A turn cut short by
|
|
128
|
+
the drop ends with its text so far.
|
|
129
|
+
|
|
130
|
+
## Running the example
|
|
131
|
+
|
|
132
|
+
[`examples/agent.py`](examples/agent.py) is LiveKit's basic voice agent with AirCaps as its speech-to-text (the LLM
|
|
133
|
+
and the voice come from LiveKit Inference).
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
git clone https://github.com/aircaps/livekit-plugins-aircaps.git
|
|
137
|
+
cd livekit-plugins-aircaps
|
|
138
|
+
cp .env.example .env # add AIRCAPS_API_KEY and your LiveKit project's URL, key and secret
|
|
139
|
+
uv sync --extra example
|
|
140
|
+
uv run examples/agent.py console
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
`console` runs the agent in your terminal with your microphone and speakers; `dev` connects it to your LiveKit
|
|
144
|
+
project. `AIRCAPS_END_OF_TURN=1` switches it to model-detected end of turn.
|
|
145
|
+
|
|
146
|
+
## Tests
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
uv sync
|
|
150
|
+
uv run pytest
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
The tests run against a local fake of the AirCaps API; no key is needed.
|
|
154
|
+
|
|
155
|
+
## Compatibility
|
|
156
|
+
|
|
157
|
+
Tested with LiveKit Agents 1.8.13, on Python 3.10 to 3.13.
|
|
158
|
+
|
|
159
|
+
## Support
|
|
160
|
+
|
|
161
|
+
Open an [issue](https://github.com/aircaps/livekit-plugins-aircaps/issues), or [contact AirCaps](https://aircaps.ai/contact).
|
|
162
|
+
|
|
163
|
+
## License
|
|
164
|
+
|
|
165
|
+
Apache 2.0, see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
livekit/plugins/aircaps/__init__.py,sha256=BtgYOOcrHXUrZYJ17NcwLaq_n16tXypaHAFyqBXNUI4,1282
|
|
2
|
+
livekit/plugins/aircaps/log.py,sha256=ow_-A9_1WMvFe7yq7r5PliqBF2yOG5SA775UyTcZSR4,70
|
|
3
|
+
livekit/plugins/aircaps/models.py,sha256=104faWTxu9QMLAZNrumCFkyEprVfjbhywmZtzfbpt3A,706
|
|
4
|
+
livekit/plugins/aircaps/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
5
|
+
livekit/plugins/aircaps/stt.py,sha256=q4gQ94lmJ54eJ6VLRaNI5igOL_FdzH8rx_0lDRkVdRY,23858
|
|
6
|
+
livekit/plugins/aircaps/version.py,sha256=78A_h3zxBFL8I3S4faER0gUB0UeWNc3L4kySRJWJU-s,594
|
|
7
|
+
livekit_plugins_aircaps-0.1.0.dist-info/METADATA,sha256=X7mxsqSH-s5fh_wJQIFZC9_IDw2bbTrh8rue0zArfYM,6706
|
|
8
|
+
livekit_plugins_aircaps-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
9
|
+
livekit_plugins_aircaps-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
|
|
10
|
+
livekit_plugins_aircaps-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
Apache License
|
|
3
|
+
Version 2.0, January 2004
|
|
4
|
+
http://www.apache.org/licenses/
|
|
5
|
+
|
|
6
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
7
|
+
|
|
8
|
+
1. Definitions.
|
|
9
|
+
|
|
10
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
11
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
12
|
+
|
|
13
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
14
|
+
the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
17
|
+
other entities that control, are controlled by, or are under common
|
|
18
|
+
control with that entity. For the purposes of this definition,
|
|
19
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
20
|
+
direction or management of such entity, whether by contract or
|
|
21
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
23
|
+
|
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
25
|
+
exercising permissions granted by this License.
|
|
26
|
+
|
|
27
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
28
|
+
including but not limited to software source code, documentation
|
|
29
|
+
source, and configuration files.
|
|
30
|
+
|
|
31
|
+
"Object" form shall mean any form resulting from mechanical
|
|
32
|
+
transformation or translation of a Source form, including but
|
|
33
|
+
not limited to compiled object code, generated documentation,
|
|
34
|
+
and conversions to other media types.
|
|
35
|
+
|
|
36
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
37
|
+
Object form, made available under the License, as indicated by a
|
|
38
|
+
copyright notice that is included in or attached to the work
|
|
39
|
+
(an example is provided in the Appendix below).
|
|
40
|
+
|
|
41
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
42
|
+
form, that is based on (or derived from) the Work and for which the
|
|
43
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
44
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
45
|
+
of this License, Derivative Works shall not include works that remain
|
|
46
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
47
|
+
the Work and Derivative Works thereof.
|
|
48
|
+
|
|
49
|
+
"Contribution" shall mean any work of authorship, including
|
|
50
|
+
the original version of the Work and any modifications or additions
|
|
51
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
52
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
53
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
54
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
55
|
+
means any form of electronic, verbal, or written communication sent
|
|
56
|
+
to the Licensor or its representatives, including but not limited to
|
|
57
|
+
communication on electronic mailing lists, source code control systems,
|
|
58
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
59
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
60
|
+
excluding communication that is conspicuously marked or otherwise
|
|
61
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
62
|
+
|
|
63
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
64
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
65
|
+
subsequently incorporated within the Work.
|
|
66
|
+
|
|
67
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
68
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
69
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
70
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
71
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
72
|
+
Work and such Derivative Works in Source or Object form.
|
|
73
|
+
|
|
74
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
75
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
76
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
77
|
+
(except as stated in this section) patent license to make, have made,
|
|
78
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
79
|
+
where such license applies only to those patent claims licensable
|
|
80
|
+
by such Contributor that are necessarily infringed by their
|
|
81
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
82
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
83
|
+
institute patent litigation against any entity (including a
|
|
84
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
85
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
86
|
+
or contributory patent infringement, then any patent licenses
|
|
87
|
+
granted to You under this License for that Work shall terminate
|
|
88
|
+
as of the date such litigation is filed.
|
|
89
|
+
|
|
90
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
91
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
92
|
+
modifications, and in Source or Object form, provided that You
|
|
93
|
+
meet the following conditions:
|
|
94
|
+
|
|
95
|
+
(a) You must give any other recipients of the Work or
|
|
96
|
+
Derivative Works a copy of this License; and
|
|
97
|
+
|
|
98
|
+
(b) You must cause any modified files to carry prominent notices
|
|
99
|
+
stating that You changed the files; and
|
|
100
|
+
|
|
101
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
102
|
+
that You distribute, all copyright, patent, trademark, and
|
|
103
|
+
attribution notices from the Source form of the Work,
|
|
104
|
+
excluding those notices that do not pertain to any part of
|
|
105
|
+
the Derivative Works; and
|
|
106
|
+
|
|
107
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
108
|
+
distribution, then any Derivative Works that You distribute must
|
|
109
|
+
include a readable copy of the attribution notices contained
|
|
110
|
+
within such NOTICE file, excluding those notices that do not
|
|
111
|
+
pertain to any part of the Derivative Works, in at least one
|
|
112
|
+
of the following places: within a NOTICE text file distributed
|
|
113
|
+
as part of the Derivative Works; within the Source form or
|
|
114
|
+
documentation, if provided along with the Derivative Works; or,
|
|
115
|
+
within a display generated by the Derivative Works, if and
|
|
116
|
+
wherever such third-party notices normally appear. The contents
|
|
117
|
+
of the NOTICE file are for informational purposes only and
|
|
118
|
+
do not modify the License. You may add Your own attribution
|
|
119
|
+
notices within Derivative Works that You distribute, alongside
|
|
120
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
121
|
+
that such additional attribution notices cannot be construed
|
|
122
|
+
as modifying the License.
|
|
123
|
+
|
|
124
|
+
You may add Your own copyright statement to Your modifications and
|
|
125
|
+
may provide additional or different license terms and conditions
|
|
126
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
127
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
128
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
129
|
+
the conditions stated in this License.
|
|
130
|
+
|
|
131
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
132
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
133
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
134
|
+
this License, without any additional terms or conditions.
|
|
135
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
136
|
+
the terms of any separate license agreement you may have executed
|
|
137
|
+
with Licensor regarding such Contributions.
|
|
138
|
+
|
|
139
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
140
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
141
|
+
except as required for reasonable and customary use in describing the
|
|
142
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
143
|
+
|
|
144
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
145
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
146
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
147
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
148
|
+
implied, including, without limitation, any warranties or conditions
|
|
149
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
150
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
151
|
+
appropriateness of using or redistributing the Work and assume any
|
|
152
|
+
risks associated with Your exercise of permissions under this License.
|
|
153
|
+
|
|
154
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
155
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
156
|
+
unless required by applicable law (such as deliberate and grossly
|
|
157
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
158
|
+
liable to You for damages, including any direct, indirect, special,
|
|
159
|
+
incidental, or consequential damages of any character arising as a
|
|
160
|
+
result of this License or out of the use or inability to use the
|
|
161
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
162
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
163
|
+
other commercial damages or losses), even if such Contributor
|
|
164
|
+
has been advised of the possibility of such damages.
|
|
165
|
+
|
|
166
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
167
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
168
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
169
|
+
or other liability obligations and/or rights consistent with this
|
|
170
|
+
License. However, in accepting such obligations, You may act only
|
|
171
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
172
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
173
|
+
defend, and hold each Contributor harmless for any liability
|
|
174
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
175
|
+
of your accepting any such warranty or additional liability.
|
|
176
|
+
|
|
177
|
+
END OF TERMS AND CONDITIONS
|
|
178
|
+
|
|
179
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
180
|
+
|
|
181
|
+
To apply the Apache License to your work, attach the following
|
|
182
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
183
|
+
replaced with your own identifying information. (Don't include
|
|
184
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
185
|
+
comment syntax for the file format. We also recommend that a
|
|
186
|
+
file or class name and description of purpose be included on the
|
|
187
|
+
same "printed page" as the copyright notice for easier
|
|
188
|
+
identification within third-party archives.
|
|
189
|
+
|
|
190
|
+
Copyright [yyyy] [name of copyright owner]
|
|
191
|
+
|
|
192
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
193
|
+
you may not use this file except in compliance with the License.
|
|
194
|
+
You may obtain a copy of the License at
|
|
195
|
+
|
|
196
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
197
|
+
|
|
198
|
+
Unless required by applicable law or agreed to in writing, software
|
|
199
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
200
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
201
|
+
See the License for the specific language governing permissions and
|
|
202
|
+
limitations under the License.
|