mia/Aegisub
1
0
Fork 1
Code Issues Pull requests Projects Releases Wiki Activity

More auto4 files...

Browse source 
Originally committed to SVN as r645.
This commit is contained in:
Niels Martin Hansen 2006-12-28 21:19:59 +00:00
parent b39451823e
commit ef6ef4c603
8 changed files with 1501 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
automation/demos/macro-1-edgeblur.lua Normal file
View file

@ -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)

367
automation/v4-docs/basic-function-interface.txt Normal file
View file

@ -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.)
---

180
automation/v4-docs/configuration-dialogs.txt Normal file
View file

@ -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.
---

214
automation/v4-docs/file-streams.txt Normal file
View file

@ -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.
---

32
automation/v4-docs/misc.txt Normal file
View file

@ -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.
---

176
automation/v4-docs/overview.txt Normal file
View file

@ -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.

97
automation/v4-docs/progress-reporting.txt Normal file
View file

@ -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.
---

416
automation/v4-docs/subtitle-data.txt Normal file
View file

@ -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.
---