Metadata-Version: 2.5
Name: livekit-plugins-tts-cache-router
Version: 0.1.0
Summary: LiveKit Agents plugin for tts-cache-router, a caching TTS router for Sarvam, Raya and ElevenLabs
Project-URL: Homepage, https://ttscacherouter.dev
Project-URL: Documentation, https://docs.ttscacherouter.dev/livekit
Project-URL: Source, https://github.com/talqing/tts-cache-router
Author: Oggnai Technologies Private Limited
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,audio,cache,elevenlabs,livekit,raya,realtime,sarvam,tts,voice
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10.0
Requires-Dist: livekit-agents>=1.8.5
Description-Content-Type: text/markdown

# livekit-plugins-tts-cache-router

[LiveKit Agents](https://github.com/livekit/agents) plugin for
[tts-cache-router](https://ttscacherouter.dev): Sarvam, Raya and ElevenLabs text-to-speech,
with every sentence your agent 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/livekit](https://docs.ttscacherouter.dev/livekit).

## Install

```bash
pip install livekit-plugins-tts-cache-router
```

## Usage

```python
from livekit.plugins import tts_cache_router

tts = tts_cache_router.TTS(
    provider=tts_cache_router.Sarvam(model="bulbul:v3", speaker="shubh", language="hi-IN"),
)
# or
tts = tts_cache_router.TTS(
    provider=tts_cache_router.Raya(
        model="standard", voice_id="d6a002d0-230c-49b1-a137-b8a7d564b1ae", language="hi"
    ),
)
# or
tts = tts_cache_router.TTS(
    provider=tts_cache_router.ElevenLabs(voice_id="JBFqnCBsd6RMkjVDRZzb", model="eleven_flash_v2_5"),
)

session = AgentSession(tts=tts, ...)
```

Before the first request, store your Sarvam, Raya or ElevenLabs API key in the dashboard at
[ttscacherouter.dev](https://ttscacherouter.dev/dashboard/provider-keys). The router keeps it
encrypted and uses it only to call that provider for your requests.

Set `TTS_CACHE_ROUTER_API_KEY` to your router API key, from the same dashboard (or pass
`api_key=`).

### `TTS(...)`

| Argument | Default | |
|---|---|---|
| `provider` | required | `Sarvam(...)`, `Raya(...)` or `ElevenLabs(...)` |
| `api_key` | `$TTS_CACHE_ROUTER_API_KEY` | router API key |
| `base_url` | `wss://api.ttscacherouter.dev` | set to your own router when self-hosting |
| `sample_rate` | `24000` | 8000, 16000, 22050 or 24000; ElevenLabs also 32000, 44100 or 48000 |

How long cached audio is kept is your org's retention setting, in the dashboard.

### `Sarvam(...)`

`model` (`"bulbul:v3"` or `"bulbul:v4-flash"`), `speaker`, `language` (e.g. `"hi-IN"`),
`pace` (0.5–2.0, default 1.0), `temperature` (0.01–1.0, default 0.6), `dict_id`, and for
`bulbul:v4-flash` only: `pitch` (-0.5–0.5), `loudness` (0.1–2.5), `enable_preprocessing`;
`min_buffer_size` (30–200) and `max_chunk_length` (50–500; by default each sentence is
synthesized whole).

### `Raya(...)`

`model` (`"standard"` or `"m1"`), `voice_id`, `language` (e.g. `"hi"`), `speed` (0.5–1.5,
default 1.0).

### `ElevenLabs(...)`

The settings of ElevenLabs' own LiveKit plugin: `voice_id`, `model` (default
`"eleven_turbo_v2_5"`; `eleven_v3` and `eleven_v4` models go through ElevenLabs' text-to-dialogue
API), `language` (optional; `"en-US"` or `"english"` is sent as `"en"`, as ElevenLabs' plugin
sends it), `voice_settings` (`VoiceSettings(stability, similarity_boost,
style=None, speed=None, use_speaker_boost=None)`; the voice's stored settings when omitted),
`apply_text_normalization` (`"auto"`, `"on"` or `"off"`), `apply_language_text_normalization`,
`enable_ssml_parsing`, `enable_logging`, `pronunciation_dictionary_locators`
(`PronunciationDictionaryLocator(pronunciation_dictionary_id, version_id)`, up to 3),
`sync_alignment` (default `True`: word-level timed transcripts) and `preferred_alignment`
(`"normalized"` or `"original"`).

### Changing settings mid-session

```python
tts.update_options(speaker="priya", pace=1.1)  # the current provider's settings, by name
tts.update_options(provider=tts_cache_router.Raya(...))  # or another provider
```

Replies that start afterwards use the new settings.

### Interruptions

When the agent is interrupted, the plugin cancels the router segment and keeps the connection open,
so the next reply starts on a warm connection.

### Metrics

`TTSMetrics.characters_count` counts only characters the provider synthesized (and billed) for
the request; sentences served from the cache count zero. `provider` and `model` report the
underlying provider, so usage dashboards attribute cost correctly.
