User Tools

Site Tools


ffmpeg:subtitles:ass_file_syntax

This is an old revision of the document!


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.
  
  
FieldDescription
NameIdentifies the style. Case-sensitive.
FontnameThe subtitle font as identified by operating systems.
FontsizeThe point size of the font.
PrimaryColourThe font color. See the Data types section for information on how color values are represented.
SecondaryColourA 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.
BackColourThe color of the subtitle shadow.
BoldText 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.
BorderStyle1 - Outline with shadow, 3 - Rendered with an opaque box.
OutlineThe width of the text outline, in pixels.
ShadowThe depth of the text shadow, in pixels.
AlignmentThe alignment of the subtitle. See the Data types section.
MarginLLeft margin.
MarginRRight margin.
MarginVVertical margin.
EncodingA 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:

FieldDescription
LayerAn 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.
StartThe start time of the subtitle. See the Data types section.
EndThe end time of the subtitle.
StyleThe style to be used by the script. Styles are defined in the Styles section.
NameThe person who spoke the dialog.
MarginL
MarginV4-digit margin override.
EffectAn effect or special directive associated with the line. Possible values are:
Scroll up;<y10>;<y20>;<delay(1-100)>[;fadeawayheight],
Banner;<delay(1-100)>[;lefttoright(01)][;<fadeawaywidth],
Scroll down;<y10>;<y20>;<delay(1-100)>[;fadeawayheight]
TextThe 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:

DescriptorDescription
DialogueA normal subtitle line.
CommentA commented subtitle line. These will not be displayed on screen.
PictureDisplays a picture with the path specified in the Text field.
SoundPlays a WAV file with the path specified in the Text field.
MoviePlays an AVI file with the path specified in the Text field.
CommandExecutes the program with the path specified in the Text field.
ffmpeg/subtitles/ass_file_syntax.1735600233.txt.gz · Last modified: 2024/12/30 23:10 by peter

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki