New ATTRIBUTES block by cookiecrook · Pull Request #523 · w3c/webvtt

cookiecrook · 2024-02-03T02:08:31Z

Closes #511

Add new ATTRIBUTES block parsing rules and examples as discussed in #511.

This is also a prerequisite for:

VTT Type Proposal for time-coded general-flash metadata #512

…and its duplicate in the WHATWG repo:
whatwg/html#11333

cookiecrook · 2024-06-14T00:37:23Z

Marking as Ready for Review despite there being some TODOs remaining in the diff. Feedback requested from @gkatsev, @silviapfeiffer, @nigelmegitt, @eric-carlson, @chrisn, @bdougherty, et al.

cookiecrook · 2024-06-14T21:08:46Z

I think this PR is merge-ready now once a TTWG reviewer approves. The previously included TODO comments are now removed from this PR in favor of addressing that follow-on work in:

Add a kind sub-type differentiator to new WebVTT ATTRIBUTES block #525

nigelmegitt

I think this would benefit from more clarity (i.e. more text) about the intended use of ATTRIBUTES and its relationship to attributes on the HTML <track> element, and any other potential usage context.

nigelmegitt · 2024-09-23T22:05:48Z

Needs a review from the Editor, @gkatsev .

nigelmegitt · 2024-09-23T22:08:06Z

See also another operational practice described for doing this at #485 (comment) in which YouTube is doing it in the Header section. We should probably make sure that whatever we specify here aligns with practice, or if not, that folk using that alternative approach are happy to change.

Update: @gkatsev had the action to draft a PR to resolve #485, and that looks to me as though it would overlap strongly with this PR.

gkatsev

Thanks for the work on this @cookiecrook and for your patience!

gkatsev · 2024-09-24T23:26:35Z

See also another operational practice described for doing this at #485 (comment) in which YouTube is doing it in the Header section. We should probably make sure that whatever we specify here aligns with practice, or if not, that folk using that alternative approach are happy to change.

What YouTube has definitely seems to align with it. Would be great if we can find someone from there to comment on this, if they could potentially move to the new block when it exists.

Update: @gkatsev had the action to draft a PR to resolve #485, and that looks to me as though it would overlap strongly with this PR.

I think ultimately, particularly, with HLS's usage of the header, we do still want the header as "point of extensibility" there. But, we may want to discourage new uses of it, since the majority of these use cases could use the ATTRIBUTES block. As an example, the ECMAScript spec added the __proto__ to the spec to get it documented but marked it as legacy: https://262.ecma-international.org/15.0/index.html#sec-object.prototype.__proto__ (I'm not aware of something specific like that in HTML or w3c specs, but I'm also not sure that there's anything against doing so).

cookiecrook · 2024-09-27T16:24:41Z

@gkatsev wrote:

What YouTube has definitely seems to align with it. Would be great if we can find someone from there to comment on this, if they could potentially move to the new block when it exists.

Yes, I have taken that as an action.

css-meeting-bot · 2024-09-27T22:14:58Z

The Timed Text Working Group just discussed New ATTRIBUTES block w3c/webvtt#523, and agreed to the following:

SUMMARY: @cookiecrook to raise issue on HTML about track attribute precedence

The full IRC log of that discussion

