Read Dictation Transcript Frames

The WebSocket sends each transcription result as a JSON text message. Parse the message in your WebSocket handler, such as event.data in the browser’s onmessage callback, or use the equivalent message handler in your WebSocket library. For complete examples, see Stream audio to Dictation session. To learn how to establish the WebSocket connection and stream audio, see Stream Dictation audio.

Partial and final transcripts

Use is_final to decide whether the text should be shown as draft text or committed to the transcript.

`is_final`	Meaning
`false`	Partial, or interim, transcript. The text may change in later messages as the recognizer refines its result.
`true`	Final transcript for that segment. The recognizer has committed to this text, and it will not be revised.

Example partial frame:

{
  "transcript": {
    "transcript": "the recognized text so far",
    "words": []
  },
  "is_final": false,
  "transcript_id": "01J9XABCDEFGHJKMNPQRSTVWXYZ"
}

Example final frame:

{
  "transcript": {
    "transcript": "The patient reports feeling better today",
    "words": [
      { "word": "The", "speaker": { "id": "S1" } },
      { "word": "patient", "speaker": { "id": "S1" } }
    ]
  },
  "is_final": true,
  "transcript_id": "01J9XWXYZABCDEFGHJKMNPQRSTUV"
}

End of results

After the upstream stream ends, the server sends one terminal frame:

{
  "transcript": {
    "transcript": "EOF",
    "words": []
  }
}

Treat transcript.transcript equal to EOF as the canonical end-of-results signal for that speech session. The WebSocket closes shortly after.

Handle transcript updates in your UI

The Dictation WebSocket sends transcript updates as speech is processed. Each message contains the current transcript and an is_final flag that tells you whether the text is still changing or has been finalized.

Partial and final updates

A single spoken sentence can generate multiple partial transcript frames before a single final transcript is produced. Interim frames are drafts that the recognizer can revise. The final frame is the committed text for that segment. Your application is responsible for deciding how transcript text is displayed and stored in the editor.

Frame	Recommended client behavior
`is_final: false`	Display the transcript as interim text and replace it whenever a newer interim update arrives. Do not append interim transcripts to your committed transcript. Each interim update replaces the previous one until a final transcript is received.
`is_final: true`	Append the transcript to your editor or transcript buffer and remove any interim text. Use the `words` array in the final frame when you need word-level detail or speaker information.
`transcript.transcript: "EOF"`	No more transcript frames will be sent for this Dictation session. After you receive `EOF`, close the WebSocket if appropriate and complete the session using the REST API.

Recommended client state

A common approach is to maintain two pieces of state:

committedText: transcript that has been finalized and stored.
interimText: the current in-progress transcript that is replaced by newer interim updates or cleared when a final transcript arrives.

The server does not send empty transcript frames. Every transcript contains text except the terminal EOF frame.

Insert transcript text

Cursor and insertion point

The WebSocket returns only transcript text. It does not know your cursor position, selected text, or the surrounding content in your editor. Your application is responsible for inserting each transcript at the correct location.

Spacing

Before inserting a transcript, determine whether a space is needed between the existing text and the incoming transcript. Insert a leading space only when the existing text does not already end with whitespace or an opening bracket or quote ((, [, {, "), the insertion point is not at the beginning of the field, and the incoming transcript does not begin with punctuation that should attach to the previous text (for example ,, ., :, ;, !, ?).

Capitalization

Your application is responsible for capitalization when starting a new sentence or paragraph. Do not recapitalize on every interim update.

Examples

Existing text	Incoming transcript	Result
(empty field)	`Patient reports mild chest pain.`	`Patient reports mild chest pain.`
`Assessment:`	`patient denies fever.`	`Assessment: patient denies fever.`
`Pain (`	`mild`	`Pain (mild`
`No`	`,`	`No,`

Understand transcript ordering

The `transcript_id` field

Every transcript frame includes a transcript_id, but the value identifies a single emitted message, not a spoken utterance. Multiple interim and final updates for the same spoken phrase can each have a different transcript_id.

Do not use transcript_id to detect duplicate transcripts.
Use transcript arrival order to display updates.

The `words` array

Final transcript frames include the words array, which provides word-level metadata such as the individual word and speaker information (when available). Use it when your application shows word-level detail or distinguishes speakers. Interim frames typically contain an empty words array.

End-of-stream (EOF) lifecycle

To finish a Dictation session cleanly:

Send AUDIO_END.
Continue reading transcript frames.
Wait for the terminal EOF transcript (transcript.transcript: "EOF").
Close the WebSocket.
Complete the Dictation session using the End Dictation session REST API.

Stream Dictation Audio

Open /ws/transcribe, send audio, and end with AUDIO_END.

Wire Format

Outbound Dictation messages and audio format and chunking.

Complete the Session

End the Dictation session with REST after you finish reading frames.

Dictation Streaming API

API reference and code samples for transcript frames.

Next steps

Open the Dictation tab in Complete the session after streaming Review Audio Dictation for the full REST workflow

Get Started

Concepts & Feature Guides

Tutorials

Resources

FAQs & Support

Read Dictation Transcript Frames

Partial and final transcripts

End of results

Handle transcript updates in your UI

Partial and final updates

Recommended client state

Insert transcript text

Cursor and insertion point

Spacing

Capitalization

Examples

Understand transcript ordering

The `transcript_id` field

The `words` array

End-of-stream (EOF) lifecycle

Stream Dictation Audio

Wire Format

Complete the Session

Dictation Streaming API

Next steps

​Partial and final transcripts

​End of results

​Handle transcript updates in your UI

​Partial and final updates

​Recommended client state

​Insert transcript text

​Cursor and insertion point

​Spacing

​Capitalization

​Examples

​Understand transcript ordering

​The transcript_id field

​The words array

​End-of-stream (EOF) lifecycle

​Related topics and resources

Stream Dictation Audio

Wire Format

Complete the Session

Dictation Streaming API

​Next steps

Partial and final transcripts

End of results

Handle transcript updates in your UI

Partial and final updates

Recommended client state

Insert transcript text

Cursor and insertion point

Spacing

Capitalization

Examples

Understand transcript ordering

The `transcript_id` field

The `words` array

End-of-stream (EOF) lifecycle

Related topics and resources

Next steps