WebVTT: The Web Video Text Tracks Format

https://www.w3.org/TR/webvtt/
Admin
This specification defines WebVTT, a format for marking up external text track resources for HTML...
Tokens:66,474
Snippets:316
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### WebVTT Example with Start Alignment

Source: https://www.w3.org/TR/webvtt/index

Shows how to use 'align:start' in WebVTT to align text based on its base direction (left for LTR, right for RTL).

```WebVTT
WEBVTT
00:00:00.000 --> 00:00:05.000
align:start
Hello!
שלום!
```

--------------------------------

### WebVTT Example with Start Alignment

Source: https://www.w3.org/TR/webvtt/1

Shows how to use 'align:start' in WebVTT to align text based on its base direction (left for LTR, right for RTL).

```WebVTT
WEBVTT
00:00:00.000 --> 00:00:05.000
align:start
Hello!
שלום!
```

--------------------------------

### WebVTT Cue Span Start Tag Syntax

Source: https://www.w3.org/TR/webvtt/index

Details the syntax for a WebVTT cue span start tag, including the tag name, optional classes, and the annotation format when required.

```APIDOC
WebVTT cue span start tag:
  1. U+003C LESS-THAN SIGN character (<).
  2. Tag name.
  3. Zero or more occurrences of:
     1. U+002E FULL STOP character (.).
     2. One or more characters (excluding specific control/special characters) representing a class.
  4. If annotation is required:
     1. U+0020 SPACE or U+0009 CHARACTER TABULATION (tab).
     2. One or more annotation components (text or HTML character reference).
  5. U+003E GREATER-THAN SIGN character (>).
```

--------------------------------

### WebVTT Cue Span Start Tag Syntax

Source: https://www.w3.org/TR/webvtt/1

Details the syntax for a WebVTT cue span start tag, including the tag name, optional classes, and the annotation format when required.

```APIDOC
WebVTT cue span start tag:
  1. U+003C LESS-THAN SIGN character (<).
  2. Tag name.
  3. Zero or more occurrences of:
     1. U+002E FULL STOP character (.).
     2. One or more characters (excluding specific control/special characters) representing a class.
  4. If annotation is required:
     1. U+0020 SPACE or U+0009 CHARACTER TABULATION (tab).
     2. One or more annotation components (text or HTML character reference).
  5. U+003E GREATER-THAN SIGN character (>).
```

--------------------------------

### WebVTT Basic Example with Arabic Text

Source: https://www.w3.org/TR/webvtt/index

Demonstrates a basic WebVTT cue with Arabic text, showing how bidirectional text might be rendered by default.

```WebVTT
WEBVTT
00:00:07.000 --> 00:00:09.000
What was his name again?
00:00:09.000 --> 00:00:11.000
عالي, I think.
```

--------------------------------

### WebVTT Balanced Wrapped Caption Example

Source: https://www.w3.org/TR/webvtt/index

Presents an example of WebVTT cues wrapped to maintain balanced line lengths, illustrating adaptive text display.

```WebVTT
      Never drink
    liquid nitrogen.

  — It will perforate
      your stomach.
    — You could die.

  The Organisation for
  Sample Public Service
  Announcements accepts
  no liability for the
     content of this
  advertisement, or for
   the consequences of
  any actions taken on
    the basis of the
  information provided.
```

--------------------------------

### WebVTT Example with Regions for ::cue-region

Source: https://www.w3.org/TR/webvtt/index

Demonstrates the definition and usage of regions in WebVTT, including setting an ID and applying styles to a specific region using the region:ID syntax within the cue text.

```WebVTT
WEBVTT

REGION id:editor-comments regionanchor:0%,0% viewportanchor:0%,0%
00:00:00.000 --> 00:00:08.000 No match (normal cue)

00:00:08.000 --> 00:00:16.000 region:editor-comments Yellow!
```

--------------------------------

### WebVTT Basic Example with Arabic Text

Source: https://www.w3.org/TR/webvtt/1

Demonstrates a basic WebVTT cue with Arabic text, showing how bidirectional text might be rendered by default.

```WebVTT
WEBVTT
00:00:07.000 --> 00:00:09.000
What was his name again?
00:00:09.000 --> 00:00:11.000
عالي, I think.
```

--------------------------------

### WebVTT Balanced Wrapped Caption Example

Source: https://www.w3.org/TR/webvtt/1

Presents an example of WebVTT cues wrapped to maintain balanced line lengths, illustrating adaptive text display.

```WebVTT
      Never drink
    liquid nitrogen.

  — It will perforate
      your stomach.
    — You could die.

  The Organisation for
  Sample Public Service
  Announcements accepts
  no liability for the
     content of this
  advertisement, or for
   the consequences of
  any actions taken on
    the basis of the
  information provided.
```

--------------------------------

### WebVTT Example with Regions for ::cue-region

Source: https://www.w3.org/TR/webvtt/1

Demonstrates the definition and usage of regions in WebVTT, including setting an ID and applying styles to a specific region using the region:ID syntax within the cue text.

