Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New ATTRIBUTES block #523

Open
wants to merge 11 commits into
base: main
Choose a base branch
from
Open

New ATTRIBUTES block #523

Changes from 6 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
18b3b37
sharing incomplete draft to allow validation of the parsing intention
cookiecrook Feb 3, 2024
665bc57
minor revision on algo allowed chars
cookiecrook Feb 9, 2024
ae202da
file structure inclusion
cookiecrook Mar 30, 2024
f4f4e31
Move the type registry out of this PR into #512 or another.
cookiecrook Mar 30, 2024
992f234
update attr key regex and note
cookiecrook Mar 30, 2024
7824b46
further clarifying parsing rules for attrs block, key/value pairs, an…
cookiecrook Jun 14, 2024
5423996
updates from first review; more external references
cookiecrook Jun 14, 2024
3011cc4
commenting the subtype references in favor of addressing as new webvt…
cookiecrook Jun 14, 2024
f4fd5f8
removing the commented subtype references in favor of addressing as n…
cookiecrook Jun 14, 2024
840e17e
review: -"video descriptions" + "descriptions"
cookiecrook Jun 17, 2024
d6ca24e
review comments from nigelmeggit
cookiecrook Jun 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
202 changes: 200 additions & 2 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -563,6 +563,62 @@ CSS comment (e.g. <code>/**/</code>).</p>

</div>



<div class="example">

<p>In this example, an optional WebVTT attributes object is used to define the source language and its label in a subtitle/caption selection menu.</p>
cookiecrook marked this conversation as resolved.
Show resolved Hide resolved
<pre>
WEBVTT

ATTRIBUTES
kind: subtitles
srclang: es-mx
cookiecrook marked this conversation as resolved.
Show resolved Hide resolved
label: Español

NOTE
Standard subtitles (unlike CC or SDH captions) typically
translate spoken dialog or signage, but not audible sounds
effects like "dogs barking."
cookiecrook marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This example isn't a great place to put definitional content. The WebVTT spec does not currently distinguish between subtitles and captions and that's probably a good thing. If there's an intended linkage between the kind attribute and the HTML track element's kind attribute then that should be explicit in the spec text.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If there's an intended linkage between the kind attribute and the HTML track element's kind attribute then that should be explicit in the spec text.

I included that in the "WebVTT attributes key/value parsing rules."

   <dt>If the key name is "<code>kind</code>"</dt>
   <dd>Process the value as <a href="https://html.spec.whatwg.org/multipage/media.html#attr-track-kind">the kind attribute</a> of a track element according to the HTML Standard.</dd>

Did you miss the above text, or is there some additional place where you'd like it added? Thanks for clarifying.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I may have missed it, but I can see why: that's appearing as part of §6.6 "WebVTT rules for extracting the chapter title" - shouldn't it be in its own numbered section?

Aside from that, what does "process the value as ..." mean? Does it mean that it takes precedence over the same attribute on the <track> element? Seems like we need to say something about precedence in this scenario.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I may have missed it, but I can see why: that's appearing as part of §6.6 "WebVTT rules for extracting the chapter title" - shouldn't it be in its own numbered section?

I agree, it should be a separate section.

Aside from that, what does "process the value as ..." mean? Does it mean that it takes precedence over the same attribute on the <track> element? Seems like we need to say something about precedence in this scenario.

I was wondering the same. Are these purely metadata or do they interact with the HTML/DOM in any way? And what is the order of precedence if both values are used? The track element wins? That might need a change in HTML?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Section mismatch was probably due to my unfamiliarty with Bikeshed. I will correct it and look at your other question at the same time.


1
00:00:10.123 --> 00:00:15.432
¡Hola! ¿Qué tál?
</pre>

</div>


<div class="example">

<p>In this example, an optional WebVTT attributes object is used to differentiate captions from standard subtitles.</p>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My feeling here is that the number of examples enumerating different values of kind is unnecessary given that this specification is not defining that attribute's value set. Better to have one example and, somewhere, link the value set to its canonical definition.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure I understand... Are you suggesting the value parsing algo cross reference the HTML Infra values in track[kind]?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, upon re-reading, it sounds like you're suggesting the examples be removed.

