はじめに
ここでは、UTAUのプラグイン機能の詳細な仕様を記述します。
インストール方法や、作成されたプラグイン一覧などは、
UTAU用プラグインのページを参照して下さい。
また、今のところアナウンスされていないエントリの説明も含みます。
そのため、不確定な情報も混じっています。ご了承ください。
詳細な調査は、UTAU Ver0.2.76を用いて行っています。
基本情報
プラグインの形式
プラグインには、最低この二つのファイルが必要です。
plugin.txt 設定ファイル
[実行ファイル] プラグイン本体
実行ファイルは、コマンドライン引数を取れる形式である必要があります。
また、install.txtというファイルを用意すると、
プラグインのインストールが容易になります。
これ以外にも、別のファイルを含んでいても構いません。
例 : readme.txt
plugin.txtの形式
plugin.txtには、以下のように記述します。
name=プラグインテスト
execute=test.exe
shell=use
ustversion=スクリプトバージョン
notes=all
nameには、プラグインの名称を書きます。これはメニューに反映されます。
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 : plugins以下に作られるフォルダ名。省略不可。
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ファイル及びpluginスクリプトに旧形式のエントリを出力する」をオンにしたときのみ存在する）
[#数字]
選択範囲の情報が格納されたセクションです。
このセクションは、省略できません。
例外として、プラグイン操作自体をキャンセルする場合は、
全てのセクションを省略することが出来ます。
また、セクションの数字には意味は無く、
出力順序通りに本体の選択範囲に適用されます。
[#PREV],[#NEXT]
[#PREV]は、選択範囲の直前の音符データが格納されます。
[#NEXT]には、選択範囲の直後のデータが入ります。
前後に音符が無ければ、このセクションはありません。
出力の際は、省略してもかまいませんし、
省略しなければ、情報が反映されます。
また出力の際は、必ずしも数字セクションの直前・直後に書かなくてもかまいません。
[#INSERT]
出力の際に使うことの出来る、特別なセクションです。
これを書いた位置に、音符を追加します。
数字セクションの一つとして扱われますので、
[#PREV]の直前や[#NEXT]の直後に書いても、
選択範囲外の位置に音符が追加されることはありません。
また、選択範囲の後に音符が無く、
なおかつ選択範囲の末尾にこのセクションを追加する場合は、
Lengthをきちんと指定しないと、
長さ0の音符データが出来てしまうので注意してください。
[#DELETE]
出力の際に使うことの出来る、特別なセクションです。
数字セクションの代わりにこれを書くと、その音符を削除します。
それ以外のセクションは削除できません。
[#VERSION]
UTAU0.4から追加されたセクションです。
UTAUの設定で「Ustファイル及びpluginスクリプトに旧形式のエントリを出力する」をオフにした場合のみ存在します。
現時点では「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を指定しても、
Ver0.2.35以前と完全に同じ動作にはなりません。
値を空白にすると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_endを加工する場合は範囲名が重複しないようにしてください。
読み込み専用エントリ
書き換えても反映されない読み込み専用のエントリ。
Ver.0.4.15で実装された為、それ以前のバージョンでは利用不可能。
@preuttr 自動調整込みの先行発声
書式 : @preuttr=実数
レンダリング時の自動調整込みの先行発声値。
@overlap 自動調整込みのオーバーラップ
書式 : @overlap=実数
レンダリング時の自動調整込みのオーバーラップ値。
@stpoint 自動調整込みのSTP
書式 : @stpoint=実数
レンダリング時の自動調整込みのSTP値。
@filename レンダリング使用ファイル名
書式 : @filename=ファイル名
レンダリングで使われる音源ファイル名。
音抜けする場合は表示されない。
@alias エイリアス
書式 : @alias=エイリアス
Prefix.map適用済みのエイリアス。無ければ音符に入力した歌詞。
音抜けする場合は表示されない。
@cache キャッシュファイル名
書式 : @cache=ファイルパス
キャッシュファイル名。キャッシュが存在しない場合は表示されない。
※Ver.0.4.18時点ではフルパスで渡されるが、キャッシュディレクトリは除かれる予定らしい。
ピッチ(Mode1)
PBType ピッチベンドのタイプ
書式 : PBType=値
定義域 : 5もしくはOldData
デフォルト値 : 5
通常は5を指定して下さい。
OldDataは、かなり初期のUTAUで使われていたピッチベンドタイプです。
Piches ピッチ数列
書式1 : Piches=整数,整数,整数…
書式2 : Pitches=整数,整数,整数…
書式3 : PitchBend=整数,整数,整数…
定義域 : -2048～2047
単位 : cent
デフォルト値 : 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エントリが存在しなければ旧バージョンであると判断できます。
ピッチ(Mode2)
ポルタメントの点の上限は50です。
これに応じて、PBW、PBY、PBMの値の数の上限も決まります。
この部分のエントリの詳細は、
公式からの情報が見つからなかったので、
著者の完全な推測となります。
Mode2からMode1に戻した場合でも、
これらエントリの値は全て保存されます。
Renderボタンを押さない限り、
Mode1のピッチ情報も変わりません。
また、ここのエントリのデフォルト値はありません。
というのも、[#INSERT]で挿入した音符は、
ポルタメントの設定もビブラートの設定も無いからです。
PBS ピッチ曲線の最初の点
書式1 : PBS=整数
書式2 : PBS=整数;実数
定義域 : -200～200;-204.8～204.7
単位 : ミリ秒;10cent
最初の点の、音符の始点からの相対座標。
一つ目の値は時間位置、二つ目の値はピッチシフト値を表します。
ピッチシフト値を指定しない場合、0が入ります。
区切りが「;」であるのに注意して下さい。
PBW ピッチポイント間隔
書式 : PBW=実数,実数,実数,…
定義域 : 音符の終点を超えない限り制限なし？
単位 : ミリ秒
最も左のポイント間隔の値から始まります。
PBY 最初の点を除くピッチポイントのシフト値
書式 : PBY=実数,実数,実数,…
定義域 : -204.8～204.7
単位 : 10cent
最初の点を除く全ての点のピッチシフト値。
省略されている部分は全て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,任意
単位 : パーセント,ミリ秒,cent,パーセント,パーセント,パーセント,パーセント,なし
Lengthに対する長さ,周期,深さ,入,出,位相,高さ,未使用
の順で格納されています。
ノートのプロパティを直接変更することにより、上記の定義域を越えた値が入る場合があります。
Flags プロパティのflags + BRE + NoFormantFilter
書式 : Flags=文字列
デフォルト値 : 空白
以下に書いてあるフラグの中には、
公式にアナウンスされていないものも含みます。
フラグのそれぞれの効果の説明は、
音のプロパティを参照してください。
数字指定ありの物は、定義域を書いてあります。
全てアルファベット順です。
b フォルマント修正を通さないBRE
定義域 : 0～100
デフォルト値 : 0
B BRE
定義域 : 0～100
デフォルト値 : 50
c ローパスフィルタ1(フォルマント修正前)
定義域 : 0～100
デフォルト値 : 50
C ローパスフィルタ1
定義域 : 0～100
デフォルト値 : 0
D ローパスフィルタ2
定義域 : 0～100
デフォルト値 : 0
E ローパスフィルタ3
定義域 : 0～100
デフォルト値 : 0
F フォルマント修正適用周波数帯域設定(ピッチ基準)
定義域 : 0～不明
デフォルト値 : 3
g 簡易ジェンダーファクター
定義域 : -100～100
デフォルト値 : 0
G 周波数表再作成
デフォルト値 : 指定なし
数字指定なし。
h ローパスフィルタ4(BRE以外)
定義域 : 0～99
デフォルト値 : 0
100以上にしても、BREが1以上であれば音が出ます。
H ローパスフィルタ4
定義域 : 0～99
デフォルト値 : 0
L フォルマント修正適用周波数帯域設定(周波数基準)
定義域 : 0～不明(130以下だと思われる)
デフォルト値 : なし
N NoFormantFilter
デフォルト値 : 指定なし
数字指定なし。
P ピークコンプレッサの強さ
定義域 : 0～100
デフォルト値 : 86
R TIPSエンジン用パラメータファイル再作成
デフォルト値 : 指定なし
数字指定なし。
t 音程を10cent単位でシフト
定義域 : 不明
デフォルト値 : 0
T 周波数表をテキストで出力
デフォルト値 : 指定なし
数字指定なし。
W ロボット声生成
デフォルト値 : 指定なし
数字指定なし。
公式ではまだアナウンスされていないと思われるフラグ。
Y 伸縮範囲のBREの割合
定義域 : 0～100
デフォルト値 : 100
/ 高速化パッチ用エンジン切り替え
高速化パッチの際使われる記号のデフォルト。
一応変更はできるが。
独自エントリ
書式 : $エントリ名=値
ユーザーが独自のエントリを定義することが出来ます。
セクション内に書式のように記述すると、Othersに反映されます。
書式の最初の一文字目の$は、半角でなければなりません。
エントリ名は、改行、半角のスペース、半角の/を含まない限り自由です。
値は、半角の「=」（等号）や半角の「\n」（バックスラッシュ＋英小文字のn）があると、それ以降の文字列が欠落します。また、半角空白は半角カンマに置換されます。それ以外の制限はありません。
例 : $君は=実に,馬鹿だなぁ
参考リンク
ここに無い情報は独自調査です。
統計: -
本日: -
昨日: -
最終更新：2019年01月04日 18:08
