This is an old revision of the document!
Table of Contents
ffmpeg - Subtitles - ASS file syntax
ASS (Advanced SubStation Alpha) is a newer version of SSA (SubStation Alpha); technically version 4+).
- SubStation Alpha (SSA) is a subtitling / script format that supports text formatting, animation, graphics and karaoke.
File Specification
SSA and ASS files are plain text files.
- ASS added Unicode support.
ASS (SSA V4+)
ASS is an improvement upon the SSA V4 specification.
- ASS files have INI-style sections: each section is preceded by a line containing the sections name, in square brackets.
- Aside from this, each line is generally composed of: a line descriptor, which tells about what the line is about; a colon; and the line data itself.
- Any whitespace between these parts are allowed.
- Blank lines are also allowed.
- Hard comment lines are preceded by either a semicolon or !: (with “!” as the line descriptor).
- Unrecognized and incorrect line formats are ignored.
Fields on the line data are separated by a comma and, with the exception of the Text field, which should be the last field, must not contain any commas.
Descriptors
<td Original Script Original Translation Original Editing Original Timing Script Updated By (mostly optional) >Contributors to the production of the script. <td PlayResX PlayResY >The resolution of the script.
A comment line. A description of the script. The version of the file format. For ASS, this is v4.00+. Details regarding updates made to the script can be placed here. Where in the video will the script begin playback How collisions are managed. Possible values are: Normal - subtitles are stacked onto each other, and Reverse - subtitles are shifted to make way for new ones. The speed of the script. This value is a multiplier times 100 of the speed of the script playback. 0 - Smart wrapping, lines are evenly broken 1 - End of line word wrapping, hard breaks only. 2 - No word wrapping. Both line breaks allowed. 3 - Smart wrapping with lower lines wider.
Styles section
The Styles section defines different preset styles that can be used to adjust the appearance of individual lines in the script.
- The actual name of the section depends on the file version, for ASS this is [V4+ Styles].
- In the Events section, unrecognized styles are styled with the “Default” style.
- Unrecognized fonts are assigned to Arial - this may occur when the font is not installed in a target system.
The following is a sample Styles section:
{{c|directive|[V4+ Styles]}} {{c|key1|Format:}} Name{{c|key|,}} Fontname{{c|key|,}} Fontsize{{c|key|,}} PrimaryColour{{c|key|,}} SecondaryColour{{c|key|,}} OutlineColour{{c|key|,}} BackColour{{c|key|,}} Bold{{c|key|,}} Italic{{c|key|,}} Underline{{c|key|,}} StrikeOut{{c|key|,}} ScaleX{{c|key|,}} ScaleY{{c|key|,}} Spacing{{c|key|,}} Angle{{c|key|,}} BorderStyle{{c|key|,}} Outline{{c|key|,}} Shadow{{c|key|,}} Alignment{{c|key|,}} MarginL{{c|key|,}} MarginR{{c|key|,}} MarginV{{c|key|,}} Encoding {{c|key1|Style:}} Default{{c|key|,}}Arial{{c|key|,}}28{{c|key|,}}&H00FFFFFF{{c|key|,}}&H1EFFFFFF{{c|key|,}}&H0048001C{{c|key|,}}&H7F000000{{c|key|,}}-1{{c|key|,}}0{{c|key|,}}0{{c|key|,}}0{{c|key|,}}100{{c|key|,}}100{{c|key|,}}0{{c|key|,}}0{{c|key|,}}1{{c|key|,}}1.5{{c|key|,}}0.5{{c|key|,}}2{{c|key|,}}10{{c|key|,}}10{{c|key|,}}10{{c|key|,}}1
Format
Defines the format of subsequent Style lines. This is provided for backward-compatibility.
Style
Defines a style. The style is subsequently identified by its Name field.
Field | Description |
---|---|
Name | Identifies the style. Case-sensitive. |
Fontname | The subtitle font as identified by operating systems. |
Fontsize | The point size of the font. |
PrimaryColour | The font color. See the Data types section for information on how color values are represented. |
SecondaryColour | A secondary font color. This may be used in subtitle collisions (SSA) or as the first color displayed in the karaoke. |
OutlineColour | (SSA uses TertiaryColor) The color used to outline the font. |
BackColour | The color of the subtitle shadow. |
Bold | Text formatting that can be applied to the subtitle. Boolean value. (See Data types section.) |
Italic | |
Underline (v4+) | |
Strikeout (v4+) | |
ScaleX | (v4+) These are multipliers that can be used to scale the subtitle. |
ScaleY | |
Angle (v4+) | The rotation of the subtitle, in floating-point degrees. The rotation origin depends on the alignment of the subtitle. |
BorderStyle | 1 - Outline with shadow, 3 - Rendered with an opaque box. |
Outline | The width of the text outline, in pixels. |
Shadow | The depth of the text shadow, in pixels. |
Alignment | The alignment of the subtitle. See the Data types section. |
MarginL | Left margin. |
MarginR | Right margin. |
MarginV | Vertical margin. |
Encoding | A number representing the encoding to be used. |
Events section
This section contains the different objects to be displayed on screen, each having its corresponding properties, including timing.
The following are the fields available to ASS:
Field | Description | |
---|---|---|
Layer | An integer indicating the layer the subtitle is in. Subtitles having different layer numbers will be ignored during collision detection. Lower layer numbers are drawn first. | |
Start | The start time of the subtitle. See the Data types section. | |
End | The end time of the subtitle. | |
Style | The style to be used by the script. Styles are defined in the Styles section. | |
Name | The person who spoke the dialog. | |
MarginL | ||
MarginV | 4-digit margin override. | |
Effect | An effect or special directive associated with the line. Possible values are: | |
Scroll up;<y1 | 0>;<y2 | 0>;<delay(1-100)>[;fadeawayheight], |
Banner;<delay(1-100)>[;lefttoright(0 | 1)][;<fadeawaywidth], | |
Scroll down;<y1 | 0>;<y2 | 0>;<delay(1-100)>[;fadeawayheight] |
Text | The subtitle text. This is a special field in the sense that it must always be the last field, and can contain commas. |
The following are the Event section descriptors:
Descriptor | Description |
---|---|
Dialogue | A normal subtitle line. |
Comment | A commented subtitle line. These will not be displayed on screen. |
Picture | Displays a picture with the path specified in the Text field. |
Sound | Plays a WAV file with the path specified in the Text field. |
Movie | Plays an AVI file with the path specified in the Text field. |
Command | Executes the program with the path specified in the Text field. |