ASS File Documentation

Summary

An .ass file is an Advanced SubStation Alpha subtitle: a plain UTF-8 text file that stores timed subtitles together with rich styling — named fonts, colours, on-screen positioning, rotation, fades and karaoke timing. It extends the older SubStation Alpha (SSA) format and is the standard for typeset subtitles such as anime fansubs. Name it after the video (movie.mkv + movie.ass) so players like MPV or VLC auto-load it, and edit it in Aegisub. Its MIME type is text/x-ssa.

Technical details

FeatureValue
Full nameAdvanced SubStation Alpha (ASS / SSA v4.00+)
File extension.ass
MIME typetext/x-ssa
Format typePlain-text styled/timed subtitle (INI-style sections)
EncodingUTF-8 text (optional EF BB BF BOM)
DeveloperEvolved from SubStation Alpha (Kotus, 1998); popularised by the Aegisub editor
IntroducedASS in the early 2000s, extending SSA (1998)
Open standardYes (openly documented, no licence fee)
StructureSections: [Script Info], [V4+ Styles], [Events]
Event lineDialogue: with 10 comma-separated fields (Layer, Start, End, Style, Name, MarginL/R/V, Effect, Text)
Reference rendererlibass (used by MPV, VLC, ffmpeg)
First line[Script Info] (text, not a binary signature)
Related extensions.ssa, .srt, .vtt, .sub, .sup
SpecificationASS specification
Syntax at a glance

An .ass file is plain UTF-8 text with no binary signature. It is organised into INI-style sections, each introduced by a name in square brackets. It almost always opens with [Script Info] (optionally after a UTF-8 BOM). The three key sections are [Script Info] (metadata plus PlayResX/PlayResY, the resolution the styles are designed for), [V4+ Styles] (named style definitions), and [Events], where each subtitle is a Dialogue: line whose 10 comma-separated fields end with the text. Inline override tags in braces, e.g. {\i1}, {\pos(640,700)}, {\fad(200,200)}, change styling mid-line.

What is an ASS file?

An .ass file is a subtitle in the Advanced SubStation Alpha format. It began as an extension of SubStation Alpha (SSA), a format created in 1998 for the SubStation Alpha editor by Kotus; the “Advanced” revision, internally versioned SSA v4.00+, added far more control over how text is drawn and where. It is plain UTF-8 text, so any editor can read it, but where SRT carries only text and timing, ASS carries a full typesetting model: named styles, arbitrary fonts and colours, precise positioning, rotation, fades and karaoke. That is why it became the standard for fansubbed anime and for any subtitle that has to typeset signs, song lyrics and stylised dialogue rather than just caption speech.

The file is organised as INI-style sections, and the rest of this article walks through them: the [Script Info] header and why its resolution fields matter, the [V4+ Styles] style table field by field, the ten fields of a Dialogue: event, the override-tag language in braces, and how a renderer like libass turns all of that into pixels. Nothing here is binary; every element is a line of readable text.

The [Script Info] section and PlayRes

An ASS file almost always opens with the section header [Script Info] (optionally after a UTF-8 byte-order mark, EF BB BF). This section holds document-level metadata as Key: Value lines: Title, ScriptType: v4.00+ (which declares the ASS dialect), WrapStyle, ScaledBorderAndShadow, and crucially PlayResX and PlayResY.

PlayResX/PlayResY define the virtual canvas that every coordinate, font size and margin in the file is expressed against. If a script says PlayResX: 1280 and PlayResY: 720, then a {\pos(640,360)} tag means the centre of a 1280×720 frame, and the renderer scales that canvas to the actual video size. Getting these values wrong is the single most common cause of subtitles that appear too large, too small or mispositioned: the styling was authored for one resolution and is being stretched onto another.

[V4+ Styles]: the style table, field by field

The [V4+ Styles] section defines named styles that events refer to by name. It begins with a Format: line listing the columns in order, then one Style: line per style with values in that exact order. The 23 fields are:

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,Arial,48,&H00FFFFFF,&H000000FF,&H00000000,&H64000000,
       0,0,0,0,100,100,0,0,1,2,2,2,10,10,10,1

Several fields deserve a note. The four colour fields are &HAABBGGRR hex: the byte order is alpha, blue, green, red, and the alpha byte is inverted (00 is opaque, FF is transparent). PrimaryColour is the fill; OutlineColour is the border; SecondaryColour is used by karaoke for the not-yet-sung portion; BackColour is the shadow. Alignment uses numpad positions (1–9), where 2 is bottom-centre and 8 is top-centre. BorderStyle chooses an outline+shadow (1) or an opaque box (3). Outline and Shadow are widths in pixels. Because styles are named, a single change to a style line restyles every line that uses it — the reason ASS is called a typesetting format, not just a caption format.

[Events]: the ten fields of a Dialogue line

The [Events] section carries the subtitles themselves. Like the styles section it starts with a Format: line, then each subtitle is a Dialogue: line with ten comma-separated fields — and only ten, because the last field, the text, may itself contain commas and is therefore never split.

Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:12.30,0:00:15.80,Default,,0,0,0,,{\i1}Did you hear that?{\i0}

Layer orders overlapping lines (higher layers draw on top). Start and End are timestamps in H:MM:SS.cc (centiseconds, not milliseconds). Style names which [V4+ Styles] entry to apply. Name is a free-text actor label used by editors, ignored at playback. MarginL/MarginR/MarginV override the style’s margins for this line (0 means use the style). Effect can invoke built-in effects such as Scroll up or Banner. Text is the visible string, which may contain override tags. An Events line can also begin with Comment: instead of Dialogue:, in which case it is stored but not rendered.

Override tags: styling inside the text field

Within the text, styling is changed mid-line by override tags in curly braces, each starting with a backslash. They are what push ASS well beyond SRT’s basic italics. A representative set:

TagEffect
{\i1} / {\b1}Italic on / bold on (0 turns off)
{\pos(x,y)}Place the line at an absolute point on the PlayRes canvas
{\an8}Set alignment for this line (numpad positions)
{\fad(t1,t2)}Fade in over t1 ms, fade out over t2 ms
{\c&H0000FF&}Change the primary (fill) colour mid-line
{\frz30}Rotate the text 30 degrees around the z-axis
{\t(...)}Animate a tag’s value over time (transform)
{\k50}Karaoke: hold this syllable for 50 centiseconds, then recolour

Karaoke is a good illustration of how the pieces combine: the \k tags split a line into syllables with per-syllable durations, and the renderer sweeps each syllable from SecondaryColour to PrimaryColour as its time arrives. All of this is stored as ordinary text, which is why an .ass file is tiny and diff-friendly even for heavily typeset dialogue.

How libass renders a line, and why VLC and MPV differ

The de-facto reference renderer is libass, the library MPV, ffmpeg and many others use. To draw a frame it resolves each active event’s style, applies any override tags in order, lays out the text against the PlayResX/PlayResY canvas, requests the named fonts (falling back if a font is missing), and composites fill, outline and shadow with the specified colours and alpha. Because libass implements the tag language closely, MPV and IINA tend to render advanced ASS accurately. VLC handles the common cases but has historically not matched every tag, which is why the same file can look correct in MPV and slightly off in VLC. A missing font is the other frequent cause of “my styling disappeared”: the renderer substitutes a default face and the intended look is lost.

Sidecar files, muxing and the SRT trade-off

Using an .ass with a video works exactly like SRT: give the subtitle the same base name as the video in the same folder (movie.mkv + movie.ass) and libass-based players auto-load it, or drag it onto the playing window. To bind it permanently and keep it toggleable, mux it into an MKV as a selectable subtitle track with MKVToolNix; the styling is preserved because MKV stores the ASS track verbatim. Converting ASS down to SRT is possible in Aegisub or Subtitle Edit, but it is lossy in one direction only: SRT carries text and timing, so every style, position, colour and karaoke effect is discarded and just the words and timestamps survive. If you need styled subtitles inside an MP4, which has poor support for styled text tracks, the usual route is to burn (hardsub) the ASS into the picture, which is irreversible and requires re-encoding.

FAQ

What is the difference between ASS and SRT?

SRT stores only text and timing with minimal formatting. ASS adds a full typesetting model: named styles, fonts, colours, absolute positioning, rotation, fades and karaoke. Converting ASS to SRT keeps the words and timestamps but drops every styling feature, because SRT has nowhere to put them.

Why do my ASS subtitles look plain or mispositioned?

Two usual causes. The player may not fully implement the tag language — MPV and IINA (libass) render advanced ASS most accurately, VLC less so. Or the fonts named in [V4+ Styles] are not installed, so the renderer substitutes a default face. Mispositioning specifically often means the PlayResX/PlayResY in [Script Info] do not match the resolution the styling was authored for.

Why are ASS colours written back-to-front, like &H00FF0000 for blue?

Colours are stored as &HAABBGGRR: alpha, blue, green, red. So the low byte is red and the high byte is alpha, and the alpha is inverted (00 = fully opaque). &H00FF0000 is therefore opaque blue, not red.

References