186 lines
7 KiB
Text
186 lines
7 KiB
Text
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 <http://www.lua.org/> 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:
|
|
<http://www.animereactor.dk/aegisub/>
|
|
|
|
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.
|