Add WebVTT header metadata to disambiguate metadata cues (#511) by cookiecrook · Pull Request #548 · w3c/webvtt

cookiecrook · 2026-05-28T21:11:22Z

Replaces the ATTRIBUTES-block approach explored in #523 with the TTWG-consensus design: file-level key/value pairs are written on the lines immediately following the WEBVTT file header line and are terminated by a blank line, rather than living in a separate block.

Key behaviors per the April 23 + May 7 TTWG meeting consensus and follow-up review comments:

Reserves four header keys: lang, kind, label, type (all optional; lang aligns with HTML ; type addresses VTT Metadata Cue format is ambiguous; some metadata may be unintentionally presented to the user in a context outside HTML #511 by identifying metadata schemas, with the taxonomy work continuing in VTT Type Proposal for time-coded general-flash metadata #512).
Accepts both ":" and "=" as separators; "=" is permitted for HLS-compatible files but is marked non-recommended.
Matches reserved keys case-sensitively; authors must use lowercase.
Allows Unicode in keys and values, excluding bidi controls, line breaks, and the "-->" substring.
Requires non-reserved keys to contain a hyphen and not start with one, reserving the hyphen-free namespace for future standardization.
Parses leniently: invalid lines are ignored individually and do not invalidate the rest of the header; no parser warnings are required.
Adds the parser plumbing (a new |header metadata| slot on the parser signature, a "collect WebVTT header metadata" algorithm, and a new return path from "collect a WebVTT block" when the in-header flag is set).
Updates the WebVTT metadata text prose to recommend declaring kind and type for files delivered outside an HTML context, addressing the cue-format ambiguity from VTT Metadata Cue format is ambiguous; some metadata may be unintentionally presented to the user in a context outside HTML #511.

Closes #511. Defers HTML-integration details (precedence between VTT header metadata and attributes, processing model) to whatwg/html#11665.

Note: GenAI (Claude Opus 4.8) used in the creation of this latest iteration.

Preview | Diff

Replaces the ATTRIBUTES-block approach explored in w3c#523 with the TTWG-consensus design: file-level key/value pairs are written on the lines immediately following the WEBVTT file header line and are terminated by a blank line, rather than living in a separate block. Key behaviors per the April 23 + May 7 TTWG meeting consensus and follow-up review comments: - Reserves four header keys: lang, kind, label, type (all optional; lang aligns with HTML <track srclang>; type addresses w3c#511 by identifying metadata schemas, with the taxonomy work continuing in w3c#512). - Accepts both ":" and "=" as separators; "=" is permitted for HLS-compatible files but is marked non-recommended. - Matches reserved keys case-sensitively; authors must use lowercase. - Allows Unicode in keys and values, excluding bidi controls, line breaks, and the "-->" substring. - Requires non-reserved keys to contain a hyphen and not start with one, reserving the hyphen-free namespace for future standardization. - Parses leniently: invalid lines are ignored individually and do not invalidate the rest of the header; no parser warnings are required. - Adds the parser plumbing (a new |header metadata| slot on the parser signature, a "collect WebVTT header metadata" algorithm, and a new return path from "collect a WebVTT block" when the in-header flag is set). - Updates the WebVTT metadata text prose to recommend declaring kind and type for files delivered outside an HTML context, addressing the cue-format ambiguity from w3c#511. Closes w3c#511. Defers HTML-integration details (precedence between VTT header metadata and <track> attributes, processing model) to whatwg/html#11665.

- Data model: explicitly state that unrecognized pairs are preserved only when the key meets the hyphen requirement; pairs that don't are dropped by the parser. Explains the webcompat motivation for reserving the unhyphenated key-name space. - Reframe the `type` reserved key as a name reservation with no values defined here; defer the registry (with `video.strobing. general-flash` as the expected first entry) to w3c#512. Drop the now redundant "future revision" note. - Replace duplicated reserved-key lists in the syntax section and in the "collect WebVTT header metadata" algorithm with references to the data-model section. - Drop the "opaque" framing in the metadata-text paragraph per Nigel's earlier objection. - Remove the parenthetical formatting from the parser's "ignore invalid line" step.

Addresses a missed cleanup from PR w3c#548 feedback. Removes the hardcoded count of "four" reserved keys in the parser notes, and corrects the explanation of how incorrectly-cased keys are handled (they are ignored immediately due to lacking a hyphen, rather than being collected as unrecognized pairs).

himorin · 2026-05-30T16:29:34Z

@cookiecrook
pr-preview will remove lines in description after last of certain line, like <!-- or ***. I don't think automatic line by Claude will include such, but it is possible to be added to the bottom after pr-preview added (so, in result, order of <description-text> <pr-preview lines> <claude-lines> will be used, and latter two parts removed and new pr-preview lines added)
if you have any specific point to be considered, please file issue to https://github.com/tobie/pr-preview

(note, not sure what the WG has decided on usage of AI tool to generate specification text...)