Metadata-Version: 2.4
Name: pipecat-sonex
Version: 0.1.0
Summary: SonexLabs TTS service for pipecat-ai real-time voice pipelines
Project-URL: Homepage, https://sonexlabs.com
Project-URL: Documentation, https://docs.sonexlabs.com
Project-URL: Repository, https://github.com/sonexlabs/pipecat-sonex
Project-URL: Bug Tracker, https://github.com/sonexlabs/pipecat-sonex/issues
Author-email: SonexLabs <hi@sonexlabs.com>
License: MIT
License-File: LICENSE
Keywords: pipecat,sonexlabs,streaming,tts,voice-ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: pipecat-ai>=1.1.0
Description-Content-Type: text/markdown

# pipecat-sonex

> **SonexLabs TTS** for [pipecat-ai](https://github.com/pipecat-ai/pipecat) real-time voice pipelines.

[![PyPI](https://img.shields.io/pypi/v/pipecat-sonex)](https://pypi.org/project/pipecat-sonex/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

`pipecat-sonex` provides `SonexTTSService` — a pipecat-native TTS service that connects any pipecat pipeline to the [SonexLabs](https://sonexlabs.com) Panini TTS API.

`SonexTTSService` extends pipecat's official `TTSService` base class, so it works exactly like `CartesiaTTSService`, `ElevenLabsTTSService`, and other first-party services:

- The base class handles **sentence aggregation**, **LLM token buffering**, **interruption recovery**, **TTSStartedFrame / TTSStoppedFrame**, and **metrics**.
- You only need to configure credentials and voice.
- Voice and language can be **changed mid-conversation** via `TTSUpdateSettingsFrame`.

---

## Installation

```bash
pip install pipecat-sonex
# or
uv add pipecat-sonex
```

---

## Quick start

### 1. List available voices

```bash
curl https://api.sonexlabs.com/v1/voices \
  -H "Authorization: Bearer $SONEX_API_KEY"
```

Copy a `voice_id` from the response — it is **required**.

### 2. Add to your pipeline

```python
from pipecat_sonex import SonexTTSService

tts = SonexTTSService(
    api_key="vsk_...",
    voice="en-US-male-1",   # required — no default
    language="en",          # optional
    sample_rate=24000,      # 24000 for WebRTC, 8000 for telephony
)
```

Drop it into any pipeline the same way as any other pipecat TTS service:

```python
pipeline = Pipeline([
    transport.input(),
    stt,
    context_aggregator.user(),
    llm,
    tts,                    # ← SonexTTSService here
    transport.output(),
    context_aggregator.assistant(),
])
```

---

## Constructor parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | `str` | — | SonexLabs API key (`vsk_...`) |
| `voice` | `str` | — | **Required.** Voice ID from `GET /v1/voices` |
| `language` | `str` | `""` | BCP-47 tag (`"en"`, `"hi"`, `"te"`, …). Omit to auto-detect. |
| `speed` | `float` | `1.0` | Speech rate multiplier (practical range: 0.75–1.5) |
| `sample_rate` | `int` | `24000` | Output PCM rate. Use `8000` for Twilio/Exotel telephony. |
| `endpoint` | `str` | `https://api.sonexlabs.com` | API base URL |
| `settings` | `SonexTTSSettings` | `None` | Runtime-updatable settings (takes precedence) |

---

## Runtime settings update

Change voice or language mid-conversation:

```python
from pipecat.frames.frames import TTSUpdateSettingsFrame
from pipecat_sonex import SonexTTSSettings

await task.queue_frames([
    TTSUpdateSettingsFrame(delta=SonexTTSSettings(voice="hi-IN-female-1", language="hi"))
])
```

---

## Examples

All examples are in the [`examples/`](examples/) directory.  Copy `.env.example` to `.env` and fill in your credentials before running.

### WebRTC + OpenAI LLM

Full browser-to-server voice bot using SmallWebRTC transport:

```bash
pip install "pipecat-ai[openai,deepgram,silero,webrtc]" pipecat-sonex python-dotenv fastapi uvicorn
python examples/webrtc_openai.py
# Open http://localhost:7860 and click Connect
```

### Twilio telephony

```bash
pip install "pipecat-ai[openai,deepgram,silero,twilio]" pipecat-sonex python-dotenv fastapi uvicorn
python examples/telephony_twilio.py
# Expose with ngrok, point Twilio webhook to https://<host>/incoming-call
```

### Exotel telephony

```bash
pip install "pipecat-ai[openai,deepgram,silero]" pipecat-sonex python-dotenv fastapi uvicorn
python examples/telephony_exotel.py
# Expose with ngrok, set Exotel Passthru URL to wss://<host>/ws/exotel
```

### Vobiz telephony

`VobizFrameSerializer` is bundled in `pipecat_sonex.vobiz` — no extra package needed:

```bash
pip install "pipecat-ai[openai,deepgram,silero]" pipecat-sonex python-dotenv fastapi uvicorn
python examples/telephony_vobiz.py
# Set Vobiz WebSocket URL to wss://<host>/ws/vobiz
```

---

## API reference

See the full API documentation at [docs.sonexlabs.com/api-reference](https://docs.sonexlabs.com/api-reference).

---

## License

MIT — see [LICENSE](LICENSE).
