pipecat-sonex 0.1.0

SonexLabs TTS service for pipecat-ai real-time voice pipelines

pipecat-sonex

SonexLabs TTS for pipecat-ai real-time voice pipelines.

---

pipecat-sonex provides SonexTTSService — a pipecat-native TTS service that connects any pipecat pipeline to the SonexLabs 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

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

---

Quick start

1. List available voices

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

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:

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:

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/ 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:

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

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

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:

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.

---

License

MIT — see LICENSE.