UTAU插件标准

原文链接（日语）作者：UTAU ユーザー互助会@ ウィキ翻译：SuibianP

序言

此篇文章将会详细记述UTAU的插件功能的开发方法。

安装的方法和已制成插件的一览等，请参考UTAU用插件页面。

并且，还含有对目前在其他地方都没有提及的条目的说明。

因此，也混杂有不确定的信息。请知悉。

详细的调查可使用UTAU Ver 0.2.76进行。

UTAU插件标准

基本信息

插件的形式

对于插件，最少需要以下两个文件。

plugin.txt 设定文件

[可执行文件] 插件本体

可执行文件必须能够获取命令行调用参数。

并且，如果准备名为install.txt的文件，将使插件的安装变得容易。

除此之外，含有其他文件也没有关系。

例如：readme.txt

`plugin.txt`的格式

plugin.txt按照以下形式记述。

name=plugintest
execute=test.exe
shell=use
ustversion=scriptversion
notes=all

在name后记录有在UTAU菜单中显示的插件的名称。

在execute后记录有可执行文件的名称。

通常会用CreateProcess来启动插件，但在指定有shell=use的情况下会用ShellExecuteEx来启动插件。因此，也能够执行exe以外的文件（jar、html、hta等）。

ustversion是UTAU0.4.15以后追加的条目。指定了插件脚本的版本。截至目前可指定ustversion=1.00（相当于UTAU0.2.76）、ustversion=1.10（Mode1用音高序列移至Pitches条目）、ustversion=1.20（移调改为Modulation，Mode1用音高序列移至PitchBend`条目）中任意一个。省略时UTAU本体的设定会被使用。

notes是UTAU0.4.15以后追加的条目。在指定此项时，将无视选择范围传递全部音符。省略时仅传递选择范围。

`install.txt`的格式

install.txt是仅在插件安装时被使用的特别的文件。如果事先做好恰当的准备，就只需将以zip格式压缩的插件文件拖放至UTAU中，即可自动安装。即使没有此文件，对插件自身的功能也没有影响。

在插件中，install.txt记述如下内容。

type=editplugin
folder=bar
contentsdir=foo
description=说明

type：若为插件应写作editplugin。 folder：在plugin下创建的文件夹名。不可省略。 contentsdir：解压的文件夹名。若省略则变为与folder相同。 description：可以省略。用一行来写插件的说明。

文件夹构成

在使用install.txt的情况下，需要按如下形式来配布。

爱啥啥.uar

　├install.txt

　└foo（文件夹）

　　├plugin.txt

　　├【可执行文件】

　　└其他文件（若有）

uar是UTAU安装档案专用的扩展名，实际上是变更了扩展名的zip压缩文件。

即使把扩展名保留为zip也能够安装。

请将记作foo的部分替换为在install.txt的contentsdir（若没有则为folder）中填写的文件名。

在不使用install.txt的时候，必须用手动复制到plugins文件夹下等方式安装。

install.txt如上记述时，安装后将变为如下所示。

UTAU安装目录

├utau.exe

├plugins

│　└bar

│　　├plugin.txt

│　　├【可执行文件】

│　　└其他文件（若有）

└其他UTAU相关文件

数据输入输出方法

输入

UTAU本体会将选择范围的信息用临时文件输出后，将该文件路径通过插件的命令行调用参数传递。

插件通过读取该文件来获取音符信息。

输出

插件在编辑选择范围的信息后，将结果覆盖输入的临时文件。

数据格式

从UTAU传递的临时文件是由多个名为节的单位构成的文本格式。

文字编码为ShiftJIS，换行为CR+LF.

节内有存储音符的详细信息的被称作条目的东西。

节

指从[#●]开始直到下一个[#●]之前为止中间的部分。

基本上，一个节对应一个音符。

节有几个种类，各自的作用不同。

[#SETTING]

是存在于临时文件的最前面的节，记载有基本设定。

作为只读，即使变更对于本体侧的信息也不会有任何改变。

输出时，省略也没关系。

Tempo 曲速 VoiceDir 音源文件夹 CacheDir 缓存文件夹 UstVersion 插件用临时文件的版本（针对UTAU Ver.0.4以后，仅在开启设定的“以旧形式条目输出UST文件和插件脚本”时存在）

[#数字]

是记载选择范围的信息的节。

此节不能省略。

作为例外，插件操作被其本身取消时，可以省略任何节。

而且，节的数字没有意义，会根据输出顺序应用于本体的选择范围。

`[#PREV]`, `[#NEXT]`

[#PREV]存储选择范围前一音符的数据。

[#NEXT]中存有选择范围后一音符的数据。

若无前后音符，则没有此节。

输出时，省略也没关系，但如果不省略，就会反映出信息。

并且输出时，未必一定要写在紧邻数字节的前后。

`[#INSERT]`

是在输出时才能够使用的特别的节。

在它被写的位置追加音符。

因为被当作数字节的一种，所以即使写在[#PREV]前或[#NEXT]后，也不会在选择范围以外的位置追加音符。

并且，在选择范围后没有音符且选择范围末尾追加此节的情况下，若未恰当的指定Length，将产生长度0的音符，请注意。

[#DELETE]

是在输出时才能够使用的特别的节。

若以此替换数字节，会删除该音符。

不能删除其他的节。

[#VERSION]

是从UTAU0.4追加的节。

仅在UTAU设定中“以旧形式条目输出UST文件和插件脚本”开启的情况下存在。

截至目前只写作“UST Version 1.20”。

条目

条目在输出时可以省略，此时被UTAU侧解释为该条目内无变更。

因此，无变更音符可只返回节头。

在省略用[#INSERT]插入的节的条目的情况下，UTAU本体会填入某些值。此值和作为音符默认设定的值不同。

所谓条目的各说明中的“默认值”是使用[#INSERT]节追加音符的情况下，不指定任何条目时填入的值。

一定存在的条目

`Length`　音符的长度

格式：Length=整数

定义域：1～7680

单位：Ticks（四分音符=480）

默认值：后一音符的Length（若无则为0）

即使指定超过上限的值，Ver0.2.76也能正常读取，但旧版本会存在音符不能够移动的情况。

并且，用鼠标拖动的输入上限也是7680（下限是15）。

`Lyric`　词

格式：Lyric=字符串

定义域：除例外的全部字符串

默认值：后一音符的Lyric（若无则为空白）

作为例外，不能指定含有换行、节名、条目名+“=”的词。

例如“あ[#INSERT]”、“あPreUtterance=”、“あ$foo=bar”这样的东西。

不过，通过GUI侧的操作等已经变为那样的词时，只要插件侧不进行变更就保持原状。

`NoteNum`　音阶编号

格式：NoteNum=整数

定义域：24～107

单位：音符编号（与MIDI相同）

默认值：后一音符的NoteNum（若无则为24）

从C1=24开始，每半音值上升一。

若指定108(C8)以上，音符会变得无法表示在画面上。

若指定120(C9)以上，音符属性会变得无法打开。

若指定23以下，合成时出现错误。

`PreUtterance`　先行发声

格式：PreUtterance=实数

定义域：不足60000

单位：毫秒

默认值：空白（原音值）

条目本身一定存在，但值可以为空白。

有可能被省略的条目

与音调相关的条目和参数也可以省略，但因为有很多所以后述。

`VoiceOverlap`　重叠部分

格式：VoiceOverlap=实数

定义域：不足60000

单位：毫秒

默认值：空白（原音值）

Intensity　音的强度

格式：Intensity=实数

定义域：0～200

默认值：空白（100）

音量的峰值，200时为-0db，100时变成-6db附近。

要贴合得严密到什么程度可通过P参数指定。

`Moduration`　移调

格式1：Moduration=实数

格式2：Modulation=实数

定义域：-200～200

单位：百分比

默认值：空白（100）

通过UTAU的版本和选项设定，Moduration、Modulation两种格式都能够得到。

使用fresamp系引擎若指定为-101以下，生成的声音会变得很奇怪，请注意。

`StartPoint`　STP

格式：StartPoint=实数

定义域：只要在原音范围内就没有限制？

单位：毫秒

默认值：空白（0）

`Envelope`　包络

格式1：Envelope=p1,p2,p3,v1,v2,v3,v4

格式2：Envelope=p1,p2,p3,v1,v2,v3,v4,%,p4

格式2：Envelope=p1,p2,p3,v1,v2,v3,v4,,p4（无“%”的状态为通过“母音结合”“交给☆我吧”母音结合的情况）

格式3：Envelope=p1,p2,p3,v1,v2,v3,v4,%,p4,p5

格式4：Envelope=p1,p2,p3,v1,v2,v3,v4,%,p4,p5,v5

（无论哪种格式、p,v都是正整数）

定义域：p在音符的范围内和其他的值不矛盾就没有限制？ v是0～200

单位：p是毫秒，v是百分比

默认值：0,5,35,0,100,100,0,%,0,10,100

直到Ver0.2.35的版本中，只有格式1有效。

并且，即使在Ver0.2.36以后的版本中指定格式1，也不再是和以前完全相同的行为。

若使值变为空白则填入0。

`Tempo`　曲速

格式：Tempo=实数

定义域：10～512

单位：BPM(Beats Per Minute)

默认值：[#SETTING]的Tempo

设定此节以后的音符的曲速。

`Velocity`　子音速度

格式：Velocity=小数

定义域：0～200

默认值：空白（100）

`Label`　标签

格式：Label=字符串

默认值：空白

`$direct`　直接输出

格式：$direct=布尔值

定义域：True

默认值：空白

不经resampler（工具2）的加工输出。

因为经过wavtool（工具1）的加工，包络、先行发声等会被反映。

（实际的行为是记述不限于“True”的任何值都会直接输出。

例如即使是$direct=False或$direct=0也会直接输出。在Ver.0.2.77上证实）

`$patch`　wav文件直接输出

格式：$patch=文件名

定义域：指定对于与ust文件相同的文件夹的相对路径中的wav文件名

默认值：空白

不经resampler（工具2）的加工输出。

因为经过wavtool（工具1）的加工，包络、先行发声等会被反映。

wav文件不存在的情况下会变为与休止符同样对待。

若文件名有半角的等号（=）或半角的逗号（,）则无法正常渲染，请注意。

`$region`　选择范围的开始

格式：$region=范围名|范围名|范围名…

默认值：空白

选择范围的开始重复的情况下，用|分隔。

一个ust内存在同一范围名的情况下，在前面存在的选择范围优先被选择。加工$region时请勿重复范围名。

`$region_end`　选择范围的终止

格式：$region_end=范围名|范围名|范围名…

默认值：空白

选择范围的开始重复的情况下，用|分隔。

一个ust内存在同一范围名的情况下，在前面存在的选择范围优先被选择。加工$region时请勿重复范围名。

如果音频缺失，则不会显示。

`@alias`　别名

格式：@alias=别名

Prefix.map适用完成的别名。若无则为向音符输入的歌词。

如果音频缺失，则不会显示。

`@cache`　缓存文件名

格式：@cache=文件路径

缓存文件名。不存在缓存的情况下不被表示。

※在Ver.0.4.18中转移为绝对路径，似乎预定去除缓存路径。

音调（模式1）

`PBType`　滑音类型

格式：PBType=值

定义域：5或OldData

默认值：5

通常请指定5。

OldData是相当初期的UTAU中被使用过的滑音类型。

`Piches`　音调数列

格式1：Piches=整数,整数,整数…

格式2：Pitches=整数,整数,整数…

格式3：PitchBend=整数,整数,整数…

定义域：-2048～2047

单位：音分

默认值：0

以5ticks的步进表示音高。

通过UTAU的版本和选项设定Piches、Pitches、PitchBend每种格式都能够得到。

从插件侧输出哪种格式都没有变化。

被省略的部分全部作为0被处理。

音调数列的开始位置根据UTAU版本有所差异。Ver.0.2.76的情况下为从先行发声的位置被开始。Ver.0.4之后为从在PBStart中被指定的位置被开始。

`PBStart`　音调数列开始位置

格式：PBStart=实数

单位：毫秒

默认值：0

是Ver.0.4以降之后被追加的条目，指示Mode1用音调数列的开始位置。比音符开头更先行的情况保存负的值。

值不存在的情况下意义为0ms，但请注意旧版本中不存在PBStart，永远从先行发声的位置被开始（在Ver.0.2.76证实）。

※若[#VERSION]节不存在且[#SETTING]节中UstVersion条目不存在则可判断为旧版本。

音调（模式2）

滑音点的上限为50。

与此对应，也决定了PBW、PBY、PBM值个数的上限。

此部分条目的详情，由于从官方未能找到信息，为作者的完全推测。

即使从Mode2回归到Mode1的情况下，这些条目的值也会被全部保存。

只要渲染按钮没有被按下，Mode1的音调信息也不会改变。

并且，这里的条目没有默认值。因为用[#INSERT]插入的音符既没有滑音设定也没有颤音设定。

`PBS`　音高曲线最初点

格式1：PBS=整数

格式2：PBS=整数;实数

定义域：-200～200; -204.8～204.7

单位：毫秒; 10音分

最初的点为从音符开始点的相对坐标。

第一个值为时间位置，第二个值代表音高点移动值。

未指定音高点移动值的情况，会输入0。

请注意分隔符为;。

`PBW`　音高点间隔

格式：PBW=实数,实数,实数,…

定义域：只要没有超过音符的终点就没有限制？

单位：毫秒

从最左端点的间隔值开始。

`PBY`　除最初点外的音高点移动值

格式：PBY=实数,实数,实数,…

定义域：-204.8～204.7

单位：10音分

除最初点外的音高点移动值。

被省略部分全部作为0被处理。

从左边第二个点的值按顺序开始。

除最初和最后两个以外没有点，或全部点的移动值为0的情况，有条目被省略的情况。

`PBM`　音高曲线的形状

格式：PBM=文字,文字,文字,…

定义域：未指定、s、r、j中的任意一个

从左按顺序指定各点间音高曲线的形状。

曲线：未指定　直线：s　R型：r　J型：j

被省略的部分全部作为曲线被处理。

全部为曲线的情况，有条目被省略的情况。

`VBR`　颤音

格式：VBR=实数,实数,实数,实数,实数,实数,实数,任意

定义域：0～100, 64～512, 5～200, 0～100, 0～100, 0～100, 0～100, 任意

单位：百分比、毫秒、音分、百分比、百分比、百分比、百分比、无

相对于Length的长度、周期、深度、入、出、相位、高度、未使用

以上述顺序被容纳。

通过直接变更音符的属性，有输入超出上述定义域的值的情况。

Flags

属性的flags+BRE+无共振峰滤波器

格式：Flags=文字列

默认值：空白

在以下所记录的Flag中，含有官方未宣布的内容。

Flag各种各样的效果的说明，请参照音符的属性。

指定数字的一并记录有定义域。

全部为字母表顺序。

即使变为100以上，如果BRE为1以上仍会出声。

好像是官方还没有宣布的Flag。

如果在节内按格式记述，则在Others中反映。

格式开头的一字符的$必须为半角。

条目名只要不含换行、半角空格、半角的/即自由。

值如果含有半角的“=”（等号）或半角的“\n”（反斜杠+小写英文字母的n），在此以后的字符串会缺失。并且，半角空格被替换为半角逗号。除此以外没有限制。

例：$张三=法外狂徒