The Automation 4 karaskel.lua include file contains several functions
intended to help the development of karaoke effects with Automation 4 Lua.
It also defines several new data structures, and extensions to those
defined by Automation 4 Lua itself.
karaskel.lua itself includes
`utils.lua` and
`unicode.lua` so you do not need to
include those yourself when using karaskel.lua.
Using karaskel.lua is strongly recommended when creating karaoke effects,
and it can also be useful for other tasks as it contains several text
layouting functions.
Synopsis: meta, styles = karaskel.collect_head(subtitles, generate_furigana)
Reads the subtitle file to collect all header information and style definitions, and optionally also generates new styles for furigana layouts.
subtitles is the Subtitle File object defined by Automation 4 Lua.generate_furigana is a boolean: if it is true a style for furigana
layout is generated for each style that does not have
one already. Generation of furigana styles will never overwrite existing
styles, create double style definitions or create meaningless furigana
styles for other furigana styles.Calling collect_head is usually one of the first things you do in your
processing function.
The returned meta table contains a map of all Name: Value pairs in the
[Script Info] section. It also always contains meta.res_x and
meta.res_y calculated from the PlayResX and PlayResY fields,
following VSFilter conventions for default values when one or both of the
fields are missing.
The returned styles table contains a map of all defined styles, along
with any generated furigana layout styles. The style structures stored in
this table have one added field, style.margin_v which is an alias for
style.margin_t, for convenience. styles can be indexed by style names
(case sensitive, names not mangled) and by numbers. styles.n is the
number of styles stored, and styles[1] is the first style defined.
Synopsis: karaskel.preproc_line(subtitles, meta, styles, line)
Calculate sizing, positioning and various other information for a single
subtitle line. This function calls karaskel.preproc_line_text,
karaskel.preproc_line_size and karaskel.preproc_line_pos in order.
This function does not return a value, but rather modifies the line
table. See below for more information.
Synopsis: karaskel.preproc_line_text(meta, styles, line)
Preprocess the text of a single line. meta and styles are the tables
returned by [[karaskel.collect_head|karaskel.lua#karaskel.collect_head]].
This function does not return a value, but rather modifies the line
table. The following fields are added:
line.text_stripped - Line text with all override tags and vector
drawings removed.line.duration - Duration of the line in millisecondsline.kara and line.furi - Extended karaoke and furigana
tables, without sizing and
position data.This function does not calculate any text sizing or positioning
information. (In fact it currently doesn't use the meta or styles
arguments at all.)
Synopsis: karaskel.preproc_line_size(meta, styles, line)
Calculate sizing data for a line and all karaoke syllables and furigana parts. Also adds a reference to the line style.
This function does not return a value, but rather modifies the line
table. The following fields are added:
line.styleref - A reference to the Style table representing this line's
selected style.line.furistyle - A reference to the Style table representing this
line's furigana layout style. If there is no style with the right name,
this field is false instead.line.width, line.height, line.descent and line.extlead - SizingAlso, this function modifies the line.kara and line.furi tables, adding
sizing information.
No position information is calculated here.
If the line table does not seem to have been processed with
karaskel.preproc_line_text yet, this will be done automatically.
Synopsis: karaskel.preproc_line_pos(meta, styles, line)
Calculate line, karaoke and furigana position information.
This function invokes karaskel.do_basic_layout when no furigana style is
available, and karaskel.do_furigana_layout when a furigana style is
defined for the line. The furigana layout algorithm might change the
calculated width of the line.
This function does not return a value, but rather modifies the line
table. The following fields are added:
line.margin_v - A convenience alias for line.margin_t.line.eff_margin_l, line.eff_margin_r, line.eff_margin_t,
line.eff_margin_b and line.eff_margin_v - Effective margin values for
the line. If the corresponding margin override for the line is non-zero,
that value is used, otherwise the value defined in the style is used.line.halign - One of "left", "center" or "right", the horizontal
alignment of the line, derived from line.styleref.align.line.valign - One of "top", "middle" or "bottom", the vertical
alignment of the line, derived from line.styleref.align.line.left - The left edge X coordinate for the line, assuming its given
alignment, effective margins and no collision detection.line.center - The line centre X coordinate, assuming its given
alignment, effective margins and no collision detection.line.right - The right edge X coordinate for the line, assuming its
given alignment, effective margins and no collision detection.line.top - The top edge Y coordinate for the line, assuming its given
alignment, effective margins and no collision detection.line.middle - The line vertical centre Y coordinate, assuming its given
alignment, effective margins and no collision detection. line.vcenter is
an alias for this.
line.bottom - The bottom edge Y coordinate for the line, assuming its
given alignment, effective margins and no collision detection.line.x and line.y - X and Y coordinates for the line, suitable for
using in a \pos override tag to get the line's original position.Furthermore, the line.kara and line.furi tables are modified by the
layout function called, adding positioning information.
See the part on data structures later on this page for more details on the various fields that are added.
If no line sizing information is found, karaskel.preproc_line_size will
be invoked, which might in turn also invoke karaskel.preproc_line_text.
This function is not intended to be called directly, but is rather called
as a helper function for karaskel.preproc_line_pos.
It runs a very simple layout algorithm for the line.kara table, which
simply calculates the positions of the syllables when placed in one
straight line with no additional spacing in between. Positioning
information is added to each karaoke syllable.
The line.furi table is not touched.
This function is not intended to be called directly, but is rather called
as a helper function for karaskel.preproc_line_pos.
It runs an advanced text layout algorithm to position karaoke syllables and furigana neatly, avoiding unwanted overlapping. People interested in the actual algorithm used should read the function source code. It should be well enough commented.
This function adds positioning information to both the line.kara and
line.furi tables. It might also change the line.width field as the line
base text is expanded to make room for furigana.
A karaoke skeleton is a framework for building karaoke effects in. It usually works by writing a couple of functions yourself for handling the actual effect work, and these are then called at various times. The actual details of what functions you need to write depends on the actual karaoke skeleton.
Main function: karaskel.use_fx_library_furi(use_furigana, add_macro)
Call the karaskel.use_fx_library_furi function to install the Effect
Library skeleton for this script file. The script_name and
script_description globals are used to name the export filter produced.
If use_furigana is true, furigana styles are created and added as needed.
If add_macro is true, a macro is registered in addition to the export
filter.
The basic premise of the Effect Library skeleton is that each timed karaoke line has a word in its Effect field that describes what effect to apply to that line. This makes Effect Library a good choice if you want to use several different effects in a single karaoke.
When Effect Library is invoked, it calls a function named fx_effect for
each Dialogue line in the subtitle file. For example, if the Effect field
of a dialogue line is "jump", the function named fx_jump is called. For
lines with empty Effect field, the function fx_none is called.
If an fx function does not exist, the original line is left in the subtitle
file. Otherwise, whether the original line is left depends on the return
value of the fx function, a true return value means the original line is
kept, a false value means it is made into a Comment line.
Signature of fx functions: keep = fx_effect(subtitles, meta, styles, line, fxdata)
fxdata is the contents of the Effect field after the initial word
defining the effect to be used. All output of an fx function should be
appended to the subtitle file represented by subtitles.
Simplified main function: karaskel.use_fx_library(add_macro)
Identical to the _furi variant above, except that the use_furigana
parameter is removed; it is assumed to be false.
Main function: karaskel.use_classic_adv(use_furigana, add_macro)
Call the karaskel.use_classic_adv function to install the Classic
Advanced skeleton for this script file. The script_name and
script_description globals are used to name the export filter produced.
If use_furigana is true, furigana styles are created and added as needed,
and furigana processing is enabled. If add_macro is true, a macro is
registered in addition to the export filter.
This skeleton is created in the image of the Automation 3 karaskel-adv
skeleton, but it is not compatible with it. (You cannot use a
karaskel-adv script with Classic Advanced without rewriting parts of your
script.) The basic premise is that the do_syllable function is called
once for each syllable. Optionally, you can have a function called for each
line, using the do_line function.
Classic Advanced uses a slightly different model than the usual Automation
4 Lua one. Here all subtitle lines are collected first before any further
processing is done. They also have line.prev and line.next fields
added, to allow linked list style access. To add lines to the output, you
must still add lines to the subs object though. Before processing starts,
all original lines are deleted from the subs object.
Signature of syllable function: do_syllable(subs, meta, styles, lines, line, syl)
The syllable function must be named do_syllable. If furigana processing
is enabled, you can also define a function called do_furigana with the
same signature, to process furigana syllables. Furigana still follows the
Automation 4 model here.
Signature of line function: do_line(subs, meta, styles, lines, line, default_do_line)
Defining a line function is optional, and is often not required. The line
function must be named do_line if it exists. The default_do_line
parameter is the function that would be called if do_line didn't exist.
You can call it to run the default line processing along with your own
processing.
karaskel.lua defines and extends several data structures. Some of the
changes are already listed above under the individual functions.
The styles array is produced by the karaskel.collect_head function and
should be passed to most other karaskel.lua functions. It contains a list
of all styles in the subtitle file, and can be accessed in two ways.
styles.n is a number telling the number of styles in the array.
styles[1] is the first defined style and styles[styles.n] is the last
defined style.
The styles array can also be indexed by style names, such that
styles[style.name] == style. The names are not mangled and the indexing
is case sensitive.
Be aware that modifying the styles will never update the subtitles file,
and conversely updating the styles in the subtitle file will not
automatically be reflected in styles either.
This is a slight extension of the basic style class subtitle line structure.
One field is added:
style.margin_v is a convenience alias for style.margin_t.Full list of fields:
style.class == "style"style.raw - The raw line text.style.section == "[V4+ Styles]"style.name - Name of the style.style.fontname - Name of the font face used by the style.style.fontsize - Font size for the style.style.color1, style.color2, style.color3 and style.color4 - The
four colours used by the style, in regular order. Use
[[extract_color|Automation/Lua/Modules/#extractcolor]] and family to
manipulate these.style.bold - true/false to specify bold/non-bold font face. Can
also be a number to specify font weight, but this is not well supported
and should be avoided.style.italic - Boolean, whether an italic/oblique version of the font
face is used or not.style.underline and style.strikeout - Boolean, whether to apply these
two decorations to the text.style.scale_x and style.scale_y - Scaling in X and Y direction, 100
is neutral.style.spacing - Additional spacing in pixels between individual
characters in text.style.angle - Z axis rotation for the text.style.borderstyle - 1 (one) for regular outlined text, 3 for opaque
box behind subtitles.style.outline - Width of the extended outline around the text.style.shadow - Distance to the shadow behind the text.style.align - Numpad-style alignment for the text on screen.style.margin_l, style.margin_r, style.margin_t and style.margin_b
style.margin_v is an alias for top margin.style.encoding - Windows font encoding ID for the style.style.relative_to - Currently unsupported.style.vertical - Unsupported, tentative AS5 feature.A large number of new fields have been added to the dialogue line class.
Basic fields:
line.class == "dialogue", also for comment linesline.raw - The raw line text.line.section - Usually "[Events]".line.comment - Boolean, true if the line is a Comment line rather than
Dialogue.line.layer - Layer of the line.line.start_time, line.end_time - Start and end times of the line in
milliseconds.line.style - Name of the style used for the line.line.actor - Actor field for the line.line.margin_l, line.margin_r, line.margin_t and line.margin_b -
Margin overrides for the line, a zero value means use margin from style.line.effect - Effect field of the line.line.userdata - Unused.line.text - Dialogue text.Basic added fields, by karaskel.preproc_line_text:
line.text_stripped - Line text with all override tags and vector
drawings removed.line.duration - Duration of the line in millisecondsline.kara and line.furi - Array tables of extended karaoke and
furigana tables, respectively. They do not contain sizing and positioning
data from the beginning.Added fields for sizing, by karaskel.preproc_line_size:
line.styleref - A reference to the Style table representing this line's
selected style.line.furistyle - A reference to the Style table representing this
line's furigana layout style. If there is no style with the right name,
this field is false instead.line.width, line.height, line.descent and line.extlead - Sizing
information for the stripped line text, as returned by
aegisub.text_extents. line.width may also be modified by
karaskel.preproc_line_pos.Added fields for positioning, by karaskel.preproc_line_pos:
line.margin_v - A convenience alias for line.margin_t.line.eff_margin_l, line.eff_margin_r, line.eff_margin_t,
line.eff_margin_b and line.eff_margin_v - Effective margin values for
the line. If the corresponding margin override for the line is non-zero,
that value is used, otherwise the value defined in the style is used.line.halign - One of "left", "center" or "right", the horizontal
alignment of the line, derived from line.styleref.align.line.valign - One of "top", "middle" or "bottom", the vertical
alignment of the line, derived from line.styleref.align.line.left - The left edge X coordinate for the line, assuming its given
alignment, effective margins and no collision detection.line.center - The line centre X coordinate, assuming its given
alignment, effective margins and no collision detection.line.right - The right edge X coordinate for the line, assuming its
given alignment, effective margins and no collision detection.line.top - The top edge Y coordinate for the line, assuming its given
alignment, effective margins and no collision detection.line.middle - The line vertical centre Y coordinate, assuming its given
alignment, effective margins and no collision detection line.vcenter is
an alias for this.line.bottom - The bottom edge Y coordinate for the line, assuming its
given alignment, effective margins and no collision detection.line.x and line.y - X and Y coordinates for the line, suitable for
using in a \pos override tag to get the line's original position.Added fields for linked list access, only available when using the Classic Advanced skeleton:
line.prev, line.next - Access the dialogue line before and after this
one. These might be nil on the first/last dialogue lines. Blank lines,
style lines, header lines etc. are not included in this linked list.Tables for regular karaoke syllables and furigana parts are identical in
(almost) every aspect, and can usually be processed by the same code
without problems. There are a few points to take note of which are marked.
Everywhere it says syl here, you can replace that with furi unless
otherwise noted.
Basic fields, defined by aegisub.parse_karaoke_data:
syl.duration - syllable duration in milliseconds (divide by 10 to get a
number suitable for \k tags.)syl.start_time, syl.end_time - Start and end time of the syllable in
milliseconds, relative to the start time of the line.syl.tag - The name of the tag defining this syllable, without
backslash. It will usually be one of k, K, kf or ko. Note that
kt is not handled. Furigana parts have the same tag as the original
syllable defining them.syl.text - Text including tags of the syllable. Same as stripped text
for furigana.syl.text_stripped - Text of the syllable with all tags removed. For
main syllables, this also has furigana and multi-highlight parts removed.
This is the text you will usually want to use.Additions by karaskel.preproc_line_text:
syl.kdur - Syllable duration in centiseconds, suitable for use in \k
tags.syl.line - Back reference to the line table containing this syllable.syl.inline_fx - Name of the _inline-fx_ for this
syllable.syl.i - Index number of this syllable.syl.prespace, syl.postspace - Space characaters at the start/end of
the syllable. Always blank for furigana. These are spaces included in
syl.text_stripped. You will usually never need this.syl.text_spacestripped - Syllable text stripped for tags and trimmed of
spaces at the start and end. This, syl.prespace and syl.postspace
together can produce the same as syl.text_stripped. You will usually
never need this.syl.isfuri - true if the table is a furigana table, false if it is
not. If you use a single function to process both regular and furigana
syllables, you can use this to do differentiated processing still.syl.highlights - Array table of multi-highlight data for the syllable.
For furigana, there is always exactly one highlight defined. See below
for format of highlight tables.Additions by karaskel.preproc_line_size:
syl.style - Reference to the style used to calculate sizing for this
syllable. This will be the main line style for regular syllables and the
furigana style for furigana. You should always set the style of the
generated lines to this one.syl.width, syl.height - Width and height of syl.text_spacestripped,
as returned by aegisub.text_extents.syl.prespacewidth, syl.postspacewidth - Width of syl.prespace and
syl.postspace respectively. You will usually not need these. Always
zero for furigana.Additions by karaskel.preproc_line_pos:
syl.left, syl.center, syl.right - Respectively left, center and
right aligned positions of the syllable/furigana, for use with different
alignments. The positions are relative to the left edge of the line,
meaning you will need to add a value for line positioning to use these
values to position syllables on screen. There is no guarantee that
syl.right for one syllable is equal to syl.left for the next
syllable.line.left + syl.center
Calculates the default X position of a syllable, suitable for use with
\an2, \an5 or \an8 alignment.
A highlight table defines one highlight of a multi-highlight timed syllable.
Highlight tables are entirely defined by karaskel.preproc_line_text, and
contain the following fields:
hl.start_time, hl.end_time - Start and end time of the highlight, in
milliseconds, relative to the start of the line.hl.duration - Duration of the highlight in milliseconds.