pipecat-sonex

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

Tested with Pipecat v1.7.0.

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.

Streaming and connection reuse

Requests go to SonexLabs' /v1/speech/stream endpoint, so audio is delivered as chunked HTTP as soon as each sentence is generated instead of waiting for the full utterance, reducing time-to-first-audio. The underlying aiohttp.ClientSession uses a TCPConnector with keepalive_timeout set, so connections are pooled and reused across requests rather than reconnecting for every sentence.

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="9b8fsavyez",     # Diya (English), from GET /v1/voices — required, no default
)

Language is optional — leave it unset and Panini auto-detects from the input text. For telephony (Twilio/Exotel/Vobiz), pass sample_rate=8000 — see Constructor parameters.

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

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="lkwlapu6ab"))  # Priya, from GET /v1/voices
])

Examples

All examples are in the examples/ directory. Copy .env.example to .env and fill in your credentials before running.

Minimal (foundational example)

The smallest possible pipeline — just speaks one line and exits:

pip install "pipecat-ai[webrtc]" pipecat-sonex python-dotenv fastapi uvicorn
python examples/01_say_one_thing.py
# Open http://localhost:7860/client/ and click Connect

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

LiveKit

For a LiveKit room-based voice bot example, see the separate pipecat-sonex-livekit repo.

API reference

See the full API documentation at docs.sonexlabs.com/api-reference.

License

MIT — see LICENSE.