From efa63f7af0c8f4d726fbcfbbf7fb97f47f8b29eb Mon Sep 17 00:00:00 2001 From: James Craig Date: Fri, 2 Feb 2024 18:06:08 -0800 Subject: [PATCH 01/23] sharing incomplete draft to allow validation of the parsing intention --- index.bs | 133 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 131 insertions(+), 2 deletions(-) diff --git a/index.bs b/index.bs index e62fbf5..90d0088 100644 --- a/index.bs +++ b/index.bs @@ -563,6 +563,62 @@ CSS comment (e.g. /**/).

+ + +
+ +

In this example, an optional WebVTT attributes object is used to define the source language and its label in a subtitle/caption selection menu.

+ 
+WEBVTT
+
+ATTRIBUTES
+kind: subtitles
+srclang: es-mx
+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."
+
+1
+00:00:10.123 --> 00:00:15.432
+¡Hola! ¿Qué tál?
+
+ +
+ + +
+ +

In this example, an optional WebVTT attributes object is used to differentiate captions from standard subtitles.

+ 
+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 ♫]
+
+ +
+ + +

Comments in WebVTT

This section is non-normative.

@@ -658,6 +714,32 @@ CSS comment (e.g. /**/).

+ + +
+ +

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.

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

Metadata example

This section is non-normative.

@@ -671,11 +753,14 @@ signifies the end of the WebVTT cue.

-

In this example, a talk is split into each slide being a chapter.

+

In this example, topics mentioned in a talk are provided as URLs for reference.

  WEBVTT
 
+ ATTRIBUTES
+ kind: metadata
+ 
  NOTE
  Thanks to http://output.jsbin.com/mugibo
 
@@ -704,6 +789,28 @@ signifies the end of the WebVTT cue.
+
+ +

In this example, a sequence of video thumbnails and their text alternative are made available for the playback UI.

+ 
+WEBVTT
+
+ATTRIBUTES
+kind: metadata
+type: video-thumbnails
+
+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."
+ }
+}
+
+ +
+

Conformance

@@ -1650,6 +1757,28 @@ SIGN).

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

+

A WebVTT attributes object consists of the following components, in the given order:

+
    +
  1. The string "ATTRIBUTES".
    2. +
  2. + The following components, in the given order: +
      +
    1. A WebVTT line terminator.
      2. +
    2. Zero or more key/value pairs, parsed in the given order: +
        +
      1. A WebVTT attribute key consisting of any sequence of one or more (TODO: /A-Za-z/?) characters.
        2. +
      2. A single U+003A COLON character (":").
        3. +
      3. Zero or one U+0020 SPACE or U+0009 CHARACTER TABULATION (tab) characters.
        4. +
      4. A WebVTT attribute value consisting of any sequence of zero or more characters other than U+000A LINE FEED (LF) characters and U+000D CARRIAGE RETURN (CR) characters, except that the entire resulting string must not contain the substring "-->" (U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN).
        5. +
      5. A WebVTT line terminator.
        6. +
      +
      3. +
    3. A final WebVTT line terminator to complete the WebVTT attributes object.
      4. +
    +
    3. +
+ +

A WebVTT comment block consists of the following components, in the given order:

    @@ -1687,7 +1816,7 @@ separated from the next by a WebVTT line terminator. (In other words, any have two consecutive WebVTT line terminators and does not start or end with a WebVTT line terminator.)

    -

    WebVTT metadata text cues are only useful for scripted applications (e.g. using the +

    WebVTT metadata text cues were originally intended for scripted applications (e.g. using the metadata text track kind in a HTML text track).

    From 4fdab4f0fceda2a4606fcf20a417aa9d3fa61d06 Mon Sep 17 00:00:00 2001 From: James Craig Date: Fri, 9 Feb 2024 14:38:26 -0800 Subject: [PATCH 02/23] minor revision on algo allowed chars --- index.bs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.bs b/index.bs index 90d0088..d243659 100644 --- a/index.bs +++ b/index.bs @@ -1766,10 +1766,10 @@ SIGN).

  1. A WebVTT line terminator.
  2. Zero or more key/value pairs, parsed in the given order:
      -
    1. A WebVTT attribute key consisting of any sequence of one or more (TODO: /A-Za-z/?) characters.
      2. +
    2. A WebVTT attribute key consisting of any sequence of one or more (TODO: ref HTML tagname char or ECMAScript variable char ranges) characters.
    3. A single U+003A COLON character (":").
    4. Zero or one U+0020 SPACE or U+0009 CHARACTER TABULATION (tab) characters.
      5. -
    5. A WebVTT attribute value consisting of any sequence of zero or more characters other than U+000A LINE FEED (LF) characters and U+000D CARRIAGE RETURN (CR) characters, except that the entire resulting string must not contain the substring "-->" (U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN).
      6. +
    6. A WebVTT attribute value 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 "-->" (U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN).
    7. A WebVTT line terminator.
    3. From 591905e78c20fb44b60f8e1bb04602b3632912e2 Mon Sep 17 00:00:00 2001 From: James Craig Date: Fri, 29 Mar 2024 21:29:22 -0700 Subject: [PATCH 03/23] file structure inclusion --- index.bs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/index.bs b/index.bs index d243659..94795f2 100644 --- a/index.bs +++ b/index.bs @@ -1581,6 +1581,9 @@ with the MIME type text/vtt. [[!RFC3629]]

  3. Two or more WebVTT line terminators to terminate the line with the file magic and separate it from the rest of the body.
    4. +
  4. Zero or one WebVTT attributes object followed by one or + more WebVTT line terminators.
    5. +
  5. Zero or more WebVTT region definition blocks, WebVTT style blocks and WebVTT comment blocks separated from each other by one or more WebVTT line From a404d22ae921ba4a9edf95a940ed98e363fb592b Mon Sep 17 00:00:00 2001 From: James Craig Date: Sat, 30 Mar 2024 12:39:02 -0700 Subject: [PATCH 04/23] Move the type registry out of this PR into #512 or another. --- index.bs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 94795f2..356859e 100644 --- a/index.bs +++ b/index.bs @@ -797,7 +797,11 @@ WEBVTT ATTRIBUTES kind: metadata -type: video-thumbnails + +NOTE +The Timed Text Working Group is discussing a registry for metadata `type` +values, such as `video-thumbnails` or `video-flash-avoidance`. +See webvtt issues #511 and #512 for more info. 00:00:01.959 --> 00:00:02.938 { From 5e0bf50e5215e663f5c3c1c5c3f83dad69c4b4ac Mon Sep 17 00:00:00 2001 From: James Craig Date: Sat, 30 Mar 2024 14:52:26 -0700 Subject: [PATCH 05/23] update attr key regex and note --- index.bs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.bs b/index.bs index 356859e..0959f7d 100644 --- a/index.bs +++ b/index.bs @@ -800,7 +800,7 @@ kind: metadata NOTE The Timed Text Working Group is discussing a registry for metadata `type` -values, such as `video-thumbnails` or `video-flash-avoidance`. +values, such as `type: video-thumbnails` or `type: video-flash-avoidance`. See webvtt issues #511 and #512 for more info. 00:00:01.959 --> 00:00:02.938 @@ -1773,7 +1773,7 @@ SIGN).

  6. A WebVTT line terminator.
  7. Zero or more key/value pairs, parsed in the given order:
      -
    1. A WebVTT attribute key consisting of any sequence of one or more (TODO: ref HTML tagname char or ECMAScript variable char ranges) characters.
      2. +
    2. A WebVTT attribute key consisting of (TODO: ref HTML tagname or ECMAScript variable char ranges? or identifier regex [a-zA-Z_][0-9a-zA-Z_]*).
    3. A single U+003A COLON character (":").
    4. Zero or one U+0020 SPACE or U+0009 CHARACTER TABULATION (tab) characters.
    5. A WebVTT attribute value 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 "-->" (U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN).
      6. From 97c18ed25d24fd71ec895aa4a8647dc3e59defc7 Mon Sep 17 00:00:00 2001 From: James Craig Date: Thu, 13 Jun 2024 17:30:56 -0700 Subject: [PATCH 06/23] further clarifying parsing rules for attrs block, key/value pairs, and follow-on tbd 'type' --- index.bs | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 66 insertions(+), 4 deletions(-) diff --git a/index.bs b/index.bs index 0959f7d..a24aec7 100644 --- a/index.bs +++ b/index.bs @@ -1585,7 +1585,7 @@ with the MIME type text/vtt. [[!RFC3629]]

    6. Two or more WebVTT line terminators to terminate the line with the file magic and separate it from the rest of the body.
      7. -
    7. Zero or one WebVTT attributes object followed by one or +
    8. Zero or one WebVTT attributes block followed by one or more WebVTT line terminators.
    9. Zero or more WebVTT region definition blocks,

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

      -

      A WebVTT attributes object consists of the following components, in the given order:

      +

      A WebVTT attributes block consists of the following components, in the given order:

      1. The string "ATTRIBUTES".
      2. @@ -1773,18 +1773,39 @@ SIGN).

      3. A WebVTT line terminator.
      4. Zero or more key/value pairs, parsed in the given order:
          -
        1. A WebVTT attribute key consisting of (TODO: ref HTML tagname or ECMAScript variable char ranges? or identifier regex [a-zA-Z_][0-9a-zA-Z_]*).
          2. +
        2. A WebVTT attribute key consisting of [A-Za-z_][0-9A_Za-z_]*: +
            +
          • Any one of the following: +
              +
            • U+0041 LATIN CAPITAL LETTER A through U+005A LATIN CAPITAL LETTER Z
              • +
            • U+0061 LATIN CAPITAL SMALL A through U+007A LATIN SMALL LETTER A
              • +
            • U+005F LOW LINE _ ("underscore")
              • +
            +
            • +
          • Optionally followed by zero or more of the following: +
              +
            • U+0030 DIGIT ZERO ("0") through U+0039 DIGIT NINE ("9")
              • +
            • U+0041 LATIN CAPITAL LETTER A through U+005A LATIN CAPITAL LETTER Z
              • +
            • U+0061 LATIN CAPITAL SMALL A through U+007A LATIN SMALL LETTER A
              • +
            • U+005F LOW LINE ("_" underscore)
              • +
            +
            • +
          • 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?
            • +
          +
        3. A single U+003A COLON character (":").
        4. Zero or one U+0020 SPACE or U+0009 CHARACTER TABULATION (tab) characters.
        5. A WebVTT attribute value 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 "-->" (U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN).
        6. A WebVTT line terminator.
        5. -
      5. A final WebVTT line terminator to complete the WebVTT attributes object.
        6. +
      6. A final WebVTT line terminator to complete the WebVTT attributes block.
    +

    Process the WebVTT attributes block key/value pairs according to the WebVTT attributes key/value parsing rules.

    +

    A WebVTT comment block consists of the following components, in the given order:

    @@ -4266,6 +4287,47 @@ follows:

+

The WebVTT attributes key/value parsing rules consist of the following algorithm.

+ +
    +
  1. Let |input| be the list of key/value pairs from a WebVTT attributes block.
    2. +
  2. + How the attribute is processed depends on its key name, as follows: +
    + +
    If the key name is "kind"
    +
    Process the value as the kind attribute of a track element according to the HTML Standard.
    + +
    If the key name is "srclang"
    +
    Process the value as the srclang attribute of a track element according to the HTML Standard.
    + +
    If the key name is "label"
    +
    Process the value as the label attribute of a track element according to the HTML Standard.
    + +
    If the key name is "type" (TODO: For clarity, should this be "subkind" or "kind_subtype" instead?)
    +
    Process the value according to the WebVTT type attribute parsing rules. + +
    Otherwise
    +
    Ignore the key/value pair.
    + +
    +
    3. +
+ +

The WebVTT type attribute parsing rules consist of the following algorithm.

+ +
    +
  1. 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: +
      +
    • metadata subtype: time-coded video poster thumbnails (common de facto use for scrubbing but no spec)
      • +
    • metadata subtype: WebVTT Issue 512: time-coded flash metadata
      • +
    • caption or description subtype: text equivalent of audio description audio track (used for braille displays)
      • +
    • etc.
      • +
    +
    2. +
+ +

Rendering

