The "region" concept

WebVTT currently deals with two layout concepts: the text area that is to be rendered, and the video viewport. (Actually, there is a third: the line box - but it is orthogonal to the issue at hand.) In other caption formats (in particular in CEA-608 and CEA-708), a third concept exists: the concept of a rendering region which holds multiple cues. It is called "window" in CEA-708 [CEA-708].

This specification introduces the CEA-708 "window" concept into WebVTT under the term "region", because the term "window" already bears a different meaning on the Web. This specification's main goal is to allow for a simple implementation of rollup captions, but it also satisfies other use cases:

• It introduces the ability to move a group of captions from one location on the video to another without having to copy the cues.
• It introduces the ability to style the region's background and border differently from the cues it contains.
• It introduces a means to specify an anchor point and a growth direction for the text that is rendered on screen and thus gives the author more control over the placement of text when the user changes the font size.
• It introduces the ability to specify a caption rendering region of fixed width with a fixed number of rendered lines to also give the author more control over the amount of space on the video viewport that captions will take up when the user changes font size.
• It introduces the ability to specify which region is to be rendered in the foreground in the case of region overlap e.g. when the user increases caption font size.

Many of these features are part of what the US FCC (Federal Communications Commission) has required for Captioning of Internet Video Programming [FCC].

Example WebVTT file with regions

The following example shows two regions containing rollup captions for two different speakers. Fred's cues scroll up in a region in the left half of the video, Bill's cues scroll up in a region on the right half of the video. Fred's first cue disappears at 12.5sec even through it is defined until 20sec because its region is limited to 3 lines and at 12.5sec a fourth cue appears:

WEBVTT
Region: id=fred width=50% lines=3 regionanchor=0%,100% viewportanchor=10%,90% scroll=up
Region: id=bill width=50% lines=3 regionanchor=100%,100% viewportanchor=90%,90% scroll=up

00:00:00.000 --> 00:00:20.000 region:fred align:left
Hi, my name is Fred

00:00:02.500 --> 00:00:22.500 region:bill align:right
Hi, I'm Bill

00:00:05.000 --> 00:00:25.000 region:fred align:left
Would you like to get a coffee?

00:00:07.500 --> 00:00:27.500 region:bill align:right
Sure! I've only had one today.

00:00:10.000 --> 00:00:30.000 region:fred align:left
This is my fourth!

00:00:12.500 --> 00:00:32.500 region:fred align:left
OK, let's go.

Text track region

A text track region represents a subpart of the video viewport and provides a rendering area for text track cues.

Each text track region consists of:

An identifier

An arbitrary string.

A width

A number giving the width of the box within which the text of each line of the containing cues is to be rendered, to be interpreted as a percentage of the video width. Defaults to 100.

A lines value

A number giving the number of lines of the box within which the text of each line of the containing cues is to be rendered. Defaults to 3.

A region anchor point

Two numbers giving the x and y coordinates within the region which is anchored to the video viewport and does not change location even when the region does, e.g. because of font size changes. Defaults to (0,100), i.e. the bottom left corner of the region.

A region viewport anchor point

Two numbers giving the x and y coordinates within the video viewport to which the region anchor point is anchored. Defaults to (0,100), i.e. the bottom left corner of the viewport.

A scroll value

One of the following:

None

Indicates that the cues in the region are not to scroll and instead stay fixed at the location they were first painted in.

Up

Indicates that the cues in the region will be added at the bottom of the region and push any already displayed cues in the region up until all lines of the new cue are visible in the region.

Text track list of regions

Extension of text track cue

In addition to the existing attributes, each text track cue also consists of:

A region identifier

A string that references by identifier the region that a cue belongs to, if it is not null.

Also, update the following text track cue attribute definitions:

A text position

A number giving the position of the text of the cue within each line. If the cue is not within a region, to be interpreted as a percentage of the video, as defined by the writing direction, otherwise to be interpreted as a percentage of the region width.

