ffmpeg - Subtitles - ASS file syntax

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	Percent	Font scaling
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/

Table of Contents