Aegisub/automation/v4-docs/subtitle-data.txt

Automation 4 Subtitle Data format and functions API

This file describes the API for retrieving and manipulating subtitle data in
Automation 4, as well as the data structures generated and accepted by these
APIs.

---

Subtitle Line table

A Subtitle Line table contains various information about a line in the
subtitle file being processed. There are several classes of subtitle lines,
which all have a few fields in common, but otherwise have different fields.


Common keys for all Subtitle Line classes:

class (string)
  The class of the Subtitle Line. Must be one of:
    "clear", (empty line)
    "comment", (semicolon-style comment line)
    "head", (section heading)
    "info", (key/value pair in Script Info section)
    "format", (line format definition)
    "style", (style definition line)
    "stylex", (style extension line, tentative AS5 feature)
    "dialogue", (dialogue line or dialogue-style comment line)
    "unknown" (unknown kind of line)
  Lines of the "unknown" class should never appear in well-formed subtitle
  scripts. They will usually be a result of a line being outside the section
  it belongs in.

raw (string)
  The raw text of the line.
  You should not change this field directly, since the data in it will never
  be used for generating lines in internal representation. It will, however,
  be updated from the remaining data in the line whenever it is required for
  one thing or another by an internal function.

section (string)
  The section this line is placed in. If it is placed before the first section
  heading, this field is nil.


Key defined only for the "comment" class:

text (string)
  The text of the comment line, ie. everything after the initial semicolon,
  including any spaces.


Key defined only for the "head" class:

No special keys are defined for this class, but the "section" field will be
the name of the new section started.


Keys defined only for the "info" class:

key (string)
  The "key" part of the line, ie. everything before the first colon.

value (string)
  The "value" part of the line, ie. everything after the first colon,
  discarding any leading whitespace.


Keys defined only for the "format" class:

fields (table)
  An Array Table of strings, each being the name of a field on the line.


Keys defined only for the "style" class:

name (string)
  Name of the style.

fontname (string)
  Name of the font used.

fontsize (number)
  Size of the font used, in pixels.

color1 (string)
color2 (string)
color3 (string)
color4 (string)
  The four colors for the style. (Fill, pre-karaoke fill, border, shadow)
  In VB hexadecimal, ie. "&HAABBGGRR&"

bold (boolean/number)
  The boldness/weight of the font. This will usually be a boolean, but it
  can be a number, in which case it must be one of 0, 100, 200, ..., 900.

italic (boolean)
underline (boolean)
strikeout (boolean)
  Other properties of the font.

scale_x (number)
scale_y (number)
  Scaling of the text, in percent.

spacing (number)
  Additional spacing between letters. Always integer.

angle (number)
  Rotation of the text on the Z axis in degrees.

borderstyle (number)
  1 = outline and drop shadow; 3 = opaque box.

outline (number)
  Width of the outline.

shadow (number)
  Distance between shadow and text.

align (number)
  Numpad alignment of the text.

margin_l (number)
margin_r (number)
margin_t (number)
margin_b (number)
  Left/right/top/bottom margins of the text in pixels.
  If using a format without support for separate top and bottom margins, the
  margin_t value will be used for vertical margin when converting back to
  textual representation.

encoding (number)
  Font encoding used for text. This follows the MS Windows font encoding
  constants.

relative_to (number)
  From STS.h: "0: window, 1: video, 2: undefined (~window)"

vertical (boolean)
  Whether vertical text semantics is used or not. (Tentative AS5 field.)


Keys defined only for the "stylex" class:

Remember that this class is only for the tentative AS5 format.

name (string)
  Name of the new style defined.

basename (string)
  Name of the style the new style is based on.

overrides (string)
  String of override tags defining the new style.


Keys only defined for the "dialogue" class:

comment (boolean)
  True if the line is a comment line, otherwise false.

layer (number)
  The layer the line is rendered in.

start_time (number)
end_time (number)
  Start/end time of the line in milliseconds.

style (string)
  Name of the style assigned to this line.

actor (string)
  Name of the actor performing this line.

margin_l (number)
margin_r (number)
margin_t (number)
margin_b (number)
  Left/right/top/bottom margins of the text in pixels.
  If any of these are zero, it's considered "not overriding".
  Same comment as for style lines applies.

effect (string)
  Effect to apply to the line.

userdata (string)
  Authoring-application defined data. (Tentative AS5 field.)

text (string)
  The text for this line.

---

Subtitle File user data object

The Subtitle File object is a user data object with some of the metatable
methods overridden to provide table-like access to the subtitle lines, as
well as some functions to modify the subtitles.

The following operations are supported.

n = #subs
n = subs.n
  Retrieve the number of lines in total.
  The first syntax is preferred.

line = subs[i]
  Retrieve line i, assuming 1 <= i <= n.

subs[i] = line
  Replace line i with new data.

subs[i] = nil
subs.delete(i[, i2, ...])
  Delete line i, pushing all following lines up an index. (Ie. by repeatedly
  deleting line 1 this way, the file will eventually end up empty.)
  The function syntax for this function can also take multiple line indexes,
  in which case it deletes each of those lines. All indexes are relative to
  the line numbering before the function is called.

subs.deleterange(a, b)
  Deletes all lines from index a to index b, both inclusive. If b < a,
  nothing is done.

subs[0] = line
subs.append(line[, line2, ...])
  Append one or more lines to a file.

subs[-i] = line
subs.insert(i, line[, line2, ...])
  Insert one or more lines before index i.


Effeciency concerns

Internally in Aegisub the subtitles are stored in a linked list, meaning
random access runs in O(n) time rather than O(1), as the interface presented
here could make it seem like.

Internally, a cursor to the last accessed item is kept, to make sequential or
mostly-sequential access to items faster, but totally random access will
still be somewhat ineffecient. Accessing items near the start or end of the
subtitle file can also be done reasonable fast however.

After an item-by-item deletion, the cursor will be placed at the item that
now has the lowest id specified for the operation.
After a range deletion operation, the cursor will be placed at the item
that now has the first id in the range of the operation.
After an insert operation, the cursor will be placed after the last inserted
item.
An append operation does not move the cursor.

---

Parsing tag data

This function uses the Aegisub SSA parser to split a string into override
blocks and text, and give separate access to each tag in override blocks.

function aegisub.parse_tag_data(text)

@text (string)
  The SSA-format string to parse.

Returns: A Parsed Tag Data table.

---

Recreating a line from tag data

This function takes a Parsed Tag Data table and creates an SSA string from it.

function aegisub.unparse_tag_data(tagdata)

@tagdata (table)
  The Parsed Tag Data table to "unparse".

Returns: A string, being the "unparsed" data.

---

Parsing karaoke data

Tihs function uses the Aegisub SSA parser to split a string into karaoke
syllables with additional calculated information added.

function aegisub.parse_karaoke_data(text)

@text (string)
  The SSA-format string to parse.

Returns: A Parsed Karaoke Data table.

---

Parsed Tag Data table

The Parsed Tag Data table is an Array Table containing a number of Parsed Line
Block tables.


Parsed Line Block table

A Parsed Line Block describes part of a line. (See ass_dialogue.cpp:70 for a
more complete description of this.
There are several classes of Parsed Line Block tables, which have slightly
varying fields.


Base Parsed Line Block table class

class (string)
  One of:
    "plain",
    "override",
    "drawing"


"plain" and "drawing" Parsed Line Block table classes

text (string)
  The text contained in this block.


"override" Parsed Line Block table class

This class doesn't have any new, specifically named fields. It does, however,
have multiple integer indexed fields, ie. acts as an Array Table.
Each of these indexes refer to a table of type Parsed Override Tag.


Parsed Override Tag table

This table describes a single override-tag in an SSA line.

valid (boolean)
  Whether this tag was parsed as a valid tag, or is just used for representing
  junk in the middle of the line.

name (string)
  Name of the tag, including leading backslash character. (In the case of
  invalid tags, the leading backslash might not be present.)

paran (boolean)
  Whether this tag has parantheses in its textual representation.

params (table)
  This is an Array Table containing the parameters for this tag. It will
  always have the maximum number of entries that can be supported by the tag,
  but in case of omitted parameters, the parameters omitted will have 'false'
  for value in this table.

---

Parsed Karaoke Data table

The Parsed Karaoke Data table is simply an Array Table of Karaoke Syllable
Data tables. However, the Parsed Karaoke Data table will always have one more
item than its count shows, which is numbered 0 (zero). This item contains
everything before the first syllable.


Karaoke Syllable Data table

This table contains information about a single karaoke syllable.

duration (number)
  Duration of the syllable in milliseconds.
  (In case of syllable zero, this is always zero. Also zero for "kt" tags.)

start_time (number)
end_time (number)
  Start and end times of the syllable, relative to the start of the line,
  given in milliseconds.
  (While these can technically easily be calculated from the duration data,
  they are too convenient to leave out from the standard interface.)

tag (string)
  The tag used for marking up this syllable. Usually one of:
    "k", "K", "kf", "ko", "kt"
  (In case of syllable zero, this is always the empty string.)

text (string)
  The text of the syllable, including all additional override tags.

text_stripped (string)
  The text of the syllable, stripped of any override tags.

---

Setting undo points

This function can only be used in macro features, it will have no effect when
used in any other feature.
It sets an undo point.

You should always call this function after every operation that must be
undoable as a separate step. It is considered very bad practice to modify
the subtitles in a macro without setting at least one undo-point, which must
be at the end.

An undo step can consist of any number of subtitle operations. (Ie. inserting,
deleting and replacing subtitle file lines.)

Furthermore, this function also marks the subtitles as "modified". No other
function does this.

function aegisub.set_undo_point(description)

@description (string)
  A short description of the operation that will be undone, if this undo-point
  is used.

Returns: nothing.

---