karaskel.lua

  1. 函数
    1. karaskel.collect_head
    2. karaskel.preproc_line(预处理行)
    3. karaskel.preproc_line_text(预处理行文本)
    4. karaskel.preproc_line_size(预处理行尺寸)
    5. karaskel.preproc_line_pos(预处理行位置)
    6. karaskel.do_basic_layout(基本布局)
    7. karaskel.do_furigana_layout(假名标注布局)
  2. Karaoke skeletons(卡拉OK框架)
    1. Effect Library(特效库)
    2. Classic Advanced
  3. Data structures
    1. Styles array
    2. Style table
    3. Dialogue line table
    4. Karaoke and furigana syllable tables
      1. Highlight table

Automation 4的核心文件 karaskel.lua 内置了许多函数,用来协助Automation 4 Lua方面的卡拉OK特效制作 它定义了几种新的数据结构,也拓展了Automation 4 本身定义的一些。

karaskel.lua 包含 `utils.lua``unicode.lua` 。所以你在使用karaskel.lua时不必再单独include这两项。

karaskel.lua 的用武之地主要是卡拉OK特效,它也可以被用来进行一些简单的文字样式调整。

函数

karaskel.collect_head

摘要: meta, styles = karaskel.collect_head(subtitles, generate_furigana)

读取字幕文件来获取所有的头部信息和样式定义,也可以为假名生成新的样式。

使用 collect_head 一般情况下是你在处理函数中做的第一步。

返回的 meta 表包含着以下全部, Name: Value 对应到 [Script Info] 部分。它也包含 meta.res_xmeta.res_y ,它们对应到 PlayResX and PlayResY

返回的 styles 表包含着全部已定义的样式, 也包含着自动生成的假名样式, 样式结构在style表中占有单独的位置,如style.margin_v (又称 style.margin_t), 为了方便, styles 可以通过样式名称 (区分大小写,不可缺内容) 和数字来指定。 styles.n 是样式存储的编号, styles[1] 就是第一个被定义的样式。

karaskel.preproc_line(预处理行)

摘要: karaskel.preproc_line(subtitles, meta, styles, line)

为单行字幕计算尺寸、位置和其它信息。这个函数按顺序调用 karaskel.preproc_line_text, karaskel.preproc_line_sizekaraskel.preproc_line_pos

这个函数不会返回值,但是在修饰 line 表的时候例外。详见下。

karaskel.preproc_line_text(预处理行文本)

摘要: karaskel.preproc_line_text(meta, styles, line)

预处理单行的文本。 metastyles 是由 [[karaskel.collect_head|karaskel.lua#karaskel.collect_head]] 返回的表。

这个函数不会返回值,但是在修饰 line 表的时候例外:

这个函数不计算任何尺寸和位置信息。 (事实上它根本不使用 meta 或者 styles 之前获取到的尺寸位置信息)

karaskel.preproc_line_size(预处理行尺寸)

摘要: karaskel.preproc_line_size(meta, styles, line)

为整行、所有的音节和假名标注计算尺寸,参照行样式信息。

这个函数不会返回值,但是在修饰 line 表的时候例外:

这一部分不涉及位置信息的计算。

如果 line 看起来没被 karaskel.preproc_line_text 处理过,那么这个步骤会自动完成。

karaskel.preproc_line_pos(预处理行位置)

摘要: karaskel.preproc_line_pos(meta, styles, line)

计算行、卡拉OK和假名标注的位置信息。

当没有可用的假名标注样式时,这个函数借助 karaskel.do_basic_layout, 当有可用的假名标注样式时借助 karaskel.do_furigana_layout 。假名布局算法可能改变行的计算宽度。

这个函数不会返回值,但是在修饰 line 表的时候例外:

此外, line.karaline.furi 表是被布局函数调用,然后加上位置信息。

详见这部分 data structures

如果没有找到任何行的尺寸信息, karaskel.preproc_line_size 会被调用, 它可能会转而调用 karaskel.preproc_line_text

karaskel.do_basic_layout(基本布局)

这个函数不是被直接调用的,它更像是一个 karaskel.preproc_line_pos 的辅助函数。

它为 line.kara 表运行一个简单的布局算法,简单地计算一行中各个音节的位置。位置信息被添加到各个音节。

line.furi 表在这个函数中不被处理。

karaskel.do_furigana_layout(假名标注布局)

这个函数也不是被直接调用的,它更像是一个 karaskel.preproc_line_pos 的辅助函数。

它为运行一个高级的布局算法,来把卡拉OK音节和假名标注整齐地排布,还能防止重叠。对这部分使用的算法感兴趣的人可以读读源码。

这个函数为 line.karaline.furi 表添加位置信息。它也有可能改变 line.width ,因为行宽度可能受假名标注影响而变化。

Karaoke skeletons(卡拉OK框架)

卡拉OK框架是指帮助你构筑卡拉OK特效的一套框架。你可以在一些自定义函数中使用它,来解决特定的特效问题,框架中的内容会多次被调用。你具体需要写什么样的函数也取决于卡拉OK框架。

Effect Library(特效库)

主函数: karaskel.use_fx_library_furi(use_furigana, add_macro)

调用 karaskel.use_fx_library_furi 函数为当前脚本安装 特效库 框架。script_namescript_description 全局变量用来命名导出滤镜。 如果 use_furigana 为真, 则会生成专门的标注假名样式。 如果 add_macro 为真, 则会在导出滤镜处添加宏。

使用特效库功能的前提是在每一打好K值行的特效栏填写了你希望应用的特效类型(名称)。 如果你想在一个文件里应用多种卡拉OK效果,这是一个很好的选择。

当特效库函数被调用,它会首先为每个对话行调用 "fx_特效" 。举个例子, 如果某个对话行的特效栏填写的是 "jump", 则名为 fx_jump 的函数将会被调用。对于特效栏为空的对话行, 函数 fx_none 将会被调用。

如果指明的 fx 函数并不存在,那么原始的行将会被保留。否则,原始行是否存在取决于 fx 函数在返回部分的写法。返回真值则意味着保留原始行,否则将会把原始行设置为注释行。

fx 函数用法: keep = fx_effect(subtitles, meta, styles, line, fxdata)

fxdata 指的是特效栏中声明特效类型后紧跟的特效名称。 fx 函数的所有输出都是 subtitles 被处理后添加到字幕文件中的行。

简化的主函数: karaskel.use_fx_library(add_macro)

_furi 变种相同,除了 use_furigana 被去除;它被假定为false。

Classic Advanced

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.

Data structures

karaskel.lua defines and extends several data structures. Some of the changes are already listed above under the individual functions.

Styles array

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.

Style table

This is a slight extension of the basic style class subtitle line structure.

One field is added:

Full list of fields:

Dialogue line table

A large number of new fields have been added to the dialogue line class.

Basic fields:

Basic added fields, by karaskel.preproc_line_text:

Added fields for sizing, by karaskel.preproc_line_size:

Added fields for positioning, by karaskel.preproc_line_pos:

Added fields for linked list access, only available when using the Classic Advanced skeleton:

Karaoke and furigana syllable tables

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:

Additions by karaskel.preproc_line_text:

Additions by karaskel.preproc_line_size:

Additions by karaskel.preproc_line_pos:

Example
line.left + syl.center

Calculates the default X position of a syllable, suitable for use with \an2, \an5 or \an8 alignment.

Highlight table

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: