How to consume realtime transcription events and build a caption UI that doesn't jitter.
The problem with naive approaches
A naive live caption UI might try to update text on every event. With partial-text systems, this causes visible jitter as words are repeatedly replaced.
StableStream™ describes Lanson Live's stable, readable text behavior. On the public Realtime endpoint, each conversation.item.input_audio_transcription.completed event contains the delivered segment text; the API does not send later partial-text revisions of that segment. This avoids one source of caption jitter, but layout and ordering still depend on your UI.
LiveFinal™ describes the correction/finalization mechanism. Optional refinement runs before this completed event; do not wait for a separate correction or finalization event. Check transcript.safe_for_downstream before triggering application actions; stability is not an accuracy guarantee.
Recommended render strategy
Append-only display
const captions = document.getElementById('captions');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.type === 'conversation.item.input_audio_transcription.completed') {
// Append directly — text is final, no replacement needed
const p = document.createElement('p');
p.dataset.utterance = data.utterance_index;
p.textContent = data.text;
captions.appendChild(p);
captions.scrollTop = captions.scrollHeight;
}
};With optional status indicators
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.type === 'input_audio_buffer.speech_started') {
showIndicator(data.utterance_index, 'listening');
}
if (data.type === 'input_audio_buffer.speech_stopped') {
showIndicator(data.utterance_index, 'processing');
}
if (data.type === 'conversation.item.input_audio_transcription.completed') {
hideIndicator(data.utterance_index);
appendCaption(data.utterance_index, data.text);
}
};What you do NOT need to do
- ❌ No partial → final text replacement mapping
- ❌ No waiting for "stabilization" (received text is already stable)
- ❌ No text rollback or undo
- ❌ No debounce or jitter elimination
- ❌ No re-rendering of previously shown text
Scrolling behavior
For long sessions, manage scroll behavior:
function appendCaption(index, text) {
const p = document.createElement('p');
p.textContent = text;
// Auto-scroll if user is near bottom
const isNearBottom =
captions.scrollHeight - captions.scrollTop - captions.clientHeight < 100;
captions.appendChild(p);
if (isNearBottom) {
captions.scrollTop = captions.scrollHeight;
}
}Styling for readability
#captions p {
margin: 0.25em 0;
padding: 0.25em 0.5em;
border-radius: 4px;
transition: opacity 0.2s;
}Related
- StableStream™ — readable output behavior
- LiveFinal™ — correction and delivery boundaries
- Stable vs. Partial Text — concept
- Browser Live Captions — full browser setup