```WebVTT
WEBVTT

REGION id:editor-comments regionanchor:0%,0% viewportanchor:0%,0%
00:00:00.000 --> 00:00:08.000 No match (normal cue)

00:00:08.000 --> 00:00:16.000 region:editor-comments Yellow!
```

--------------------------------

### WebVTT Example with Timestamps for :past/:future

Source: https://www.w3.org/TR/webvtt/index

Demonstrates the use of timestamps within WebVTT cue text to enable matching by the :past and :future pseudo-classes in CSS. This example shows how specific parts of a cue can be targeted.

```WebVTT
WEBVTT

00:00:00.000 --> 00:00:08.000 <c>No match (no timestamps)</c>
00:00:08.000 --> 00:00:16.000 No match <00:00:12.000> (no elements)
00:00:16.000 --> 00:00:24.000 <00:00:16.000> <c>This</c> <00:00:18.000> <c>can</c> <00:00:20.000> <c>match</c> <00:00:22.000> <c>:past/:future</c> <00:00:24.000>
```

--------------------------------

### WebVTT Example with Timestamps for :past/:future

Source: https://www.w3.org/TR/webvtt/1

Demonstrates the use of timestamps within WebVTT cue text to enable matching by the :past and :future pseudo-classes in CSS. This example shows how specific parts of a cue can be targeted.

```WebVTT
WEBVTT

00:00:00.000 --> 00:00:08.000 <c>No match (no timestamps)</c>
00:00:08.000 --> 00:00:16.000 No match <00:00:12.000> (no elements)
00:00:16.000 --> 00:00:24.000 <00:00:16.000> <c>This</c> <00:00:18.000> <c>can</c> <00:00:20.000> <c>match</c> <00:00:22.000> <c>:past/:future</c> <00:00:24.000>
```

--------------------------------

### WebVTT Cue Styling with Default Classes

Source: https://www.w3.org/TR/webvtt/index

This example demonstrates applying default text and background color classes to WebVTT cues using the `<c>` tag. It shows how to combine multiple classes for text and background styling, illustrating the use of classes like `.yellow`, `.bg_blue`, `.magenta`, and `.bg_black`.

```webvtt
WEBVTT

02:00.000 --> 02:05.000
<c.yellow.bg_blue>This is yellow text on a blue background</c>

04:00.000 --> 04:05.000
<c.yellow.bg_blue.magenta.bg_black>This is magenta text on a black background</c>
```

--------------------------------

### WebVTT Wrapped Caption Example

Source: https://www.w3.org/TR/webvtt/index

Shows how WebVTT cues can wrap to fit display width, demonstrating how explicit line breaks are still honored even with wrapping.

```WebVTT
           Never drink liquid nitrogen.

        — It will perforate your stomach.
                — You could die.

    The Organisation for Sample Public Service
    Announcements accepts no liability for the
    content of this advertisement, or for the
     consequences of any actions taken on the
        basis of the information provided.
```

--------------------------------

### WebVTT Cue Styling with Default Classes

Source: https://www.w3.org/TR/webvtt/1

This example demonstrates applying default text and background color classes to WebVTT cues using the `<c>` tag. It shows how to combine multiple classes for text and background styling, illustrating the use of classes like `.yellow`, `.bg_blue`, `.magenta`, and `.bg_black`.

```webvtt
WEBVTT

02:00.000 --> 02:05.000
<c.yellow.bg_blue>This is yellow text on a blue background</c>

04:00.000 --> 04:05.000
<c.yellow.bg_blue.magenta.bg_black>This is magenta text on a black background</c>
```

--------------------------------

### WebVTT ::cue Pseudo-element Styling

Source: https://www.w3.org/TR/webvtt/index

Demonstrates styling of WebVTT cues using the ::cue pseudo-element with various CSS selectors. Includes examples for general cues, ID-specific cues, element types within cues, class-based styling, attribute selectors, and language-based selection.

