3. Block Specifications - OpenAnime/ESL GitHub Wiki

Defines global metadata for the subtitle file. Exactly one meta block MUST be present.

Attributes:

• title (String, Optional): The title of the subtitle content.
  • Example: title = "My Awesome Subtitles"
• esl_version (String, Required): The version of the ESL specification this file adheres to. This helps parsers and renderers understand compatibility.
  • Example: esl_version = "1.1"
• target_fps (Number, Optional): The intended target frames-per-second for which time-based animations (like karaoke segment offsets or motion durations) were authored. This can help renderers make adjustments or ensure smooth playback if the actual rendering framerate differs.
  • Example: target_fps = 23.98
• resolution (Array of two Numbers [width, height], Required): The reference resolution inpixels.
  • Example: resolution = [1920, 1080]
• language (String, Optional): The IETF language tag (e.g., "en-US", "ja-JP").
  • Example: language = "en-US"
• default_style (String, Required): The name of a defined style block to be used for cues that do not specify a style attribute. Must refer to an existing style name.
  • Example: default_style = "base_style"
• scale_border_and_shadow (Boolean, Optional, Default: true): If true, border_width and shadow metrics are scaled relative to script resolution pixels, otherwise it is relative to the video resolution pixels (which means the border thickness will vary depending on the resolution of the video on which the subtitles are rendered.)
  • Example: scale_border_and_shadow = true

Example:

meta {
  title                   = "Show Title - Episode 1"
  esl_version             = "1.1"
  target_fps              = 23.98
  resolution              = [1280, 720]
  language                = "en-GB"
  default_style           = "default"
  scale_border_and_shadow = true
}

Defines a named set of visual styling properties for text. Zero or more style blocks can be defined in a file. The style_name label MUST be a unique string identifier for the style.

Attributes:

• extends (String, Optional): Name of another style block to inherit properties from.

  Inheritance is shallow: properties in the current style override those from the parent. Inheritance cycles are an error.

• font_family (String, Optional): Name of the font family. E.g., "Roboto".
• font_size (Number, Optional): Font size in logical pixels. E.g., 48.
• font_weight (String or Number, Optional): Font weight (e.g., "normal", "bold", "700").
• color (String, Optional): Text color (e.g., "#RRGGBB", "#RRGGBBAA"). E.g., "#FFFF00CC".
• align (String, Optional, Default: "bottom-center"): Nine-point alignment of the text block.
  • Allowed: "top-left", "top-center", "top-right", "middle-left", "middle-center", "middle-right", "bottom-left", "bottom-center", "bottom-right".
• border_width (Number, Optional): Width of text outline in logical pixels. E.g., 2.
• border_color (String, Optional): Color of text outline. E.g., "#000000".
• shadow (Array of [Number, Number, Number, String], Optional): Defines [offsetX, offsetY, blurRadius, color]. E.g., shadow = [2, 2, 3, "#00000080"].
• letter_spacing (Number, Optional): Additional character spacing in logical pixels. E.g., 1.5.
• line_height (Number, Optional): Line height multiplier or absolute logical pixels. E.g., 1.2 (multiplier) or 60 (pixels). (Behavior for absolute vs. multiplier should be clarified by implementers if ambiguous).

Example:

style "important_notice" {
  extends     = "default"
  font_family = "Impact"
  font_size   = 72
  color       = "#FFDD00"
  align       = "middle-center"
  shadow      = [3, 3, 5, "#000000"]
}

Defines a named, reusable animation effect, which can contain zero or more motion blocks. Each motion_name MUST be a unique string identifier. Transitions interpolate the animation from its current state to the target state defined by a newly activated motion.

Attributes:

• duration (Number, Required): Duration of the motion in milliseconds. E.g., 500.
• delay (Number, Optional, Default: 0): Delay before motion starts (ms), relative to its application (cue in/out).
• easing (String or Array of four Numbers [x1,y1,x2,y2], Optional, Default: "linear"): Easing function.
  • String: See Appendix A for predefined names. E.g., "quad-in-out".
  • Array: Cubic Bezier control points. E.g., [0.42, 0, 0.58, 1].
• opacity (Number, Optional): Animate opacity (0.0-1.0).
• position (Array of two Numbers [to_x, to_y], Optional): Animate position in logical pixels, additive to cue's current position. E.g., [0, 100].
• scale (Number, Optional): Animate scale (1.0 is normal). E.g., 0.7.
• rotate (Number, Optional): Animate rotation in degrees. E.g., 45.
• shear_x (Number, Optional): Animate horizontal shear factor. E.g., 0.5.
• shear_y (Number, Optional): Animate vertical shear factor. E.g., 0.5.

Example:

// other styles etc..

motion "gentle_fade_in" {
  duration = 1000
  easing   = "sine-out"
  opacity  = 1
}

cue {
  in        = 4500
  out       = 5000
  text      = "Hello world!"
  style     = "shout"
  opacity   = 0
  motion_in = ["gentle_fade_in"]
}

Defines a single timed text entry. Zero or more cue blocks can be defined.

Attributes:

• in (Number, Required): Start time in milliseconds. E.g., 1500.
• out (Number, Required): End time in milliseconds (MUST be > in). E.g., 5000.
• text (String or Array of KaraokeSegments, Required): The text content.
  • String: Plain text. May contain inline formatting tags (see Section 7). E.g., "Hello<br><b>World</b>!".
  • Array of KaraokeSegments: [["segmentText", offsetMs], ...]. offsetMs is relative to cue.in.
    • Example: text = [["Ka", 0], ["ra", 200], ["o", 350], ["ke!", 500]]
• opacity (Number, Optional): Opacity (0.0-1.0).
• style (String, Optional): Name of a defined style. Uses meta.default_style if omitted. E.g., style = "warning_style".
• align (String, Optional): Overrides style's align for this specific cue. Allowed values are the same as for style.align. E.g., align = "top-right".
• position (Array of two Numbers [x,y], Optional): Static base position in logical pixels. E.g., position = [100, 100].
• rotation (Number, Optional): Static rotation in degrees. E.g., rotation = -10.
• shear_x (Number, Optional): Static horizontal shear factor. E.g., shear_x = 0.1.
• shear_y (Number, Optional): Static vertical shear factor. E.g., shear_y = -0.1.
• margin_top (Number, Optional): Top margin in logical pixels. E.g., margin_top = 50.
• margin_right (Number, Optional): Right margin in logical pixels. E.g., margin_right = 50.
• margin_bottom (Number, Optional): Bottom margin in logical pixels. E.g., margin_bottom = 50.
• margin_left (Number, Optional): Left margin in logical pixels. E.g., margin_left = 50.
• motion_in (Array of Strings, Optional): List of motion_names for cue appearance.
  • Example: motion_in = ["fade_in", "fly_up_fast"]
• motion_out (Array of Strings, Optional): List of motion_names for cue disappearance. Timing is relative to cue.out (e.g., starts at cue.out - motion.duration + motion.delay).
  • Example: motion_out = ["fade_out_quick"]

Example:

cue {
  in          = 10000
  out         = 15000
  text        = "This is a test message!"
  style       = "important_notice"
  motion_in   = ["gentle_fade_in", "slide_from_bottom"]
}