.wave Speech-to-Text

Streaming STT with WaveSTTService over .wave’s Deepgram-compatible WebSocket API, with interim results and multilingual support.

Overview

WaveSTTService provides streaming speech-to-text through .wave, over its /v1/listen WebSocket, a Deepgram-compatible streaming transcription endpoint. The service extends Pipecat’s WebsocketSTTService and pushes InterimTranscriptionFrame and TranscriptionFrame results into the pipeline. When the VAD reports the end of speech, it sends Finalize and marks the answering transcription as finalized.

Source Repository

Source code, README, and issues for the .wave integration

Example

Transcribe a browser microphone in a single file

.wave Socket Reference

Messages, parameters, languages, and close codes

.wave

Create an account and an API key

PyPI Package

The pipecat-dotwave package on PyPI

Installation

This is a community-maintained package distributed separately from pipecat-ai:

uv add pipecat-dotwave

Prerequisites

.wave Account Setup

Before using the .wave STT service, you need:

1. .wave Account: Sign up at dotwave.ai
2. API Key: Create an API key in the .wave console

Required Environment Variables

• DOTWAVE_API_KEY: Your .wave API key for authentication

Configuration

api_key · str · required

.wave API key, sent as Authorization: Token <key>.

base_url · str · default: "api.dotwave.ai"

API endpoint: a bare host, or a URL with a scheme such as ws://localhost:8080. A bare host uses wss.

encoding · str · default: "linear16"

Encoding sent on the socket: "linear16", "mulaw", or "alaw". Pipeline audio is converted as needed: linear16 is sent at 16 or 24 kHz (other rates are resampled to 16 kHz), mulaw and alaw at 8 kHz.

sample_rate · int · default: "None"

Sample rate of the incoming audio in Hz. If None, uses the pipeline’s input sample rate.

utterance_end_ms · int · default: "None"

Silence in milliseconds (1000 to 3200) after which the socket ends a segment on its own, sending a final with speech_final and an UtteranceEnd message. If None, segments end on Finalize, which the service sends when the VAD reports the end of speech.

interim_results · bool · default: "True"

Whether to receive interim results.

extra_headers · dict[str, str] · default: "None"

Additional headers for the WebSocket handshake. Merged after the default headers, so they can override them.

segment_finals · bool · default: "True"

Push one TranscriptionFrame per segment, holding the whole segment, with InterimTranscriptionFrames carrying the segment so far. False pushes one frame per socket result instead, often one word at a time. See “How results arrive” under Notes.

settings · WaveSTTService.Settings · default: "None"

Runtime-updatable settings. See Settings below.

ttfs_p99_latency · float · default: "None"

P99 latency from speech end to final transcript, in seconds, used by turn strategies. .wave has not measured this value for Pipecat, so Pipecat’s default applies if None. Measure your deployment with stt-benchmark and pass the result.

Settings

Runtime-configurable settings passed via the settings constructor argument using WaveSTTService.Settings(...). These can be updated mid-conversation with STTUpdateSettingsFrame; a change reconnects the socket.

Parameter	Type	Default	Description
model	str	"nemotron-asr-streaming"	Transcription model.
language	Language | str | None	None	Language to transcribe. None or "multi" selects automatic language detection.
extra	dict	{}	Additional query parameters, sent as given. A parameter the socket refuses is reported as an error.

Usage

Basic Setup

import os

from pipecat_dotwave import WaveSTTService

stt = WaveSTTService(api_key=os.getenv("DOTWAVE_API_KEY"))

# ... add stt to your pipeline, after a VAD

With a Language and a Segment Rule

import os

from pipecat.transcriptions.language import Language

from pipecat_dotwave import WaveSTTService

stt = WaveSTTService(
    api_key=os.getenv("DOTWAVE_API_KEY"),
    utterance_end_ms=1000,
    settings=WaveSTTService.Settings(language=Language.PT_BR),
)

Telephony Audio

import os

from pipecat_dotwave import WaveSTTService

stt = WaveSTTService(
    api_key=os.getenv("DOTWAVE_API_KEY"),
    encoding="mulaw",
)

Notes

• VAD required for timely finals: Put a VAD upstream of the service (a VADProcessor, or the user aggregator’s VAD). On VADUserStoppedSpeakingFrame the service sends Finalize, and the transcription that answers it is pushed with finalized=True.
• How results arrive: The socket sends a final as soon as words are settled, often one word at a time. By default the service collects them and pushes one TranscriptionFrame per segment. A segment ends when the socket answers Finalize (the frame is marked finalized), when a final is marked speech_final or an UtteranceEnd arrives (with utterance_end_ms), or when the service stops or reconnects with words pending. While a segment is open, each interim and each final pushes an InterimTranscriptionFrame with the segment so far, so turn strategies and RTVI clients show live text. Finals join with one space, except in Chinese and Japanese where they join with no separator. With segment_finals=False, each socket result is its own frame.
• Languages: A Pipecat Language is sent as the tag the socket expects. Regional values pass through (Language.PT_BR as pt-BR), Language.EN is sent as en (English, United States), and a bare code with a single regional variant is sent as that variant (Language.DE as de-DE). You can also pass a tag string such as "pt-BR". A language .wave does not serve is refused when the socket opens, with an error naming the tags it does serve. Frames carry the reported language as a Pipecat Language, and none with automatic detection.
• Not supported: diarize, multichannel, channels, keywords, and endpointing. Passing them to the constructor raises TypeError.
• Keepalive: A session closes after 30 seconds without audio, so the service sends a short burst of silence after 20 idle seconds.
• Errors: Error messages from the socket are pushed as ErrorFrame. A refused API key (close code 4401) or a malformed request (4400) is permanent and not retried; other closes reconnect with backoff.
• Pricing: $0.00045 per minute of audio. See pricing and limits.

Event Handlers

WaveSTTService supports the standard service connection events:

Event	Description
on_connected	Connected to the .wave socket
on_disconnected	Disconnected from the socket
on_connection_error	A connection error occurred

@stt.event_handler("on_connected")
async def on_connected(service):
    print("Connected to .wave")

Compatibility

Tested with Pipecat v1.12.0 and pipecat-dotwave 0.1.1. Requires Pipecat 1.12.0 or later and Python 3.11 or later. Check the source repository for the latest tested version and changelog.