プラグイン仕様

はじめに

ここでは、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」(Mode2用ピッチ配列がPitchesエントリで渡る)、「ustversion=1.20」(モジュレーションがModulation、Mode2用ピッチ配列が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]

一時ファイルの先頭にあるセッションで、基本的な設定が書いてあります。
読み取り専用で、ここを変更しても本体側の情報は何も変更されません。
出力の際は、省略してもかまいません。

[#数字]

選択範囲の情報が格納されたセッションです。
このセッションは、省略できません。
例外として、プラグイン操作自体をキャンセルする場合は、
全てのセッションを省略することが出来ます。
また、セクションの数字には意味は無く、
出力順序通りに本体の選択範囲に適用されます。

[#PREV],[#NEXT]

[#PREV]は、選択範囲の直前の音符データが格納されます。
[#NEXT]には、選択範囲の直後のデータが入ります。
前後に音符が無ければ、このセクションはありません。
出力の際は、省略してもかまいませんし、
省略しなければ、情報が反映されます。
また出力の際は、必ずしも数字セクションの直前・直後に書かなくてもかまいません。

[#INSERT]

出力の際に使うことの出来る、特別なセッションです。
これを書いた位置に、音符を追加します。
数字セクションの一つとして扱われますので、
[#PREV]の直前や[#NEXT]の直後に書いても、
選択範囲外の位置に音符が追加されることはありません。

また、選択範囲の後に音符が無く、
なおかつ選択範囲の末尾にこのセクションを追加する場合は、
Lengthをきちんと指定しないと、
長さ0の音符データが出来てしまうので注意してください。

[#DELETE]

出力の際に使うことの出来る、特別なセッションです。
数字セッションの代わりにこれを書くと、その音符を削除します。
それ以外のセッションは削除できません。

エントリ

エントリは出力の際は省略することも出来、その場合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 モジュレーション
書式 : Moduration=整数
定義域 : -200~200
単位 : パーセント
デフォルト値 : 空白(100)
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=整数,整数,整数…
定義域 : -2048~2047
単位 : cent
デフォルト値 : 0
5ticksの刻み幅でピッチを示します。
UTAUのバージョンによってPichesとPitchesのどちらの書式もあり得ます。
プラグイン側からの出力はどちらの書式でも変わりません。
省略された部分は全て0として処理されます。

ピッチ(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)があると、それ以降の文字列が欠落します。また、半角空白は半角カンマに置換されます。それ以外の制限はありません。
例 : $君は=実に,馬鹿だなぁ


参考リンク

ここに無い情報は独自調査です。


名前:
コメント:

統計: -
本日: -
昨日: -