When a text track cue whose active flag is set has its writing direction, snap-to-lines flag, line position, text position, size, alignment, region identifier or text change value, then the user agent must empty the text track cue display state, and then immediately run the text track's rules for updating the display of WebVTT text tracks.

Extension of the WebVTT file body syntax

The specification of a the "WebVTT file body" syntax in the WebVTT specification is extended to the following:

A WebVTT file body consists of the following components, in the following order:

1. An optional U+FEFF BYTE ORDER MARK (BOM) character.
2. The string "WEBVTT".
3. Optionally, either a U+0020 SPACE character or a U+0009 CHARACTER TABULATION (tab) character followed by any number of characters that are not U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN (CR) characters.
4. One or more WebVTT line terminator to terminate the line with the file magic and separate it from the rest of the file body.
5. Zero or more WebVTT metadata headers and WebVTT comments separated from each other by two or more WebVTT line terminators.
6. One or more WebVTT line terminators to terminate the header block and separate the cues from the file header.
7. Zero or more WebVTT cues and WebVTT comments separated from each other by two or more WebVTT line terminators.
8. Zero or more WebVTT line terminators.

WebVTT metadata header syntax

A WebVTT metadata header consists of the following components, in the given order:

1. A WebVTT metadata header name.
2. A U+003A COLON (colon) character.
3. A WebVTT metadata header value.

A WebVTT metadata header name and a WebVTT metadata header value each consist 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).

WebVTT region metadata header syntax

A WebVTT region metadata header is a special kind of WebVTT metadata header where both of the following apply:

• The WebVTT metadata header name is the string "Region".
• The WebVTT metadata header value are WebVTT region settings.

WebVTT region and WebVTT region settings syntax

A WebVTT region represents its region settings.

The WebVTT region settings part of a WebVTT region metadata header consists of zero or more of the following components, in any order, separated from each other by one or more U+0020 SPACE characters or U+0009 CHARACTER TABULATION (tab) characters. Each component must not be included more than once per WebVTT region setting string.

• A WebVTT region identifier.
• A WebVTT region width setting.
• A WebVTT region lines setting.
• A WebVTT region anchor setting.
• A WebVTT region viewport anchor setting.
• A WebVTT region scroll setting.

WebVTT region settings give configuration options regarding the dimensions, positioning and anchoring of the region. For example, it allows a group of cues within a region to be anchored in the center of the region and the center of the video viewport. In this example, when the font size grows, the region grows uniformly in all directions from the center.

A WebVTT region identifier consists of the following components, in the order given:

1. The string "id".

2. A U+003D EQUALS SIGN character (=).

3. An arbitrary string of one or more characters other than U+0020 SPACE or U+0009 CHARACTER TABULATION character. The string must not contain the substring "-->" (U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN).

The WebVTT region identifier gives a name to the region so it can be referenced by the cues that belong to the region.

A WebVTT region width setting consists of the following components, in the order given:

1. The string "width".

2. A U+003D EQUALS SIGN character (=).

3. One or more ASCII digits.

4. An optional U+002E DOT character (.).

5. One or more ASCII digits.

6. A U+0025 PERCENT SIGN character (%).

The WebVTT region width setting provides a fixed width as a percentage of the video width for the region into which cues are rendered and based on which alignment is calculated.

A WebVTT region lines setting consists of the following components, in the order given:

1. The string "lines".

2. A U+003D EQUALS SIGN character (=).

3. One or more ASCII digits.

The WebVTT region lines setting provides a fixed height as a number of lines for the region into which cues are rendered. As such, it defines the height of the roll-up region if it is a scroll region.

A WebVTT region anchor setting consists of the following components, in the order given:

1. The string "regionanchor".

2. A U+003D EQUALS SIGN character (=).

3. One or more ASCII digits.

4. An optional U+002E DOT character (.).

5. One or more ASCII digits.

6. A U+0025 PERCENT SIGN character (%).

7. A U+002C COMMA character (,).

8. One or more ASCII digits.

9. An optional U+002E DOT character (.).

10. One or more ASCII digits.

11. A U+0025 PERCENT SIGN character (%).