FWIW, as a reader of the spec (this was my first PR to VTT), I found the pre-existing examples helpful. Perhaps others will too? The ATTRIBUTES block is defined here, so seeing how it's used with different key/value pairs seems useful to me, even if those values are defined by HTML.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is one of each:

  • subtitle example
  • caption example
  • description example
  • metadata example

I'd prefer to leave all 4 examples, but perhaps we can compromise on just removing the subtitle example?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I still think there are too many but it's not a major complaint; as you say, many folk find examples an easy way into understanding the specification.

Also I just noticed that Example 14 is appearing in the Chapters section, but its about descriptions, so it seems to be misplaced.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tend to like a lot of examples.

Given how similar the subtitles and captions examples are, maybe we only keep one?

<pre>
WEBVTT

ATTRIBUTES
kind: captions
srclang: es-mx
label: Español (SDH)

NOTE
Captions (SDH aka Subtitles for the Deaf and Hard-of-Hearing)
typically include spoken dialog as well as important audible
sounds such as "floor boards creak", "dogs barking", or in
this case, "music".

1
00:00:10.123 --> 00:00:15.432
¡Hola! ¿Qué tál?

2
00:00:47.462 --> 00:01:04.028
[♫ música ♫]
</pre>

</div>



<h3 id=introduction-comments>Comments in WebVTT</h3>
cookiecrook marked this conversation as resolved.
Show resolved Hide resolved

<p><i>This section is non-normative.</i></p>
Expand Down Expand Up @@ -658,6 +714,32 @@ CSS comment (e.g. <code>/**/</code>).</p>

</div>



<div class="example">
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we probably want this in a separate section on descriptions, alternatively, should move to section 1.4 Other caption and subtitling features rather than being in the chapters section.


<p>In this example, a WebVTT attributes object is used to indicate the text track cues represent video descriptions for the blind. Unlike subtitles or captions, these are not intended to be rendered visually.</p>
cookiecrook marked this conversation as resolved.
Show resolved Hide resolved
<pre>
WEBVTT

ATTRIBUTES
kind: descriptions
srclang: en-us
label: English (AD)

NOTE
VTT-based descriptions are meant to render as text-to-speech audio or braille,
for blind or deafblind audiences, not usually as visual captions on screen.
As such, the option/label might be displayed in an audio menu or elsewhere.

1
00:00:10.123 --> 00:00:15.432
A young girl tiptoes down a dark hallway.
</pre>

</div>


<h3 id=introduction-metadata>Metadata example</h3>

<p><i>This section is non-normative.</i></p>
Expand All @@ -671,11 +753,14 @@ signifies the end of the WebVTT cue.</p>

<div class="example">

<p>In this example, a talk is split into each slide being a chapter.</p>
<p>In this example, topics mentioned in a talk are provided as URLs for reference.</p>

<pre>
WEBVTT

ATTRIBUTES
kind: metadata

NOTE
Thanks to http://output.jsbin.com/mugibo

Expand Down Expand Up @@ -704,6 +789,32 @@ signifies the end of the WebVTT cue.</p>

</div>

<div class="example">

<p>In this example, a sequence of video thumbnails and their text alternative are made available for the playback UI.</p>
<pre>
WEBVTT

ATTRIBUTES
kind: metadata

NOTE
The Timed Text Working Group is discussing a registry for metadata `type`
values, such as `type: video-thumbnails` or `type: video-flash-avoidance`.
See webvtt issues #511 and #512 for more info.
cookiecrook marked this conversation as resolved.
Show resolved Hide resolved

00:00:01.959 --> 00:00:02.938
{
"src": "https://cdn.example.com/thumbnails.jpg#xywh=0,0,284,160",
"alt": {
"en-us": "Miguel crosses the marigold bridge to the land of the dead.",
"es-mx": "Miguel cruza el puente marigold hacia la tierra de los muertos."
}
}
</pre>

</div>


<h2 id=conformance>Conformance</h2>

