Automation 4 Lua Progress reporting

From Aegisub Manual

There functions are used to report various status and progress back to the GUI while a script is running.


Progress reporting

A progress dialogue box is always shown when an Automation 4 Lua script is running. You can use these functions to control what is displayed in it.


Synopsis: aegisub.progress.set(percent)

Set the position of the percent-done bar in the progress window.

  • percent (number) - Number from 0 to 100.


Synopsis: aegisub.progress.task(msg, ...)

Set the "task" text in the progress window, this is the small text below the progress bar showing what the script is currently doing.

  • msg (string) - A format string specifying the message, see the Lua standard string library string.format function for details on format strings.
  • ... - Parameters to the format string.


Synopsis: aegisub.progress.title(title, ...)

Set the title of the progress window, this is the large text displayed above the progress bar. This text should usually not changing while the script is running. By default this is set to the name of the feature running, eg. the name of the macro (menu item text) if it's a macro.

  • title (string) - A format string specifying the title, see the Lua standard string library string.format function for details on format strings.
  • ... - Parameters to the format string.


Synopsis: cancelled = aegisub.progress.is_cancelled()

Tells whether the user has clicked on the Cancel button.

You should call this function regularly during long operations, and stop the execution of your script as quickly as possible. If you're a macro you should either roll back all changes you have made if possible, or set an undo point so the user can undo the changes made by the script.

  • cancelled (bool) - false if the user has not clicked the Cancel button, true if the user has clicked Cancel. If is_cancelled returns true all subsequent calls to it in the current execution will also return true.

Debug output

The primary support for script debugging in Automation 4 Lua is through sending debug messages to the message log integrated in the progress window.

If a script shows a debug or other message, the progress window stays open after the script has finished running, until the user clicks the Close button. Please consider whether it's really that important that the user sees your messages, blocking other input to the program to display something that might be irrelevant to the user can create a bad experience.



  • aegisub.debug.out(msg, ...)
  • aegisub.debug.out(level, msg, ...)
  • aegisub.log(msg, ...)
  • aegisub.log(level, msg, ...)

The two names are synonymous, you can use either name depending on your preference.

Sends a message to the message log, optionally with a specific severity level. The user can control in Aegisub's options the highest level messages that will be shown.

  • level (number) - Severity level of the message. This parameter is optional, if you leave it out (by entirely skipping it) the message will always be shown.
  • 'msg (string) - A format string specifying the message, see the Lua standard string library string.format function for details on format strings.
  • ... - Parameters to the format string.

The following severity levels are suggested:

  • 0 "fatal" - Something really bad happened and the script can't continue. Level 0 messages are always shown. Note that Aegisub won't terminate your script because you display a level 0 message, you will still have to do that yourself.
  • 1 "error" - A real error occurred so the user should expect something to have gone wrong even though you tried to recover. A fatal error might happen later.
  • 2 "warning" - It looks like something is wrong and the user ought to know because it might mean something needs to be fixed.
  • 3 "hint" - A tip or otherwise on how the user can improve things, or hints that something might cause a warning or error later on.
  • 4 "debug" - Information meant to help fix errors in the script, such as dumps of variable contents.
  • 5 "trace" - Extremely verbose information about what the script is doing, literally a message for each single step done with lots of variable dumps.

Automation Manager • Running macros • Using export filters • Standard macros • Changes from Automation 3 • Moving from Automation 3

Karaoke Templater reference:

Declaring templates • Execution order • Modifiers • Inline-variables ($-variables) • Code lines and blocks • Execution envirionment

Lua reference:

Registration • Subtitles object • Progress reporting • Config dialogues • Misc. APIs • karaskel.lua • utils.lua • unicode.lua • cleantags.lua

Karaskel concepts:

Style tables • Dialogue line tables • Syllable tables • Inline effects • Furigana