Integrations

Pipecat

SonexTTSService extends Pipecat's official TTSService base class, so it works exactly like CartesiaTTSService or ElevenLabsTTSService — drop it into any Pipecat transport (SmallWebRTC, FastAPI WebSocket, Twilio, Exotel, Vobiz); no Daily required.

GitHub: pipecat-sonex
Source, examples, and PyPI package for the Pipecat plugin.

Install

pip install pipecat-ai pipecat-sonex

Requires Python 3.10+. Tested with pipecat-ai v1.7.0.

Basic usage

from pipecat_sonex import SonexTTSService

tts = SonexTTSService(
    api_key="vsk_...",        # or set SONEX_API_KEY env var
    voice="9b8fsavyez",       # from GET /v1/voices — required, no default
)

# Drop into any pipeline, same as any other pipecat TTS service
pipeline = Pipeline([
    transport.input(),
    stt,
    context_aggregator.user(),
    llm,
    tts,                      # ← SonexTTSService here
    transport.output(),
    context_aggregator.assistant(),
])

Configuration

api_keystrRequired

SonexLabs API key (vsk_...). Falls back to SONEX_API_KEY env var.

voicestrRequired

Voice ID from GET /v1/voices. No default.

languagestrOptional

Leave unset — Pāṇini TTS auto-detects language from the input text.

speedfloatOptional

Speaking rate multiplier. Practical range 0.75–1.5. Default 1.0.

sample_rateintOptional

Pipeline output rate in Hz. Not sent to the API — pipecat resamples to this value. Default 24000. Use 8000 for telephony.

endpointstrOptional

API base URL. Default https://api.sonexlabs.com.

settingsSonexTTSSettingsOptional

Runtime-updatable settings, takes precedence over constructor args.

How it works

The processor buffers LLMTextFrame tokens until a sentence boundary, then:

  1. POSTs { "input": "...", "voice": "...", "response_format": "wav" } to the /v1/speech/stream endpoint
  2. Releases the inference lock at TTFB; the GPU is free and the next sentence can start immediately
  3. Streams the chunked WAV response, parsing PCM data as it arrives to minimize time-to-first-audio
  4. Pushes TTSAudioRawFrame frames downstream to the transport at the configured sample rate

A pooled aiohttp.ClientSession (via TCPConnector keep-alive) reuses connections across requests instead of reconnecting per sentence. It also handles TTSSpeakFrame for direct synthesis, strips markdown formatting, and skips non-speakable tokens.

Full pipeline example (WebRTC)

import os, asyncio
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat.services.groq.llm import GroqLLMService
from pipecat.audio.vad.silero import SileroVADAnalyzer
from pipecat.transports.base_transport import TransportParams
from pipecat.transports.smallwebrtc.transport import SmallWebRTCTransport
from pipecat_sonex import SonexTTSService

async def run_bot(webrtc_connection, stt):
    transport = SmallWebRTCTransport(
        webrtc_connection,
        params=TransportParams(
            audio_in_enabled=True,
            audio_out_enabled=True,
            vad_analyzer=SileroVADAnalyzer(),
        ),
    )

    llm = GroqLLMService(
        api_key=os.getenv("GROQ_API_KEY"),
        model="llama-3.3-70b-versatile",
    )

    tts = SonexTTSService(
        api_key=os.getenv("SONEX_API_KEY"),
        voice=os.getenv("SONEX_VOICE_ID"),
        speed=1.0,
        sample_rate=16000,
    )

    pipeline = Pipeline([
        transport.input(),
        stt,
        llm,
        tts,
        transport.output(),
    ])

    runner = PipelineRunner()
    await runner.run(PipelineTask(
        pipeline,
        params=PipelineParams(allow_interruptions=True),
    ))

Telephony (Twilio / Exotel / Vobiz)

Set sample_rate=8000 to match the telephony μ-law transport output rate. Pipecat's SOXR resampler handles 24 kHz → 8 kHz downsampling transparently. VobizFrameSerializer ships bundled in pipecat_sonex.vobiz — no extra package needed.

tts = SonexTTSService(
    api_key=os.getenv("SONEX_API_KEY"),
    voice="9b8fsavyez",
    sample_rate=8000,
)

Environment variables

SONEX_API_KEY=vsk_your_key_here
SONEX_VOICE_ID=your_voice_id