A tool for creating styled YouTube subtitles.

YouTube's built-in subtitle editor doesn't support styling of any kind. If you want formatting such as bold, italic and coloring, you need to upload a subtitle file instead. The site accepts a number of file formats such as RealText, WebVTT and TTML, but all of these come with their own limitations - and most importantly, none of them give access to the full array of features offered by the YouTube player. For that, you need to use a YouTube-specific format called YTT (YouTube Timed Text, also known as SRV3). It supports the following:

• Bold/italic/underline
• Text coloring and transparency
• Background coloring and transparency (including hiding the background box completely)
• Outlines, glows and drop shadows
• Fonts and font sizes
• Positioning (place your subtitles anywhere on the video)
• Karaoke timing (make the syllables of a song lyric appear as they're sung)
• Vertical text
• Ruby text

YTSubConverter can produce this file format for you.

The current version is 1.5.0. You can find the change history on the Releases tab.

YTSubConverter is an .ass → .ytt converter. You can create .ass subtitles using Aegisub.

Conversion is straightforward: launch the program, open your .ass file and click Convert. Alternatively, drag the .ass straight onto the .exe. In both cases, you'll get a .ytt file that's ready for upload.

The program tries to approximate the look of the Aegisub subtitles as closely as possible on YouTube:

You'll notice that each .ass shadow can turn into one of four different YouTube shadow types: glow (same as outline), bevel, soft shadow and hard shadow. You can even combine multiple shadow types if you want - just choose from the checkboxes in the conversion UI. This is also where you can configure current word highlighting for karaoke (example video).

Apart from converting from .ass to .ytt, the tool can also convert from .sbv (the format you get when downloading subs from YouTube's built-in editor) to .srt. This allows you to download existing, unstyled subs and add styling to them. Simply open the .sbv file, click Convert, and open the resulting .srt file in Aegisub.

YTSubConverter supports the following .ass style features:

• Font name. YouTube only allows the following fonts:

(Roboto is the YouTube default; the tool will automatically pick this if the specified font is not allowed)

• Font size. The "Default" style (or the first style if there is no "Default") always gets the standard YouTube font size no matter what you pick, while the other styles are relative to it. For example, if the "Default" style has size 15 in Aegisub and the "Header" style has 30, these will be respectively at 100% and 200% of the standard size in YouTube. Note that you can't go lower than 75% and that Android doesn't support custom sizes.
• Bold, italic, underline
• Primary, secondary, outline and shadow color
• Alignment
• Outline thickness and shadow distance (only checking whether the value is 0 or greater than 0)

It also supports the following override tags:

• {\b} - bold
• {\i} - italic
• {\u} - underline
• {\fn} - font. (See above for list of allowed fonts)
• {\fs} - font size. This tag is relative to the size of the "Default" style (or the first style if there is no "Default"). For example, if the "Default" style has size 15 and you put {\fs30}, the YouTube subtitle will be twice the standard size. Note that you can't go lower than 75% and that Android doesn't support custom sizes.
• {\c} or {\1c} - regular text color
• {\2c} - unsung karaoke text color
• {\3c} - outline color
• {\4c} - shadow color
• {\1a} - regular text transparency
• {\2a} - unsung karaoke text transparency
• {\3a} - background transparency
• {\4a} - shadow transparency. Due to YouTube limitations, this only works if the shadow color is &H222222& and the shadow transparency equals the text transparency.
• {\alpha} - set all transparencies at the same time
• {\pos} - position
• {\an} - alignment
• {\k} - karaoke segment duration
• {\r} - reset to current or specified style
• {\fad} - simple fade. Due to YouTube limitations, shadows don't fade along unless their color is &H222222&.
• {\fade} - complex fade. Due to YouTube limitations, shadows don't fade along unless their color is &H222222&.
• {\move} - move from one point to another
• {\t} - animate colors, transparencies and font sizes.
• {\ytsub} - start using subscript (only works on PC)
• {\ytsup} - start using superscript (only works on PC)
• {\ytsur} - switch back to regular script
• {\ytruby} - enable ruby text. {\ytruby}これは[漢/かん][字/じ]です will result in a 漢 with a かん above it, followed by a 字 with a じ above it. You can change the position of the ruby text: {\ytruby8} will display it above the line (default), while {\ytruby2} will display it below. This tag only works on PC; mobile apps will display これは漢(かん)字(じ)です instead.
• {\ytvert} - enable vertical text (only works on PC):
  • {\ytvert9} - characters are placed vertically in columns, with those columns going from right to left.
  • {\ytvert7} - characters are placed vertically in columns, with those columns going from left to right.
  • {\ytvert1} - the whole subtitle is rotated 90° counter-clockwise so that the lines that used to go from top to bottom now go from left to right.
  • {\ytvert3} - the whole subtitle is rotated 90° counter-clockwise and the order of the lines is inverted so they go from right to left.
• {\ytpack} - start ({\ytpack1}) or stop ({\ytpack0}) packing text into the space of a single full-width character. Only works on PC in vertical text.
• {\ytshake} - make the subtitle randomly jump around.
  • {\ytshake} - shake for the duration of the subtitle, staying within 20px of the original position.
  • {\ytshake(radius)} - stay within radius pixels of the original position.
  • \ytshake(radiusX, radiusY) - stay within radiusX pixels of the original position on the X axis and radiusY pixels on the Y axis.
  • {\ytshake(radius, t1, t2)} - start shaking at t1 and stop at t2 (both numbers are in milliseconds relative to the subtitle start time).
  • {\ytshake(radiusX, radiusY, t1, t2)}
• {\ytchroma} - adds a chromatic abberation effect. At the start, a red, a green and a blue copy of the subtitle come together and merge into the regular subtitle. At the end, the subtitle splits up into its three copies again which then disperse.
  • {\ytchroma} - copies start at a distance of 20px and converge/disperse over 270ms.
  • {\ytchroma(intime, outtime)} - copies converge over intime milliseconds at the start and disperse over outtime milliseconds at the end.
  • {\ytchroma(offsetX, offsetY, intime, outtime)} - the first copy starts at offsetX pixels to the left of and offsetY pixels above the subtitle position. (The last copy starts at the same distance in the opposite direction.) Both offsets can be negative.
  • {\ytchroma(color1, color2..., alpha, offsetX, offsetY, intime, outtime)} - replace the default red/green/blue by any number of custom colors. Both the colors and the alpha value should be specified in hexadecimal (&H...&).
• {\ytkt} - enables advanced Karaoke Types.
  • {\ytktFade} - Configure the line to use fading karaoke (example video).
  • {\ytktGlitch} - Configure the line to use karaoke with glitching text (example video). Looks for Latin, Chinese, Japanese and Korean characters in each syllable and generates random ones accordingly. Works best with left-aligned text and invisible unsung lyrics (= fully transparent secondary color).
  • {\ytkt(Cursor,text)} - Places the specified text after the word that's currently being sung.
  • {\ytkt(Cursor,formatting tags,text)} - Like the above, but you can customize the look of the cursor with override tags (similar to \t).
  • {\ytkt(Cursor,interval,tags1,text1,tags2,text2,...)} - Defines an animated cursor where each "frame" lasts interval milliseconds.
  • {\ytkt(LCursor,text)} and other variants - Like Cursor, except the cursor is placed before (to the Left of) the word that's currently being sung.

Unsupported tags are ignored.

The repository contains two sample .ass files:

• Color-coded dialogue sample (YouTube video)
• Karaoke sample (YouTube video)

After you upload a subtitle file, YouTube gives you a preview so you can try it out before submitting. This is nice, except that the preview only shows the file's text; it doesn't show the styling. This complicates testing: each time you make a change and want to see the result, you'd have to actually publish the subtitles so you can see them in the "real" player. This is especially bothersome if you're contributing to someone else's channel, as you'd have to get the subtitles approved each time (or make a copy of the video on your own channel).

Fortunately, there's an easier way to test your subtitles - one which doesn't require you to upload them at all. It works by using Fiddler, a program which can intercept web requests from your browser and send back a file from your hard drive (rather than one from YouTube's servers). By redirecting your browser's request for subtitles to your local .ytt file, you can see those local subtitles in your browser as though you uploaded them. Since you're not actually uploading them, you can test your changes much more quickly.

While this approach can save you a lot of time, it does require some initial setup:

• Download and install Fiddler.
• Launch the program.
• Open the menu Tools → Options.
  • On the "HTTPS" tab, enable "Capture HTTPS CONNECTs" as well as "Decrypt HTTPS traffic."
  • Allow the program to install the security certificate. (Note: if you're using Firefox, some additional steps may be needed)
  • Click OK.
• In the toolbar, change "Keep: All sessions" to "Keep: 100 sessions." (This is to keep the request log from growing too much if you leave the program open for a long time)
• Switch to the "AutoResponder" tab in the right hand panel.
  • Put checkmarks in "Enable rules" and "Unmatched requests passthrough."
  • Click "Add Rule."
  • In the "Rule Editor" at the top, put the following text in the top textbox: regex:^https://www\.youtube\.com/api/timedtext
  • Click "Save."

Once this initial setup is done, you only need to do the following whenever you want to test subtitles:

• Launch Fiddler
• Select the rule on the "AutoResponder" tab
• Put the path to your local .ytt file in the bottom textbox in the "Rule Editor"
• Click "Save."

As long as Fiddler is running (and the rule is enabled), any YouTube video you view will have the specified .ytt file as its subtitles. If you make a change to the file, you don't even need to refresh the page in your browser to see it; simply disable and re-enable subtitles in the video, which will cause the YouTube player to "redownload" them.

Styled subtitles work on your own videos, but also on those made by others: if a content creator enabled community subtitles on a video, you can upload styled subtitles to it.

First access the subtitle editor as follows:

Then upload your .ytt file through the "Actions" dropdown:

Once the upload is complete, click "Submit contribution" while making sure not to change anything in the built-in editor. If you do, all styling information will be lost. (YouTube warns you about this when uploading to your own channel, but not when uploading to others').

Also note that you won't see the styling in the built-in editor's preview pane. This is normal; as long as you don't change anything after uploading, the styling will show up in the "real" video player afterwards.

Subtitles won't appear on the video right away after uploading - they also need to be published. For your own channel, you can of course do this yourself.

For others' channels, there used to be a community approval feature: if enough community members clicked the "Looks good" button, the subtitles would get published automatically, without intervention of the channel owner. As of August 2019, however, this is no longer possible. The hasty change YouTube made in response to spam complaints from top creators means that while the "Looks good" button is still there, it no longer does anything: the subtitles won't get published no matter how many people click it.

The result is that only channel owners can publish community subtitles now. However, YouTube didn't inform them of this change and also doesn't notify them about subtitles awaiting approval. Chances of them noticing and publishing your subtitles are therefore next to zero.

This means that, after you submit your subtitles, you need to contact the channel owner and ask them to publish - each and every time. The first time you contact them, you can point them to YouTube's help page on the topic (English/Japanese) to explain the situation.

YouTube has some bugs and limitations when it comes to styled subtitles. Please be aware of the following:

• Subtitles positioned off-center will move out towards the sides in theater mode, possibly even hanging out of the video frame.
• Custom positions and alignments don't work during a premiere; subtitles are always displayed in the default position, being the bottom center of the video (bug). Once the premiere is over, however, they'll be displayed correctly.
• The mobile apps don't support background customization; they show a black rectangle no matter what color or transparency you specify. This means you need to be careful with dark text, because while it'll be perfectly readable on a custom bright background on PC, it'll be barely readable on the default background on mobile.
  • YTSubConverter detects dark text and adds an invisible, brighter subtitle on top of it. Because the Android app ignores transparency, (only) Android users will see this bright version and be able to read the subtitle. iOS users, however, are not so lucky - the app doesn't show the invisible subtitle, leaving only unreadable black-on-black text.

Subtitles for a certain channel will often have recurring looks. For example, Kizuna AI's gaming channel has pink subtitles for talking, red for screaming and yellow for explanations. To avoid having to put tags everywhere, you should of course define these recurring looks as Aegisub styles. Assigning these styles to the individual subtitles can be quite a hassle, however. This section offers a quicker way.

First do some initial setup:

• Create the styles you need and put them in your Aegisub style storage.
• Place the script replace markers.lua in Aegisub\automation\autoload.
• Choose a marker (ideally a single, special character) for each style and link these markers to their styles inside the script. The script contains some examples, and as you'll see, it's in fact possible to register multiple marker sets for different YouTube channels.

Then do the following for each video:

• Download the video using e.g. youtube-dl. (Tip: because YT-DL picks the highest resolution by default, you can save time by using -F to discover the available video resolutions and then downloading with -f<number> to download a smaller file.)
  • If you're planning on doing karaoke timing, you may want to check if the video has Opus-encoded audio and explicitly download that - reason being that the m4a audio you normally get is ever so slightly shifted in time. Example: -f137+251
• Open the locally saved video in a player that supports global hotkeys (e.g. VLC). If you haven't yet, set up hotkeys for pausing, resuming and rewinding the video.
• Open Notepad and type out the subtitles, using the global hotkeys to control the video without having to switch between windows.
• While typing, prefix each line with the marker of the style it should get later on. (e.g. *Hello, Darling!)
• When you're done, copy all the text and paste it into Aegisub's subtitle grid (simply click the grid and press Ctrl-V).
• Next, run the script by clicking Automation → Replace markers → <channel name> in the Aegisub menu. This will remove the markers and assign the corresponding styles.
• Set up the timings and additional formatting.
  • If the video has hardsubs, you can save a lot of time by using the "Align subtitle to video" feature of this unofficial Aegisub version. Simply select the softsub, activate the feature from the toolbar, click a point in the hardsub and click OK; the timing of the softsub will be automatically updated to match. To work even faster, set up a hotkey for this feature using the time/align command name.
• Save the subtitles as an .ass file.
• Convert the .ass to .ytt using YTSubConverter.
• Upload the .ytt to YouTube and contact the channel owner for publishing.

YTSubConverter can also convert in the opposite direction: from .ytt (or .srv3, which is the same) to .ass. What's more, it can do this for two different purposes: editing and archiving.

• By default, it'll produce an .ass file that you can edit and convert back to .ytt, getting the exact same look with different text. Example use cases: fixing a mistake in your own published subtitles if you already deleted the .ass, or translating someone else's published subtitles for which you never had the .ass in the first place.
• You can also get an .ass that emulates how the subtitles look on YouTube. To do this, you need to call the converter from the command line, passing it the .ytt/.srv3 path along with the --visual option. While the resulting .ass can't be converted back to .ytt, it does give you (almost) the same visual experience in a local media player as on YouTube. Example use case: archiving videos so you can keep watching them, with visually accurate subtitles, even if they get taken down.

You can download a video along with its published .ytt/.srv3 subtitles by using youtube-dl with the following options: --write-sub --all-subs --sub-format=srv3

Thanks to the following people for providing the UI translations:

• Admiy02 - Malay
• Kasaka-117 (@kasaka_117) - Korean
• Mali (@mali_5157) - Chinese
• Saiv46 - Russian
• tototo (@vvto33) - Japanese