The WebVTT region anchor setting provides a tuple of two percentages that specify the point within the region box that is fixed in location. The first percentage measures the x-dimension and the second percentage y-dimension from the top left corner of the region box. If no WebVTT region anchor setting is given, the anchor defaults to 0%, 100% (i.e. the bottom left corner).

A WebVTT region viewport anchor setting consists of the following components, in the order given:

1. The string "viewportanchor".

2. A U+003D EQUALS SIGN character (=).

3. One or more ASCII digits.

4. An optional U+002E DOT character (.).

5. One or more ASCII digits.

6. A U+0025 PERCENT SIGN character (%).

7. A U+002C COMMA character (,).

8. One or more ASCII digits.

9. An optional U+002E DOT character (.).

10. One or more ASCII digits.

11. A U+0025 PERCENT SIGN character (%).

The WebVTT region viewport anchor setting provides a tuple of two percentages that specify the point within the video viewport that the region anchor point is anchored to. The first percentage measures the x-dimension and the second percentage measures the y-dimension from the top left corner of the video viewport box. If no viewport anchor is given, it defaults to 0%, 100% (i.e. the bottom left corner).

For browsers, the region maps to an absolute positioned CSS box relative to the video viewport, i.e. there is a relative positioned box that represents the video viewport relative to which the regions are absolutely positioned. Overflow is hidden.

A WebVTT region scroll setting consists of the following components, in the order given:

1. The string "scroll".

2. A U+003D EQUALS SIGN character (=).

3. The string "up".

The WebVTT region scroll setting specifies whether cues rendered into the region are allowed to move out of their initial rendering place and roll up, i.e. move towards the top of the video viewport. If the scroll setting is omitted, cues do not move from their rendered position.

Cues are added to a region one line at a time below existing cue lines. When an existing rendered cue line is removed, and it was above another already rendered cue line, that cue line moves into its space, thus scrolling in the given direction. If there is not enough space for a new cue line to be added to a region, the top-most cue line is pushed off the visible region (thus slowly becoming invisible as it moves into overflow:hidden). This eventually makes space for the new cue line and allows it to be added.

When there is no scroll direction, cue lines are added in the empty line closest to the line in the bottom of the region. If no empty line is available, the oldest line is replaced.

WebVTT region cue setting syntax

This specification extends the existing set of WebVTT cue settings with a new setting.

A WebVTT region cue setting consists of the following components, in the order given:

1. The string "region".

2. A U+003A COLON character (:).

3. An arbitrary string of one or more characters other than U+0020 SPACE or U+0009 CHARACTER TABULATION character. The string must not contain the substring "-->" (U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN).

A WebVTT region cue setting configures a cue to become part of a region by referencing the region's identifier unless the cue has a "vertical", "line" or "size" cue setting. If a cue is part of a region, its cue settings for "position" and "align" are applied to the line boxes in the cue relative to the region box.

Extension of WebVTT header parsing (step 11-15)

This is an extension of the WebVTT parser algorithm.

Introduce an additional variable regions to be a text track list of regions, which the WebVTT parser will create in addition to the text track list of cues output.

15. Metadata header loop: If line is not the empty string, run the following substeps:

    1. Metadata header creation: Let metadata be a new WebVTT metadata header.

    2. Let metadata's name be the empty string.

    3. Let metadata's value be the empty string.

    4. If line contains the character ":" (A U+003A COLON), then set metadata's name to the substring of line before the first ":" character and metadata's value to the substring after this character.

    5. If metadata's name equals "Region":

       1. Region creation: Let region be a new text track region.
       2. Let region's identifier be the empty string.
       3. Let region's width be 100.
       4. Let region's lines be 3.
       5. Let region's anchor point be (0,100).
       6. Let region's viewport anchor point be (0,100).
       7. Let region's scroll value be NONE.
       8. Collect WebVTT region settings from metadata's value using region for the results.
       9. Region processing: Construct a WebVTT Region Object from region, follow the WebVTT region DOM construction rule and have the WebVTT Region Object take part in the WebVTT cue text rendering rules extended as below.
       10. If the text track list of regions regions contains a region with the same region identifier value as region, remove that region.
       11. Add region to the text track list of regions regions.

    6. Jump back to the step labeled header.

