RFC (Request For Comments)
Type: Standards Track (ASS v4.1)
Title: ASS v4.1 Extension [Variants]
Author: * Jesse Chan <jc@linux.com>
        * rcombs <rcombs@rcombs.me>
Comments-Summary: None
Comments-URI: https://github.com/libass/libass/issues/328
Status: Draft
Start Date: 2019-02-08
License: Public Domain (Copyright not applied)

This feature allows authors to provide multiple versions of their subtitles within a single track, letting the user choose which format to use. Common uses include dis/enabling honorifics, localized names, puns, and in-universe terms, and TL notes. This feature also allows authors to use alternative styles (StyleVariant), do whole file text replacements (Replacements) or whole event replacements (DialogueVariant) for different variants.

This feature may be enabled in a limited fashion in a backward compatible way by inserting:

[V4+ Extensions]
ExtensionVariants: 1

or enabled in full in a non-backward-compatible way by starting with:

[Script Info 4.1]

ASS parsers usually ignore unknown tags so it is backward compatible as long as we don't touch existing tags.

• Honorifics (hr)
• General localization (lo)
• TL notes (nt)
• Light typesetting (lt)

Using these types is not required, but it allows users to more easily set presets in their player configuration and the standard is expected to expand over time.

Format:

[Variants]
Variant: <title>,<description>,<code>,<default>

Example:

[Variants]
Variant: Honorifics,"-kun"\, "-chan"\, etc…,hr,off
Variant: Localization,Generally localizing terms,lo,on
Variant: Mahjong terms,"Suji", "Dora", etc…,lo/mj,default
Variant: Item names,"Godrobe", "Omnisilk",lo/it,on

As seen here, <code> may use path-style syntax. There are no limits on the length of variant codes, but keeping them short is likely convenient for content authors. Sub-variants must have a parent. Players should organize sub-variants into a tree-like menu. Using codes consistently allows the user to set defaults in their player. In this example, if the user has their player configured to disable "General localization" (lo), then when the file is loaded, Mahjong terms (lo/mj) will be disabled, but Item names (lo/it) will be enabled unless the user also has a lo/it preference set. These options must be adjustable both globally in the player configuration, and during playback per-file.

[Replacements]
Replacement: Layers (optional), Start (optional), End (optional), Styles (optional), Original Text, New Text

Examples:

Replacement: ,,,,Fuck,Hugs (Replace all "Fuck" with "Hugs")
Replacement: ,0:00:00.00,0:10:00.00,,Fuck,Hugs (Replace "Fuck" with "Hugs" during 0:00:00.00,0:10:00.00)
Replacement: ,,,Default,Fuck,Hugs (Replace all "Fuck" in Default style with "Hugs")
Replacement: ,,,-OPENING,Fuck,Hugs (Replace all "Fuck" with "Hugs" except those in OPENING style)
Replacement: ,,,<-OPENING, -ENDING>,Fuck,Hugs (Replace all "Fuck" with "Hugs" except those in OPENING or ENDING style)

Each variant SHALL only have EITHER whole style OR <...>-only replacements for a style.

StyleVariant: Variant, Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding

Parser should discard default Style and use StyleVariant for style if Variant specified in StyleVariant is selected.

StyleFontnameVariant: Variant, Name, Fontname
StyleFontsizeVariant: Variant, Name, Fontsize

Parser should use Name to match Style and replace elements in that Style if Variant specified is selected.

NOT backward compatible

Style: ..., FontDefault<hr=Font2><lo=Font2>, ...

Only one element variant SHALL be selected.

On multiple matches, later ones SHALL have higher precedence.

For example above, lo prevails when both hr and lo is selected.

Each variant SHALL only have EITHER whole event OR <...>-only replacements for an event.

MUST immediately follow the event to be replaced

DialogueVariant: Variant, Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text

Parser should discard the default event if the specified Variant is selected.

MUST be inserted right after event to be changed

Each variant SHALL only have one same type <...>-only replacement for an event.

DialogueTextVariant: Variant, Text
DialogueStyleVariant: Variant, Style
...

Parsing of variants of current event end when line does not start with:

Dialogue<...>Variant:

Parser should now replace elements of default event with elements specified in <...>Variant if Variant is selected.

NOT backward compatible

..., Could you come over here, <hr-Mr. >Nagoyama<hr+-san>?
..., Could you come over here, Mr. Nagoyama?<hr=Nagoyama-san?>
..., StyleDefault<hr=Style1><lo=Style2>, ...

Only one element variant SHALL be selected when "=" is used.

The later one SHALL have higher precedence. Non-text elements may only use "="

For example, above lo prevails when both hr and lo is selected.

Dialogue: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Empty (Empty text event)
DialogueTextVariant: Variant, Text (Replace Text (Empty) of above event with real Text)

RFC: Probably change syntax of DialogueVariant (Variant, ...) to (Mode, Variant, ...)?

Mode 0 -> Replace
Mode 1 -> Add