What is WebVTT?
WebVTT is a W3C text format for timed cues associated with web audio or video. A .vtt file can contain subtitles, captions, chapter labels, descriptions, positioning, and limited cue styling.
How WebVTT works
A WebVTT file is UTF-8 text, labeled with the text/vtt media type, that begins with the string WEBVTT, followed by optional region and style blocks and then cue blocks. Each cue has a timing line and a payload that is rendered as caption or subtitle text or interpreted as a chapter title or metadata, depending on how the consuming software uses the track. Cue settings on the timing line control writing direction, line and position, size, alignment, and region. Cue text accepts only a small set of tags, and CSS reaches cues through the ::cue pseudo-element, which honors a fixed list of properties. Timestamps are read against the timeline of the media the file accompanies, so a file timed for one cut needs re-timing when that media is trimmed, sped up, or replaced.
Key facts
- A cue’s timing line is a start timestamp, the string
-->, and an end timestamp, where each timestamp is written asmm:ss.tttorhh:mm:ss.tttwith a period before exactly three millisecond digits. When the parser cannot read that line, it discards the cue and moves on to the next block, so one bad timing line removes one cue without stopping the rest of the file. - An HTML
trackelement gives the file’s address insrc, its role inkind, and its language insrclang;kinddefaults to subtitles when omitted, andsrclangis required for subtitles. A file on a different origin from the page loads only if the parent media element has acrossoriginattribute and the response passes the CORS check. Without that attribute, the browser restricts the request to the page’s own origin and the track fails to load. - WebVTT was based on SubRip’s SRT format, but an SRT file is not a valid WebVTT file. It lacks the
WEBVTTsignature, without which a WebVTT parser aborts, and SRT timing lines conventionally write milliseconds after a comma where WebVTT requires a period. Converting from WebVTT to SRT loses more: the basic SRT cue of a sequence number, timing line, and text has no defined place for cue settings, regions, orSTYLEblocks. - HTTP Live Streaming carries subtitles as WebVTT segments. RFC 8216 says each segment should include an
X-TIMESTAMP-MAPheader that maps cue times to the MPEG-2 timestamps of the other renditions. When the header is absent, clients must assume cue time 0 maps to MPEG-2 timestamp 0, which is correct only if the audio and video timestamps also start there.
When WebVTT matters
An HTML video player can load WebVTT tracks for captions, chapters, or timed metadata. A cue whose timing line cannot be parsed is dropped, and CSS properties outside the permitted set are ignored, so a file can load while some cues are missing or unstyled.
How Transloadit helps with WebVTT
Transloadit’s /speech/transcribe Robot returns a transcript as a WebVTT subtitle file when its format parameter is webvtt. The /video/subtitle Robot accepts SRT and VTT subtitle files and either adds them to a video as a separate stream or burns them into the picture.
Enabling speaker_labels adds speaker labels to json and meta output only; the Robot documentation states that WebVTT output is unchanged.
- Speech transcription Robot: output formats including
webvtt - Video subtitle Robot: add SRT or VTT subtitles to a video
Explore Transloadit’s file formats & compression capabilities