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.
@@ -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,9 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ .echo_cache/
5
+ .env
6
+ dist/
7
+ *.egg-info/
8
+ .pytest_cache/
9
+ .ruff_cache/
@@ -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
+ [![PyPI](https://img.shields.io/pypi/v/pipecat-echo-tts?cacheSeconds=3600)](https://pypi.org/project/pipecat-echo-tts)
32
+ [![Python](https://img.shields.io/pypi/pyversions/pipecat-echo-tts)](https://pypi.org/project/pipecat-echo-tts)
33
+ [![License](https://img.shields.io/badge/license-BSD--2--Clause-blue)](LICENSE)
34
+ [![Pipecat](https://img.shields.io/Pipecat-1.15.1-brightgreen)](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
+ [![PyPI](https://img.shields.io/pypi/v/pipecat-echo-tts?cacheSeconds=3600)](https://pypi.org/project/pipecat-echo-tts)
11
+ [![Python](https://img.shields.io/pypi/pyversions/pipecat-echo-tts)](https://pypi.org/project/pipecat-echo-tts)
12
+ [![License](https://img.shields.io/badge/license-BSD--2--Clause-blue)](LICENSE)
13
+ [![Pipecat](https://img.shields.io/Pipecat-1.15.1-brightgreen)](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,2 @@
1
+ # Makes `tests` a regular package: a stray top-level `tests` package in
2
+ # site-packages otherwise shadows this directory (PEP 420 namespace loses).
@@ -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