This specification ignores all WebVTT metadata headers that don't specify regions.

Introduction of a WebVTT region settings parser

We first introduce an algorithm to parse a percentage string and then the algorithm to collect WebVTT region settings.

The rules to parse a percentage string are as follows. This will return a percentage value or, if at any point the algorithm says that it "fails", this means that it is aborted at that point with an IndexSizeError and returns nothing.

1. Let input be the string being parsed.

2. If input contains any characters other than U+0025 PERCENT SIGN characters (%), U+002E DOT characters (.) and ASCII digits, then fail.

3. If input does not contain at least one ASCII digit, then fail.

4. If input contains more than one U+002E DOT character (.), then fail.

5. If any character in input other than the last character is a U+0025 PERCENT SIGN character (%), then fail.

6. If the last character in input is not a U+0025 PERCENT SIGN character (%), then fail.

7. Ignoring the trailing percent sign, interpret input as a real number. Let that number be the percentage.

8. If percentage is outside Throws an the range 0.0% .. 100.0%, fail.

9. Return percentage.

When the algorithm above requires that the user agent collect WebVTT region settings from a string input for a text track, the user agent must run the following algorithm. This algorithm returns a list of WebVTT Region Objects.

1. Let settings be the result of splitting input on spaces.

2. For each token setting in the list settings, run the following substeps:

   1. If setting does not contain a U+003D EQUALS SIGN character (=), or if the first U+003D EQUALS SIGN character (=) in setting is either the first or last character of setting, then jump to the step labeled next setting.

   2. Let name be the leading substring of setting up to and excluding the first U+003D EQUALS SIGN character (=) in that string.

   3. Let value be the trailing substring of setting starting from the character immediately after the first U+003D EQUALS SIGN character (=) in that string.

   4. Run the appropriate substeps that apply for the value of name, as follows:

      If name is a case-sensitive match for "id"

      Let region's identifier be value.

      Otherwise if name is a case-sensitive match for "width"

      If parse a percentage string from value returns a percentage, let region's text track region width be percentage.

      Otherwise if name is a case-sensitive match for "lines"

      1. If value contains any characters other than ASCII digits, then jump to the step labeled next setting.

      2. Interpret value as an integer, and let number be that number.

      3. Let region's text track region lines be number.

      Otherwise if name is a case-sensitive match for "regionanchor"

      1. If value does not contain a U+002C COMMA character (,), then jump to the step labeled next setting.

      2. Let anchorX be the leading substring of value up to and excluding the first U+002C COMMA character (,) in that string.

      3. Let anchorY be the trailing substring of value starting from the character immediately after the first U+002C COMMA character (,) in that string.

      4. If parse a percentage string from anchorX or parse a percentage string from anchorY don't return a percentage, then jump to the step labeled next setting.

      5. Let region's text track region anchor point be the tuple of the percentage values calculated from anchorX and anchorY.

      Otherwise if name is a case-sensitive match for "viewportanchor"

      1. If value does not contain a U+002C COMMA character (,), then jump to the step labeled next setting.

      2. Let viewportanchorX be the leading substring of value up to and excluding the first U+002C COMMA character (,) in that string.

      3. Let viewportanchorY be the trailing substring of value starting from the character immediately after the first U+002C COMMA character (,) in that string.

      4. If parse a percentage string from viewportanchorX or parse a percentage string from viewportanchorY don't return a percentage, then jump to the step labeled next setting.

      5. Let region's text track region viewport anchor point be the tuple of the percentage values calculated from viewportanchorX and viewportanchorY.

      Otherwise if name is a case-sensitive match for "scroll"

      1. If value is a case-sensitive match for the string "up", then let region's scroll value be "scroll up".

   5. Next setting: Continue to the next setting, if any.

Extension of WebVTT cue creation (step 20-35)