<nigel> Subtopic: New ATTRIBUTES block #523
<nigel> github: https://github.com//pull/523
<nigel> jcraig: Need to assess, if there's a mismatch, which one wins.
<nigel> .. I don't have a strong opinion.
<nigel> .. Main reason we want it in the VTT is sometimes there's no HTML as an intermediary,
<nigel> .. so the track information is missing.
<nigel> gkatsev: That makes sense, my question would be would this also allow a change in HTML
<nigel> .. if we're adding precedence to those attributes.
<nigel> jcraig: I would expect that whatever we land on, we could have the same thing reflected on the track element
<nigel> eric_carlson: We also would want to add some text to the spec describing the rules of precedence,
<nigel> .. whichever way we go.
<nigel> Nigel: How are you going to work out which way to go?
<nigel> eric_carlson: We'll put a stick in the ground and we'll be right.
<nigel> gkatsev: My assumption is the track element takes precedence
<nigel> eric_carlson: That would be right, it would override what's in the file.
<nigel> gkatsev: Can still have the precedence rules in the VTT spec but would also need them in HTML
<nigel> eric_carlson: HTML doesn't say anything about how to process the contents of the VTT file,
<nigel> .. so maybe no change needed.
<nigel> jcraig: The other editorial suggestions seem fine to me.
<nigel> .. There was a section question, was just my unfamiliarity with bikeshed.
<nigel> gkatsev: Should we open an HTML issue now around this to get the conversation going.
<nigel> jcraig: I'll take that as an action and write it into PR 523 so I don't forget it.
<nigel> pal: On that last point, if you run into any issues, I can help, please don't hesitate to ask.
<nigel> jcraig: You mean pushback on HTML?
<nigel> pal: Sure, ultimately the question is who writes those tests.
<nigel> .. As Nigel pointed out there's a large body of tests to port to WPT.
<nigel> .. With reference renderers once we've overcome the issue of should we have that at all in WPT,
<nigel> .. I'm confident that we'll have the resources to make that happen.
<nigel> group confusion caused because Pierre misheard!
<nigel> gkatsev: With that we can, unless there's anything specific to WebVTT right now we can end
<nigel> SUMMARY: @cookiecrook to raise issue on HTML about track attribute precedence

cookiecrook · 2024-09-27T22:15:03Z

I've also taken an action to file an issue to HTML to propose any reflected attributes from the VTT to HTML Track content attributes.

cookiecrook · 2026-03-10T01:47:36Z

@zcorpan wrote:

I guess we could support either : or = but maybe make = non-conforming.

There were multiple metadata uses in the wild. Supporting both could ease that transition for authors already utilizing = as the delimiter, but I question if that's worthwhile to add to the parser, since those actors can already continue with their usage of =-delimited VTT metadata without the ATTRIBUTES block. Is it's really worth it to permanently enshrine this non-conforming usage into the parser?

OK but per [obsoleted comment] it seems YouTube already uses the header for these attributes?

No... unless there has been a recent change, YT uses capitalized key/value pairs outside a block... e.g. Language: en without the ATTRIBUTES header. The case-insensitivity pattern was to ease that transition to the simple addition of the header for otherwise-conforming usages.

[relationship between keys and their HTML usage] seems like a layering violation. WebVTT should make the data available and HTML should say what to do with it in its track processing model.

Significant changes made as a WebVTT attributes object. Please review.

cookiecrook · 2026-03-10T01:48:56Z

Also @nigelmegitt asked about internationalization and unicode.

I've updated this portion significantly, including clarification that, of the key/value pairs, only the keys are ASCII; the values allow Unicode, other than some multi-line and bi-directional exceptions. In prior conversations, the WG feedback seemed to indicate a limited character set was desirable for the keys a number of reasons, including simplified case-folding, avoidance of visibly similar characters or other masked content like zero-width joiners, etc.

Do you feel strongly that the keys should also allow the full Unicode charset?

cookiecrook · 2026-03-10T19:59:01Z

Open Question: I changed the lang key to language based on review feedback here and precedent for YouTube's usage of Language: en... However, this now conflicts with WebVTT's <lang en> element, as well as HTML's lang and srclang attributes. I don't personally care which the WebVTT spec uses for the new ATTRIBUTES block key, so I'd like the Timed Text Working Group to make the decision.

cookiecrook · 2026-03-10T22:19:25Z

+  <code>type</code> is valid but parsers may generate a warning.</p>
+ </dd>
+
+ <dt><dfn lt="WebVTT attributes object language">A language</dfn></dt>


Open question here re: consistency of language vs lang vs srclang.
#523 (comment)

nigelmegitt · 2026-03-11T10:51:57Z

Also @nigelmegitt asked about internationalization and unicode.

