What is a VTT file? The WebVTT subtitle format explained

The VTT file format compared with SRT

Both SRT and VTT hold timed subtitle text, but they make different promises. An SRT file is a loose convention. A VTT file is built to a published specification, so a browser knows exactly what each line means. That formality is why VTT appears in HTML5 video, in web accessibility audits and in players that need to position captions rather than merely display them.

On the surface the two files look similar. Both list cues in time order, both store a start time, an end time and text, and both are readable in a text editor. The difference appears in the details: the header line, the millisecond separator, the role of identifiers and the presence of cue settings. A file that ignores those details may play in a forgiving desktop editor and fail in a browser.

• SRT: number, comma timestamp, text.
• VTT: WEBVTT header, optional identifier, dot timestamp, optional settings.
• VTT is the format the HTML5 track element expects.

The WebVTT format: header, cues and settings

Every WebVTT file begins with the signature WEBVTT on the first line. A blank line normally follows, then the first cue. The signature tells a parser that the file is not SRT with an unusual name. Comments, regions and style blocks may appear before the first cue. If the signature is missing or preceded by a byte-order mark, a strict browser can ignore the entire track.

VTT writes milliseconds after a dot, not a comma: 00:00:04.250. The arrow and spacing between the two times match the familiar SRT look. An optional cue identifier can sit on its own line above the timestamp. Unlike SRT's sequence number, this identifier is not displayed and does not need to be numeric. You can use a word such as intro or speaker-a to make the file easier to review.

Cue settings follow the end timestamp on the same line. They control alignment, line position, text position, size and region. A settings list might read align:start position:10%. Browsers apply these hints; many video editors ignore them on import. Inline tags such as <b> and <i> are also defined, along with voice and language spans.

WEBVTT

intro
00:00:00.500 --> 00:00:03.400
This is the first caption.

speaker-a
00:00:03.800 --> 00:00:07.200 align:start position:10%
The second caption sits on the left.

Cue identifiers, NOTE blocks and STYLE rules

WebVTT reserves blocks for comments and styling. A NOTE block begins with NOTE and continues until a blank line. It is invisible in playback and useful for editorial notes, speaker names or conversion warnings. A STYLE block contains CSS rules that apply to cue classes, though browsers limit which properties affect captions. A REGION block defines a positioned area for cues that share placement.

These blocks are the main reason a VTT file can carry information that an SRT file cannot. They also make hand-editing riskier. A missing blank line can absorb the next cue into a comment, and a stray brace in a STYLE block can break the rules that follow. When you only need plain captions, omit these blocks entirely and keep the file as close to SRT structure as the format allows.

Cue identifiers are optional, and that surprises people who are used to SRT numbering. If you delete every identifier from a simple VTT file, it still plays. If you keep identifiers, make them unique within the file. Duplicate identifiers are not a parsing error, but they make debugging harder when a player logs the cue name.

Browser support and the HTML5 track element

Browsers do not read VTT files through a file input by default. A web page loads a caption track with the HTML5 track element: a video element contains a track element whose kind is captions or subtitles, whose src points to the .vtt file and whose srclang names the language. The track element also supports a default attribute for the track that should start enabled.

The server should send the file with the text/vtt MIME type. If it sends text/plain or application/octet-stream, some browsers still load the track, but standards-compliant behavior depends on the correct type. Cross-origin tracks add another constraint: the video page must be allowed to read the caption file, often through CORS headers.

Support is broad in current versions of Chrome, Edge, Firefox and Safari, but the details differ. Styling support is partial, and cue settings are hints rather than guarantees. Test with the browser and device your audience uses, especially if captions are positioned over a busy part of the frame.

Encoding and valid versus invalid examples

Encoding works the same way as other plain-text subtitles: UTF-8 is the safe default. The WEBVTT signature must be the first text a parser sees. A UTF-8 byte-order mark can appear before it, and some parsers tolerate that while others do not. If a browser refuses a file that looks correct, save without a BOM and reload.

Line endings are usually forgiving. Windows CRLF and Unix LF both work in modern browsers, although consistency makes diffs and version control cleaner. Avoid tabs inside cue text; use spaces if alignment matters to you. Keep one blank line between blocks so that a NOTE or a cue does not swallow the next block.

A valid cue has a timestamp line and at least one line of text. An invalid file might use a comma, omit the WEBVTT header, place text before the timestamp, or include an empty cue. The examples below show the difference. The second block is intentionally broken and should not be copied.

WEBVTT

00:00:01.000 --> 00:00:04.000
The door is open.

00:00:06,000 --> 00:00:09,000
The comma breaks strict parsing.

Where VTT is the better choice

Choose VTT when the video will play in a browser and the player supports the track element. It is the standard path for custom HTML5 players, for some learning platforms and for sites that need captions to respond to layout. VTT is also a reasonable choice when you need comments or cue-level styling that should travel with the file.

Choose SRT when the file will move between desktop editors, captioning agencies or upload forms that list SRT first. SRT is simpler and harder to break. If both are needed, keep an SRT master and generate VTT for web playback, so a browser-only feature never becomes a dependency in the editing pipeline.

Do not assume that converting to VTT magically adds browser support. A player still needs a caption track, a matching language and a reachable URL. Conversion fixes syntax, not delivery.

How to create a VTT with VoiceToTextFree

VoiceToTextFree can produce the text and timing, then you can download a subtitle file for the player you use. Open the subtitle generator and transcribe the clip in the browser. Review the cues in the SRT editor, fix names and line breaks, and export. If the destination is a web page, convert a copy to VTT and check the header and dot separators.

After conversion, load the file in the target browser with the developer console open. A missing track, a MIME type mismatch or a CORS error is easier to diagnose there than by guessing from a blank caption area. Keep the original transcript so you can regenerate a clean file if the conversion step changes.

Common mistakes when writing WebVTT

The most common mistake is a comma timestamp copied from SRT. The second is a missing WEBVTT header. The third is a blank line in the wrong place, which turns the following cue into part of a comment or a continuation. All three produce files that look plausible in a text editor and fail in a browser.

• Use a dot, not a comma, before milliseconds.
• Keep WEBVTT as the first visible line.
• Put exactly one blank line between blocks.
• Do not add SRT-style sequence numbers unless you understand that they become cue identifiers.
• Serve the file as text/vtt.

Checking a file in a second browser

If a track works in one browser and fails in another, the difference is often MIME type, CORS or a byte-order mark rather than the cue text. Open the network panel and confirm that the .vtt request returned the file with the expected type. Then compare the first line of the response with a known-good file.

A second browser is a cheap test, but it is not a substitute for a validator. Syntax problems and delivery problems look identical when the caption area is simply empty, so check both layers before you change the text.