# 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](/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](/speech-to-text/features/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](/speech-to-text/features/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](/speech-to-text/features/diarization/).

## How It Works

1. **Connect** - Open a WebSocket connection to `wss://api.reson8.dev/v1/speech-to-text/realtime` with an [authentication](/authentication/) header.
2. **Configure** - Use [query parameters](/api/speech-to-text/realtime/#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](/api/speech-to-text/realtime/) for full details on messages, fields, and error codes.

## Sequence Diagram

<Mermaid code={`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](/api/speech-to-text/realtime/#flush-request) 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.