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

::callout{icon="i-lucide-info" color="primary"} When is text stable?

The text in a conversation.item.input_audio_transcription.completed event is final. Once received, it will never be modified for that utterance. ::

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](/docs/concepts/stablestream) — the stability contract

[Build a Stable Caption UI](/docs/guides/stable-caption-ui) — UI implementation

[Server Events](/docs/api-reference/server-events) — event field reference