pipecat-tts-cache-router

Pipecat TTS service for tts-cache-router: Sarvam, Raya, ElevenLabs, OpenAI, Deepgram, xAI, Soniox, Smallest AI and Cartesia text-to-speech, with every sentence your bot has said before served from a per-account cache.

Same output whether you call the provider directly or through the router: each sentence reaches the provider verbatim with your exact settings, and a cache hit replays a real provider take for that exact request.

Full documentation: docs.ttscacherouter.dev/pipecat. For LLMs and coding agents: llms.txt, and this page as Markdown at pipecat.md.

Tested with Pipecat v1.12.0. Maintained by Oggnai Technologies, the company that runs tts-cache-router.

Install

pip install pipecat-tts-cache-router

Usage

import os

from pipecat_tts_cache_router import TTSCacheRouterTTSService

tts = TTSCacheRouterTTSService(
    api_key=os.environ["TTS_CACHE_ROUTER_API_KEY"],
    settings=TTSCacheRouterTTSService.Settings(
        model="sarvam/bulbul:v3", voice="shubh", language="hi-IN"
    ),
)

pipeline = Pipeline(
    [transport.input(), stt, user_aggregator, llm, tts, transport.output(), assistant_aggregator]
)

Before the first request, store your Sarvam, Raya, ElevenLabs, OpenAI, Deepgram, xAI, Soniox, Smallest AI or Cartesia API key in the dashboard at ttscacherouter.dev. The router keeps it encrypted and uses it only to call that provider for your requests. Your bot authenticates with your router API key alone, from the same dashboard.

TTSCacheRouterTTSService(...)

Other keyword arguments go to Pipecat's WebsocketTTSService, except text_aggregation_mode: the router splits the text into sentences itself, so the service streams the LLM's text to it as it arrives.

TTSCacheRouterTTSService.Settings(...)

The settings are in the router's own names, the same for every provider:

Every provider's models, voices, languages and options are in Models and options. The router checks the settings when the pipeline starts, so a wrong one is reported then as an ErrorFrame.

Changing settings mid-session

from pipecat.frames.frames import TTSUpdateSettingsFrame

await worker.queue_frame(
    TTSUpdateSettingsFrame(delta=TTSCacheRouterTTSService.Settings(voice="priya"))
)

Replies that start afterwards use the new settings. A model of another provider starts from no language, speed or options unless the update gives them.

Interruptions

When the user interrupts, the service tells the router to stop the reply, and the provider stops the sentence it was synthesizing. The next reply starts on the same connection.

Transcripts

The service's TTSTextFrames follow the audio: each sentence's words as its audio starts, or word by word with ElevenLabs and Cartesia.

Metrics

With usage metrics on, each reply's TTSUsageMetricsData counts only the characters the provider synthesized (and billed); sentences served from the cache count zero. Its model is "<provider>/<model>".

Once a reply is all sent, the service also calls its on_cache_stats handlers with a CacheStats: the reply's context_id, sentences, cached_sentences, characters and billed_characters (and cached_characters, the difference):

@tts.event_handler("on_cache_stats")
async def on_cache_stats(tts, stats):
    print(stats.cached_sentences, "of", stats.sentences, "sentences from the cache")

An interrupted reply reports both too, counting the sentences the router sent in full before the interruption. This needs a router that reports them (the hosted router does); with an older one, the service logs an error and reports nothing for the interrupted reply.

Example

examples/pipecat_agent.py is a complete bot: Deepgram speech-to-text, an OpenAI LLM and this service, on Pipecat's local WebRTC runner. With TTS_CACHE_ROUTER_API_KEY, DEEPGRAM_API_KEY and OPENAI_API_KEY set:

cd examples
uv run pipecat_agent.py

Then open http://localhost:7860/client and talk to it.

License

Apache-2.0.