Convert VTT to ASS

Because the destination stopped being a web page. A vertical cut for social, a promo that has to read on a muted feed, a translated version where on-screen text needs replacing in place — none of those are served by a track element and a stylesheet. They need subtitles that are part of the picture, and that means a format where appearance is written into the file.

WebVTT is a good delivery format and a poor authoring one for this kind of work. It has a small styling vocabulary, browsers implement the weaker parts of it inconsistently, and none of it survives the moment the video leaves the browser. ASS was built by people whose entire concern was how the subtitles look, and this conversion is the door into that.

Across: the text of every cue, its line breaks, and its start and end times. That is the substance of the track and it arrives complete, with every cue turned into a dialogue line under one style.

Stopped: cue settings, voice tags interpreted as speakers, STYLE blocks, NOTE comments and cue identifiers. Four of those five are constructs a WebVTT author had to type deliberately, which is why this page names them rather than describing the conversion as lossless. If your VTT was written by a transcription service and never touched, none of them apply and nothing at all is lost.

A WebVTT timing line can carry a line number, an alignment, a position and a size after the end timestamp. The parser reads the end time up to the first space and throws away everything after it, so a caption you deliberately pushed to the top of the frame comes out at alignment 2 with all the others.

The frustrating part is that ASS is dramatically better at this than WebVTT ever was — a numeric grid for the standard nine positions, and an override tag that can place a line at an exact coordinate, move it over time, or rotate it. The information simply does not survive an intermediate representation that holds a start, an end and some text. Note which cues were positioned before you convert, because afterwards nothing in the file remembers.

Making that note takes a minute and is worth the minute. Search the WebVTT for the word line, which is the setting that does nearly all the work in practice, and write down the timestamps it appears on. Those are the cues that were moved for a reason — a lower third, a burned-in title, a graphic — and they are the ones that will sit on top of that reason once every caption defaults to the bottom of the frame. Everything else was always going to be at the bottom and needs no attention at all.

WebVTT marks a speaker with a voice tag in angle brackets at the front of the cue. ASS attributes a line to a named style, and optionally to a name field in the dialogue line, which is a different mechanism entirely. Nothing maps one onto the other, and cue text is copied verbatim, so the tag arrives as characters a renderer will draw on screen.

The correct response is to make it a style, which is what you came here for. Define one style per speaker with its own colour, then assign lines to them and delete the tags. That gives you what the voice tag was gesturing at and what a browser mostly refused to render — two speakers distinguishable at a glance, without writing their names into the caption text.

The generated style is Arial at size 48, white, with a black outline two pixels thick, no shadow, alignment 2, and margins of 10 on the left, right and bottom. The script header sets ScriptType v4.00+, WrapStyle 0 and ScaledBorderAndShadow yes.

For social work the first two fields to touch are the font and the outline. Arial is chosen because it exists everywhere rather than because it looks like anything, and a two-pixel outline that is legible over a dark scene disappears over a bright one — a background box or a heavier outline is what makes captions readable on a phone in daylight. ScaledBorderAndShadow being on means both scale with the resolution rather than staying fixed at the script’s.

In WebVTT the appearance mostly lives outside the file: CSS in the page targets the cue pseudo-element, and a STYLE block inside the file is a limited in-band version of the same thing. The file describes content and the page describes presentation, which is a sound separation for a document format.

ASS inverts that. Styles are named, defined in the file, referenced per line, and overridable inline for a single word. The file is the presentation, which is why it renders identically in every player that implements the format and why it can be burned into a picture with confidence. Neither model can be mechanically translated into the other, which is the honest reason nothing carries across.

WebVTT writes three digits after the decimal point and ASS writes two, so every timestamp is truncated on the way in. A cue starting at 00:00:01.238 becomes 0:00:01.23. The error is at most nine milliseconds and always early, never late.

That is a fifth of a frame at 24 frames per second and it will never be seen. The one exception is karaoke timing, where syllables are set against the audio and the difference between two adjacent syllables can matter. Karaoke is authored in ASS rather than converted into it, so in practice this is a footnote rather than a constraint.

Most places the finished video will go cannot render an ASS track: social platforms, phone galleries, televisions reading from a network share, and every web player. If the styling is the point, the styling has to become pixels, which means rendering the subtitles into the frame and re-encoding the video.

Decide before you typeset rather than after, because the two paths reward different choices. A track destined to be burned in can use any font on your machine and place text anywhere, since the viewer’s machine is never involved. A track meant to stay soft has to survive font substitution and a player that may ignore half of what you wrote, and the design has to be conservative enough to degrade quietly.

An ASS dialogue line has ten fields before the text: a layer, the two times, a style name, a character name, three margin overrides and an effect. The conversion fills three of them — the times and the style, which is always Default — writes the layer as zero, and leaves the rest empty.

Those blanks are where typesetting starts. The layer decides what draws on top of what when two lines share the screen, which matters the moment a sign is placed over dialogue. The margin overrides move a single line without touching the style, which is the light-touch way to lift one caption above a subtitle burned into the picture. And the character name is a free-text field Aegisub shows as a column, which makes it the natural place to record who is speaking while you work out which lines belong to which style.

These two files answer different questions and it is reasonable to keep both, as long as one of them is generated. The VTT belongs on the web page, where it is accessible, selectable, searchable and switchable off. The ASS belongs to the version of the video where appearance is the message.

Which one is the master depends on where the corrections happen. If the words change most often — a name spelled wrong, a caption re-timed — the VTT is the master and the ASS is regenerated and re-typeset, which is real work. If the design changes most often, keep the ASS and export a plain track for the web. What does not work is editing both, because nothing in either file records which one is now correct.