关于QPitchEditor

QPitchEditor - 基于 UTAU 的歌声合成前端

关于QPitchEditor
- 简介
- 依赖关系
  - Qt
  - LibUTAU216
- 鸣谢
- 关于作者
- 其他
- 联系方式

简介

QPitchEditor 是使用 Qt 开发、以更便捷的方式实现 UTAU 的功能而设计的工具，是 UTAU 的第三方编辑器。
QPitchEditor 主要服务于 UTAU 的使用群体，它既可以作为插件供 UTAU 本体调用，也可以独立编辑 UST 文件。
QPitchEditor 是共享免费软件，它将会终身免费供各位用户使用，不时进行更新。
您可以在不修改本程序任何原始文件的条件下自由复制、分发本程序。

依赖关系

Qt

QPitchEditor 使用 Qt 5.15.2 开发，以动态链接形式发布。
开发：Qt Company
协议：LGPL v3
链接：Qt | 为嵌入式和桌面应用开发而生的跨平台软件开发框架

LibUTAU216

QPitchEditor 使用了 LibUTAU216（C++类库），感谢前辈的分享。
作者：SHINTA P
协议：Attribution-NonCommercial-Inheritance
链接：Lib UTAU 帮助页

鸣谢

Synthesizer V Studio

图形界面参考了 Synthesizer V。
开发：Dreamtonics
链接：Synthesizer V | Dreamtonics株式会社

UTSU

图形界面参考了 UTSU。
开发：titinko
链接：UTSU - 跨平台声音合成前端

参与开发与内测

Jungle
小P孩儿呐，史蒂芬王富贵
东云家的嘤皇阿光，Rocker飞鹰
洛温阿特金森

关于作者

与各位一样，是 UTAU 的粉丝，对 UTAU 的原理有一定的研究，但调音能力在水平线以下。
主要使用 C++ 为工具，在开发 QPitchEditor 前制作了一大堆 UTAU 插件，自此对 UTAU 爱到一发不可收拾。
不是音乐专业，天生五音不全。
幻想将来做一个声音合成引擎。
Sleepwalking 永远的神。

其他

本页面使用 mdBook 设计，感谢 GitHub Pages 提供服务器。
如果您在使用中发现任何 Bug，请第一时间联系我修改。

联系方式

QQ：2208325774
Email：trueful@163.com
BiliBili：UID 87172593
Twitter：@SineStriker

更新日志

作者的更新记录以及拖更的理由

开发日志

2021.2.2

更改了音符数据的存储方式
重写 LibUTAU 类，完成了 Qt 专用的 LibUTAUForQt
完善合成算法，使之直接从音符读取数据

2021.2.1

Bug 修复：修复了先行声音吞掉前驱音符的错误
推导咬合校正算法，实现不需要依赖本体提供校正结果

2021.1.25

Bug 修复：更正了合成算法的一些错误
Bug 修复：更正了变曲速导致的合成器参数错误
使用 QMediaPlayer 播放音频

如何安装

如何使用

基本功能

显示

内置工具

其他

提供给开发者

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`　子音速度

渲染时的自动调整完成的重叠部分值。

`@stpoint`　自动调整完成的STP

格式：@stpoint=实数

渲染时的自动调整完成的STP值。

`@filename`　渲染使用文件名

格式：@filename=文件名

渲染中被使用的音源文件名。

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

`@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各种各样的效果的说明，请参照音符的属性。

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

`Y`　伸缩范围的BRE比例

定义域：0～100

默认值：100

`/`　切换为高速化批处理用引擎

高速化批处理时被使用记号的默认。

大概可以变更。

自定义条目

格式：$条目名=值

用户可以定义自定义条目。

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

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

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

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

例：$张三=法外狂徒

UTAU 后端机制

UTAU 调教的细节。

Mode1 音高曲线

Mode 1 音高曲线脚本解析

序言

可能很多人觉得 Mode 1 没用，主要是 UTAU 的 Mode 1 操作流程是在是不太令人满意。（UTAU插件标准也把这个略去了）
但是其实 Mode 2 的音高曲线在传给引擎前，是先转化成 Mode 1 的形式的，因为重采样器只看得懂连续的音高曲线采样点。

PBStart

