====== echoseika API DLL 説明 ======

2018/06/24\\
旧文書を再編集しました。以降メンテナンスされません。

\\
\\
\\
\\
\\
\\

===== DLLの使用例 =====

AvatorControllerクラスのインスタンスを作成し、操作対象の話者を登録します。登録された話者に対してアクションを指定します。
==== VOICEROID+EX操作例 ====

以下は VOICEROID+京町セイカ EX を発声させる最少コードです。

<code csharp sample.cs>
using System;
using echoSeikaAPI;

namespace sample
{
    class Program
    {
        static void Main()
        {
            AvatorController control = new AvatorController();          // コントローラオブジェクト生成
            if (control.Register(Avator.SEIKA))                         // 話者 VOICEROID+京町セイカ EXの登録ができた
            {
                control.PlaySync(Avator.SEIKA, "寒い日が続きますね");     // VOICEROID+京町セイカ EX 発声
            }
        }
    }
}
</code>

==== CeVIO操作例 ====

以下は CeVIO-さとうささら を発声させる最少コードです。
このプログラムは32bitコードの必要があります。

<code csharp sample.cs>
using System;
using echoSeikaAPI;

namespace sample
{
    class Program
    {
        static void Main()
        {
            AvatorController control = new AvatorController();          // コントローラオブジェクト生成
            if (control.Register(Avator.SASARA))                        // 話者 CeVIO-さとうささらの登録ができた
            {
                control.PlaySync(Avator.SASARA, "寒い日が続きますね");    // CeVIO-さとうささら 発声
            }
        }
    }
}
</code>

==== SAPI操作例 ====

以下は SAPIの話者 "Microsoft Haruka Desktop"を発声させる最少コードです。

<code csharp sample.cs>
using System;
using echoSeikaAPI;

namespace sample
{
    class Program
    {
        static void Main()
        {
            AvatorController control = new AvatorController();          // コントローラオブジェクト生成
            if (control.Register(Avator.SAPI))                          // 話者SAPIの登録ができた
            {
                control.SetTalkerName(Avator.SAPI, "Microsoft Haruka Desktop");  // SAPI話者に "Microsoft Haruka Desktop" を指定
                control.PlaySync(Avator.SAPI, "寒い日が続きますね");               // "Microsoft Haruka Desktop" 発声
            }
        }
    }
}
</code>

===== DLLのエントリ説明 =====

以下は 2018/04/14 公開のDLL( c)についての説明です。

==== エントリ ====

現在以下のエントリが公開されています。
<code csharp>
public string DLLVersion();                                            // 外部向けバージョンを返す
public bool Register(Avator cv);                                       // 話者をコントローラに登録する(use_pm = true)
public bool Register(Avator cv, bool use_pm);                          // 話者をコントローラに登録する
public bool isRegisted(Avator cv);                                     // 話者が登録されているか確認する
public bool Remove(Avator cv);                                         // 話者をコントローラの登録から外す
public void PlaySync(Avator cv, string talkText);                      // 話者に発声させる。cvが TAMMY, YUKARI, YOSHIDA, の時はPlayAsync()と同じ動作になる。
public void PlayAsync(Avator cv, string talkText);                     // 話者に発声させる(非同期)
public void Save(Avator cv, string talkText, string WavFilePath);      // 話者の発声内容を保存する

public string[] GetAvailableTaker(Avator cv);                          // SAPI用 利用可能な話者の一覧を返す
public void SetTalkerName(Avator cv, string cvName);                   // SAPI用 話者名を登録する

public void SetPostMessageWait(Avator cv, int wait);                   　       // VOICEROID用。保存ダイアログ表示を待ち合わせる時間。100ミリ秒以上で指定。
public void SetVoiceEffectParam(Avator cv, VoiceEffectParam ve, decimal param); // 話者の音声効果を設定する
public bool SetVoiceEmotionParam(Avator cv, string ve, decimal param);          // 話者の感情パラメタを設定する
</code>

==== 話者 ====

enum Avator には以下の話者が定義されています。