```APIDOC
::cue
  Applies styles to any WebVTT cue.
  CSS Syntax Example:
    video::cue {
      color: yellow;
    }
  WebVTT Syntax Example:
    WEBVTT
    00:00:00.000 --> 00:00:08.000 Yellow!
    00:00:08.000 --> 00:00:16.000 Also yellow!

::cue(selector)
  Applies styles to WebVTT cues or elements within cues that match the given selector.

  ID Selector:
    CSS Syntax Example:
      video::cue(#cue1) {
        color: yellow;
      }
    WebVTT Syntax Example:
      WEBVTT
      cue1 00:00:00.000 --> 00:00:08.000 Yellow!
    Description: Matches cues with a text track cue identifier matching the given ID.

  Type Selector:
    CSS Syntax Example:
      video::cue(c), video::cue(i), video::cue(b), video::cue(u), video::cue(ruby), video::cue(rt), video::cue(v), video::cue(lang) {
        color: yellow;
      }
    WebVTT Syntax Example:
      WEBVTT
      00:00:00.000 --> 00:00:08.000 <c>Yellow!</c> <i>Yellow!</i> <u>Yellow!</u> <b>Yellow!</b> <ruby>Yellow! <rt>Yellow!</rt></ruby> <v Kathryn>Yellow!</v> <lang en>Yellow!</lang>
    Description: Matches WebVTT Internal Node Objects (e.g., <b>, <i>, <c>) with the given tag name.

  Class Selector:
    CSS Syntax Example:
      video::cue(.loud) {
        color: yellow;
      }
    WebVTT Syntax Example:
      WEBVTT
      00:00:00.000 --> 00:00:08.000 <c.loud>Yellow!</c> <i.loud>Yellow!</i.loud>
    Description: Matches WebVTT Internal Node Objects with the given applicable classes.

  Attribute Selector:
    CSS Syntax Example:
      video::cue([lang="en-US"]) {
        color: yellow;
      }
      video::cue(v[voice="Kathryn"]) {
        color: lime;
      }
    WebVTT Syntax Example:
      WEBVTT
      00:00:00.000 --> 00:00:08.000 Yellow!
      00:00:08.000 --> 00:00:16.000 <lang en-GB>Cyan!</lang>
      00:00:16.000 --> 00:00:24.000 <v Kathryn>I like lime.</v>
    Description: Matches the root WebVTT Node Object or Language Object by 'lang' attribute, or WebVTT Voice Objects by 'voice' attribute.

  :lang() Pseudo-class:
    CSS Syntax Example:
      video::cue(:lang(en)) {
        color: yellow;
      }
      video::cue(:lang(en-GB)) {
        color: cyan;
      }
    WebVTT Syntax Example:
      WEBVTT
      00:00:00.000 --> 00:00:08.000 Yellow!
      00:00:08.000 --> 00:00:16.000 <lang en-GB>Cyan!</lang>
    Description: Matches WebVTT Internal Node Objects with an applicable language matching the given language range.
```

--------------------------------

### WebVTT Wrapped Caption Example

Source: https://www.w3.org/TR/webvtt/1

Shows how WebVTT cues can wrap to fit display width, demonstrating how explicit line breaks are still honored even with wrapping.

```WebVTT
           Never drink liquid nitrogen.

        — It will perforate your stomach.
                — You could die.

    The Organisation for Sample Public Service
    Announcements accepts no liability for the
    content of this advertisement, or for the
     consequences of any actions taken on the
        basis of the information provided.
```

--------------------------------

### WebVTT ::cue Pseudo-element Styling

Source: https://www.w3.org/TR/webvtt/1

Demonstrates styling of WebVTT cues using the ::cue pseudo-element with various CSS selectors. Includes examples for general cues, ID-specific cues, element types within cues, class-based styling, attribute selectors, and language-based selection.

```APIDOC
::cue
  Applies styles to any WebVTT cue.
  CSS Syntax Example:
    video::cue {
      color: yellow;
    }
  WebVTT Syntax Example:
    WEBVTT
    00:00:00.000 --> 00:00:08.000 Yellow!
    00:00:08.000 --> 00:00:16.000 Also yellow!

::cue(selector)
  Applies styles to WebVTT cues or elements within cues that match the given selector.

  ID Selector:
    CSS Syntax Example:
      video::cue(#cue1) {
        color: yellow;
      }
    WebVTT Syntax Example:
      WEBVTT
      cue1 00:00:00.000 --> 00:00:08.000 Yellow!
    Description: Matches cues with a text track cue identifier matching the given ID.

  Type Selector:
    CSS Syntax Example:
      video::cue(c), video::cue(i), video::cue(b), video::cue(u), video::cue(ruby), video::cue(rt), video::cue(v), video::cue(lang) {
        color: yellow;
      }
    WebVTT Syntax Example:
      WEBVTT
      00:00:00.000 --> 00:00:08.000 <c>Yellow!</c> <i>Yellow!</i> <u>Yellow!</u> <b>Yellow!</b> <ruby>Yellow! <rt>Yellow!</rt></ruby> <v Kathryn>Yellow!</v> <lang en>Yellow!</lang>
    Description: Matches WebVTT Internal Node Objects (e.g., <b>, <i>, <c>) with the given tag name.

  Class Selector:
    CSS Syntax Example:
      video::cue(.loud) {
        color: yellow;
      }
    WebVTT Syntax Example:
      WEBVTT
      00:00:00.000 --> 00:00:08.000 <c.loud>Yellow!</c> <i.loud>Yellow!</i.loud>
    Description: Matches WebVTT Internal Node Objects with the given applicable classes.

  Attribute Selector:
    CSS Syntax Example:
      video::cue([lang="en-US"]) {
        color: yellow;
      }
      video::cue(v[voice="Kathryn"]) {
        color: lime;
      }
    WebVTT Syntax Example:
      WEBVTT
      00:00:00.000 --> 00:00:08.000 Yellow!
      00:00:08.000 --> 00:00:16.000 <lang en-GB>Cyan!</lang>
      00:00:16.000 --> 00:00:24.000 <v Kathryn>I like lime.</v>
    Description: Matches the root WebVTT Node Object or Language Object by 'lang' attribute, or WebVTT Voice Objects by 'voice' attribute.

  :lang() Pseudo-class:
    CSS Syntax Example:
      video::cue(:lang(en)) {
        color: yellow;
      }
      video::cue(:lang(en-GB)) {
        color: cyan;
      }
    WebVTT Syntax Example:
      WEBVTT
      00:00:00.000 --> 00:00:08.000 Yellow!
      00:00:08.000 --> 00:00:16.000 <lang en-GB>Cyan!</lang>
    Description: Matches WebVTT Internal Node Objects with an applicable language matching the given language range.
```

