Karaoke Templater Reference: Code execution environment

From Aegisub Manual

The Lua code in code blocks and on code lines is run in a separate global environment such that it won't accidentally disturb the main script function.

You can store your own data in this environment for use later, for example pre-compute some values on code-lines and later insert them using code blocks, but it also contains several pre-defined variables and functions designed to make it easier writing effect templates.

It's important to understand that the contents of code execution environment and the inline-variables ($-variables) are not related. You cannot change an inline-variable by changing something in the code execution environment nor can you add new ones. However, you can create and re-define the contents of the code execution environment.

[edit] Line and syllable information

The code execution environment contains a few variables pointing to the current line and syllable structure being processed, as well as some more supporting tables. These are just references to the structures produced by karaskel and are not modified in any way.

You should treat these as read-only, except line. If you change the other ones, the kara-templater script might start misbehaving.

• line - The line currently being produced, changing this will affect the resulting line in the file. See the reference for dialogue line tables.
• orgline - The original line, this is the source line the current syllable is located on.
• syl - The current syllable structure. If the current template is a furi template, it's the current furigana syllable. If the current template has one or both of the char or multi modifiers, this is a pseudo-syllable structure, a copy of the original syllable structure with several values changed to look like the current part of the syllable being processed. Also see the reference for syllable tables.
• basesyl - Usually the same as syl, except when the template has the char or multi modifier, then this is the original syllable. (If syl == basesyl is true, then the current template is neither char nor multi.)
• meta - Contains various metadata about the script, namely the contents of the Script Info section. Most importantly, it has the res_x and res_y fields describing the script resolution.

All of these variables are reset to nil whenever processing starts for a new line, except meta. They are then set to the relevant value whenever processing hits a new stage. This means that, for example pre-line templates only has line and orgline set and both syl and basesyl are nil. In code once templates, all of the variables except meta are nil.

[edit] Standard libraries and related things

Both the string and math Lua standard libraries are imported into the execution environment, as they are generally useful.

You can also access the main execution environment of the kara-templater script itself using the _G (underscore capital-G) variable and through that access the rest of the Lua standard library. For example, _G.table.sort refers to the regular table.sort function. See the Lua 5.1 manual for details on the available libraries.

You can also access the Automation 4 Lua standard libraries through the _G variable: karaskel.lua, unicode.lua and utils.lua.

There is also the self-reference tenv variable, this refers to the code execution environment itself. This means that tenv.tenv == tenv is true.

[edit] Utility functions

These functions help do more complex modifications of the output line (the line variable) and are unavoidable when creating complex effects.

Currently there is just one, but it is possible to define your own functions in code lines.

[edit] retime

Synopsis: retime(mode, startadjust, endadjust)

A graphical explanation of the different modes of the retimefunction.

This function is usually used once in a template in a code block by itself. It adjusts the start and end time of the output line in various ways.

The mode parameter determines how the start and end times of the line are changed, it must be a string with one of the following values. Because it must be a string, the name of the mode must be enclosed in quotation marks!

The startadjust and endadjust parameters slightly change meaning based on the mode, but generally is a number of milliseconds added to the "base" time controlled by the mode.

Possible modes:

• abs or set - Both startadjust and endadjust are used as absolute time values to set the start and end time of the line directly.
• preline - Intended to make effects that happen before the actual line start. Both start and end time of the line are set to the start time of the line, then startadjust is added to the start time and endadjust added to the end time. Usually startadjust should be negative here and endadjust be zero.
• line - Use the regular line timings and just add startadjust to the start time and endadjust to the end time.
• start2syl - Intended to make the look of the syllable from the start of the line until it is highlighted. The start time of the line is kept and the end time is set to the start time of the syllable. Use startadjust and endadjust to offset the times.
• presyl - Similar to preline but for the syllable timing instead.
• syl - From start of syllable to end of syllable.
• postsyl - Similar to presyl but the base timing is the syllable end time instead of start time. You will usually want to use a zero addstart and positive addend here.
• syl2end - The time from the end of the syllable to the end of line, similar to start2syl.
• postline - Similar to postsyl but for the line timing instead.

There is also a special mode:

• sylpct - Both of startadjust and endadjust are treated as percentage values from 0 to 100 and are used to set the line timing to cover that part of the syllable's time.

