From ef6ef4c603c9b481c6f34882fbc175b47be62c79 Mon Sep 17 00:00:00 2001 From: Niels Martin Hansen Date: Thu, 28 Dec 2006 21:19:59 +0000 Subject: [PATCH] More auto4 files... Originally committed to SVN as r645. --- automation/demos/macro-1-edgeblur.lua | 19 + .../v4-docs/basic-function-interface.txt | 367 +++++++++++++++ automation/v4-docs/configuration-dialogs.txt | 180 ++++++++ automation/v4-docs/file-streams.txt | 214 +++++++++ automation/v4-docs/misc.txt | 32 ++ automation/v4-docs/overview.txt | 176 ++++++++ automation/v4-docs/progress-reporting.txt | 97 ++++ automation/v4-docs/subtitle-data.txt | 416 ++++++++++++++++++ 8 files changed, 1501 insertions(+) create mode 100644 automation/demos/macro-1-edgeblur.lua create mode 100644 automation/v4-docs/basic-function-interface.txt create mode 100644 automation/v4-docs/configuration-dialogs.txt create mode 100644 automation/v4-docs/file-streams.txt create mode 100644 automation/v4-docs/misc.txt create mode 100644 automation/v4-docs/overview.txt create mode 100644 automation/v4-docs/progress-reporting.txt create mode 100644 automation/v4-docs/subtitle-data.txt diff --git a/automation/demos/macro-1-edgeblur.lua b/automation/demos/macro-1-edgeblur.lua new file mode 100644 index 000000000..94ba44e14 --- /dev/null +++ b/automation/demos/macro-1-edgeblur.lua @@ -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) diff --git a/automation/v4-docs/basic-function-interface.txt b/automation/v4-docs/basic-function-interface.txt new file mode 100644 index 000000000..007ccfd6b --- /dev/null +++ b/automation/v4-docs/basic-function-interface.txt @@ -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.) + +--- diff --git a/automation/v4-docs/configuration-dialogs.txt b/automation/v4-docs/configuration-dialogs.txt new file mode 100644 index 000000000..9bc0597e8 --- /dev/null +++ b/automation/v4-docs/configuration-dialogs.txt @@ -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. + +--- diff --git a/automation/v4-docs/file-streams.txt b/automation/v4-docs/file-streams.txt new file mode 100644 index 000000000..e8edf870e --- /dev/null +++ b/automation/v4-docs/file-streams.txt @@ -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. + +--- diff --git a/automation/v4-docs/misc.txt b/automation/v4-docs/misc.txt new file mode 100644 index 000000000..abe732496 --- /dev/null +++ b/automation/v4-docs/misc.txt @@ -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. + +--- diff --git a/automation/v4-docs/overview.txt b/automation/v4-docs/overview.txt new file mode 100644 index 000000000..5479af0e9 --- /dev/null +++ b/automation/v4-docs/overview.txt @@ -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 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: + (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. diff --git a/automation/v4-docs/progress-reporting.txt b/automation/v4-docs/progress-reporting.txt new file mode 100644 index 000000000..9272e646a --- /dev/null +++ b/automation/v4-docs/progress-reporting.txt @@ -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. + +--- diff --git a/automation/v4-docs/subtitle-data.txt b/automation/v4-docs/subtitle-data.txt new file mode 100644 index 000000000..17865c162 --- /dev/null +++ b/automation/v4-docs/subtitle-data.txt @@ -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. + +---