Automation 4 Lua Subtitle file interface

From Aegisub Manual

This page describes the subtitle file interface use in Automation 4 Lua scripts to manipulate subtitle files.

There is one special object (the subtitles user data object) which has a number of functions, and a number of table formats defined.

Contents 1 The subtitles object 1.1 Retrieve number of lines 1.2 Read line 1.3 Append line 1.4 Insert line 1.5 Replace line 1.6 Delete line 1.7 Creating an undo point 2 Line data tables 2.1 clear class 2.2 comment class 2.3 head class 2.4 info class 2.5 format class 2.6 style class 2.7 dialogue class 2.8 unknown class

[edit] The subtitles object

Most (currently all) Automation 4 Lua feature functions are passed a subtitles object when called. This object is used to obtain data from and manipulate the subtitles the feature is being applied on.

A subtitles object can have two special properties depending on the context it is created for:

• Read-only - Some feature functions must not be allowed to modify the subtitle file at all. This includes for example macro validation functions and export filter configuration panel providers, because this would be outside user expectations.
• Allow undo points - Only some feature functions allow undo points to be set. Currently this is only macro processing functions. Due to the current (2.1/2.2) implementation of the Undo system in Aegisub, attempting to set undo points in any other context can cause data corruption, and thus is disallowed.

To allow the most flexibility, the subtitles object represents a complete ASS format file, line by line, including all meta-lines such as section headers, blank lines and semicolon comments.

The subtitles object supports the following operations:

• Retrieve number of lines
• Read line
• Append line (to end of file)
• Insert line (at arbitrary position in file)
• Replace line
• Delete line
• Create undo point

These operations are described in detail below. In all operation synopses and examples, subtitles is used for name of the subtitles object being operated on.

[edit] Retrieve number of lines

Synopsis:

• num_lines = #subtitles
• num_lines = subtitles.n

This operation retrieves the total number of lines in the subtitle file currently. This number only changes by using the other operations on the subtitle object, it cannot change spontaneously during the execution of a script.

• num_lines (number) - Number of lines in subtitle file.

The first syntax is the preferred one, per normal Lua 5.1 coding style.

[edit] Read line

Synopsis: line = subtitles[i]

This retrieves the indexed line and creates a new table object with data about it.

• line (table) - Table with data about the retrieved line. Will be nil if the line indexed is out of range.
• i (number) - Index into the subtitles file of the line number to retrieve. This is one-based, the first line in the file has index 1.

Aegisub internally stores the subtitle file as a linked list, which means that random access is slow, but sequential access is fast. While Automation 4 Lua presents the subtitles as if it was an array, it internally maintains a cursor used to optimise for sequential access. It is faster to access a line with an index close to the one you last accessed than to access one further away. It is always fast to access lines near the beginning or end of the file.

[edit] Append line

Synopsis:

• subtitles[0] = line
• subtitles.append(line)
• subtitles.append(line1, line2, ...)

Append one or more lines to the end of the subtitles file. In the first syntax, it is the number 0 (zero) used for index. (Setting index 0 causes an append operation.)

The third syntax supports appending multiple lines with one single operation.

• line (table) - The line object table to append to the subtitles file.

The latter function-call syntax is preferred for readability. The table index setting syntax is slightly faster.

Appending a line always runs in constant time, it does not move the cursor otherwise used to optimise sequential access.

[edit] Insert line

Synopsis:

• subtitles[-i] = line
• subtitles.insert(i, line)
• subtitles.insert(i, line1, line2, ...)

Inserts one or more lines into the subtitles file before the numbered line. In the first syntax, you supply a negative index, eg. to insert a line before line 5 you supply index -5 (negative 5.)

Inserting lines will move lines after the inserted lines to move down in index, such that old indexes will no longer be valid.

• i (number) - Index to insert before.
• line (table) - The line object table to insert into the subtitles file.

The latter function-call syntax is preferred for readability. The table index setting syntax is slightly faster.

