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 primarily uses the Lua language for scripting engine. See for more information. Automation 4 can be extended to use other scripting engines/languages, but this hasn't been tried yet, and this document will mostly describe the Lua implementation. --- 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! Like Automation 3, Automation 4 Lua uses UTF-8 for storing text. There is currently no actual support libraries for handling this, but it's expected that some will be added later on. Especially important will be a Unicode- aware regex engine. --- 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 not supported. Automation scripts implement one or more features, of which there are four classes. A feature is implemented by writing one or more functions required for the feature, and registering the feature by calling an API function in the global script environment. --- 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: 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 release-version to use Automation 3. Allowed creating export filters only, but also using them as pseudo-macros. Only access to the Events section of a file, no real access to the rest of the file. Version 4 Using Lua as engine, but framework supports adding further engines later. Present in Aegisub 2.00 and later Heavily expanded feature set, allowing a much wider range of modifications, and more direct integration into the Aegisub user interface. Scripts can either be autoloaded along with Aegisub, or be bound (local) to a subtitle file. What version 2 was intended to have been.