Transcription modes

Transcription modes let your app choose between a clean transcript and a word-for-word transcript that preserves fillers, repetitions, interrupted words, self-repairs, false starts, and vocal sounds such as laughter.

Automatic transcription currently defaults to intended. Beginning September 1, 2026, the default will change to verbatim. Set transcription_mode=intended explicitly to preserve clean-transcript behavior after that date.

Choose one transcript style

When automatic transcription is used, transcription_mode controls the style of transcript returned by the API.

Value	Behavior
`intended`	Current default through August 31, 2026. Returns a clean, readable transcript of what the speaker meant to say. Fillers, repeated attempts, interrupted fragments, and vocal events may be removed.
`verbatim`	Default beginning September 1, 2026. Returns what the speaker said, including supported fillers, adjacent word repetitions, interrupted word fragments, and vocal events. It also returns a normalized `events` array.

Only these two values are supported. transcription_mode applies only when the API performs automatic transcription. Supplying reference_text or reference_phones continues to define the pronunciation target and does not allow generated text to replace that target.

curl -s -X POST https://api.langcraft.world/v1/speech/analyze \
  -H "x-api-key: $LANGCRAFT_API_KEY" \
  -F "[email protected]" \
  -F "lang=en" \
  -F "transcription_mode=verbatim"

Intended response

Through August 31, 2026, omitting transcription_mode has the same effect as sending transcription_mode=intended. Send the value explicitly if your integration always requires a clean transcript.

{
  "transcription": {
    "mode": "intended",
    "event_schema_version": "1",
    "text": "I think we should go on Thursday.",
    "words": [
      {"index": 0, "text": "I", "start": 120, "end": 240, "word_group_index": 0},
      {"index": 1, "text": "think", "start": 270, "end": 610, "word_group_index": 1}
    ],
    "events": []
  }
}

Verbatim response

{
  "transcription": {
    "mode": "verbatim",
    "event_schema_version": "1",
    "text": "I I think [UM] we should go on th* Thursday [laughter].",
    "words": [
      {"index": 0, "text": "I", "start": 120, "end": 240, "word_group_index": null},
      {"index": 1, "text": "I", "start": 290, "end": 420, "word_group_index": 0},
      {"index": 2, "text": "think", "start": 450, "end": 790, "word_group_index": 1, "surface_phones": [{"phone": "θ", "predicted_index": 2, "start": 460, "end": 520, "word_index": 2}]},
      {"index": 3, "text": "[UM]", "start": 920, "end": 1160, "word_group_index": null, "surface_phones": [{"phone": "ə", "predicted_index": 6, "start": 940, "end": 1120, "word_index": 3}]},
      {"index": 4, "text": "we", "start": 1220, "end": 1370, "word_group_index": 2},
      {"index": 5, "text": "should", "start": 1410, "end": 1690, "word_group_index": 3},
      {"index": 6, "text": "go", "start": 1740, "end": 1910, "word_group_index": 4},
      {"index": 7, "text": "on", "start": 1940, "end": 2050, "word_group_index": 5},
      {"index": 8, "text": "th*", "start": 2090, "end": 2180, "word_group_index": null},
      {"index": 9, "text": "Thursday", "start": 2210, "end": 2760, "word_group_index": 6},
      {"index": 10, "text": "[laughter]", "start": 2940, "end": 3380, "word_group_index": null}
    ],
    "surface_phones": [
      {"phone": "θ", "predicted_index": 2, "start": 460, "end": 520, "word_index": 2},
      {"phone": "ə", "predicted_index": 6, "start": 940, "end": 1120, "word_index": 3}
    ],
    "events": [
      {
        "type": "repetition",
        "text": "I",
        "count": 2,
        "word_indices": [0, 1],
        "start": 120,
        "end": 420
      },
      {
        "type": "filler",
        "label": "um",
        "text": "[UM]",
        "word_indices": [3],
        "start": 920,
        "end": 1160
      },
      {
        "type": "cutoff",
        "text": "th*",
        "fragment": "th",
        "word_indices": [8],
        "start": 2090,
        "end": 2180
      },
      {
        "type": "vocal_event",
        "label": "laughter",
        "text": "[laughter]",
        "word_indices": [10],
        "start": 2940,
        "end": 3380
      }
    ]
  }
}

All start and end values are milliseconds from the beginning of the uploaded audio. A timestamp can be null when the recognizer cannot obtain a reliable boundary. events is always an array and is empty when no supported events are detected.

Transcription fields

