A.I.VOICE Editor API¶

外部プログラムから A.I.VOICE Editor を操作する機能を、.NET アセンブリ・COM コンポーネントとして公開します。

A.I.VOICE をさらに自由に、さらに便利にするアプリケーションの開発にご利用ください。

A.I.VOICE Editor API リファレンス¶

「A.I.VOICE Editor API クラスライブラリリファレンス」を参照してください。

チュートリアル¶

API 機能を利用して A.I.VOICE Editor と連携する基本的な方法を、サンプルプログラムのコードを参考に解説します。

本項では .NET のサンプルプログラムを元に記述します。

サンプルプログラムは以下からダウンロード可能です。

WpfSample.zip

COMSample.zip

※ WpfSample の実行には System.Text.Json のインストールが必要です。NuGet よりパッケージを取得してください。
※ System.Text.Json は A.I.VOICE Editor API の利用に必須ではありません。WpfSample プロジェクトでは JSON の取り扱い方法の一例として使用しています。
※ 本サンプルプログラムは API の利用方法を解説する目的で作成されており、一般的なプログラムとして適切ではない内容を含む可能性があります。

参照の追加¶

プロジェクトの参照に、インストールフォルダーにある「AI.Talk.Editor.Api.dll」を追加します。

API オブジェクトを生成する¶

A.I.VOICE Editor を操作するオブジェクトを生成します。

サンプルプログラムでは、メイン画面の生成時にオブジェクトを生成しています。

private TtsControl _ttsControl;     // TTS APIの呼び出し用オブジェクト

public MainWindow()
{
    InitializeComponent();

    this.DataContext = _vm;

    _ttsControl = new TtsControl();
}

利用可能なホスト名の一覧を取得する¶

同 PC にインストールされている、本 API により操作可能なホストプログラムの名称の一覧を取得します。

サンプルプログラムでは、メイン画面のロード時に操作可能なホストプログラムを取得し、名称をホストプログラム一覧のコンボボックスの選択候補に設定しています。

private void Window_Loaded(object sender, RoutedEventArgs e)
{
    // 接続可能なホストの一覧を取得する
    _vm.AvailableHosts = _ttsControl.GetAvailableHostNames();

    if (_vm.AvailableHosts.Count() > 0)
    {
        _vm.CurrentHost = _vm.AvailableHosts[0];
    }
}

API を初期化する¶

接続対象のホスト名称を指定し、API を初期化します。

接続可能なホストの名称は、前項の GetAvailableHostNames() で取得します。

サンプルプログラムでは、「接続」ボタンの押下時にホストプログラム一覧のコンボボックスで選択されたホスト名称を渡して初期化しています。

private void ButtonStartup_Click(object sender, RoutedEventArgs e)
{
    try
    {
        // APIを初期化する
        _ttsControl.Initialize(_vm.CurrentHost);

        // ホストと接続する
        this.Startup();
    }
    catch (Exception ex)
    {
        this.ShowError("接続処理でエラーが発生しました。" + Environment.NewLine + ex.Message);
    }
}

ホストへ接続する¶

初期化時に指定したホストプログラムへの接続を確立します。

サンプルプログラムでは、前項の「接続」ボタンの押下時に呼びだされる Startup() メソッド内で接続を行っています。

private void Startup()
{
    try
    {
        if (_ttsControl.Status == HostStatus.NotRunning)
        {
            // ホストプログラムを起動する
            _ttsControl.StartHost();
        }

        // ホストプログラムに接続する
        _ttsControl.Connect();

        _vm.DisplayVersion = "ホストバージョン: " + _ttsControl.Version;

        this.RefreshVoiceNames();
        this.RefreshVoicePresetNames();

        TextBox.Focus();

        this.ShowStatus("ホストへの接続を開始しました。");
    }
    catch (Exception ex)
    {
        this.ShowError("ホストへの接続に失敗しました。" + Environment.NewLine + ex.Message);
    }
}

※ ホストプログラムへ接続後、10分間 API を介した操作が行われない状態が続くと自動的に接続が解除されます。

ホストの各種値を取得する¶

ホストプログラムの各種設定値を取得します。

取得可能な値に関しては API リファレンスを参照してください。

以下の例では、テキスト形式タブの「ホストから取得」ボタン押下時にテキストとその選択状態を取得し、サンプルプログラムへ反映しています。

