WebVTT format — complete reference
Overview
WebVTT (Web Video Text Tracks) is the subtitle and caption format defined by the W3C for use with HTML5 video. It is the format used by the <track> element and is the modern standard for captions on the web.
- Extension:
.vtt - Encoding: UTF-8
- Header: required —
WEBVTT
Structure
WEBVTT 1 00:00:01.000 --> 00:00:04.000 Hello and welcome. 2 00:00:05.500 --> 00:00:08.750 This is a WebVTT file.
Header
The file must start with WEBVTT optionally followed by metadata on the same line. A blank line separates the header from the first cue.
Timing format
Timestamps use HH:MM:SS.mmm — note the period before milliseconds, not a comma. The hour field is optional if the video is under one hour: MM:SS.mmm is also valid.
Cue identifiers
Cue identifiers are optional strings on the line before the timestamp. They are useful for targeting cues from CSS or JavaScript:
WEBVTT intro 00:00:01.000 --> 00:00:04.000 Hello and welcome.
Cue settings
WebVTT cues can carry positioning and alignment settings after the end timestamp:
00:00:01.000 --> 00:00:04.000 line:0 position:20% size:60% align:start
Common settings:
line— vertical position.position— horizontal position.size— width of the cue box.align— text alignment (start, center, end, left, right).region— attaches the cue to a named region.
Styling
WebVTT supports CSS-based styling through ::cue pseudo-selectors and STYLE blocks:
WEBVTT
STYLE
::cue {
color: yellow;
font-family: sans-serif;
}
Supported inline tags
<b>,<i>,<u>— formatting.<c.classname>— span with a class.<v Speaker>— voice/speaker information.<ruby>and<rt>— ruby annotation (for CJK).<lang>— language marker.
Common problems
- Missing WEBVTT header. The file will not load in HTML5 players.
- Comma instead of period in millisecond. SRT uses commas; VTT uses periods.
- SRT-style positioning tags like
{\an8}. These are ASS syntax, not VTT. They will display literally in VTT players. - Unclosed voice tags.
<v Speaker>without a matching close can break rendering.