音高曲线的起点，其值等于 先行声音（校正后）+ STP（校正后），再取负
一般不应手动修改

PitchBend

以 PBStart 为起点，每 5 ticks 记录一个音高采样点（即一个四分音符 96 个）
采样点为整数，范围 -2048~2047
采样点的值为偏离当前音符的音阶的程度，一个半音相当于 100
空白相当于 0，如果末尾全是 0，可以省略

PBType

通常都是 5

示例

脚本

PBType=5

PitchBend=0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,3,9,18,31,46,64,84,106,130,155,181,208,235,261,286,311,334,355,374,390,403,414,421,426,426,424,418,410,398,383,366,346,325,301,277,251,225,199,172,147,122,99,78,58,41,27,16,7,2,0

PBStart=0.0

形状

Mode2 音高曲线

Mode 2 音高曲线脚本解析

序言

对插件标准的一些补充

PBS

作用

指定音高曲线第一个控制点的坐标

格式

格式1：PBS=整数
- 单位：毫秒
- 表示偏离音符开始点的时间
格式2：PBS=整数;实数
- 单位：毫秒；1/10 半音
- 第一个值为偏离时间，第二个值为偏移当前音符音阶的程度
- 如果未指定第二个值，相当于 0
- 当前驱音符是休止符时，第二个值才有效

PBW

作用

从第二个控制点开始，指定每个控制点与前驱控制点的间隔
可能用记录间隔代替记录绝对时间坐标更节省空间

格式

PBW=实数,实数,实数,…
- 单位：毫秒

定义域

应当全部是非负数（虽然是负数 UTAU 也接受，但是效果很奇怪）
最后一个点不超过当前音符末尾（不考虑后继音符）

PBY

作用

从第二个控制点开始，指定每个控制点偏离当前音符音阶的程度

格式

PBY=实数,实数,实数,…
- 单位：1/10 半音

定义域

-204.8～204.7，空白

注意事项

空白作为 0 被处理，被省略的部分全部作为 0 被处理。
除最初和最后两个以外没有点，或全部点的移动值为0的情况，该条目可能被省略。

PBM

作用

从第二个控制点开始，指定每个控制点与前驱控制点连线的形状

格式

PBM=字符,字符,字符,…

定义域

空白、s、r、j中的任意一个
- 曲线：空白
- 直线：s
- R 型：r
- J 型：j

注意事项

被省略的部分全部作为曲线被处理。
全部为曲线的情况，该条目可能被省略。

处理方式

曲线：1/2 周期的余弦曲线
R 型：1/4 周期的余弦曲线，下凸
J 型：1/4 周期的余弦曲线，上凸

VBR

作用

指定颤音的形状

格式

VBR=实数,实数,实数,实数,实数,实数,实数,任意

定义域

长度：0～100,
周期：64～512（实际上只要是正整数就行）
深度：5～200
淡入：0～100
淡出：0～100
相位：0～100
偏移：0～100
强弱：任意（没有作用的值）

处理方式

长度：占音符长度的比例
深度：单位为 1/100 个半音
淡入：从颤音头部往后，占颤音长度的比例
淡出：从颤音尾部往前，占颤音长度的比例
相位：单位为 1/100 个周期（颤音本身是正弦多周期）
偏移：偏离音阶的程度，单位为 1/100 深度

咬合校正

原文链接（日语）作者：SHINTA P

咬合校正

声明

咬合校正是 UTAU 计算音符长度时非常重要的环节，虽然 Ameya 大大没有公布实际的校正算法，但是通过其他前辈的文档以及我自己的一些推导，在做了大量实验比较后，比较好地还原了校正过程。

为什么需要校正

如果一个音符的先行声音长度太大，并且它的前驱音符长度比较短，在这种情况下，理论上就会比前驱音符先发声。（换句话说，前驱音符直接被缩没了）
例如，当曲速为360时（四分音符的时长为167毫秒），有两个连续的四分音符（歌词分别为“あ”与“い”），如果后者的先行发声（设重叠为0）为200毫秒，那么理论上前者就会被全部被挤占。