private void ButtonGetText_Click(object sender, RoutedEventArgs e)
{
    try
    {
        // テキスト
        _vm.Text = _ttsControl.Text;

        // 選択開始位置
        TextBox.SelectionStart = _ttsControl.TextSelectionStart;

        // 選択文字数
        TextBox.SelectionLength = _ttsControl.TextSelectionLength;

        TextBox.Focus();

        this.ShowStatus("テキスト形式のテキストを取得しました。");
    }
    catch (Exception ex)
    {
        this.ShowError("テキスト形式のテキストの取得に失敗しました。" + Environment.NewLine + ex.Message);
    }

}

以下の例では、マスターコントロールの「ホストから取得」ボタン押下時にホストプログラムのマスターコントロールの値を取得し、サンプルプログラムへ反映しています。

private void ButtonGetMasterControl_Click(object sender, RoutedEventArgs e)
{
    try
    {
        JsonToMasterControl(_ttsControl.MasterControl);

        this.ShowStatus("マスターコントロールを取得しました。");
    }
    catch (Exception ex)
    {
        this.ShowError(this, "マスターコントロールの取得に失敗しました。" + Environment.NewLine + ex.Message);
    }
}

マスターコントロールの値は JSON 形式の文字列で授受を行います。

下記 JsonToMasterControl() メソッドではホストプログラムから取得した JSON 形式の文字列から実際の値へ変換しています。

void JsonToMasterControl(string json)
{
    // { "Volume":1.00, "Speed":1.00, "Pitch":1.00, ... }

    var jsonDocument = System.Text.Json.JsonDocument.Parse(json);

    if (jsonDocument != null)
    {
        _vm.Volume = jsonDocument.RootElement.GetProperty("Volume").GetDouble();
        _vm.Speed = jsonDocument.RootElement.GetProperty("Speed").GetDouble();
        _vm.Pitch = jsonDocument.RootElement.GetProperty("Pitch").GetDouble();
        _vm.PitchRange = jsonDocument.RootElement.GetProperty("PitchRange").GetDouble();
        _vm.MiddlePause = jsonDocument.RootElement.GetProperty("MiddlePause").GetInt32();
        _vm.LongPause = jsonDocument.RootElement.GetProperty("LongPause").GetInt32();
        _vm.SentencePause = jsonDocument.RootElement.GetProperty("SentencePause").GetInt32();
    }
}

以下の例では、ボイスプリセット一覧の「表示」ボタン押下時に選択されているボイスプリセットの各値を JSON 形式に整形した文字列をメッセージボックスで表示しています。

private void ButtonShowVoicePresetInfo_Click(object sender, RoutedEventArgs e)
{
    // 選択されているボイスプリセットの情報を JSON 形式のテキストとして取得
    var jsonVoicePreset = _ttsControl.GetVoicePreset(_ttsControl.CurrentVoicePresetName);

    // メッセージダイアログで表示
    this.ShowInformation(jsonVoicePreset);

    this.ShowStatus("ボイスプリセットの情報を取得しました。");
}

ホストの各種値を設定する¶

ホストプログラムの各種値を設定します。

設定可能な値に関しては API リファレンスを参照してください。

以下の例では、「ホストへ設定」ボタン押下時にサンプルプログラムのテキストとその選択状態をホストプログラムへ反映しています。

private void ButtonSetText_Click(object sender, RoutedEventArgs e)
{
    try
    {
        // テキスト
        _ttsControl.Text = _vm.Text;

        // 選択開始位置
        _ttsControl.TextSelectionStart = TextBox.SelectionStart;

        // 選択文字数
        _ttsControl.TextSelectionLength = TextBox.SelectionLength;

        this.ShowStatus("テキスト形式のテキストを設定しました。");
    }
    catch (Exception ex)
    {
        this.ShowError("テキスト形式のテキストの設定に失敗しました。" + Environment.NewLine + ex.Message);
    }
}

以下の例では、「ホストへ設定」ボタン押下時にサンプルプログラムのマスターコントロールの値をホストプログラムへ反映しています。

private void ButtonSetMasterControl_Click(object sender, RoutedEventArgs e)
{
    try
    {
        _ttsControl.MasterControl = MasterContorolToJson();

        this.ShowStatus("マスターコントロールを設定しました。");
    }
    catch (Exception ex)
    {
        this.ShowError(this, "マスターコントロールの設定に失敗しました。" + Environment.NewLine + ex.Message);
    }
}

