pipecat-echo-tts 0.1.1__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_echo_tts-0.1.1/.github/workflows/publish.yml +16 -0
- pipecat_echo_tts-0.1.1/.gitignore +9 -0
- pipecat_echo_tts-0.1.1/CHANGELOG.md +22 -0
- pipecat_echo_tts-0.1.1/LICENSE +25 -0
- pipecat_echo_tts-0.1.1/PKG-INFO +149 -0
- pipecat_echo_tts-0.1.1/README.md +128 -0
- pipecat_echo_tts-0.1.1/examples/.env.template +12 -0
- pipecat_echo_tts-0.1.1/examples/bot.py +141 -0
- pipecat_echo_tts-0.1.1/pyproject.toml +66 -0
- pipecat_echo_tts-0.1.1/src/pipecat_echo_tts/__init__.py +24 -0
- pipecat_echo_tts-0.1.1/src/pipecat_echo_tts/cache.py +91 -0
- pipecat_echo_tts-0.1.1/src/pipecat_echo_tts/py.typed +0 -0
- pipecat_echo_tts-0.1.1/src/pipecat_echo_tts/service.py +124 -0
- pipecat_echo_tts-0.1.1/tests/__init__.py +2 -0
- pipecat_echo_tts-0.1.1/tests/conftest.py +102 -0
- pipecat_echo_tts-0.1.1/tests/test_cache.py +72 -0
- pipecat_echo_tts-0.1.1/tests/test_service.py +92 -0
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
name: Publish to PyPI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
release:
|
|
5
|
+
types: [published]
|
|
6
|
+
|
|
7
|
+
jobs:
|
|
8
|
+
publish:
|
|
9
|
+
runs-on: ubuntu-latest
|
|
10
|
+
steps:
|
|
11
|
+
- uses: actions/checkout@v4
|
|
12
|
+
- uses: astral-sh/setup-uv@v5
|
|
13
|
+
- run: uv build
|
|
14
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
15
|
+
with:
|
|
16
|
+
password: ${{ secrets.PYPI_API_TOKEN }}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.1
|
|
4
|
+
|
|
5
|
+
**Fixed**
|
|
6
|
+
|
|
7
|
+
- Only cache audio the wav container represents losslessly: a multi-channel
|
|
8
|
+
inner was stored as mono and every later cache hit replayed mangled audio.
|
|
9
|
+
Non-mono phrases are served untouched but not cached.
|
|
10
|
+
|
|
11
|
+
## 0.1.0
|
|
12
|
+
|
|
13
|
+
- `EchoTTSService`: a Pipecat TTS service that wraps yours, caches
|
|
14
|
+
phrase-level audio on live calls (pipecat already hands text over in
|
|
15
|
+
sentence slots), and replays cached audio instantly on repetition.
|
|
16
|
+
- `EchoCache`: phrase text to PCM on disk, one small wav per phrase, sample
|
|
17
|
+
rate in the header. Stdlib only. Hand-seed phrases by copying wav files in
|
|
18
|
+
(see `filename_for`).
|
|
19
|
+
- The wrapper forwards the public lifecycle (`setup`, `StartFrame`, `cleanup`)
|
|
20
|
+
to the inner service, so the inner starts, connects and shuts down with the
|
|
21
|
+
pipeline.
|
|
22
|
+
- `stats`: hits, misses, characters served from cache, phrases cached.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
BSD 2-Clause License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026, Daniel Garcia Pena
|
|
4
|
+
All rights reserved.
|
|
5
|
+
|
|
6
|
+
Redistribution and use in source and binary forms, with or without
|
|
7
|
+
modification, are permitted provided that the following conditions are met:
|
|
8
|
+
|
|
9
|
+
1. Redistributions of source code must retain the above copyright notice, this
|
|
10
|
+
list of conditions and the following disclaimer.
|
|
11
|
+
|
|
12
|
+
2. Redistributions in binary form must reproduce the above copyright notice,
|
|
13
|
+
this list of conditions and the following disclaimer in the documentation
|
|
14
|
+
and/or other materials provided with the distribution.
|
|
15
|
+
|
|
16
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
17
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
18
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
19
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
20
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
21
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
22
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
23
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
24
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
25
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: pipecat-echo-tts
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: Your TTS bill, cached — a Pipecat TTS wrapper that caches phrase-level audio on live calls and replays it instantly on repetition.
|
|
5
|
+
Project-URL: Homepage, https://github.com/iamdgarcia/pipecat-echo-tts
|
|
6
|
+
Project-URL: Repository, https://github.com/iamdgarcia/pipecat-echo-tts
|
|
7
|
+
Project-URL: Issues, https://github.com/iamdgarcia/pipecat-echo-tts/issues
|
|
8
|
+
Author-email: Daniel Garcia Peña <info@iamdgarcia.com>
|
|
9
|
+
License-Expression: BSD-2-Clause
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: cache,conversational-ai,cost-optimization,pipecat,tts,voice-ai
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
|
|
18
|
+
Requires-Python: >=3.11
|
|
19
|
+
Requires-Dist: pipecat-ai<2,>=1.6.0
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
|
|
22
|
+
<div align="center">
|
|
23
|
+
<a href="https://github.com/pipecat-ai/pipecat">
|
|
24
|
+
<img alt="Pipecat" width="220px" height="auto" src="https://raw.githubusercontent.com/pipecat-ai/pipecat/main/pipecat.png">
|
|
25
|
+
</a>
|
|
26
|
+
<p><em>A community integration for <a href="https://github.com/pipecat-ai/pipecat">Pipecat</a></em></p>
|
|
27
|
+
</div>
|
|
28
|
+
|
|
29
|
+
# pipecat-echo-tts
|
|
30
|
+
|
|
31
|
+
[](https://pypi.org/project/pipecat-echo-tts)
|
|
32
|
+
[](https://pypi.org/project/pipecat-echo-tts)
|
|
33
|
+
[](LICENSE)
|
|
34
|
+
[](https://github.com/pipecat-ai/pipecat)
|
|
35
|
+
|
|
36
|
+
Your TTS bill, cached: Echo wraps the TTS you already chose, hears each phrase
|
|
37
|
+
once, and replays it instantly, forever after, for free.
|
|
38
|
+
|
|
39
|
+
Inspired by [Echo](https://www.echospeaks.ai/) (echospeaks.ai), the hosted TTS
|
|
40
|
+
cache for Pipecat — this is the open, self-hosted take: your machine, your
|
|
41
|
+
cache directory, no service in the middle.
|
|
42
|
+
|
|
43
|
+
## Why
|
|
44
|
+
|
|
45
|
+
Across a typical voice AI stack, text-to-speech is the single largest line
|
|
46
|
+
item — bigger than the LLM and the transcriber combined. And an agent says the
|
|
47
|
+
same things all day: greetings, confirmations, hold lines, closings.
|
|
48
|
+
Synthesizing "Sure, I can help you with that" for the ten thousandth time is
|
|
49
|
+
paying full price for bytes you already own.
|
|
50
|
+
|
|
51
|
+
Echo caches the audio your TTS engine already produced. Replaying a cached
|
|
52
|
+
phrase costs no TTS call, no network round trip and no tokens — and it comes
|
|
53
|
+
back instantly, so repeated lines also lose their synthesis latency.
|
|
54
|
+
|
|
55
|
+
## Install
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
uv add pipecat-echo-tts
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Usage
|
|
62
|
+
|
|
63
|
+
One wrapper is the whole integration. It **is** a Pipecat TTS service — same
|
|
64
|
+
frames, same lifecycle, same place in the pipeline:
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
from pipecat_echo_tts import EchoTTSService
|
|
68
|
+
|
|
69
|
+
tts = EchoTTSService(tts=CartesiaTTSService(...))
|
|
70
|
+
|
|
71
|
+
pipeline = Pipeline([
|
|
72
|
+
transport.input(),
|
|
73
|
+
stt,
|
|
74
|
+
context_aggregator.user(),
|
|
75
|
+
llm,
|
|
76
|
+
tts, # your TTS, cached
|
|
77
|
+
transport.output(),
|
|
78
|
+
context_aggregator.assistant(),
|
|
79
|
+
])
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Nothing about your voice changes: the cache stores the audio your own TTS
|
|
83
|
+
produced, in its own voice, and the inner service starts and shuts down with
|
|
84
|
+
the pipeline.
|
|
85
|
+
|
|
86
|
+
Watch the savings as calls come in:
|
|
87
|
+
|
|
88
|
+
```python
|
|
89
|
+
tts.stats
|
|
90
|
+
# {'hits': 41, 'misses': 7, 'chars_served': 1042, 'phrases_cached': 23}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The cache lives in `.echo_cache/` next to where you run the bot and survives
|
|
94
|
+
restarts. It is keyed to the exact normalized phrase: delete the directory
|
|
95
|
+
when you change voice, since the key carries no voice fingerprint.
|
|
96
|
+
|
|
97
|
+
## How it works
|
|
98
|
+
|
|
99
|
+
Pipecat hands text to a TTS one phrase at a time — the sentence-level
|
|
100
|
+
aggregated slots from the LLM response machinery. `EchoTTSService` caches each
|
|
101
|
+
phrase's audio the first time it synthesizes (one miss), and on every later
|
|
102
|
+
occurrence streams the cached bytes immediately (one hit). No VAD, no turn
|
|
103
|
+
model, no ONNX, no background recording: the cache fills from live calls and
|
|
104
|
+
the inner service is driven through its public lifecycle only.
|
|
105
|
+
|
|
106
|
+
Because the wrapper is a real `TTSService`, there are no fake frames anywhere:
|
|
107
|
+
a cache hit is the same words, the same voice, already paid for. Turn tracking,
|
|
108
|
+
RTVI events, interruptions and mute strategies see exactly what they would see
|
|
109
|
+
if the phrase had been synthesized again.
|
|
110
|
+
|
|
111
|
+
## Run the example
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
cp examples/.env.template examples/.env # add your keys
|
|
115
|
+
uv run examples/bot.py --transport webrtc
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
A support agent whose routine lines repeat; call it twice and hear the second
|
|
119
|
+
call skip synthesis on every phrase the first call already said. The stats log
|
|
120
|
+
at connect/disconnect shows what the cache caught.
|
|
121
|
+
|
|
122
|
+
## Compatibility
|
|
123
|
+
|
|
124
|
+
Tested with Pipecat v1.15.1. Inner services must be HTTP-style (their
|
|
125
|
+
`run_tts` yields the audio): OpenAI, Cartesia HTTP, ElevenLabs HTTP, Deepgram,
|
|
126
|
+
Azure, Rime, Gemini. WebSocket-streaming inners deliver audio outside
|
|
127
|
+
`run_tts`, which this wrapper does not capture.
|
|
128
|
+
|
|
129
|
+
## Limitations
|
|
130
|
+
|
|
131
|
+
- **Exact match only.** "Hello, Jane" and "Hello, Sam" are different keys;
|
|
132
|
+
templated phrases with variables are on the roadmap. Consistent phrasing
|
|
133
|
+
from your system prompt raises the hit rate directly.
|
|
134
|
+
- **A cache is voice-bound.** The directory must be cleared when the voice
|
|
135
|
+
changes; there is no voice fingerprint in the key yet.
|
|
136
|
+
- **Inner usage metrics** (the provider's character counts) are not relayed
|
|
137
|
+
into the pipeline's usage frames; the wrapper's `stats` is the source of
|
|
138
|
+
truth for what was served from cache.
|
|
139
|
+
|
|
140
|
+
## Roadmap
|
|
141
|
+
|
|
142
|
+
- Templated phrases with variables (dynamic slots, echospeaks-style)
|
|
143
|
+
- Optional similarity matching (fuzzy keys with embedding confirmation)
|
|
144
|
+
- Relay of inner-service usage metrics
|
|
145
|
+
|
|
146
|
+
## Credits
|
|
147
|
+
|
|
148
|
+
- [Echo (echospeaks.ai)](https://www.echospeaks.ai/) — the idea, built as a
|
|
149
|
+
hosted product; go there if you want it managed for you.
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
<a href="https://github.com/pipecat-ai/pipecat">
|
|
3
|
+
<img alt="Pipecat" width="220px" height="auto" src="https://raw.githubusercontent.com/pipecat-ai/pipecat/main/pipecat.png">
|
|
4
|
+
</a>
|
|
5
|
+
<p><em>A community integration for <a href="https://github.com/pipecat-ai/pipecat">Pipecat</a></em></p>
|
|
6
|
+
</div>
|
|
7
|
+
|
|
8
|
+
# pipecat-echo-tts
|
|
9
|
+
|
|
10
|
+
[](https://pypi.org/project/pipecat-echo-tts)
|
|
11
|
+
[](https://pypi.org/project/pipecat-echo-tts)
|
|
12
|
+
[](LICENSE)
|
|
13
|
+
[](https://github.com/pipecat-ai/pipecat)
|
|
14
|
+
|
|
15
|
+
Your TTS bill, cached: Echo wraps the TTS you already chose, hears each phrase
|
|
16
|
+
once, and replays it instantly, forever after, for free.
|
|
17
|
+
|
|
18
|
+
Inspired by [Echo](https://www.echospeaks.ai/) (echospeaks.ai), the hosted TTS
|
|
19
|
+
cache for Pipecat — this is the open, self-hosted take: your machine, your
|
|
20
|
+
cache directory, no service in the middle.
|
|
21
|
+
|
|
22
|
+
## Why
|
|
23
|
+
|
|
24
|
+
Across a typical voice AI stack, text-to-speech is the single largest line
|
|
25
|
+
item — bigger than the LLM and the transcriber combined. And an agent says the
|
|
26
|
+
same things all day: greetings, confirmations, hold lines, closings.
|
|
27
|
+
Synthesizing "Sure, I can help you with that" for the ten thousandth time is
|
|
28
|
+
paying full price for bytes you already own.
|
|
29
|
+
|
|
30
|
+
Echo caches the audio your TTS engine already produced. Replaying a cached
|
|
31
|
+
phrase costs no TTS call, no network round trip and no tokens — and it comes
|
|
32
|
+
back instantly, so repeated lines also lose their synthesis latency.
|
|
33
|
+
|
|
34
|
+
## Install
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
uv add pipecat-echo-tts
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Usage
|
|
41
|
+
|
|
42
|
+
One wrapper is the whole integration. It **is** a Pipecat TTS service — same
|
|
43
|
+
frames, same lifecycle, same place in the pipeline:
|
|
44
|
+
|
|
45
|
+
```python
|
|
46
|
+
from pipecat_echo_tts import EchoTTSService
|
|
47
|
+
|
|
48
|
+
tts = EchoTTSService(tts=CartesiaTTSService(...))
|
|
49
|
+
|
|
50
|
+
pipeline = Pipeline([
|
|
51
|
+
transport.input(),
|
|
52
|
+
stt,
|
|
53
|
+
context_aggregator.user(),
|
|
54
|
+
llm,
|
|
55
|
+
tts, # your TTS, cached
|
|
56
|
+
transport.output(),
|
|
57
|
+
context_aggregator.assistant(),
|
|
58
|
+
])
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Nothing about your voice changes: the cache stores the audio your own TTS
|
|
62
|
+
produced, in its own voice, and the inner service starts and shuts down with
|
|
63
|
+
the pipeline.
|
|
64
|
+
|
|
65
|
+
Watch the savings as calls come in:
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
tts.stats
|
|
69
|
+
# {'hits': 41, 'misses': 7, 'chars_served': 1042, 'phrases_cached': 23}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The cache lives in `.echo_cache/` next to where you run the bot and survives
|
|
73
|
+
restarts. It is keyed to the exact normalized phrase: delete the directory
|
|
74
|
+
when you change voice, since the key carries no voice fingerprint.
|
|
75
|
+
|
|
76
|
+
## How it works
|
|
77
|
+
|
|
78
|
+
Pipecat hands text to a TTS one phrase at a time — the sentence-level
|
|
79
|
+
aggregated slots from the LLM response machinery. `EchoTTSService` caches each
|
|
80
|
+
phrase's audio the first time it synthesizes (one miss), and on every later
|
|
81
|
+
occurrence streams the cached bytes immediately (one hit). No VAD, no turn
|
|
82
|
+
model, no ONNX, no background recording: the cache fills from live calls and
|
|
83
|
+
the inner service is driven through its public lifecycle only.
|
|
84
|
+
|
|
85
|
+
Because the wrapper is a real `TTSService`, there are no fake frames anywhere:
|
|
86
|
+
a cache hit is the same words, the same voice, already paid for. Turn tracking,
|
|
87
|
+
RTVI events, interruptions and mute strategies see exactly what they would see
|
|
88
|
+
if the phrase had been synthesized again.
|
|
89
|
+
|
|
90
|
+
## Run the example
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
cp examples/.env.template examples/.env # add your keys
|
|
94
|
+
uv run examples/bot.py --transport webrtc
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
A support agent whose routine lines repeat; call it twice and hear the second
|
|
98
|
+
call skip synthesis on every phrase the first call already said. The stats log
|
|
99
|
+
at connect/disconnect shows what the cache caught.
|
|
100
|
+
|
|
101
|
+
## Compatibility
|
|
102
|
+
|
|
103
|
+
Tested with Pipecat v1.15.1. Inner services must be HTTP-style (their
|
|
104
|
+
`run_tts` yields the audio): OpenAI, Cartesia HTTP, ElevenLabs HTTP, Deepgram,
|
|
105
|
+
Azure, Rime, Gemini. WebSocket-streaming inners deliver audio outside
|
|
106
|
+
`run_tts`, which this wrapper does not capture.
|
|
107
|
+
|
|
108
|
+
## Limitations
|
|
109
|
+
|
|
110
|
+
- **Exact match only.** "Hello, Jane" and "Hello, Sam" are different keys;
|
|
111
|
+
templated phrases with variables are on the roadmap. Consistent phrasing
|
|
112
|
+
from your system prompt raises the hit rate directly.
|
|
113
|
+
- **A cache is voice-bound.** The directory must be cleared when the voice
|
|
114
|
+
changes; there is no voice fingerprint in the key yet.
|
|
115
|
+
- **Inner usage metrics** (the provider's character counts) are not relayed
|
|
116
|
+
into the pipeline's usage frames; the wrapper's `stats` is the source of
|
|
117
|
+
truth for what was served from cache.
|
|
118
|
+
|
|
119
|
+
## Roadmap
|
|
120
|
+
|
|
121
|
+
- Templated phrases with variables (dynamic slots, echospeaks-style)
|
|
122
|
+
- Optional similarity matching (fuzzy keys with embedding confirmation)
|
|
123
|
+
- Relay of inner-service usage metrics
|
|
124
|
+
|
|
125
|
+
## Credits
|
|
126
|
+
|
|
127
|
+
- [Echo (echospeaks.ai)](https://www.echospeaks.ai/) — the idea, built as a
|
|
128
|
+
hosted product; go there if you want it managed for you.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Cerebras (LLM): https://cloud.cerebras.ai
|
|
2
|
+
CEREBRAS_API_KEY=
|
|
3
|
+
# Optional: defaults to llama-3.3-70b
|
|
4
|
+
CEREBRAS_MODEL=
|
|
5
|
+
|
|
6
|
+
# Deepgram (STT): https://console.deepgram.com
|
|
7
|
+
DEEPGRAM_API_KEY=
|
|
8
|
+
|
|
9
|
+
# Cartesia (TTS): https://play.cartesia.ai
|
|
10
|
+
CARTESIA_API_KEY=
|
|
11
|
+
# Optional: defaults to the 71a7ad14... M0 voice
|
|
12
|
+
CARTESIA_VOICE_ID=
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
#
|
|
2
|
+
# SPDX-License-Identifier: BSD-2-Clause
|
|
3
|
+
#
|
|
4
|
+
|
|
5
|
+
"""A support agent whose routine lines repeat — and stop costing money.
|
|
6
|
+
|
|
7
|
+
The whole integration is one wrapper: `EchoTTSService` around your TTS. Call
|
|
8
|
+
one fills the cache; every call after that serves the repeated phrases from
|
|
9
|
+
disk instantly. Same voice, same quality, no TTS call for a phrase it has
|
|
10
|
+
heard.
|
|
11
|
+
|
|
12
|
+
Run with: uv run examples/bot.py --transport webrtc
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
import os
|
|
16
|
+
|
|
17
|
+
from dotenv import load_dotenv
|
|
18
|
+
from loguru import logger
|
|
19
|
+
from pipecat.audio.vad.silero import SileroVADAnalyzer
|
|
20
|
+
from pipecat.frames.frames import LLMRunFrame
|
|
21
|
+
from pipecat.pipeline.pipeline import Pipeline
|
|
22
|
+
from pipecat.pipeline.worker import PipelineParams, PipelineWorker
|
|
23
|
+
from pipecat.processors.aggregators.llm_context import LLMContext
|
|
24
|
+
from pipecat.processors.aggregators.llm_response_universal import (
|
|
25
|
+
LLMContextAggregatorPair,
|
|
26
|
+
LLMUserAggregatorParams,
|
|
27
|
+
)
|
|
28
|
+
from pipecat.runner.types import RunnerArguments
|
|
29
|
+
from pipecat.runner.utils import create_transport
|
|
30
|
+
from pipecat.services.cartesia.tts import CartesiaTTSService
|
|
31
|
+
from pipecat.services.cerebras.llm import CerebrasLLMService
|
|
32
|
+
from pipecat.services.deepgram.stt import DeepgramSTTService
|
|
33
|
+
from pipecat.transports.base_transport import BaseTransport, TransportParams
|
|
34
|
+
from pipecat.workers.runner import WorkerRunner
|
|
35
|
+
|
|
36
|
+
from pipecat_echo_tts import EchoTTSService
|
|
37
|
+
|
|
38
|
+
# Relative to this file, not the shell's cwd, so the example runs from anywhere.
|
|
39
|
+
load_dotenv(os.path.join(os.path.dirname(__file__), ".env"))
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def make_tts() -> EchoTTSService:
|
|
43
|
+
"""Your TTS, wrapped: the cache is `.echo_cache/`, filled from live calls."""
|
|
44
|
+
return EchoTTSService(
|
|
45
|
+
tts=CartesiaTTSService(
|
|
46
|
+
api_key=os.getenv("CARTESIA_API_KEY"),
|
|
47
|
+
sample_rate=24000,
|
|
48
|
+
settings=CartesiaTTSService.Settings(
|
|
49
|
+
voice=os.getenv(
|
|
50
|
+
"CARTESIA_VOICE_ID", "71a7ad14-091c-4e8e-a314-022ece01c121"
|
|
51
|
+
),
|
|
52
|
+
),
|
|
53
|
+
)
|
|
54
|
+
)
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
async def run_bot(transport: BaseTransport, runner_args: RunnerArguments) -> None:
|
|
58
|
+
logger.info("Starting bot")
|
|
59
|
+
|
|
60
|
+
stt = DeepgramSTTService(api_key=os.getenv("DEEPGRAM_API_KEY"))
|
|
61
|
+
tts = make_tts()
|
|
62
|
+
|
|
63
|
+
llm = CerebrasLLMService(
|
|
64
|
+
api_key=os.getenv("CEREBRAS_API_KEY"),
|
|
65
|
+
model=os.getenv("CEREBRAS_MODEL", "llama-3.3-70b"),
|
|
66
|
+
settings=CerebrasLLMService.Settings(
|
|
67
|
+
system_instruction=(
|
|
68
|
+
"You are a phone support agent for ABC Shop. You greet callers, "
|
|
69
|
+
"confirm what they need, and close the call warmly. Keep replies "
|
|
70
|
+
"to one or two short sentences, and phrase routine lines the same "
|
|
71
|
+
"way every time."
|
|
72
|
+
),
|
|
73
|
+
),
|
|
74
|
+
)
|
|
75
|
+
|
|
76
|
+
context = LLMContext()
|
|
77
|
+
user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
|
|
78
|
+
context,
|
|
79
|
+
user_params=LLMUserAggregatorParams(vad_analyzer=SileroVADAnalyzer()),
|
|
80
|
+
)
|
|
81
|
+
|
|
82
|
+
pipeline = Pipeline(
|
|
83
|
+
[
|
|
84
|
+
transport.input(),
|
|
85
|
+
stt,
|
|
86
|
+
user_aggregator,
|
|
87
|
+
llm,
|
|
88
|
+
tts,
|
|
89
|
+
transport.output(),
|
|
90
|
+
assistant_aggregator,
|
|
91
|
+
]
|
|
92
|
+
)
|
|
93
|
+
|
|
94
|
+
worker = PipelineWorker(
|
|
95
|
+
pipeline,
|
|
96
|
+
params=PipelineParams(
|
|
97
|
+
enable_metrics=True,
|
|
98
|
+
enable_usage_metrics=True,
|
|
99
|
+
),
|
|
100
|
+
idle_timeout_secs=runner_args.pipeline_idle_timeout_secs,
|
|
101
|
+
)
|
|
102
|
+
|
|
103
|
+
runner = WorkerRunner(handle_sigint=runner_args.handle_sigint)
|
|
104
|
+
await runner.add_workers(worker)
|
|
105
|
+
|
|
106
|
+
@transport.event_handler("on_client_connected")
|
|
107
|
+
async def on_client_connected(transport, client):
|
|
108
|
+
logger.info(f"Client connected — echo stats so far: {tts.stats}")
|
|
109
|
+
context.add_message(
|
|
110
|
+
{
|
|
111
|
+
"role": "developer",
|
|
112
|
+
"content": "Greet the caller and ask how you can help today.",
|
|
113
|
+
}
|
|
114
|
+
)
|
|
115
|
+
await worker.queue_frames([LLMRunFrame()])
|
|
116
|
+
|
|
117
|
+
@transport.event_handler("on_client_disconnected")
|
|
118
|
+
async def on_client_disconnected(transport, client):
|
|
119
|
+
logger.info(f"Client disconnected — echo stats: {tts.stats}")
|
|
120
|
+
await worker.cancel()
|
|
121
|
+
|
|
122
|
+
await runner.run()
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
async def bot(runner_args: RunnerArguments):
|
|
126
|
+
transport_params = {
|
|
127
|
+
"webrtc": lambda: TransportParams(
|
|
128
|
+
audio_in_enabled=True,
|
|
129
|
+
audio_out_enabled=True,
|
|
130
|
+
),
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
transport = await create_transport(runner_args, transport_params)
|
|
134
|
+
|
|
135
|
+
await run_bot(transport, runner_args)
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
if __name__ == "__main__":
|
|
139
|
+
from pipecat.runner.run import main
|
|
140
|
+
|
|
141
|
+
main()
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "pipecat-echo-tts"
|
|
3
|
+
version = "0.1.1"
|
|
4
|
+
description = "Your TTS bill, cached — a Pipecat TTS wrapper that caches phrase-level audio on live calls and replays it instantly on repetition."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.11"
|
|
7
|
+
license = "BSD-2-Clause"
|
|
8
|
+
license-files = ["LICENSE"]
|
|
9
|
+
authors = [{ name = "Daniel Garcia Peña", email = "info@iamdgarcia.com" }]
|
|
10
|
+
keywords = [
|
|
11
|
+
"pipecat",
|
|
12
|
+
"voice-ai",
|
|
13
|
+
"tts",
|
|
14
|
+
"cache",
|
|
15
|
+
"conversational-ai",
|
|
16
|
+
"cost-optimization",
|
|
17
|
+
]
|
|
18
|
+
classifiers = [
|
|
19
|
+
"Development Status :: 3 - Alpha",
|
|
20
|
+
"Intended Audience :: Developers",
|
|
21
|
+
"Programming Language :: Python :: 3.11",
|
|
22
|
+
"Programming Language :: Python :: 3.12",
|
|
23
|
+
"Programming Language :: Python :: 3.13",
|
|
24
|
+
"Topic :: Multimedia :: Sound/Audio :: Speech",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
# Signal-free by design: the package IS a TTSService that wraps yours. No
|
|
28
|
+
# VAD, no turn model, no ONNX, no sibling-plugin dependencies — a phrase
|
|
29
|
+
# cache (stdlib: hashlib + wave) and a run_tts wrapper.
|
|
30
|
+
dependencies = [
|
|
31
|
+
"pipecat-ai>=1.6.0,<2",
|
|
32
|
+
]
|
|
33
|
+
|
|
34
|
+
[project.urls]
|
|
35
|
+
Homepage = "https://github.com/iamdgarcia/pipecat-echo-tts"
|
|
36
|
+
Repository = "https://github.com/iamdgarcia/pipecat-echo-tts"
|
|
37
|
+
Issues = "https://github.com/iamdgarcia/pipecat-echo-tts/issues"
|
|
38
|
+
|
|
39
|
+
[dependency-groups]
|
|
40
|
+
dev = ["pytest>=8", "pytest-asyncio>=0.24", "ruff>=0.8"]
|
|
41
|
+
# Only the examples/ bot needs provider extras — the library itself needs none.
|
|
42
|
+
examples = [
|
|
43
|
+
"pipecat-ai[cerebras,deepgram,runner,silero,webrtc]",
|
|
44
|
+
"python-dotenv",
|
|
45
|
+
]
|
|
46
|
+
|
|
47
|
+
[tool.uv]
|
|
48
|
+
default-groups = ["dev", "examples"]
|
|
49
|
+
|
|
50
|
+
[build-system]
|
|
51
|
+
requires = ["hatchling"]
|
|
52
|
+
build-backend = "hatchling.build"
|
|
53
|
+
|
|
54
|
+
[tool.hatch.build.targets.wheel]
|
|
55
|
+
packages = ["src/pipecat_echo_tts"]
|
|
56
|
+
|
|
57
|
+
[tool.ruff]
|
|
58
|
+
line-length = 100
|
|
59
|
+
target-version = "py311"
|
|
60
|
+
|
|
61
|
+
[tool.pytest.ini_options]
|
|
62
|
+
asyncio_mode = "auto"
|
|
63
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
64
|
+
filterwarnings = [
|
|
65
|
+
"ignore::DeprecationWarning:pipecat.*",
|
|
66
|
+
]
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"""pipecat-echo-tts: your TTS bill, cached.
|
|
2
|
+
|
|
3
|
+
`EchoTTSService` wraps the TTS you already chose and caches phrase-level
|
|
4
|
+
audio on live calls; repeated phrases play instantly from disk::
|
|
5
|
+
|
|
6
|
+
from pipecat_echo_tts import EchoTTSService
|
|
7
|
+
|
|
8
|
+
tts = EchoTTSService(tts=CartesiaTTSService(...))
|
|
9
|
+
|
|
10
|
+
See the repository README for the full story.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from .cache import EchoCache, filename_for, normalize
|
|
14
|
+
from .service import EchoTTSService
|
|
15
|
+
|
|
16
|
+
__version__ = "0.1.1"
|
|
17
|
+
|
|
18
|
+
__all__ = [
|
|
19
|
+
"EchoCache",
|
|
20
|
+
"EchoTTSService",
|
|
21
|
+
"__version__",
|
|
22
|
+
"filename_for",
|
|
23
|
+
"normalize",
|
|
24
|
+
]
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
"""Phrase audio cache: text to PCM on disk, keyed to the words spoken.
|
|
2
|
+
|
|
3
|
+
One `.wav` per phrase, named after its normalized text plus a short
|
|
4
|
+
fingerprint, so the cache directory is readable and hand-seeding a phrase is a
|
|
5
|
+
file copy. The sample rate lives in the wav header, not in the key: a phrase
|
|
6
|
+
recorded at one rate is served at that rate, and the transport resamples.
|
|
7
|
+
Deleting the directory is the whole invalidation story — do it when the voice
|
|
8
|
+
changes, because the key carries no voice fingerprint.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import hashlib
|
|
14
|
+
import wave
|
|
15
|
+
from pathlib import Path
|
|
16
|
+
|
|
17
|
+
__all__ = ["EchoCache", "normalize"]
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def normalize(text: str) -> str:
|
|
21
|
+
"""Return the cache key for a phrase: lowercased, whitespace collapsed.
|
|
22
|
+
|
|
23
|
+
Punctuation is kept on purpose: "Yes." and "Yes" are different prosodies,
|
|
24
|
+
and a cache that conflates them stores the wrong melody against a key.
|
|
25
|
+
"""
|
|
26
|
+
return " ".join(text.lower().split())
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def filename_for(text: str, sample_rate: int) -> str:
|
|
30
|
+
"""Return the cache filename for a phrase.
|
|
31
|
+
|
|
32
|
+
Exported so phrases can be seeded by hand: name a `.wav` with this and
|
|
33
|
+
drop it in the cache directory; Echo serves it without ever calling the
|
|
34
|
+
inner TTS.
|
|
35
|
+
"""
|
|
36
|
+
key = normalize(text)
|
|
37
|
+
safe = "".join(c if c.isalnum() else "_" for c in key).strip("_")[:64] or "empty"
|
|
38
|
+
tag = hashlib.sha1(key.encode()).hexdigest()[:6]
|
|
39
|
+
return f"{safe}_{tag}_{sample_rate}hz.wav"
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class EchoCache:
|
|
43
|
+
"""Keeps phrase audio between runs, in a directory of small wav files."""
|
|
44
|
+
|
|
45
|
+
def __init__(self, path: str | Path = ".echo_cache"):
|
|
46
|
+
self._path = Path(path)
|
|
47
|
+
self._path.mkdir(parents=True, exist_ok=True)
|
|
48
|
+
|
|
49
|
+
@property
|
|
50
|
+
def path(self) -> Path:
|
|
51
|
+
"""The cache directory."""
|
|
52
|
+
return self._path
|
|
53
|
+
|
|
54
|
+
def get(self, text: str) -> tuple[bytes, int] | None:
|
|
55
|
+
"""Return ``(pcm, sample_rate)`` for a phrase, or ``None`` if not cached.
|
|
56
|
+
|
|
57
|
+
A corrupt file (a crash mid-write, a hand-seeded mistake) is treated as
|
|
58
|
+
a miss and removed, so the next miss can rewrite it instead of the key
|
|
59
|
+
staying poisoned forever.
|
|
60
|
+
"""
|
|
61
|
+
hits = sorted(self._path.glob(self._glob_for(text)))
|
|
62
|
+
if not hits:
|
|
63
|
+
return None
|
|
64
|
+
try:
|
|
65
|
+
with wave.open(str(hits[0]), "rb") as wf:
|
|
66
|
+
rate = wf.getframerate()
|
|
67
|
+
pcm = wf.readframes(wf.getnframes())
|
|
68
|
+
except (wave.Error, EOFError):
|
|
69
|
+
hits[0].unlink(missing_ok=True)
|
|
70
|
+
return None
|
|
71
|
+
return pcm, rate
|
|
72
|
+
|
|
73
|
+
def put(self, text: str, pcm: bytes, sample_rate: int) -> None:
|
|
74
|
+
"""Store PCM for a phrase. Empty audio is not stored."""
|
|
75
|
+
if not pcm:
|
|
76
|
+
return
|
|
77
|
+
name = filename_for(text, sample_rate)
|
|
78
|
+
target = self._path / name
|
|
79
|
+
if target.exists():
|
|
80
|
+
return
|
|
81
|
+
with wave.open(str(target), "wb") as wf:
|
|
82
|
+
wf.setnchannels(1)
|
|
83
|
+
wf.setsampwidth(2)
|
|
84
|
+
wf.setframerate(sample_rate)
|
|
85
|
+
wf.writeframes(pcm)
|
|
86
|
+
|
|
87
|
+
def _glob_for(self, text: str) -> str:
|
|
88
|
+
key = normalize(text)
|
|
89
|
+
safe = "".join(c if c.isalnum() else "_" for c in key).strip("_")[:64] or "empty"
|
|
90
|
+
tag = hashlib.sha1(key.encode()).hexdigest()[:6]
|
|
91
|
+
return f"{safe}_{tag}_*.wav"
|
|
File without changes
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
"""Your TTS, with a phrase cache in front of it.
|
|
2
|
+
|
|
3
|
+
`EchoTTSService` is a real pipecat TTS service that wraps the one you already
|
|
4
|
+
chose. Pipecat hands text to a TTS one phrase at a time (the sentence-level
|
|
5
|
+
aggregated slots); the service caches the audio for each phrase it synthesizes
|
|
6
|
+
once, and on every later occurrence streams the cached bytes immediately — no
|
|
7
|
+
call to the inner service, no network round trip, no bill.
|
|
8
|
+
|
|
9
|
+
The wrapper forwards the public lifecycle (`setup`, the `StartFrame`,
|
|
10
|
+
`cleanup`) to the inner service, so the inner starts, connects and shuts down
|
|
11
|
+
exactly as it would in the pipeline. Because the wrapper *is* a TTSService,
|
|
12
|
+
everything downstream treats its output as normal bot speech — there are no
|
|
13
|
+
fake frames anywhere: a cache hit is the same words, the same voice, already
|
|
14
|
+
paid for.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
from pipecat.frames.frames import Frame, StartFrame, TTSAudioRawFrame
|
|
20
|
+
from pipecat.processors.frame_processor import FrameDirection
|
|
21
|
+
from pipecat.services.tts_service import TTSService
|
|
22
|
+
|
|
23
|
+
from .cache import EchoCache, normalize
|
|
24
|
+
|
|
25
|
+
__all__ = ["EchoTTSService"]
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class EchoTTSService(TTSService):
|
|
29
|
+
"""Caches phrase audio from the wrapped TTS and replays it on repetition.
|
|
30
|
+
|
|
31
|
+
Build it like your own TTS, wrapped::
|
|
32
|
+
|
|
33
|
+
tts = EchoTTSService(tts=CartesiaTTSService(...))
|
|
34
|
+
|
|
35
|
+
pipeline = Pipeline([
|
|
36
|
+
transport.input(), stt, context_aggregator.user(),
|
|
37
|
+
llm, tts, transport.output(), context_aggregator.assistant(),
|
|
38
|
+
])
|
|
39
|
+
|
|
40
|
+
The first call that says a phrase pays for it; every call after that is
|
|
41
|
+
served from disk. The cache is keyed to the exact normalized phrase and
|
|
42
|
+
lives in `.echo_cache/` — delete it when the voice changes, since the key
|
|
43
|
+
carries no voice fingerprint.
|
|
44
|
+
|
|
45
|
+
Note: use an HTTP-style TTS as the inner service (one whose `run_tts`
|
|
46
|
+
yields the audio — OpenAI, Cartesia HTTP, ElevenLabs HTTP, Deepgram,
|
|
47
|
+
Azure). WebSocket-streaming inners deliver audio outside `run_tts`, which
|
|
48
|
+
this wrapper does not capture.
|
|
49
|
+
"""
|
|
50
|
+
|
|
51
|
+
def __init__(self, *, tts: TTSService, cache: EchoCache | None = None, **kwargs):
|
|
52
|
+
"""Initialize the cache-wrapped TTS.
|
|
53
|
+
|
|
54
|
+
Args:
|
|
55
|
+
tts: The inner service that synthesizes on a cache miss. Build one
|
|
56
|
+
instance for Echo and do not use it elsewhere in the pipeline.
|
|
57
|
+
cache: Where phrase audio is kept. Defaults to `EchoCache()` in
|
|
58
|
+
`.echo_cache/`.
|
|
59
|
+
**kwargs: Forwarded to `TTSService` (`sample_rate`, settings and
|
|
60
|
+
friends).
|
|
61
|
+
"""
|
|
62
|
+
super().__init__(push_start_frame=True, push_stop_frames=True, **kwargs)
|
|
63
|
+
self._inner = tts
|
|
64
|
+
self._cache = cache or EchoCache()
|
|
65
|
+
self.hits = 0
|
|
66
|
+
self.misses = 0
|
|
67
|
+
self.chars_served = 0
|
|
68
|
+
|
|
69
|
+
@property
|
|
70
|
+
def stats(self) -> dict:
|
|
71
|
+
"""Live counters: `hits`, `misses`, `chars_served`, `phrases_cached`."""
|
|
72
|
+
return {
|
|
73
|
+
"hits": self.hits,
|
|
74
|
+
"misses": self.misses,
|
|
75
|
+
"chars_served": self.chars_served,
|
|
76
|
+
"phrases_cached": len(list(self._cache.path.glob("*.wav"))),
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
async def setup(self, setup):
|
|
80
|
+
"""Set up the wrapper and the inner service with the same machinery."""
|
|
81
|
+
await super().setup(setup)
|
|
82
|
+
await self._inner.setup(setup)
|
|
83
|
+
|
|
84
|
+
async def process_frame(self, frame: Frame, direction: FrameDirection):
|
|
85
|
+
"""Start the inner service when the pipeline starts, then carry on."""
|
|
86
|
+
if isinstance(frame, StartFrame) and direction == FrameDirection.DOWNSTREAM:
|
|
87
|
+
await self._inner.process_frame(frame, direction)
|
|
88
|
+
await super().process_frame(frame, direction)
|
|
89
|
+
|
|
90
|
+
async def cleanup(self):
|
|
91
|
+
"""Shut the inner service down with the pipeline."""
|
|
92
|
+
await self._inner.cleanup()
|
|
93
|
+
await super().cleanup()
|
|
94
|
+
|
|
95
|
+
async def run_tts(self, text: str, context_id: str):
|
|
96
|
+
"""Serve a phrase from the cache, or synthesize it once and cache it.
|
|
97
|
+
|
|
98
|
+
Pipecat calls this once per aggregated phrase slot, so the cache is
|
|
99
|
+
phrase-keyed without this service doing any splitting.
|
|
100
|
+
"""
|
|
101
|
+
cached = self._cache.get(text)
|
|
102
|
+
if cached is not None:
|
|
103
|
+
pcm, rate = cached
|
|
104
|
+
self.hits += 1
|
|
105
|
+
self.chars_served += len(text)
|
|
106
|
+
yield TTSAudioRawFrame(pcm, rate, 1, context_id=context_id)
|
|
107
|
+
return
|
|
108
|
+
|
|
109
|
+
self.misses += 1
|
|
110
|
+
chunks: list[bytes] = []
|
|
111
|
+
rate: int | None = None
|
|
112
|
+
mono = True
|
|
113
|
+
async for frame in self._inner.run_tts(text, context_id):
|
|
114
|
+
if isinstance(frame, TTSAudioRawFrame):
|
|
115
|
+
chunks.append(frame.audio)
|
|
116
|
+
rate = frame.sample_rate
|
|
117
|
+
if frame.num_channels != 1:
|
|
118
|
+
# The wav cache is mono 16-bit by design; anything else is
|
|
119
|
+
# served untouched but not stored (a hit would replay it
|
|
120
|
+
# mangled).
|
|
121
|
+
mono = False
|
|
122
|
+
yield frame
|
|
123
|
+
if chunks and rate and mono:
|
|
124
|
+
self._cache.put(normalize(text), b"".join(chunks), rate)
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
"""Shared fakes for the test suite.
|
|
2
|
+
|
|
3
|
+
The wrapper is frame plumbing around a TTS contract, so the inner is a fake
|
|
4
|
+
TTSService that yields configurable PCM and records its lifecycle.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import asyncio
|
|
10
|
+
from itertools import pairwise
|
|
11
|
+
|
|
12
|
+
from pipecat.clocks.system_clock import SystemClock
|
|
13
|
+
from pipecat.frames.frames import Frame, StartFrame, TTSAudioRawFrame
|
|
14
|
+
from pipecat.processors.frame_processor import (
|
|
15
|
+
FrameDirection,
|
|
16
|
+
FrameProcessor,
|
|
17
|
+
FrameProcessorSetup,
|
|
18
|
+
)
|
|
19
|
+
from pipecat.services.tts_service import TTSService
|
|
20
|
+
from pipecat.utils.asyncio.task_manager import TaskManager
|
|
21
|
+
|
|
22
|
+
SAMPLE_RATE = 24000
|
|
23
|
+
PCM = b"\x01\x02" * 40
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class FakeInnerTTS(TTSService):
|
|
27
|
+
"""A TTSService that yields one fixed audio frame and records its life."""
|
|
28
|
+
|
|
29
|
+
def __init__(self, pcm: bytes = PCM, rate: int = SAMPLE_RATE, **kwargs):
|
|
30
|
+
super().__init__(**kwargs)
|
|
31
|
+
self.pcm = pcm
|
|
32
|
+
self.rate = rate
|
|
33
|
+
self.started = False
|
|
34
|
+
self.cleaned = False
|
|
35
|
+
self.calls: list[str] = []
|
|
36
|
+
|
|
37
|
+
async def run_tts(self, text: str, context_id: str):
|
|
38
|
+
self.calls.append(text)
|
|
39
|
+
yield TTSAudioRawFrame(self.pcm, self.rate, 1, context_id=context_id)
|
|
40
|
+
|
|
41
|
+
async def process_frame(self, frame: Frame, direction: FrameDirection):
|
|
42
|
+
if isinstance(frame, StartFrame):
|
|
43
|
+
self.started = True
|
|
44
|
+
await super().process_frame(frame, direction)
|
|
45
|
+
|
|
46
|
+
async def cleanup(self):
|
|
47
|
+
self.cleaned = True
|
|
48
|
+
await super().cleanup()
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
class Sink(FrameProcessor):
|
|
52
|
+
"""Collects everything that passes through, and passes it on."""
|
|
53
|
+
|
|
54
|
+
def __init__(self):
|
|
55
|
+
super().__init__()
|
|
56
|
+
self.frames: list[Frame] = []
|
|
57
|
+
|
|
58
|
+
async def process_frame(self, frame: Frame, direction: FrameDirection):
|
|
59
|
+
await super().process_frame(frame, direction)
|
|
60
|
+
self.frames.append(frame)
|
|
61
|
+
await self.push_frame(frame, direction)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
async def make_service(inner: FakeInnerTTS | None = None, **kwargs):
|
|
65
|
+
"""A started EchoTTSService over a fake inner, wired to a sink."""
|
|
66
|
+
import tempfile
|
|
67
|
+
from pathlib import Path
|
|
68
|
+
|
|
69
|
+
from pipecat_echo_tts.cache import EchoCache
|
|
70
|
+
from pipecat_echo_tts.service import EchoTTSService
|
|
71
|
+
|
|
72
|
+
tmp = tempfile.mkdtemp()
|
|
73
|
+
service = EchoTTSService(
|
|
74
|
+
tts=inner or FakeInnerTTS(), cache=EchoCache(Path(tmp) / "cache"), **kwargs
|
|
75
|
+
)
|
|
76
|
+
sink = Sink()
|
|
77
|
+
task_manager = TaskManager(loop=asyncio.get_running_loop())
|
|
78
|
+
setup = FrameProcessorSetup(
|
|
79
|
+
clock=SystemClock(), task_manager=task_manager, pipeline_worker=None
|
|
80
|
+
)
|
|
81
|
+
for p in (service, sink):
|
|
82
|
+
await p.setup(setup)
|
|
83
|
+
for a, b in pairwise((service, sink)):
|
|
84
|
+
a.link(b)
|
|
85
|
+
start = StartFrame(audio_in_sample_rate=SAMPLE_RATE, audio_out_sample_rate=SAMPLE_RATE)
|
|
86
|
+
await service.queue_frame(start, FrameDirection.DOWNSTREAM)
|
|
87
|
+
await asyncio.sleep(0.05)
|
|
88
|
+
return service, sink
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
async def send(processor: FrameProcessor, frame: Frame, direction=FrameDirection.DOWNSTREAM):
|
|
92
|
+
await processor.queue_frame(frame, direction)
|
|
93
|
+
await asyncio.sleep(0.02)
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
async def spoken(service, text: str) -> list[TTSAudioRawFrame]:
|
|
97
|
+
"""Run the service's run_tts and return the audio frames it yielded."""
|
|
98
|
+
out = []
|
|
99
|
+
async for frame in service.run_tts(text, "ctx-test"):
|
|
100
|
+
if isinstance(frame, TTSAudioRawFrame):
|
|
101
|
+
out.append(frame)
|
|
102
|
+
return out
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
"""The cache: keys, roundtrip, rate from the wav header."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
|
|
7
|
+
from pipecat_echo_tts.cache import EchoCache, filename_for, normalize
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def test_normalize_lowercases_and_collapses_whitespace():
|
|
11
|
+
assert normalize(" Hello there, World! ") == "hello there, world!"
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def test_roundtrip(tmp_path: Path):
|
|
15
|
+
cache = EchoCache(tmp_path / "c")
|
|
16
|
+
cache.put("Sure, I can help you with that.", b"\x01\x02", 24000)
|
|
17
|
+
assert cache.get("Sure, I can help you with that.") == (b"\x01\x02", 24000)
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def test_key_is_normalized_so_casing_and_spaces_hit(tmp_path: Path):
|
|
21
|
+
cache = EchoCache(tmp_path / "c")
|
|
22
|
+
cache.put("Perfect, you're all set.", b"\x01\x02", 24000)
|
|
23
|
+
assert cache.get("perfect, you're all set.") == (b"\x01\x02", 24000)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def test_rate_comes_from_the_wav_header_not_the_key(tmp_path: Path):
|
|
27
|
+
"""The same phrase cached at a different rate is a different file, same key."""
|
|
28
|
+
cache = EchoCache(tmp_path / "c")
|
|
29
|
+
cache.put("Hello there.", b"\x01\x02", 16000)
|
|
30
|
+
cache.put("Hello there.", b"\x03\x04", 24000)
|
|
31
|
+
assert cache.get("Hello there.") in [(b"\x01\x02", 16000), (b"\x03\x04", 24000)]
|
|
32
|
+
assert len(list((tmp_path / "c").glob("*.wav"))) == 2
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def test_put_is_idempotent(tmp_path: Path):
|
|
36
|
+
cache = EchoCache(tmp_path / "c")
|
|
37
|
+
cache.put("Same phrase.", b"\x01\x02", 24000)
|
|
38
|
+
cache.put("Same phrase.", b"\x09\x09", 24000)
|
|
39
|
+
assert cache.get("Same phrase.") == (b"\x01\x02", 24000)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def test_empty_pcm_is_not_stored(tmp_path: Path):
|
|
43
|
+
cache = EchoCache(tmp_path / "c")
|
|
44
|
+
cache.put("Empty.", b"", 24000)
|
|
45
|
+
assert cache.get("Empty.") is None
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def test_missing_phrase_returns_none(tmp_path: Path):
|
|
49
|
+
cache = EchoCache(tmp_path / "c")
|
|
50
|
+
assert cache.get("Never cached.") is None
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def test_corrupt_file_is_treated_as_miss_and_removed(tmp_path: Path):
|
|
54
|
+
"""A crash-mid-write file must not poison the key forever."""
|
|
55
|
+
cache = EchoCache(tmp_path / "c")
|
|
56
|
+
name = filename_for("Hello, thank you for calling.", 24000)
|
|
57
|
+
(tmp_path / "c" / name).write_bytes(b"garbage not a wav")
|
|
58
|
+
assert cache.get("Hello, thank you for calling.") is None
|
|
59
|
+
assert not (tmp_path / "c" / name).exists() # removed, not just skipped
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def test_hand_seeding_with_a_real_wav(tmp_path: Path):
|
|
63
|
+
import wave as _wave
|
|
64
|
+
|
|
65
|
+
cache = EchoCache(tmp_path / "c")
|
|
66
|
+
name = filename_for("Hello, thank you for calling.", 24000)
|
|
67
|
+
with _wave.open(str(tmp_path / "c" / name), "wb") as wf:
|
|
68
|
+
wf.setnchannels(1)
|
|
69
|
+
wf.setsampwidth(2)
|
|
70
|
+
wf.setframerate(24000)
|
|
71
|
+
wf.writeframes(b"\x01\x02")
|
|
72
|
+
assert cache.get("hello, thank you for calling.") == (b"\x01\x02", 24000)
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
"""The service: cache hit serves without the inner, miss synthesizes and stores."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from pipecat.frames.frames import ErrorFrame, TTSAudioRawFrame
|
|
6
|
+
|
|
7
|
+
from tests.conftest import PCM, SAMPLE_RATE, FakeInnerTTS, make_service, spoken
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
async def test_miss_delegates_to_inner_and_stores():
|
|
11
|
+
inner = FakeInnerTTS()
|
|
12
|
+
service, _ = await make_service(inner)
|
|
13
|
+
out = await spoken(service, "Sure, I can help you with that.")
|
|
14
|
+
assert [f.audio for f in out] == [PCM]
|
|
15
|
+
assert [f.sample_rate for f in out] == [SAMPLE_RATE]
|
|
16
|
+
assert inner.calls == ["Sure, I can help you with that."]
|
|
17
|
+
assert service.misses == 1 and service.hits == 0
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
async def test_hit_serves_from_cache_without_the_inner():
|
|
21
|
+
inner = FakeInnerTTS()
|
|
22
|
+
service, _ = await make_service(inner)
|
|
23
|
+
await spoken(service, "Sure, I can help you with that.") # miss, fills cache
|
|
24
|
+
out = await spoken(service, "Sure, I can help you with that.") # hit
|
|
25
|
+
assert inner.calls == ["Sure, I can help you with that."] # inner called ONCE
|
|
26
|
+
assert [f.audio for f in out] == [PCM]
|
|
27
|
+
assert service.hits == 1 and service.chars_served == len("Sure, I can help you with that.")
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
async def test_hit_is_case_and_whitespace_insensitive():
|
|
31
|
+
service, _ = await make_service()
|
|
32
|
+
await spoken(service, "Perfect, you're all set.")
|
|
33
|
+
out = await spoken(service, "perfect, you're ALL SET.")
|
|
34
|
+
assert len(out) == 1
|
|
35
|
+
assert service.misses == 1 and service.hits == 1
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
async def test_start_frame_is_forwarded_to_the_inner():
|
|
39
|
+
inner = FakeInnerTTS()
|
|
40
|
+
await make_service(inner)
|
|
41
|
+
assert inner.started, "the inner service must be started by the wrapper"
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
async def test_cleanup_is_forwarded_to_the_inner():
|
|
45
|
+
inner = FakeInnerTTS()
|
|
46
|
+
service, _ = await make_service(inner)
|
|
47
|
+
await service.cleanup()
|
|
48
|
+
assert inner.cleaned
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
async def test_stats_shape():
|
|
52
|
+
service, _ = await make_service()
|
|
53
|
+
await spoken(service, "Hello, thank you for calling.")
|
|
54
|
+
s = service.stats
|
|
55
|
+
assert s["hits"] == 0 and s["misses"] == 1
|
|
56
|
+
assert s["phrases_cached"] == 1
|
|
57
|
+
await spoken(service, "Hello, thank you for calling.")
|
|
58
|
+
assert service.stats["hits"] == 1
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
async def test_inner_errors_pass_through(tmp_path):
|
|
62
|
+
"""An ErrorFrame from the inner reaches the caller, and nothing is cached."""
|
|
63
|
+
|
|
64
|
+
class BrokenInner(FakeInnerTTS):
|
|
65
|
+
async def run_tts(self, text: str, context_id: str):
|
|
66
|
+
yield ErrorFrame(error="provider down")
|
|
67
|
+
|
|
68
|
+
inner = BrokenInner()
|
|
69
|
+
service, _ = await make_service(inner)
|
|
70
|
+
out = await spoken(service, "Whatever.")
|
|
71
|
+
assert len(out) == 0 # no audio, no crash
|
|
72
|
+
assert service.stats["phrases_cached"] == 0
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
async def test_non_mono_audio_is_served_but_not_cached():
|
|
76
|
+
"""The wav cache is mono 16-bit by design: multi-channel audio must not
|
|
77
|
+
enter it, or a later hit would replay it mangled."""
|
|
78
|
+
|
|
79
|
+
class StereoInner(FakeInnerTTS):
|
|
80
|
+
async def run_tts(self, text: str, context_id: str):
|
|
81
|
+
self.calls.append(text)
|
|
82
|
+
yield TTSAudioRawFrame(self.pcm, self.rate, 2, context_id=context_id)
|
|
83
|
+
|
|
84
|
+
inner = StereoInner()
|
|
85
|
+
service, _ = await make_service(inner)
|
|
86
|
+
out = await spoken(service, "Whatever works.")
|
|
87
|
+
assert len(out) == 1 # served to the pipeline untouched
|
|
88
|
+
assert inner.calls == ["Whatever works."]
|
|
89
|
+
assert service.stats["phrases_cached"] == 0 # but not cached
|
|
90
|
+
# A repeat is still a miss (nothing was cached): the inner runs again.
|
|
91
|
+
await spoken(service, "Whatever works.")
|
|
92
|
+
assert service.misses == 2 and service.hits == 0
|