为了防止出现这种奇怪的情况，在UTAU中，当一个音符的先行声音使前一个音符缩短了一半以上的长度时，为了让前一个音符能存活一半长度（即用ticks计算的毫秒数除以2），该音符的先行声音、重叠和STP会被调整。
在示例情况下，它实际的先行声音会被调整为约83毫秒，使得前驱的音符能存活一半。
我（自作主张）地把这种调整称为“咬合校正”。

校正过程

辅音速度

指定先行声音和重叠部分的伸缩倍率，可以在0到200的范围内指定，并且100不会扩展或收缩

辅音速度值越大，速度越快，辅音部分被缩得越短。辅音速度0在时间轴上是两倍，200是一半

设 k 是实际伸缩倍率，v 是辅音速度，则 k = 2^(1 - v / 100)

初始变量值

初始的先行声音与重叠从属性面板中读取，如果属性面板为空，则从原音设定读取

初始 STP 从属性面板读取，如果属性面板为空，则为 0

音符理论时长（ms） = 音长（Ticks）/ 480 * 60 / 音符曲速 * 1000
伸缩倍率 = 2^(1 - 辅音速度 / 100)
先行声音 = 初始先行声音 * 伸缩倍率
重叠 = 初始重叠 * 伸缩倍率

最大先行长度

如果前驱音符是一般音符，最大先行长度 = 前驱音符理论时长 / 2
如果前驱音符是休止符，最大先行长度 = 前驱音符理论时长

咬合校正的启动条件

先行声音 - 重叠 > 最大先行长度

咬合校正率（系数）

咬合校正率 = 最大先行长度 /（先行声音－重叠）

校正后的变量值

校正后的先行声音 = 先行声音 * 咬合校正率
校正后的重叠＝重叠 * 咬合校正率
校正后的 STP = 先行声音 - 校正后的先行声音 + 初始 STP

音符实际长度与二次校正

末端偏移 = 后继音符的重叠（校正后） - 后继音符的先行声音（校正后）
如果后继音符设置了一个非常大的重叠值，或者其他原因，使得末端偏移超过后继音符的理论时长，那么就取后继音符的理论时长
实际长度 = 理论时长 + 先行声音（校正后）+ 末端偏移

UTAU 中的 Bug

在测试变速曲的时候发现了一个严重的问题，这一问题告诉插件开发者，UTAU 提供给插件的校正后的先行/重叠/STP是有问题的。
我们知道，音符长度（毫秒）= 音长(ticks) / 480 * 60 / 曲速 * 1000
UTAU在UI中执行当前音符的咬合校正计算时，用的是当前音符的曲速去计算前驱音符的长度，但是在传给引擎参数时又正确地用了前驱音符的曲速。
也就是说，它显示在UI上的，与它传给插件的校正结果都是有问题的！（幸好传给引擎的是对的）
有以下三种情况
1. 在前驱音符曲速与当前音符的相等时，不会引起什么问题。
2. 在前驱音符曲速小于当前音符的时，那就意味着UI中计算的前驱音符长度变短了，有可能原本不用启动校正但是却被校正了。
3. 在前驱音符曲速大于当前音符的时，那就意味着UI中计算的前驱音符长度变长了，有可能UI中的校正力度可能不够大，导致UI中计算的校正后的先行声音照样能吞掉前驱音符一半长度（或者吞掉前驱休止符的整个长度，导致合成器接收到的音符长度是负的，造成严重错误）。
建议：所以在插件里，如果要使用校正后的先行/重叠/STP，最好还是自己算，或者在检测到前驱音符与当前音符曲速不相等时不使用UTAU提供的校正结果。
在UTAU中手动修改的STP会直接与在校正后的STP相加作为新的STP传给引擎，校正后的先行声音和重叠不受影响，不过最好还是不要去改它。
UTAU 在传递给引擎数据的 先行声音/重叠/STP 都是经过校正的。

简易C++校正算法

// 先去除首位空格，判断余下部分是否为空或r或R，如果是就为真
bool isRestNoteLyric();

// 首先从UST中获取当前音符与前驱音符的所有音符属性
GetValueFromSectionNote();

// 判断过程如下
double CorrectRate = 1;
double velocityRate = pow(2, 1 - CurVelocity / 100);

CurPreUttr *= velocityRate;
CurOverlap *= velocityRate;

