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 を操作するオブジェクトを生成します。
サンプルプログラムでは、メイン画面の生成時にオブジェクトを生成しています。
1private TtsControl _ttsControl; // TTS APIの呼び出し用オブジェクト
2
3public MainWindow()
4{
5 InitializeComponent();
6
7 this.DataContext = _vm;
8
9 _ttsControl = new TtsControl();
10}
利用可能なホスト名の一覧を取得する¶
同 PC にインストールされている、本 API により操作可能なホストプログラムの名称の一覧を取得します。
サンプルプログラムでは、メイン画面のロード時に操作可能なホストプログラムを取得し、名称をホストプログラム一覧のコンボボックスの選択候補に設定しています。
1private void Window_Loaded(object sender, RoutedEventArgs e)
2{
3 // 接続可能なホストの一覧を取得する
4 _vm.AvailableHosts = _ttsControl.GetAvailableHostNames();
5
6 if (_vm.AvailableHosts.Count() > 0)
7 {
8 _vm.CurrentHost = _vm.AvailableHosts[0];
9 }
10}
API を初期化する¶
接続対象のホスト名称を指定し、API を初期化します。
接続可能なホストの名称は、前項の GetAvailableHostNames() で取得します。
サンプルプログラムでは、「接続」ボタンの押下時にホストプログラム一覧のコンボボックスで選択されたホスト名称を渡して初期化しています。
1private void ButtonStartup_Click(object sender, RoutedEventArgs e)
2{
3 try
4 {
5 // APIを初期化する
6 _ttsControl.Initialize(_vm.CurrentHost);
7
8 // ホストと接続する
9 this.Startup();
10 }
11 catch (Exception ex)
12 {
13 this.ShowError("接続処理でエラーが発生しました。" + Environment.NewLine + ex.Message);
14 }
15}
ホストへ接続する¶
初期化時に指定したホストプログラムへの接続を確立します。
サンプルプログラムでは、前項の「接続」ボタンの押下時に呼びだされる Startup() メソッド内で接続を行っています。
1private void Startup()
2{
3 try
4 {
5 if (_ttsControl.Status == HostStatus.NotRunning)
6 {
7 // ホストプログラムを起動する
8 _ttsControl.StartHost();
9 }
10
11 // ホストプログラムに接続する
12 _ttsControl.Connect();
13
14 _vm.DisplayVersion = "ホストバージョン: " + _ttsControl.Version;
15
16 this.RefreshVoiceNames();
17 this.RefreshVoicePresetNames();
18
19 TextBox.Focus();
20
21 this.ShowStatus("ホストへの接続を開始しました。");
22 }
23 catch (Exception ex)
24 {
25 this.ShowError("ホストへの接続に失敗しました。" + Environment.NewLine + ex.Message);
26 }
27}
※ ホストプログラムへ接続後、10分間 API を介した操作が行われない状態が続くと自動的に接続が解除されます。
ホストの各種値を取得する¶
ホストプログラムの各種設定値を取得します。
取得可能な値に関しては API リファレンスを参照してください。
以下の例では、テキスト形式タブの「ホストから取得」ボタン押下時にテキストとその選択状態を取得し、サンプルプログラムへ反映しています。
1private void ButtonGetText_Click(object sender, RoutedEventArgs e)
2{
3 try
4 {
5 // テキスト
6 _vm.Text = _ttsControl.Text;
7
8 // 選択開始位置
9 TextBox.SelectionStart = _ttsControl.TextSelectionStart;
10
11 // 選択文字数
12 TextBox.SelectionLength = _ttsControl.TextSelectionLength;
13
14 TextBox.Focus();
15
16 this.ShowStatus("テキスト形式のテキストを取得しました。");
17 }
18 catch (Exception ex)
19 {
20 this.ShowError("テキスト形式のテキストの取得に失敗しました。" + Environment.NewLine + ex.Message);
21 }
22
23}
以下の例では、マスターコントロールの「ホストから取得」ボタン押下時にホストプログラムのマスターコントロールの値を取得し、サンプルプログラムへ反映しています。
1private void ButtonGetMasterControl_Click(object sender, RoutedEventArgs e)
2{
3 try
4 {
5 JsonToMasterControl(_ttsControl.MasterControl);
6
7 this.ShowStatus("マスターコントロールを取得しました。");
8 }
9 catch (Exception ex)
10 {
11 this.ShowError(this, "マスターコントロールの取得に失敗しました。" + Environment.NewLine + ex.Message);
12 }
13}
マスターコントロールの値は JSON 形式の文字列で授受を行います。
下記 JsonToMasterControl() メソッドではホストプログラムから取得した JSON 形式の文字列から実際の値へ変換しています。
1void JsonToMasterControl(string json)
2{
3 // { "Volume":1.00, "Speed":1.00, "Pitch":1.00, ... }
4
5 var jsonDocument = System.Text.Json.JsonDocument.Parse(json);
6
7 if (jsonDocument != null)
8 {
9 _vm.Volume = jsonDocument.RootElement.GetProperty("Volume").GetDouble();
10 _vm.Speed = jsonDocument.RootElement.GetProperty("Speed").GetDouble();
11 _vm.Pitch = jsonDocument.RootElement.GetProperty("Pitch").GetDouble();
12 _vm.PitchRange = jsonDocument.RootElement.GetProperty("PitchRange").GetDouble();
13 _vm.MiddlePause = jsonDocument.RootElement.GetProperty("MiddlePause").GetInt32();
14 _vm.LongPause = jsonDocument.RootElement.GetProperty("LongPause").GetInt32();
15 _vm.SentencePause = jsonDocument.RootElement.GetProperty("SentencePause").GetInt32();
16 }
17}
以下の例では、ボイスプリセット一覧の「表示」ボタン押下時に選択されているボイスプリセットの各値を JSON 形式に整形した文字列をメッセージボックスで表示しています。
1private void ButtonShowVoicePresetInfo_Click(object sender, RoutedEventArgs e)
2{
3 // 選択されているボイスプリセットの情報を JSON 形式のテキストとして取得
4 var jsonVoicePreset = _ttsControl.GetVoicePreset(_ttsControl.CurrentVoicePresetName);
5
6 // メッセージダイアログで表示
7 this.ShowInformation(jsonVoicePreset);
8
9 this.ShowStatus("ボイスプリセットの情報を取得しました。");
10}
ホストの各種値を設定する¶
ホストプログラムの各種値を設定します。
設定可能な値に関しては API リファレンスを参照してください。
以下の例では、「ホストへ設定」ボタン押下時にサンプルプログラムのテキストとその選択状態をホストプログラムへ反映しています。
1private void ButtonSetText_Click(object sender, RoutedEventArgs e)
2{
3 try
4 {
5 // テキスト
6 _ttsControl.Text = _vm.Text;
7
8 // 選択開始位置
9 _ttsControl.TextSelectionStart = TextBox.SelectionStart;
10
11 // 選択文字数
12 _ttsControl.TextSelectionLength = TextBox.SelectionLength;
13
14 this.ShowStatus("テキスト形式のテキストを設定しました。");
15 }
16 catch (Exception ex)
17 {
18 this.ShowError("テキスト形式のテキストの設定に失敗しました。" + Environment.NewLine + ex.Message);
19 }
20}
以下の例では、「ホストへ設定」ボタン押下時にサンプルプログラムのマスターコントロールの値をホストプログラムへ反映しています。
1private void ButtonSetMasterControl_Click(object sender, RoutedEventArgs e)
2{
3 try
4 {
5 _ttsControl.MasterControl = MasterContorolToJson();
6
7 this.ShowStatus("マスターコントロールを設定しました。");
8 }
9 catch (Exception ex)
10 {
11 this.ShowError(this, "マスターコントロールの設定に失敗しました。" + Environment.NewLine + ex.Message);
12 }
13}
前述の通りマスターコントロールの値は JSON 形式の文字列で授受を行うため、下記 MasterContorolToJson() メソッドでサンプルプログラムでのマスターコントロールの値を JSON 形式の文字列へ変換しています。
1string MasterContorolToJson()
2{
3 return "{ \"Volume\" : " + _vm.Volume + ", " +
4 "\"Pitch\" : " + _vm.Pitch + ", " +
5 "\"Speed\" : " + _vm.Speed + ", " +
6 "\"PitchRange\" : " + _vm.PitchRange + ", " +
7 "\"MiddlePause\" : " + _vm.MiddlePause + ", " +
8 "\"LongPause\" : " + _vm.LongPause + ", " +
9 "\"SentencePause\" : " + _vm.SentencePause + " }";
10}
ボイスプリセットの追加・設定は、マスターコントロールと同様に JSON 形式の文字列を使用します。
各値の指定方法は API リファレンスを参照してください。また、前述の ホストの各種値を取得する のボイスプリセット値取得の結果を参考にしてください。
テキストの読み上げを開始する¶
ホストプログラムでテキストの読み上げを開始します。
1private void ButtonPlay_Click(object sender, RoutedEventArgs e)
2{
3 try
4 {
5 // 再生
6 _ttsControl.Play();
7
8 this.ShowStatus("音声を再生しました。");
9 }
10 catch (Exception ex)
11 {
12 this.ShowError("音声の再生に失敗しました。" + Environment.NewLine + ex.Message);
13 }
14}
テキストの読み上げを停止する¶
ホストプログラムでのテキストの読み上げを停止します。
1private void ButtonStop_Click(object sender, RoutedEventArgs e)
2{
3 try
4 {
5 // 停止
6 _ttsControl.Stop();
7
8 this.ShowStatus("音声を停止しました。");
9 }
10 catch (Exception ex)
11 {
12 this.ShowError("音声の停止に失敗しました。" + Environment.NewLine + ex.Message);
13 }
14}
読み上げ音声をファイルに保存する¶
保存先のパスを指定して、読み上げ音声をファイルに保存します。読み上げるテキストや音声効果値、音声ファイル保存に関する設定はホストプログラムの値が使用されます。
SaveAudioToFile() は同期メソッドであるため、処理が終わるまで呼び出し位置でプログラムが停止します。非同期化する場合は呼び出し側で実装してください。
サンプルプログラムでは、ファイル保存ダイアログで指定したパスへの音声保存処理を別スレッドで行い、処理中は待機画面を表示しています。
1private void ButtonSaveAudioToFile_Click(object sender, RoutedEventArgs e)
2{
3 string path = null;
4
5 // 省略:ファイル保存ダイアログでパスを決定、path に格納する
6
7 var context = System.Threading.SynchronizationContext.Current;
8
9 // 待機画面を作成
10 var dialog = new WaitWindow()
11 {
12 Title = "音声ファイル保存",
13 Owner = this,
14 };
15
16 // 保存処理を別スレッドで実行
17 var task = Task.Factory.StartNew(() =>
18 {
19 try
20 {
21 // 合成結果をファイルに保存する
22 _ttsControl.SaveAudioToFile(path);
23
24 // 保存処理が終了したら待機画面のメッセージを変更、「OK」ボタンを押下可能にする
25 var msg = "音声をファイルに保存しました。";
26 this.ShowStatus(msg);
27 dialog.ViewModel.Text = msg;
28 dialog.ViewModel.ButtonVisibility = Visibility.Visible;
29 }
30 catch (Exception ex)
31 {
32 context.Send(_ =>
33 {
34 this.ShowError(dialog, "音声の保存に失敗しました。" + Environment.NewLine + ex.Message);
35 dialog.Close();
36 }, null);
37 }
38 });
39
40 // 待機画面を表示
41 dialog.ShowDialog();
42}
ホストとの接続を解除する¶
ホストプログラムへの接続を解除します。
サンプルプログラムでは、「切断」ボタン押下時と、画面が閉じる(プログラムを終了する)時に下記 Disconnect() メソッドを呼び出し接続を解除しています。
1private void Disconnect()
2{
3 try
4 {
5 // ホストプログラムとの接続を解除する
6 _ttsControl.Disconnect();
7
8 this.ShowStatus("ホストへの接続を終了しました。");
9 }
10 catch (Exception ex)
11 {
12 this.ShowError("ホストへの接続の終了に失敗しました。" + Environment.NewLine + ex.Message);
13 }
14}
A.I.VOICE Editor API利用規約¶
第1条(目的)
本A.I.VOICE Editor API利用規約(以下「本規約」といいます)は、株式会社エーアイ(以下「当社」といいます)が提供する「A.I.VOICE」シリーズ製品(以下「A.I.VOICE製品」といいます)の拡張機能として提供されるA.I.VOICE Editor API機能(以下「本API」といいます)をお客様が使用する条件を定めるものです。
第2条(契約の成立)
1.お客様は、あらかじめA.I.VOICE製品の正当なライセンスを有した上で、A.I.VOICE製品のエンドユーザー使用許諾契約書(以下「A.I.VOICE製品EULA」といいます)に加えて本規約の内容に同意した上で、本APIを利用するものとします。
2.本APIの利用を開始した時点で、お客様が本規約に同意したものとみなされ、お客様と当社との間で本規約を内容とする利用契約が成立します。
3.本APIを法人が利用する場合には、ご利用条件等について個別にご確認の上、別途契約が必要となりますので、別途お問合せください。
4.本APIを個人が商用に利用する場合には、別途お問合せください。
第3条(禁止事項)
お客様は、次に掲げる行為をしてはならないものとします。
(1)本APIを、本規約又はA.I.VOICE製品EULAに違反する利用形態で利用し、又は第三者に利用をさせること(利用方法の公開を含む)
(2)複数人が同時に使用又は共有可能なコンピュータ上で本APIを使用すること、及び、本APIをサーバー利用(複数人が同時に接続し利用することが可能な状態)すること(Discord サーバー上のテキストチャンネルの投稿を Discord Bot を介して ボイスチャンネルで読み上げる用途を除く)
(3)その他、当社が不適切であると合理的に判断する行為
第4条(本規約の変更)
当社は、法令等を遵守するために必要なとき、お客様の一般の利益に適合するとき、当社が合理的に必要と考えるときには、本規約を変更する旨及び変更後の内容並びにその変更の効力発生時期を、お客様への通知、インターネットの利用その他の適切な方法により周知することによって、本規約の内容を変更することができるものとします。
2022年2月22日 規約制定
2023年3月15日 改訂