This section describes in some detail how to visually render WebVTT caption or From bc0b1c96fadde96a91f684ad01e6c5cc597330fa Mon Sep 17 00:00:00 2001 From: James Craig Date: Fri, 14 Jun 2024 13:44:57 -0700 Subject: [PATCH 07/23] updates from first review; more external references --- index.bs | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/index.bs b/index.bs index a24aec7..b4c04b2 100644 --- a/index.bs +++ b/index.bs @@ -578,7 +578,7 @@ label: Español NOTE Standard subtitles (unlike CC or SDH captions) typically -translate spoken dialog or signage, but not audible sounds +translate spoken dialog or signage, but not audible sound effects like "dogs barking." 1 @@ -1773,25 +1773,21 @@ SIGN).

  • A WebVTT line terminator.
  • Zero or more key/value pairs, parsed in the given order:
      -
    1. A WebVTT attribute key consisting of [A-Za-z_][0-9A_Za-z_]*: -
        +
      • A WebVTT attribute key consisting of: ([A-Za-z_][0-9A_Za-z_]*) +
        1. Any one of the following:
            -
          • U+0041 LATIN CAPITAL LETTER A through U+005A LATIN CAPITAL LETTER Z
            • -
          • U+0061 LATIN CAPITAL SMALL A through U+007A LATIN SMALL LETTER A
            • -
          • U+005F LOW LINE _ ("underscore")
            • +
          • Any ASCII Alpha character
            • +
          • U+005F LOW LINE ("_" underscore)
        2. Optionally followed by zero or more of the following:
            -
          • U+0030 DIGIT ZERO ("0") through U+0039 DIGIT NINE ("9")
            • -
          • U+0041 LATIN CAPITAL LETTER A through U+005A LATIN CAPITAL LETTER Z
            • -
          • U+0061 LATIN CAPITAL SMALL A through U+007A LATIN SMALL LETTER A
            • +
          • Any ASCII Alphanumeric character
          • U+005F LOW LINE ("_" underscore)
          3. -
        3. 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?
          4. -
      +
  • A single U+003A COLON character (":").
  • Zero or one U+0020 SPACE or U+0009 CHARACTER TABULATION (tab) characters.
    • @@ -4319,9 +4315,10 @@ follows:

    1. 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:
      2. From ab15449b27162c4f792fc28fb80bc8bb693a89bd Mon Sep 17 00:00:00 2001 From: James Craig Date: Fri, 14 Jun 2024 13:57:52 -0700 Subject: [PATCH 08/23] commenting the subtype references in favor of addressing as new webvtt issue 525 --- index.bs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/index.bs b/index.bs index b4c04b2..ff0b040 100644 --- a/index.bs +++ b/index.bs @@ -4300,8 +4300,10 @@ follows:

      If the key name is "label"
      Process the value as the label attribute of a track element according to the HTML Standard.
      +
      Otherwise
      Ignore the key/value pair.
      @@ -4310,6 +4312,7 @@ follows:

    +

    Rendering

    From c934597d6a23a7290d16fd305276402fe10e7342 Mon Sep 17 00:00:00 2001 From: James Craig Date: Fri, 14 Jun 2024 14:06:38 -0700 Subject: [PATCH 09/23] removing the commented subtype references in favor of addressing as new webvtt issue 525 --- index.bs | 21 --------------------- 1 file changed, 21 deletions(-) diff --git a/index.bs b/index.bs index ff0b040..88447ce 100644 --- a/index.bs +++ b/index.bs @@ -4300,11 +4300,6 @@ follows:

    If the key name is "label"
    Process the value as the label attribute of a track element according to the HTML Standard.
    - -
    Otherwise
    Ignore the key/value pair.
    @@ -4312,22 +4307,6 @@ follows:

    - -

    Rendering

    This section describes in some detail how to visually render WebVTT caption or From d57f19c0facce4e16c0adf7f8eea43926dbfbfc6 Mon Sep 17 00:00:00 2001 From: James Craig Date: Mon, 17 Jun 2024 14:46:11 -0700 Subject: [PATCH 10/23] review: -"video descriptions" + "descriptions" --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 88447ce..ea00c67 100644 --- a/index.bs +++ b/index.bs @@ -718,7 +718,7 @@ this case, "music".

    -

    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.

    +

    In this example, a WebVTT attributes object is used to indicate the text track cues represent descriptions for the blind. Unlike subtitles or captions, these are not intended to be rendered visually.

     WEBVTT
 

From 71a249c23482dd0ed8e44cacc2c6b79e90efe4bd Mon Sep 17 00:00:00 2001
From: James Craig 
Date: Mon, 17 Jun 2024 15:16:30 -0700
Subject: [PATCH 11/23] review comments from nigelmeggit

---
 index.bs | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/index.bs b/index.bs
index ea00c67..7f05cf5 100644
--- a/index.bs
+++ b/index.bs
@@ -573,7 +573,7 @@ WEBVTT
 
 ATTRIBUTES
 kind: subtitles
-srclang: es-mx
+lang: es-mx
 label: Español
 
 NOTE
@@ -597,7 +597,7 @@ WEBVTT
 
 ATTRIBUTES
 kind: captions
-srclang: es-mx
+lang: es-mx
 label: Español (SDH)
 
 NOTE
@@ -718,13 +718,13 @@ this case, "music".
 
 
    
 
- 
    In this example, a WebVTT attributes object is used to indicate the text track cues represent descriptions for the blind. Unlike subtitles or captions, these are not intended to be rendered visually.
    
+ 
    In this example, a WebVTT attributes object is used to indicate the text track cues represent audible or braille descriptions for the blind. Unlike subtitles or captions, these are not intended to be rendered visually.
    
  
     WEBVTT
 
 ATTRIBUTES
 kind: descriptions
-srclang: en-us
+lang: en-us
 label: English (AD)
 
 NOTE
@@ -798,11 +798,6 @@ 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.
-
 00:00:01.959 --> 00:00:02.938
 {
  "src": "https://cdn.example.com/thumbnails.jpg#xywh=0,0,284,160",
@@ -812,6 +807,11 @@ See webvtt issues #511 and #512 for more info.
  }
 }
  
    
+ 
+ 
    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.
    
+
 
 
    
 
@@ -4294,7 +4294,7 @@ follows:
    
    
    If the key name is "kind"
    
    
    Process the value as the kind attribute of a track element according to the HTML Standard.
    
 
-   
    If the key name is "srclang"
    
+   
    If the key name is "lang"
    
    
    Process the value as the srclang attribute of a track element according to the HTML Standard.
    
 
    
    If the key name is "label"
    

From 009ec96bd811cf871c00fda32a68163d11637ddf Mon Sep 17 00:00:00 2001
From: James Craig 
Date: Thu, 17 Apr 2025 14:36:28 -0700
Subject: [PATCH 12/23] Apply suggestions from code review and outreach
 feedback

