WebVTT (.vtt) vs SRT: which file a platform wants

WebVTT exists because HTML5 needed a subtitle format that browsers could implement without licensing complications and without the ambiguities of SRT. It was specified alongside the video element, so a browser could render captions, subtitles, chapters and metadata descriptions from the same file type.

The additions that matter in practice are placement and timing controls. A cue can declare where it sits on the screen, how wide it is, and how it aligns, which lets a caption avoid covering a face or a scoreboard without changing the video. For Chinese material with pinyin above the characters, that control is the difference between a readable two-line block and text that overlaps.

WebVTT also supports regions, which group cues that share a placement, and chapters and metadata tracks, which are separate from dialogue. Most users never touch those, but they are why WebVTT files from professional workflows look more structured than a plain SRT.

The single most common failure is the timestamp. SRT writes one second as 00:00:01,000 with a comma; WebVTT writes 00:00:01.000 with a period. A file with the wrong separator is rejected outright by strict parsers and silently misread by lenient ones, which is worse because the result looks like a timing problem rather than a syntax problem.

The second is the header. A WebVTT file must begin with the line WEBVTT. Some players tolerate a missing header, browsers do not, and the failure message is rarely specific. If a browser refuses a file that opens fine on the desktop, check the first line before checking anything else.

The third is the cue number. SRT requires a sequence number before each cue. WebVTT treats that position as an optional identifier and will accept a name or nothing at all. Automated converters sometimes emit numbers as identifiers, which works, and sometimes emit the number as part of the text, which does not.

Both formats are plain text, and plain text has no self-describing encoding. A file saved as GBK or Shift-JIS and then read as UTF-8 displays replacement characters or boxes, and the text is unrecoverable without knowing the original encoding. Save subtitles as UTF-8, and prefer UTF-8 without a byte order mark for WebVTT, because some browser parsers treat a leading BOM as content.

The second encoding trap is a text editor that saves "ANSI" by default. On a Chinese Windows machine that usually means GBK, and the file will look correct in that editor while looking broken everywhere else. If a client reports "the Chinese is garbled", the first question is which encoding the file was saved in, not which characters were used.

The third trap is stripping the BOM during conversion. Some pipelines do it correctly; some leave an invisible character that becomes part of the first cue. If a browser shows a stray symbol before the first subtitle line, that is usually what happened.

HTML5 video players and anything built on the browser video element want WebVTT. A self-hosted video page, a learning management system with an HTML5 player, or a custom web app will almost always take a .vtt and often will not accept an .srt without conversion.

Desktop players, older editing software, and most translation tools want SRT. It is the lingua franca of subtitle exchange: small, simple, and readable by everything, which is exactly why it is still the default handoff format after decades.

Some destinations want neither. A platform with its own caption editor wants text pasted into a box, sometimes with timings, sometimes without. In that case the practical move is to keep the SRT for your own record and paste the text, letting the platform re-time it — the SRT is the artifact that lets you paste without retyping.

SRT to WebVTT is lossless in the direction that matters: text and timing carry over, and you gain the ability to add cue settings later. The conversion is mechanical — add the header, change the millisecond separator — which is why it is safe to do at the last minute.

WebVTT to SRT is lossy in a specific way: cue settings such as position, line and alignment have no equivalent in SRT, so a caption that was placed to avoid a face will end up at the default position. If placement matters, keep the WebVTT as the master and export SRT only for destinations that demand it.

ASS is a different case. It stores text, timing, styling and both horizontal and vertical placement, which is what a two-line Chinese-plus-pinyin layout needs. Converting ASS to WebVTT or SRT drops the styling, so an ASS file should be treated as the master when the layout is the deliverable.

Open the file in a plain text editor and look at the first five lines. You should see either a number or WEBVTT, then a timestamp with the right separator, then the text. If the first timestamp is on the first line, the header is missing and a browser will reject the file.

Check that the last cue ends before the video does, and that the first cue does not start before the video starts. Negative or beyond-duration times are accepted by some parsers and rejected by others, and they are the cheapest thing to catch before an upload.

Finally, spot-check one cue with Chinese characters and one with a pinyin diacritic — for example a syllable with a third-tone mark. If the tone mark survives the editor, the encoding is intact; if it turns into a question mark, the file was saved in a codepage that cannot represent it.

We export SRT because it is the most portable result of the work: plain text and timing that any player, editor, or translator can open. We export ASS because a pinyin line above each character is a positioning problem, and positioning is what ASS stores.

We do not generate WebVTT today. If your destination is an HTML5 player, convert the SRT to WebVTT — the conversion is mechanical and lossless for text and timing — or use the ASS file where a player renders it, which most desktop players do. If you need the placement that WebVTT offers for web delivery, say so; that decision belongs to the roadmap, not to a hidden behaviour.

The browser shows nothing at all. Nine times in ten the file has no WEBVTT header, or the track element points at a path the page cannot load because of a same-origin rule. Both failures look identical from the viewer side, so check the first line of the file before checking the network tab, and check the network tab before assuming the markup is wrong.

The text appears but sits in the wrong place, or overlaps the controls. That is usually a player default rather than a file error: without cue settings, the player places captions where it likes. Add explicit line and position values to the cues that matter, and test in the player your audience actually uses rather than the one you happen to have open.

The file works locally and fails after upload. This is nearly always the content type. A server that serves .vtt as text/plain will make a browser display the cue list as text instead of rendering it as captions. The fix belongs in the server configuration, not in the file.

The timings look right but everything is one cue behind. Autoplay muted video, a delayed start, or a player that begins playback from a preroll timeline all shift the reference point. In those cases the file is correct and the page is describing a timeline the viewer is not watching, so the offset has to be applied by the page rather than baked into the file.