YTSubConverter: turning styled ASS subtitles into YouTube SRV3 timed text

YouTube's own editor cannot style a single character

The gap this tool fills is specific. YouTube's built-in subtitle editor does not support styling of any kind, so a creator who wants bold, italic or coloured captions has to upload a subtitle file instead. The site accepts several formats, including RealText, WebVTT and TTML, but each carries its own limitations, and none of them expose the full feature set of the YouTube player.

That feature set is what the SRV3 format provides, also called YTT for YouTube Timed Text. The list is long enough to explain why a dedicated converter exists: bold, italic and underline, text colouring and transparency, background colouring and transparency including hiding the background box entirely, outlines, glows and drop shadows, font and font size selection, free positioning of subtitles anywhere on the video, karaoke timing that reveals syllables as they are sung, vertical text, and ruby text.

The audience is therefore creators with their own channel who can upload a caption file, rather than viewers. This is a production tool for the upload side of YouTube, not a playback or download utility, and it makes no attempt to fetch or modify anything on the platform.

An .ass to .ytt converter at its core, with two side conversions

The primary conversion path is .ass to .ytt, and the assumption is that you already have an authoring workflow. The project states plainly that it is primarily an .ass to .ytt converter, and that you can create .ass subtitles using Aegisub. Everything else in the tool is a convenience around that path.

Two other conversions exist. The tool can convert .sbv, the format you get when downloading subs from YouTube's built-in editor, into .srt. That direction is a way to take existing unstyled subtitles, get them into .srt, open them in Aegisub, add styling, and run the whole loop back through the converter. The other is .ttml to .ytt, and the reason to do it is that YouTube already accepts TTML uploads directly but with limited support, so converting to .ytt and uploading that instead opens up more features and provides workarounds for YouTube bugs.

One thing the .ttml path does not buy you is everything. Certain features, karaoke and transitions among them, are still only available through .ass, which is the format the converter treats as the source of truth. If your caption needs per-syllable timing or transitions, the workflow has to go through Aegisub rather than a TTML export.

Opening the app, dropping a file, and reading the output

There is no install script to run and no command line documented for the converter itself. The application is distributed as a release, with the project page pointing at the releases area, and the README states that the current version is available for Windows, macOS and Linux. The repository layout confirms the three-platform structure, with separate YTSubConverter.UI.Win, YTSubConverter.UI.Mac and YTSubConverter.UI.Linux projects alongside a shared project, a test project, and a solution file.

The workflow is short. Launch the program, open your .ass file, and click Convert. On Windows there is a shortcut, and it is a genuinely useful one: you can drag the .ass file straight onto the .exe. Either way the output is a .ytt file that is ready for upload.

The conversion is a visual approximation rather than a pixel-accurate port. The stated goal is to approximate the look of the Aegisub subtitles as closely as possible on YouTube, and the project is candid that the mapping is not one to one. The example given is shadows: each .ass shadow can turn into one of four different YouTube shadow types, glow, bevel, soft shadow and hard shadow, and you can even combine several shadow types by ticking the checkboxes in the conversion UI. That same panel is where current word highlighting for karaoke is configured.

The YouTube-side limits on what .ass can express

The most useful part of the documentation is the list of places where ASS features hit a YouTube wall, because those are the surprises you would otherwise discover after uploading.

Font is the first. YouTube only allows a fixed set of fonts, and the tool automatically picks Roboto, the YouTube default, when the specified font is not permitted. Font size is relative rather than absolute. The Default style, or the first style if there is no Default, always receives the standard YouTube font size no matter what you pick, and every other style is expressed as a percentage of it, so a Default of 15 and a Header of 30 become 100 percent and 200 percent of standard size. You cannot go lower than 75 percent, and the Android app always uses the same size whatever you specify.

Alignment has a side effect that is easy to miss. On YouTube, alignment affects not only the position of the subtitle but also how subtitles move when a user hovers the mouse over the video. Top-aligned subtitles, alignments 7, 8 and 9, move downwards, center-aligned ones, alignments 4, 5 and 6, stay in place, and bottom-aligned ones, alignments 1, 2 and 3, move upwards. Outline thickness and shadow distance survive only as a check of whether the value is zero or greater than zero, so a precise outline weight in Aegisub does not carry over.

