pipecat-plugins-relay-speech 0.1.0

Pipecat plugin for Relay Speech — universal TTS adapter with sentence-level caching

pipecat-plugins-relay-speech

Pipecat TTS service backed by a Relay Speech server — a universal TTS adapter that routes synthesis through Cartesia, ElevenLabs, Sarvam, and other providers behind a single API, with built-in sentence-level LRU caching.

This plugin is the Pipecat counterpart of livekit-plugins-relay-speech. Same wire protocol, same caching benefits, same options surface.

Install

pip install pipecat-plugins-relay-speech

Usage — streaming (recommended)

from pipecat.pipeline.pipeline import Pipeline
from pipecat_relay_speech import RelaySpeechTTSService

tts = RelaySpeechTTSService(
    provider="cartesia",
    voice_id="YOUR_VOICE_ID",
    model="sonic-3",
    language="en",
    api_key="YOUR_CARTESIA_KEY",         # or set CARTESIA_API_KEY
    relay_speech_api_key="YOUR_KEY",     # or set RELAY_SPEECH_API_KEY
)

pipeline = Pipeline([..., llm, tts, transport.output()])

Pipecat aggregates LLM tokens into complete sentences before calling run_tts(...), and each sentence is shipped over a single shared WebSocket to Relay Speech. The server performs an LRU cache lookup before touching the upstream provider — repeated phrases return instantly with zero provider spend.

Usage — one-shot HTTP

from pipecat_relay_speech import RelaySpeechHttpTTSService

tts = RelaySpeechHttpTTSService(
    provider="elevenlabs",
    voice_id="YOUR_VOICE_ID",
    model="eleven_flash_v2_5",
    api_key="YOUR_ELEVENLABS_KEY",
    relay_speech_api_key="YOUR_KEY",
)

Useful for batch synthesis where the cost of holding a WebSocket open isn't worth it.

Options

All options mirror the LiveKit plugin:

Option	Description
provider	"cartesia", "elevenlabs", "sarvam"
voice_id	Provider-specific voice id
model	TTS model (e.g. "sonic-3")
language	BCP-47 (e.g. "en", "hi-IN")
speed	-1.0 … 1.0, 0.0 = normal
volume	0.5 … 2.0, 1.0 = normal
emotion	Provider emotion tags (Cartesia sonic-3)
pronunciation_dict_id	Custom pronunciation dictionary id
duration	Target audio duration (Cartesia sonic-3)
max_buffer_delay_ms	Max client-side buffer delay
add_timestamps / add_phoneme_timestamps / use_normalized_timestamps	Timestamp controls
sample_rate	PCM sample rate, default 24000 Hz
reserve_pool	Pin a dedicated cache slot for this voice/model
base_url	Override the Relay Speech endpoint (default production)

Override the endpoint via the RELAY_SPEECH_BASE_URL env var when pointing at a non-default deployment (e.g. a local OpenTTS instance).

Wire protocol

Identical to the LiveKit plugin:

• WebSocket: wss://api.relayspeech.com/v1/tts/ws?provider=…&api_key=…&relay_speech_key=…
  • Send: one JSON message per complete sentence (continue_context=True)
  • Receive: binary PCM S16LE frames, plus JSON control frames (done, error, heartbeat, cancelled)
• HTTP: POST {base_url}/v1/tts with the same body shape

Authentication is dual: the provider key (api_key) authenticates Relay Speech against the upstream provider, while the Relay Speech key (relay_speech_key) authenticates you against the Relay Speech backend and is used for usage logging.

License

Apache-2.0.