Expand Down Expand Up @@ -1474,6 +1585,9 @@ with the <a>MIME type</a> <code>text/vtt</code>. [[!RFC3629]]</p>
<li>Two or more <a lt="WebVTT line terminator">WebVTT line terminators</a> to terminate the line
with the file magic and separate it from the rest of the body.</li>

<li>Zero or one <a lt="WebVTT attributes block">WebVTT attributes block</a> followed by one or
more <a lt="WebVTT line terminator">WebVTT line terminators</a>.</li>

<li>Zero or more <a lt="WebVTT region definition block">WebVTT region definition blocks</a>, <a
lt="WebVTT style block">WebVTT style blocks</a> and <a lt="WebVTT comment block">WebVTT comment
blocks</a> separated from each other by one or more <a lt="WebVTT line terminator">WebVTT line
Expand Down Expand Up @@ -1650,6 +1764,49 @@ SIGN).</p>

<p>When interpreted as a number, a <a>WebVTT percentage</a> must be in the range 0..100.</p>

cookiecrook marked this conversation as resolved.
Show resolved Hide resolved
<p>A <dfn>WebVTT attributes block</dfn> consists of the following components, in the given order:</p>
<ol>
<li>The string "<code>ATTRIBUTES</code>".</li>
<li>
The following components, in the given order:
<ol>
<li>A <a>WebVTT line terminator</a>.</li>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure, but this item seems to be out from this <ol>, since it divides the ATTRIBUTES line but not in key/value pairs

Copy link
Author

@cookiecrook cookiecrook Jun 29, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I intended that as the line termination char on the same line as ATTRIBUTES

ATTRIBUTES
          ^

But I'd be happy to combine it with the previous line, or specify some other way at the editors' direction.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can remove a level here. So, at the top say "attributes block consists of the following components, in the given order:"

  • string ATTRIBUTES
  • Zero or more U+0020 SPACE characters or U+0009 CHARACTER TABULATION (tab) characters
  • line terminator
  • attributes block body
  • line terminator

This would match the webvtt region block definition too: https://pr-preview.s3.amazonaws.com/cookiecrook/webvtt/pull/523.html#webvtt-region-definition-block https://github.com/w3c/webvtt/blob/main/index.bs#L1500-L1511

The "attributes block body" (current lines 1774-1797) could either be inline or could move into its own subsection.

<li>Zero or more key/value pairs, parsed in the given order:
<ol>
<li>A <dfn>WebVTT attribute key</dfn> consisting of <code>[A-Za-z_][0-9A_Za-z_]*</code>:
<ul>
<li>Any one of the following:
<ul>
<li>U+0041 LATIN CAPITAL LETTER A through U+005A LATIN CAPITAL LETTER Z</li>
<li>U+0061 LATIN CAPITAL SMALL A through U+007A LATIN SMALL LETTER A</li>
cookiecrook marked this conversation as resolved.
Show resolved Hide resolved
<li>U+005F LOW LINE _ ("underscore")</li>
</ul>
</li>
<li>Optionally followed by zero or more of the following:
<ul>
<li>U+0030 DIGIT ZERO ("0") through U+0039 DIGIT NINE ("9")</li>
<li>U+0041 LATIN CAPITAL LETTER A through U+005A LATIN CAPITAL LETTER Z</li>
<li>U+0061 LATIN CAPITAL SMALL A through U+007A LATIN SMALL LETTER A</li>
cookiecrook marked this conversation as resolved.
Show resolved Hide resolved
<li>U+005F LOW LINE ("_" underscore)</li>
</ul>
</li>
<li class="ednote">Editorial Note: Should this `key` token range be an external reference to the character range for HTML TagName or ECMAScript variables? If so, which reference?</li>
cookiecrook marked this conversation as resolved.
Show resolved Hide resolved
</ul>
</li>
<li>A single U+003A COLON character ("<code>:</code>").</li>
<li>Zero or one U+0020 SPACE or U+0009 CHARACTER TABULATION (tab) characters.</li>
<li>A <dfn>WebVTT attribute value</dfn> consisting of any sequence of zero or more characters other than unescaped U+000A LINE FEED (LF) characters and unescaped U+000D CARRIAGE RETURN (CR) characters, except that the entire resulting string must not contain the substring "<code>--></code>" (U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN).</li>
<li>A <a>WebVTT line terminator</a>.</li>
</ol>
</li>
<li>A final <a>WebVTT line terminator</a> to complete the WebVTT attributes block.</li>
cookiecrook marked this conversation as resolved.
Show resolved Hide resolved
</ol>
</li>
</ol>