if (hasPrevNote){
  double PrevDuration = double(PrevLength) / 480 * 60 / PrevTempo * 1000;
  double MaxOccupy = isRestNoteLyric(PrevLyric) ? PrevDuration : (PrevDuration / 2);
  if (aCurPreUttr - aCurOverlap > MaxOccupy) {
    CorrectRate = MaxOccupy / (CurPreUttr - CurOverlap);
  }
}

double CorrecetPreUttr = CorrectRate * CurPreUttr;
double CorrecetOverlap = CorrectRate * CurOverlap;
double CorrecetSTPoint = CurPreUttr - CorrecetPreUttr;

// 追加用户设置的STP  
CorrectSTPoint += CurSTPoint;

UTAU 引擎调用

最重要的后端处理过程————引擎调用。

UTAU 合成声音原理

将人工录制的声音样本 拉伸、变调（重采样），再拼接（合成）。

引擎

引擎分为合成器与重采样器，重采样器进行拉伸变调工作，合成器对重采样器的输出文件进行拼接。
合成后的音频质量由音源本身质量决定，但很大程度上受重采样器的算法影响。
引擎都是控制台程序，没有 GUI 框架，运行时在控制台输出信息供用户参考，执行完毕立即返回。

重采样器（Resampler）

重采样器介绍

重采样器（Resampler）

作用

对音源采样进行变调，拉伸。

命令行

resampler.exe <input wavfile> <output file> <pitch_percent> <velocity> [<flags> [<offset> <length_require> [<fixed length> [<end_blank> [<volume> [<modulation> [<pich bend>...]]]]]]]

参数

必选参数

第一个参数：音源文件路径（如a.wav）
第二个参数：输出缓存文件路径（如temp.wav）
第三个参数：音阶（如C#4）
第四个参数：辅音速度（0~200的实数）

可选参数

第五个参数：Flags（如"GB60"，如果指定了后面的参数，那么此参数不能被忽略）
第六个参数：偏移（原音设定左侧蓝色区域宽度）
第七个参数：实际长度（拼接之前的单音符长度）
第八个参数：固定长度（原音设定粉红色区域宽度）
第九个参数：空白（原音设定右侧蓝色区域宽度）
第十个参数：音量（0~100的实数）
第十一个参数：移调（-200~200的实数）
第十二个参数：音高曲线字符串

补充说明

关于Flags
- 如果调用重采样器只是为了初始化频率表，那么可以将Flags参数指定为“G”，后面所有参数不指定。
关于实际长度
- 详见咬合校正
关于音高曲线字符串
- 实际上它占两个命令行参数的位置 （即重采样器会接收到13个命令行参数）
- 第一个参数：曲速加感叹号前缀 （如!120）
- 第二个参数：用基于 Base64 的 64 进制双字节序列组成的字符串，用来描述音高曲线
合法的启动参数示例
- 例1：resampler.exe infile.wav outfile.wav 120 100 GB60
- 例2：resampler.exe "D:\UTAU\voice\MyVoice\a.wav" "D:\ProjectCache\1_a_120.wav" C4 100 "B0Y0H50" 5 600 37 0 100 0 !120 AA#5#

对于制作重采样器的建议

应当兼容通用Flags，如G用来初始化频率表，T用来导出文本频率表，u用来直接输出采样等。
应当兼容输入输出文件的路径既可以是相对路径也可以是绝对路径。
第三条：对于非法的输入文件，可以输出一段空白的符合长度要求的声音。
在控制台输出信息以便用户查找问题。

音高曲线字符串

Base 64 编码表

索引	对应字符	索引	对应字符	索引	对应字符	索引	对应字符
0	A	17	R	34	i	51	z
1	B	18	S	35	j	52	0
2	C	19	T	36	k	53	1
3	D	20	U	37	l	54	2
4	E	21	V	38	m	55	3
5	F	22	W	39	n	56	4
6	G	23	X	40	o	57	5
7	H	24	Y	41	p	58	6
8	I	25	Z	42	q	59	7
9	J	26	a	43	r	60	8
10	K	27	b	44	s	61	9
11	L	28	c	45	t	62	+
12	M	29	d	46	u	63	/
13	N	30	e	47	v
14	O	31	f	48	w
15	P	32	g	49	x
16	Q	33	h	50	y

