Metadata-Version: 2.4
Name: relayspeech
Version: 0.1.0
Summary: Official Python SDK for the Relay Speech (OpenTTS) API — one client, all TTS providers.
License: MIT
License-File: LICENSE
Keywords: tts,text-to-speech,relay-speech,opentts,cartesia,elevenlabs,sarvam
Author: Vaibhav Gupta
Author-email: vaibhav.gupta2@insurancedekho.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: httpx (>=0.27.0,<1.0.0)
Requires-Dist: pydantic (>=2.7.0,<3.0.0)
Requires-Dist: websockets (>=12.0,<15.0)
Description-Content-Type: text/markdown

# Relay Speech — Python SDK

Official Python client for the [Relay Speech](https://relayspeech.ai) (OpenTTS) gateway.
One API, all TTS providers — Cartesia, ElevenLabs, Sarvam, and more.

```bash
pip install relayspeech
```

## Quickstart

```python
from relayspeech import RelaySpeech

client = RelaySpeech(
    api_key="rs_live_...",            # your Relay Speech key
    provider="cartesia",              # default provider
    provider_api_key="sk-cartesia-..."
)

audio = client.tts.bytes(
    text="Hello from Relay Speech.",
    voice_id="694f9389-aac1-45b6-b726-9d9369183238",
)
open("hello.pcm", "wb").write(audio)
```

Environment variables (`RELAY_SPEECH_API_KEY`, `CARTESIA_API_KEY`, `ELEVENLABS_API_KEY`, `SARVAM_API_KEY`)
are picked up automatically.

## REST streaming

```python
with open("out.pcm", "wb") as f:
    for chunk in client.tts.stream(text="Streaming demo.", voice_id="..."):
        f.write(chunk)
```

## Async

```python
from relayspeech import AsyncRelaySpeech

async with AsyncRelaySpeech(api_key="...", provider="elevenlabs",
                            provider_api_key="...") as client:
    async for chunk in await client.tts.stream(text="Hi", voice_id="..."):
        ...
```

## WebSocket (low-latency, full duplex)

```python
async with AsyncRelaySpeech(api_key="...", provider="cartesia",
                            provider_api_key="...") as client:
    async with client.tts.websocket() as ws:
        async for chunk in await ws.send(
            text="One sentence at a time.",
            voice_id="...",
            enable_cache=True,
        ):
            speaker.write(chunk)
```

Reuse the same `ws` for many sentences — the gateway holds the upstream provider
connection open and caches each chunk independently.

## Output format

```python
from relayspeech import OutputFormat, AudioContainer, AudioEncoding

audio = client.tts.bytes(
    text="…",
    voice_id="…",
    output_format=OutputFormat(
        container=AudioContainer.WAV,
        encoding=AudioEncoding.PCM_S16LE,
        sample_rate=24000,
    ),
)
```

## Errors

| Exception                      | When                                              |
|--------------------------------|---------------------------------------------------|
| `RelaySpeechAuthError`         | Invalid / missing Relay Speech key (401)         |
| `RelaySpeechProviderError`     | Upstream provider failed (5xx)                    |
| `RelaySpeechAPIError`          | Any other non-2xx response                        |
| `RelaySpeechConnectionError`   | Network / WebSocket transport failure             |

All inherit from `RelaySpeechError`.

