【WIP】Synthesizer V 插件开发入门（1）
图源：紺屋鴉江 - 《銀河》，Pid：94649749
写在前面
本文并非“零基础入门”型的文章。阅读此文章前，建议你已经：
- 使用过 Synthesizer V Studio（即 SVR2，以下用此简称代替），了解过 VOCALOID，知道“插件”的作用是什么；
- 已购买 Synthesizer V Studio Pro 版本，以便于插件的开发与调试；
- 有一定的编程经验，使用过 Lua 语言；
Synthesizer V Studio Pro的正版授权可从 平行四界官方淘宝店 或 Dreamtonics官方淘宝店 获取。关于 Lua 编程的资料数不胜数，可从 菜鸟教程 等网站获取。
另外，阅读时，可以配合下面两个文档：
- Home - Synthesizer V Studio Scripting Manual，官方的 Synthesizer V 插件 API 文档；
- Synthesizer V Studio 用户手册，由 磷元素P 大佬翻译的 Synthesizer V 使用手册和插件 API 文档；
正文部分存在问答部分，可能与后文的知识关联。你可以按顺序阅读，也可以在阅读完其他内容后再阅读问答部分。
以下是文章正文。
脚本存放位置
SVR2 的软件数据默认保存在“我的文档”下，而脚本放置在其中的“scripts”子目录中。
以 Windows 系统为例，如果你没有移动过“我的文档”位置，那么路径应该是：
1 | C:\Users\<你的用户名>\Documents\Dreamtonics\Synthesizer V Studio\scripts |
你可以在其中创建子目录分类存放不同种类的脚本。SVR2 安装时附带的插件默认放置在“Utilities”子目录下。
插件的基本结构
SVR2 Pro 支持两种插件格式：JavaScript 插件，使用嵌入式的 Duktape 解释器；以及 Lua 插件，使用嵌入式的 Lua 5.4解释器。这里选择 Lua 作为编程示例语言，以便有 VOCALIOID 插件开发经验的人快速转向 SVR2 的插件开发。
SVR2 插件在结构上主要有以下几个部分：
- 插件信息函数：
getClientInfo() - 本地化函数：
getTranslations() - 入口点函数：
main()
下面分别进行说明。同时注意，SVR2 软件在启动时会将所有的插件代码载入内存（但不会执行除 getClientInfo() 和 getTranslations() 外的其他部分），因而对插件代码做出的改动需关闭 SVR2 再启动 SVR2 才可生效。
插件信息
插件信息由函数 getClientInfo() 控制。作用与 VOCALOID 的 JobPlugins 中 mainfest() 函数的作用类似，保存插件的名称、维护者、兼容性等信息。
其结构如下：
1 | --[[ |
其中：
name：字符串，为插件的名称。会作为 SVR2 软件中“脚本-启动脚本”菜单中的显示名称。可以使用本地化字符串（将在后文讲解）。
author：字符串，为插件的作者信息，仅起提示作用，不会显示在软件中。同样可以使用本地化字符串。versionNumber：数字，为插件的版本号，仅起提示作用，目前在 SVR2 内不会产生任何动作。minEditorVersion：可使用该插件的最低 SVR2 版本号。SVR2 的版本号为 6 位 16 进制数字。例如：1.4.0 版本对应的版本号为0x010400。上述例子中的版本号65540转为 16 进制得0x010004，对应 SVR2 版本 1.0.4。若该值大于当前使用的 SVR2 版本号，则会触发错误提示。
问：既然 SVR2 会在启动时执行
getClientInfo()，那么是否可以在这个函数中添加其他的语句实现“随 SVR2 启动而自动执行”？
答：是可以的，但过程不能阻塞。阻塞会使 SVR2 卡在启动画面。来看一个有点超纲的例子：
1 | function getClientInfo() |
启动 SVR2 后的效果：
此处插件伴随 SVR2 的启动而自动启动了。关于插件是如何定义和显示 GUI 的，将在后文讲解。
本地化
SVR2 内置多种界面语言，而插件的本地化功能可以使插件可根据 SVR2 界面语言的不同使用不同的字符串。这样一来，插件的翻译和更新都变得更加容易。VOCALOID 无此功能，因此在分发 VOCALOID 插件时经常需要同时分发多个翻译版本。
插件的本地化由函数 getTranslations() 控制。
其基本结构如下：
1 | --[[ |
其中：
en-us：字符串，为语言代码，由形参langCode给出。更多的语言代码可在 Language designators with regions 查看。常见的语言代码：- 中文简体：
zh-cn - 中文繁体：
zh-tw - 英语：
en-us - 日语：
ja-jp
- 中文简体：
return：return的是一个二层嵌套的表。每一个子表都是如下形式：1
{'默认语言下的字符串', '目标语言下的字符串'}
- 默认语言下的字符串：当
getTranslations()函数中对langCode的条件判断均不满足，无return时，将使用该字符串。本例中，“默认语言下的字符串”是英语“Hello”。当 SVR2 的语言是日语（ja-jp）时，字符串仍将使用“Hello”。 - 目标语言下的字符串：当
getTranslations()函数中对langCode的条件判断满足且return二层链表时，将使用该字符串。本例中，若 SVR2 的语言是中文（zh-cn）时，字符串将使用“你好”。
- 默认语言下的字符串：当
SV:T()：使用本地化字符串。按照上述规则返回默认语言下的字符串或目标语言下的字符串。
问：既然 SVR2 也会在启动时执行
getTranslations()，那么是否也可以在这个函数中添加其他的语句实现“随 SVR2 启动而自动执行”？
答：是可以的，但过程依然不能阻塞。阻塞的过程会使 SVR2 卡在启动界面。
也需同时注意它与 getClientInfo() 间的区别：
不能使用 SVR2 提供的同步的 GUI 相关函数，只能使用其异步版本。同步的 GUI 函数会使插件从插件列表中消失。（可能是Bug？）
例子如下：
1
2
3
4
5
6
7
8
9
10
11
12
13function getTranslations(langCode)
local form = {
title = 'Execute!'
}
-- 非阻塞的 GUI 函数
SV:showCustomDialogAsync(form, nil)
-- 照常 return 翻译
if langCode == 'zh-cn' then
return {
{'Plugin Name', '插件名字'}
}
end
end对同步和异步的 GUI 函数的细节将在后文描述。
每次插件启动都会执行
getTranslations()，而getClientInfo()只会在 SVR2 启动时执行一次。搭配这两个函数可以实现复杂的插件自动启动过程。一个稍微超纲的例子如下：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20function getTranslations(langCode)
local form = {
title = 'getTranslations() 执行了！'
}
SV:showCustomDialogAsync(form, nil)
if langCode == 'zh-cn' then
return {
{'Plugin Name', '插件名字'}
}
end
end
-- 入口点
function main()
local form = {
title = 'main() 执行了！'
}
SV:showCustomDialog(form)
SV:finish()
end从 SVR2 的“脚本”菜单中启动插件，效果如下：
在顺序上，
getTranslations()优先于main()被执行。getTranslations()中不能使用SV:T()。使用SV:T()不会报错，但始终返回默认语言下的字符串。
问: 既然
getClientInfo()与getTranslations()都会在启动时被执行，那么它们的先后顺序是什么？
答：getTranslations(langCode) 优先于 getClientInfo() 被执行。
入口点
就像C语言程序需要 int main() 作为入口点才能编译为独立的直接运行的程序一样，插件也有类似的入口点函数 main()。
其结构如下：
1 | --[[ |
该函数只会在插件从“脚本”菜单中启动时被执行。
插件界面
界面是插件的一个重要组成部分。用户通过界面了解插件的作用、通过界面提供和调整插件所需的参数、通过界面获取插件的各种提示信息等。
SVR2 提供了两套显示 GUI 的函数：同步的函数和异步的函数。所有函数均是宿主对象 SV 的方法。
宿主对象
对象 SV 就是宿主对象（Host Object）。宿主对象保存了当前宿主（即正在运行的 SVR2 软件）内的部分数据（如软件信息、播放状态、音符状态等）。SVR2 为了方便开发者，还在 SV 对象的父类中定义了许多的工具函数（如频率与音名互相转换、时间单位互相转换等，在后文详细说明）。
宿主对象的父类会在 SVR2 启动时被实例化。同一时间运行的两个 SVR2 中的宿主对象相互独立。
界面类型
- 输入框
由函数 SV:showInputBox()（同步）及函数 SV:showInputBoxAsync() （异步）定义。提供输入框的窗口标题、输入框上方的提示信息、输入框的默认值（异步函数还需提供回调函数的函数名）作为函数参数，用户的输入内容作为返回值。
例子如下：
1 | -- 同步版本 |
- 消息框
由函数 SV:showMessageBox() （同步）及函数 SV:showMessageBoxAsync() （异步）定义。提供消息框的窗口标题和消息内容（异步函数还需提供回调函数的函数名）作为参数，无返回值。
例子如下：
1 | -- 同步版本 |
- “确定-取消”框
由函数 SV:showOkCancelBox() （同步）及函数 SV:showOkCancelBoxAsync() （异步）定义。名称来自于窗口中的两个按键“确定”和“取消”。提供“确定-取消”框的窗口标题和窗口内容（异步函数还需提供回调函数的函数名）作为参数。当用户按下“确定”时返回布尔值“true”，按下“取消”时返回布尔值“false”。
例子如下：
1 | -- 同步版本 |
- “是-否-取消”框
由函数 SV:showYesNoCancelBox() （同步）及函数 SV:showYesNoCancelBoxAsync() （异步）定义。名称来自于窗口中的三个案件“是”、“否”与“取消”。提供“是-否-取消”框的窗口标题和窗口内容（异步函数还需提供回调函数的函数名）作为参数。返回字符串“yes”、“no”和“cancel”，分别对应用户按下“是”、“否”和“取消”按键。
例子如下：
1 | -- 同步版本 |
同步函数与异步函数
每个 GUI 函数均有同步的和异步的两个版本。在函数定义上，异步函数以“Async”结尾且均没有返回值，形参较同步函数多一个回调函数名称。
与JavaScript中的Async/Await、Python中的yield一样，异步函数不会阻塞脚本的执行，而同步函数会阻塞脚本的执行，直到窗口关闭（得到返回值）。
自定义界面
预定义的几种界面类型只提供了有限的输入类型（输入框的字符串、带按钮的窗口框的按钮等），很难满足功能复杂的插件的要求。因此 SVR2 提供了绘制自定义界面的函数：SV:showCustomDialog() （同步）与 SV:showCustomDialogAsync() （异步）。
其基本结构如下：
1 | --[[ |
按钮类型
按钮类型共有两种：
- “OkCancel”：对应着界面类型中的“确认-取消框”。
- “YesNoCancel”：对应着界面类型中的“是-否-取消”框。
- “Message”：对应着界面类型中的消息框。（注：可能是翻译问题，按钮上的文字是“取消”而不是“确定”，后续可能修正）
提示信息
提示信息直接显示在标题的下方，可以用来概述插件用途、指示用户操作或显示插件作者信息等。支持使用转义字符。
举例如下：
1 | local form = { |
【WIP】Synthesizer V 插件开发入门（1）