I've updated this portion significantly, including clarification that, of the key/value pairs, only the keys are ASCII; the values allow Unicode, other than some multi-line and bi-directional exceptions. In prior conversations, the WG feedback seemed to indicate a limited character set was desirable for the keys a number of reasons, including simplified case-folding, avoidance of visibly similar characters or other masked content like zero-width joiners, etc.

Do you feel strongly that the keys should also allow the full Unicode charset?

I would suggest aligning with XML Name as closely as possible for the keys - this is what XML permits for attribute names. That goes beyond ASCII while still being a restricted set. I have not checked if there are any permitted code points that would cause parsing difficulties in WebVTT.

Alternatively a definition coincident with the WHATWG definition of attribute name could be used, but is a little less clear in my view.

cookiecrook · 2026-03-11T18:48:51Z

Open Question

@nigelmegitt wrote:

Alternatively a definition coincident with the WHATWG definition of attribute name could be used, but is a little less clear in my view.

Both XML Name and HTML attribute name can be hyphenated... such as data-foo which conflicts with variable names in some programming contexts due to the hyphen (minus) character. But given the choice between XML Name, and HTML attribute name, I'd go with HTML.

Regardless, I'm happy to take the working group's decision on this point, whatever that is. I'm collating a list of "Open Questions" here for an in-person discussion. Once we wrap up as much as we can in the thread, I'll research and summarize the remaining opens before scheduling more time with the WG.

nigelmegitt · 2026-03-12T14:49:15Z

Both XML Name and HTML attribute name can be hyphenated... such as data-foo which conflicts with variable names in some programming contexts due to the hyphen (minus) character.

Not sure how big a deal this is? People generally work around this kind of pattern in their chosen programming language. For example there are many CSS properties including a hyphen, such as font-weight that people seem able to work around in ES just fine.

zcorpan · 2026-03-12T22:58:39Z

