pipecat-aircaps 0.1.0__tar.gz
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.
- pipecat_aircaps-0.1.0/.gitignore +10 -0
- pipecat_aircaps-0.1.0/CHANGELOG.md +30 -0
- pipecat_aircaps-0.1.0/LICENSE +24 -0
- pipecat_aircaps-0.1.0/PKG-INFO +181 -0
- pipecat_aircaps-0.1.0/README.md +150 -0
- pipecat_aircaps-0.1.0/examples/voice-agent.py +118 -0
- pipecat_aircaps-0.1.0/pyproject.toml +68 -0
- pipecat_aircaps-0.1.0/src/pipecat_aircaps/__init__.py +11 -0
- pipecat_aircaps-0.1.0/src/pipecat_aircaps/py.typed +0 -0
- pipecat_aircaps-0.1.0/src/pipecat_aircaps/stt.py +582 -0
- pipecat_aircaps-0.1.0/tests/test_stt.py +494 -0
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here. The format follows
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
|
|
5
|
+
[Semantic Versioning](https://semver.org/).
|
|
6
|
+
|
|
7
|
+
## [Unreleased]
|
|
8
|
+
|
|
9
|
+
## [0.1.0] - 2026-11-19
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- `AirCapsLiveSTTService`: streaming speech-to-text with AirCaps Live 1 (`aircaps-live-1`). Interim transcripts while
|
|
14
|
+
the user speaks; a final transcript per turn, asked for when VAD reports the end of speech; endpoint lookup before
|
|
15
|
+
each connection; automatic reconnection; keepalive pings while no audio is sent.
|
|
16
|
+
- `end_of_turn=True`: the model detects the end of each turn. The service pushes
|
|
17
|
+
`ProposedUserStartedSpeakingFrame` / `ProposedUserStoppedSpeakingFrame` around each turn's final transcript and
|
|
18
|
+
recommends `ExternalUserTurnStrategies`. A new turn's first transcript waits (up to 0.5 s) until Pipecat has started
|
|
19
|
+
the turn. `end_of_turn_mode` setting (`min_latency`, `balanced`, `max_accuracy`), and `end_of_turn_threshold`,
|
|
20
|
+
`min_turn_silence_ms`, `max_turn_silence_ms`, `vad_threshold` to override single values of the mode.
|
|
21
|
+
- Words VAD did not hear are finalized one second after the last new words, so the user turn they started ends.
|
|
22
|
+
- Text that is only punctuation is never pushed; punctuation that closes the previous turn is not repeated at the
|
|
23
|
+
start of the next one.
|
|
24
|
+
- Foundational example `examples/voice-agent.py`.
|
|
25
|
+
- Tests against a local fake of the AirCaps API.
|
|
26
|
+
|
|
27
|
+
Tested with Pipecat v1.16.0.
|
|
28
|
+
|
|
29
|
+
[Unreleased]: https://github.com/aircaps/pipecat-aircaps/compare/v0.1.0...HEAD
|
|
30
|
+
[0.1.0]: https://github.com/aircaps/pipecat-aircaps/releases/tag/v0.1.0
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
BSD 2-Clause License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026, AirCaps
|
|
4
|
+
|
|
5
|
+
Redistribution and use in source and binary forms, with or without
|
|
6
|
+
modification, are permitted provided that the following conditions are met:
|
|
7
|
+
|
|
8
|
+
1. Redistributions of source code must retain the above copyright notice, this
|
|
9
|
+
list of conditions and the following disclaimer.
|
|
10
|
+
|
|
11
|
+
2. Redistributions in binary form must reproduce the above copyright notice,
|
|
12
|
+
this list of conditions and the following disclaimer in the documentation
|
|
13
|
+
and/or other materials provided with the distribution.
|
|
14
|
+
|
|
15
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
16
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
17
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
18
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
19
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
20
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
21
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
22
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
23
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
24
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: pipecat-aircaps
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: AirCaps Live speech-to-text for Pipecat voice 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/pipecat-aircaps
|
|
8
|
+
Project-URL: Issues, https://github.com/aircaps/pipecat-aircaps/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/aircaps/pipecat-aircaps/blob/main/CHANGELOG.md
|
|
10
|
+
Author: AirCaps
|
|
11
|
+
License-Expression: BSD-2-Clause
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: aircaps,pipecat,realtime,speech-to-text,stt,voice-agents
|
|
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.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
|
|
23
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
24
|
+
Classifier: Typing :: Typed
|
|
25
|
+
Requires-Python: >=3.11
|
|
26
|
+
Requires-Dist: pipecat-ai<2,>=1.16.0
|
|
27
|
+
Provides-Extra: example
|
|
28
|
+
Requires-Dist: pipecat-ai[cartesia,openai,runner,silero,webrtc]<2,>=1.16.0; extra == 'example'
|
|
29
|
+
Requires-Dist: python-dotenv; extra == 'example'
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
# pipecat-aircaps
|
|
33
|
+
|
|
34
|
+
[](https://pypi.org/project/pipecat-aircaps/)
|
|
35
|
+
[](https://github.com/aircaps/pipecat-aircaps/actions/workflows/ci.yml)
|
|
36
|
+
|
|
37
|
+
[AirCaps](https://aircaps.ai) speech-to-text for [Pipecat](https://github.com/pipecat-ai/pipecat).
|
|
38
|
+
|
|
39
|
+
`AirCapsLiveSTTService` streams the user's audio to **AirCaps Live 1** (`aircaps-live-1`), a low-latency English
|
|
40
|
+
speech-to-text model built for voice agents. It pushes interim transcripts while the user speaks, and when VAD
|
|
41
|
+
reports the end of speech it asks for the turn's final transcript at once. It can also let the model decide when each
|
|
42
|
+
turn ends (`end_of_turn=True`).
|
|
43
|
+
|
|
44
|
+
Maintained by AirCaps, the company that provides AirCaps Live 1. This is a Pipecat community integration.
|
|
45
|
+
|
|
46
|
+
## Installation
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
uv add pipecat-aircaps
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
or `pip install pipecat-aircaps`.
|
|
53
|
+
|
|
54
|
+
## Prerequisites
|
|
55
|
+
|
|
56
|
+
An AirCaps API key: sign in to the [AirCaps console](https://console.aircaps.ai), open **API keys** and create one.
|
|
57
|
+
AirCaps Live 1 is available to every account, one session at a time by default
|
|
58
|
+
([talk to us](https://aircaps.ai/contact) for more). The [AirCaps Live 1 guide](https://aircaps.ai/docs/guides/live-1)
|
|
59
|
+
describes the model and its protocol.
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
export AIRCAPS_API_KEY=...
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Usage
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
import os
|
|
69
|
+
|
|
70
|
+
from pipecat_aircaps import AirCapsLiveSTTService
|
|
71
|
+
|
|
72
|
+
stt = AirCapsLiveSTTService(api_key=os.environ["AIRCAPS_API_KEY"])
|
|
73
|
+
|
|
74
|
+
pipeline = Pipeline(
|
|
75
|
+
[
|
|
76
|
+
transport.input(),
|
|
77
|
+
stt,
|
|
78
|
+
user_aggregator,
|
|
79
|
+
llm,
|
|
80
|
+
tts,
|
|
81
|
+
transport.output(),
|
|
82
|
+
assistant_aggregator,
|
|
83
|
+
]
|
|
84
|
+
)
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Use it as you would any Pipecat STT service. It needs VAD frames to know when a turn ends, which the user aggregator
|
|
88
|
+
provides when it has a VAD analyzer (`LLMUserAggregatorParams(vad_analyzer=SileroVADAnalyzer())`), as in the example.
|
|
89
|
+
|
|
90
|
+
| Parameter | Default | |
|
|
91
|
+
| --- | --- | --- |
|
|
92
|
+
| `api_key` | required | AirCaps API key |
|
|
93
|
+
| `base_url` | `https://api.aircaps.com` | AirCaps API address |
|
|
94
|
+
| `sample_rate` | pipeline input rate | Input audio rate. Audio is resampled to 16 kHz before it is sent |
|
|
95
|
+
| `end_of_turn` | `False` | Let the model detect the end of each turn (see below) |
|
|
96
|
+
| `should_interrupt` | `True` | With `end_of_turn`: whether a new user turn interrupts the bot |
|
|
97
|
+
| `settings` | `model="aircaps-live-1"`, `language=Language.EN`, `end_of_turn_mode="balanced"` | `AirCapsLiveSTTService.Settings(...)` |
|
|
98
|
+
| `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](https://github.com/pipecat-ai/stt-benchmark) |
|
|
99
|
+
|
|
100
|
+
How it works:
|
|
101
|
+
|
|
102
|
+
- Before each connection the service asks `GET /v1/realtime/endpoint?model=aircaps-live-1` where to connect, then
|
|
103
|
+
opens that WebSocket, so audio goes straight to the model.
|
|
104
|
+
- On `VADUserStoppedSpeakingFrame` it sends `finalize`; the final transcript of the turn comes back as one
|
|
105
|
+
`TranscriptionFrame`, marked finalized, and Pipecat reports STT TTFB from it.
|
|
106
|
+
- If words arrive that VAD did not hear (a short or quiet word), the service asks for their final itself one second
|
|
107
|
+
after the last new words, so the user turn they started still ends.
|
|
108
|
+
- A session the server ends (sessions last up to an hour) is reopened automatically.
|
|
109
|
+
- While no audio is sent (for example when the STT is muted), the service pings the session so it stays open.
|
|
110
|
+
|
|
111
|
+
## Model-detected end of turn
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
stt = AirCapsLiveSTTService(
|
|
115
|
+
api_key=os.environ["AIRCAPS_API_KEY"],
|
|
116
|
+
end_of_turn=True,
|
|
117
|
+
settings=AirCapsLiveSTTService.Settings(end_of_turn_mode="balanced"),
|
|
118
|
+
)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
With `end_of_turn=True` the model decides when the user has finished, instead of Pipecat's VAD and turn analyzer:
|
|
122
|
+
|
|
123
|
+
- When a turn's first words arrive, the service pushes `ProposedUserStartedSpeakingFrame`.
|
|
124
|
+
- When the model ends the turn, it pushes the turn's final `TranscriptionFrame` (finalized), then
|
|
125
|
+
`ProposedUserStoppedSpeakingFrame`.
|
|
126
|
+
- The service recommends `ExternalUserTurnStrategies`, so the user aggregator follows these frames. You don't need a
|
|
127
|
+
VAD analyzer in the user aggregator for turn ends. If you pass your own `user_turn_strategies`, they win.
|
|
128
|
+
|
|
129
|
+
`end_of_turn_mode` trades speed for certainty: `min_latency`, `balanced` (default) or `max_accuracy`. These settings
|
|
130
|
+
override single values of the mode (leave them unset to keep the mode's):
|
|
131
|
+
|
|
132
|
+
| Setting | Range | `min_latency` / `balanced` / `max_accuracy` |
|
|
133
|
+
| --- | --- | --- |
|
|
134
|
+
| `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 |
|
|
135
|
+
| `min_turn_silence_ms` | 0 to 1000: the shortest pause that can end a turn | 40 / 80 / 400 |
|
|
136
|
+
| `max_turn_silence_ms` | 500 to 5000, or 0 for no limit: a pause this long always ends the turn | 2560 |
|
|
137
|
+
| `vad_threshold` | 0.3 to 0.9: how sure the model's voice detector must be that it hears speech | |
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
settings = AirCapsLiveSTTService.Settings(end_of_turn_mode="balanced", min_turn_silence_ms=300)
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
All of them can be changed with `STTUpdateSettingsFrame`; the session reopens to apply them.
|
|
144
|
+
|
|
145
|
+
Not supported by AirCaps Live 1: languages other than English, key terms, speaker labels.
|
|
146
|
+
|
|
147
|
+
## Running the example
|
|
148
|
+
|
|
149
|
+
[`examples/voice-agent.py`](examples/voice-agent.py) is Pipecat's standard voice agent (OpenAI LLM, Cartesia voice)
|
|
150
|
+
with AirCaps as its speech-to-text.
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
git clone https://github.com/aircaps/pipecat-aircaps.git
|
|
154
|
+
cd pipecat-aircaps
|
|
155
|
+
cp .env.example .env # add AIRCAPS_API_KEY, OPENAI_API_KEY, CARTESIA_API_KEY
|
|
156
|
+
uv sync --extra example
|
|
157
|
+
uv run examples/voice-agent.py
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Open http://localhost:7860/client and talk to it.
|
|
161
|
+
|
|
162
|
+
## Tests
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
uv sync
|
|
166
|
+
uv run pytest
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
The tests run against a local fake of the AirCaps API; no key is needed.
|
|
170
|
+
|
|
171
|
+
## Compatibility
|
|
172
|
+
|
|
173
|
+
Tested with Pipecat v1.16.0, on Python 3.11, 3.12 and 3.13.
|
|
174
|
+
|
|
175
|
+
## Support
|
|
176
|
+
|
|
177
|
+
Open an [issue](https://github.com/aircaps/pipecat-aircaps/issues), or [contact AirCaps](https://aircaps.ai/contact).
|
|
178
|
+
|
|
179
|
+
## License
|
|
180
|
+
|
|
181
|
+
BSD 2-Clause, see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# pipecat-aircaps
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/pipecat-aircaps/)
|
|
4
|
+
[](https://github.com/aircaps/pipecat-aircaps/actions/workflows/ci.yml)
|
|
5
|
+
|
|
6
|
+
[AirCaps](https://aircaps.ai) speech-to-text for [Pipecat](https://github.com/pipecat-ai/pipecat).
|
|
7
|
+
|
|
8
|
+
`AirCapsLiveSTTService` streams the user's audio to **AirCaps Live 1** (`aircaps-live-1`), a low-latency English
|
|
9
|
+
speech-to-text model built for voice agents. It pushes interim transcripts while the user speaks, and when VAD
|
|
10
|
+
reports the end of speech it asks for the turn's final transcript at once. It can also let the model decide when each
|
|
11
|
+
turn ends (`end_of_turn=True`).
|
|
12
|
+
|
|
13
|
+
Maintained by AirCaps, the company that provides AirCaps Live 1. This is a Pipecat community integration.
|
|
14
|
+
|
|
15
|
+
## Installation
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
uv add pipecat-aircaps
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
or `pip install pipecat-aircaps`.
|
|
22
|
+
|
|
23
|
+
## Prerequisites
|
|
24
|
+
|
|
25
|
+
An AirCaps API key: sign in to the [AirCaps console](https://console.aircaps.ai), open **API keys** and create one.
|
|
26
|
+
AirCaps Live 1 is available to every account, one session at a time by default
|
|
27
|
+
([talk to us](https://aircaps.ai/contact) for more). The [AirCaps Live 1 guide](https://aircaps.ai/docs/guides/live-1)
|
|
28
|
+
describes the model and its protocol.
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
export AIRCAPS_API_KEY=...
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Usage
|
|
35
|
+
|
|
36
|
+
```python
|
|
37
|
+
import os
|
|
38
|
+
|
|
39
|
+
from pipecat_aircaps import AirCapsLiveSTTService
|
|
40
|
+
|
|
41
|
+
stt = AirCapsLiveSTTService(api_key=os.environ["AIRCAPS_API_KEY"])
|
|
42
|
+
|
|
43
|
+
pipeline = Pipeline(
|
|
44
|
+
[
|
|
45
|
+
transport.input(),
|
|
46
|
+
stt,
|
|
47
|
+
user_aggregator,
|
|
48
|
+
llm,
|
|
49
|
+
tts,
|
|
50
|
+
transport.output(),
|
|
51
|
+
assistant_aggregator,
|
|
52
|
+
]
|
|
53
|
+
)
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Use it as you would any Pipecat STT service. It needs VAD frames to know when a turn ends, which the user aggregator
|
|
57
|
+
provides when it has a VAD analyzer (`LLMUserAggregatorParams(vad_analyzer=SileroVADAnalyzer())`), as in the example.
|
|
58
|
+
|
|
59
|
+
| Parameter | Default | |
|
|
60
|
+
| --- | --- | --- |
|
|
61
|
+
| `api_key` | required | AirCaps API key |
|
|
62
|
+
| `base_url` | `https://api.aircaps.com` | AirCaps API address |
|
|
63
|
+
| `sample_rate` | pipeline input rate | Input audio rate. Audio is resampled to 16 kHz before it is sent |
|
|
64
|
+
| `end_of_turn` | `False` | Let the model detect the end of each turn (see below) |
|
|
65
|
+
| `should_interrupt` | `True` | With `end_of_turn`: whether a new user turn interrupts the bot |
|
|
66
|
+
| `settings` | `model="aircaps-live-1"`, `language=Language.EN`, `end_of_turn_mode="balanced"` | `AirCapsLiveSTTService.Settings(...)` |
|
|
67
|
+
| `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](https://github.com/pipecat-ai/stt-benchmark) |
|
|
68
|
+
|
|
69
|
+
How it works:
|
|
70
|
+
|
|
71
|
+
- Before each connection the service asks `GET /v1/realtime/endpoint?model=aircaps-live-1` where to connect, then
|
|
72
|
+
opens that WebSocket, so audio goes straight to the model.
|
|
73
|
+
- On `VADUserStoppedSpeakingFrame` it sends `finalize`; the final transcript of the turn comes back as one
|
|
74
|
+
`TranscriptionFrame`, marked finalized, and Pipecat reports STT TTFB from it.
|
|
75
|
+
- If words arrive that VAD did not hear (a short or quiet word), the service asks for their final itself one second
|
|
76
|
+
after the last new words, so the user turn they started still ends.
|
|
77
|
+
- A session the server ends (sessions last up to an hour) is reopened automatically.
|
|
78
|
+
- While no audio is sent (for example when the STT is muted), the service pings the session so it stays open.
|
|
79
|
+
|
|
80
|
+
## Model-detected end of turn
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
stt = AirCapsLiveSTTService(
|
|
84
|
+
api_key=os.environ["AIRCAPS_API_KEY"],
|
|
85
|
+
end_of_turn=True,
|
|
86
|
+
settings=AirCapsLiveSTTService.Settings(end_of_turn_mode="balanced"),
|
|
87
|
+
)
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
With `end_of_turn=True` the model decides when the user has finished, instead of Pipecat's VAD and turn analyzer:
|
|
91
|
+
|
|
92
|
+
- When a turn's first words arrive, the service pushes `ProposedUserStartedSpeakingFrame`.
|
|
93
|
+
- When the model ends the turn, it pushes the turn's final `TranscriptionFrame` (finalized), then
|
|
94
|
+
`ProposedUserStoppedSpeakingFrame`.
|
|
95
|
+
- The service recommends `ExternalUserTurnStrategies`, so the user aggregator follows these frames. You don't need a
|
|
96
|
+
VAD analyzer in the user aggregator for turn ends. If you pass your own `user_turn_strategies`, they win.
|
|
97
|
+
|
|
98
|
+
`end_of_turn_mode` trades speed for certainty: `min_latency`, `balanced` (default) or `max_accuracy`. These settings
|
|
99
|
+
override single values of the mode (leave them unset to keep the mode's):
|
|
100
|
+
|
|
101
|
+
| Setting | Range | `min_latency` / `balanced` / `max_accuracy` |
|
|
102
|
+
| --- | --- | --- |
|
|
103
|
+
| `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 |
|
|
104
|
+
| `min_turn_silence_ms` | 0 to 1000: the shortest pause that can end a turn | 40 / 80 / 400 |
|
|
105
|
+
| `max_turn_silence_ms` | 500 to 5000, or 0 for no limit: a pause this long always ends the turn | 2560 |
|
|
106
|
+
| `vad_threshold` | 0.3 to 0.9: how sure the model's voice detector must be that it hears speech | |
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
settings = AirCapsLiveSTTService.Settings(end_of_turn_mode="balanced", min_turn_silence_ms=300)
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
All of them can be changed with `STTUpdateSettingsFrame`; the session reopens to apply them.
|
|
113
|
+
|
|
114
|
+
Not supported by AirCaps Live 1: languages other than English, key terms, speaker labels.
|
|
115
|
+
|
|
116
|
+
## Running the example
|
|
117
|
+
|
|
118
|
+
[`examples/voice-agent.py`](examples/voice-agent.py) is Pipecat's standard voice agent (OpenAI LLM, Cartesia voice)
|
|
119
|
+
with AirCaps as its speech-to-text.
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
git clone https://github.com/aircaps/pipecat-aircaps.git
|
|
123
|
+
cd pipecat-aircaps
|
|
124
|
+
cp .env.example .env # add AIRCAPS_API_KEY, OPENAI_API_KEY, CARTESIA_API_KEY
|
|
125
|
+
uv sync --extra example
|
|
126
|
+
uv run examples/voice-agent.py
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Open http://localhost:7860/client and talk to it.
|
|
130
|
+
|
|
131
|
+
## Tests
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
uv sync
|
|
135
|
+
uv run pytest
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
The tests run against a local fake of the AirCaps API; no key is needed.
|
|
139
|
+
|
|
140
|
+
## Compatibility
|
|
141
|
+
|
|
142
|
+
Tested with Pipecat v1.16.0, on Python 3.11, 3.12 and 3.13.
|
|
143
|
+
|
|
144
|
+
## Support
|
|
145
|
+
|
|
146
|
+
Open an [issue](https://github.com/aircaps/pipecat-aircaps/issues), or [contact AirCaps](https://aircaps.ai/contact).
|
|
147
|
+
|
|
148
|
+
## License
|
|
149
|
+
|
|
150
|
+
BSD 2-Clause, see [LICENSE](LICENSE).
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
#
|
|
2
|
+
# Copyright (c) 2026, AirCaps
|
|
3
|
+
#
|
|
4
|
+
# SPDX-License-Identifier: BSD 2-Clause License
|
|
5
|
+
#
|
|
6
|
+
|
|
7
|
+
"""A voice agent that listens with AirCaps Live 1.
|
|
8
|
+
|
|
9
|
+
The usual Pipecat voice agent (see Pipecat's examples/getting-started/06-voice-agent.py)
|
|
10
|
+
with AirCaps as its speech-to-text.
|
|
11
|
+
|
|
12
|
+
uv run examples/voice-agent.py
|
|
13
|
+
|
|
14
|
+
then open http://localhost:7860/client and talk to it.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
import os
|
|
18
|
+
|
|
19
|
+
from dotenv import load_dotenv
|
|
20
|
+
from loguru import logger
|
|
21
|
+
from pipecat.audio.vad.silero import SileroVADAnalyzer
|
|
22
|
+
from pipecat.evals.transport import EvalTransportParams
|
|
23
|
+
from pipecat.frames.frames import LLMRunFrame
|
|
24
|
+
from pipecat.pipeline.pipeline import Pipeline
|
|
25
|
+
from pipecat.pipeline.worker import PipelineParams, PipelineWorker, ProcessorUnusablePolicy
|
|
26
|
+
from pipecat.processors.aggregators.llm_context import LLMContext
|
|
27
|
+
from pipecat.processors.aggregators.llm_response_universal import (
|
|
28
|
+
LLMContextAggregatorPair,
|
|
29
|
+
LLMUserAggregatorParams,
|
|
30
|
+
)
|
|
31
|
+
from pipecat.runner.types import RunnerArguments
|
|
32
|
+
from pipecat.runner.utils import create_transport
|
|
33
|
+
from pipecat.services.cartesia.tts import CartesiaTTSService
|
|
34
|
+
from pipecat.services.openai.llm import OpenAILLMService
|
|
35
|
+
from pipecat.transports.base_transport import BaseTransport, TransportParams
|
|
36
|
+
from pipecat.workers.runner import WorkerRunner
|
|
37
|
+
|
|
38
|
+
from pipecat_aircaps import AirCapsLiveSTTService
|
|
39
|
+
|
|
40
|
+
load_dotenv(override=True)
|
|
41
|
+
|
|
42
|
+
transport_params = {
|
|
43
|
+
"eval": lambda: EvalTransportParams(audio_in_enabled=True, audio_out_enabled=True),
|
|
44
|
+
"webrtc": lambda: TransportParams(audio_in_enabled=True, audio_out_enabled=True),
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
async def run_bot(transport: BaseTransport, runner_args: RunnerArguments):
|
|
49
|
+
logger.info("Starting bot")
|
|
50
|
+
|
|
51
|
+
stt = AirCapsLiveSTTService(api_key=os.environ["AIRCAPS_API_KEY"])
|
|
52
|
+
|
|
53
|
+
tts = CartesiaTTSService(
|
|
54
|
+
api_key=os.environ["CARTESIA_API_KEY"],
|
|
55
|
+
settings=CartesiaTTSService.Settings(voice="86e30c1d-714b-4074-a1f2-1cb6b552fb49"),
|
|
56
|
+
)
|
|
57
|
+
|
|
58
|
+
llm = OpenAILLMService(
|
|
59
|
+
api_key=os.environ["OPENAI_API_KEY"],
|
|
60
|
+
settings=OpenAILLMService.Settings(
|
|
61
|
+
system_instruction="You are a helpful assistant in a voice conversation. Your responses will be spoken aloud, so avoid emojis, bullet points, or other formatting that can't be spoken. Respond to what the user said in a creative, helpful, and brief way.",
|
|
62
|
+
),
|
|
63
|
+
)
|
|
64
|
+
|
|
65
|
+
context = LLMContext()
|
|
66
|
+
user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
|
|
67
|
+
context,
|
|
68
|
+
user_params=LLMUserAggregatorParams(vad_analyzer=SileroVADAnalyzer()),
|
|
69
|
+
)
|
|
70
|
+
|
|
71
|
+
pipeline = Pipeline(
|
|
72
|
+
[
|
|
73
|
+
transport.input(),
|
|
74
|
+
stt,
|
|
75
|
+
user_aggregator,
|
|
76
|
+
llm,
|
|
77
|
+
tts,
|
|
78
|
+
transport.output(),
|
|
79
|
+
assistant_aggregator,
|
|
80
|
+
]
|
|
81
|
+
)
|
|
82
|
+
|
|
83
|
+
worker = PipelineWorker(
|
|
84
|
+
pipeline,
|
|
85
|
+
params=PipelineParams(enable_metrics=True, enable_usage_metrics=True),
|
|
86
|
+
idle_timeout_secs=runner_args.pipeline_idle_timeout_secs,
|
|
87
|
+
processor_unusable_policy=ProcessorUnusablePolicy.END,
|
|
88
|
+
)
|
|
89
|
+
|
|
90
|
+
runner = WorkerRunner(handle_sigint=runner_args.handle_sigint)
|
|
91
|
+
await runner.add_workers(worker)
|
|
92
|
+
|
|
93
|
+
@transport.event_handler("on_client_connected")
|
|
94
|
+
async def on_client_connected(transport, client):
|
|
95
|
+
logger.info("Client connected")
|
|
96
|
+
context.add_message(
|
|
97
|
+
{"role": "developer", "content": "Please introduce yourself to the user."}
|
|
98
|
+
)
|
|
99
|
+
await worker.queue_frames([LLMRunFrame()])
|
|
100
|
+
|
|
101
|
+
@transport.event_handler("on_client_disconnected")
|
|
102
|
+
async def on_client_disconnected(transport, client):
|
|
103
|
+
logger.info("Client disconnected")
|
|
104
|
+
await runner.cancel()
|
|
105
|
+
|
|
106
|
+
await runner.run()
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
async def bot(runner_args: RunnerArguments):
|
|
110
|
+
"""Main bot entry point compatible with Pipecat Cloud."""
|
|
111
|
+
transport = await create_transport(runner_args, transport_params)
|
|
112
|
+
await run_bot(transport, runner_args)
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
if __name__ == "__main__":
|
|
116
|
+
from pipecat.runner.run import main
|
|
117
|
+
|
|
118
|
+
main()
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "pipecat-aircaps"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "AirCaps Live speech-to-text for Pipecat voice agents"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "BSD-2-Clause"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
requires-python = ">=3.11"
|
|
9
|
+
authors = [{ name = "AirCaps" }]
|
|
10
|
+
keywords = ["pipecat", "speech-to-text", "stt", "voice-agents", "realtime", "aircaps"]
|
|
11
|
+
classifiers = [
|
|
12
|
+
"Development Status :: 4 - Beta",
|
|
13
|
+
"Intended Audience :: Developers",
|
|
14
|
+
"Operating System :: OS Independent",
|
|
15
|
+
"Programming Language :: Python :: 3",
|
|
16
|
+
"Programming Language :: Python :: 3.11",
|
|
17
|
+
"Programming Language :: Python :: 3.12",
|
|
18
|
+
"Programming Language :: Python :: 3.13",
|
|
19
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
20
|
+
"Topic :: Multimedia :: Sound/Audio :: Speech",
|
|
21
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
22
|
+
"Typing :: Typed",
|
|
23
|
+
]
|
|
24
|
+
dependencies = ["pipecat-ai>=1.16.0,<2"]
|
|
25
|
+
|
|
26
|
+
[project.urls]
|
|
27
|
+
Homepage = "https://aircaps.ai"
|
|
28
|
+
Documentation = "https://aircaps.ai/docs/guides/live-1"
|
|
29
|
+
Repository = "https://github.com/aircaps/pipecat-aircaps"
|
|
30
|
+
Issues = "https://github.com/aircaps/pipecat-aircaps/issues"
|
|
31
|
+
Changelog = "https://github.com/aircaps/pipecat-aircaps/blob/main/CHANGELOG.md"
|
|
32
|
+
|
|
33
|
+
[project.optional-dependencies]
|
|
34
|
+
example = ["pipecat-ai[cartesia,openai,runner,silero,webrtc]>=1.16.0,<2", "python-dotenv"]
|
|
35
|
+
|
|
36
|
+
[dependency-groups]
|
|
37
|
+
dev = ["pytest>=8", "pytest-asyncio>=0.24", "ruff>=0.9"]
|
|
38
|
+
|
|
39
|
+
[build-system]
|
|
40
|
+
requires = ["hatchling"]
|
|
41
|
+
build-backend = "hatchling.build"
|
|
42
|
+
|
|
43
|
+
[tool.hatch.build.targets.wheel]
|
|
44
|
+
packages = ["src/pipecat_aircaps"]
|
|
45
|
+
|
|
46
|
+
[tool.hatch.build.targets.sdist]
|
|
47
|
+
include = ["/src", "/tests", "/examples", "/README.md", "/CHANGELOG.md", "/LICENSE"]
|
|
48
|
+
|
|
49
|
+
[tool.pytest.ini_options]
|
|
50
|
+
asyncio_mode = "auto"
|
|
51
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
52
|
+
|
|
53
|
+
[tool.ruff]
|
|
54
|
+
line-length = 100
|
|
55
|
+
|
|
56
|
+
[tool.ruff.lint]
|
|
57
|
+
select = ["B", "D", "F", "I", "UP"]
|
|
58
|
+
|
|
59
|
+
[tool.ruff.lint.isort]
|
|
60
|
+
known-third-party = ["pipecat"]
|
|
61
|
+
section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]
|
|
62
|
+
|
|
63
|
+
[tool.ruff.lint.pydocstyle]
|
|
64
|
+
convention = "google"
|
|
65
|
+
|
|
66
|
+
[tool.ruff.lint.per-file-ignores]
|
|
67
|
+
"examples/**/*.py" = ["D"]
|
|
68
|
+
"tests/**/*.py" = ["D"]
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
#
|
|
2
|
+
# Copyright (c) 2026, AirCaps
|
|
3
|
+
#
|
|
4
|
+
# SPDX-License-Identifier: BSD 2-Clause License
|
|
5
|
+
#
|
|
6
|
+
|
|
7
|
+
"""AirCaps speech-to-text services for Pipecat."""
|
|
8
|
+
|
|
9
|
+
from pipecat_aircaps.stt import AirCapsLiveSTTService, AirCapsLiveSTTSettings
|
|
10
|
+
|
|
11
|
+
__all__ = ["AirCapsLiveSTTService", "AirCapsLiveSTTSettings"]
|
|
File without changes
|