A.I.VOICE Editor API¶
The to operate A.I.VOICE Editor from an external program is released as a NET assembly.COM component.
Use it to develop applications that make A.I.VOICE with more freedom and more convenience
A.I.VOICE Editor API reference¶
Please see “A.I.VOICE Editor API class library reference”
Tutorial¶
Explains the basic method of linking with A.I.VOICE Editor using API functions, referring to the sample program code.
This section is based on a sample program from .NET.
The sample programme can be downloaded from below.
* WpfSample requires System.Text.Json to be installed. Get the package from NuGet.
* System.Text.Json is not required to use the A.I.VOICE Editor API. The WpfSample project is used as an example of how to handle JSON.
* This sample program was created for the purpose of explaining how to use the API and may contain content that is not appropriate for a general program.
Adding references¶
Add “AI.Talk.Editor.Api.dll” in the installation folder to the project reference.
Generate API objects¶
Creates an object to operate the A.I.VOICE Editor.
In the sample program, objects are generated when the main screen is generated.
1private TtsControl _ttsControl; // TTS APIの呼び出し用オブジェクト
2
3public MainWindow()
4{
5 InitializeComponent();
6
7 this.DataContext = _vm;
8
9 _ttsControl = new TtsControl();
10}
Get a list of available hostnames¶
Obtains a list of names of host programs installed on the same PC that can be operated with this API.
In the sample program, the host program that can be operated is acquired when the main screen is loaded, and the name is set as an option for selection in the combo box of the host program list.
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}
Initialize API¶
Specifies the host name to connect to and initializes the API.
Host names available for connection can be aquired from GetAvailableHostNames() in the previous section.
In the sample program, the host name selected in the combo box of the host program list is passed and initialized when the “Connect” button is pressed.
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}
Connect to host¶
Establishes a connection to the host program that was specified when initializing.
In the sample program, the connection is made in the Startup() method when the “Connect” button is pressed as described in the previous section.
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}
* After connecting to the host program, the connection will be automatically disconnected after 10 minutes of inactivity via the API.
Obtain various host values¶
Obtains various setting values of the host program.
See the API reference for possible values.
In the example below, the text and its selection status are acquired when the “ホストから取得” button on the text format tab is pressed and reflected in the sample program.
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}
In the following example, when the “ホストから取得” button of the master control is pressed, the value of the master control in the host program is acquired and reflected in the sample program.
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}
Master control values are exchanged in JSON format strings.
The JsonToMasterControl() method below converts a string in JSON format obtained from the host program to an actual value.
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}
In the following example, a message box displays a string formatted in JSON format for each value of the voice preset selected when the “表示” button in the voice preset list is pressed.
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}
Set various host values¶
Sets various values for the host program.
See the API reference for possible values.
In the following example, the text of the sample program and its selection status are reflected to the host program when the “ホストへ設定” button is pressed.
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}
In the following example, when the “ホストへ設定” button is pressed, the master control values in the sample program are reflected to the host program.
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}
As mentioned above, master control values are exchanged in JSON format strings, so the MasterContorolToJson() method below converts the master control values in the sample program to JSON format strings.
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}
Voice presets are added and configured using JSON format strings in the same way as the master control.
Refer to the API reference for details on how to specify each value. Also, refer to the results of acquiring voice preset values in “Obtain various host values” above.
Start reading aloud text¶
Start reading aloud text by host program.
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}
Stop reading aloud text¶
Stops text reading in the host program.
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}
Save audio that was read aloud¶
Saves the audio file to a specified pass. The text to be read, voice effect, values, and settings related to saving the voice file will use the host program values.
Since SaveAudioToFile() is a synchronous method, the program stops at the call position until processing is complete. If you want to make it asynchronous, implement it on the caller side.
In the sample program, the audio saving process to the specified pass in the file saving dialog is performed in a separate thread, and a standby screen is displayed while processing.
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 from host¶
Disconnect from host program.
In the sample program, the following Disconnect() method is called to break the connection when the “切断” button is pressed or when the screen is closed (Terminate program).
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 Terms and Conditions¶
Article 1 (Purpose)
The A.I.VOICE Editor API Terms and Conditions (hereinafter referred to as the “Terms and Conditions”) stipulate the terms and conditions when you use the external cooperation API function (hereinafter referred to as the “API”) provided as an extension of the “A.I.VOICE” series products (hereinafter simply referred to as the “A.I.VOICE”) provided by AI, Inc. (hereinafter referred to as the “Company”).
Article 2 (Conclusion of Contract)
1. You shall use this API with genuine license of the A.I.VOICE and having agreed to this Terms and Conditions as well as the End User License Agreement for A.I.VOICE (hereinafter referred to as “A.I.VOICE EULA”).
2. When you start to use this API, you shall be deemed to have agreed to this Terms and Confitions, and the contract between you and the Company shall be concluded under the condition described in this Terms and Conditions.
3. If you as a corporation wish to use this API, you need to check other conditions for use and enter into a separete agreement with the Company. Please contact the Company.
4. If you as an individual wish to use this API for commercial purposes, please contact the Company.
Article 3 (Prohibitions)
You shall not engage in any of the following acts:
(1) To use this API in a manner that violates this Terms and Confitions or the A.I.VOICE EULA, or make a third party to do the same (including disclosure of the method of such use);
(2) To use this API on a computer that can be used or shared by multiple people at the same time, and to use this API on a server which can be connected and used by multiple people. (Excludes text channel posts on a Discord server that are read out on a voice channel via a Discord Bot)
(3) Any other acts that we reasonably deem inappropriate.
Article 4 (Amendment of this Terms and Confitions)
The Company may change the contents of this Terms and Conditions by announcing the change of this Terms and Conditions, the changed contents and the effective date/time in an appropriate manner including notifying you, using the Internet, when it is necessary to comply with the laws and regulations, when it is conform to the general interests of the customers, or when the Company reasonably deems it necessary.
Established on March 15 , 2023