1
Automation 4 Basic Interface
3
This document described the basic functions needed to define an Automation 4
4
script. This covers Feature registration and the prototypes of functions used
5
to implement the various features.
9
Macro Registation Function
11
This is a function called from top-level of an Automation script to register
14
function aegisub.register_macro(
21
The displayed name of the menu item this macro will generate.
24
A longer description of the function of this macro. This will appear
25
on the status bar when hovering over the menu item.
27
@processing_function (function)
28
The actual function called for the macro execution.
29
This function must be an instance of the Macro Processing Function
32
@validation_function (function)
33
Optional. A function called when it is to be determined whether the
34
macro can act on the current subtitles.
35
This function, if provided, must execute very quickly to avoid lag
37
This function must be an instance of the Macro Validation Function
44
Filter Registration Function
46
This is a function called from top level of an Automation script to register
47
a new Export Filter Feature.
49
function aegisub.register_filter(
54
options_window_provider)
57
The name of the filter, as presented to the user.
60
A longer description of the filter presented to the user.
63
A number determining the default order the enabled filters will be
64
processed. The order can be overridden by the user.
65
Priorities of some built-in filters:
66
o Clean Script Info = 0
68
o Transform Framerate = 1000
69
Filters with higher priority will be executed earlier by default.
71
@processing_function (function)
72
The function called to do the actual filter processing.
73
This function must be an instance of the Filter Processing Function
76
@options_window_provider (function)
77
Optional. A function providing a dialog template for setting options
78
prior to filter processing.
79
This function must be an instance of the Filter Options Window Provider
80
function described below.
86
Format Reader Registration
88
This is a function called from top level in an Automation script to register
89
a new File Format Reader Feature.
91
function aegisub.register_reader(
97
The name of the file format.
100
The file extension usually given to this file format. This must not
101
include any wildcards. (Ie. extension could be "srt", "sub", "ssa" and
104
@processing_function (function)
105
The function called to do the actual file import.
106
This function must be an instance of the Format Reader Function described
113
Format Writer Registration
115
This is a function called from top level in an Automation script to register
116
a new File Format Writer Feature.
118
function aegisub.register_writer(
124
Name of the file format, as presented to the user.
127
The usual file extension given to this file format. This is automatically
128
be attached to the file name on export, unless the user chooses to
131
@processing_function (function)
132
The function doing the actual file export.
133
This function must be an instance of the Format Writer Function described
140
Macro Processing Function
142
This function is called by Aegisub to execute a macro.
144
function process_macro(
149
The name of the function is script-defined. (It doesn't have to be
152
@subtitles (user data)
153
A Subtitles Object, that can be used to retrieve information about the
154
subtitle file the macro is being applied on.
156
@selected_lines (table)
157
An Array Table of numbers, each entry being an index into the file
158
represented by @subtitles. Each of the entries in this table describe that
159
a line is marked as selected by the user.
161
@active_line (number)
162
Index of the currently active line in the subtitle file.
168
Macro Validation Function
170
This function is called by Aegisub to determine whether a macro can be applied
171
to the current state of the subtitles and selection.
173
This function needs to execute very fast, since it may be called for several
174
macros whenever a menu is opened. It is suggested not to use @subtitles at all
177
This function does not have to be defined. If it's undefined, it's taken as if
178
it always returned true.
180
function validate_macro(
185
The name of the function is script-defined. (It doesn't have to be
188
@subtitles (user data)
189
A Subtitles Object, that can be used to retrieve information about the
190
subtitle file the macro is to be be applied on.
192
@selected_lines (table)
193
An Array Table of numbers, each entry being an index into the file
194
represented by @subtitles. Each of the entries in this table describe that
195
a line is marked as selected by the user.
197
@active_line (number)
198
Index of the currently active line in the subtitle file.
201
true is the macro can be applied to the current state of the subtitles,
206
Filter Processing Function
208
This function is called by Aegisub to filter the subtitles during an export
211
function process_filter(
215
The name of the function is script-defined. (It doesn't have to be
218
@subtitles (user data)
219
A Subtitles Object, that can be used to retrieve information about the
220
subtitle file the filter is being applied on.
223
A Dialog Result table representing the options the user selected for the
224
filter before starting the export operation. The fields present in this
225
table are defined by the dialog provided by the Filter Options Window
232
Filter Options Window Provider function
234
This function is called by Aegisub to get a Dialog Window definition to prompt
235
the user for input before an export operation.
236
The data input into the dialog returned by this function are automatically
237
stored into the original subtitle file when an export operation is started.
239
function filter_options_dialog(
243
The name of the function is script-defined. (It doesn't have to be
244
filter_options_dialog.)
246
@subtitles (user data)
247
A Subtitles Object, that can be used to retrieve information about the
248
subtitle file the filter is to be applied on.
250
@stored_options (table)
251
The currently stored options for this export filter. The keys in this table
252
are the option names, and the values are the values stored for those options.
254
Returns: A Dialog Window table.
258
Format Reader Function
260
This function is called by Aegisub to import a file from a foreign file
263
function read_format(
267
The name of the function is script-defined. (It doesn't have to be
270
@input_file (user data)
271
An Input File Stream, representing the file selected for import.
273
@output_subs (user data)
274
An empty Subtitles Object the imported data should be added to.
277
True if the import succeeded, false if it failed.
281
Format Writer Function
283
This function is called by Aegisub to export a file to a foreign file format.
285
function write_format(
289
The name of the function is script-defined. (It doesn't have to be
292
@input_subs (user data)
293
A Subtitles Object representing the subtitles to be exported.
295
@output_file (user data)
296
An Ouput File Stream, representing the file the exported data should be
300
True if the export succeeded, false if it failed.
301
If this function returns false, the output file is deleted from disk.
305
Script information globals
307
These are a series of global variables, the script author can set. They are
308
purely informational, and won't have any actual influence on how the script
311
None of these are required, but it is recommended to provide them.
313
These should never be present in include files.
316
A short, descriptive name for the script, used for presenting it to the
319
script_description (string)
320
A longer description of the purpose of the script, presented to the user
323
script_author (string)
324
Name(s) of the author(s) of the script.
326
script_version (string)
327
Version number of the script.
331
Including other scripts
333
For implementation reasons (and partially compatibility reasons), the Lua
334
built-in dofile() and loadfile() functions are removed, and a custom include()
335
function is provided instead.
337
This function behaves almost the same as dofile(), except that it doesn't
338
support reading from stdin (no such thing exists/is supposed to exist for
339
Aegisub) and it follows some special search rules along a path.
341
function include(filename)
344
The relative path to the script to include.
346
Returns: Any return-values of the included script.
349
1. If there are no path-components in the filename (ie. just a filename),
350
the directory of the original script is searched first. Afterwards, the
351
search path specified in the Aegisub configuration file is searched.
352
2. If the filename contains path components, it is only searched relative
353
to the location of the original script file.
354
3. Absolute paths are not mangled in any way. Using absolute paths is
355
discouraged. (Absolute paths were disallowed in Automation 3.)
added
removed
automation/v4-docs/basic-function-interface.txt
