ffmpeg:subtitles:ass_file_syntax
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.
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.
File Specification
SSA and ASS files are plain text files.
- ASS added Unicode support.
Scripts
See: https://aegisub.org/
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
NOTE:
- 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.
Styles
| 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 | 4-digit margin override. |
| MarginR | |
| MarginV | |
| 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. |
Style overrides
The ASS format has an extensive set of overrides that can be used to modify parts of or whole specific subtitles.
- All override codes except for \N, \n and \h must be enclosed in curly brackets ({}).
- Consecutive override codes may be placed inside a single pair of brackets.
- Override codes typically affect only the text succeeding it, but some codes modify the whole line.
- All override codes are preceded by a backslash (\) and may contain a parameter, if it must be provided.
- If an override code requires 2 or more parameters, these are placed inside parentheses and are comma-delimited.
The following is a list of ASS override codes.
| Override code | Parameters | Description |
|---|---|---|
| n | Soft line break - the line may break here. | |
| N | Hard / forced line break | |
| h | Non-breaking space | |
| b | 0 1 | Bold; off (0) or on (1) |
| i | 0 1 | Italic; off (0) or on (1) |
| u | 0 1 | Underline; off (0) or on (1) |
| s | 0 1 | Strikethrough; off (0) or on (1) |
| bord | width | Border |
| shad | depth | Shadow |
| be | blur amount | Outline blur (“blur edges”) |
| fn | Font name | Changes the font. |
| fs | size | Font size |
| fscx | Percent | Font scaling |
| fscy | ||
| fsp | pixels | Font spacing |
| fr/frz | degrees | Rotation around the x/y/z-axes. |
| frx | ||
| fry | ||
| fe | charset | Encoding number |
| c/1c | color | Primary / secondary / outline / shadow colour |
| 2c | ||
| 3c | ||
| 4c | ||
| alpha/1a | alpha value | Primary / secondary / outline / shadow transparency |
| 2a | ||
| 3a | ||
| 4a | ||
| an | alignment code | Alignment |
| k | duration (x0.01s) | The duration of time, in centiseconds, the succeeding text will be displayed, until the end of the line or the next k override code. This creates a karaoke effect. |
| kf/K | ||
| ko | ||
| q | integer | Wrapping style |
| r | [style] | Resets all previous override styles, applying the default style. To apply a different style, put it as a parameter. |
| t | ([<start>, <end>,][<accel>,]<styles>) | Applies a transition animation to the line. The start and end times are in milliseconds, and the styles can be any combination of the available animatable styles. |
| pos | (x,y) | Sets the position of the subtitle anchor, where 0,0 is the top-left corner. Note that the subtitle anchor also depends on the line's alignment. |
| move | (x1,y1,x2,y2[,t1, t2]) | Animates the subtitle position at the specified time or at the entirety of the subtitle time from point 1 to point 2. Time is in milliseconds, relative to the beginning of the subtitle. The subtitle anchor depends on the line's alignment. |
| org | (x,y) | Relocates the rotation origin of the subtitle. By default, the subtitle rotates about its anchor. |
| fade | a1,a2,t1,t2,t3,t4 | Creates a three-part fade animation. |
| fad | fade in duration, fade out duration | Sets a fade-in and fade-out duration. 0 will effectively disable the effect. |
| clip | x1,y1,x2,y2 | Clips a subtitle inside a rectangle. |
| clip | [scale,] drawing | Clips a subtitle inside a drawing. |
File attachment
Files can be attached to scripts and are stored as plain text. The method used is a form of UUEncoding.
Data types
- Color: Color values are expressed in hexadecimal BGR format as &HBBGGRR& or ABGR (with alpha channel) as &HAABBGGRR&.
- Transparency (alpha) can be expressed as &HAA&. Note that in the alpha channel, 00 is opaque and FF is transparent.
- Boolean values (Styles section): -1 is true, 0 is false.
- Alignment: Alignment values are based on the numeric keypad.
- 1 - bottom left, 2 - bottom center, 3 - bottom right, 4 - center left, 5 - center center, 6 - center right, 7 - top left, 8 - top center, 9 - top right.
- In addition to determining the position of the subtitle, this also determines the alignment of the text itself.
- Time: Time is expressed as h:mm:ss:xx (xx being hundredths of seconds).
- The hour can only be a single digit.
References
ffmpeg/subtitles/ass_file_syntax.txt · Last modified: 2024/12/30 23:49 by peter