----------------------------------------------------------

  setParam 自動推定用プラグイン開発の手引き

                                            2013/01/23作成
----------------------------------------------------------

本ドキュメントは、UTAU音源の原音設定を自動で行うソフトを独自に開発し、
setParam プラグインに取り込むための情報を説明したものです。


----------------------------------------------------------
＜プラグインのインストール場所＞

プラグインは実行プログラムや後述するplugin.txtなどを一つのフォルダにまとめ、
「setParam.exeのあるフォルダ\plugins\」の下に置いて下さい。


----------------------------------------------------------
＜プラグイン実行の流れ＞

プラグインを実行すると、以下の手順で処理されます。

1) setParamが「setParam.exeのあるフォルダ\plugins\inParam.txt」
　 というテキストファイルを作ります。
　 このファイルのフォーマットは以下のとおりです。

　　　1行目：処理対象の音源フォルダの絶対パス
　　　2行目：setParam〜プラグイン間のデータ受け渡し用原音設定ファイルの絶対パス
　　　3行目：F0の抽出間隔(単位=秒)
　　　4行目：パワーの抽出間隔(単位=秒)

　 ※なお、1、2行目のパスはWindows流ではなくTcl/Tk流で表記されます。
　 　Windowsの表記で「C:\foo\bar」というフォルダがあれば、Tcl/Tkでは「C:/foo/bar」
　 　と表記されます（円マークがスラッシュに置き換えられます）。

2) setParamがinParam.txtの2行目に示したファイルに
　 原音設定を保存します。

3) プラグインの設定ファイル(plugin.txt)にneedF0=1と指定があった場合は
　 各wavファイルのF0ファイルを出力します。
　 またneedPower=1と指定があった場合は各wavファイルのパワーファイルを出力します。

4) プラグインを起動します。プラグインはinParam.txt等を読み、
　 原音設定を行い、結果をinParam.txtの2行目に示したファイルに
　 oto.ini形式で書き込んで終了して下さい。

5) setParamがinParam.txtの2行目に示したファイルを読み込みます。


----------------------------------------------------------
＜plugin.txtについて＞

setParamは起動時に「setParam.exeのあるフォルダ\plugins\*\plugin.txt」を
検索してメニューに登録します。

plugin.txtには以下の項目を書けます。
必須の項目は「name=]「execute=」です。
それ以外の項目は必要なときのみ指定して下さい（不要なら行ごと省略可能です）。

　　name=単独音自動推定：hogehoge ← setParamに表示するプラグイン名
　　execute=hogehoge.exe          ← プラグインの実行コマンド
　　argv=-a %s                    ← プラグイン実行時に与える引数(詳細後述)
　　needF0=0                      ← setParamのF0データが欲しいなら1にする(詳細後述)
　　F0unit=semitone               ← F0値の単位を指定する(Hz または semitone)
　　needPower=0                   ← setParamのパワーデータが必要なら1にする(詳細後述)


----------------------------------------------------------
＜plugin.txtのargvについて＞

plugin.txtの「argv=」で指定した文字列は、プラグインを実行時引数として
プラグインに渡されます。文字列の中に以下の記号を使うこともできます。

　　%s ← 処理対象の音源フォルダの絶対パス
　　%r ← setParam〜プラグイン間のデータ受け渡し用原音設定ファイルの絶対パス
　　%f ← F0の抽出間隔（単位=秒）
　　%p ← パワーの抽出間隔（単位=秒）

なお、%sと%rのパスはWindows流ではなくTcl/Tk流で表記されます。
Windowsの表記で「C:\foo\bar」というフォルダがあれば、Tcl/Tkでは「C:/foo/bar」
と表記されます（円マークがスラッシュに置き換えられます）。

さらに%sと%rでは、音源フォルダ名が「c:/Program Files/」のように
空白を含む可能性があります。この場合プラグインは
"c:/Program"と"Files/"の二つの文字列に分けて受け取ると思いますので注意が必要です。
inParam.txtの1,2行目を読み込む方が楽、という選択肢もあると思います。


----------------------------------------------------------
＜plugin.txtのneedF0、F0unitについて＞

plugin.txtで「needF0=1」と書くと、setParamはプラグイン実行時に
各wavファイルからF0データを抽出し、テキストファイルに出力します。

・F0ファイル名：
　　wavファイルの拡張子を「.setParam-f0」に変更したもの。
　　（例：「あ.wav」のF0ファイルは「あ.setParam-f0」）

・F0ファイルの保存場所：
　　wavファイルと同じフォルダ。

・ファイル内容：
　　F0値を一行一データで縦に並べています。
　　F0値の単位については、plugin.txtで"F0unit"を使って指定できます。
　　その他のF0抽出用パラメータにはsetParamにF0を画面表示する際の値を用います。


----------------------------------------------------------
＜plugin.txtのneedPowerについて＞

plugin.txtで「needPower=1」と書くと、setParamはプラグイン実行時に
各wavファイルからパワーデータを抽出し、テキストファイルに出力します。

・パワーファイル名：
　　wavファイルの拡張子を「.setParam-power」に変更したもの。
　　（例：「あ.wav」のパワーファイルは「あ.setParam-power」）

・パワーファイルの保存場所：
　　wavファイルと同じフォルダ。

・ファイル内容：
　　パワー値を一行一データで縦に並べています。
　　パワー抽出用パラメータにはsetParamにパワーを画面表示する際の値を用います。
　　値の単位はdBです。


----------------------------------------------------------
＜その他＞

現状のプラグイン仕様は改良の余地があるため、今後変更する可能性があります。
「setParam側からこういうデータを受け取りたい」、
「setParam側にこういうデータを送りたい」など、もしご要望等があれば
ブログのコメントなどでお知らせ頂ければ幸いです。

