docs/reference/webvtt.md
WebVTT (file extension .vtt) is a modern subtitle format designed for HTML5 video, offering powerful styling and positioning capabilities.
WebVTT (Web Video Text Tracks) was developed by the W3C (World Wide Web Consortium) as the official subtitle format for HTML5 video. It's based on SubRip (SRT) but with significant enhancements for web-based video playback.
Key Features:
Pros:
Cons:
A WebVTT file starts with a mandatory signature line, followed by optional header and cue blocks.
WEBVTT
00:00:01.000 --> 00:00:03.000
Subtitle text here
00:00:03.500 --> 00:00:05.500
Another subtitle
WEBVTT [optional description]
NOTE
Optional comment block
STYLE
::cue {
background-color: rgba(0,0,0,0.8);
}
REGION
id:region1
width:40%
lines:3
regionanchor:0%,100%
viewportanchor:10%,90%
[cue identifier]
00:00:01.000 --> 00:00:03.000 [cue settings]
Subtitle text
hours:minutes:seconds.milliseconds --> hours:minutes:seconds.milliseconds
Important notes:
00:30.000 is valid.) is used as decimal separator (not comma like SRT)--> (space-arrow-space)Examples:
00:00:01.000 --> 00:00:03.500
01:15.250 --> 01:18.750
1:30:45.100 --> 1:30:50.900
-00:00:02.000 --> 00:00:00.000
WEBVTT
00:00:01.000 --> 00:00:03.000
Hello, World!
00:00:03.500 --> 00:00:05.500
This is WebVTT format.
00:00:06.000 --> 00:00:08.000
It supports multiple
lines of text.
Every WebVTT file must start with the string WEBVTT on the first line.
Valid signatures:
WEBVTT
WEBVTT - Optional description here
WEBVTT FILE This file contains subtitles
Invalid:
webvtt (lowercase not allowed)
WEBVTT (space before signature)
WEBVTT subtitle (hyphen required before description)
WebVTT supports HTML-like formatting tags and CSS classes.
<b>Bold text</b>
<i>Italic text</i>
<u>Underlined text</u>
Identify speakers using voice tags:
<v John>Hello, I'm John.
<v.loud John>I'M SHOUTING!
<v Mary>Hi John, nice to meet you.
Apply CSS classes for styling:
<c>Text with default class</c>
<c.yellow>Yellow text</c>
<c.yellow.bg_blue>Yellow text on blue background</c>
Predefined color classes:
white, lime, cyan, red, yellowmagenta, blue, black, greenFor East Asian languages (Japanese, Chinese):
<ruby>漢<rt>かん</rt>字<rt>じ</rt></ruby>
<lang en>Hello</lang>
<lang ja>こんにちは</lang>
<v John><i>thinking...</i></v>
<c.yellow><b>Important!</b></c>
Cue settings control the positioning and layout of subtitles.
00:00:01.000 --> 00:00:03.000 position:50% align:center
Text here
| Setting | Description | Values | Default |
|---|---|---|---|
position | Horizontal position | 0-100% or auto | 50% |
line | Vertical position | number, % or auto | auto |
size | Width of cue box | 0-100% | 100% |
align | Text alignment | start, center, end, left, right | center |
vertical | Vertical text | rl (right-to-left), lr (left-to-right) | horizontal |
region | Region identifier | string | none |
WEBVTT
00:00:01.000 --> 00:00:03.000 position:10% align:start
Left side text
00:00:03.500 --> 00:00:05.500 position:50% align:center
Centered text (default)
00:00:06.000 --> 00:00:08.000 position:90% align:end
Right side text
00:00:08.500 --> 00:00:10.500 line:0% position:50%
Top of screen
00:00:11.000 --> 00:00:13.000 line:85% position:50%
Near bottom
00:00:13.500 --> 00:00:15.500 size:50% position:25%
Narrow subtitle box
WebVTT supports embedded CSS for custom styling.
WEBVTT
STYLE
::cue {
background-color: rgba(0, 0, 0, 0.8);
color: white;
font-size: 1.5em;
font-family: Arial, sans-serif;
}
::cue(b) {
color: yellow;
}
::cue(.yellow) {
color: yellow;
}
::cue(.red) {
color: red;
}
00:00:01.000 --> 00:00:03.000
Normal white text
00:00:03.500 --> 00:00:05.500
<b>Yellow bold text</b>
00:00:06.000 --> 00:00:08.000
<c.red>Red text</c>
color — Text colorbackground-color — Background coloropacity — Transparency (0.0 to 1.0)font-family — Font familyfont-size — Font sizefont-weight — Bold (normal, bold, 100-900)font-style — Italic (normal, italic)text-decoration — Underline (none, underline)text-shadow — Text shadow effectwhite-space — Whitespace handlingExample:
::cue {
color: #ffffff;
background-color: rgba(0, 0, 0, 0.9);
font-family: 'Arial', sans-serif;
font-size: 20px;
text-shadow: 2px 2px 4px #000000;
}
Regions define areas of the video where subtitles can appear.
WEBVTT
REGION
id:bill
width:40%
lines:3
regionanchor:0%,100%
viewportanchor:10%,90%
scroll:up
REGION
id:fred
width:40%
lines:3
regionanchor:100%,100%
viewportanchor:90%,90%
scroll:up
00:00:01.000 --> 00:00:03.000 region:bill
<v Bill>I'm on the left
00:00:01.000 --> 00:00:03.000 region:fred
<v Fred>I'm on the right
| Property | Description | Values |
|---|---|---|
id | Unique identifier | string |
width | Region width | percentage |
lines | Number of lines | integer |
regionanchor | Anchor point in region | x%,y% |
viewportanchor | Anchor point in viewport | x%,y% |
scroll | Scroll behavior | up or none |
Cues can have optional identifiers for scripting and navigation.
WEBVTT
intro
00:00:01.000 --> 00:00:03.000
Welcome to the video
dialog-1
00:00:03.500 --> 00:00:05.500
<v John>Hello there!
dialog-2
00:00:05.500 --> 00:00:07.500
<v Mary>Hi John!
Use NOTE blocks for comments:
WEBVTT
NOTE
This is a comment block.
It can span multiple lines.
NOTE Another comment on one line
00:00:01.000 --> 00:00:03.000
Subtitle text
WEBVTT - Example subtitle file
NOTE
Created with Subtitle Edit
For demonstration purposes
STYLE
::cue {
background-color: rgba(0, 0, 0, 0.8);
color: white;
font-family: Arial, sans-serif;
}
::cue(.yellow) {
color: yellow;
}
::cue(v[voice="John"]) {
color: cyan;
}
REGION
id:left
width:40%
regionanchor:0%,100%
viewportanchor:10%,90%
REGION
id:right
width:40%
regionanchor:100%,100%
viewportanchor:90%,90%
intro
00:00:01.000 --> 00:00:03.000 position:50% align:center
<c.yellow><b>Welcome to WebVTT</b></c>
narrator
00:00:03.500 --> 00:00:06.500
<i>Narrator speaking...</i>
dialog-1
00:00:07.000 --> 00:00:09.000 region:left
<v John>Hello, I'm on the left side.
dialog-2
00:00:09.000 --> 00:00:11.000 region:right
<v Mary>And I'm on the right!
caption-1
00:00:12.000 --> 00:00:15.000 line:10% position:50%
Top-positioned subtitle
caption-2
00:00:16.000 --> 00:00:18.000 size:50% position:25% align:start
<b>Bold text</b> with <i>italic</i> and <u>underline</u>
WebVTT files must be encoded as:
Important: UTF-8 is the only valid encoding for WebVTT files according to the W3C specification.
Example:
WEBVTT
00:00:01.000 --> 00:00:05.000 line:85%
Bottom subtitle (stays for 4 seconds)
00:00:02.000 --> 00:00:04.000 line:15%
Top subtitle (appears while bottom is still showing)
Problem: Missing or incorrect WEBVTT signature
Wrong: webvtt (lowercase)
Wrong: WEBVTT (space before)
Right: WEBVTT
Right: WEBVTT - My subtitles
Problem: Browser doesn't support custom CSS or cue settings Solution: Test in different browsers; fallback to basic tags
Problem: File not saved as UTF-8 Solution: Always save WebVTT files as UTF-8 (required by spec)
Problem: Player or browser limitation Solution: Use regions or test in different player
Problem: Using comma instead of period in timecodes
Wrong: 00:00:01,000 --> 00:00:03,000
Right: 00:00:01.000 --> 00:00:03.000
WebVTT can be used for metadata, not just subtitles:
WEBVTT
00:00:00.000 --> 00:00:10.000
{"title": "Introduction", "slide": 1}
00:00:10.000 --> 00:00:30.000
{"title": "Main Content", "slide": 2}
Define video chapters:
WEBVTT
chapter-1
00:00:00.000 --> 00:05:00.000
Introduction
chapter-2
00:05:00.000 --> 00:15:00.000
Main Content
chapter-3
00:15:00.000 --> 00:20:00.000
Conclusion
Subtitle Edit can convert many formats to WebVTT:
WebVTT is natively supported in:
Note: The level of CSS styling support may vary between browsers.
| Property | Value |
|---|---|
| File Extension | .vtt, .webvtt |
| MIME Type | text/vtt |
| Character Encoding | UTF-8 (required) |
| Line Endings | Any (CRLF, LF, CR) |
| Timecode Format | HH:MM:SS.mmm or MM:SS.mmm |
| Timecode Precision | Milliseconds (3 digits) |
| Specification | W3C WebVTT |
<video controls>
<source src="video.mp4" type="video/mp4">
<track label="English" kind="subtitles" srclang="en" src="subtitles.vtt" default>
<track label="Spanish" kind="subtitles" srclang="es" src="subtitles_es.vtt">
<track label="Chapters" kind="chapters" srclang="en" src="chapters.vtt">
</video>
subtitles — Translations (default)captions — Transcription and sound effectsdescriptions — Text descriptions of visualschapters — Chapter titles for navigationmetadata — Metadata for scriptsNote: WebVTT has a complete official specification, unlike SubRip which is defined by common practice.