Inserting lines uses the list cursor and will move it.

[edit] Replace line

Synopsis: subtitles[i] = line

Delete the indexed line and insert the given line in its stead.

• i (number) - The line index to replace at.
• line (table) - The line object table to replace with.

Replacing lines uses the list cursor and will move it.

[edit] Delete line

Synopsis:

• subtitles[i] = nil
• subtitles.delete(i)
• subtitles.delete(i1, i2, ...)
• subtitles.deleterange(first, last)

Remove one or more from the subtitles file. All lines after the deleted line(s) will move up to fill the deleted indexes, so old indexes will no longer be valid.

The third syntax supports deleting multiple indexed lines in one call. The indexes given must all be correct for the subtitle file's state before any lines are deleted.

The fourth syntax deletes a range of lines, both indexed lines inclusive.

• i (number) - Index of the line to delete.
• first, last (numbers) - Indices of the first and last lines of the range to delete.

Deleting lines uses the list cursor and will move it.

[edit] Creating an undo point

Synopsis: aegisub.set_undo_point(description)

You must always set an undo point at the end of running a macro, otherwise the Undo and Redo functions stop working correctly. You can set multiple undo points while running a single macro, but be aware that it might confuse the user. (You can try to see what happens if you don't set an undo point after changing the subtitle file, just don't release scripts without this to the public!)

Only available in macro processing functions, and doesn't make sense anywhere else either.

• description (string) - Text to appear in the Edit menu for the Undo and Redo items to describe the action that can be undone.

The behaviour of the undo system will change in the next major release of Aegisub, but that's far away. The exact way it will manifest in Automation 4 scripts can't be known yet.

This is not really a function in the subtitles object, but it is still closely tied to it.

[edit] Line data tables

When you read lines from the subtitle file object they will always be one of a few classes of lines, and when you write lines back to the subtitle file they must also follow the format of one of those classes.

The line data objects are regular Lua tables with some specific fields defined.

Here's a list of the different classes of lines:

• clear - blank line, there's nothing (or only whitespace) on the line
• comment - semicolon-comment, a line starting with a semicolon, usually ignored
• head - a section heading in the file, such as [Script Info]
• info - a key/value pair in the Script Info section of the file
• format - a Format line in the file, usually ignored
• style - a regular style definition line
• dialogue - a dialogue line, which may be a comment or not; these are the lines you see in the grid in Aegisub
• unknown - an unknown kind of line

There's three fields that always exist in all line data tables:

• class (string) - The name of the class of line this is, see the list above.
• raw (string) - The raw text of the line, from first to last character on the physical line.
• section (string) - Which section of the file the line belongs to. If the line is placed before the first section heading, this field is nil.

[edit] clear class

This class doesn't define any additional fields.

[edit] comment class

This class defines one additional field:

• text (string) - The text that follows the semicolon. Basically the same as the raw field with the first character chopped off.

[edit] head class

The head class doesn't define any additional fields, but the section field contains the name of the new section started.

[edit] info class

This class defines two additional fields:

• key (string) - The part of the line before the first colon, with leading and trailing spaces removed.
• value (string) - Everything after the first colon on the line, also with leading and trailing spaces removed.

[edit] format class

This class defines one additional field:

• fields (array table) - An array table of strings, the field names listed in the order they appear on the format line.

[edit] style class

This class defines a large number of additional fields. It's usually processed by the karaskel and modified a bit by that. See the karaskel.lua section on style tables for more information about this class.

[edit] dialogue class

This class defines a large number of additional fields. It's usually processed by the karaskel and has many calculated fields added by that. See the karaskel.lua section on dialogue line tables for more information on this class.

[edit] unknown class

No additional fields are defined by this class, due to its nature. This might be things like files embedded into the subtitles. You shouldn't try to work with these lines unless you really know what you're doing, deleting, modifying and inserting unknown lines has undefined consequences. (That means, even if it works today it might not work tomorrow or in the next version of Aegisub.)