mirror of https://github.com/odrling/Aegisub
Niels Martin Hansen
parent
b39451823e
commit
ef6ef4c603
|
|
@ -0,0 +1,19 @@
|
||||||
|
-- Automation 4 demo script
|
||||||
|
-- Macro that adds \be1 tags in front of every selected line
|
||||||
|
|
||||||
|
script_name = "Add edgeblur macro"
|
||||||
|
script_description = "A testmacro showing how to do simple line modification in Automation 4"
|
||||||
|
script_author = "Niels Martin Hansen"
|
||||||
|
script_version = "1"
|
||||||
|
|
||||||
|
|
||||||
|
function add_edgeblur(subtitles, selected_lines, active_line)
|
||||||
|
for z, i in ipairs(selected_lines) do
|
||||||
|
local l = subtitles[i]
|
||||||
|
l.text = "{\\be1}" .. l.text
|
||||||
|
subtitles[i] = l
|
||||||
|
end
|
||||||
|
aegisub.set_undo_point("Add edgeblur")
|
||||||
|
end
|
||||||
|
|
||||||
|
aegisub.register_macro("Add edgeblur", "Adds \be1 tags to all selected lines", "edit", add_edgeblur)
|
||||||
|
|
@ -0,0 +1,367 @@
|
||||||
|
Automation 4 Basic Interface
|
||||||
|
|
||||||
|
This document described the basic functions needed to define an Automation 4
|
||||||
|
script. This covers Feature registration and the prototypes of functions used
|
||||||
|
to implement the various features.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Macro Registation Function
|
||||||
|
|
||||||
|
This is a function called from top-level of an Automation script to register
|
||||||
|
a new Macro Feature.
|
||||||
|
|
||||||
|
function aegisub.register_macro(
|
||||||
|
name,
|
||||||
|
description,
|
||||||
|
menu,
|
||||||
|
processing_function,
|
||||||
|
validation_function)
|
||||||
|
|
||||||
|
@name (string)
|
||||||
|
The displayed name of the menu item this macro will generate.
|
||||||
|
|
||||||
|
@description (string)
|
||||||
|
A longer description of the function of this macro. This will appear
|
||||||
|
on the status bar when hovering over the menu item.
|
||||||
|
|
||||||
|
@menu (string)
|
||||||
|
The menu this macro will appear in. Must be one of:
|
||||||
|
o "edit"
|
||||||
|
o "video"
|
||||||
|
o "audio"
|
||||||
|
o "tools"
|
||||||
|
o "right" (the subtitles grid right-click menu)
|
||||||
|
The menu chosen should be relevant to the function of the macro.
|
||||||
|
|
||||||
|
@processing_function (function)
|
||||||
|
The actual function called for the macro execution.
|
||||||
|
This function must be an instance of the Macro Processing Function
|
||||||
|
described below.
|
||||||
|
|
||||||
|
@validation_function (function)
|
||||||
|
Optional. A function called when it is to be determined whether the
|
||||||
|
macro can act on the current subtitles.
|
||||||
|
This function, if provided, must execute very quickly to avoid lag
|
||||||
|
in the GUI.
|
||||||
|
This function must be an instance of the Macro Validation Function
|
||||||
|
described below.
|
||||||
|
|
||||||
|
Returns: nothing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Filter Registration Function
|
||||||
|
|
||||||
|
This is a function called from top level of an Automation script to register
|
||||||
|
a new Export Filter Feature.
|
||||||
|
|
||||||
|
function aegisub.register_filter(
|
||||||
|
name,
|
||||||
|
description,
|
||||||
|
priority,
|
||||||
|
processing_function,
|
||||||
|
options_window_provider)
|
||||||
|
|
||||||
|
@name (string)
|
||||||
|
The name of the filter, as presented to the user.
|
||||||
|
|
||||||
|
@description (string)
|
||||||
|
A longer description of the filter presented to the user.
|
||||||
|
|
||||||
|
@priority (number)
|
||||||
|
A number determining the default order the enabled filters will be
|
||||||
|
processed. The order can be overridden by the user.
|
||||||
|
Priorities of some built-in filters:
|
||||||
|
o Clean Script Info = 0
|
||||||
|
o Fix Styles = -5000
|
||||||
|
o Transform Framerate = 1000
|
||||||
|
Filters with higher priority will be executed earlier by default.
|
||||||
|
|
||||||
|
@processing_function (function)
|
||||||
|
The function called to do the actual filter processing.
|
||||||
|
This function must be an instance of the Filter Processing Function
|
||||||
|
described below.
|
||||||
|
|
||||||
|
@options_window_provider (function)
|
||||||
|
Optional. A function providing a dialog template for setting options
|
||||||
|
prior to filter processing.
|
||||||
|
This function must be an instance of the Filter Options Window Provider
|
||||||
|
function described below.
|
||||||
|
|
||||||
|
Returns: nothing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Format Reader Registration
|
||||||
|
|
||||||
|
This is a function called from top level in an Automation script to register
|
||||||
|
a new File Format Reader Feature.
|
||||||
|
|
||||||
|
function aegisub.register_reader(
|
||||||
|
name,
|
||||||
|
extension,
|
||||||
|
processing_function)
|
||||||
|
|
||||||
|
@name (string)
|
||||||
|
The name of the file format.
|
||||||
|
|
||||||
|
@extension (string)
|
||||||
|
The file extension usually given to this file format. This must not
|
||||||
|
include any wildcards. (Ie. extension could be "srt", "sub", "ssa" and
|
||||||
|
so on.)
|
||||||
|
|
||||||
|
@processing_function (function)
|
||||||
|
The function called to do the actual file import.
|
||||||
|
This function must be an instance of the Format Reader Function described
|
||||||
|
below.
|
||||||
|
|
||||||
|
Returns: nothing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Format Writer Registration
|
||||||
|
|
||||||
|
This is a function called from top level in an Automation script to register
|
||||||
|
a new File Format Writer Feature.
|
||||||
|
|
||||||
|
function aegisub.register_writer(
|
||||||
|
name,
|
||||||
|
extension,
|
||||||
|
processing_function)
|
||||||
|
|
||||||
|
@name (string)
|
||||||
|
Name of the file format, as presented to the user.
|
||||||
|
|
||||||
|
@extension (string)
|
||||||
|
The usual file extension given to this file format. This is automatically
|
||||||
|
be attached to the file name on export, unless the user chooses to
|
||||||
|
override it.
|
||||||
|
|
||||||
|
@processing_function (function)
|
||||||
|
The function doing the actual file export.
|
||||||
|
This function must be an instance of the Format Writer Function described
|
||||||
|
below.
|
||||||
|
|
||||||
|
Returns: nothing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Macro Processing Function
|
||||||
|
|
||||||
|
This function is called by Aegisub to execute a macro.
|
||||||
|
|
||||||
|
function process_macro(
|
||||||
|
subtitles,
|
||||||
|
selected_lines,
|
||||||
|
active_line)
|
||||||
|
|
||||||
|
The name of the function is script-defined. (It doesn't have to be
|
||||||
|
process_macro.)
|
||||||
|
|
||||||
|
@subtitles (user data)
|
||||||
|
A Subtitles Object, that can be used to retrieve information about the
|
||||||
|
subtitle file the macro is being applied on.
|
||||||
|
|
||||||
|
@selected_lines (table)
|
||||||
|
An Array Table of numbers, each entry being an index into the file
|
||||||
|
represented by @subtitles. Each of the entries in this table describe that
|
||||||
|
a line is marked as selected by the user.
|
||||||
|
|
||||||
|
@active_line (number)
|
||||||
|
Index of the currently active line in the subtitle file.
|
||||||
|
|
||||||
|
Returns: nothing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Macro Validation Function
|
||||||
|
|
||||||
|
This function is called by Aegisub to determine whether a macro can be applied
|
||||||
|
to the current state of the subtitles and selection.
|
||||||
|
|
||||||
|
This function needs to execute very fast, since it may be called for several
|
||||||
|
macros whenever a menu is opened. It is suggested not to use @subtitles at all
|
||||||
|
in this function.
|
||||||
|
|
||||||
|
This function does not have to be defined. If it's undefined, it's taken as if
|
||||||
|
it always returned true.
|
||||||
|
|
||||||
|
function validate_macro(
|
||||||
|
subtitles,
|
||||||
|
selected_lines,
|
||||||
|
active_line)
|
||||||
|
|
||||||
|
The name of the function is script-defined. (It doesn't have to be
|
||||||
|
validate_macro.)
|
||||||
|
|
||||||
|
@subtitles (user data)
|
||||||
|
A Subtitles Object, that can be used to retrieve information about the
|
||||||
|
subtitle file the macro is to be be applied on.
|
||||||
|
|
||||||
|
@selected_lines (table)
|
||||||
|
An Array Table of numbers, each entry being an index into the file
|
||||||
|
represented by @subtitles. Each of the entries in this table describe that
|
||||||
|
a line is marked as selected by the user.
|
||||||
|
|
||||||
|
@active_line (number)
|
||||||
|
Index of the currently active line in the subtitle file.
|
||||||
|
|
||||||
|
Returns: Boolean.
|
||||||
|
true is the macro can be applied to the current state of the subtitles,
|
||||||
|
false if not.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Filter Processing Function
|
||||||
|
|
||||||
|
This function is called by Aegisub to filter the subtitles during an export
|
||||||
|
operation.
|
||||||
|
|
||||||
|
function process_filter(
|
||||||
|
subtitles,
|
||||||
|
config)
|
||||||
|
|
||||||
|
The name of the function is script-defined. (It doesn't have to be
|
||||||
|
process_filter.)
|
||||||
|
|
||||||
|
@subtitles (user data)
|
||||||
|
A Subtitles Object, that can be used to retrieve information about the
|
||||||
|
subtitle file the filter is being applied on.
|
||||||
|
|
||||||
|
@config (table)
|
||||||
|
A Dialog Result table representing the options the user selected for the
|
||||||
|
filter before starting the export operation. The fields present in this
|
||||||
|
table are defined by the dialog provided by the Filter Options Window
|
||||||
|
Provider function.
|
||||||
|
|
||||||
|
Returns: nothing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Filter Options Window Provider function
|
||||||
|
|
||||||
|
This function is called by Aegisub to get a Dialog Window definition to prompt
|
||||||
|
the user for input before an export operation.
|
||||||
|
The data input into the dialog returned by this function are automatically
|
||||||
|
stored into the original subtitle file when an export operation is started.
|
||||||
|
|
||||||
|
function filter_options_dialog(
|
||||||
|
subtitles,
|
||||||
|
stored_options)
|
||||||
|
|
||||||
|
The name of the function is script-defined. (It doesn't have to be
|
||||||
|
filter_options_dialog.)
|
||||||
|
|
||||||
|
@subtitles (user data)
|
||||||
|
A Subtitles Object, that can be used to retrieve information about the
|
||||||
|
subtitle file the filter is to be applied on.
|
||||||
|
|
||||||
|
@stored_options (table)
|
||||||
|
The currently stored options for this export filter. The keys in this table
|
||||||
|
are the option names, and the values are the values stored for those options.
|
||||||
|
|
||||||
|
Returns: A Dialog Window table.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Format Reader Function
|
||||||
|
|
||||||
|
This function is called by Aegisub to import a file from a foreign file
|
||||||
|
format.
|
||||||
|
|
||||||
|
function read_format(
|
||||||
|
input_file,
|
||||||
|
output_subs)
|
||||||
|
|
||||||
|
The name of the function is script-defined. (It doesn't have to be
|
||||||
|
read_format.)
|
||||||
|
|
||||||
|
@input_file (user data)
|
||||||
|
An Input File Stream, representing the file selected for import.
|
||||||
|
|
||||||
|
@output_subs (user data)
|
||||||
|
An empty Subtitles Object the imported data should be added to.
|
||||||
|
|
||||||
|
Returns: Boolean.
|
||||||
|
True if the import succeeded, false if it failed.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Format Writer Function
|
||||||
|
|
||||||
|
This function is called by Aegisub to export a file to a foreign file format.
|
||||||
|
|
||||||
|
function write_format(
|
||||||
|
input_subs,
|
||||||
|
output_file)
|
||||||
|
|
||||||
|
The name of the function is script-defined. (It doesn't have to be
|
||||||
|
write_format.)
|
||||||
|
|
||||||
|
@input_subs (user data)
|
||||||
|
A Subtitles Object representing the subtitles to be exported.
|
||||||
|
|
||||||
|
@output_file (user data)
|
||||||
|
An Ouput File Stream, representing the file the exported data should be
|
||||||
|
written to.
|
||||||
|
|
||||||
|
Returns: Boolean.
|
||||||
|
True if the export succeeded, false if it failed.
|
||||||
|
If this function returns false, the output file is deleted from disk.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Script information globals
|
||||||
|
|
||||||
|
These are a series of global variables, the script author can set. They are
|
||||||
|
purely informational, and won't have any actual influence on how the script
|
||||||
|
is treated.
|
||||||
|
|
||||||
|
None of these are required, but it is recommended to provide them.
|
||||||
|
|
||||||
|
These should never be present in include files.
|
||||||
|
|
||||||
|
script_name (string)
|
||||||
|
A short, descriptive name for the script, used for presenting it to the
|
||||||
|
user in the UI.
|
||||||
|
|
||||||
|
script_description (string)
|
||||||
|
A longer description of the purpose of the script, presented to the user
|
||||||
|
in the UI.
|
||||||
|
|
||||||
|
script_author (string)
|
||||||
|
Name(s) of the author(s) of the script.
|
||||||
|
|
||||||
|
script_version (string)
|
||||||
|
Version number of the script.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Including other scripts
|
||||||
|
|
||||||
|
For implementation reasons (and partially compatibility reasons), the Lua
|
||||||
|
built-in dofile() and loadfile() functions are removed, and a custom include()
|
||||||
|
function is provided instead.
|
||||||
|
|
||||||
|
This function behaves almost the same as dofile(), except that it doesn't
|
||||||
|
support reading from stdin (no such thing exists/is supposed to exist for
|
||||||
|
Aegisub) and it follows some special search rules along a path.
|
||||||
|
|
||||||
|
function include(filename)
|
||||||
|
|
||||||
|
@filename (string)
|
||||||
|
The relative path to the script to include.
|
||||||
|
|
||||||
|
Returns: Any return-values of the included script.
|
||||||
|
|
||||||
|
File search rules:
|
||||||
|
1. If there are no path-components in the filename (ie. just a filename),
|
||||||
|
the directory of the original script is searched first. Afterwards, the
|
||||||
|
search path specified in the Aegisub configuration file is searched.
|
||||||
|
2. If the filename contains path components, it is only searched relative
|
||||||
|
to the location of the original script file.
|
||||||
|
3. Absolute paths are not mangled in any way. Using absolute paths is
|
||||||
|
discouraged. (Absolute paths were disallowed in Automation 3.)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
@ -0,0 +1,180 @@
|
||||||
|
Automation 4 Configuration Dialog interface
|
||||||
|
|
||||||
|
This file describes the functions and data structures used for the
|
||||||
|
Configuration Dialog functionality in Automation 4.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Dialog Control table format
|
||||||
|
|
||||||
|
A Dialog Control table describes a single control in a configuration dialog,
|
||||||
|
which can display information to the user and allow them to change it.
|
||||||
|
|
||||||
|
There are a number of different classes of controls, and the keys a Dialog
|
||||||
|
Control table must contain depends on the control class.
|
||||||
|
|
||||||
|
|
||||||
|
Common keys for all control classes:
|
||||||
|
|
||||||
|
class (string)
|
||||||
|
Defines which class this control has. Must be one of:
|
||||||
|
"label",
|
||||||
|
"edit", "intedit", "floatedit", "textbox",
|
||||||
|
"dropdown",
|
||||||
|
"checkbox",
|
||||||
|
"color", "coloralpha", "alpha"
|
||||||
|
|
||||||
|
x (number)
|
||||||
|
y (number)
|
||||||
|
width (number)
|
||||||
|
height (number)
|
||||||
|
Determines the position and size of the control in the dialog. These values
|
||||||
|
are used to create a grid containing the controls. They should all be
|
||||||
|
integer. The top left corner is x,y=0,0.
|
||||||
|
If any of width and height are set to zero or less, it will be set to one
|
||||||
|
instead.
|
||||||
|
|
||||||
|
|
||||||
|
Keys defined for all classes except "label":
|
||||||
|
|
||||||
|
hint (string)
|
||||||
|
A string displayed to the user as tooltip, when hovering over the control.
|
||||||
|
|
||||||
|
name (string)
|
||||||
|
A name that uniquely identifies the control. This is recommended to be a
|
||||||
|
string easily used as an identifier in Lua, since it will be used to access
|
||||||
|
the value input into the control.
|
||||||
|
|
||||||
|
|
||||||
|
Keys defined only for "label" and "checkbox" classes:
|
||||||
|
|
||||||
|
label (string)
|
||||||
|
The text displayed to the user on the control.
|
||||||
|
|
||||||
|
|
||||||
|
Key defined only for the "edit" and "textbox" classes:
|
||||||
|
|
||||||
|
text (string)
|
||||||
|
The contents of the control when the dialog is first displayed.
|
||||||
|
This can contain newlines if the control is of the "textbox" class.
|
||||||
|
|
||||||
|
|
||||||
|
Keys defined only for the "intedit" and "floatedit" classes:
|
||||||
|
|
||||||
|
value (number)
|
||||||
|
The value in the control when the dialog is first displayed. For the
|
||||||
|
"intedit" class, if this is a non-integer number it will be truncated.
|
||||||
|
|
||||||
|
min (number or nil)
|
||||||
|
max (number or nil)
|
||||||
|
If one of these are nil, the other must also be nil. (Ie. undefined.)
|
||||||
|
If both are present, the control gets a spin button, the user can click to
|
||||||
|
update the value of the control. The user won't be able to close the
|
||||||
|
dialog if the value is outside the range between "min" and "max".
|
||||||
|
|
||||||
|
|
||||||
|
Keys defined only for the "dropdown" class:
|
||||||
|
|
||||||
|
items (table)
|
||||||
|
This is an Array Table containing only strings. They are used for the
|
||||||
|
options displayed to the user in the dropdown box.
|
||||||
|
All strings in the array table should be unique. (There is not way to
|
||||||
|
distinguish non-unique strings from each other.)
|
||||||
|
|
||||||
|
value (string)
|
||||||
|
Determines which item is selected when the dialog id first displayed. If
|
||||||
|
this is not one of the items specified, no item is selected. This is case-
|
||||||
|
sensitive.
|
||||||
|
|
||||||
|
|
||||||
|
Key defined only for the "checkbox" class:
|
||||||
|
|
||||||
|
value (boolean)
|
||||||
|
Determines whether the checkbox is checked or not when the dialog is first
|
||||||
|
displayed.
|
||||||
|
|
||||||
|
|
||||||
|
Keys defined only for the "color", "coloralpha" and "alpha" classes:
|
||||||
|
|
||||||
|
value (string)
|
||||||
|
A color value in VB or HTML hexadecimal format.
|
||||||
|
For the "color" class, this should be a 3 byte value, ie. "#RRGGBB".
|
||||||
|
For the "coloralpha" class, this should be a 4 byte value, ie. "#RRGGBBAA".
|
||||||
|
For the "alpha" class, this should be a one-byte value, ie. "#AA".
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Dialog Definition table format
|
||||||
|
|
||||||
|
The Dialog Definition table is simply an Array Table of Dialog Control tables.
|
||||||
|
|
||||||
|
Note, however, that while the visual ordering of the controls are decided
|
||||||
|
entirely by the "x", "y", "width" and "height" of the controls, the
|
||||||
|
"tab order" of the controls is decided by their ordering in the Dialog
|
||||||
|
Definition table.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Dialog Result table format
|
||||||
|
|
||||||
|
A Dialog Result table contains the user input from a configuration dialog.
|
||||||
|
|
||||||
|
The control "name" properties are used as keys in this table.
|
||||||
|
|
||||||
|
The type of the value for each entry in the table depends on the class of the
|
||||||
|
control. The control classes map to types in the following manner:
|
||||||
|
|
||||||
|
"label"
|
||||||
|
None. Since the user cannot change a label, they do not produce any value.
|
||||||
|
|
||||||
|
"edit", "textbox"
|
||||||
|
String. The text input in the box. This can contain newlines in the case of
|
||||||
|
a "textbox" class control.
|
||||||
|
|
||||||
|
"intedit", "floatedit"
|
||||||
|
Number. The number input into the control, guaranteed to be within the
|
||||||
|
constraints set by the class (integer or float) and the min/max properties.
|
||||||
|
|
||||||
|
"dropdown"
|
||||||
|
String. The case-exact text of the selected item.
|
||||||
|
|
||||||
|
"checkbox",
|
||||||
|
Boolean. The checked-state of the checkbox.
|
||||||
|
|
||||||
|
"color", "coloralpha", "alpha"
|
||||||
|
String. A VB colorstring following the same scheme as for setting the
|
||||||
|
"value" property.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Display Configuration Dialog function
|
||||||
|
|
||||||
|
This function displays a configuration dialog to the user and waits for it to
|
||||||
|
close. It then returns whether the user accepted or cancelled the dialog, and
|
||||||
|
what values were input.
|
||||||
|
|
||||||
|
function aegisub.dialog.display(dialog, buttons)
|
||||||
|
|
||||||
|
@dialog (table)
|
||||||
|
A Dialog Definition table containing the controls to be in the dialog.
|
||||||
|
|
||||||
|
@buttons (table)
|
||||||
|
Optional. This is an Array Table of strings defining the buttons that appear
|
||||||
|
in the dialog. If this is left out, empty or is otherwise not a table, the
|
||||||
|
standard Ok and Cancel buttons appear.
|
||||||
|
The strings in this Array Table are used as labels on the buttons, and for
|
||||||
|
identifying them in the return values of the function.
|
||||||
|
|
||||||
|
Returns: Two values.
|
||||||
|
1. Boolean or string.
|
||||||
|
If no custom buttons were specified, this is a boolean telling whether Ok
|
||||||
|
(true) or Cancel (false) were clicked in the dialog.
|
||||||
|
If custom buttons were specified, this is the text on the button clicked
|
||||||
|
by the user.
|
||||||
|
Even if custom buttons were specified, this can still be boolean false if
|
||||||
|
the user closes the dialog without pressing any button.
|
||||||
|
2. Table.
|
||||||
|
The Dialog Result table corresponding to the values the user input in the
|
||||||
|
dialog.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
@ -0,0 +1,214 @@
|
||||||
|
Automation 4 File Stream interface
|
||||||
|
|
||||||
|
This file describes the interface used for reading and writing files in
|
||||||
|
Automation 4. This includes text encoding conversion routines.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
About encodings
|
||||||
|
|
||||||
|
All file streams always have a text encoding. The default encoding is
|
||||||
|
determined by the user, before the import/export operation is started.
|
||||||
|
|
||||||
|
All string operations on a stream follow the current encoding. You can
|
||||||
|
change the encoding during reading/writing, and the change will only take
|
||||||
|
effect from that point on.
|
||||||
|
|
||||||
|
You can perform binary IO by setting the encoding to 'binary' and using
|
||||||
|
strings consisting only of codepoints 0 to 255.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Output File Stream user data object
|
||||||
|
|
||||||
|
This object is passed to functions operating on an Output File Stream.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Input File Stream user data object
|
||||||
|
|
||||||
|
This object is passed to functions operating on an Input File Stream.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Getting text encoding
|
||||||
|
|
||||||
|
This function returns a string describing the current text encoding used for
|
||||||
|
a file stream.
|
||||||
|
|
||||||
|
function aegisub.fstream.get_encoding(stream)
|
||||||
|
|
||||||
|
@stream (user data)
|
||||||
|
The Input File Stream or Output File Stream to get the encoding for.
|
||||||
|
|
||||||
|
Returns: String describing the encoding. This string can be used for setting
|
||||||
|
the encoding later.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Setting text encoding
|
||||||
|
|
||||||
|
This function changes the current text encoding used for a file stream.
|
||||||
|
|
||||||
|
function aegisub.fstream.set_encoding(stream, encoding)
|
||||||
|
|
||||||
|
@stream (user data)
|
||||||
|
The Input File Stream or Output File Stream to change the encoding for.
|
||||||
|
|
||||||
|
@encoding (string)
|
||||||
|
The new encoding to use.
|
||||||
|
|
||||||
|
Returns: String describing the old encoding.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
File Pointer operations
|
||||||
|
|
||||||
|
function aegisub.fstream.tell(stream)
|
||||||
|
|
||||||
|
@stream (user data)
|
||||||
|
The Input File Stream or Output File Stream get position of.
|
||||||
|
|
||||||
|
Returns: Number, the number of bytes since the beginning of the file.
|
||||||
|
|
||||||
|
|
||||||
|
function aegisub.fstream.seek(stream, length)
|
||||||
|
|
||||||
|
@stream (user data)
|
||||||
|
The Input File Stream or Output File Stream to seek in.
|
||||||
|
|
||||||
|
@length (number)
|
||||||
|
Number of bytes to skip. This can be negative.
|
||||||
|
You can only seek backwards in an Output File Stream, and doing so truncates
|
||||||
|
the file.
|
||||||
|
|
||||||
|
Returns: nothing.
|
||||||
|
|
||||||
|
|
||||||
|
function aegisub.fstream.reset(stream)
|
||||||
|
|
||||||
|
Resets the file pointer to the start of the file. Truncates an Output File
|
||||||
|
Stream to zero bytes.
|
||||||
|
|
||||||
|
@stream (user data)
|
||||||
|
The Input File Stream or Output File Stream to seek in.
|
||||||
|
|
||||||
|
Returns: nothing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Reading text
|
||||||
|
|
||||||
|
All these functions assume the file is in the current encoding specified.
|
||||||
|
|
||||||
|
|
||||||
|
function aegisub.fstream.skip_utf_bom(stream, change_encoding)
|
||||||
|
|
||||||
|
This function has undefined behaviour unless called as the first
|
||||||
|
read-operation on the stream.
|
||||||
|
|
||||||
|
It detects whether the file stream starts with an UTF Byte Order Mark, skips
|
||||||
|
the number of bytes used by that BOM, and optionally changes the current file
|
||||||
|
encoding to match the detected BOM.
|
||||||
|
|
||||||
|
@stream (user data)
|
||||||
|
The Input File Stream to read from.
|
||||||
|
|
||||||
|
@change_encoding (boolean)
|
||||||
|
If true, change encoding to match the detected BOM.
|
||||||
|
|
||||||
|
Returns: Boolean, whether a BOM was detected or not.
|
||||||
|
|
||||||
|
|
||||||
|
function aegisub.fstream.read(stream, length)
|
||||||
|
|
||||||
|
Read a number of characters from a file.
|
||||||
|
|
||||||
|
@stream (user data)
|
||||||
|
The Input File Stream to read from.
|
||||||
|
|
||||||
|
@length (number)
|
||||||
|
Number of characters to read. If this is zero, no data are read. If this
|
||||||
|
is larger than the number of characters available, data are read until the
|
||||||
|
end of file.
|
||||||
|
|
||||||
|
Returns: String, the string read from the file.
|
||||||
|
|
||||||
|
|
||||||
|
function aegisub.fstream.read_bytes(stream, length)
|
||||||
|
|
||||||
|
Read a number of bytes from a file and convert to a string.
|
||||||
|
|
||||||
|
@stream (user data)
|
||||||
|
The Input File Stream to read from.
|
||||||
|
|
||||||
|
@length (number)
|
||||||
|
The number of bytes to read.
|
||||||
|
|
||||||
|
Returns: String, best-effort converted from the bytes read.
|
||||||
|
|
||||||
|
|
||||||
|
function aegisub.fstream.read_line(stream, include_newline)
|
||||||
|
|
||||||
|
Read until next newline in the file. A newline is defined asone of these
|
||||||
|
sequences of Unicode codepoints in the decoded text:
|
||||||
|
0x0A ("\n")
|
||||||
|
0x0D ("\r")
|
||||||
|
0x0D 0x0A ("\r\n")
|
||||||
|
The sequence "\n\r" is interpreted as two newlines, ie. a newline, a blank
|
||||||
|
line and yet another newline.
|
||||||
|
|
||||||
|
@stream (user data)
|
||||||
|
The Input File Stream to read from.
|
||||||
|
|
||||||
|
@include_newline (boolean)
|
||||||
|
If true, include the newline character(s) in the returned string.
|
||||||
|
|
||||||
|
Returns: String.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Writing text
|
||||||
|
|
||||||
|
All these functions assume the file is in the current encoding specified.
|
||||||
|
|
||||||
|
|
||||||
|
function aegisub.fstream.write_utf_bom(stream)
|
||||||
|
|
||||||
|
This function will corrupt your file if used anywhere else than on position 0.
|
||||||
|
|
||||||
|
Write the correct UTF BOM character to the file, or nothing if not currently
|
||||||
|
in an UTF encoding.
|
||||||
|
|
||||||
|
@stream (user data)
|
||||||
|
The Output File Stream to write the BOM to.
|
||||||
|
|
||||||
|
Returns: nothing.
|
||||||
|
|
||||||
|
|
||||||
|
function aegisub.fstream.write(stream, text)
|
||||||
|
|
||||||
|
Write a string to a file.
|
||||||
|
|
||||||
|
@stream (user data)
|
||||||
|
The Output File Stream to write to.
|
||||||
|
|
||||||
|
@text (string)
|
||||||
|
The text to write.
|
||||||
|
|
||||||
|
Returns: nothing.
|
||||||
|
|
||||||
|
|
||||||
|
function aegisub.fstream.write_line(stream, text)
|
||||||
|
|
||||||
|
Write a string to a file, followed by an "\r\n" newline.
|
||||||
|
|
||||||
|
@stream (user data)
|
||||||
|
The Output File Stream to write to.
|
||||||
|
|
||||||
|
@text (string)
|
||||||
|
The text to write.
|
||||||
|
|
||||||
|
Returns: nothing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
@ -0,0 +1,32 @@
|
||||||
|
Miscellaneous functions in Automation 4
|
||||||
|
|
||||||
|
This document describes various functions that couldn't be placed in any of
|
||||||
|
the other Automation 4 documents.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Getting the rendered size of a string
|
||||||
|
|
||||||
|
This function might later on be part of a full rendering-interface for
|
||||||
|
creating actual bitmaps of text.
|
||||||
|
|
||||||
|
This function does NOT attempt to handle line breaks, automatic line breaking,
|
||||||
|
fomatting override tags, vector drawings or anything else to that effect.
|
||||||
|
If you need such functionality, you need to implement it yourself. (For now,
|
||||||
|
at least.)
|
||||||
|
|
||||||
|
function aegisub.text_extents(style, text)
|
||||||
|
|
||||||
|
@style (table)
|
||||||
|
A "style" class Subtitle Line table.
|
||||||
|
|
||||||
|
@text (string)
|
||||||
|
The text to calculate the rendered size of.
|
||||||
|
|
||||||
|
Returns: 4 values, all numbers.
|
||||||
|
1. Width of text in pixels.
|
||||||
|
2. Height of text in pixels.
|
||||||
|
3. Descent of text in pixels.
|
||||||
|
4. External leading of text in pixels.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
@ -0,0 +1,176 @@
|
||||||
|
Aegisub Automation documentation
|
||||||
|
Version 4
|
||||||
|
Copyright 2005-2006 Niels Martin Hansen
|
||||||
|
|
||||||
|
THIS IS OUT OF DATE COMPARED TO THE REST OF THE DOCS!
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
This document describes version 4 of the automation system used in Aegisub.
|
||||||
|
The automation system uses the Lua language for scripting engine.
|
||||||
|
See <http://www.lua.org/> for more information.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Overview
|
||||||
|
|
||||||
|
Aegisub Automation is a scripting environment that allows you to automate
|
||||||
|
almost any task working with subtitles in Aegisub, ie. a macro environment.
|
||||||
|
|
||||||
|
Automation allows you to:
|
||||||
|
- Create macros (adding extra menu items to the main menu)
|
||||||
|
o Those macros can optionally also display dialog boxes to the user
|
||||||
|
o Allows adding new features to Aegisub without recompiling the entire
|
||||||
|
program!
|
||||||
|
- Write export filters
|
||||||
|
o This is what Automation 3 did, but with more options
|
||||||
|
o Useful for adding complicated special effects to a script
|
||||||
|
- Write file-format importers and exporters
|
||||||
|
o Load every strange subtitle format you come by
|
||||||
|
o Save in those formats as well
|
||||||
|
o Exporters write directly to a file stream, allowing you to generate
|
||||||
|
those huge karaoke effects much faster!
|
||||||
|
|
||||||
|
Automation runs in a true Unicode environment, meaning strings are internally
|
||||||
|
represented as UTF-32, so you, as programmer, don't have to worry about text
|
||||||
|
encodings, prefix encodings etc. to write scripts that can handle text in
|
||||||
|
mostly any language of the world.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Scripts, files functions
|
||||||
|
|
||||||
|
An automation script is a Lua script following certain conventions described
|
||||||
|
in this document. A script consists of one or more files, with one of them
|
||||||
|
being the master script, and the others being include files.
|
||||||
|
|
||||||
|
Every script runs in a separate Lua interpreter, so separate scripts cannot
|
||||||
|
communicate directly with each other. Scripts can share code by having common
|
||||||
|
include files. Scripts can share data by storing data in the subtitle files,
|
||||||
|
either in the dialogue lines or in the Script Info headers.
|
||||||
|
|
||||||
|
Files containing Automation scripts must in UTF-8 encoding, with or without
|
||||||
|
BOM (Byte Order Mark). Compiled Lua scripts should also work, as long as all
|
||||||
|
strings are UTF-8 encoded, but this is untested and unsupported.
|
||||||
|
|
||||||
|
Automation scripts implement one or more of four possible features. A feature
|
||||||
|
is implemented by filling a specially named global table with certain values.
|
||||||
|
See below for a discussion about the various features and how they differ.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Scriptable features
|
||||||
|
|
||||||
|
The following four features can be implemented by an Automation script:
|
||||||
|
|
||||||
|
- Macro
|
||||||
|
A macro is presented as a new menu item in the Automation menu on the menu
|
||||||
|
bar in Aegisub. When the user select the menu item, a function in the
|
||||||
|
Automation script is called to do processing. Features are present to allow
|
||||||
|
direct interaction with the subtitle data.
|
||||||
|
|
||||||
|
The macro can create and display dialog windows to the user.
|
||||||
|
|
||||||
|
A macro can provide a function, that determines whether the macro cen be
|
||||||
|
run, based on the current selection in the program, and the contents of
|
||||||
|
the subtitles.
|
||||||
|
|
||||||
|
- Export filter
|
||||||
|
An export filter is presented as a filter in the Export dialog accessed
|
||||||
|
from the File menu. The export filter is called when the user uses the
|
||||||
|
Export feature. The export filter is given access every line (including
|
||||||
|
Styles and Script Info lines) in the subtitle file, and can add/modify/
|
||||||
|
remove lines in those.
|
||||||
|
|
||||||
|
The export filter can provide a function, that returns a configuration
|
||||||
|
dialog, which is presented to the user before the export is run. This
|
||||||
|
function can access the subtitle data in order to customise the
|
||||||
|
configuration dialog, before it's presented to the user.
|
||||||
|
|
||||||
|
- File format reader
|
||||||
|
It is not yet decided how the file format reader is accessed.
|
||||||
|
|
||||||
|
Current ideas:
|
||||||
|
o It provides two functions, one to test whether it can handle a given
|
||||||
|
file and one to actually convert that file to ASS. Which import filter
|
||||||
|
to use is decided by Aegisub, based on the result of the first function.
|
||||||
|
o The user selects an import filter and a file. The import filter is
|
||||||
|
applied to the selected file.
|
||||||
|
|
||||||
|
The file format reader can present dialog windows to the user.
|
||||||
|
|
||||||
|
The file format reader is given access to the raw file stream.
|
||||||
|
|
||||||
|
- File format writer
|
||||||
|
The file format writer is selected in the Export dialog access from the
|
||||||
|
File menu. The file format writer is handed all the lines of the subtitles
|
||||||
|
file and a file stream to write to.
|
||||||
|
|
||||||
|
The file format writer can report itself as writing a binary format or a
|
||||||
|
text format. In the case of a text format, all output is passed through the
|
||||||
|
character set conversion routines in Aegisub.
|
||||||
|
|
||||||
|
The file format writer can present dialog windows to the user.
|
||||||
|
|
||||||
|
Every feature is given access to the following in addition to what's described
|
||||||
|
above:
|
||||||
|
|
||||||
|
- Displaying/hiding/updating a progress bar.
|
||||||
|
- Outputting messages to the user.
|
||||||
|
- Accessing framerate data
|
||||||
|
- (Not fully decided yet) Raw video frame data (RGB and/or YUV)
|
||||||
|
- (Not fully decided yet) Raw and FFT transformed wave data
|
||||||
|
- (Not fully decided yet) Utilising FexTracker functions
|
||||||
|
- Calculating the rendered size of a text string, given a style definition
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Script registration
|
||||||
|
|
||||||
|
Scripts can be loaded in two ways, through autoload or by assigning them to
|
||||||
|
a subtitle file.
|
||||||
|
|
||||||
|
Autoloading of scripts happens by placing the master script file into the
|
||||||
|
"automation/autoload" directory under the Aegisub installation directory.
|
||||||
|
|
||||||
|
Assining scripts to a subtitle file is done through the Automation Manager
|
||||||
|
GUI. Scripts assigned to a subtitle file are stored in the ASS Script Info
|
||||||
|
line "Automation Scripts", using a pipe character as separator between the
|
||||||
|
master script filenames.
|
||||||
|
|
||||||
|
The automatic loading/storing of configuration options from Automation 3 has
|
||||||
|
been removed, but can still be implemented in an Export Filter feature using
|
||||||
|
the initialisation function.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Actual documentation for functions, data structures and other interfaces is
|
||||||
|
yet to be written.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
|
||||||
|
Versions of the scripting interface
|
||||||
|
|
||||||
|
Here's a quick history of the scripting interface:
|
||||||
|
|
||||||
|
Version 1
|
||||||
|
Using Lua as engine.
|
||||||
|
The scripts used in the Karaoke Effector application, avaible at:
|
||||||
|
<http://www.jiifurusu.dk/files/programming/effector/> (currently down)
|
||||||
|
|
||||||
|
Version 2
|
||||||
|
Using Python as engine.
|
||||||
|
The first draft for an Aegisub automation engine.
|
||||||
|
Never implemented.
|
||||||
|
|
||||||
|
Version 3
|
||||||
|
Using Lua as engine.
|
||||||
|
Aegisub 1.09 was the last release-version to use Automation 3.
|
||||||
|
(Tentative release date only!)
|
||||||
|
|
||||||
|
Version 4
|
||||||
|
Using Lua as engine
|
||||||
|
Present in Aegisub 1.10 and later (tentative!)
|
||||||
|
Heavily expanded feature set, allowing a much wider range of modifications,
|
||||||
|
and more direct integration into the Aegisub user interface.
|
||||||
|
|
@ -0,0 +1,97 @@
|
||||||
|
Automation 4 Progress Reporting and Debugging interface
|
||||||
|
|
||||||
|
This document describes the functions used for reporting progress and
|
||||||
|
outputting debug information during the running of a script.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Showing/hiding the progress dialog
|
||||||
|
|
||||||
|
This function has been removed. A progress dialog is always shown.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Setting the progress bar position
|
||||||
|
|
||||||
|
function aegisub.progress.set(precent)
|
||||||
|
|
||||||
|
@percent (number)
|
||||||
|
The percentage completed.
|
||||||
|
|
||||||
|
Returns: nothing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Showing the current task
|
||||||
|
|
||||||
|
Used to set a message describing the current task being done.
|
||||||
|
|
||||||
|
function aegisub.progress.task(msg, ...)
|
||||||
|
|
||||||
|
@msg (string)
|
||||||
|
A format string used for the message.
|
||||||
|
|
||||||
|
@...
|
||||||
|
Parameters to the format string.
|
||||||
|
|
||||||
|
Returns: nothing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Setting the progress dialog title
|
||||||
|
|
||||||
|
function aegisub.progress.title(title, ...)
|
||||||
|
|
||||||
|
The default title for the progress dialog is the name of the current Feature
|
||||||
|
being executed.
|
||||||
|
|
||||||
|
@title (string)
|
||||||
|
A format string used for the title.
|
||||||
|
|
||||||
|
@...
|
||||||
|
Parameters to the format string.
|
||||||
|
|
||||||
|
Returns: nothing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Getting the "cancelled" status
|
||||||
|
|
||||||
|
Call this function to determine whether the Cancel button in the progress
|
||||||
|
dialog has been clicked.
|
||||||
|
|
||||||
|
function aegisub.progress.is_cancelled()
|
||||||
|
|
||||||
|
Returns: Boolean. True is the user has clicked the Cancel button, false if it
|
||||||
|
has not been clicked.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Outputting text to the debug log
|
||||||
|
|
||||||
|
function aegisub.debug.out(level, msg, ...)
|
||||||
|
|
||||||
|
@level (number)
|
||||||
|
Integer describing the verbosity of this message. Here are some suggested
|
||||||
|
values you can use:
|
||||||
|
0: Fatal, this is really an error that can't be ignored. (Note that the
|
||||||
|
script execution is NOT automatically stopped because of this.)
|
||||||
|
1: Error, this kind of error can be recovered from, but might result in a
|
||||||
|
fatal error later on.
|
||||||
|
2: Warning, something might be going wrong.
|
||||||
|
3: Hint, something isn't entirely sane, but nothing wrong.
|
||||||
|
4: Debug, some additional data only needed for development.
|
||||||
|
5: Trace, extremely verbose data showing every tiny step during execution.
|
||||||
|
The level can be used to let the user limit how severe messages will be
|
||||||
|
shown, so you eg. can leave trace messages in, yet the casual user of the
|
||||||
|
script won't see them unless he explicitly enables it.
|
||||||
|
|
||||||
|
@msg (string)
|
||||||
|
A format string used for the message.
|
||||||
|
|
||||||
|
@...
|
||||||
|
Parameters for the format string.
|
||||||
|
|
||||||
|
Returns: nothing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
@ -0,0 +1,416 @@
|
||||||
|
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.
|
||||||
|
|
||||||
|
---
|
||||||
Loading…
Reference in New Issue