Subtitle formats

SRT to VTT, in two changes.

To convert an SRT file to VTT, add a first line reading WEBVTT followed by a blank line, and change the comma before the milliseconds in every timestamp to a full stop: 00:01:04,250 becomes 00:01:04.250. That is the whole conversion for an ordinary file. The numbered lines can stay. What goes wrong in practice is the encoding, the formatting tags, and how the file is served, which this guide covers.

Get the Mac app — $9.99 → Try it free in your browser
1 · The difference

Two formats, nearly the same file.

WebVTT was designed for the web, starting from SubRip's layout, so a simple SRT is one header and a punctuation change away from valid VTT.

The same cue, in each format:

1
00:01:04,250 --> 00:01:06,900
Is this thing on?
WEBVTT

1
00:01:04.250 --> 00:01:06.900
Is this thing on?

In the VTT, the 1 is a cue identifier: optional, and harmless to keep. VTT also lets the hours be left off (01:04.250), which SRT does not. Everything else VTT adds is optional and has no SRT equivalent:

SRT has no styling of its own. Players honour a handful of HTML-like tags by convention (<b>, <i>, <u> and <font color>) and that is all. Going from SRT to VTT therefore loses nothing. Going back can lose a lot, which is covered further down.

2 · Convert it

Three ways, from one command to none.

All three keep the timings exactly; none of them needs the video.

With ffmpeg

If you have ffmpeg (on a Mac, brew install ffmpeg), it reads one and writes the other, and it handles the header, the timestamps and the tags for you:

ffmpeg -i captions.srt captions.vtt

The same command the other way round converts VTT to SRT.

With one line of shell, and nothing to install

macOS already has everything needed. This writes the header, then copies the file with the comma in every timestamp swapped for a full stop:

{ printf 'WEBVTT\n\n'; sed -E 's/([0-9]{2}:[0-9]{2}:[0-9]{2}),([0-9]{3})/\1.\2/g' captions.srt; } > captions.vtt

The pattern only matches a full 00:00:00,000 timestamp, so a comma in the dialogue is left alone.

By hand

Any plain text editor works: TextEdit in plain-text mode, or a code editor. Type WEBVTT and a blank line at the top, then use find and replace on the timestamps. Most code editors accept the same pattern as above, with $1.$2 as the replacement. Save it with a .vtt extension and UTF-8 encoding.

3 · What breaks

The file converted and still will not play.

Almost always one of four things, none of them the timestamps.

The encoding. WebVTT must be UTF-8. Older SRT files, especially ones made on Windows or downloaded from subtitle sites, are often in a legacy encoding such as Windows-1252, and accented letters turn into garbage or the file is rejected. On a Mac, file -I captions.srt reports the encoding, and iconv converts it before you do anything else:

iconv -f WINDOWS-1252 -t UTF-8 captions.srt > captions-utf8.srt

The header. WEBVTT has to be the very first thing in the file, followed by a blank line. A missing blank line, or text pasted above it, and a browser rejects the whole file. Windows line endings are fine; VTT accepts them.

Tags that only SRT players understand. <font color="…"> is not part of WebVTT, so browsers ignore it. To keep a colour, give the text a class (<c.yellow>…</c>) and colour it in a STYLE block. Some SRT files also carry SubStation codes like {\an8} to move a line to the top; those mean nothing in VTT and may show up as text, so replace them with a cue setting such as line:10%.

How it is served. If the file is fine and the browser still shows nothing, the problem is usually the page. See the next section.

4 · On a web page

Why you needed a VTT in the first place.

The HTML <track> element is the one place SRT will not do: browsers read only WebVTT there.

<video controls src="talk.mp4">
  <track kind="subtitles" src="talk.en.vtt" srclang="en" label="English" default>
</video>
5 · The other way

VTT to SRT: what gets left behind.

Needed for most editors and upload forms that predate the web format.

ffmpeg does it in one command, as above. Done by hand, it is more than reversing the punctuation:

  1. Delete the WEBVTT line and any STYLE, NOTE and REGION blocks.
  2. Delete everything after the end time on each timing line: the cue settings.
  3. Write every timestamp in full, with hours: 01:04.250 becomes 00:01:04,250.
  4. Number the cues 1, 2, 3 in order, replacing any named identifiers.
  5. Remove voice tags, class tags and the in-cue timestamps some VTT files use for karaoke-style reveals. Keep <b>, <i> and <u>.

Position, styling and speaker names do not survive, because SRT has nowhere to put them. If they matter, the format you want is probably not SRT but ASS, which carries all of it and is what video tools render when you burn subtitles into the picture.

6 · From the video

If you have the video, you may not need to convert at all.

suubbs writes both formats from the same timings, so there is no conversion step to get wrong.

suubbs transcribes a video on your own Mac, gives every word a timestamp, and exports SRT, WebVTT, styled ASS and a word-level JSON from that one source. A VTT export of captions you never styled is a bare file like the one above, without the cue numbers. Style them, and the VTT carries the look as a STYLE block of ::cue rules, with placement as cue settings, so a browser's own caption renderer shows most of it. Word highlighting, fades and a dragged position are the parts only ASS can hold, and suubbs says so at export. Nothing is uploaded.

You can also convert an existing file in it: open the video, import the SRT or VTT, and export the other format. It is the right tool if the file also needs its words or timing fixed while you are there, and the wrong one for a straight conversion, for four reasons worth knowing:

The free browser version exports only the lines that start in the first 60 seconds; the Mac app, $9.99 once, has no limit. For a long file you only want reformatted, the ffmpeg line above is quicker. If the converted file plays but the words land early or late, that is a different problem, covered in fixing subtitles that are out of sync.

Format questions

What people ask next.

Including the ones that turn out to be about the web page, not the file.

What is the difference between SRT and VTT?

WebVTT is the web format built from SubRip's layout. It starts with a WEBVTT header, uses a full stop rather than a comma before the milliseconds, and can carry positioning, CSS styling and speaker labels that SRT cannot.

Do I need to remove the cue numbers when converting to VTT?

No. In WebVTT a line above the timestamp is an optional cue identifier, so the SRT numbers are valid as they are.

Does converting change the timing?

No. Both formats store milliseconds, so a conversion keeps every time exactly. If the subtitles are early or late after converting, they were already out of sync with that video.

Why does my VTT file not show in the browser?

Check that WEBVTT is the first line followed by a blank line, that the file is UTF-8, that the track has the default attribute, and, if it is on another domain, that the server allows CORS and the video has crossorigin.

Can I use an SRT file directly in an HTML video?

Not in a <track> element. Browsers read only WebVTT there, so convert it first, or load it with a JavaScript player that parses SRT itself.

What do I lose converting VTT back to SRT?

Positioning, STYLE blocks, class and voice tags, and comments. Bold, italic and underline survive. If the styling matters, export ASS instead.

Keep reading

Related

SRT and VTT from the same timings.

[one · source · every · format]