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)

yin8086/aegisub32_note_Chinese.md

Aegisub32 Lua Script学习

一、整体结构

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

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

3. 执行过程

二、注册

1. 特性

2.元数据

3. 注册函数

a. 注册宏

b 注册导出过滤器

4. 回调函数定义

a. 宏处理回调

b. 宏验证函数

c. 过滤器函数

d. 过滤器配置器

三、重要API

1. Subtitles对象

2. Line对象

a. info特有成员

b.style 特有成员

c.dialogue 特有成员

3. 进度条

4.调试

5.对话框

1.请求用户输入

2.打开文件

3.另存为文件对话框

6. 重要API