Metadata-Version: 2.4
Name: pipecat-plugins-relay-speech
Version: 0.1.0
Summary: Pipecat plugin for Relay Speech — universal TTS adapter with sentence-level caching
License: Apache-2.0
Requires-Python: >=3.10
Requires-Dist: aiohttp<4.0.0,>=3.9.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: pipecat-ai>=0.0.108
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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`](../livekit-plugins-relay-speech). Same wire
protocol, same caching benefits, same options surface.

## Install

```bash
pip install pipecat-plugins-relay-speech
```

## Usage — streaming (recommended)

```python
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

```python
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.