Be careful with the retime function on line templates, if you use it directly on a line template it will probably not do what you want. You should only use it on pre-line, syl and furi templates. You should also only use it once in each template.

The retime function always returns the empty string ("") which will cause it to output nothing when used in code blocks, but still evaluate to true if used in boolean expressions.

template syl: !retime("preline", -1000, 0)!{\pos($scenter,$smiddle)\an5\fscx0\fscy0\t(\fscx100\fscy100)}

template syl: !retime("syl", 0, 0)!{\pos($x,$y)\t(\fscx360)}

template syl: !retime("sylpct", 0, 50)!{\move($x,$y,$x,!$y-10!)}
template syl: !retime("sylpct", 50, 100)!{\move($x,!$y-10!,$x,$y)}

[edit] relayer

Synopsis: relayer(newlayer)

Change the Layer field of the generated line to newlayer.

Note: If you want a template to always generate lines with a static layer number, you do not need to use this function. You can just set the Layer field on the template line, it will transfer to the generated lines.

template syl: !relayer(syl.i*5+20)!

[edit] restyle

Synopsis: restyle(newstyle)

Change the Style field on the generated line to newstyle.

Be careful that this does not update the sizing and positioning information. If you want to use sizing or positioning information such as $x, $lwidth, line.middle and syl.right you must change to a style that uses the same font name, font size, boldness, italics, font encoding, X and Y scaling, character spacing, alignment and margins. If you change to a style where any of those properties are different, the positioning and sizing information will be invalid.

No example because the function has limited use.

[edit] maxloop

Synopsis: maxloop(newmax)

Dynamically control the number of times a template will be looped.

Be careful that using this function incorrectly might result in a template that loops forever, until Aegisub runs out of memory or you cancel the template application.

You do not need to use the loop modifier on templates to use this function.

template syl: !maxloop(syl.width + 2*line.styleref.outline)!{\clip(!line.left+syl.left-line.styleref.outline+j-1!,0,!line.left+syl.left-line.styleref.outline+j!,!meta.res_y!)\an5\move(!line.left+syl.center!,!line.middle!,!line.left+syl.center!,!line.middle+math.random(-20,20)!,$start,$end)\shad0}

template syl: !maxloop(j+1)!

[edit] loopctl

Synopsis: loopctl(newj, newmaxj)

Control both loop variables. This function has questionable utility.

newj sets the new value of tenv.j and newmaxj sets the new value of tenv.maxj.

No example because the function has limited use.

[edit] Template execution data

These variables either give some further information on the status of the executing template or modify the rules for template execution in some way. They generally work together with specific template modifiers.

[edit] Looping templates

When a template with the loop or repeat modifier is running, two new variables are introduced in the code execution environment, j and maxj.

• maxj is the number of loops, ie. simply the parameter given to the loop modifier.
• j is the loop iteration counter, it starts at 1 in the first iteration and maxj in the last.

If you change j or maxj while a template is executing, you can affect the number of iterations the loop makes. The maxloop function is convenient for making dynamic loops.

template syl loop 5: {\an5\pos($scenter,$smiddle)\1a&HFF&\3a&Hcc&\t($start,$end,\fscx!100+j*10!\fscy!100+j*10!\3a&HFF&)}

template syl loop 20: {\move($x,$y,!$x+15*math.cos(math.pi*2*j/maxj)!,!$y+15*math.sin(math.pi*2*j/maxj)!,$start,$end)\t($start,$end,\alpha&HFF&)}

[edit] Conditional templates with fxgroup

The fxgroup modifier uses a special table fxgroup in the code execution environment to control whether a template will be executed or not.

The parameter given to the fxgroup modifier names a key (always a string) in the fxgroup table in the execution environment, and when a template assigned to an fxgroup is about to be executed, the value for that key in the fxgroup table is looked up. If the value is true or the key doesn't exist, the template is executed, if it's false the template is skipped.

While you can technically use any text string for fxgroup names, because they're used in Lua code it's best to avoid ones that overlap with Lua reserved words such as end, break, return and several more.

code syl: fxgroup.long = (syl.duration > 200)
template syl noblank: all here: 
template syl fxgroup long: is long: 
karaoke: {\k10}huh? {\k40}wee~~