This is an extension of the WebVTT parser algorithm.

Introduce an additional assignment step after step 28.

• Let cue's region identifier be the empty string.

Extension of WebVTT cue setting parsing

This is an extension of the algorithm to parse the WebVTT settings.

Introduce an additional substep for step 4.

If name is a case-sensitive match for "region"

1. Let cue's region identifier be value.

Also add an additional step 5 to the algorithm to parse the WebVTT settings:

5. If cue's line position is not auto or cue's size is not 100 or cue's writing direction is not horizontal, but cue's region identifier is not the empty string, let cue's region identifier be the empty string.

This makes sure that no matter in which order the cue settings are provided, if the cue has a line position or a size setting or is vertical, the region identifier will be ignored.

Prepare region list

Extend step 7 to include regions and prepare the region list:

7. Let cues be an empty list of text track cues and regions be an empty list of text track regions. For each track track in tracks append to regions all the regions from track's text track list of regions.

Prepare region CSS boxes

Add the following steps after step 8 to prepare the CSS boxes for regions:

• If reset is false, then, for each text track region region in regions let regionNode be a WebVTT region object.

• Apply the following steps for each regionNode:

  1. Prepare some variables for the application of CSS properties to regionNode as follows:

     • Let regionWidth be the text track region width. Let width be 'regionWidth vw' ('vw' is a CSS unit).[CSSVALUES]

     • Let lineHeight be '0.0533vh' ('vh' is a CSS unit).[CSSVALUES] and regionHeight be the text track region lines. Let lines be 'lineHeight multiplied by regionHeight.

     • Let viewportAnchorX be the x dimension of the text track region viewport anchor and regionAnchorX be the x dimension of the text track region anchor. Let leftOffset be regionAnchorX multiplied by width divided by 100.0. Let left be leftOffset subtracted from 'viewportAnchorX vw'.

     • Let viewportAnchorY be the y dimension of the text track region viewport anchor and regionAnchorY be the y dimension of the text track region anchor. Let topOffset be regionAnchorY multiplied by lines divided by 100.0. Let top be topOffset subtracted from 'viewportAnchorY vh'.

  2. Apply the terms of the CSS specifications to regionNode within the following constraints, thus obtaining a CSS box box positioned relative to an initial containing block:

     1. No style sheets are associated with regionNode. (The regionNodes are subsequently restyled using style sheets after their boxes are generated, as described below.)

     2. Properties on regionNode have their values set as defined in the next section. (That section uses some of the variables whose values were calculated earlier in this algorithm.)

     3. The viewport (and initial containing block) is video's rendering area.

  3. Add the CSS box box to output.

Extend reusing already rendered CSS boxes of cues

Replace step 9 with the following extended step 9:

9. If reset is false, then, for each text track cue cue in cues: if cue's text track cue display state has a set of CSS boxes, then:

   • if there is a WebVTT region whose region identifier is identical to cue's text track cue region identifier:

     add those boxes to that region's box and remove cue from cues.

   • otherwise:

     add those boxes to output and remove cue from cues.

Extend rendering cues into region CSS boxes

Make step 10's substeps apply only to text track cues whose text track cue region identifier does not match with the region identifier of a WebVTT region, if any. Add alternative substeps for text track cues in regions:

