VTT File Documentation

Summary

The .vtt extension has two very different meanings. To Crestron’s AV design software it is a VisionTools Pro-e Project, the binary project file that stores a touch-panel interface layout. In practice, though, the overwhelming majority of .vtt files are WebVTT (Web Video Text Tracks): plain-text subtitle and caption files for HTML5 video, MIME type text/vtt, whose first line is literally WEBVTT. Check the first bytes to tell them apart.

Technical details

FeatureValue
SITE format nameVisionTools Pro-e Project
SITE developerCrestron Electronics
SITE format typeAV touch-panel interface project (binary), VisionTools Pro-e (VT Pro-e)
Opened with (SITE)Crestron VisionTools Pro-e
File extension.vtt
Dominant real meaningWebVTT — Web Video Text Tracks (subtitles/captions)
WebVTT MIME typetext/vtt
WebVTT developerW3C / WHATWG
WebVTT format typePlain UTF-8 text, timed cues for HTML5 <track>
WebVTT open standardYes (W3C WebVTT specification)
Introduced (WebVTT)~2010, derived from SubRip (SRT)
WebVTT signatureFirst line is the literal text WEBVTT (optional UTF-8 BOM before it)
Timecode syntax00:00:01.000 --> 00:00:04.000 (period before milliseconds)
vs SRTSRT uses a comma in timecodes and no WEBVTT header
WebVTT featuresCue positioning, CSS ::cue styling, voice/class spans, regions, NOTE blocks
Related extensions.srt, .ass, .ssa, .sub, .sbv
WebVTT specificationw3.org/TR/webvtt1/
Signature at a glance
57 45 42 56 54 54 = “WEBVTT”

A WebVTT file is plain UTF-8 text with no binary magic number, but the standard requires the very first line to be the literal string WEBVTT (optionally followed by a space or tab and a header note). An optional UTF-8 byte-order mark EF BB BF may precede it. That WEBVTT line is the de facto signature: if you open a .vtt in a text editor and see it, the file is subtitles. A Crestron VisionTools Pro-e Project with the same extension is instead a binary project file and will not begin with readable WEBVTT text, which is the quickest way to tell the two apart.

What is a VTT file?

The .vtt extension carries two unrelated formats, and it is worth naming both plainly. In the SITE database, .vtt is a VisionTools Pro-e Project: the project file that Crestron’s VisionTools Pro-e (VT Pro-e) software saves when you design the interface for an AV touch panel. That is a real but specialised binary format opened only by Crestron’s tooling.

For almost everyone who encounters a .vtt today, however, the file is WebVTT (Web Video Text Tracks): a plain-text subtitle or caption file for HTML5 video. WebVTT is a W3C standard, was derived from SubRip (SRT) around 2010, and is the format the HTML5 <track> element loads to display captions in a browser. Its MIME type is text/vtt. Because the two formats share three letters but nothing else, the rest of this article covers WebVTT in depth (the file you almost certainly have) and returns to the VisionTools project at the end.

The WEBVTT header line

A WebVTT file is human-readable UTF-8 text, so you can open it in any editor. The specification requires that it begin with a specific signature: the very first line must be the string WEBVTT. Nothing may come before it except an optional UTF-8 byte-order mark (EF BB BF). The header line may be exactly WEBVTT, or WEBVTT followed by a space or tab and then free text used as a title or note.

WEBVTT - English captions for demo.mp4

00:00:01.000 --> 00:00:04.000
Welcome to the demonstration.

00:00:04.500 --> 00:00:07.200
This line appears a little later.

After the header comes a blank line, then a sequence of cues. If the first bytes are not WEBVTT, a conforming parser rejects the file, which is why a stray byte before the header, or saving the file in the wrong encoding, makes captions silently fail to load. This same rule is the reliable way to distinguish a WebVTT subtitle file from a VisionTools Pro-e project: the subtitle file starts with legible WEBVTT text, the Crestron project does not.

The cue: identifier, timings and payload

A cue is the unit that puts one caption on screen for one interval. It has up to three parts: an optional identifier line, a mandatory timing line, and one or more lines of payload text.

intro-1                              <- optional cue identifier
00:01:12.500 --> 00:01:15.000 line:80% align:center
Here is the <i>caption</i> text,
which may span two lines.