^ 製品                      ^ 値                  ^
| VOICEROID＋ 京町セイカ EX     | Avator.SEIKA       |
| VOICEROID＋ 琴葉茜          | Avator.AKANE       |
| VOICEROID＋ 琴葉葵          | Avator.AOI         |
| VOICEROID＋ 水奈瀬コウ EX     | Avator.MINASE      |
| VOICEROID＋ 東北きりたん EX    | Avator.KIRITAN     |
| 音街ウナTalk Ex             | Avator.UNA         |
| VOICEROID＋ 民安ともえ        | Avator.TAMMY       |
| VOICEROID＋ 民安ともえ EX     | Avator.TAMMY_EX    |
| VOICEROID＋ 東北ずん子        | Avator.ZUNKO       |
| VOICEROID＋ 東北ずん子 EX     | Avator.ZUNKO_EX    |
| VOICEROID＋ 結月ゆかり        | Avator.YUKARI      |
| VOICEROID＋ 結月ゆかり EX     | Avator.YUKARI_EX   |
| VOICEROID＋ 鷹の爪 吉田くん     | Avator.YOSHIDA     |
| VOICEROID＋ 鷹の爪 吉田くん EX  | Avator.YOSHIDA_EX  |
| VOICEROID＋ 月読アイ EX      | Avator.AI_EX       |
| VOICEROID＋ 月読ショウタ EX    | Avator.SHOUTA_EX   |
| CeVIOさとうささら             | Avator.SASARA      |
| CeVIOすずきつづみ             | Avator.TSUZUMI     |
| CeVIOタカハシ               | Avator.TAKAHASHI   |
| CeVIO-ONE               | Avator.ONE         |
| CeVIO-IA                | Avator.IA          |
| Speech API 5            | Avator.SAPI        |


==== 登録、削除 ====

話者をコントローラーに登録します。

<code csharp>
control.Register(Avator.SEIKA);                            // 登録成功時 true が返る
control.Remove(Avator.SEIKA);                              // 削除成功時 true が返る
</code>

複数製品を同時制御したい場合は Register() を製品毎に実行します。Remove() は登録話者製品の制御を終了します。

SAPI使用時は Register() の後に SetTalkerName() で話者を明示します。

<code csharp>
control.Register(Avator.SAPI);                            // 登録成功時 true が返る
control.SetTalkerName(Avator.SAPI, "CeVIO-さとうささら");   // SAPI利用時は、話者名をこのメソッドで指定する
control.Remove(Avator.SAPI);                              // 削除成功時 true が返る
</code>

VOICEROID+/+EX利用時、DLL制御下でアプリケーションウインドウが見えなくなるのが嫌だ、と言う場合はこの指定をどうぞ。 
<code csharp>
control.Register(Avator.SEIKA, false);                     // z-order制御が甘くなるけどアプリケーションウインドウは消えない
</code>

==== 話者一覧取得 ====

SAPI使用時、話者一覧を取得可能です。

<code csharp>
control.Register(Avator.SAPI);                            // 登録成功時 true が返る
string[] list = control.GetAvailableTaker(Avator.SAPI);   // 話者一覧を取得する
control.SetTalkerName(Avator.SAPI, list[0]);              // 話者一覧最初の話者を指定する
</code>


==== 音声効果設定 ====

音量,話速,高さ,声質,イントネーション を設定します。

<code csharp>
control.SetVoiceEffectParam(Avator.SEIKA, VoiceEffectParam.volume,     volume);     // 音量(大きさ)
control.SetVoiceEffectParam(Avator.SEIKA, VoiceEffectParam.speed,      speed);      // 話速(速さ)
control.SetVoiceEffectParam(Avator.SEIKA, VoiceEffectParam.pitch,      pitch);      // 高さ
control.SetVoiceEffectParam(Avator.SEIKA, VoiceEffectParam.alpha,      alpha);      // 声質
control.SetVoiceEffectParam(Avator.SEIKA, VoiceEffectParam.intonation, intonation); // 抑揚
</code>

VOICEROIDには効果に『声質』がないので指定しても無視されます。

製品によって指定できる範囲が異なります。

^ 製品          ^ VOICEROID+         ^ VOICEROID+EX   ^ CeVIO     ^ SAPI        ^
^ 音量          | 0.00 ～ 2.00 (*1)  | 0.00 ～ 2.00   | 0 ～ 100  | 0 ～ 100    |
^ 話速          | 0.5 ～ 2.0 (*2)    | 0.50 ～ 4.00   | 0 ～ 100  | -10 ～  10  |
^ 高さ          | 0.5 ～ 2.0 (*2)    | 0.50 ～ 2.00   | 0 ～ 100  | -           |
^ 声質          | -                  | -              | 0 ～ 100  | -           |
^ 抑揚          | -                  | 0.00 ～ 2.00   | 0 ～ 100  | -           |

(*1)0.05単位で指定 (*2)0.1単位で指定

VOICEROID+/VOICEROID+EXで音声効果を使う場合は、あらかじめ音声効果ウインドウ(音声効果タブ)を表示しておきます。\\
{{:pasted:20230411-190451.png?nolink|大丈夫な設定}}

以下の画面のままだと、コマンドラインで指定した音声効果パラメタが反映されません。\\
{{:pasted:20230411-190517.png?nolink|駄目な設定}}

VOICERID+ 結月ゆかり、民安ともえ、鷹の爪吉田君 (VOICEROID+ EXではないもの) はこのように音声効果ウインドウを表示させておきます。
この時、キーボード(キーボードショートカット)で音声効果パラメタを操作しないでください。やってしまうとおそらく制御不能になります。

