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

cookiecrook · 2026-06-01T17:45:47Z

Thanks. I discovered my error in the description and corrected it.

The context for others: I had commented wondering why PR Preview deleted the note about this being co-authored by GenAI, but deleted that comment once I discovered the reason and fixed the error. @himorin must've seen a record of the old comment in an older notification.

nigelmegitt

Another thought with no obvious place to comment on the changed files: in HTML there's a defined meaning to an attribute with no value, e.g. <div id="..." someattr> results in a DOM object that can be queried in javascript for the truthiness of someattr.

Would it make sense to match that here, and, in the absence of a : or = delimiter, if the entire line matches the requirements for a key, consider it to be a "true" attribute set on the file?

nigelmegitt · 2026-06-03T14:29:20Z

+<p>A <a>WebVTT header metadata key</a> must additionally satisfy one of the following:</p>
+
+<ul>
+ <li>It is one of the keys reserved by this specification for <a>WebVTT header metadata</a>;
+ see [[#header-metadata]] for the current list of reserved keys.</li>
+ <li>It contains at least one U+002D HYPHEN-MINUS character, and its first character is not a
+ U+002D HYPHEN-MINUS character.</li>
+</ul>


This is confusingly presented. It means either one or the other condition must be met but that's very subtle - it took me several readings before I noticed the word "one" in line 1660 and realised that it means "exactly one".

There is more explanation in the note that follows, but it's too late (for this linear reader anyway!).

Suggest reformatting to be clearer that there are reserved keys, which are listed, and which contain no hyphen, and unreserved keys that can be defined by applications, which must contain at least one hyphen.

Then the note that follows could hopefully be removed or greatly reduced.

I will modify. Thanks.

nigelmegitt · 2026-06-03T14:39:49Z

+<a lt="WebVTT header metadata kind">kind</a> of "<code>metadata</code>" together with a
+<a lt="WebVTT header metadata type">type</a> identifying the schema in use; see
+[[#header-metadata]]. Consumers that do not recognise the
+<a lt="WebVTT header metadata type">type</a> value must not present the cue payloads as


This seems to be asking a bit much - if the consumer doesn't recognise the WebVTT header metadata at all, then it has no way to reject presentation of the cue payloads based on the unrecognised "type" value.

This is mainly intended to allow non-web consumers that do recognize the header metadata to know what types to not display as on-screen captions... Of course we can't update old clients where this is already a problem.

While I understand why it's added, I wonder if it's a bit too restrictive without a clear benefit. Metadata tracks are already generally expected to be used in a scripting context and not shown to users.
This is definitely an edge case, but what should a vendor do is the following situation?

someone sets a kind:metadata and a type but then in the html app that track's mode is set to showing?
it might be ok to display it since it was explicitly set but a this line says that the it must not be displayed.

nigelmegitt · 2026-06-03T14:40:59Z

+constraints given for that key in [[#header-metadata]]. A given reserved key must not appear
+more than once in a single <a>WebVTT file</a>.</p>


The parsing steps are clear that only the first pair for any given key will be used, and doesn't issue any parsing error or other error if this constraint is not met.

Is this just a statement, or are you asking for a change? If the latter, please clarify.

gkatsev · 2026-06-08T21:06:42Z

Another thought with no obvious place to comment on the changed files: in HTML there's a defined meaning to an attribute with no value, e.g. <div id="..." someattr> results in a DOM object that can be queried in javascript for the truthiness of someattr.

Would it make sense to match that here, and, in the absence of a : or = delimiter, if the entire line matches the requirements for a key, consider it to be a "true" attribute set on the file?

I wonder whether we should allow it at the moment or to keep the scope smaller disallow it for now until this is asked for. I'd lean towards disallow at the moment, which I believe is currently covered by the parsing logic.

gkatsev

Thanks! Seems like we're in a pretty good place with this PR now.

gkatsev · 2026-06-08T20:51:25Z


 <pre>
 WEBVTT
+ kind: metadata


thought(non-blocking): I wonder whether it would be helpful to add these headers to other examples?

I don't remember if we talked about this in the other PR, I didn't find a direct answer from looking briefly.

gkatsev · 2026-06-08T21:22:19Z

+<a lt="WebVTT header metadata kind">kind</a> of "<code>metadata</code>" together with a
+<a lt="WebVTT header metadata type">type</a> identifying the schema in use; see
+[[#header-metadata]]. Consumers that do not recognise the
+<a lt="WebVTT header metadata type">type</a> value must not present the cue payloads as


While I understand why it's added, I wonder if it's a bit too restrictive without a clear benefit. Metadata tracks are already generally expected to be used in a scripting context and not shown to users.
This is definitely an edge case, but what should a vendor do is the following situation?

someone sets a kind:metadata and a type but then in the html app that track's mode is set to showing?
it might be ok to display it since it was explicitly set but a this line says that the it must not be displayed.

gkatsev · 2026-06-08T21:32:01Z

one thing I noticed that isn't relevant to the contents of the PR is that in the diff preview extra whitespace is collapsed in the examples. So, everything is bunched up together.

Seems to be fine in the regular preview and the regular deploy.