10. For each text track cue cue in cues that has not yet had corresponding CSS boxes added to output, in text track cue order, run the following substeps:

    • If cue has an empty text track cue region identifier or there is no WebVTT region whose region identifier is identical to cue's text track cue region identifier, run the following substeps:

      [Run substep 1-17 as defined in the WebVTT spec.]

    • Otherwise run the following substeps:

      1. Let region be the WebVTT region whose region identifier matches the text track cue region identifier of cue.

      2. If region's text track region scroll setting is 'up' and region already has one child, set region's 'transition-property' to 'top' and 'transition-duration' to '0.433s'.

      3. Let nodes be the list of WebVTT Node Objects obtained by applying the WebVTT cue text parsing rules to the cue's text track cue text.

      4. Apply the Unicode Bidirectional Algorithm's Paragraph Level steps to the concatenation of the values of each WebVTT Text Object in nodes, in a pre-order, depth-first traversal, excluding WebVTT Ruby Text Objects and their descendants, to determine the paragraph embedding level of the first Unicode paragraph of the cue. [BIDI]

         Within a cue, paragraph boundaries are only denoted by Type B characters, such as U+000A LINE FEED (LF), U+0085 NEXT LINE (NEL), and U+2029 PARAGRAPH SEPARATOR. (This means each line of the cue is reordered as if it was a separate paragraph.)

      5. If the paragraph embedding level determined in the previous step is even (the paragraph direction is left-to-right), let direction be 'ltr', otherwise, let it be 'rtl'.

      6. Let offset be the text track cue text position multiplied by the width of the WebVTT region object whose region identifier is identical to cue's text track cue region identifier and divided by 100 (i.e. interpret it as a percentage of the region width).

      7. If direction is 'ltr' and 'text-align' is 'start' or 'left', or if direction is 'rtl' and 'text-align' is 'end' or 'left', let left be offset and let right be 'auto'

         If direction is 'ltr' and 'text-align' is 'end' or 'right', or if direction is 'rtl' and 'text-align' is 'start' or 'right', let left be 'auto' and right be offset.

         If 'text-align' is 'middle', ignore the offset.

      8. Apply the terms of the CSS specifications to nodes in the same way that they are applied to in step 10, substep 12 is applied to nodes of a cue that is not part of a region, except that the initial containing block is region.

         Let boxes be the boxes generated as descendants of the initial containing block, along with their positions.

      9. If there are no line boxes in boxes, skip the remainder of these substeps for cue. The cue is ignored.

      10. Let cue's text track cue display state have the CSS boxes in boxes.

      11. Add the CSS boxes in boxes to region.

Applying CSS properties to WebVTT Region Objects and their children

When following the extended rules for updating the display of WebVTT text tracks, user agents must set properties of WebVTT region objects at the CSS user agent cascade layer as defined in this section. [CSS]

Every WebVTT region object is initialised with the following CSS settings:

• the 'position' property must be set to 'absolute'
• the 'writing-mode' property must be set to 'horizontal-tb'
• the 'background' shorthand property must be set to 'rgba(0,0,0,0.8)'
• the 'word-wrap' property must be set to 'break-word'
• the 'overflow-wrap' property must be set to 'break-word'
• the 'font' shorthand property must be set to '(0.0533/1.3)vh sans-serif'
• the 'line-height' shorthand property must be set to '0.0533vh'
• the 'color' property must be set to 'rgba(255,255,255,1)'
• the 'overflow' property must be set to 'hidden'
• the 'width' property must be set to width
• the 'min-height' property must be set to '0px'
• the 'max-height' property must be set to height
• the 'left' property must be set to left
• the 'right' property must be set to right
• the 'top' property must be set to top
• the 'display' property must be set to 'inline-flex'
• the 'flex-flow' property must be set to 'column'
• the 'justify-content' property must be set to 'flex-end'

The variables width, height, top, and left are the values with those names determined by the rules for updating the display of WebVTT text tracks for the text track region from which the WebVTT region object was constructed.

The children of every WebVTT region object are not initialised with the CSS properties of (root) List of WebVTT Node Objects but instead with these CSS settings:

• the 'position' property must be set to 'relative'
• the 'unicode-bidi' property must be set to 'plaintext'
• the 'width' property must be set to 'auto'
• the 'height' property must be set to height
• the 'left' property must be set to left
• the 'text-align' property must be set as described for (root) List of WebVTT Node Objects not part of a region

All other non-inherited properties must be set to their initial values; inherited properties must inherit their values from the media element for which the text track region is being rendered, if any. If there is no media element (i.e. if the text track is being rendered for another media playback mechanism), then inherited properties on the WebVTT region objects must take their initial values.

If there are style sheets that apply to the media element or other playback mechanism, then they must be interpreted as defined in the next section.