[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"article-doc:docs\u002Frealtime\u002F5.transcript-lifecycle":3},"---\ntitle: Transcript Lifecycle\ndescription: Speech segment states and event transitions.\n---\nState transitions for transcribed text in a realtime session. Understanding these states is essential for building caption UIs.\n\n## State flow\n\n```\naudio input\n  ↓\nspeech_started (VAD detects speech)\n  ↓\n[upstream processing — segment in progress]\n  ↓\nspeech_stopped (VAD detects silence \u002F flush)\n  ↓\ntranscription.completed (stable text)\n```\n\n## Event semantics\n\n### speech_started\n\nVAD detected the start of a speech segment.\n\n- **At this point**: no transcribed text yet\n- **Client action**: optionally show a \"listening\" indicator\n- **Mutable**: no, `utterance_index` is fixed\n\n### speech_stopped\n\nVAD detected the end of a speech segment (silence, flush, or max speech duration).\n\n- **At this point**: upstream begins final transcription\n- **Client action**: optionally show \"processing\" state\n- **Mutable**: no\n\n### conversation.item.input_audio_transcription.completed\n\nA speech segment has been transcribed. This is the **primary output**.\n\n- **At this point**: `text` is stable and will not change\n- **Client action**: display the text, safe to write to database\n- **Mutable**: no, text is final\n- **Can trigger downstream**: yes\n\n::callout{icon=\"i-lucide-info\" color=\"primary\"}\n**When is text stable?**\n\nThe `text` in a `conversation.item.input_audio_transcription.completed` event is final. Once received, it will never be modified for that utterance.\n::\n\n## utterance_index\n\nEach speech segment has a unique, incrementing `utterance_index`. Use it to:\n- Order transcribed results\n- Detect missing events (index gaps)\n- Merge into a complete transcript\n\n## Concurrent utterances\n\nThe upstream may process multiple speech segments simultaneously. `limits.max_concurrent_utterances` limits concurrency. When exceeded, frames are dropped and `lanson.throttled` is sent.\n\n## No partial text\n\nIn the current version:\n- **No partial transcription is pushed**: no intermediate text before `transcription.completed`\n- **One result per utterance**: each utterance produces one `completed` event\n- **Text is immediately stable**: no partial → final transition needed on the client\n\nThis means clients do not need to handle caption jitter — each segment's text arrives in its final form.\n\n## Related\n\n- [StableStream](\u002Fdocs\u002Fconcepts\u002Fstablestream) — the stability contract\n- [Build a Stable Caption UI](\u002Fdocs\u002Fguides\u002Fstable-caption-ui) — UI implementation\n- [Server Events](\u002Fdocs\u002Fapi-reference\u002Fserver-events) — event field reference\n",1790059118957]