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

  setParam 自動推定用プラグイン開発の手引き
  (version 3.0-b150712以降用) 

                                           2013/01/23 作成
                                           2015/07/12 改訂
----------------------------------------------------------

本ドキュメントは、UTAU音源の原音設定を行うソフトsetParamのプラグインを
開発するための情報を説明するものです。

setParamのプラグインはver.2.0-b130130で仕様策定しました。
その後ver.3.0-b150712で仕様変更を行い以下の3種類のプラグインを作成出来るようになりました。

　(a) 全データを更新するプラグイン(自動推定など)
　(b) 波形窓で表示中のデータを変更するプラグイン
　(c) パラメータ一覧表で複数選択したデータを変更するプラグイン


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

「setParam.exeのあるフォルダ\plugins\」の下にフォルダを作って
その中に開発したプラグインのプラグラムや後述するplugin.txtを置いて下さい。


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

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

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

　　　------------------------------------------------------------------
　　　1行目：処理対象の音源フォルダの絶対パス。
　　　2行目：setParam〜プラグイン間のデータ受け渡し用原音設定ファイルの絶対パス。
　　　3行目：F0の抽出間隔(単位=秒)。
　　　4行目：パワーの抽出間隔(単位=秒)。
　　　5行目：setParamの波形窓で現在表示しているデータの行番号。
　　　       ファイル先頭行を1とカウントします。
　　　6行目：setParamのパラメータ一覧表で現在選択しているセルの行番号。
　　　       複数選択している場合、コンマ刻みで行番号を列挙します。
　　　------------------------------------------------------------------

　 inParam.txtの内容例を以下に示します。
　　　------------------------------------------------------------------
　　　C:/voicebank/example
　　　C:/voicebank/example/oto-autoEstimation.ini
　　　0.01
　　　0.02
　　　5
　　　3,4,5
　　　------------------------------------------------------------------

　 　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行目に示したファイルに
　 上書きして終了して下さい。

5) setParamがinParam.txtの2行目に示したファイルを読み込みます。
　 その際、プラグイン設定ファイル(plugin.txt)で指定したプラグインの種類に応じて
　 データの取り込み方(全部取り込むか or 該当行だけ取り込むか)が変わります。


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

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

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

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


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

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

　　%S ← 処理対象の音源フォルダの絶対パス。
　　%s ← 処理対象の音源フォルダの絶対パス。
　　   　 旧版のプラグインとの後方互換性用であり、パスが空白を含む場合に文字列が分解される。
　　%R ← setParam〜プラグイン間のデータ受け渡し用原音設定ファイルの絶対パス。
　　%r ← setParam〜プラグイン間のデータ受け渡し用原音設定ファイルの絶対パス。
　　   　 旧版のプラグインとの後方互換性用であり、パスが空白を含む場合に文字列が分解される。
　　%f ← F0の抽出間隔（単位=秒）。
　　%p ← パワーの抽出間隔（単位=秒）。
　　%n ← 現在表示中の波形はデータ受け渡し用原音設定ファイルの何行目か。
　　%l ← 現在選択中の各データは受け渡し用原音設定ファイルの何行目かのリスト。
　　   　 例えば2行目〜4行目を選択しているなら「2,3,4」とコンマ刻みの文字列になります。

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

さらに音源フォルダ名が「c:/Program Files/」のように空白を含む場合、
%sと%rでは、"c:/Program"と"Files/"の二つの文字列に分けて受け取ると思いますので注意が必要です。
そのためなるべく%Sと%Rを利用するか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です。


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

開発したプラグインの動作が以下のいずれに該当するかを指定します。

　・setParamの波形窓で表示中のデータのみを更新するプラグインなら
　　→  edit=single
　・setParamのパラメータ一覧表で選択した範囲の行だけを更新するプラグインなら
　　→　edit=region
　・全データを更新するプラグインなら
　　→　edit=all

プラグインの実行結果を読み込む際に、setParamはeditの値に応じて
該当行だけ読み込むのか全部を読み込み直すのかを以下の例のように切り替えます。

例1：oto.iniの3行目のデータを表示している時にedit=singleのプラグインを実行した場合、
　　 setParamは結果ファイルの冒頭2行目を読み飛ばして3行目のみを取り込みます。

例2：oto.iniの3、4、7行目のデータを一覧表で表示している時にedit=regionのプラグインを実行した場合、
　　 setParamは結果ファイルの冒頭2行目を読み飛ばし、3〜7行目を取り込みます。

例3：edit=allのプラグインを実行した場合、
　　 setParamは結果ファイルをすべて取り込みます。


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

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

