Add WebVTT header metadata to disambiguate metadata cues (#511)

[cookiecrook]

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

[himorin]

@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]

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]

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.

[cookiecrook]

I will modify. Thanks.

[cookiecrook]

I struggled with this a bit… Here's the current version, which is now part of the previous list, rather than a separate "additionally" list.

• [prior requirements for a key]
• It must either match a reserved key, or must match the additional hyphenated formatting requirements of a custom key:
  • reserved key: Matches one of the keys reserved by this specification for WebVTT header metadata; see [[#header-metadata]] for the current list of reserved keys.
  • custom key: contains at least one U+002D HYPHEN-MINUS character, and its first character is not a U+002D HYPHEN-MINUS character.

[cookiecrook]

@nigelmegitt I think this is the last issue blocking review. All other review feedback has been resolved. Please let me know if you have additional comments. Thanks!

[gkatsev]

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]

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.

[css-meeting-bot]

The Timed Text Working Group just discussed Add WebVTT header metadata to disambiguate metadata cues (#511) w3c/dapt#548, and agreed to the following:

• SUMMARY: Review and edits to continue; group reminded to check this PR.

The full IRC log of that discussion

<nigel> Subtopic: Add WebVTT header metadata to disambiguate metadata cues (#511) w3c/dapt#548
<nigel> github: https://github.com//pull/548
<cpn> Gary: The new PR is out, in good shape but needs more reviews
<cpn> Nigel: You had a comment about something being too restrictive without benefit?
<cpn> Gary: It says that if you see a type that you don't recognise, you must not display it too the user. Is that necessary, as the expectation for metadata is that you don't display it
<cpn> ... But if the user forces metadata to be visible this would conflict with that. It seems unnecessary
<cpn> Gary: Does this assumes a new type value means a new form of metadata. But it could parse as VTT cues and be presented?
<cpn> s/Gary/Nigel/
<cpn> Gary: I think it's associated with kind metadata, but that may be an unnecessary restriction as well
<cpn> Nigel: I don't have a view right now, but something to think about
<cpn> Gary: You also made a clarification request, on the parsing steps
<cpn> Nigel: The rule is that a given rule key must not appear more than once in a WebVTT file. The first will be used. But what happens if it does appear more than once, is there an error state?
<cpn> Gary: Makes sense
<cpn> ... The parsing rules say there isn't an error generator
<nigel> Chris: Is the "must" guidance to authors?
<nigel> Gary: It's a lower-case "must" rather than an upper-case MUST
<nigel> Chris: If that's the case maybe it should explain that.
<cpn> Chris: Suggest rephrasing it to say "Authors should ... " as it's actually guidance to authors
<cpn> Gary: Yes
<cpn> ... We'll probably need WPTs for this
<cpn> Nigel: Having tests along with PRs is helpful
<cpn> Gary: I think that's everything on this PR
<cpn> Nigel: There are a few actions to take, based on the comments. One thing is subtle, about an unordered list. James said he'd modify that.
<cpn> Gary: So I don't think there's anything major left
<nigel> SUMMARY: Review and edits to continue; group reminded to check this PR.

[cookiecrook]

@nigelmegitt wrote:

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?

@gkatsev replied

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.

I think Nigel is referring to Boolean attributes. If so, those are all implicitly false, but scope limited to specific Element definitions. For example, required is allowed on any form input element, but the checked attribute is only allowed on checkbox.

Without a way to limit the scope of which implicit Boolean metadata keys exist (like IDL provides for HTML elements), we'd be assigning permanent "falsy" values to every undefined key going forward. I agree with Gary that I'd prefer to keep the scope smaller now until a need is presented later.

[cookiecrook]

@nigelmegitt I just fixed a few errant whitespace diffs I somehow missed previously. I think this is the only remaining discussion issue: a rewrote of some prose you correctly noted was confusingly phrased. Thanks for your review.

• Add WebVTT header metadata to disambiguate metadata cues (#511) #548 (comment)