pipecat-echo-tts 0.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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,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,8 @@
1
+ pipecat_echo_tts/__init__.py,sha256=VFm1jxF8DxbjagJanivKGQqGsd_Xa7MeEDemINKN5Og,562
2
+ pipecat_echo_tts/cache.py,sha256=ymQPWs-2TtfXXbDbojFbZ8gAmhBvD-GG9JdSg7kDvWQ,3277
3
+ pipecat_echo_tts/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
4
+ pipecat_echo_tts/service.py,sha256=sbPStZic1I6gPoyi6A8yJpTTbxB_NNKH3cjKl0wsaBY,5096
5
+ pipecat_echo_tts-0.1.1.dist-info/METADATA,sha256=UcjwHy4KdcGqKq71cEJcqwl-szrIMLniLlkazl4nkiU,5956
6
+ pipecat_echo_tts-0.1.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
7
+ pipecat_echo_tts-0.1.1.dist-info/licenses/LICENSE,sha256=W0Dssv9PJuaOK2TIJXTQ21LgJx-bKqRKPHJwJTtT9eM,1328
8
+ pipecat_echo_tts-0.1.1.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -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.