Transparencies and fades have their own conditions. Shadow transparency works only if the shadow colour is &H222222& and the shadow transparency equals the text transparency, and the same restriction applies to shadows and outlines during both the simple {\fad} and complex {\fade} fades, which do not fade along unless their colour is &H222222&.

The override tags that reach beyond plain styling

A set of override tags is supported, and several of them exist purely to work around YouTube behaviour rather than to mirror ASS. The styling tags are the familiar ones: bold, italic, underline, font, font size, the primary text colour, the unsung karaoke colour, outline colour and shadow colour, each with a matching transparency tag, plus a tag that sets all transparencies at once. Position, alignment, karaoke segment duration, style reset, and move from one point to another are all carried across, and the tool can animate colours, transparencies and font sizes.

One of them is worth singling out. Making the unsung karaoke text fully transparent is what switches YTSubConverter to YouTube's native karaoke feature, and that native mode hides the text and background box of unsung text even on mobile, which is a behaviour you would otherwise have to approximate with transparency tags.

The YouTube-specific tags extend the format past what ASS can do. There is a subscript, a superscript and a switch back to regular script, and all three work only on PC. Ruby text is enabled with its own tag, and the example given shows a Japanese phrase broken into base characters with readings above them:

{\ytruby}これは[漢/かん][字/じ]です

The ruby position can be changed, with the position 8 variant putting the reading above the line as the default does, and the position 2 variant putting it below. Ruby text also works only on PC, and mobile apps will display the text with parenthesised readings instead.

Vertical text follows the same pattern. The tag enables it, and only on PC, with variants for columns going from right to left, columns going from left to right, a whole subtitle rotated 90 degrees counter-clockwise, and a rotated subtitle with the order of the lines inverted. These are not ASS concepts, so no general subtitle tool would produce them.

What a subtitle uploader can and cannot do with this

The practical limit is the platform, not the tool. Everything this converter produces is a file you upload to a video on a channel you control, so there is no API, no CLI, and no automation surface in the documentation. The project is a desktop application with a conversion dialog, which is a sensible fit for a caption workflow that a person runs a handful of times per video.

The second limit is fidelity. The converter maps ASS concepts onto YouTube concepts, and the mapping is lossy in specific, documented ways: outline weights collapse to a boolean, font sizes become relative percentages with a 75 percent floor, fades refuse to touch shadows and outlines unless the colour matches a specific value, and several YouTube-specific features are PC only. A creator whose design depends on exact outline weight is going to be disappointed.

The third limit is the source of truth. ASS remains the authoring format, and Aegisub remains the editor. The converter is a translator at the end of that chain, not a replacement for it. Interestingly, the repository also carries files that are not part of the converter core, including a mitmproxy_script.py, a replace markers.lua for what appears to be a subtitle authoring helper, and sample .ass files. Those extras hint at a broader workflow around the tool, though the documentation here does not describe them.

For a pure .ass to .ytt job, none of that matters. Download a release, convert, upload, and check the result on the clients your viewers actually use, since the desktop and mobile differences documented above are the ones that will show up in the comments.

Editorial conclusion

YTSubConverter is worth adopting if you already author in Aegisub and upload subtitles to your own YouTube channel, since it removes the manual translation from ASS styling into a YouTube-specific format. It is the wrong tool if you are not uploading captions yourself, because it produces no subtitle file that a viewer benefits from. Before you rely on it, convert sample1.ass, upload the .ytt to a private or unlisted video, and check the result on both desktop and an Android client, because the documentation states several effects, including ruby text, vertical text, subscripts and superscripts, work on PC only, and the Android app always uses the same font size regardless of what you specify.

Frequently asked questions

Official sources

1. arcusmaximus/YTSubConverter on GitHub
2. Issues
3. License: MIT
4. README
5. Releases