open-standards/wai/live-conformance/captions/README.md

# live-conformance/captions — timed text and live captions

The corpus of [`extensions/timed-text.md`](../../extensions/timed-text.md) §13: live
captions as `WEV1` events with their `WTX1` annotations, cues given as lists, and what each
maps onto: WebVTT documents and segments, IMSC1 documents, the two MoQ caption timelines,
CTA-608 byte pairs, and the disclosure label in HLS, C2PA, the catalogs and the sidecar.

**Timed-text equivalence.** For each event vector, a conforming verifier of the corpus's
room, holding every principal to live-events' default policy and offered `events` one at a
time in the order given, reaches the outcome the vector states (§4.3): `refuse` with the
`reason` and `index`, `gap` with the `gaps`, or `accept`. A vector that does not refuse also
states its `revisions`, each with its `window` (§4.7: its `source`, `cta-608` or `cta-708`, its
`service` and its `window`, or null) and whether that window is unknown (`window_unknown`),
what a sink shows at each instant of `shown` (§4.4), each caption with its window, and, for
a stream with no gap, the cues the stream resolves to or the refusal (`resolve`, §4.5); a
vector with a `join` states the
records a subscriber joining the events track at that group receives, its outcome and what it
shows (§4.6). For each event vector that resolves and each cue vector, `targets` states, for
each target it names, the file written or the reason refused: `webvtt` (§5.1), `segments`
(§5.2), `imsc` (§6.1, §6.2), `timelines` (§7.1–§7.3; every object byte for byte), `cc608`
(§8; the mode, the slot clock's rate, the file and what the decoder reports of it, §8.8) and
`disclosure` (§7.4, §10: the HLS tags, the session data, the sidecar, the C2PA statement and
the catalog entries, each byte for byte). `read_cases` are WebVTT texts the reader refuses
(§5.3), and `decode_cases` 608 streams the decoder refuses (§8.8), each with its reason. A
verifier that reaches another outcome, reason, index, revision, cue, rendering or byte does
not conform.

**Provenance.** Generated here: `wai_timed_text_vectors gen` writes `vectors.json` and every
expected output from events and cues authored in code, from fixed seeds. Each principal's key
and each model digest is SHA-256 of a fixed label and an index, the room id likewise, every
time is a constant, and Ed25519 signing is deterministic (RFC 8032), so every file is the
same bytes on every machine. The texts are written for the corpus, in English and Spanish.
The generator asserts, before it writes, that each vector reaches the outcome it was written
to have, that every WebVTT file reads back to its cues, that every 608 file decodes to the
rows its cues lay out, and that the corpus covers every reason of §12 and every 608 code path
of §8. No recorded data.

## Layout

- `vectors.json`: `pt0_ms` (the media time of the room's `t0`), `room`, `principals`
  (`captioner`, `asr`, `host`), `models`, `event_vectors`, `cue_vectors`, `read_cases` and
  `decode_cases`. A cue is written as `start`, `end`, `lang`, `origin`, `model` (lowercase
  hexadecimal, or null), `anchor`, `text` and `italic` (pairs of first code point and count).
- `NAME.vtt`, `NAME.segK.vtt`: WebVTT documents and segments.
- `NAME.ttml`: IMSC1 Text Profile documents.
- `NAME.MODE[.rNUM-DEN].608.hex`: 608 byte pairs in the hexadecimal form of §8.3, on the
  30000/1001 slot clock unless the name gives another rate.

## Checking

```
cargo run --no-default-features --features timed_text --bin wai_timed_text_vectors -- verify ../live-conformance/captions
python3 -I timed_text_verify.py captions
```

The first runs from `wai-rs/`, the second from `live-conformance/`. The second is the
corpus's second implementation, written from the extension's text; it shares no code with
`wai-rs`.