Transcript Lifecycle

State transitions for transcribed text in a realtime session. Understanding these states is essential for building caption UIs.

State flow

audio input
  ↓
speech_started (VAD detects speech)
  ↓
[upstream processing — segment in progress]
  ↓
speech_stopped (VAD detects silence / flush)
  ↓
transcription.completed (stable text)

Event semantics

speech_started

VAD detected the start of a speech segment.

• At this point: no transcribed text yet
• Client action: optionally show a "listening" indicator
• Mutable: no, utterance_index is fixed

speech_stopped

VAD detected the end of a speech segment (silence, flush, or max speech duration).

• At this point: upstream begins final transcription
• Client action: optionally show "processing" state
• Mutable: no

conversation.item.input_audio_transcription.completed

A speech segment has been transcribed. This is the primary output.

• At this point: text is stable and will not change
• Client action: display the text, safe to write to database
• Mutable: no, text is final
• Can trigger downstream: yes

utterance_index

Each speech segment has a unique, incrementing utterance_index. Use it to:

• Order transcribed results
• Detect missing events (index gaps)
• Merge into a complete transcript

Concurrent utterances

The upstream may process multiple speech segments simultaneously. limits.max_concurrent_utterances limits concurrency. When exceeded, frames are dropped and lanson.throttled is sent.

No partial text

In the current version:

• No partial transcription is pushed: no intermediate text before transcription.completed
• One result per utterance: each utterance produces one completed event
• Text is immediately stable: no partial → final transition needed on the client

This means clients do not need to handle caption jitter — each segment's text arrives in its final form.

Related

• StableStream — the stability contract
• Build a Stable Caption UI — UI implementation
• Server Events — event field reference