Aegisub/automation/v4-docs/basic-function-interface.txt

352 lines
9.6 KiB
Plaintext
Raw Normal View History

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)
2006-03-22 22:57:03 +01:00
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,
is_text_format,
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.)
@is_text_format (boolean)
Determines whether the user can select a default encoding for reading text
from the file. This only affects whether a default encoding is chosen or not,
even with this argument set to false, you can still read text. You should set
this to true, if the format allows storing in different encodings, and doesn't
explicitly store the used encoding anywhere.
@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,
is_text_format,
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.
@is_text_format (boolean)
Determines whether the user can select a target encoding or not. This
option should be true if the format written allows choosing between
different encodings, and the user should be able to select which one to
use. This option doesn't affect whether you can write text to the file or
not, but only whether the user can select an encoding or not.
@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.
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.
---