Moving from Automation 3

From Aegisub Manual

If you're an avid user of Automation 3 (Lua) scripting from Aegisub 1.10 and earlier you will be happy to know that Aegisub 2 still supports Automation 3 scripts with no or only very small changes to them.

Contents 1 Things to look out for 1.1 Karaoke tables 1.2 colorstring_to_rgb function 1.3 New script file name extension 2 Good news 3 Running Automation 3 scripts 4 Why use Automation 4 instead?

Things to look out for

Karaoke tables

The karaoke tables are no longer generated by Aegisub but in karaskel. If you're using karaskel already you shouldn't need to worry about this.

If you aren't using karaskel, here's how to get the karaoke tables:

First you will need the karaskel-base. Put this line as some of the first in your script:

include("karaskel-base.auto3")

You will then need to call a function in process_lines:

karaskel.parse_syllable_data(meta, styles, lines)

That line should be the very first thing you do in process_lines. It will modify lines so it also includes the karaoke data.

colorstring_to_rgb function

This should also not be a problem if you're using the include files as it has been recommended to do.

The aegisub.colorstring_to_rgb function was moved from being an internal function implemented in C++ to being in the utils include. If you're using karaskel, you also have utils included. Otherwise you can include it manually like this:

include("utils.auto3")

New script file name extension

As shown above, the .lua extension is no longer officially used for Automation 3 scripts. It should continue to work in most cases, however. Specifically, all the include files still also exist with .lua extension. These will detect whether you're using an Automation 3 or Automation 4 script and include the correct version of the include file for you.

It can in some cases be problematic to have a main script called .lua since those will first be loaded with the Automation 4 Lua 5.1 engine, which means that the Automation 4 includes will also be used at first. Only after the script has been loaded it's possible to test whether it's actually an Automation 3 script. If a .lua file is found to be an Automation 3 script after being loaded as an Automation 4 one, it's reloaded as an Automation 3 one instead.

If you find that this auto-detection fails to work for your script and it instead fails to load, or is just left loaded as a (non-functioning) Automation 4 script, manually rename the file to .auto3.

Good news

The text_extents function now uses the Automation 4 version of the calculation, which should be 100% VSFilter compatible in all cases. This means all weird spacing problems should be resolved. (There might still be some half-pixel-off errors due to rounding.)

Running Automation 3 scripts

With the Apply button gone from the Automation Manager you might be wondering how to run Automation 3 scripts.

You use them from the Export dialog. (Automation 3 scripts have always first and foremost been export filters.) You do not have to go to the Automation Manager window every time to reload a script, nor do you have to use the old "self-include-reload" trick. All local Automation scripts are automatically reloaded whenever you open the Export dialog.

Why use Automation 4 instead?

Since Automation 3 still works you might be tempted to continue using it. Here are some reasons not to:

• Simpler script file structure. There are less required elements and you are somewhat more free in how to express things.
• Several array indexing inconsistencies have been corrected, everything is now indexed from one as the custom in Lua programming is. The exception to this rule is for karaoke tables, these have retained the "zero'th" syllable, everything before the first karaoke tag.
• The pre-calculations performed by karaskel provide more useful information and more advanced position. It's also more modular, allowing you to control what is pre-calculated and when.
• You get direct access to the Script Info and Styles sections of the subtitle file, allowing you to modify styles and header information, also adding and removing it.
• The ability to write macros. Macros are easier to access than the old semi-workaround that was the Apply button, and they have access to information about the lines selected in the subtitle grid.

But of course you shouldn't start rewriting all your existing scripts to Automation 4 unless you have a really good reason.

If you decide to write scripts for Automation 4 Lua you can read the overview of changes from Automation 3 page for a jumpstart.