> For the complete documentation index, see [llms.txt](https://www.conserver.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.conserver.io/extensions/wtf-transcription.md).

# WTF Transcription

Shows how to store speech-to-text output from any provider in one shape, so you can switch or compare providers without rewriting downstream code.

**Draft:** [`draft-howe-vcon-wtf-extension-02`](https://datatracker.ietf.org/doc/draft-howe-vcon-wtf-extension/) · **Extension token:** `wtf_transcription`

## Purpose of the format

Every speech-to-text provider returns its own JSON. The World Transcription Format (WTF) defines one shape for that output: the full transcript, time-aligned segments, optional word timing, speaker diarization, quality metrics and processing metadata, with provider-specific extras kept in a separate `extensions` object. A transcript in WTF form reads the same whether Whisper, Deepgram or another engine produced it.

WTF data is analysis, derived from the dialog. The draft says it MUST be stored in `analysis[]` (Section 6.1). The extension is Compatible and does not need to be listed in `critical` (Section 5.1).

## Analysis entry

This vCon reduces the draft's example in Section 12.1 to two words:

```json
{
  "vcon": "0.4.0",
  "uuid": "01928e10-193e-8231-b9a2-279e0d16bc46",
  "created_at": "2025-01-02T12:00:00Z",
  "extensions": ["wtf_transcription"],
  "parties": [
    { "tel": "+12025550100", "name": "Alice" },
    { "tel": "+12025550199", "name": "Bob" }
  ],
  "dialog": [
    {
      "type": "recording",
      "start": "2025-01-02T12:15:30Z",
      "duration": 65.2,
      "parties": [0, 1],
      "mediatype": "audio/x-wav",
      "url": "https://example.com/recordings/call-recording.wav",
      "content_hash": "sha512-GLy6IPaIUM1GqzZqfIPZlWjaDsNgNvZM0iCONNThnH0a75fhUM6cYzLZ5GynSURREvZwmOh54-2lRRieyj82UQ"
    }
  ],
  "analysis": [
    {
      "type": "wtf_transcription",
      "dialog": 0,
      "vendor": "deepgram",
      "product": "nova-2",
      "mediatype": "application/json",
      "encoding": "json",
      "body": {
        "transcript": {
          "text": "Hello,",
          "language": "en-US",
          "duration": 65.2,
          "confidence": 0.92
        },
        "segments": [
          {
            "id": 0,
            "start": 0.5,
            "end": 1.1,
            "text": "Hello,",
            "confidence": 0.95,
            "speaker": 0,
            "words": [0, 1]
          }
        ],
        "words": [
          { "id": 0, "start": 0.5, "end": 0.8, "text": "Hello", "confidence": 0.98, "speaker": 0, "is_punctuation": false },
          { "id": 1, "start": 0.9, "end": 1.1, "text": ",", "confidence": 0.95, "speaker": 0, "is_punctuation": true }
        ],
        "speakers": {
          "0": { "id": 0, "label": "Alice", "segments": [0], "total_time": 0.6, "confidence": 0.95 }
        },
        "metadata": {
          "created_at": "2025-01-02T12:15:30Z",
          "processed_at": "2025-01-02T12:16:35Z",
          "provider": "deepgram",
          "model": "nova-2",
          "audio": { "duration": 65.2 }
        }
      }
    }
  ]
}
```

The draft's example points the dialog at a file with no `url` or `body`; this reduction adds a `url` and a placeholder `content_hash` so the dialog is complete under core-04. It has no lawful basis attachment because the point is the analysis shape; see [Lawful Basis](https://www.conserver.io/extensions/lawful-basis.md) for that.

## Analysis fields

From draft Section 6.1 and core-04 Section 4.5:

* `type` MUST be `"wtf_transcription"`.
* `encoding` MUST be `"json"`, and `body` is the WTF object itself, not a string.
* `dialog` SHOULD give the transcribed dialog index.
* `vendor` is required by core-04. Use the provider; put the model in `product`.

## Body structure

**Required** (Section 6.2.1):

* `transcript`: `text`, `language` (BCP 47, such as `en-US`), `duration` in seconds, `confidence` from 0 to 1.
* `segments`: array of `id`, `start`, `end` (seconds, `end` after `start`), `text`, `confidence`, and optionally `speaker` (integer or string) and `words`.
* `metadata`: `created_at`, `processed_at`, `provider` (lowercase), `model`, and optionally `processing_time`, `audio` (`duration`, `sample_rate`, `channels`, `format`, `bitrate`) and `options`.

**Optional** (Section 6.2.2):

* `words`: a top-level array of word objects (`id`, `start`, `end`, `text`, `confidence`, `speaker`, `is_punctuation`). A segment's `words` array holds indexes into this array, not word objects.
* `speakers`: an object keyed by speaker ID, each value with `id`, `label`, `segments`, `total_time`, `confidence`. Not an array.
* `alternatives`, `enrichments`, `quality`, `streaming`, and `extensions` for provider-specific data such as `extensions.whisper` or `extensions.deepgram`.

All confidence values are normalized to the range 0 to 1 (Section 8.1).

## Python

Build the analysis entry with the [`vcon`](https://pypi.org/project/vcon/) library. The example uses `vcon` 1.0.6, which writes core-05 (`"vcon": "0.5.0"`), so the recording dialog sits in a session. `add_wtf_transcription_analysis()` writes the entry this draft defines: `type: "wtf_transcription"`, `encoding: "json"`, the WTF document as the `body` value, `vendor` and `product` from `metadata["provider"]` and `metadata["model"]`, and the draft URL in `schema`. It also adds `wtf_transcription` to `extensions`.

```python
from vcon import Dialog, Session, Vcon
from vcon.party import Party

v = Vcon.build_new()  # sets "vcon": "0.5.0"
v.add_party(Party(tel="+15551230001", name="Alice"))
v.add_party(Party(tel="+15551230002", name="Bob"))
v.add_session(Session(start="2026-10-06T14:00:00Z", parties=[0, 1]))
v.add_dialog(Dialog(type="recording", start="2026-10-06T14:00:00Z", parties=[0, 1],
                    url="https://example.com/call.wav", mediatype="audio/x-wav",
                    # placeholder hash; set content_hash when you have the bytes
                    content_hash="sha512-GLy6IPaIUM1GqzZqfIPZlWjaDsNgNvZM0iCONNThnH0a75fhUM6cYzLZ5GynSURREvZwmOh54-2lRRieyj82UQ"),
             session=0)

wtf = {
    "transcript": {"text": "Hello, I need help with my account.", "language": "en-US",
                   "duration": 3.2, "confidence": 0.95},
    "segments": [{"id": 0, "start": 0.0, "end": 3.2,
                  "text": "Hello, I need help with my account.", "confidence": 0.95}],
    "metadata": {"created_at": "2026-10-06T14:00:00Z", "processed_at": "2026-10-06T14:00:04Z",
                 "provider": "whisper", "model": "whisper-large-v3"},
}

v.add_wtf_transcription_analysis(**wtf, dialog_index=0)

entry = v.find_analysis_by_type("wtf_transcription")
print(entry["vendor"], entry["product"], entry["encoding"])   # whisper whisper-large-v3 json
print(entry["body"]["transcript"]["text"])                    # Hello, I need help with my account.
print(v.get_extensions(), v.is_valid())                       # ['wtf_transcription'] (True, [])
print(v.get_validation_warnings())                            # []
```

To set `vendor` and `product` yourself, write the entry with `add_analysis()`, which takes keyword arguments only, and list the extension:

```python
v.add_analysis(
    type="wtf_transcription",
    dialog=0,
    vendor="openai",
    product="whisper-large-v3",
    mediatype="application/json",
    encoding="json",
    body=wtf,
)
v.add_extension("wtf_transcription")  # is_valid() fails without it
```

Before 1.0.3, `add_wtf_transcription_analysis()` wrote `type: "transcription"` and passed the body through `json.dumps`, producing a string; `Vcon.decoded_body()` reads entries in either form. `add_wtf_transcription_attachment()` is deprecated in 1.0.4 and emits a `DeprecationWarning`: it stores WTF in `attachments[]`, which the draft does not allow. Use `add_wtf_transcription_analysis()`. Write `body` as the WTF object, not `json.dumps(wtf)`; since 1.0.4 `get_validation_warnings()` flags a `json` body that is a serialized JSON string.

## See also

* [Field reference](https://www.conserver.io/vcons/field-reference.md) for analysis fields and body encodings.
* [Standard Links](https://www.conserver.io/conserver/standard-links.md) for the conserver's transcription links.
* [Comparing transcription engines](https://www.conserver.io/use-cases-studies/patterns.md#comparing-transcription-engines) for multi-provider comparison.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.conserver.io/extensions/wtf-transcription.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