编码规则

按指定的曲速决定控制点（音高采样点）的数量，每拍有96个控制点（5ticks采样一次）
- !120：0.5秒，96个采样点
- !180：0.333秒，96个采样点
音高曲线的起点：先行声音（校正后）+ STP（校正后）
采样点是整 -2048~2047 的 12bit 整数，每个半音相当于 100
通过 Base64 将采样点的值转换成每单元 2个字符 的字符串
- 38 -> Am (38 = 0 * 64 + 38 * 1)
- 176 -> Cw (176 = 2 * 64 + 48 * 1)
负数先取反（即加4096）再参与编码
- -2 -> /+ (-2 + 4096 = 63 * 64 + 62)
同一个数字连续出现会按如下格式压缩长度
- AA#5# 表示 AA AA AA AA AA AA，它的意思是 [0,0,0,0,0,0]

示例

源 - 1

-175 -257 -341 -417 -480 -522 -540 -537 -532 -527 -522 -517 -512 -508 -503 -498 -494 -489 -485 -480 -476 -472 -468 -464 -460 -456 -453 -449 -446 -443 -440 -437 -434 -432 -429 -427 -425 -423 -421 -420 -418 -417 -416 -415 -415 -414 -414 -414 -408 -391 -365 -332 -295 -257 -221 -190 -167 -153 -150 -149 -146 -141 -135 -127 -117 -106 -94 -80 -66 -50 -34 -18 -1 16 33 50 67 83 98 113 126 138 149 159 167 173 178 181 183 183 185 188 192 198 204 212 221 231 242 254 266 279 293 307 321 336 351 365 379 393 407 420 432 444 454 464 473 480 487 492 496 498 499 499 498 497 494 491 487 482 476 470 463 455 447 438 428 418 408 397 386 375 363 351 339 327 315 303 291 279 268 256 245 235 225 215 206 197 189 182 175 169 164 160 156 153 151 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 150 145 133 113 88 57 25 -7 -38 -64 -84 -96 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -100 -99 -99 -99 -99 -99 -99 -98 -98 -98 -98 -97 -97 -97 -96 -96 -96 -95 -95 -95 -94 -94 -93 -93 -92 -92 -92 -91 -91 -90 -90 -89 -89 -88 -87 -87 -86 -86 -85 -85 -84 -83 -83 -82 -82 -81 -80 -80 -79 -78 -78 -77 -76 -76 -75 -74 -73 -73 -72 -71 -70 -70 -69 -68 -67 -67 -66 -65 -64 -64 -63 -62 -61 -60 -60 -59 -58 -57 -56 -56 -55 -54 -53 -52 -52 -51 -50 -49 -48 -48 -47 -46 -45 -44 -43 -43 -42 -41 -40 -39 -39 -38 -37 -36 -36 -35 -34 -33 -33 -32 -31 -30 -30 -29 -28 -27 -27 -26 -25 -25 -24 -23 -22 -22 -21 -20 -20 -19 -19 -18 -17 -17 -16 -16 -15 -14 -14 -13 -13 -12 -12 -11 -11 -10 -10 -9 -9 -8 -8 -8 -7 -7 -6 -6 -6 -5 -5 -5 -4 -4 -4 -3 -3 -3 -3 -2 -2 -2 -2 -2 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1 -1
Base64 - 1

9R7/6r5f4g323k3n3s3x32374A4E4J4O4S4X4b4g4k4o4s4w4044474/5C5F5I5L5O5Q5T5V5X5Z5b5c5e5f5g5h5h5i#2#5o556T607Z7/8j9C9Z9n9q9r9u9z95+B+L+W+i+w++/O/e/u//AQAhAyBDBTBiBxB+CKCVCfCnCtCyC1C3C3C5C8DADGDMDUDdDnDyD+EKEXElEzFBFQFfFtF7GJGXGkGwG8HGHQHZHgHnHsHwHyHzHzHyHxHuHrHnHiHcHWHPHHG/G2GsGiGYGNGCF3FrFfFTFHE7EvEjEXEMEAD1DrDhDXDODFC9C2CvCpCkCgCcCZCXCW#107#CRCFBxBYA5AZ/5/a/A+s+g+c#54#+d#5#+e#3#+f#2#+g#2#+h#2#+i+i+j+j+k#2#+l+l+m+m+n+n+o+p+p+q+q+r+r+s+t+t+u+u+v+w+w+x+y+y+z+0+0+1+2+3+3+4+5+6+6+7+8+9+9+++//A/A/B/C/D/E/E/F/G/H/I/I/J/K/L/M/M/N/O/P/Q/Q/R/S/T/U/V/V/W/X/Y/Z/Z/a/b/c/c/d/e/f/f/g/h/i/i/j/k/l/l/m/n/n/o/p/q/q/r/s/s/t/t/u/v/v/w/w/x/y/y/z/z/0/0/1/1/2/2/3/3/4#2#/5/5/6#2#/7#2#/8#2#/9#3#/+#4#//#12#

