Caption files

WebVTT styling: CSS, with a short list.

Style WebVTT captions with CSS's ::cue selector, either in a STYLE block inside the .vtt file or in the stylesheet of the page playing the video. Only a few properties apply — colour, background, font, text-shadow and some others — and position is not one of them: that lives in cue settings after the timestamp.

Get the Mac app — $9.99 → Try it free in your browser
The short answer

Styling a caption file is not styling a web page.

The syntax is CSS. The rules are narrower, and the viewer gets the last word.

A WebVTT file can carry its own look. The format borrowed CSS for it: a STYLE block near the top of the file holds ordinary-looking rules, and the selector they use is ::cue, which means "the caption text". A minimal styled file looks like this:

WEBVTT

STYLE
::cue {
  color: #ffd93d;
  background-color: rgba(0, 0, 0, 0.8);
}

00:00:01.000 --> 00:00:02.400
Yellow text on a dark box.

Three things make it different from styling a page. First, only a short list of properties works on ::cue: the colour, opacity and visibility properties, text-decoration, text-shadow, the background properties, the outline properties, the font properties including line-height, white-space, and two specialised ones for vertical and ruby text. There is no padding, no border, no rounded corners, no margin and no positioning. Second, where the caption sits is not CSS at all; it is set per cue, in settings written after the timestamp. Third, the viewer can override you: caption preferences in the operating system or the player can replace some or all of what the file asks for, and for accessibility that is the correct order of priority.

1 · The recipes

How to get each look in WebVTT.

What people usually want from a caption, and the closest thing the format allows.

You want In WebVTT The catch
Text colourcolorNone
Font and weightfont-family, font-weight, font-styleThe viewer needs the font, or the player substitutes one
Sizefont-size as a percentageRelative to the player's own default caption size, not the video
A box behind the textbackground-color, with rgba() for transparencyNo padding and no rounded corners
An outlineA ring of text-shadow offsetsNo stroke property is allowed
A soft shadowtext-shadow with a blurNone
One word in another colourA <c.name> span and a ::cue(.name) ruleNone
Top, middle or bottomThe line: cue settingNot CSS; see subtitle position
The spoken word highlightedTimestamp tags with :past / :futureUneven support across players

Two of those deserve a word more. A percentage font-size on ::cue scales the player's default caption size, whatever that happens to be, so the only way to state a size is as a ratio to it. And because there is no -webkit-text-stroke or any other stroke on the allowed list, an outline has to be faked: several hard-edged shadows, each offset a little in a different direction, so that together they ring every letter. Four offsets leave the diagonals of round letters visibly thinner than their sides; eight look like a real outline.

2 · A real file

One caption, styled, line by line.

Exactly what suubbs writes for its Pop look — Inter Tight, black weight, upper case, a dark outline — with one word recoloured.

WEBVTT

STYLE
::cue {
  color: #ffffff;
  font-family: "Inter Tight";
  font-size: 132%;
  font-weight: 700;
  font-style: normal;
  letter-spacing: 0.01em;
  line-height: 1.24;
  background-color: transparent;
  text-shadow: 0.138em 0em 0 #17161a, 0.098em 0.098em 0 #17161a, …;
}

STYLE
::cue(.s1) {
  color: #ffd93d;
}

00:00:01.000 --> 00:00:02.400
MADE ON MY <c.s1>MAC</c>

Three small losses are worth knowing about. WebVTT gets a bold weight as 700, so suubbs' black weight arrives as ordinary bold. The letter-spacing line is written, but it is not on the ::cue allowed list, so browsers ignore it. And the rounded corners the preview can give a box have no equivalent, since border-radius is not allowed.

Style it in a preview. Export the CSS.

[::cue]

3 · Where the CSS lives

In the file, or in your page.

The same rule works in two places, and they fail in different ways.

A STYLE block inside the .vtt

The block goes after the WEBVTT header line and before the first cue, separated from both by blank lines, and it may not contain the string -->. A block placed after a cue is not treated as a style block. The advantage is that the look travels with the file to any player that reads it. The weakness is that not every player does: support has varied between browsers, and many players and upload forms take a .vtt for its words and timings only. If the styling matters, test the exact player your audience uses.

A ::cue rule in the page's stylesheet

If you control the web page the video plays in, you can put the same rules in its ordinary CSS:

video::cue {
  color: #ffffff;
  background-color: rgba(12, 11, 16, 0.92);
}
video::cue(.s1) {
  color: #ffd93d;
}

This styles every caption track on those video elements, which is useful when you publish many videos with one look and do not want it repeated in every file. The same allowed-property list applies.

Why styling sometimes does not show

4 · Making one

A styled .vtt from a video, without writing the CSS.

If you are starting from the video rather than an existing file, the CSS can come out of a live preview instead of a text editor.

  1. Transcribe. Drop the video into suubbs and press Generate. The words are transcribed on your own machine; nothing is uploaded.
  2. Style against the picture. Pick a look or set the font, size, colour and treatment — none, shadow, box or outline — in the style panel. To recolour one word, select it and change its colour; a line can be given its own look the same way.
  3. Export WebVTT. The file gets one ::cue rule for the document and one class for each distinct override, as in the example above. If the anchor or edge offset was changed, the cue settings carry it.

Before the file is written, suubbs names what WebVTT cannot hold from what you set, rather than dropping it quietly: a word-by-word highlight, fades, and a caption dragged to a free position. A document nobody styled is exported as a bare WebVTT file with no STYLE block at all, so the player's own look applies. For captions that must look exactly as designed — on TikTok or Reels, say, where a caption file is not uploaded — burn them into the picture from an ASS export instead; burning subtitles into a video covers it.

Already have an SRT and only need the format changed? Converting SRT to VTT is a one-line job and does not need suubbs. How size behaves across SRT, WebVTT and ASS is on subtitle font size.

Details

What people ask next.

Can you style VTT subtitles with CSS?

Yes. WebVTT captions are styled with the ::cue pseudo-element, either in a STYLE block inside the .vtt file or in the stylesheet of the page that plays the video. Only a limited set of properties applies: colour, background, font, text-shadow, outline, opacity and a few others. Position is set with cue settings, not CSS.

Where does the STYLE block go in a VTT file?

After the WEBVTT header and before the first cue, separated by blank lines. It may not contain the string -->. A block placed after a cue is not treated as a style block.

Why is my VTT styling not showing?

Usually one of three things: the player does not read STYLE blocks from inside the file, the viewer's own caption settings are overriding yours, or the property is not one ::cue allows. Test in the player your audience actually uses, and try the same rule in the page's stylesheet.

How do I add a background box to VTT captions?

Set background-color on ::cue, with an rgba() value if you want it partly transparent. Padding and rounded corners are not allowed properties, so the box hugs the text and has square corners.

How do I add an outline to VTT captions?

There is no stroke property on the ::cue allowed list, so draw the outline with text-shadow: several shadows offset in a ring around each letter. suubbs writes eight, in em units, so the outline keeps its weight at any caption size.

Can WebVTT do word-by-word highlighting?

The format has inline timestamp tags and :past and :future pseudo-classes meant for that, but support across players is uneven. suubbs does not write them; for highlighted captions it exports ASS for a burn-in, and warns that WebVTT cannot carry the highlight.

Keep reading

Related