VTT Subtitle Editor
Practical WebVTT reference

WebVTT format guide

Understand the parts a subtitle editor must preserve: the WEBVTT signature, cue IDs, exact timestamps, layout settings, payload markup, comments, styles, and regions.

Reviewed against the current W3C WebVTT specification · July 30, 2026

What is a VTT file?

Web Video Text Tracks, usually called WebVTT or VTT, is a timed-text format designed for captions, subtitles, descriptions, chapters, and other text synchronized with audio or video on the web. A .vtt file is UTF-8 text, so you can inspect it in a text editor—but its block order and timing syntax matter.

The browser-facing reference is the W3C WebVTT specification. MDN also provides an approachable WebVTT format overview.

Basic WebVTT file structure

A file begins with the case-sensitive WEBVTT signature. A blank line separates the header from body blocks. Each cue normally contains an optional identifier, one timing line, and one or more payload lines.

WEBVTT

intro-1
00:00:01.000 --> 00:00:04.200 position:20% align:start
<v Alice>Welcome to the tutorial.
This deliberate line break is part of the cue.

00:00:05.000 --> 00:00:07.500
The next cue has no identifier.

Blank lines delimit blocks. Removing a blank line can accidentally merge a cue with the next cue, comment, or style block. A robust editor should keep body blocks in order rather than reducing the file to a spreadsheet of text and times.

WebVTT timestamps

A timing line uses an ASCII arrow surrounded by whitespace: start --> end. Timestamps use a period before three millisecond digits. The common hour form is hh:mm:ss.mmm; shorter media may use mm:ss.mmm.

00:01.250 --> 00:04.000
01:02:03.400 --> 01:02:07.900

Minutes and seconds must be two digits and stay between 00 and 59. The end must be later than the start. Cues may overlap under WebVTT, but overlap is often an editorial warning because it can reduce readability or produce competing on-screen text.

Cue settings and positioning

Settings follow the end timestamp on the same line. They control how a cue is laid out. Multiple settings are separated by spaces, and each setting should appear no more than once.

00:00:12.000 --> 00:00:15.000 line:85% position:20% size:60% align:start
Lower-left caption

00:00:16.000 --> 00:00:19.000 vertical:rl line:10%
Vertical cue
  • line chooses a line position or line number.
  • position chooses the cue's horizontal position.
  • size limits cue-box width as a percentage.
  • align controls text alignment, such as start, center, or end.
  • vertical selects right-to-left (rl) or left-to-right (lr) vertical writing.
  • region associates a cue with a declared WebVTT region.

Delivery platforms do not all support every setting equally. Preserve settings even when your preview cannot reproduce a destination player's exact layout.

Cue text, line breaks, and markup

Cue payload is not arbitrary HTML. WebVTT defines its own restricted cue-text syntax, including bold, italic, underline, classes, voices, languages, ruby annotations, and inline timestamps.

<v Alice><b>Important:</b> keep the voice label.
Use <c.highlight>classes</c> without executing HTML.

<lang fr>Bonjour</lang> <ruby>東京<rt>とうきょう</rt></ruby>

Line breaks can be intentional caption layout. A safe editor can show a plain-text preview while retaining the original markup and lines for export. It should never inject cue payload as executable page HTML.

NOTE, STYLE, and REGION blocks

NOTE comments

A NOTE block stores comments for people or production systems. It is not displayed as a cue. Comments can contain multiple lines and end at the next blank line.

NOTE QC pass: spelling approved
Keep speaker labels for the final export.

STYLE blocks

A STYLE block contains WebVTT cue CSS. It must appear before the first cue. Moving it below a cue makes the document non-conforming even if some players still accept it.

STYLE
::cue(v[voice="Alice"]) {
  color: yellow;
}

REGION blocks

A REGION block declares a reusable layout area. Like STYLE, it belongs before the first cue. A cue can then refer to its region by ID.

REGION
id:credits
width:40%
lines:3
regionanchor:0%,100%
viewportanchor:5%,95%
scroll:up

Format errors versus quality warnings

Not every undesirable subtitle is an invalid VTT. Separating conformance errors from editable house rules keeps validation honest.

Blocking format problems

  • missing or malformed WEBVTT signature;
  • missing blank separator after the header;
  • timestamp syntax the parser cannot interpret;
  • end time equal to or earlier than start time;
  • malformed or impossible cue-setting values;
  • STYLE or REGION after the first cue; and
  • NUL characters or unrecognized body blocks.

Editorial quality warnings

  • overlapping or out-of-document-order cues;
  • high characters per second (CPS);
  • very short or long display duration;
  • long lines, too many lines, or no visible text; and
  • unknown or repeated cue settings that are still preserved.

Thresholds such as 20 CPS, 42 characters per line, two lines, or 1–7 seconds are useful defaults, not universal WebVTT rules. A broadcaster, streaming service, school, or localization team may require different values.

Common VTT repair workflows

Shift subtitles that are uniformly early or late

If every subtitle is out of sync by the same amount, apply one millisecond offset to all valid cues. For negative shifts, confirm that no start time would fall below zero or clamp the entire document while preserving relative timing.

Correct repeated terminology

Find and replace is safer when limited to cue payload. Changing the raw document blindly can alter identifiers, style selectors, region IDs, or metadata.

Fix a rejected upload

Start with blocking errors: verify the signature, blank separator, arrow, timestamps, end-after-start rule, cue settings, and advanced block placement. Then compare platform-specific requirements, encoding, and file extension.

Preview against local video

Load the exact media version used to create the captions, seek around scene cuts, and inspect entry and exit timing. A waveform can help locate speech, but the picture and spoken content remain the final reference.

VTT versus SRT

Both formats represent timed text, but they are not interchangeable containers. SRT generally uses numbered cues and comma-separated milliseconds. It cannot faithfully represent WebVTT cue settings, regions, style blocks, comments, header metadata, or every cue-text construct.

1
00:00:01,000 --> 00:00:04,200
Welcome to the tutorial.

Converting VTT to SRT should therefore be presented as a lossy export. Keep the VTT source when those features matter.

A preservation checklist

Before trusting an editor for an existing production file, make a small text-only edit and compare the exported document. Check that it retains:

  • the signature text and header metadata;
  • cue identifiers and exact settings;
  • payload markup and deliberate line breaks;
  • NOTE, STYLE, and REGION blocks in order; and
  • unknown blocks for inspection rather than silently deleting them.

Open the browser-local VTT editor