The identifier is any label on its own line before the timings; it lets scripts and CSS target a specific cue and must not itself contain -->. The timing line is the heart of the cue: a start time, the literal arrow --> surrounded by spaces, and an end time. Times are written hours:minutes:seconds.milliseconds (hours optional), and the crucial detail is the period before the milliseconds, 00:01:12.500. This is the single most common difference from SRT, which uses a comma (00:01:12,500). Trailing the timings are optional cue settings such as line: (vertical position), position: (horizontal), align:, size: and vertical:, which place and orient the caption on the video.

Payload markup: voices, classes and timestamps

The cue text is not entirely plain: WebVTT defines a small set of inline tags that SRT lacks. A voice span, <v Speaker>...</v>, labels who is talking and can be styled per speaker. A class span, <c.loud>...</c>, attaches a CSS class. Basic <i>, <b> and <u> tags give italic, bold and underline. A timestamp tag inside a cue, like <00:01:13.000>, marks the moment individual words should highlight, which is how karaoke-style word-by-word captioning works. Because the text is HTML-like, the characters &, < and > in real dialogue must be escaped as &amp;, &lt; and &gt;.

NOTE, STYLE and REGION blocks

Between cues, WebVTT allows three special blocks that SRT has no equivalent for. A NOTE block is a comment ignored on playback; it runs until the next blank line and cannot contain -->. A STYLE block embeds CSS that targets the pseudo-element ::cue, so captions can be coloured, given a background or a specific font directly from the file:

STYLE
::cue {
  color: #fff;
  background: rgba(0,0,0,0.6);
}
::cue(v[voice="Narrator"]) { color: #9cf; }

REGION
id:speaker width:40% lines:3 regionanchor:0%,100% viewportanchor:10%,90%

A REGION block defines a rectangular area of the video with its own size and anchor, so groups of cues can scroll within a fixed box rather than always sitting along the bottom edge. These styling and positioning features are the technical reason WebVTT is preferred over SRT for accessible, styled web captions: the presentation travels with the timing in one file the browser renders natively.

Loading WebVTT into an HTML5 video

You rarely “open” a .vtt by itself. On the web it is attached to a <video> through a <track> child, and the browser parses and renders it:

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

The kind attribute distinguishes captions, subtitles, descriptions, chapters and metadata tracks, all of which use the same WebVTT syntax. Desktop players such as VLC and MPV auto-load a .vtt that shares the video’s name and folder, and editors like Subtitle Edit open it directly for retiming. Because the file is text, fixing a typo or nudging a timecode is a matter of editing lines and saving as UTF-8, which is essential so accented and non-Latin characters display correctly.

Converting WebVTT to SRT

The most common WebVTT task after simply displaying it is converting to and from SRT, because the two are nearly the same format. The mechanical differences are small and precise: strip the WEBVTT header and any NOTE/STYLE/REGION blocks and cue settings, number the cues sequentially (SRT requires an integer before each cue), and swap the period in each timecode for a comma. That is nearly all a converter does, which is why the round trip is essentially lossless for plain dialogue and can even run client-side in a browser. Tools like Subtitle Edit and ffmpeg handle it, as do many web converters.

The VisionTools Pro-e Project (the SITE meaning)

The other .vtt, and the name in this SITE’s database, is a VisionTools Pro-e Project from Crestron Electronics. VisionTools Pro-e is Windows software used to design the graphical interface shown on Crestron AV control touch panels: button layouts, pages, joins and feedback for a room-control system. The .vtt holds that project as a binary file, and it opens only in VisionTools Pro-e (later Crestron tooling superseded it). It is not text, does not begin with WEBVTT, and has nothing to do with subtitles. If your .vtt is one of these, opening it in a text editor shows binary data rather than readable cues, and you need Crestron’s software to work with it.

FAQ

What is the difference between VTT and SRT?

Both are timed-text subtitle formats and are almost identical. WebVTT (.vtt) is the HTML5 web-captions standard: it starts with a WEBVTT header and uses a period in timecodes (00:00:01.000). SRT has no header, numbers its cues, and uses a comma (00:00:01,000). WebVTT additionally supports styling, positioning and regions.

How do I know which kind of VTT I have?

Open it in a text editor. If the first line reads WEBVTT and you see timecoded caption text, it is a WebVTT subtitle file. If it shows binary data, it is likely a Crestron VisionTools Pro-e Project that needs VisionTools Pro-e to open.

Why are there strange characters in my WebVTT file?

That is an encoding mismatch. WebVTT must be UTF-8; re-save the file as UTF-8 in Subtitle Edit or a text editor so accents and non-Latin scripts render correctly.

References