---
 index.bs | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/index.bs b/index.bs
index 7f05cf5..b7ed80c 100644
--- a/index.bs
+++ b/index.bs
@@ -4283,6 +4283,7 @@ follows:
    
 
 
 
+
    WebVTT Attributes key/value Parsing Rules
    
 
    The WebVTT attributes key/value parsing rules consist of the following algorithm.
    
 
 
      
@@ -4291,13 +4292,13 @@ follows:
      
   How the attribute is processed depends on its key name, as follows:
   
      
 
-   
      If the key name is "kind"
      
+   
      If the key name is "kind" (case-insensitive)
      
    
      Process the value as the kind attribute of a track element according to the HTML Standard.
      
 
-   
      If the key name is "lang"
      
+   
      If the key name is "lang" (case-insensitive)
      
    
      Process the value as the srclang attribute of a track element according to the HTML Standard.
      
 
-   
      If the key name is "label"
      
+   
      If the key name is "label" (case-insensitive)
      
    
      Process the value as the label attribute of a track element according to the HTML Standard.
      
 
    
      Otherwise
      

From 0a074fe132cfa8358b1ddfdfe6d109436d0578e3 Mon Sep 17 00:00:00 2001
From: James Craig 
Date: Thu, 17 Apr 2025 15:57:59 -0700
Subject: [PATCH 13/23] incorporated all but one final comment of the review
 feedback

---
 index.bs | 179 +++++++++++++++++++++++++++++--------------------------
 1 file changed, 93 insertions(+), 86 deletions(-)

diff --git a/index.bs b/index.bs
index b7ed80c..01e1527 100644
--- a/index.bs
+++ b/index.bs
@@ -362,12 +362,100 @@ CSS comment (e.g. /**/).
    +

    Attributes Block

    + +

    This section is non-normative.

    + +

    WebVTT supports an Attributes block to provide additional information about the rendered text track, and to allow disambiguation of metadata tracks.

    + + + + +
    + +

    In this example, an optional WebVTT attributes object is used to define the source language and its label in a subtitle/caption selection menu.

    + 
    +WEBVTT
+
+ATTRIBUTES
+kind: subtitles
+lang: es-mx
+label: Español
+
+NOTE
+Standard subtitles (unlike CC or SDH captions) typically 
+translate spoken dialog or signage, but not audible sound 
+effects like "dogs barking."
+
+1
+00:00:10.123 --> 00:00:15.432
+¡Hola! ¿Qué tál?
+
    + +
    + + +
    + +

    In this example, an optional WebVTT attributes object is used to differentiate captions from standard subtitles.

    + 
    +WEBVTT
+
+ATTRIBUTES
+kind: captions
+lang: 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 ♫]
+
    + +
    + + +
    + +

    In this example, a WebVTT attributes object is used to indicate the text track cues represent audible or braille descriptions for the blind. Unlike subtitles or captions, these are not intended to be rendered visually.

    + 
    +WEBVTT
+
+ATTRIBUTES
+kind: descriptions
+lang: 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.
+
    + +
    + + +

    Other caption and subtitling features

    This section is non-normative.

    WebVTT also supports some less-often used features.

    +

    In this example, the cues have an identifier:

    @@ -565,60 +653,6 @@ CSS comment (e.g. /**/).

    -
    - -

    In this example, an optional WebVTT attributes object is used to define the source language and its label in a subtitle/caption selection menu.

    - 
    -WEBVTT
-
-ATTRIBUTES
-kind: subtitles
-lang: es-mx
-label: Español
-
-NOTE
-Standard subtitles (unlike CC or SDH captions) typically 
-translate spoken dialog or signage, but not audible sound 
-effects like "dogs barking."
-
-1
-00:00:10.123 --> 00:00:15.432
-¡Hola! ¿Qué tál?
-
    - -
    - - -
    - -

    In this example, an optional WebVTT attributes object is used to differentiate captions from standard subtitles.

    - 
    -WEBVTT
-
-ATTRIBUTES
-kind: captions
-lang: 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 ♫]
-
    - -
    - - -

    Comments in WebVTT

    This section is non-normative.

    @@ -715,31 +749,6 @@ this case, "music".
    - -
    - -

    In this example, a WebVTT attributes object is used to indicate the text track cues represent audible or braille descriptions for the blind. Unlike subtitles or captions, these are not intended to be rendered visually.

    - 
    -WEBVTT
