====== 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:

<code>
{{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
</code>

<WRAP info>
**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.

</WRAP>

----

===== 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:|
|:::|<nowiki>Scroll up;<y1|0>;<y2|0>;<delay(1-100)>[;fadeawayheight],</nowiki>|
|:::|<nowiki>Banner;<delay(1-100)>[;lefttoright(0|1)][;<fadeawaywidth],</nowiki>|
|:::|<nowiki>Scroll down;<y1|0>;<y2|0>;<delay(1-100)>[;fadeawayheight]</nowiki>|
|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 =====

https://wiki.multimedia.cx/index.php?title=SubStation_Alpha

https://aegisub.org/

https://validator.subtitledpro.com/