Convert SBV to VTT

The video moves for a reason: a course platform that wants the file, a site that does not want a third-party embed, a client whose brand guidelines rule out a YouTube player, a recording that should not be on a public platform at all. The video transcodes and uploads without difficulty. The captions are the part that stops working.

SBV is Google’s own format and essentially nothing outside YouTube reads it, least of all a browser. HTML video takes subtitles through a track element and accepts WebVTT alone, so a caption file that worked perfectly on the platform it came from produces an empty subtitle menu on the page it moved to.

A WebVTT file must begin with the word WEBVTT on its own first line, before anything else. It is not documentation and it is not optional: a parser that does not find it rejects the file without reading further. SBV has no header construct at all — the first line of the file is the first timing line.

So there is nothing to adapt, only something to add. The converter writes the header and a blank line, then the cues. This is the difference that makes renaming impossible and that a hand-editing approach gets wrong most often, because it is the one part of the format that has no counterpart in the source at all.

SBV puts both times on one line separated by a comma. WebVTT puts them on one line separated by an arrow, with the hours zero-padded to two digits. Both formats already write three digits of milliseconds after a full stop, so that half of the timestamp is carried across unchanged.

The timings themselves are exact. Every value is held in milliseconds through the conversion, so a caption that began at 0:04:12.500 in the SBV begins at 00:04:12.500 in the VTT. Nothing is rounded, snapped or shifted, and there is no precision loss in either direction — the two formats measure the same thing to the same resolution and disagree only about spelling.

A large share of SBV files are automatic transcripts rather than authored captions, and the conversion does not make the words any better. Speech recognition is dependable on ordinary conversational language and undependable on names, places, product names, acronyms and technical vocabulary — which is to say, on the words that carry the point of a sentence.

That matters more once the video is on your own site. For public sector bodies and a growing number of businesses, captions on prerecorded video are a legal requirement under accessibility legislation rather than a courtesy, and an unchecked machine transcript does not meet it. The gap is not only accuracy: captions are supposed to include non-speech information such as who is speaking off screen and when music starts, and a recogniser produces none of that.

Every WebVTT cue can carry settings after its end timestamp: a line setting that moves it vertically, an align setting that moves it horizontally, a position and a size. SBV has none of this, so the converted file arrives with no settings and everything sits at the bottom.

Adding them is the first improvement worth making on a self-hosted player. The bottom of the frame is where a player draws its own controls and where video producers put lower thirds, so a caption that overlaps either is the most common complaint about self-hosted video. Two words on the timing line move it for those few seconds, and no amount of CSS achieves the same thing.

SBV has no construct for attributing a line to a speaker, so caption files that need it use a convention: a name and a colon, or a dash at the start of each speaker’s line as broadcast captioning has always done. Those characters are copied into the WebVTT verbatim, and they will appear on screen exactly as typed.

WebVTT has a proper mechanism for this — a voice tag naming the speaker, which a browser can style differently per speaker and which a screen reader can announce as attribution rather than as text. Converting the typed convention into voice tags is a search and replace, and it is one of the few pieces of manual work on a converted caption file that pays for itself on an accessibility audit.

A WebVTT file fetched from a different origin than the page is refused unless the response carries the right cross-origin headers, and the refusal is silent. The video plays, the subtitle menu is empty, and nothing in the console says why. It is the single most expensive failure in self-hosted captioning, because it looks like every other cause at once.

Serving the .vtt from the same origin as the HTML avoids the entire class of problem, which is a good reason to keep caption files beside the page rather than on a separate asset domain or a bucket with a different hostname. If they must live elsewhere, the cross-origin headers and the crossorigin attribute on the video element both have to be right, and testing that in a browser is the only way to know.

The media type is the other thing a host gets wrong quietly. A WebVTT file should be served as text/vtt, and a configuration that falls back to a generic binary type or to text/plain gives a browser grounds to ignore it. Opening the .vtt URL directly in a tab settles both questions at once: if it renders as text from the same origin as your page, the file and the hosting are fine and whatever is wrong is in the markup.

If the video stays on YouTube as well as on your site, there are now two caption files. They start identical and they diverge the first time somebody fixes a typo in whichever one they had open, and nothing in either file records which is now correct.

Pick a master and generate the other. Editing on YouTube and re-downloading is workable if corrections are rare and the platform is where your team already works. Editing the WebVTT and uploading it to YouTube — which accepts WebVTT directly — is better if the site is the primary home, because the file you maintain is then the one with positioning and voice tags in it, and those are what a re-download would throw away.

The kind attribute has values beyond subtitles and captions, and they use the same WebVTT syntax you now have. Chapters produces a navigable list of sections in players that support it. Descriptions carries audio description text for screen readers. Metadata carries arbitrary timed cues that are never displayed and that JavaScript can react to as the playhead reaches them.

That last one is how interactive transcripts, synchronised slides and timed annotations get built, and it is worth knowing about on a self-hosted player because the platform you left had those features and your page does not. A second track file with kind set to chapters costs a few lines of WebVTT and gives a long recording the thing viewers actually want from it, which is the ability to skip to the part they came for.

It is worth asking, because an embedded YouTube player brings its caption track, its rendering, its language switching and its accessibility behaviour with it at no cost. If the reason for moving is presentational rather than substantive, embedding is less work and fewer failure modes.

The reasons that hold up are the ones about control and privacy: material that should not be on a public platform, a player without third-party tracking, a site that has to work where YouTube is blocked, or a caption track that needs positioning and styling the platform will not do. Where one of those applies, self-hosting is right and this conversion is the first step of it. Where none does, the shorter path is worth considering before the work starts.