前述の通りマスターコントロールの値は JSON 形式の文字列で授受を行うため、下記 MasterContorolToJson() メソッドでサンプルプログラムでのマスターコントロールの値を JSON 形式の文字列へ変換しています。

string MasterContorolToJson()
{
    return "{ \"Volume\" : " + _vm.Volume + ", " +
        "\"Pitch\" : " + _vm.Pitch + ", " +
        "\"Speed\" : " + _vm.Speed + ", " +
        "\"PitchRange\" : " + _vm.PitchRange + ", " +
        "\"MiddlePause\" : " + _vm.MiddlePause + ", " +
        "\"LongPause\" : " + _vm.LongPause + ", " +
        "\"SentencePause\" : " + _vm.SentencePause + " }";
}

ボイスプリセットの追加・設定は、マスターコントロールと同様に JSON 形式の文字列を使用します。

各値の指定方法は API リファレンスを参照してください。また、前述のホストの各種値を取得するのボイスプリセット値取得の結果を参考にしてください。

テキストの読み上げを開始する¶

ホストプログラムでテキストの読み上げを開始します。

private void ButtonPlay_Click(object sender, RoutedEventArgs e)
{
    try
    {
        // 再生
        _ttsControl.Play();

        this.ShowStatus("音声を再生しました。");
    }
    catch (Exception ex)
    {
        this.ShowError("音声の再生に失敗しました。" + Environment.NewLine + ex.Message);
    }
}

テキストの読み上げを停止する¶

ホストプログラムでのテキストの読み上げを停止します。

private void ButtonStop_Click(object sender, RoutedEventArgs e)
{
    try
    {
        // 停止
        _ttsControl.Stop();

        this.ShowStatus("音声を停止しました。");
    }
    catch (Exception ex)
    {
        this.ShowError("音声の停止に失敗しました。" + Environment.NewLine + ex.Message);
    }
}

読み上げ音声をファイルに保存する¶

保存先のパスを指定して、読み上げ音声をファイルに保存します。読み上げるテキストや音声効果値、音声ファイル保存に関する設定はホストプログラムの値が使用されます。

SaveAudioToFile() は同期メソッドであるため、処理が終わるまで呼び出し位置でプログラムが停止します。非同期化する場合は呼び出し側で実装してください。

サンプルプログラムでは、ファイル保存ダイアログで指定したパスへの音声保存処理を別スレッドで行い、処理中は待機画面を表示しています。

private void ButtonSaveAudioToFile_Click(object sender, RoutedEventArgs e)
{
    string path = null;

    // 省略：ファイル保存ダイアログでパスを決定、path に格納する

    var context = System.Threading.SynchronizationContext.Current;

    // 待機画面を作成
    var dialog = new WaitWindow()
    {
        Title = "音声ファイル保存",
        Owner = this,
    };

    // 保存処理を別スレッドで実行
    var task = Task.Factory.StartNew(() =>
    {
        try
        {
            // 合成結果をファイルに保存する
            _ttsControl.SaveAudioToFile(path);

            // 保存処理が終了したら待機画面のメッセージを変更、「OK」ボタンを押下可能にする
            var msg = "音声をファイルに保存しました。";
            this.ShowStatus(msg);
            dialog.ViewModel.Text = msg;
            dialog.ViewModel.ButtonVisibility = Visibility.Visible;
        }
        catch (Exception ex)
        {
            context.Send(_ =>
            {
                this.ShowError(dialog, "音声の保存に失敗しました。" + Environment.NewLine + ex.Message);
                dialog.Close();
            }, null);
        }
    });

    // 待機画面を表示
    dialog.ShowDialog();
}

ホストとの接続を解除する¶

ホストプログラムへの接続を解除します。

サンプルプログラムでは、「切断」ボタン押下時と、画面が閉じる（プログラムを終了する）時に下記 Disconnect() メソッドを呼び出し接続を解除しています。

private void Disconnect()
{
    try
    {
        // ホストプログラムとの接続を解除する
        _ttsControl.Disconnect();

        this.ShowStatus("ホストへの接続を終了しました。");
    }
    catch (Exception ex)
    {
        this.ShowError("ホストへの接続の終了に失敗しました。" + Environment.NewLine + ex.Message);
    }
}