Field	Type	Description
`mode`	`"intended" \| "verbatim"`	Transcript style selected for the request.
`event_schema_version`	`"1"`	Version of the normalized event definitions.
`text`	string	Transcript in the selected style.
`words`	array	Timed transcript tokens. Each entry contains `index`, `text`, `start`, `end`, `word_group_index`, and a `surface_phones` array; timestamps and `word_group_index` can be `null`.
`surface_phones`	array	Timestamped open-recognizer phone observations for the complete utterance. Each item contains `phone`, `predicted_index`, `start`, `end`, and the assigned transcript `word_index`.
`events`	array	Normalized events. Empty in intended mode and when verbatim mode detects no supported events.

The events array is derived from the verbatim transcript and its timings. It does not expose model-specific token IDs or internal labels.

Words and pronunciation scoring

What you need	Field
Complete transcript	`transcription.text`
All timed words and their detected phones	`transcription.words`
Intended words with pronunciation scores	`word_groups`
Complete chronological phone timeline	`transcription.surface_phones`

Each transcription.words[] entry contains its detected phones in surface_phones. When a transcript word corresponds to a scored target, word_group_index points to its entry in word_groups. A value of null means the token is not scored. This includes extra words, fillers, abandoned repetitions, cut-offs, and vocal events. events[].word_indices points to the related entries in transcription.words.

Event types

The v1 event schema is a discriminated union selected by type.

`filler`

A filled pause normalized to one of the supported labels.

Field	Type	Description
`type`	`"filler"`	Event discriminator.
`label`	`"uh" \| "um"`	Normalized filler identity. The v1 parser recognizes explicit `[UH]` and `[UM]` labels.
`text`	string	Text as represented in the verbatim transcript, such as `[UH]` or `[UM]`.
`word_indices`	integer[]	Related entries in `transcription.words`.
`start`, `end`	number or `null`	Event boundaries in milliseconds.

Words such as “like,” “well,” “I mean,” and “you know” are ordinary transcript words. They are not classified as filler events.

`repetition`

An adjacent repetition of the same word, such as I I or we we we.

Field	Type	Description
`type`	`"repetition"`	Event discriminator.
`text`	string	Repeated word.
`count`	integer	Number of adjacent occurrences. Always at least `2`.
`word_indices`	integer[]	Repeated entries in `transcription.words`.
`start`, `end`	number or `null`	Boundaries spanning the repeated sequence.

Non-adjacent repetitions and repeated phrases are preserved in the transcript but are not guaranteed to produce a repetition event.

`cutoff`

An interrupted word or audible word fragment. The verbatim transcript uses a trailing *, for example th* Thursday.

Field	Type	Description
`type`	`"cutoff"`	Event discriminator.
`text`	string	Marked transcript form, such as `th*`.
`fragment`	string	Recognized fragment without the trailing marker.
`word_indices`	integer[]	Related entries in `transcription.words`.
`start`, `end`	number or `null`	Fragment boundaries in milliseconds.

Short word fragments are acoustically ambiguous. The model may detect that an interruption occurred while producing an imperfect fragment spelling.

`vocal_event`

A supported non-lexical vocal or acoustic event.

Field	Type	Description
`type`	`"vocal_event"`	Event discriminator.
`label`	string	Normalized event label.
`text`	string	Bracketed transcript form.
`word_indices`	integer[]	Related entries in `transcription.words`.
`start`, `end`	number or `null`	Event boundaries in milliseconds.

Supported labels are:

breath
cough
laughter
lipsmack
noise
sigh
sniff
throatclearing
yawn
other

other preserves a detected bracketed event that cannot be mapped safely to one of the named labels.

What is not a structured event

The verbatim transcript can preserve more speech detail than the v1 event schema classifies.

Self-repairs and false starts can appear in text, but the API does not currently return a structured relationship between abandoned words and the speaker’s correction.
Stuttering is not returned as a single event type. Whole-word repetitions may appear as repetition, and interrupted attempts may appear as cutoff. Blocks, prolongations, and physical secondary behaviors are not classified.
Silent pauses are represented by gaps between word timestamps and by the top-level pauses and pause_metrics fields. They are not transcription events.

Getting started

Reference

Preview

Choose one transcript style

Intended response

Verbatim response

Transcription fields

Words and pronunciation scoring

Event types

`filler`

`repetition`

`cutoff`

`vocal_event`

What is not a structured event

​Choose one transcript style

​Intended response

​Verbatim response

​Transcription fields

​Words and pronunciation scoring

​Event types

​filler

​repetition

​cutoff

​vocal_event

​What is not a structured event

Choose one transcript style

Intended response

Verbatim response

Transcription fields

Words and pronunciation scoring

Event types

`filler`

`repetition`

`cutoff`

`vocal_event`

What is not a structured event