この画面は、キーボード(キーボードショートカット)で音声効果を操作してしまい、ピッチにフォーカスが当たったままになっている例です。
画面を閉じて、再度音声効果のウインドウを開き直してください。

{{:pasted:20230411-190537.png?nolink|}}

==== 感情パラメタ設定 ====

このDLLでは CeVIO話者にのみ有効な設定です。

<code csharp>
control.SetVoiceEmotionParam(Avator.SASARA, "元気",   100); // 感情パラメタ "元気"   に 100 を指定
control.SetVoiceEmotionParam(Avator.SASARA, "哀しみ",   0); // 感情パラメタ "哀しみ" に 0 を指定
</code>

範囲は 0 ～ 100 です。感情のパラメタは話者毎に異なるので、CeVIOのエディタで確認してください。"元気"のパラメタを持たない話者に"元気"を指定しても反映されません。

{{:documents:voiceroid:voiceroid-009-010.png?nolink|}}
{{:documents:voiceroid:voiceroid-009-011.png?nolink|}}
{{:documents:voiceroid:voiceroid-009-012.png?nolink|}}\\

このように異なります。
|            ^  感情パラメタ  ^^^^^^^
|:::         ^ "元気"   ^ "普通" ^ "怒り" ^ "哀しみ" ^ "クール" ^ "照れ" ^ "へこみ"  ^
^ さとうささら |  ○     |  ○     |  ○     |  ○     |          |       |          |  
^ すずきつづみ |        |        |        |        |  ○       |  ○    |          |
^ タカハシ　　 |  ○     |  ○     |        |        |          |       |  ○       |

==== 音声再生 ====

<code csharp>
control.PlaySync(Avator.SEIKA,  "寒い日が続きますね");  // 同期再生
control.PlayAsync(Avator.SEIKA, "寒い日が続きますね");  // 非同期再生
</code>

残念ですが、VOICEROID+ では非同期実行ができなくなってしまいました。どちらのメソッドを使っても同期実行となります。

以下のコードは、3人のVOICEROIDが同時にしゃべりだします。PlayAsync()をPlaySync()に置き換えてみるとはっきり違いが判るでしょう。
<code csharp>
using System;
using echoSeikaAPI;

namespace sample
{
    class sample
    {
        static void Main()
        {
            AvatorController control = new AvatorController();

            control.Register(Avator.SEIKA);
            control.Register(Avator.ZUNKO_EX);
            control.Register(Avator.TAMMY_EX);

            control.PlayAsync(Avator.SEIKA,    "カエルの歌がー、聞こえてくるよー");
            control.PlayAsync(Avator.ZUNKO_EX, "カエルの歌がー、聞こえてくるよー");
            control.PlayAsync(Avator.TAMMY_EX, "カエルの歌がー、聞こえてくるよー");

            // control.PlaySync(Avator.SEIKA,    "カエルの歌がー、聞こえてくるよー");
            // control.PlaySync(Avator.ZUNKO_EX, "カエルの歌がー、聞こえてくるよー");
            // control.PlaySync(Avator.TAMMY_EX, "カエルの歌がー、聞こえてくるよー");

            Console.ReadKey();
        }
    }
}
</code>


==== 音声保存 ====

WAVファイルの保存ができます。ファイルはフルパスで指定してください。\\
VOICEROIDは過去に開いたフォルダを覚えているので、相対パス指定だと何処に保存されたかわからなくなります。

<code csharp>
control.Save(Avator.SEIKA, "寒い日が続きますね",  @"H:\echoseika\samui.wav");
</code>

VOICEROIDでWAVファイル保存を実行するとダイアログが表示されます。\\
DLLは制御システム上、ダイアログが表示されてからダイアログ検出を始めます。ですが、ダイアログが表示されているか否かを判断することができません。そのため、指定時間を待ってその間にダイアログが表示されたものと仮定して検出を開始します。\\
なおダイアログ検出に失敗すれば、保存ダイアログは表示されたままとなり、手動操作しなければなりません。

待ち時間のデフォルトは1000ミリ秒(1秒)です。\\
もし実行環境が高性能/低負荷なら待ち時間を変更してダイアログ表示時間を短くすることが可能かもしれません。高負荷な環境であれば1000ミリ秒でも足りないかもしれません。\\
以下は待ち時間を500ミリ秒(0.5秒)に変更した例です。

<code csharp>
control.SetPostMessageWait(Avator.SEIKA, 500);
control.Save(Avator.SEIKA, "寒い日が続きますね",  @"H:\echoseika\samui.wav");
</code>


===== CeVIO使用時の注意 =====

このDLLでCeVIO話者を使うアプリケーションは、32bitアプリケーションでなければいけません。\\
CeVIO（とCeVIOの外部連携インターフェース）が32bitアプリケーションであることを要求します。


{{tag> 技術資料 Windows voiceroid tool}}