pipecat-saidwire

Saidwire real-time speech-to-text for Pipecat.

SaidwireSTTService streams your user's audio to Saidwire over a WebSocket and pushes InterimTranscriptionFrames while they speak and a TranscriptionFrame when they finish. When your VAD decides the user stopped talking, the service sends Finalize, and the final transcript comes straight back, so turn-taking doesn't wait on a server-side pause.

Saidwire is English-only. Pricing is $0.30 per audio hour, billed per second of audio sent. Get a key at saidwire.com/dev.

This package is built and maintained by Saidwire, the company that runs the service.

Tested with Pipecat v1.15.0 (Python 3.11+).

Installation

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

Set your key:

export SAIDWIRE_API_KEY=your_key

Usage with a Pipecat pipeline

from pipecat.pipeline.pipeline import Pipeline
from pipecat_saidwire import SaidwireSTTService

stt = SaidwireSTTService()  # reads SAIDWIRE_API_KEY

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

Already have a Pipecat bot? Replace your current STT service with the stt = ... line. Nothing else changes.

Running the example

examples/bot.py is a complete voice agent (Saidwire STT, an OpenAI LLM, Cartesia TTS, Silero VAD) that you talk to from your browser:

pip install "pipecat-ai[webrtc,daily,silero,openai,cartesia,runner]" pipecat-saidwire
export SAIDWIRE_API_KEY=... OPENAI_API_KEY=... CARTESIA_API_KEY=...
python examples/bot.py
# open http://localhost:7860/client and start talking

examples/transcribe_file.py streams a WAV file through a pipeline in real time and prints the transcripts. It needs only a Saidwire key:

python examples/transcribe_file.py call.wav

How it behaves in a pipeline

Dropped connections reconnect with backoff. A bad or revoked key, or used-up credit, is reported once as a permanent error, with no retry loop. If the service answers "starting up" or "busy" (HTTP 503 or 429), the service waits for the Retry-After time and tries again, for up to warmup_timeout seconds (default 300). Audio sent while it waits is not transcribed.

Configuration

stt = SaidwireSTTService(
    api_key="...",  # default: $SAIDWIRE_API_KEY
    sample_rate=None,  # default: the pipeline's input rate
    settings=SaidwireSTTService.Settings(
        endpointing=None,  # server default; False = finals only from Finalize / long pauses
        interim_results=True,
        punctuate=True,
        early_words=False,  # True: on_early_word for each word as soon as it is committed
        vad_events=False,  # True: on_speech_started when the server hears speech begin
        utterance_end_ms=None,  # e.g. 1000: on_utterance_end after 1 s of silence
    ),
    vad_force_finalize=True,  # VADUserStoppedSpeakingFrame -> Finalize (recommended)
    warmup_timeout=300.0,
)

Constructor parameters:

Runtime Settings (change them with STTUpdateSettingsFrame):

Events

@stt.event_handler("on_early_word")
async def on_early_word(stt, word):
    # {"word": "cancel", "punctuated_word": "cancel.", "start": 6.84, "end": 7.29, ...}
    # Sent as soon as the word is committed, usually before the final that contains it.
    # Useful for keyword triggers ("stop", "cancel"). The final transcript is authoritative.
    ...


@stt.event_handler("on_speech_started")  # vad_events=True
async def on_speech_started(stt, message): ...


@stt.event_handler("on_utterance_end")  # utterance_end_ms set
async def on_utterance_end(stt, message): ...

Plus the standard on_connected, on_disconnected and on_connection_error. stt.request_id is the id of the current stream; include it when you contact support.

Protocol

Saidwire's streaming API uses the Deepgram-compatible /v1/listen protocol, so you can also point an existing /v1/listen client at wss://api.saidwire.com with your Saidwire key. This package adds Saidwire defaults and the extras above. API reference: saidwire.com/docs/api.

Development

uv sync --group dev        # or: pip install -e . pytest pytest-asyncio ruff
pytest                     # runs against a fake server on 127.0.0.1; no key, no network
ruff check . && ruff format --check .

Support

Open an issue on this repository, or email support@saidwire.com.

License

MIT. See LICENSE.