简易转换（C++）

static const char Base64EncodeMap[] =
"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=";

string encode_single_num(int n) {
    char x, y;
    string result;

    //若为负则以12位二进制取反
    if (n < 0) {
        n += 4096;
    }

    //转化为64进制，十位为x，个位为y，并映射为Base64字符
    x = Base64EncodeMap[int(n / 64)];
    y = Base64EncodeMap[n % 64];

    result = x + y;

    return result;
}

合成器（Wavtool）

合成器介绍

合成器（Wavtool）

作用

对重采样器输出的音频裁剪、添加音量包络、拼接。

命令行

wavtool2 <outfile> <infile> offset length p1 p2 p3 v1 v2 v3 v4 ovr p4 p5 v5

参数

必选参数

第一个参数：输入文件（如a.wav）
第二个参数：输出文件（如temp.wav）
第三个参数：StartPoint（实数）
第四个参数：输出长度（音长@曲速±校正值）
第五个参数：音量包络p1
第六个参数：音量包络p2

可选参数

第七个参数：音量包络p3（一旦指定了，必须指定重叠及之前所有参数）
第八个参数：音量包络v1
第九个参数：音量包络v2
第十个参数：音量包络v3
第十一个参数：音量包络v4
第十二个参数：重叠
第十三个参数：音量包络p4
第十四个参数：音量包络p5
第十五个参数：音量包络v5

补充说明

关于输出长度

格式：音长@曲速±校正值
示例：480@120+50.1，120@105-41
音长就是以tick为单位的音长。
校正值 = 先行声音（校正后）+ 末端偏移
详见咬合校正
注意事项：校正值+理论长度不能变成负数。

关于合成结束信号

对于一般的合成器
- 需要将拼接的音频划分为 temp.wav.whd（文件头）与 temp.wav.dat（数据内容）。
- 第一次调用产生这两个文件，后续调用将数据追加在dat文件上。
- 批处理在最后一次拼接后合并这两个文件，生成一个完整的 temp.wav。
针对 moresampler（合成器模式）
- 每次调用会将缓存的文件名（类似文本的格式）直接写入 temp.wav 作为参考，结束前检测 temp.bat 文件的内容，根据缓存文件名来判断是不是最后一次调用。
- 如果是最后一次，那么根据 temp.wav 的内容一次性拼接所有的缓存文件。
- 因此如果要自己写程序调用引擎并兼容moresampler，必须按照格式保留 temp.bat。
  - 当使用 UTAU 多核处理时由于 temp.bat 不符合单核处理的格式，moresampler 读取不到结束信号，所以会失败。
- 使用时必须开启 UTAU 的缓存处理选项（没开时每次生成的缓存会覆盖上一次）。

UTAU 渲染脚本

原文链接（日语）原作者：delta_kuro

UTAU 渲染脚本

声明

本文依据个人分析所写，因此可能存在少量不严谨。另外，翻译过程中补充了一些内容。

渲染脚本的位置

临时文件夹

一般地，UTAU 启动后，会在系统环境变量为 TEMP 的路径下创建后台工作目录 utauX（X为正整数，由于utau可以多开，按启动顺序依次递增），用来存放合成脚本文件。

一般是这样一个文件夹：C:\user\<user名>\AppData\Local\Temp\utau1\

脚本文件

一般会产生以下两个文件。

temp.bat
temp_helper.bat