I still think this should be in the header instead of a new block (see #523 (review) ).

zcorpan · 2026-03-12T23:05:26Z

Open Question: I changed the lang key to language based on review feedback here and precedent for YouTube's usage of Language: en... However, this now conflicts with WebVTT's <lang en> element, as well as HTML's lang and srclang attributes. I don't personally care which the WebVTT spec uses for the new ATTRIBUTES block key, so I'd like the Timed Text Working Group to make the decision.

lang is certainly more consistent, and looks nicer with kind and type also being 4 characters long. I suppose Youtube should be able to change to conform.

zcorpan · 2026-03-12T23:24:34Z

I would suggest aligning with XML Name as closely as possible for the keys - this is what XML permits for attribute names. That goes beyond ASCII while still being a restricted set. I have not checked if there are any permitted code points that would cause parsing difficulties in WebVTT.

Alternatively a definition coincident with the WHATWG definition of attribute name could be used, but is a little less clear in my view.

I think we should not use XML Name. WebVTT already borrows HTML syntax and parsing for named character references; it would be inconsistent and unnecessary to use XML syntax for something else in WebVTT.

HTML attribute name syntax prevents > (good because we shouldn't allow "-->") and = but doesn't prevent :. I guess we could say HTML attribute name minus : for which characters are allowed, or define the syntax in WebVTT without referencing HTML.

cookiecrook · 2026-03-12T23:36:28Z

@zcorpan wrote:

I still think this should be in the header instead of a new block (see #523 (review) ).

There are several existing in-the-wild use cases that would become non-conforming if this wasn't a new block. Those existing ambiguous, loosely defined or entirely undefined uses of VTT metadata will continue to persist in perpetuity.

I recall a a core TTWG member (@gkatsev IIRC) suggested the ATTRIBUTES block as a way to ease that transition from the ambiguous legacy processing to more structured processing model, while maintaining webcompat.

[Update: @gkatsev proposed METADATA (# or #:~:text), but either @eric-carlson or I renamed it to ATTRIBUTES to avoid redundancy, since it's primary use will be for kind: metadata.]

nigelmegitt · 2026-03-13T09:20:55Z

I think we should not use XML Name. WebVTT already borrows HTML syntax and parsing for named character references; it would be inconsistent and unnecessary to use XML syntax for something else in WebVTT.

It's true, the design choices made historically for WebVTT have been extremely XML-unfriendly, so maintaining separation from XML would be consistent. However, since we are primarily talking about metadata, and there may be use cases where folk want to transfer keys and values to/from other syntaxes, it would be good to be as open as possible within those existing constraints to minimise the need to rename keys.

HTML attribute name syntax prevents > (good because we shouldn't allow "-->") and = but doesn't prevent :. I guess we could say HTML attribute name minus : for which characters are allowed, or define the syntax in WebVTT without referencing HTML.

Or remove the requirement for the : after the key name - since the attribute name syntax prevents white space, it's not really needed. We could just have a syntax that looks like:

key [white space]+ value [line terminator]

e.g.

ATTRIBUTES
type  captions
lang  en
label English language hard of hearing subtitles

zcorpan · 2026-03-13T10:10:15Z

There are several existing in-the-wild use cases that would become non-conforming if this wasn't a new block. Those existing ambiguous, loosely defined or entirely undefined uses of VTT metadata will continue to persist in perpetuity.

They will not become non-conforming, they are already non-conforming.

The space for headers in the spec was reserved for the standards' own future use, it was not intended for private use (hence it is currently non-conforming to have anything there).

In fact, the opposite is true: if we start allowing custom headers, then existing content that has custom headers, assuming the syntax matches what we allow, such content can go from non-conforming to conforming. I think this shouldn't be a goal, though, only that we shouldn't shy away from using the spec's intended space for future extensibility because users of the spec have broken the contract and are using invalid WebVTT.

I recall a a core TTWG member (@gkatsev IIRC) suggested the ATTRIBUTES block as a way to ease that transition from the ambiguous legacy processing to more structured processing model, while maintaining webcompat.

Yeah the interesting question is whether it would break any existing usage if we add some standardized attributes in the header. If they keys used in the wild are different from the ones we're standardizing, then nothing will break, as far as I can tell. Even if the key is the same, so long as the value is different, still nothing would break. What is the web compat issue?

zcorpan · 2026-03-13T10:21:11Z

Or remove the requirement for the : after the key name - since the attribute name syntax prevents white space, it's not really needed. We could just have a syntax that looks like:
key [white space]+ value [line terminator]
e.g.
ATTRIBUTES
type  captions
lang  en
label English language hard of hearing subtitles

IMO this makes it less clear that they are key/value pairs, and it's inconsistent with WebVTT cue settings.

nigelmegitt · 2026-03-13T10:31:53Z

IMO this makes it less clear that they are key/value pairs, and it's inconsistent with WebVTT cue settings.

The : is optional in WebVTT cue settings so it isn't really inconsistent.

I also just remembered that some classification schemas etc for metadata use URNs for keys, which often include : so add that on the plus side for permitting colons.

zcorpan · 2026-03-13T12:02:55Z

That looks like a spec bug. The syntax for each individual cue setting requires the :, and without the colon the name and the value would run together which is not possible to parse.

Edit: filed #541

cookiecrook · 2026-03-17T19:14:12Z

Open Questions for TTWG Meeting Discussion (Date TBD)

Should this use the new ATTRIBUTES block as proposed vs. putting the key/value pairs in the existing header.
- @zcorpan thinks it should be in the header
- I’m strongly for the ATTRIBUTES block for transitional ease wrt existing, non-conforming use of header parsing. (Note: @zcorpan objected to my use of “webcompat” above since the existing header usage, although widespread, is already non-conforming and therefore not technically a webcompat concern.)
- Other TTWG members (including but not limited to @gkatsev) have expressed interest in the ATTRIBUTES, but I don’t know how strongly this belief is held or by whom.
Key name parsing, including character: define here, reference HTML, or use another name definition?
- ASCII+ (as in PR), XML Name, or HTML attribute name?
- Some characters need exclusion.
  - Bidi and reverse chars excluded.
  - Are we concerned with look-alike character like those comparable in ASCII and Cyrillic?
  - What about zero-width joiners used in emoji variant combinations?
Should the reserved key name be lang or language?
- Previously lang, changed to language at @nigelmegitt’s review request (Note: my PR misses that change in at least one place)
- @zcorpan prefers lang... I have a mild pref for lang, too.
- No one has voted for srclang the other existing precedent.
- Not sure about others.
Should kind be required, or should kind: metadata be required in order to use (metadata) type?
- Sounds like no, but I’d like to discuss anyway.
- See follow-on goal for metadata type in New ATTRIBUTES block #523 (comment)
- See also 5 below.
Should there be any parser warning, or should it be left to a validator, rather than the parser?
- Sounds like there is mild agreement that there is no need for a parser warning.
- Depending on outcome of 4 above, this may be moot.
Remove the subtitles example since it is so similar to the captions example.
- The TTWG feels the difference between subtitle (for those who can hear but need translation of the primary language) vs captions (which includes sensory needs like Deaf and Hard-of-Hearing groups, as well as those with translation needs) is not relevant to call out in VTT spec examples.
- I have a mild pref to keep both, but will concede to the TTWG consensus after discussion.

cookiecrook · 2026-03-17T19:19:21Z

@nigelmegitt @gkatsev @zcorpan Please help if I missed anything in summary of open questions above. Thanks.

I know that @eric-carlson would like to attend said meeting, and is out this week. My next availability at the normal TTWG meeting time (8am Pacific) is April 9th or April 23rd.

gkatsev · 2026-03-17T19:31:10Z

My next availability is also April 9th.

I still need to review the new discussion but should note that I'm leaning towards using the headers space assuming that we allow non-conforming usage like mentioned here #523 (comment)

nigelmegitt · 2026-03-18T09:08:28Z

Agenda for TTWG 2026-04-09 is w3c/ttwg#331, which I'm unable to attend, but have added this as a possible agenda item. 23rd April would work for me, alternatively.

zcorpan · 2026-03-18T12:39:29Z

(Note: @zcorpan objected to my use of “webcompat” above since the existing header usage, although widespread, is already non-conforming and therefore not technically a webcompat concern.)

To clarify, I objected to the claim that existing WebVTT content would go from being conforming to being non-conforming, as it's currently invalid WebVTT to use non-blank lines immediately after the WEBVTT file signature.

There could be a webcompat concern, but it's separate from whether existing content is conforming or non-conforming. I asked for examples where the new processing of headers would break existing content. The fact that existing content is using headers doesn't mean that that content will break if browsers start to process some known headers with some known values. I think there's only a potential issue if the standardized key and value are exactly the same as what already exists in the wild, but the semantics are different.

zcorpan · 2026-03-18T12:53:38Z

ASCII+ (as in PR), XML Name, or HTML attribute name?

If we don't need to allow characters outside of ASCII, an option is to align with HTML PI target: whatwg/html#12118

Right now it's [a-zA-Z][a-zA-Z0-9-]* but I added a review comment asking if _ should also be allowed.

nigelmegitt · 2026-03-18T14:29:11Z

If we don't need to allow characters outside of ASCII

Since the metadata keys may originate or relate to schemas external to WebVTT and to HTML, my view is that only allowing ASCII characters is likely to be overly restrictive. It's also unnecessary to be so limiting.

cookiecrook · 2026-03-24T00:56:22Z

Since Nigel can't make it on April 9th, can everyone make it on April 23rd?

If not, let's go ahead with April 9th.

gkatsev · 2026-03-24T17:22:45Z

Yeah, I think the 23rd works a bit better for me as well. We're going to cancel the April 9th meeting and have the agenda item be on the 23rd.

…e subtitles example.

cookiecrook commented Feb 3, 2024

View reviewed changes

Comment thread index.bs

cookiecrook commented Feb 9, 2024

View reviewed changes