diff --git a/automation/include/karaskel-base.lua b/automation/include/karaskel-base.lua index a2dc0a00a..9645c59dc 100644 --- a/automation/include/karaskel-base.lua +++ b/automation/include/karaskel-base.lua @@ -80,7 +80,7 @@ function karaskel.precalc_syllable_data(meta, styles, lines) meta.res_y = 288 elseif meta.res_x == 0 then -- This is braindead, but it's how TextSub does things... - if meta.res_x == 1024 then + if meta.res_y == 1024 then meta.res_x = 1280 else meta.res_x = meta.res_y / 3 * 4 @@ -154,21 +154,27 @@ function karaskel.precalc_syllable_data(meta, styles, lines) syl.inline_fx = inline_fx -- Do positioning calculations, if applicable sumtext = sumtext .. syl.text_stripped + karaskel.trace("new sumtext = " .. sumtext) if karaskel.engage_positioning then -- Summed text dimensions local sumwidth = aegisub.text_extents(style, sumtext) + karaskel.trace("sumwidth = " .. sumwidth) -- Strip some spaces - local tmp1, tmp2, prespc, syltxt, postspc = string.find(syl.text_stripped, "^(%s*)(.-)(%s*)$") + local tmp1, tmp2, prespc, syltxt, postspc = string.find(syl.text_stripped, "^([ \t]*)(.-)([ \t]*)$") -- Pre/post space dimensions local prespc_width = aegisub.text_extents(style, prespc) local postspc_width = aegisub.text_extents(style, postspc) + karaskel.trace("space capture lengths = " .. string.len(prespc) .. ", " .. string.len(syltxt) .. ", " .. string.len(postspc)) + karaskel.trace("space widths = " .. prespc_width .. ", " .. postspc_width) -- Syllable dimensions syl.width, syl.height, syl.ascent, syl.extlead = aegisub.text_extents(style, syltxt) + karaskel.trace("syllable text, width = " .. syltxt .. ", " .. syl.width) karaskel.trace("precalc_syllable_data:8::") -- Syllable positioning syl.right = sumwidth - postspc_width syl.left = sumwidth - syl.width + prespc_width syl.center = math.floor(syl.left + (syl.right - syl.left) / 2) + karaskel.trace("syllable left, center, right = " .. syl.left .. ", " .. syl.center .. ", " .. syl.right) if syl.furigana then karaskel.calc_furigana_sizes(line, syl) end diff --git a/automation/v4-docs/data-structures.txt b/automation/v4-docs/data-structures.txt new file mode 100644 index 000000000..efc262749 --- /dev/null +++ b/automation/v4-docs/data-structures.txt @@ -0,0 +1,141 @@ +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. Can 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 (functioon) + 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. + +--- + +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 (nhumber) + 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. + +--- + +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. + +--- + +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. + +--- + diff --git a/automation/v4-docs/overview.txt b/automation/v4-docs/overview.txt new file mode 100644 index 000000000..abe0377e5 --- /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 A DRAFT. SUBJECT TO CHANGE. +Last updated: 2006-02-01 04:17 UTC+1 + +--- + +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! + +--- + +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. + +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. + + For preformance-reasons, there is currently no provision for the script to + enable/disable its menu item based on eg. the selection in the Aegisub + subtitles grid. + + - 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 specify a static configuration dialog presented to + the user in the Export UI. + + The export filter can specify a function that's run after the user selects + the Export item on the File menu, but before the Export dialog is actually + displayed. This function will be given access to the subtitles currently + loaded. This is to feature customising the configuration dialog based on + the contents of the subtitles. + It is strongly discouraged to change anything but a single, private Script + Info header line in the subtitles handed to this initialisation function. + + - 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.10 was the last version to use Automation 3. + (Tentative release date only!) + +Version 4 + Using Lua as engine + Present in Aegisub 1.11 and later (tentative!) + Heavily expanded feature set, allowing a much wider range of modifications, + and more direct integration into the Aegisub user interface.