A cue is one piece of text with a start and end time, and settings that place it on the screen.
One cue
| Line | Content | Notes |
|---|---|---|
| Identifier | any text without --> | Optional. Unique in the file. CSS can select a cue by it, as ::cue(#id). |
| Timing line | start --> end, then optional settings | Spaces or tabs, at least one, around --> and between settings. |
| Text | one or more lines | See Cue text. Ends at the first blank line. |
The start must be later than or equal to the start of every earlier cue, and the end later than the start. Cues may overlap.
Timestamps
A timestamp is hh:mm:ss.ttt or, when the hours are zero, may be
mm:ss.ttt.
| Part | Digits | Range |
|---|---|---|
Hours and : | 2 or more | 0 and up; optional when 0 |
| Minutes | exactly 2 | 00–59 |
| Seconds | exactly 2 | 00–59 |
. and milliseconds | exactly 3 | 000–999 |
The full stop before the milliseconds is the quickest way to tell WebVTT from SRT, which uses a comma.
Cue settings
Each setting is name:value, at most once per cue, in any order. A
setting with no colon, or a colon at either end, is skipped, as is any value a player
does not recognise.
| Setting | Values | Default | Meaning |
|---|---|---|---|
vertical | rl, lr | horizontal | Vertical text, with lines growing right to left or left to right. |
line | a line number (may be negative), or a percentage; then optionally ,start, ,center or ,end | auto, start | Where the cue sits across the lines of the video: a line number counts lines from the top (or from the bottom when negative); a percentage is a distance across the video. The alignment says which edge of the cue box goes there. |
position | a percentage, 0 to 100; then optionally ,line-left, ,center or ,line-right | auto, auto | Where the cue box sits along the line, as a percentage of the video’s width (or height, for vertical text). |
size | a percentage, 0 to 100 | 100% | The width of the cue box (height for vertical text). |
align | start, center, end, left, right | center | How the text lines are aligned inside the box. start and end follow the text direction. |
region | a region id | none | Shows the cue in a region. |
A percentage is digits, optionally with a decimal part, then %, such as
12.5%. A cue loses its region if it also has vertical, a
line other than auto, or a size other than
100%.
How the position is worked out
| Value | When auto or left out |
|---|---|
| Line | A line number: the cue goes on the last line (−1) if its track is the first track showing, −2 for the second, and so on. Players then stack overlapping cues line by line. A line given as a percentage turns this snapping to lines off, and an auto line is then 100%. |
| Position | 0 for align:left, 100 for align:right, otherwise 50. |
| Position alignment | line-left for align:left; line-right for align:right; for start, line-left in left-to-right text and line-right otherwise; for end the reverse; otherwise center. |
| Alignment | Edge of the cue box placed at the value |
|---|---|
Line start | Top (horizontal text); left for vertical:lr; right for vertical:rl |
Line center | The middle |
Line end | Bottom; right for vertical:lr; left for vertical:rl |
Position line-left | Left (horizontal text) or top (vertical) |
Position center | The middle |
Position line-right | Right (horizontal text) or bottom (vertical) |
Worked example
00:00:04.000 --> 00:00:06.250 line:10%,start position:25%,line-left size:50% align:start
Somewhere we have never been.