Realtime

The WebSocket API provides real-time speech-to-text transcription. You send audio data and receive transcript results as the speech is recognized.

Use it when you need a live transcript while audio is being captured: live subtitles, dictation, or transcribing an ongoing call or meeting. When in doubt, see Choosing an Endpoint.

Interim and Final Results

By default the server sends only final transcripts, whose text will not change. Set include_interim=true to also receive interim transcripts: early results that may be revised as more audio arrives. Show interim text live for immediate feedback, but only persist it once a transcript with is_final: true arrives.

Audio Format

With the default encoding=auto, the server detects the audio format from the container headers at the start of the stream; for raw audio, set encoding explicitly. See Audio Formats for the supported formats, streaming containers, and the reconnecting caveat.

Language

The server auto-detects the language by default; use the language query parameter to pin one or constrain detection to a list. See Languages. Set include_language=true to include the detected language on transcripts (empty on interim transcripts, since they carry no language signal).

Diarization

Pass diarize=true to label each transcript with the speaker_id of its dominant speaker. See Diarization.

How It Works

1. Connect - Open a WebSocket connection to wss://api.reson8.dev/v1/speech-to-text/realtime with an authentication header.
2. Configure - Use query parameters to set the audio encoding and which fields to include in the response.
3. Stream audio - Send audio data as binary WebSocket frames.
4. Receive transcripts - The server returns transcript messages as JSON text frames. Results can be interim (partial, may change) or final (stable).
5. Close - Close the WebSocket connection when done.

See the API reference for full details on messages, fields, and error codes.

Sequence Diagram

sequenceDiagram
  Client->>Server: Create Connection (auth + query params)
  activate Server
  Client->>Server: Audio (binary)
  Client->>Server: Audio (binary)
  Server->>Client: Transcript (Partial)
  Client->>Server: Audio (binary)
  Server->>Client: Transcript (Final)
  Client->>Server: Audio (binary)
  Client->>Server: Flush Request
  Server->>Client: Transcript (Final)
  Server-->>Client: Flush Confirmation
  Client->>Server: Close Connection
  deactivate Server

Flush

Send {"type":"flush_request"} as a JSON text frame to force any buffered audio to be finalized immediately. The server returns the final transcript followed by a flush_confirmation - see the API reference for the message format.

Ping / Pong

The server sends WebSocket ping frames every 30 seconds to keep the connection alive. This uses the built-in WebSocket ping/pong mechanism - clients should respond with a pong for every ping received. Most WebSocket libraries and browsers handle this automatically.