WebVTT

Web Video Text Tracks (WebVTT) is a UTF-8 plain-text format for text synchronized with audio or video. A .vtt file has the MIME type text/vtt.¹ Browsers use WebVTT with the HTML <track> element. Other software can parse the same cues into transcripts or other forms of time-aligned data.

File structure

Every file starts with WEBVTT. After the header, it may contain STYLE, REGION, and NOTE blocks followed by cues. Blank lines separate blocks. Each cue has an optional identifier, a timing line, and a payload.¹

WEBVTT

intro
00:00:01.000 --> 00:00:04.500 align:start position:10%
<v Alice>Hello, <i>world</i>.

00:00:05.000 --> 00:00:07.000
This cue can span
more than one line.

The timing line contains a start time, -->, and an end time. WebVTT timestamps use either mm:ss.mmm or hh:mm:ss.mmm. Settings after the end time control presentation:

• align aligns text inside the cue box.
• line places the cue along the line axis.
• position places it along the position axis.
• size sets the cue box’s width, or its height for vertical text.
• vertical changes the writing direction.
• region assigns a cue to a named region.

Cue text can contain a limited markup language. Common tags include <b>, <i>, <u>, <c> for classes, <v> for a voice or speaker, and <lang> for a language span. Inline timestamps support karaoke-style word timing. These look like HTML, but a general HTML parser is not a WebVTT parser.²

Adding a track to HTML

Use kind to tell the browser how to interpret the file:

<video controls src="interview.mp4">
  <track
    default
    kind="captions"
    src="interview.en.vtt"
    srclang="en"
    label="English" />
</video>

The available kinds have different purposes:³

• subtitles translate or transcribe dialogue for a listener who can hear the audio but does not understand it.
• captions include dialogue and relevant non-speech audio for a viewer who cannot hear the audio.
• descriptions describe visual content.
• chapters provide navigation labels.
• metadata carries time-aligned data for scripts and is not displayed.

A page can provide multiple tracks for different languages and uses. If kind="subtitles", srclang is required. Only one track on a media element can have the default attribute.³

CSS can style displayed captions with ::cue:

video::cue {
  color: white;
  background: rgb(0 0 0 / 80%);
}

video::cue(v[voice="Alice"]) {
  color: lemonchiffon;
}

The browser exposes loaded tracks through HTMLMediaElement.textTracks. TextTrack supplies the cue list and active cues, while cuechange reports when the active set changes.³

Cues

A cue describes what should be active during a time range but does not promise one sentence, one speaker turn, or one unique piece of text. Caption generators often wrap a sentence across cue lines. Live and karaoke-style captions may repeat earlier words while adding new ones:

00:00:00.000 --> 00:00:02.000
The product is

00:00:02.000 --> 00:00:04.000
The product is fast

00:00:04.000 --> 00:00:06.000
fast and reliable.

Concatenating these payloads produces duplicate text. Treat conversion as a normalization step:

1. Parse cues and timestamps before changing the text.
2. Extract speaker information from <v> tags.
3. Remove caption markup and decode character references.
4. Replace presentation line breaks with spaces when they do not carry meaning.
5. Remove repeated prefixes or overlaps from rolling captions.
6. Merge adjacent additions while keeping speaker changes as segment boundaries.

Do not apply these rules when line breaks, styling, or regions are part of the information you need. A chapter track, lyric track, or time-aligned metadata track needs a renderer suited to that use rather than transcript cleanup.

Parsing and conversion

The WebVTT specification defines both valid syntax and error-tolerant parsing rules. A browser may display a malformed file even when a conformance checker rejects it, so successful playback does not prove that the file is valid.² Use a WebVTT parser when cue identifiers, regions, inline timestamps, or cue settings matter. Splitting on blank lines is not enough to handle every block and parser recovery rule.

When converting captions into a transcript, keep the original VTT as the source. The conversion may discard layout, styling, line breaks, and word-level timing. Those choices cannot be reversed from plain text or normalized segments.