Aegisub32 Lua Script学习笔记（官方文档翻译总结）

aegisub_note_chinese.md

Aegisub32 Lua Script学习

@(日常笔记)

一、整体结构

1. 全局变量——描述脚本元数据

• script_name
• script_description
• script_author
• script_version

2. 脚本功能——均可包含0个一个或者多个

• Macro
• Export Filter

3. 执行过程

• 顶层代码会被执行一遍
• 通常的做法是：引入模块，定义函数，然后向aegisub32注册
• 通常顶层代码只需要访问lua_automation_version 和注册函数即可
• 当在菜单中被点击时，被注册的处理函数会被注册。传入的第一个参数是subtitles对象，它是一个类数组的对象，但是多了增删改字幕行的功能。

二、注册

1. 特性

特性指脚本给用户的提供的一些功能。是一个提供能功能以及展示UI的回调函数。

• Macro 出现在Automation菜单，有名字，描述，处理函数以及一个可选的验证函数（决定此功能在某个状态下是否可用）
• Export Filter 出现在导出字幕对话框中，会在字幕导出时被应用。包含名字，描述，处理函数，以及一个可选的选项面板提供器。提供器是一个函数，会返回配置对话框定义结构体，用于导出对话框展示此个导出过滤器支持的配置选项，用于用户配置。

2.元数据

上面已经提到过，基本的4个，都是可选的

3. 注册函数

a. 注册宏

aegisub.register_macro(name, description, processing_function, validation_function, is_active_function)

• name 名称， 支持使用Foo/a，Foo/b，两者会被弄在一个子菜单中。
• description。 简介, 建议<= 60
• validation_function。验证函数，上面说过
• is_active_function。 是否在菜单项中带有对勾，打对勾时执行的函数

b 注册导出过滤器

aegisub.register_filter(name, description, priority, processing_function, configuration_panel_provider)

• name 名称， 支持使用Foo/a，Foo/b，两者会被弄在一个子菜单中。
• description。 简介, 建议<= 60
• priority。优先级。执行顺序
• processing_function。 处理函数
• configuration_panel_provider。可选，用于定义配置面板

4. 回调函数定义

a. 宏处理回调

process_macro(subtitles, selected_lines, active_line)

• subtitles (user data) - 字幕对象【引用】
• selected_lines (table) - 选择的字幕行索引组成的数组. 初始状态下，table内的值是行索引。只有dialog类型的字幕才会被选择
• active_line (number) - 当前正在被编辑的行的索引。
• 【返回】最多返回两个值：新的selected_lines table，（当函数返回后被选中的行的索引）。新的active_line 的索引，应包含在新的selected_lines table内。

b. 宏验证函数

validate_macro(subtitles, selected_lines, active_line)

速度应很快，否则卡住UI线程。

• subtitles (user data) - 字幕对象。【只读】
• 【返回值】，Boolean。有时也返回string，告诉用户为何此宏无法运行。

c. 过滤器函数

process_filter(subtitles, settings)

这里操作的永远是字幕本身，而是其copy。

• subtitles (user data) - 字幕对象。【copy】
• settings(table)。配置信息
• 【返回】不返回

d. 过滤器配置器

get_filter_configuration_panel(subtitles, old_settings)

不要阻塞主线程UI

• subtitles (user data) - 字幕对象。【只读】
• old_settings(table)。原先配置
• 【返回】返回配置table

三、重要API

1. Subtitles对象

• 行数(number)

num_lines = #subtitles
num_lines = subtitles.n
for i = 1, #subs -- 非O(1)，但此时会缓存

• 获取某一行(table) ，索引为(number)

line = subtitles[i]

• 添加一行 （文件结尾）。索引式最快

subtitles[0] = line   -- lua索引从1开始，0出发append
subtitles.append(line)
subtitles.append(line1, line2, ...)

• 插入行，在i(number)索引之前。会使插入行后面的索引失效。索引式最快

subtitles[-i] = line
subtitles.insert(i, line)
subtitles.insert(i, line1, line2, ...)

• 替换一行

subtitles[i] = line

• 删除行。删除行后面的会迁移，索引会失效。

subtitles[i] = nil
subtitles.delete(i)
subtitles.delete(i1, i2, ...)
subtitles.delete({i1, i2, ...})
subtitles.deleterange(first, last)

• 创建恢复点

aegisub.set_undo_point(description)

2. Line对象

一般为info，style, dialog,unknown四类

• info 键值对(Script Info内的)
• style 样式定义
• dialogue 真正字幕行
• unknown 未知行

一般有如下成员

• class (string) 具体的类型，为Info，Style之类的
• raw (string) 原始行字符串
• section (string) 在所属文件的哪一部分

a. info特有成员

• key (string) 首尾空格删除
• value (string) 首尾空格删除

b.style 特有成员

详见karaskel.lua

c.dialogue 特有成员

详见karaskel.lua

3. 进度条

aegisub.progress.set(percent)
aegisub.progress.task(msg, ...) -- 显示信息
aegisub.progress.title(title, ...) -- 标题
cancelled = aegisub.progress.is_cancelled() -- 应调用aegisub.cancel()

4.调试

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

0-fatal, 5-trace。

5.对话框

1.请求用户输入

详细参数见http://docs.aegisub.org/3.2/Automation/Lua/Dialogs/

config = {
    {class="label", text="Times to frobulate", x=0, y=0},
    {class="intedit", name="times", value=20, x=0, y=1}
}
btn, result = aegisub.dialog.display(config,
        {"Frobulate", "Nevermind"},
        {"ok"="Frobulate", "cancel"="Nevermind"})
if btn then
    frobulate(result.times)
end

2.打开文件

filename = aegisub.dialog.open('Select file to read', '', '',
                               'Text files (.txt)|*.txt', false, true)
if not filename then aegisub.cancel() end

file = io.open(filename, 'rb')
....

3.另存为文件对话框

file_name = aegisub.dialog.save(title, default_file, default_dir, wildcards, dont_prompt_for_overwrite=false)

6. 重要API

*aegisub.cancel() 回滚

• width, height, descent, ext_lead = aegisub.text_extents(style, text) 获取系统字体特性，计算字体渲染的出来的具体像素大小。不适用于处理带换行，布局的文本，而是用来处理超长文本的缩略显示的

• frame = aegisub.frame_from_ms(ms)

• ms = aegisub.ms_from_frame(frame)

• xres, yres, ar, artype = aegisub.video_size()

• keyframes = aegisub.keyframes()

• path = aegisub.decode_path(encoded_path)