tts-cache-router docs

LiveKit Agents

Soniox with LiveKit

Soniox in a LiveKit agent: through our plugin, or through LiveKit's Soniox plugin with a changed URL.

With our plugin#

Soniox’s text to speech with the settings of LiveKit’s Soniox plugin. Each sentence of your agent’s reply is synthesized on its own and cached. The router calls Soniox’s US endpoint, so store a key from a Soniox project in the US region.

pip install livekit-plugins-tts-cache-router
agent.py
from livekit.plugins import tts_cache_router as tcr# The API key comes from TTS_CACHE_ROUTER_API_KEY.tts = tcr.TTS(    provider=tcr.Soniox(        language="en",        voice="Adrian",    ),)

Pass tts to AgentSession(tts=tts). Set TTS_CACHE_ROUTER_API_KEY in the agent’s environment, and store your Soniox key under Provider keys. The constructor of TTS itself is on the plugin’s page.

tcr.Soniox(...)#

languagestrRequired
The language the text is read in, e.g. en or hi. Soniox reads the text through this language’s pronunciation, so set it to the language of your agent’s replies.
modelstrDefault "tts-rt-v2"
The Soniox model.
voicestrDefault "Adrian"
A Soniox voice, e.g. Adrian or Nina, or a cloned voice’s id. Every voice speaks every language.
speedfloatDefault 1.0
Speaking rate, 0.7–1.3.
reduce_silencebool | NoneDefault None
Shorten the pauses between words. None leaves it to Soniox (off).

Every value the router accepts, and the languages per model, are in Models and options.

Changing settings#

Replies that start afterwards use the new settings:

Python
tts.update_options(voice="Nina", speed=1.1)

With LiveKit's Soniox plugin#

Keep livekit-plugins-soniox and point it at the router: your router API key in place of your Soniox key, and the router’s address. Nothing else changes.

pip install livekit-plugins-soniox
agent.py
import osfrom livekit.plugins import sonioxtts = soniox.TTS(    model="tts-rt-v2",    voice="Adrian",    language="en",    api_key=os.environ["TTS_CACHE_ROUTER_API_KEY"],    websocket_url="wss://api.ttscacherouter.dev/soniox/tts-websocket",)

Each sentence is a take of its own, so the pause between two sentences is shorter (about 0.2 s) than when Soniox’s plugin sends a whole reply into one stream (about 0.5 s). The first sentence starts as soon as it is complete; with Soniox’s plugin alone, Soniox waits for the next sentence or the end of the reply.

Pass model="tts-rt-v2" and a voice explicitly: Soniox’s plugin defaults to tts-rt-v1-preview, a deprecated alias, and to Maya, a voice tts-rt-v2 doesn’t have.

Each sentence is a Soniox stream of its own, one at a time per connection: the same Soniox concurrency as Soniox’s own plugin.

The router splits the reply into sentences and caches each one, with a few differences from Soniox’s own messages.

Requests, responses and errors keep Soniox’s own shape. The endpoints behind it are described in Soniox API drop-in.

Which to choose#

Both use your org's cache and your stored provider key, and sound the same.

  • Our plugin reports only the characters Soniox billed in LiveKit’s TTSMetrics (cache hits count zero), and lets you switch provider with update_options.
  • Soniox’s plugin is the smallest change to an agent that already uses it. Its metrics count every character, cached or not; the dashboard’s Usage page has the real split.