Detailed Guide to WebVTT Caption Syntax: A Development and Debugging Guide from Timestamps to Styling

The first line of a standard WebVTT file must be the WEBVTT declaration. The declaration can be followed by a space and file description text, and different structural blocks are separated by blank lines. Most HTML5 players cannot correctly parse files that do not include the WEBVTT header.

NOTE comment blocks are used to add development annotations or caption descriptions, and support single-line or multi-line content. They are not rendered or displayed by players. During development and debugging, NOTE blocks can be used to mark caption paragraphs that need modification, without affecting the final playback result.

Each caption cue consists of a timestamp and display text. The timestamp format supports two styles of millisecond separators: the dot and the comma. Most modern browsers only support the dot notation.

The hour field in timestamps is optional. Captions with a total duration of less than one hour can omit the hour field, resulting in the format MM:SS.sss. The full format is HH:MM:SS.sss. The start time and end time are separated by the --> symbol.

WebVTT supports six standard inline tags for modifying the display style of partial text. Among these, b, i, and u correspond to bold, italic, and underline respectively, following the same rules as the corresponding HTML tags. Developers can use them directly in manual writing.

The ruby tag is used for pinyin annotation, the lang tag is used to mark text in different languages, and the voice tag is used to label the speaker. These tags are mainly used for metadata classification, and players can implement differentiated rendering based on them.

The ::cue pseudo-element is a dedicated CSS pseudo-element provided for WebVTT captions. Developers can use this pseudo-element to modify the default style of all captions on a web page, and it supports common CSS properties such as color, font, and background.

STYLE blocks are used to define global or cue-specific styles inside the WebVTT file. REGION blocks are used to define caption rendering regions, and support displaying different captions in multiple regions simultaneously, which is commonly used for multi-language caption side-by-side display.

The HTML5 track element is used to import external WebVTT caption files. The kind attribute of the track element defines the caption type, which has five possible values: subtitles, captions, descriptions, chapters, metadata.

Among these, subtitles correspond to general translated captions, captions correspond to captions for users with hearing impairment that include environmental sound annotations, chapters correspond to chapter navigation, and metadata stores page metadata and is not displayed. Different players handle the kind attribute with differentiated behavior.