-
-ATTRIBUTES
-kind: descriptions
-lang: 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.
-
    - -
    - -

    Metadata example

    This section is non-normative.

    @@ -807,15 +816,13 @@ kind: metadata } } + -

    The Timed Text Working Group is discussing a registry for metadata type +

    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.

    - - -

    Conformance

    All diagrams, examples, and notes in this specification are non-normative, as are all sections @@ -1800,7 +1807,7 @@ SIGN).

    -

    Process the WebVTT attributes block key/value pairs according to the WebVTT attributes key/value parsing rules.

    +

    Process the WebVTT attributes block key/value pairs according to the WebVTT rules for parsing attribute key/value pairs.

    A WebVTT comment block consists of the following components, in the given order:

    @@ -4283,8 +4290,8 @@ follows:

    -

    WebVTT Attributes key/value Parsing Rules

    -

    The WebVTT attributes key/value parsing rules consist of the following algorithm.

    +

    WebVTT rules for parsing attribute key/value pairs

    +

    The WebVTT rules for parsing attribute key/value pairs consist of the following algorithm.

    1. Let |input| be the list of key/value pairs from a WebVTT attributes block.
      2. From 6aa01dc513cca3b0241e3fd10916e4496f244d5a Mon Sep 17 00:00:00 2001 From: James Craig Date: Fri, 18 Apr 2025 15:44:38 -0700 Subject: [PATCH 14/23] clarifying case insensitive --- index.bs | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index 01e1527..5c007d6 100644 --- a/index.bs +++ b/index.bs @@ -4299,13 +4299,13 @@ follows:

      How the attribute is processed depends on its key name, as follows:
      -
      If the key name is "kind" (case-insensitive)
      +
      If the key name is "kind" (ASCII case-insensitive)
      Process the value as the kind attribute of a track element according to the HTML Standard.
      -
      If the key name is "lang" (case-insensitive)
      +
      If the key name is "lang" (ASCII case-insensitive)
      Process the value as the srclang attribute of a track element according to the HTML Standard.
      -
      If the key name is "label" (case-insensitive)
      +
      If the key name is "label" (ASCII case-insensitive)
      Process the value as the label attribute of a track element according to the HTML Standard.
      Otherwise
      @@ -4315,6 +4315,9 @@ follows:

    +

    These keys are case-insensitive to allow compatibility with large video distributors already using this pattern in production.

    + +

    Rendering

    This section describes in some detail how to visually render WebVTT caption or From d0e4581e273225b7361c2b4f548c2d971314500e Mon Sep 17 00:00:00 2001 From: James Craig Date: Fri, 18 Apr 2025 15:48:05 -0700 Subject: [PATCH 15/23] correcting case insensitive --- index.bs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index 5c007d6..b277ec6 100644 --- a/index.bs +++ b/index.bs @@ -4299,13 +4299,13 @@ follows:

    How the attribute is processed depends on its key name, as follows:
    -
    If the key name is "kind" (ASCII case-insensitive)
    +
    If the key name is "kind" (ASCII case-insensitive)
    Process the value as the kind attribute of a track element according to the HTML Standard.
    -
    If the key name is "lang" (ASCII case-insensitive)
    +
    If the key name is "lang" (ASCII case-insensitive)
    Process the value as the srclang attribute of a track element according to the HTML Standard.
    -
    If the key name is "label" (ASCII case-insensitive)
    +
    If the key name is "label" (ASCII case-insensitive)
    Process the value as the label attribute of a track element according to the HTML Standard.
    Otherwise
    From 0e5dd511930f957e15484f8be9ba0c8381388ad7 Mon Sep 17 00:00:00 2001 From: James Craig Date: Fri, 18 Apr 2025 16:00:23 -0700 Subject: [PATCH 16/23] reorg attr block def based on gary's feedback --- index.bs | 52 ++++++++++++++++++++++++++-------------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/index.bs b/index.bs index b277ec6..0b39b30 100644 --- a/index.bs +++ b/index.bs @@ -1774,40 +1774,40 @@ SIGN).

    A WebVTT attributes block consists of the following components, in the given order:

    1. The string "ATTRIBUTES".
      2. -
    2. - The following components, in the given order: +
    3. Zero or more U+0020 SPACE or U+0009 CHARACTER TABULATION (tab) characters.
      4. +
    4. A WebVTT line terminator.
      5. +
    5. A WebVTT attributes body block.
      6. +
    6. A WebVTT line terminator.
      7. +
    + +

    A WebVTT attributes body block consists of the following components, in the given order:

    +
      +
    1. Zero or more key/value pairs, parsed in the given order:
        -
      1. A WebVTT line terminator.
        2. -
      2. Zero or more key/value pairs, parsed in the given order: +
      3. A WebVTT attribute key consisting of: ([A-Za-z_][0-9A_Za-z_]*)
          -
        1. A WebVTT attribute key consisting of: ([A-Za-z_][0-9A_Za-z_]*) -
            -
          1. Any one of the following: -
              -
            • Any ASCII Alpha character
              • -
            • U+005F LOW LINE ("_" underscore)
              • -
            -
            2. -
          2. Optionally followed by zero or more of the following: - -
            3. -
          +
        2. Any one of the following: +
            +
          • Any ASCII Alpha character
            • +
          • U+005F LOW LINE ("_" underscore)
            • +
          +
          3. +
        3. Optionally followed by zero or more of the following: +
          4. -
        4. A single U+003A COLON character (":").
          5. -
        5. Zero or one U+0020 SPACE or U+0009 CHARACTER TABULATION (tab) characters.
          6. -
        6. A WebVTT attribute value 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 "-->" (U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN).
          7. -
        7. A WebVTT line terminator.
        4. -
      4. A final WebVTT line terminator to complete the WebVTT attributes block.
        5. +
      5. A single U+003A COLON character (":").
        6. +
      6. Zero or one U+0020 SPACE or U+0009 CHARACTER TABULATION (tab) characters.
        7. +
      7. A WebVTT attribute value 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 "-->" (U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN).
        8. +
      8. A WebVTT line terminator.
    - -

    Process the WebVTT attributes block key/value pairs according to the WebVTT rules for parsing attribute key/value pairs.

    +

    Process the WebVTT attributes body block key/value pairs according to the WebVTT rules for parsing attribute key/value pairs.

    A WebVTT comment block consists of the following components, in the given order:

    From b333603f218b264dad5c879b6f29f1f57853828d Mon Sep 17 00:00:00 2001 From: James Craig Date: Thu, 3 Jul 2025 15:51:58 -0700 Subject: [PATCH 17/23] bidi feedback from aphilips --- index.bs | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 0b39b30..a2a9147 100644 --- a/index.bs +++ b/index.bs @@ -1802,7 +1802,15 @@ SIGN).

  • A single U+003A COLON character (":").
  • Zero or one U+0020 SPACE or U+0009 CHARACTER TABULATION (tab) characters.
    • -
  • A WebVTT attribute value 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 "-->" (U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN).
    • +
  • + A WebVTT attribute value consisting of any sequence of zero or more characters other than the following: +
      +
    • unescaped LINE FEED (LF) characters (U+000A),
      • +
    • unescaped CARRIAGE RETURN (CR) characters (U+000D),
      • +
    • unescaped bi-directional formatting characters (U+202B, U+202C, U+202D, U+202E, U+2066, U++2067, U++2068, U+2069, U+200E, U+200F, U+061C), or
      • +
    • the substring "-->" (U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN).
      • +
    +
  • A WebVTT line terminator.
    • From d9c7fb65889c75d6f33ead64a9334314c4de5da6 Mon Sep 17 00:00:00 2001 From: James Craig Date: Mon, 7 Jul 2025 10:43:00 -0700 Subject: [PATCH 18/23] m. whitespace. --- index.bs | 1 - 1 file changed, 1 deletion(-) diff --git a/index.bs b/index.bs index a2a9147..8ff51b4 100644 --- a/index.bs +++ b/index.bs @@ -455,7 +455,6 @@ A young girl tiptoes down a dark hallway.

    WebVTT also supports some less-often used features.

    -

    In this example, the cues have an identifier:

    From 6a79f258ee5bcea064cdf37cc0dffc12226dd5bf Mon Sep 17 00:00:00 2001 From: James Craig Date: Mon, 7 Jul 2025 10:43:09 -0700 Subject: [PATCH 19/23] m. whitespace. --- index.bs | 2 -- 1 file changed, 2 deletions(-) diff --git a/index.bs b/index.bs index 8ff51b4..54fd0c0 100644 --- a/index.bs +++ b/index.bs @@ -650,8 +650,6 @@ A young girl tiptoes down a dark hallway.
    - -

    Comments in WebVTT

    This section is non-normative.

    From 7d54121805026f2a33f935558872837a5e02f087 Mon Sep 17 00:00:00 2001 From: James Craig Date: Mon, 7 Jul 2025 10:44:23 -0700 Subject: [PATCH 20/23] m. whitespace. --- index.bs | 1 - 1 file changed, 1 deletion(-) diff --git a/index.bs b/index.bs index 54fd0c0..e280629 100644 --- a/index.bs +++ b/index.bs @@ -745,7 +745,6 @@ A young girl tiptoes down a dark hallway. -

    Metadata example

    This section is non-normative.

    From ae5ad1c84192fd0ec54b5dc2b8eae6d8edd314d1 Mon Sep 17 00:00:00 2001 From: James Craig Date: Mon, 9 Mar 2026 17:07:19 -0700 Subject: [PATCH 21/23] Define parsing algorithm of ATTRIBUTES block MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses review feedback: - Add WebVTT attributes object to data model - Rewrite WebVTT attributes block syntax definition to expand value charset to Unicode, define numeric character reference escaping for CR/LF/bidi - Add |attributes| output slot - Add ATTRIBUTES branch to collect a WebVTT block state machine - Add collect WebVTT attributes algorithm - Rewrite key/value parsing rules: lang→language, decouple from HTML, preserve unknown keys in custom pairs --- index.bs | 328 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 273 insertions(+), 55 deletions(-) diff --git a/index.bs b/index.bs index 6fa4e58..518bc3e 100644 --- a/index.bs +++ b/index.bs @@ -1550,6 +1550,70 @@ together, which is particularly important when scrolling up.

    +

    WebVTT attributes object

    + +

    A WebVTT attributes object represents the optional file-level metadata declared in a +WebVTT attributes block. It consists of:

    + +
    + +
    A kind
    +
    +

    A string giving the text track kind. If present, must be one of "subtitles", + "captions", "descriptions", "chapters", or + "metadata". Defaults to the empty string.

    +

    The kind key is the only required key. Consumers that do not + recognise the kind value should treat the entire WebVTT attributes object + as opaque.

    +
    + +
    A type
    +
    +

    A string further differentiating the subtype within a kind (for example, + distinguishing varieties of metadata tracks). If present, must be either + "custom" or a string beginning with "custom-". All other values + are reserved for future standardization. Defaults to the empty string.

    +

    The type key disambiguates the track kind subtype to resolve + naming conflicts for the other common key names often used by different types of metadata.

    +

    Authors including + custom pairs should provide a non-empty + type value to identify the application or schema those pairs belong to. + A WebVTT attributes block with non-empty + custom pairs and an empty + type is valid but parsers may generate a warning.

    +
    + +
    A language
    +
    +

    A string giving the BCP 47 language tag of the track content. Defaults to the empty + string.

    +
    + +
    A label
    +
    +

    A human-readable string intended for use in a track selection menu. Defaults to the empty + string.

    +
    + +
    Custom pairs
    +
    +

    An ordered list of key/value string pairs for any unrecognized attribute keys. Defaults to + the empty list.

    +

    Custom pairs should be accompanied by a non-empty + type value so that consumers can identify the + schema to which the pairs belong. If custom pairs are present and type is the + empty string, parsing continues normally, but parsers may generate a warning.

    +
    + +
    + +

    The WebVTT attributes object's properties are intended to be used by +the embedding context (e.g. HTML) to populate the corresponding internal text track concepts. +How format-provided values interact with values specified in the embedding context (e.g. +<track> element attributes) is defined by the embedding specification. See +whatwg/html issue #11665 for the +ongoing HTML integration work.

    +

    WebVTT chapter cues

    A WebVTT chapter cue is a WebVTT cue whose cue text is interpreted as a @@ -1769,49 +1833,61 @@ SIGN).

    A WebVTT attributes block consists of the following components, in the given order:

      -
    1. The string "ATTRIBUTES".
      2. +
    2. The string "ATTRIBUTES" (U+0041, U+0054, U+0054, U+0052, U+0049, U+0042, U+0055, + U+0054, U+0045, U+0053).
    3. Zero or more U+0020 SPACE or U+0009 CHARACTER TABULATION (tab) characters.
    4. A WebVTT line terminator.
      5. -
    5. A WebVTT attributes body block.
      6. -
    6. A WebVTT line terminator.
      7. +
    7. Zero or more WebVTT attribute key/value pairs, + each followed by a WebVTT line terminator.
    -

    A WebVTT attributes body block consists of the following components, in the given order:

    +

    The WebVTT attributes block is terminated by a blank line (two consecutive +WebVTT line terminators), exactly as for +WebVTT region definition blocks.

    + +

    The kind key is the only required key in a +WebVTT attributes block. It must appear in the block to disambiguate the track kind. +Without it, consumers cannot determine whether other well-known keys such as +language and label apply to a recognized track kind, and may treat +them as opaque. See WebVTT rules for parsing +attribute key/value pairs.

    + +

    A WebVTT attribute key/value pair consists of the following components, +in the given order:

      -
    1. Zero or more key/value pairs, parsed in the given order: -
        -
      1. A WebVTT attribute key consisting of: ([A-Za-z_][0-9A_Za-z_]*) -
          -
        1. Any one of the following: -
            -
          • Any ASCII Alpha character
            • -
          • U+005F LOW LINE ("_" underscore)
            • -
          -
          2. -
        2. Optionally followed by zero or more of the following: - -
          3. -
        -
        2. -
      2. A single U+003A COLON character (":").
        3. -
      3. Zero or one U+0020 SPACE or U+0009 CHARACTER TABULATION (tab) characters.
        4. -
      4. - A WebVTT attribute value consisting of any sequence of zero or more characters other than the following: -
          -
        • unescaped LINE FEED (LF) characters (U+000A),
          • -
        • unescaped CARRIAGE RETURN (CR) characters (U+000D),
          • -
        • unescaped bi-directional formatting characters (U+202B, U+202C, U+202D, U+202E, U+2066, U++2067, U++2068, U+2069, U+200E, U+200F, U+061C), or
          • -
        • the substring "-->" (U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN).
          • -
        -
        5. -
      5. A WebVTT line terminator.
        6. -
      +
    2. A WebVTT attribute key consisting of one or more + ASCII alphanumeric characters or + U+005F LOW LINE (_) characters, where the first character is either an + ASCII alpha character or U+005F LOW + LINE (_). In other words, matching the production + [A-Za-z_][0-9A-Za-z_]*.
      3. +
    3. A single U+003A COLON character (":").
      4. +
    4. Zero or one U+0020 SPACE or U+0009 CHARACTER TABULATION (tab) characters.
      5. +
    5. A WebVTT attribute value, which is any sequence of zero or more Unicode + characters, subject to the following constraints: +
        +
      • The characters U+000A LINE FEED (LF) and U+000D CARRIAGE RETURN (CR) must not appear + literally; they may be represented using the + numeric + character references &#x000A; and &#x000D; + respectively.
        • +
      • The bidirectional formatting characters U+202B, U+202C, U+202D, U+202E, U+2066, + U+2067, U+2068, U+2069, U+200E, U+200F, and U+061C must not appear literally; they may + be represented using + numeric + character references (e.g. &#x200E;).
        • +
      • The resulting string, after escape processing, must not contain the substring + "-->" (U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN).
        • +
    -

    Process the WebVTT attributes body block key/value pairs according to the WebVTT rules for parsing attribute key/value pairs.

    + +

    Keys are restricted to ASCII to ensure consistent case-folding and to avoid +ambiguity in key matching. Values may contain any Unicode characters (subject to the constraints +above) to support multilingual labels, language tags, and other internationalized content.

    + +

    The numeric character reference escape convention above is the same as that used +in WebVTT for bidi mark characters in cue payloads (e.g."&#x2068;").

    A WebVTT comment block consists of the following components, in the given order:

    @@ -2614,11 +2690,13 @@ chapters, or metadata. Most of the steps will be skipped for chapters or metadat

    WebVTT file parsing

    A WebVTT parser, given an input byte stream, a text track list of cues -|output|, and a collection of CSS style sheets |stylesheets|, must decode the byte -stream using the UTF-8 decode algorithm, and then must parse the resulting -string according to the WebVTT parser algorithm below. This results in WebVTT cues -being added to |output|, and CSS style sheets being added to |stylesheets|. -[[!RFC3629]]

    +|output|, a collection of CSS style sheets |stylesheets|, and optionally a +slot |attributes| for a WebVTT attributes object, must decode the byte stream using the +UTF-8 decode algorithm, and then must parse the resulting string +according to the WebVTT parser algorithm below. This results in WebVTT cues +being added to |output|, CSS style sheets being added to |stylesheets|, and +if a WebVTT attributes block is present, a WebVTT attributes object being set in +|attributes|. [[!RFC3629]]

    A WebVTT parser, specifically its conversion and parsing steps, is typically run asynchronously, with the input byte stream being updated incrementally as the resource is @@ -2713,6 +2791,9 @@ stream lacks this WebVTT file signature, then the parser aborts.

  • Otherwise, if |block| is a WebVTT region object, add |block| to |regions|.

    • +

  • Otherwise, if |block| is a WebVTT attributes object, and |attributes| has been + provided to this invocation of the WebVTT parser, let |attributes| be |block|.

    • +

  • collect a sequence of code points that are U+000A LINE FEED (LF) @@ -2753,6 +2834,8 @@ header set, the user agent must run the following steps:

  • Let |region| be null.

    • +

  • Let |attributes| be null.

    • +

  • Loop: Run these substeps in a loop:

    @@ -2934,7 +3017,40 @@ header set, the user agent must run the following steps:

    • - +
  • + +

    Otherwise, if |seen cue| is false and |buffer| starts with the substring + "ATTRIBUTES" (U+0041, U+0054, U+0054, U+0052, U+0049, U+0042, U+0055, U+0054, + U+0045, U+0053), and the remaining characters in |buffer| (if any) are all ASCII + whitespace, then run these substeps:

    + +
      + +

    1. Attributes creation: Let |attributes| be a new WebVTT attributes + object.

      2. + +

    2. Let |attributes|'s kind be the empty + string.

      3. + +

    3. Let |attributes|'s type be the empty + string.

      4. + +

    4. Let |attributes|'s language be the + empty string.

      5. + +

    5. Let |attributes|'s label be the empty + string.

      6. + +

    6. Let |attributes|'s custom pairs + be an empty list.

      7. + +

    7. Let |buffer| be the empty string.

      8. + +
    + +
    • + + @@ -2969,6 +3085,9 @@ header set, the user agent must run the following steps:

    using |region| for the results. Construct a WebVTT Region Object from |region|, and return it.

    +

  • Otherwise, if |attributes| is not null, then collect WebVTT attribute settings from + |buffer| using |attributes| for the results, and return |attributes|.

    • +

  • Otherwise, return null.

    • @@ -3106,6 +3225,56 @@ means that it is aborted at that point and returns nothing.

    + +

    WebVTT attributes settings parsing

    + +

    When the WebVTT parser algorithm says to collect WebVTT attribute settings +from a string |input| for a WebVTT attributes object |attributes|, the user agent must +run the following steps:

    + +
      + +

    1. Let |lines| be the result of splitting |input| on U+000A LINE FEED (LF) characters.

      2. + +
    2. +

      For each string |line| in |lines|, run the following substeps:

      +
        + +

      1. If |line| does not contain a U+003A COLON character (:), then jump to + the step labeled next line.

        2. + +

      2. Let |name| be the leading substring of |line| up to and excluding the first U+003A + COLON character.

        3. + +

      3. If |name| is not a valid WebVTT attribute key, then jump to the step labeled + next line.

        4. + +

      4. Let |value| be the trailing substring of |line| starting from the character + immediately after the first U+003A COLON character.

        5. + +

      5. If |value| is not empty and its first character is a U+0020 SPACE or U+0009 + CHARACTER TABULATION (tab) character, remove that first character from |value|.

        6. + +

      6. Let |value| be the result of + parsing + character references in |value|, with no additional allowed character.

        7. + +

      7. Run the WebVTT rules for parsing attribute key/value pairs for |name| and + |value| against |attributes|.

        8. + +

      8. Next line: Continue.

        9. + +
      +
      3. + +
    3. +

      If |attributes|'s custom pairs is not + empty and |attributes|'s type is the empty string, + then, parsers may generate a warning.

      +
      4. + +
    +

    WebVTT cue timings and settings parsing

    When the algorithm above says to collect WebVTT cue timings and settings from a string @@ -4294,32 +4463,81 @@ follows:

    -

    WebVTT rules for parsing attribute key/value pairs

    -

    The WebVTT rules for parsing attribute key/value pairs consist of the following algorithm.

    +

    WebVTT rules for parsing attribute key/value pairs

    + +

    The WebVTT rules for parsing attribute key/value pairs for a |name|/|value| pair +against a WebVTT attributes object |attributes| are as follows:

    -
      -
    1. Let |input| be the list of key/value pairs from a WebVTT attributes block.
      2. +
      1. - How the attribute is processed depends on its key name, as follows: + How the pair is processed depends on |name|, as follows:
        -
        If the key name is "kind" (ASCII case-insensitive)
        -
        Process the value as the kind attribute of a track element according to the HTML Standard.
        +
        If |name| is an ASCII + case-insensitive match for "kind"
        +
        +

        Let |normalized| be the result of + converting |value| to ASCII + lowercase.

        +

        If |normalized| is one of "subtitles", "captions", + "descriptions", "chapters", or "metadata", set + |attributes|'s kind to |normalized|.

        +

        Otherwise, ignore the pair.

        +
        + +
        If |name| is an ASCII + case-insensitive match for "type"
        +
        +

        Let |normalized| be the result of + converting |value| to ASCII + lowercase.

        +

        If |normalized| is "custom" or starts with the prefix + "custom-" (U+0063, U+0075, U+0073, U+0074, U+006F, U+006D, U+002D), set + |attributes|'s type to |normalized|.

        +

        Otherwise, if |normalized| is not the empty string, ignore the pair. All non-custom + type values are reserved for future standardization.

        +
        -
        If the key name is "lang" (ASCII case-insensitive)
        -
        Process the value as the srclang attribute of a track element according to the HTML Standard.
        +
        If |name| is an ASCII + case-insensitive match for "language"
        +
        Set |attributes|'s language to + |value|.
        -
        If the key name is "label" (ASCII case-insensitive)
        -
        Process the value as the label attribute of a track element according to the HTML Standard.
        +
        If |name| is an ASCII + case-insensitive match for "label"
        +
        Set |attributes|'s label to |value|.
        Otherwise
        -
        Ignore the key/value pair.
        +
        Append the pair (|name|, |value|) to |attributes|'s + custom pairs.
      -

      These keys are case-insensitive to allow compatibility with large video distributors already using this pattern in production.

      +

      The kind key is the only required key in a +WebVTT attributes block. It disambiguates the track kind and guards against naming +conflicts: consumers that do not recognise a given kind value should treat the +entire WebVTT attributes object as opaque. The type key further +differentiates subtypes within a kind (for example, distinguishing varieties of +metadata tracks). All non-custom type values are reserved for future +standardization; authors needing custom subtypes must use "custom" or a value +beginning with "custom-".

      + +

      The kind, type, language, and +label keys are matched +ASCII case-insensitively +to allow compatibility with implementations already using this pattern in production. +Unrecognized keys are preserved in the +custom pairs list for use by consuming +applications.

      + +

      The WebVTT attributes object's properties are consumed by the embedding +context. How kind, +language, and +label relate to the corresponding attributes of an +HTML <track> element is defined by the HTML specification. See +whatwg/html issue #11665.

      Rendering

      From 2ecef694cb71c3b02d2de50d10eef11281e8e0f3 Mon Sep 17 00:00:00 2001 From: James Craig Date: Mon, 9 Mar 2026 18:10:39 -0700 Subject: [PATCH 22/23] m. minor naming diffs I missed before push. --- index.bs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/index.bs b/index.bs index 518bc3e..5f8107e 100644 --- a/index.bs +++ b/index.bs @@ -1847,7 +1847,7 @@ SIGN).

      The kind key is the only required key in a WebVTT attributes block. It must appear in the block to disambiguate the track kind. -Without it, consumers cannot determine whether other well-known keys such as +Without it, consumers cannot determine whether other common key names such as language and label apply to a recognized track kind, and may treat them as opaque. See WebVTT rules for parsing attribute key/value pairs.

      @@ -3085,7 +3085,7 @@ header set, the user agent must run the following steps:

      using |region| for the results. Construct a WebVTT Region Object from |region|, and return it.

      -

    2. Otherwise, if |attributes| is not null, then collect WebVTT attribute settings from +

    3. Otherwise, if |attributes| is not null, then collect WebVTT attributes from |buffer| using |attributes| for the results, and return |attributes|.

      4. @@ -3228,11 +3228,11 @@ means that it is aborted at that point and returns nothing.

      WebVTT attributes settings parsing

      -

      When the WebVTT parser algorithm says to collect WebVTT attribute settings +

      When the WebVTT parser algorithm says to collect WebVTT attributes from a string |input| for a WebVTT attributes object |attributes|, the user agent must run the following steps:

      -
        +

        1. Let |lines| be the result of splitting |input| on U+000A LINE FEED (LF) characters.

          2. From 158e2125d27b2dd64369cb81ee38857d9cdad649 Mon Sep 17 00:00:00 2001 From: James Craig Date: Tue, 24 Mar 2026 15:36:07 -0700 Subject: [PATCH 23/23] Review comment from Nigel and Gary to keep captions example but remove subtitles example. --- index.bs | 25 ------------------------- 1 file changed, 25 deletions(-) diff --git a/index.bs b/index.bs index 5f8107e..fe9dfaa 100644 --- a/index.bs +++ b/index.bs @@ -370,31 +370,6 @@ CSS comment (e.g. /**/).

          - -
          - -

          In this example, an optional WebVTT attributes object is used to define the source language and its label in a subtitle/caption selection menu.

          - 
          -WEBVTT
-
-ATTRIBUTES
-kind: subtitles
-lang: es-mx
-label: Español
-
-NOTE
-Standard subtitles (unlike CC or SDH captions) typically 
-translate spoken dialog or signage, but not audible sound 
-effects like "dogs barking."
-
-1
-00:00:10.123 --> 00:00:15.432
-¡Hola! ¿Qué tál?
-
          - -
          - -

          In this example, an optional WebVTT attributes object is used to differentiate captions from standard subtitles.