如果使用了 UTAU 的多核渲染，那么不会产生 helper，会产生以下文件，具体数量与线程数相同。

temp.bat
temp1.bat
temp2.bat
temp3.bat
...

渲染脚本的作用

单核处理

temp.bat

从UTAU直接启动
将各种参数存在批处理的变量中
对于休止符，直接启动wavtool

temp_helper.bat

从temp.bat中启动
将temp.bat中设定的参数发送给resampler和wavtool

多核处理

temp.bat

一次性调用合成器，在最后启动。

其他批处理文件

在合成开始后同时启动重采样器，并行进程。
所有进程结束后启动 temp.bat。

本文只讨论单核渲染的批处理文件。

渲染脚本的内容

temp.bat 页首

@rem project
工程文件名

@set loadmodule
模块的设定？似乎一直是空白的

@set tempo
工程曲速

@set samples
采样频率

@set oto
音源文件夹的完整路径

@set tool
合成引擎 (wavtool)的完整路径

@set resamp
重采样引擎(resampler) 的完整路径

@set output
temp.wav的相对路径

@set helper
temp_helper.bat的路径

@set cachedir
缓存文件夹的路径

@set flag
全局Flags

@set env
默认音量包络

@set stp
定义变量stp

@del "%output%" 2>nul
如果temp.wav存在，则将它删掉
"2>nul"指的是不输出错误信息

@mkdir "%cachedir%" 2>nul
创建缓存文件夹

temp.bat 正文

对于休止符

@"%tool%" "%output%""%oto%\R.wav" 0 480@120+0.0 0 0
直接调用wavtool

第一个参数：输出文件

第二个参数：在原音设定文件夹下的R.wav（似乎用这个来识别休止符）

第三个参数：stp（休止符为0）

第四个参数：输出的实际长度

格式：音长@tempo+校正值

校正值 = 先行声音（校正后）+ 末端偏移
详见咬合校正

第五个参数（以及后面一堆）：音量包络（对于休止符:0 0）

对于除休止符以外的音符

@set params=100 0 !120 AA#5#　[必填]
设定音调参数

第一个参数：音量

第二个参数：移调

第三个参数：曲速（格式：!tempo）

第四个参数：音高曲线字符串

@set flag="g5"
设定 Flags

一般是全局flags在后，音符flags在前

出现同一个参数时，只有第一个有效

当出现 e 或者 E 时，在前面添加反斜杠

@set env=0 5 35 0 100 100 0 70 0 10 100 [必填]
音量包络（除了休止符，有三种格式，任选其一）

p1 p2 p3 v1 v2 v3 v4 ove

p1 p2 p3 v1 v2 v3 v4 ove p4

p1 p2 p3 v1 v2 v3 v4 ove p4 p5 v5

@set stp=150
设定 stp 数值

@set vel=100【必填】
辅音速度

@set temp="%cachedir%\1_あ_C4_OkgOOW.wav"【必填】
缓存文件的路径

文件名是 [ust音符序号]_[歌词]_[音阶]_[六位英文数字].wav

歌词中的半角空格会被替换为“+”，“*”替换为“$”，“?”替换为“=”，正反斜杠替换为下划线，其他文件名敏感符号直接忽略。

乱码后缀意义不明（可能是随机生成）

当对同一个音符进行操作后，通过改变文件名来区分缓存，这种方法比较好。

@echo ##########------------------------------(1/4)【必填】
显示合成进度

@call %helper% "%oto%_おおうえあ.wav" C4 480@120+70.0 30 3170.884 600 50.0 -1169.19 0【必填】
temp_helper.bat的启动指令

第1个参数：采样的文件名("%oto%\あ.wav")

第2个参数：渲染目标音阶名(C4)

第3个参数：音符长度(与休止符相同)(480@120+70.0)

第4个参数：先行发声(30)

第5个参数：偏移(3170.884)

第6个参数：resampler输出的声音长度(600)

与wavtool结合前，没有经过裁剪直接输出的长度

（第3个参数换算为ms后的长度+stp）/50，四舍五入以后再乘以50

第7个参数固定范围(50.0)

第8个参数右侧空白(-1169.19)

第9个参数序号(0)

多线程合成时这个参数如果错误可能引起问题

temp_helper.bat 内容

