> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langcraft.world/llms.txt
> Use this file to discover all available pages before exploring further.

# Transcription modes

> Choose a clean intended transcript or a verbatim transcript with normalized speech events

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.

<Warning>
  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.
</Warning>

## 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.

```bash theme={null}
curl -s -X POST https://api.langcraft.world/v1/speech/analyze \
  -H "x-api-key: $LANGCRAFT_API_KEY" \
  -F "audio=@speech.wav" \
  -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.

```json theme={null}
{
  "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

```json theme={null}
{
  "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.