<p>Process the <a>WebVTT attributes block</a> key/value pairs according to the <a>WebVTT attributes key/value parsing rules</a>.</p>


<p>A <dfn>WebVTT comment block</dfn> consists of the following components, in the given order:</p>

<ol>
Expand Down Expand Up @@ -1687,7 +1844,7 @@ separated from the next by a <a>WebVTT line terminator</a>. (In other words, any
have two consecutive <a lt="WebVTT line terminator">WebVTT line terminators</a> and does not start
or end with a <a>WebVTT line terminator</a>.)</p>

<p><a>WebVTT metadata text</a> cues are only useful for scripted applications (e.g. using the
<p><a>WebVTT metadata text</a> cues were originally intended for scripted applications (e.g. using the
<code>metadata</code> <a>text track kind</a> in a HTML <a>text track</a>).</p>


Expand Down Expand Up @@ -4130,6 +4287,47 @@ follows:</p>
</ol>


<p>The <dfn>WebVTT attributes key/value parsing rules</dfn> consist of the following algorithm.</p>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<p>The <dfn>WebVTT attributes key/value parsing rules</dfn> consist of the following algorithm.</p>
<h3 id=rules-for-parsing-attr-key-values algorithm>WebVTT Attributes key/value parsing rules</h3>
<p>The <dfn>WebVTT attributes key/value parsing rules</dfn> consist of the following algorithm.</p>


<ol algorithm="WebVTT attributes block parsing">
<li>Let |input| be the list of key/value pairs from a <a>WebVTT attributes block</a>.</li>
<li>
How the attribute is processed depends on its key name, as follows:
<dl>

<dt>If the key name is "<code>kind</code>"</dt>
<dd>Process the value as <a href="https://html.spec.whatwg.org/multipage/media.html#attr-track-kind">the kind attribute</a> of a track element according to the HTML Standard.</dd>

<dt>If the key name is "<code>srclang</code>"</dt>
<dd>Process the value as <a href="https://html.spec.whatwg.org/multipage/media.html#attr-track-srclang">the srclang attribute</a> of a track element according to the HTML Standard.</dd>

<dt>If the key name is "<code>label</code>"</dt>
<dd>Process the value as <a href="https://html.spec.whatwg.org/multipage/media.html#attr-track-label">the label attribute</a> of a track element according to the HTML Standard.</dd>

<dt>If the key name is "<code>type</code>" (TODO: For clarity, should this be "subkind" or "kind_subtype" instead?)</dt>
<dd>Process the value according to the <a>WebVTT type attribute parsing rules</a>.
cookiecrook marked this conversation as resolved.
Show resolved Hide resolved

<dt>Otherwise</dt>
<dd>Ignore the key/value pair.</dd>

</dl>
</li>
</ol>

<p>The <dfn>WebVTT type attribute parsing rules</dfn> consist of the following algorithm.</p>

<ol algorithm="WebVTT type attribute attribute parsing">
<li>TODO: This could reference a new TBD W3C Note or Evergreen list of acknowledged kind subtypes, along with a reference to the specification for each, which clarify the usage or define further parsing rules of each type. For example:
<ul>
<li>metadata subtype: time-coded video poster thumbnails (common de facto use for scrubbing but no spec)</li>
<li>metadata subtype: <a href="https://github.com/w3c/webvtt/issues/512">WebVTT Issue 512: time-coded flash metadata</a></li>
<li>caption or description subtype: text equivalent of audio description audio track (used for braille displays)</li>
<li>etc.</li>
</ul>
</li>
</ol>
cookiecrook marked this conversation as resolved.
Show resolved Hide resolved


<h2 id=rendering>Rendering</h2>

<p class="note">This section describes in some detail how to visually render <a>WebVTT caption or
Expand Down