--------------------------------

### WebVTT Example with Regions and ID Selector

Source: https://www.w3.org/TR/webvtt/index

Illustrates WebVTT region definition with IDs and how these IDs can be used in CSS selectors (e.g., #scroll) to target specific regions for styling, demonstrating the ::cue-region(selector) functionality.

```WebVTT
WEBVTT

REGION id:editor-comments width: 40% regionanchor:0%,100% viewportanchor:0%,100%
REGION id:scroll width: 40% regionanchor:100%,100% viewportanchor:90%,90% scroll:up
00:00:00.000 --> 00:00:08.000 No match (normal cue)
00:00:08.000 --> 00:00:16.000 region:editor-comments Yellow!
00:00:10.000 --> 00:00:16.000 region:scroll Over here it’s Cyan!
```

--------------------------------

### WebVTT Example with Unicode Bidi Formatting

Source: https://www.w3.org/TR/webvtt/index

Illustrates the use of U+2068 (FSI) and U+2069 (PDI) characters to correctly render bidirectional text within a WebVTT cue.

```WebVTT
WEBVTT
00:00:04.000 --> 00:00:08.000
I’ve read the book נוילנד 3 times!
```

--------------------------------

### WebVTT Nested Cues Example

Source: https://www.w3.org/TR/webvtt/index

Demonstrates a WebVTT file structure where cues exhibit a nested relationship, allowing them to be represented as a tree. This format adheres to the definition of a 'WebVTT file using only nested cues'.

```WebVTT
WEBVTT

00:00.000 --> 01:24.000
Introduction

00:00.000 --> 00:44.000
Topics

00:44.000 --> 01:19.000
Presenters

01:24.000 --> 05:00.000
Scrolling Effects

01:35.000 --> 03:00.000
Achim’s Demo

03:00.000 --> 05:00.000
Timeline Panel
```

--------------------------------

### WebVTT Example with Regions and ID Selector

Source: https://www.w3.org/TR/webvtt/1

Illustrates WebVTT region definition with IDs and how these IDs can be used in CSS selectors (e.g., #scroll) to target specific regions for styling, demonstrating the ::cue-region(selector) functionality.

```WebVTT
WEBVTT

REGION id:editor-comments width: 40% regionanchor:0%,100% viewportanchor:0%,100%
REGION id:scroll width: 40% regionanchor:100%,100% viewportanchor:90%,90% scroll:up
00:00:00.000 --> 00:00:08.000 No match (normal cue)
00:00:08.000 --> 00:00:16.000 region:editor-comments Yellow!
00:00:10.000 --> 00:00:16.000 region:scroll Over here it’s Cyan!
```

--------------------------------

### WebVTT Multi-line Caption Example

Source: https://www.w3.org/TR/webvtt/index

Illustrates how WebVTT handles line breaks within cues for multi-line captions, showing explicit line breaks and automatic wrapping.

```WebVTT
WEBVTT

00:01.000 --> 00:04.000
Never drink liquid nitrogen.

00:05.000 --> 00:09.000
— It will perforate your stomach.
— You could die.

00:10.000 --> 00:14.000
The Organisation for Sample Public Service Announcements accepts no liability for the content of this advertisement, or for the consequences of any actions taken on the basis of the information provided.
```

--------------------------------

### WebVTT Nested Cues Example

Source: https://www.w3.org/TR/webvtt/1

Demonstrates a WebVTT file structure where cues exhibit a nested relationship, allowing them to be represented as a tree. This format adheres to the definition of a 'WebVTT file using only nested cues'.

```WebVTT
WEBVTT

00:00.000 --> 01:24.000
Introduction

00:00.000 --> 00:44.000
Topics

00:44.000 --> 01:19.000
Presenters

01:24.000 --> 05:00.000
Scrolling Effects

01:35.000 --> 03:00.000
Achim’s Demo

03:00.000 --> 05:00.000
Timeline Panel
```

--------------------------------

### WebVTT Example with Unicode Bidi Formatting

Source: https://www.w3.org/TR/webvtt/1

Illustrates the use of U+2068 (FSI) and U+2069 (PDI) characters to correctly render bidirectional text within a WebVTT cue.

```WebVTT
WEBVTT
00:00:04.000 --> 00:00:08.000
I’ve read the book נוילנד 3 times!
```

--------------------------------

### WebVTT Multi-line Caption Example

Source: https://www.w3.org/TR/webvtt/1

Illustrates how WebVTT handles line breaks within cues for multi-line captions, showing explicit line breaks and automatic wrapping.

```WebVTT
WEBVTT

00:01.000 --> 00:04.000
Never drink liquid nitrogen.

00:05.000 --> 00:09.000
— It will perforate your stomach.
— You could die.

00:10.000 --> 00:14.000
The Organisation for Sample Public Service Announcements accepts no liability for the content of this advertisement, or for the consequences of any actions taken on the basis of the information provided.
```

--------------------------------

### WebVTT Cue Text Tokenizer and Parsing Logic

Source: https://www.w3.org/TR/webvtt/index

Describes the WebVTT cue text tokenizer and the steps for processing different token types (strings, start tags, end tags, timestamp tags) to build the cue text structure. It details how specific tags like 'c', 'i', 'b', 'u', 'ruby', 'rt', 'v', and 'lang' affect the parsing state and object creation.

```APIDOC
WebVTT Cue Text Parsing Process:

1.  **Initialization**:
    - If language is set, set result's applicable language and push language onto the language stack.

2.  **Loop**:
    - If position is past the end of input, return result and abort.
    - Let token be the result of invoking the WebVTT cue text tokenizer.

3.  **Token Processing**:
    - **If token is a string**:
        - Create a WebVTT Text Object whose value is the string token.
        - Append the Text Object to the current node.
    - **If token is a start tag**:
        - Process based on tag name:
            - `c`: Attach a WebVTT Class Object.
            - `i`: Attach a WebVTT Italic Object.
            - `b`: Attach a WebVTT Bold Object.
            - `u`: Attach a WebVTT Underline Object.
            - `ruby`: Attach a WebVTT Ruby Object.
            - `rt`: If current is a WebVTT Ruby Object, attach a WebVTT Ruby Text Object.
            - `v`: Attach a WebVTT Voice Object, set its value to the token’s annotation string (or empty string).
            - `lang`: Push the token’s annotation string (or empty string) onto the language stack; attach a WebVTT Language Object.
            - Otherwise: Ignore the token.
        - **Attachment Steps** (for WebVTT Internal Node Objects):
            - Create a new object of the specified concrete class.
            - Set its applicable classes to the token's classes (excluding empty strings).
            - Set its applicable language to the top of the language stack (if not empty).
            - Append the new object to the current node.
            - Let current be the newly created node object.
    - **If token is an end tag**:
        - If tag name matches current object type (e.g., `c` and current is WebVTT Class Object), let current be the parent node of current.
        - Specific end tag behaviors:
            - `lang`: Let current be parent, pop language stack.
            - `ruby` (end tag) and current is WebVTT Ruby Text Object: Let current be parent's parent.
            - Otherwise: Ignore the token.
    - **If token is a timestamp tag**:
        - Let input be the tag value.
        - Collect a WebVTT timestamp from input.
        - If timestamp collection succeeds and pointer is at end of input:
            - Create a WebVTT Timestamp Object with the collected time.
            - Append it to current.
        - Otherwise: Ignore the token.

4.  **Jump to Loop** (step 2).

**WebVTT Cue Text Tokenizer Output**: Emits tokens which are either strings, start tags (with tag name, list of classes), end tags, or timestamp tags.
```

--------------------------------

### WebVTT Cue Text Tokenizer and Parsing Logic

Source: https://www.w3.org/TR/webvtt/1

Describes the WebVTT cue text tokenizer and the steps for processing different token types (strings, start tags, end tags, timestamp tags) to build the cue text structure. It details how specific tags like 'c', 'i', 'b', 'u', 'ruby', 'rt', 'v', and 'lang' affect the parsing state and object creation.

```APIDOC
WebVTT Cue Text Parsing Process:

1.  **Initialization**:
    - If language is set, set result's applicable language and push language onto the language stack.

2.  **Loop**:
    - If position is past the end of input, return result and abort.
    - Let token be the result of invoking the WebVTT cue text tokenizer.

3.  **Token Processing**:
    - **If token is a string**:
        - Create a WebVTT Text Object whose value is the string token.
        - Append the Text Object to the current node.
    - **If token is a start tag**:
        - Process based on tag name:
            - `c`: Attach a WebVTT Class Object.
            - `i`: Attach a WebVTT Italic Object.
            - `b`: Attach a WebVTT Bold Object.
            - `u`: Attach a WebVTT Underline Object.
            - `ruby`: Attach a WebVTT Ruby Object.
            - `rt`: If current is a WebVTT Ruby Object, attach a WebVTT Ruby Text Object.
            - `v`: Attach a WebVTT Voice Object, set its value to the token’s annotation string (or empty string).
            - `lang`: Push the token’s annotation string (or empty string) onto the language stack; attach a WebVTT Language Object.
            - Otherwise: Ignore the token.
        - **Attachment Steps** (for WebVTT Internal Node Objects):
            - Create a new object of the specified concrete class.
            - Set its applicable classes to the token's classes (excluding empty strings).
            - Set its applicable language to the top of the language stack (if not empty).
            - Append the new object to the current node.
            - Let current be the newly created node object.
    - **If token is an end tag**:
        - If tag name matches current object type (e.g., `c` and current is WebVTT Class Object), let current be the parent node of current.
        - Specific end tag behaviors:
            - `lang`: Let current be parent, pop language stack.
            - `ruby` (end tag) and current is WebVTT Ruby Text Object: Let current be parent's parent.
            - Otherwise: Ignore the token.
    - **If token is a timestamp tag**:
        - Let input be the tag value.
        - Collect a WebVTT timestamp from input.
        - If timestamp collection succeeds and pointer is at end of input:
            - Create a WebVTT Timestamp Object with the collected time.
            - Append it to current.
        - Otherwise: Ignore the token.

4.  **Jump to Loop** (step 2).

**WebVTT Cue Text Tokenizer Output**: Emits tokens which are either strings, start tags (with tag name, list of classes), end tags, or timestamp tags.
```

--------------------------------

### WebVTT Cue Timings Structure

Source: https://www.w3.org/TR/webvtt/index

Defines the sequence and components of WebVTT cue timings, specifying the start and end time offsets for a cue block. It mandates that start times must be sequential and end times must be after start times.

```APIDOC
WebVTT cue timings:
  [WebVTT timestamp] (start time)
  (SPACE or TAB characters)
  -->
  (SPACE or TAB characters)
  [WebVTT timestamp] (end time)

  - Start time must be >= start times of previous cues.
  - End time must be > start time of the current cue.
  - Cues are ordered by start time.
  - Cues can overlap.
```

--------------------------------

### WebVTT Cue Timings Structure

Source: https://www.w3.org/TR/webvtt/1

Defines the sequence and components of WebVTT cue timings, specifying the start and end time offsets for a cue block. It mandates that start times must be sequential and end times must be after start times.

```APIDOC
WebVTT cue timings:
  [WebVTT timestamp] (start time)
  (SPACE or TAB characters)
  -->
  (SPACE or TAB characters)
  [WebVTT timestamp] (end time)

  - Start time must be >= start times of previous cues.
  - End time must be > start time of the current cue.
  - Cues are ordered by start time.
  - Cues can overlap.
```

--------------------------------

### WebVTT Cue Processing Steps

Source: https://www.w3.org/TR/webvtt/index

Details the substeps involved in processing lines to form WebVTT cues. It covers initialization, buffer management, and cue text assignment.

```APIDOC
ProcessWebVTTLine(line, previous_position, in_header, seen_cue, seen_eof, buffer, cue):
  // If line is the empty string, break out of loop.
  If line is empty string:
    break loop

  // Otherwise, run these substeps:
  // 1. If *in header* is not set and line count is 2, run these substeps:
  If not in_header and line_count is 2:
    // 1.1. If seen cue is false and buffer starts with 'STYLE' and remaining chars are ASCII whitespace:
    If not seen_cue and buffer starts with "STYLE" and remaining_chars_are_whitespace(buffer):
      // 1.1.1. Let stylesheet be the result of creating a CSS style sheet.
      stylesheet = CreateCSSStyleSheet(
        location=null,
        parent_css_style_sheet=null,
        owner_node=null,
        owner_css_rule=null,
        media="",
        title="",
        alternate_flag=unset,
        origin_clean_flag=set
      )
      // Let buffer be the empty string.
      buffer = ""
    // 1.2. Otherwise, if seen cue is false and buffer starts with 'REGION' and remaining chars are ASCII whitespace:
    Else if not seen_cue and buffer starts with "REGION" and remaining_chars_are_whitespace(buffer):
      // 1.2.1. *Region creation*: Let region be a new WebVTT region.
      region = NewWebVTTRegion(
        identifier="",
        width=100,
        lines=3,
        anchor_point=(0, 100),
        viewport_anchor_point=(0, 100),
        scroll_value="none"
      )
      // Let buffer be the empty string.
      buffer = ""

  // If buffer is not the empty string, append a U+000A LINE FEED (LF) character to buffer.
  If buffer is not empty:
    Append LF to buffer

  // Append line to buffer.
  Append line to buffer

  // Let previous position be position.
  previous_position = position

  // If seen EOF is true, break out of *loop*.
  If seen_eof:
    break loop

  // If cue is not null, let the cue text of cue be buffer, and return cue.
  If cue is not null:
    cue.text = buffer
    return cue

  // Otherwise, let cue's [cue text](#cue-text) be the empty string.
  cue.text = ""
  // Otherwise, let cue be null.
  cue = null
  // Otherwise, let buffer be the empty string and let seen cue be true.
  buffer = ""
  seen_cue = true

```

--------------------------------

### WebVTT Cue Processing Steps

Source: https://www.w3.org/TR/webvtt/1

Details the substeps involved in processing lines to form WebVTT cues. It covers initialization, buffer management, and cue text assignment.

```APIDOC
ProcessWebVTTLine(line, previous_position, in_header, seen_cue, seen_eof, buffer, cue):
  // If line is the empty string, break out of loop.
  If line is empty string:
    break loop

  // Otherwise, run these substeps:
  // 1. If *in header* is not set and line count is 2, run these substeps:
  If not in_header and line_count is 2:
    // 1.1. If seen cue is false and buffer starts with 'STYLE' and remaining chars are ASCII whitespace:
    If not seen_cue and buffer starts with "STYLE" and remaining_chars_are_whitespace(buffer):
      // 1.1.1. Let stylesheet be the result of creating a CSS style sheet.
      stylesheet = CreateCSSStyleSheet(
        location=null,
        parent_css_style_sheet=null,
        owner_node=null,
        owner_css_rule=null,
        media="",
        title="",
        alternate_flag=unset,
        origin_clean_flag=set
      )
      // Let buffer be the empty string.
      buffer = ""
    // 1.2. Otherwise, if seen cue is false and buffer starts with 'REGION' and remaining chars are ASCII whitespace:
    Else if not seen_cue and buffer starts with "REGION" and remaining_chars_are_whitespace(buffer):
      // 1.2.1. *Region creation*: Let region be a new WebVTT region.
      region = NewWebVTTRegion(
        identifier="",
        width=100,
        lines=3,
        anchor_point=(0, 100),
        viewport_anchor_point=(0, 100),
        scroll_value="none"
      )
      // Let buffer be the empty string.
      buffer = ""

  // If buffer is not the empty string, append a U+000A LINE FEED (LF) character to buffer.
  If buffer is not empty:
    Append LF to buffer

  // Append line to buffer.
  Append line to buffer

  // Let previous position be position.
  previous_position = position

  // If seen EOF is true, break out of *loop*.
  If seen_eof:
    break loop

  // If cue is not null, let the cue text of cue be buffer, and return cue.
  If cue is not null:
    cue.text = buffer
    return cue

  // Otherwise, let cue's [cue text](#cue-text) be the empty string.
  cue.text = ""
  // Otherwise, let cue be null.
  cue = null
  // Otherwise, let buffer be the empty string and let seen cue be true.
  buffer = ""
  seen_cue = true

```

--------------------------------

### WebVTT Basic Interview Captions

Source: https://www.w3.org/TR/webvtt/index

A sample WebVTT file demonstrating standard captioning for an interview. It includes timestamps, speaker tags (<v>), and the spoken text.

```WebVTT
WEBVTT

00:11.000 --> 00:13.000
<v Roger Bingham>We are in New York City

00:13.000 --> 00:16.000
<v Roger Bingham>We’re actually at the Lucern Hotel, just down the street

00:16.000 --> 00:18.000
<v Roger Bingham>from the American Museum of Natural History

00:18.000 --> 00:20.000
<v Roger Bingham>And with me is Neil deGrasse Tyson

00:20.000 --> 00:22.000
<v Roger Bingham>Astrophysicist, Director of the Hayden Planetarium

00:22.000 --> 00:24.000
<v Roger Bingham>at the AMNH.

00:24.000 --> 00:26.000
<v Roger Bingham>Thank you for walking down here.

00:27.000 --> 00:30.000
<v Roger Bingham>And I want to do a follow-up on the last conversation we did.

00:30.000 --> 00:31.500 align:right size:50%
<v Roger Bingham>When we e-mailed—

00:30.500 --> 00:32.500 align:left size:50%
<v Neil deGrasse Tyson>Didn’t we talk about enough in that conversation?

00:32.000 --> 00:35.500 align:right size:50%
<v Roger Bingham>No! No no no no; 'cos 'cos obviously 'cos

00:32.500 --> 00:33.500 align:left size:50%
<v Neil deGrasse Tyson><i>Laughs</i>

00:35.500 --> 00:38.000
<v Roger Bingham>You know I’m so excited my glasses are falling off here.
```

--------------------------------

### WebVTT Cue Settings List Syntax

Source: https://www.w3.org/TR/webvtt/index

Details the structure of a WebVTT cue settings list, which allows for optional metadata like alignment, position, and size. Settings are key-value pairs separated by whitespace.

```APIDOC
WebVTT cue settings list:
  [setting1] [setting2] ...

  Each setting:
    [setting name] (optional ':' [setting value])

  - Setting name/value: Sequence of characters excluding LF/CR, must not contain '-->'.
  - Separators: SPACE or TAB characters.
  - Order: Any.
```

--------------------------------

### WebVTT Basic Interview Captions

Source: https://www.w3.org/TR/webvtt/1

A sample WebVTT file demonstrating standard captioning for an interview. It includes timestamps, speaker tags (<v>), and the spoken text.

```WebVTT
WEBVTT

00:11.000 --> 00:13.000
<v Roger Bingham>We are in New York City

00:13.000 --> 00:16.000
<v Roger Bingham>We’re actually at the Lucern Hotel, just down the street

00:16.000 --> 00:18.000
<v Roger Bingham>from the American Museum of Natural History

00:18.000 --> 00:20.000
<v Roger Bingham>And with me is Neil deGrasse Tyson

00:20.000 --> 00:22.000
<v Roger Bingham>Astrophysicist, Director of the Hayden Planetarium

00:22.000 --> 00:24.000
<v Roger Bingham>at the AMNH.

00:24.000 --> 00:26.000
<v Roger Bingham>Thank you for walking down here.

00:27.000 --> 00:30.000
<v Roger Bingham>And I want to do a follow-up on the last conversation we did.

00:30.000 --> 00:31.500 align:right size:50%
<v Roger Bingham>When we e-mailed—

00:30.500 --> 00:32.500 align:left size:50%
<v Neil deGrasse Tyson>Didn’t we talk about enough in that conversation?

00:32.000 --> 00:35.500 align:right size:50%
<v Roger Bingham>No! No no no no; 'cos 'cos obviously 'cos

00:32.500 --> 00:33.500 align:left size:50%
<v Neil deGrasse Tyson><i>Laughs</i>

00:35.500 --> 00:38.000
<v Roger Bingham>You know I’m so excited my glasses are falling off here.
```

--------------------------------

### WebVTT Cue Settings List Syntax

Source: https://www.w3.org/TR/webvtt/1

Details the structure of a WebVTT cue settings list, which allows for optional metadata like alignment, position, and size. Settings are key-value pairs separated by whitespace.

```APIDOC
WebVTT cue settings list:
  [setting1] [setting2] ...

  Each setting:
    [setting name] (optional ':' [setting value])

  - Setting name/value: Sequence of characters excluding LF/CR, must not contain '-->'.
  - Separators: SPACE or TAB characters.
  - Order: Any.
```

--------------------------------

### WebVTT Comment Block Structure

Source: https://www.w3.org/TR/webvtt/index

Describes the format for WebVTT comment blocks, which are ignored by the parser. Comments start with 'NOTE' and can contain arbitrary text separated by line terminators.

```APIDOC
WebVTT comment block:
  NOTE
  (optional:
    SPACE or TAB
    [WebVTT line terminator]
    [any characters except LF/CR, optionally separated by line terminators]
    [WebVTT line terminator]
  )

  - Ignored by WebVTT parsers.
```

--------------------------------

### WebVTT: Chapter Markers

Source: https://www.w3.org/TR/webvtt/index

Demonstrates using WebVTT to define chapter markers for video content. Chapters are plain text cues that act as navigation points, typically placed before the timed cue they represent.

```WebVTT
WEBVTT

NOTE
This is from a talk Silvia gave about WebVTT.

Slide 1
00:00:00.000 --> 00:00:10.700
Title Slide

Slide 2
00:00:10.700 --> 00:00:47.600
Introduction by Naomi Black

Slide 3
00:00:47.600 --> 00:01:50.100
Impact of Captions on the Web

Slide 4
00:01:50.100 --> 00:03:33.000
Requirements of a Video text format

```

--------------------------------

### WebVTT: Multi-line Comments

Source: https://www.w3.org/TR/webvtt/index

Shows how to embed multiple lines of comments in a WebVTT file. Comments are delimited by blank lines and start with 'NOTE'. This allows for detailed annotations or metadata.

```WebVTT
WEBVTT

NOTE
This file was written by Jill. I hope
you enjoy reading it. Some things to
bear in mind:
- I was lip-reading, so the cues may
not be 100% accurate
- I didn’t pay too close attention to
when the cues should start or end.

00:01.000 --> 00:04.000
Never drink liquid nitrogen.

NOTE check next cue

00:05.000 --> 00:09.000
— It will perforate your stomach.
— You could die.

NOTE end of file

```

--------------------------------

### WebVTT: Single-line Comments

Source: https://www.w3.org/TR/webvtt/index

Illustrates how to include single-line comments within a WebVTT file. Comments are identified by starting with 'NOTE' after a blank line and end at the next blank line.

```WebVTT
WEBVTT

00:01.000 --> 00:04.000
Never drink liquid nitrogen.

NOTE I’m not sure the timing is right on the following cue.

00:05.000 --> 00:09.000
— It will perforate your stomach.
— You could die.

```

--------------------------------

### WebVTT Comment Block Structure

Source: https://www.w3.org/TR/webvtt/1

Describes the format for WebVTT comment blocks, which are ignored by the parser. Comments start with 'NOTE' and can contain arbitrary text separated by line terminators.

```APIDOC
WebVTT comment block:
  NOTE
  (optional:
    SPACE or TAB
    [WebVTT line terminator]
    [any characters except LF/CR, optionally separated by line terminators]
    [WebVTT line terminator]
  )

  - Ignored by WebVTT parsers.
```
Tokens:
Raw