[与ust无关的指令]

@if exist %temp%goto A
如果存在缓存文件，那么跳过重采样步骤

@if exist"%cachedir%%9_.wav" del "%cachedir%%9_.wav"
如果有相同序号但不同名称的文件，则删除

@"%resamp%"%1 %temp% %2 %vel% %flag% %5 %6 %7 %8 %params%
启动重采样引擎（之前已经讲过）

:A
提供给第一行跳跃的标签

@"%tool%""%output%" %temp% %stp% %3 %env%
启动合成引擎（与休止符一样）

temp.bat 页脚

[与ust无关的指令]

@if not exist"%output%.whd" goto E
@if not exist"%output%.dat" goto E
检查是否生成了 temp.whd 和 temp.dat。如果没有，跳过以下步骤。

当temp_helper.bat正在被调用时，还没有生成temp.wav，temp.whd与temp.dat已经生成了。

copy /Y"%output%.whd" /B + "%output%.dat" /B "%output%"
将 temp.whd 和 temp.dat 合并为 temp.wav。

#whd可能是 wav head 的意思。

del "%output%.whd"
del"%output%.dat"
删除temp.whd与temp.dat。

:E
跳过合并与删除过程的标签。

资源与参考

与本程序相关的参考。

UTAU 前辈

Ameya
- Twitter：@ameyaP_
Masao
- Twitter：@namiyome
Zteer
- Twitter：@zteer
ScientistB
- Twitter：@scientistb
Kanru Hua
- BiliBili：Sleepwalking
- Twitter：@khuasw
...

UTAU 中华组

Haru.jpg
- BiliBili：Haru.jpg
- Twitter：@Haru_jpg

插件解析类库

简单的试听器

其他资源

可能用得到的资源分享。

UTAU Unions

中文参考

UTAU 中文文档

作者：SuibianP
链接：UTAU相关各种文档的简体中文翻译堆积处

Qt 中文文档

作者：Qt Company
链接：Qt 中文文档

mdBook 中文文档

作者：linshi
链接：mdBook 中文文档

QPitchEditor 特性

格式兼容

关于用 QPitchEditor 打开各种类型的文件的方法。

引言

受到 UTAU 插件机制的启发，将 QPitchEditor 打开文件的处理过程与本体分离。
QPitchEditor 本身只能打开 UST 文件，通过调用外部控制台程序打开其他类型的文件。
因此只要开发者制作出特定类型文件转换为 UST 文件的转换器，提供可执行文件供 QPitchEditor 调用，QPitchEditor 就能打开（导入）任意类型的文件。

基本信息

转换器的形式

最少需要以下两个文件。
- [config.txt] 设定文件
- [可执行文件] 转换器本体
可执行文件必须能够获取命令行调用参数。
除此之外，含有其他文件也没有关系。
- 例如：readme.txt

`config.txt`的格式

config.txt按照以下形式记述（务必指定编码为 ANSI）。

filters=Synthesizer V Project(*.svp *.s5p)
execute=test.exe
shell=use
import=front

解释

在filters后指定在 QPitchEditor 文件对话框中类型过滤器栏显示的内容。
- 格式：名称(*.扩展名1 *.扩展名2 *.扩展名3 ...)
在execute后指定可执行文件的名称。
通常会用CreateProcess启动，但在指定有shell=use的情况下会用ShellExecuteEx启动。因此，也能够执行exe以外的文件（jar、html、hta等）。
import指定导入文件时的插入方式，省略时将音符追加在工程末尾。
- 定义域：head，front，back
- head：将音符插入在工程最前端。
- front：将音符插入在选区前。
- back：将音符插入在选区后。

启动转换器提供两个命令行参数，第一个是待打开（导入）文件的绝对路径，第二个是将文件转换为 UST 格式后保存的绝对路径。

输出

转换后的文件由转换器创建，路径由第二个命令行参数指定。
转换后的编码为 ANSI 或 UTF-8。

注意事项

转换后的文件在[#SETTING]节指定全局曲速（不指定默认为120）即可，如果指定了音源、合成器与重采样器 QPitchEditor 也会读取；音符节应当符合UST格式。
转换器应当是控制台程序，运行效率应当较高，转换完成后立即返回。