SubStation Alpha and ASS

SubStation Alpha (SSA, .ssa) and its successor Advanced SubStation Alpha (ASS, .ass) are text subtitle formats with full control over fonts, colours, outlines, positioning, rotation, animation, karaoke and vector drawings. Anime fansubs, music videos and anything with typeset signs use ASS. The original SubStation Alpha program is long abandoned; the format lives on through libass, the renderer used by mpv, VLC, FFmpeg, Jellyfin and most players on Linux and Windows, and through editors such as Aegisub and Subtitle Edit.

Players that do not use libass (most TVs, phones, browsers, Apple software) render ASS poorly or not at all. For those, deliver SRT, or burn the subtitles in.

File structure

[Script Info]
ScriptType: v4.00+
PlayResX: 1280
PlayResY: 720
ScaledBorderAndShadow: yes
YCbCr Matrix: TV.709

[V4+ Styles]
Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
Style: Default,Noto Sans,44,&H00FFFFFF,&H000000FF,&H00000000,&H80000000,0,0,0,0,100,100,0,0,1,2,0,2,48,48,36,1

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:01.00,0:00:03.50,Default,,0,0,0,,The test begins here.
Dialogue: 0,0:00:04.00,0:00:07.00,Default,,0,0,0,,{\an8\i1}Top of the frame{\i0}\Nsecond line

• [Script Info] sets PlayResX/PlayResY, the coordinate space all sizes, margins and positions are measured in. libass scales that space to the video, so a script written for 1280×720 still fits 1080p. ScaledBorderAndShadow: yes makes outlines scale with it. YCbCr Matrix tells the renderer which matrix the video uses, so subtitle colours match colours sampled from the video: set it to the video’s range and matrix (TV.709 for ordinary HD), or None for anything that is not BT.601 or BT.709, such as HDR.
• [V4+ Styles] defines named styles. Events pick one by name; override tags change it per line.
• [Events] holds the Dialogue: lines. Times are H:MM:SS.cc (centiseconds, with a period). \N is a hard line break; the text field may contain commas.
• Colours are &HAABBGGRR: alpha first, then blue, green, red, the reverse of HTML. Alpha 00 is opaque and FF is transparent, so &H00FFFFFF is opaque white. Inside override tags the form is &HBBGGRR&.
• Lines starting with ; are comments, and Comment: events are ignored by renderers.

Override tags worth knowing

Tags go in {braces} inside the text, and {\i1}…{\i0} toggles for part of a line. The full list is in Aegisub’s reference.

Tag	Effect
\an1…\an9	Alignment on the numeric keypad layout (\an8 is top centre, \an2 bottom centre)
\pos(x,y), \move(…)	Place text at a coordinate in the script space, or move it
\b1, \i1, \u1	Bold, italic, underline
\fnName, \fs40	Font and size
\c&HBBGGRR&	Primary colour; \3c outline, \4c shadow
\fad(in,out)	Fade in and out (milliseconds)
\k, \kf, \ko	Karaoke timing (centiseconds)
\p1	Treat the text as a vector drawing

Fonts: attach them

ASS styles reference fonts by family name, and the viewer must have them. Fonts that are not installed fall back to a default and ruin typesetting. In Matroska, attach the font files to the MKV so mpv, VLC and other libass players load them automatically:

ffmpeg -i video.mkv -i subs.ass -map 0 -map 1 -c copy -attach NotoSans-Regular.ttf -metadata:s:t:0 mimetype=font/ttf output.mkv
mkvmerge -o output.mkv video.mkv subs.ass --attach-file NotoSans-Regular.ttf
mkvpropedit output.mkv --add-attachment NotoSans-Bold.ttf

Set one -attach and mimetype pair per font (-metadata:s:t:1, …). A font installed on your own machine hides a missing attachment, so test on a machine without it. Check that the licence of each font allows redistribution. To extract the fonts from an existing MKV: ffmpeg -dump_attachment:t "" -i video.mkv (it ends with “At least one output file must be specified”, but the fonts are written), or mkvextract video.mkv attachments 1 2 3.

ASS only survives in Matroska. MP4 cannot hold ASS or fonts, and -c:s mov_text would reduce it to plain text.

Burn in

ffmpeg -i video.mkv -vf ass=subs.ass -c:v libx264 -crf 18 -c:a copy output.mp4
ffmpeg -i video.mkv -vf subtitles=video.mkv -c:v libx264 -crf 18 -c:a copy output.mp4

ass= reads an .ass file. subtitles=video.mkv renders the file’s first embedded subtitle track and loads its attached fonts (si=1 picks the second). To use fonts from a folder instead, add :fontsdir=/path/to/fonts. Both filters need an FFmpeg built with libass.

Converting

ASS to SRT or WebVTT keeps the words and basic italics/bold, and drops everything else; FFmpeg leaves <font size> wrappers and raw {\an8} tags in the SRT. SRT to ASS works cleanly and gives you a basic style to restyle in an editor. See the subtitle overview.