Transcript Text Handling

Learn about best practices for inserting transcript segments into the target editor

The /transcribe WebSocket emits transcript segments as plain text. Each segment is produced without full knowledge of your UI state (cursor position, selection, surrounding characters, field boundaries).

The backend service can’t reliably decide whether to prefix spaces, capitalize the first letter of a new sentence in your document, or avoid double-spaces because those depend on what’s already in the text field at the current cursor.

This guide assumes an established, configured connection. For establishing the WebSocket, sending configuration, and waiting for CONFIG_ACCEPTED before streaming audio, see WebSocket Connections.

Treat each incoming transcript segment as a suggestion with the client responsible for whitespace normalization at the insertion boundary (before/after the inserted segment). For interim rendering and commit semantics, see Interim & final result handling.

See transcript response message details in the API reference.

---

Understanding Transcript Fields

Use data.text for insertion into the document - it is already normalized with punctuation applied, locale-specific spacing preserved, and command phrases removed.

Use data.rawTranscriptText for debugging, analytics, or for workflows where you want to show what the user literally said (including spoken punctuation phrases).

/transcribe returns a single data object per transcript message (one segment). This differs from /streams, which returns a data array of speaker-attributed segments — see Diarized Transcript Handling.

---

Spacing Rules at the Insertion Boundary

Goal is to insert segments so words are not stitched together incorrectly ("pain." + "Patient" → "pain. Patient"), but also avoid leading spaces when the cursor is at the beginning of a field or after whitespace.

1. Before inserting Text:
   • Look at the character immediately before the insertion point (prevChar).
   • Look at the first character of Text (nextChar).
2. Then decide whether to prepend a space.

Recommendation

—

Prepend exactly one space only if all are true:

• You are not at the start of the field (cursor > 0).
• prevChar is not whitespace (' ', '\n', '\t') and is not an opening bracket/quote you want to stick to (e.g. (, [, {, “, ").
• nextChar is not punctuation that should attach to the left in the current locale (for most locales , . : ; ! ? ) ] } %).

This handles the common cases:

• "pain." + "Patient reports..." → adds a space.
• "" + "Patient reports..." → no leading space.
• "(" + "mild chest pain" → no space after (.
• "pain" + "," → no space before comma.

Post-insert normalization (optional) If your editor frequently contains trailing spaces before the cursor, you can also:

• Collapse multiple spaces at the join (“pain.␠␠” + “Patient” → “pain.␠Patient”).
• Avoid adding a space if there’s already whitespace immediately before the cursor.

Casing at insertion boundaries is client-owned and should only be applied at true sentence or paragraph boundaries, not on every interim update.

Locale-specific spacing

Some punctuation spacing rules are language-specific.

For primaryLanguage: "fr" (or "fr-FR"):

• Use a non-breaking space (\u00A0) before standalone :, ;, !, and ? when those characters arrive as separate transcript segments.
• If data.text already contains the spacing (for example, bonjour\u00A0:), insert it as-is and do not normalize it away.

Do not apply this French non-breaking-space rule to other locales such as fr-CH.

---

Bullet Points and List Formatting

When a user wants to insert a bullet point during dictation, speaking “hyphen” inserts the literal hyphen character (-) into the transcript text. Some editors automatically convert a leading - into a list item, but this behavior is inconsistent across platforms and cannot be relied upon for predictable list formatting.

Recommendation

—

Use one of the following approaches instead of relying on spoken punctuation alone to create bullet points:

• Commands: Define a command (e.g., "new bullet", "next bullet") that the client handles by invoking the editor’s native list or bullet API. This gives the editor full control over list formatting, indentation, and nesting. See Commands.
• Replacements: Configure a replacement rule that maps the spoken “bullet point” to the editor’s expected list-marker format. This is useful when the editor requires a specific prefix string to trigger list formatting.

Spoken “dash” inserts the em-dash character (—) with spaces on either side, which is not suitable for list formatting. Use “hyphen” (-) if inserting a literal character, but prefer commands or replacements for reliable list behavior. See Spoken Punctuation for details on hyphen and dash output.

---

Examples

Scenarios

	Existing Text	Cursor Location	Incoming text	Insert
1	""	0	"Patient reports mild chest pain."	"Patient reports mild chest pain." (no leading space)
2	"Assessment:"	end	"patient denies fever."	" patient denies fever." (add one leading space)
3	"Pain ("	end	"mild"	"mild" (no space after (
4	"No"	end	","	"," (no space before comma)
5	"Bonjour"	end	":"	"\u00A0:" when primaryLanguage is "fr" or "fr-FR"

Sample Code

JavaScript

const FRENCH_NBSP_BEFORE = new Set([":", ";", "!", "?"]);
const LEFT_ATTACH = new Set([",", ".", ":", ";", "!", "?", ")", "]", "}", "%"]);
const NO_SPACE_AFTER = new Set(["(", "[", "{", "“", "\"", "'"]);

function isWhitespace(ch: string) {
  return ch === " " || ch === "\n" || ch === "\t" || ch === "\u00A0";
}

function getLeadingSeparator(
  prevChar: string | null,
  nextChar: string,
  primaryLanguage?: string,
) {
  if (!prevChar) return "";
  if (isWhitespace(prevChar)) return "";
  if (isWhitespace(nextChar)) return "";
  if (NO_SPACE_AFTER.has(prevChar)) return "";

  const normalizedPrimaryLanguage = primaryLanguage?.toLowerCase();
  const isFrenchNbspLocale =
    normalizedPrimaryLanguage === "fr" || normalizedPrimaryLanguage === "fr-fr";

  if (isFrenchNbspLocale && FRENCH_NBSP_BEFORE.has(nextChar)) {
    return "\u00A0";
  }

  if (LEFT_ATTACH.has(nextChar)) return "";
  return " ";
}

/**
 * Decide what string to insert at the current cursor.
 * `text` is the entire field value, `cursor` is the insertion index,
 * and `segment` should be `message.data.text`.
 */
export function buildInsertion(
  text: string,
  cursor: number,
  segment: string,
  primaryLanguage?: string,
) {
  if (!segment) return "";

  const prevChar = cursor > 0 ? text[cursor - 1] : null;
  const nextChar = segment[0];
  const lead = getLeadingSeparator(prevChar, nextChar, primaryLanguage);

  // Preserve any service-provided spacing inside the segment itself.
  return lead + segment;
}

This page covers single-speaker /transcribe dictation. See Diarized Transcript Handling for multi-speaker, diarized output on /streams, where segments can arrive out of chronological order across speakers.

Contact us if you need further assistance working with transcript segments.