AquesTalk10 iOS マニュアル株式会社 アクエスト
www.a-quest.com

概要
本文書は、音声合成ライブラリ AquesTalk10 iOS をアプリケーションに組み込んで使用するためのプログラミングの方法、注意点を示したものです。
AquesTalk10 は、かな表記の音声記号列から WAV 音声データを生成するライブラリです。
AquesTalk10 は、声質パラメータを指定することで様々な声質の音声を生成できる特徴があります。
本ライブラリを使用するには、開発ライセンスキーの設定が必要です。このライセンスキーを設定しない場合は、評価版として動作し、以下の制限があります。
評価版の制限「ナ行、マ行」を指定すると、すべて「ヌ」と発声します

また、本ライブラリをアプリケーションに組み込んで使用する際には使用ライセンス、配布には頒布ライセンスが必要です。ライセンスの種類や購入方法は、弊社サイトのライセンスのページを参照してください。

仕様

ライブラリ形式

iOS 用 static ライブラリ arm64,armv7s,armv7,x86_64,i386,bitcode

対応 OS

iOS 5.1.1 以上

入力データ形式

かな表記音声記号列（Shift JIS/UTF8/UTF16)

出力データ形式

WAV フォーマット（16KHz サンプリング,16bitPCM,モノラル）データ*サンプリング周波数は声質パラメータにより変化

声種

ベース音素片 3 種 パラメータでユーザカスタマイズ可関数 I/F

C 関数呼び出し (Objective-C や swift から呼び出し可能）

マルチスレッド対応

ライブラリサイズ

約 150KByte (アーキテクチャあたり)

動作確認環境macOS 10.13, Xcode 9.0, iOS 10.3

サンプルプログラム
本 SDK には、Objective-C 版と Swift 版の２つのサンプルアプリが含まれています。アプリ作成の参考にしてください。
このアプリは、テキストボックスに音声記号列指定して Play ボタンを押下すると合成音声を発声するアプリケーションです。声質パラメータの一部をスライダによって変更し、声質を変化できます。
なお、開発環境は xcode 9.0 で確認しています。

コード説明
以下に、Objective-C 版のサンプルアプリのソースを例に示します。
ヘッダファイル AquesTalk_iPhone.h は、ViewController.h に#import でインポートします。
ライブリ libAquesTalk.a は、「既存のファイルをプロジェクトに追加」で行います。
次に示すコードは、ViewController.m の一部で、[Play]ボタンが押されたときに呼ばれる関数部分です。
4 行目で終了通知のイベントを作成しています。これは、再生が終了したタイミングでラベルの表示を[playing...]から[done]に変更するためです。
テキストボックスから取得した文字列を Shift JIS へ文字コードを変換しています（7 行目）。
音声記号列の指定は、ShiftJIS 以外に、UTF-8 の文字コードの関数もあります。
変数 voice に声質パラメータを設定しています。この例では、プリセット声種[F1]の値をコピーしてから(10行目)、スライダから取得した値を、話速、高さ、音程１の各声質パラメータにセットして(11-13 行目)、声質を変えています。声質パラメータは他にもあり、適宜追加してください。パラメータの値の範囲や動作の詳細は「声質パラメータ」の章を参照ください。
関数 AquesTalkDa_Synthe の最初の引数は、viewDidLoad()内で生成した AquesTalk のインスタンスです。
2 番目の引数は、声質パラメータの構造体のアドレスをしています。この関数は、非同期なので、音声出力を待たずに関数から抜けます。音声記号列が正しくないなど、エラーが生じた場合は、戻り値に 0 以外の値が返ります（16 行目）。

123
45-(IBAction)play:(id)sender{//終了通知イベントの作成 name 部分は NSNotificationCenter に設定した値に合わせる
NSNotification *notification = [NSNotification
notificationWithName:@"AquesTalkDaDoneNotify" object:self userInfo:nil];678910111213141516171819202122232425// テキストボックスから文字列取得し、文字コードを ShiftJIS に変換char *sjis = (char*)[[textfield text] cStringUsingEncoding:NSShiftJISStringEncoding];// 声質設定
AQTK_VOICE voice =gVoice_F1; //プリセット声種の F1 をベースにする
voice.spd = (int)[spd value]; // スライダーの値から話速をセット
voice.pit = (int)[pit value]; // 高さ
voice.lmd = (int)[lmd value]; // 音程 1// 音声合成 非同期再生
int iret = AquesTalkDa_Play(m_pAqTk, &voice, sjis, notification);if(iret!=0){ // エラーの場合はアラート表示
UIAlertController *alertController = [UIAlertController alertControllerWithTitle:@"Error"message:@"音声記号列の指定が正しくありません" preferredStyle:UIAlertControllerStyleAlert];[alertController addAction:[UIAlertAction actionWithTitle:@"はい"style:UIAlertActionStyleDefault handler:^(UIAlertAction *action) { }]];
[self presentViewController:alertController animated:YES completion:nil];
return;}onPlayLabel.text = @"Playing...";}

ライブラリ使用方法・注意点
AquesTalk10 iOS のライブラリはスタティックライブラリです。アプリのビルド（リンク）時に組み込まれ、アプリ内に libAquesTalk.a を入れる必要ありません。
アプリケーションに組み込む際のポイントは、ヘッダファイル AquesTalk_iPhone.h をプロジェクトに適切にインポート(インクルード)することと、リンク時に libAquesTalk.a を外部ライブライブラリとして追加する２点です。
また、本ライブラリは次のライブラリに依存しています。リンカの「追加するライブラリ」にこれらを追加します。
別途追加するライブラリ

libc++.tbd
AudioToolbox.framework

インターフェースは、C の関数インターフェースになっています。そのため文字列を C の文字列に変換が必要など、Objective-C や Swift から用いる場合は多少注意が必要です。多く利用する場合は、各言語に応じたラップ関数を用意しても良いでしょう。
関数は、同期で音声出力、非同期で音声出力、音声波形データを返す３つのタイプがあります。このうちAquesTalk_Synthe()関数で返された音声データは、使用後に AquesTalk_FreeWav()で解放してください。
アプリ側で free() などを使用して解放すると、ハングの可能性があります。

関 数 API

デバイスに音声出力する（同期タイプ）
AquesTalkDa_PlaySync

AquesTalk_iPhone.h

説明

同期タイプの音声合成。デバイスに音声出力する。発声が終了するまで戻らない。

構文

int AquesTalkDa_PlaySync(const AQTK_VOICE *pParam, const char *koe,)

引数
pParam

声質パラメータ(構造体 AQTK_VOICE のアドレス)を指定

koe

音声記号列（SJIS NULL 終端）を指定

戻り値

0:正常終了 それ以外：エラーコード参照

AquesTalkDa_PlaySync_Utf8

AquesTalk_iPhone.h

説明

同期タイプの音声合成。デバイスに音声出力する。発声が終了するまで戻らない。

構文

int AquesTalkDa_PlaySync_Utf8(const AQTK_VOICE *pParam, const char *koe,)

引数
pParam

声質パラメータ(構造体 AQTK_VOICE のアドレス)を指定

koe

音声記号列（UTF-8）を指定

戻り値

0:正常終了 それ以外：エラーコード参照

デバイスに音声出力する（非同期タイプ）
AquesTalkDa_Create

AquesTalk_iPhone.h

説明AquesTalk のインスタンスを生成して返す。非同期タイプの音声合成をおこなうときに使用する。

構文

H_AQTKDA AquesTalkDa_Play()

引数なし

戻り値

AquesTalk のインスタンスのハンドルを返す

AquesTalkDa_Release
説明

AquesTalk のインスタンスを解放

構文

void AquesTalkDa_Play(H_AQTKDA hMe)

AquesTalk_iPhone.h

引数

ｈMe

音声合成エンジンのハンドル AquesTalkDa_Create()で生成したもの

戻り値なし

AquesTalkDa_Play

AquesTalk_iPhone.h

説明

非同期タイプの音声合成。デバイスに音声出力する。音声波形生成後にすぐに戻り、再生終了後にnotification に指定したイベントが通知される。

構文

int AquesTalkDa_Play(H_AQTKDA hMe, const AQTK_VOICE *pParam, const char *koe,,
NSNotification* notification)

引数

ｈMe

音声合成エンジンのハンドル AquesTalkDa_Create()で生成したもの

pParam

声質パラメータ(構造体 AQTK_VOICE のアドレス)を指定

koe

音声記号列（SJIS NULL 終端）を指定

notification

再生終了イベントの指定。イベント通知不要のときは NULL を指定

戻り値

0:正常終了 それ以外：エラーコード参照

AquesTalkDa_Play_Utf8

AquesTalk_iPhone.h

説明

非同期タイプの音声合成。デバイスに音声出力する。音声波形生成後にすぐに戻り、再生終了後にnotification に指定したイベントが通知される。

構文

int AquesTalkDa_Play_Utf8(H_AQTKDA hMe, const AQTK_VOICE *pParam, const char *koe,,
NSNotification* notification)

引数

ｈMe

音声合成エンジンのハンドル AquesTalkDa_Create()で生成したもの

pParam

声質パラメータ(構造体 AQTK_VOICE のアドレス)を指定

koe

音声記号列（UTF8 NULL 終端）を指定

notification

再生終了イベントの指定。イベント通知不要のときは NULL を指定

戻り値0:正常終了 それ以外：エラーコード参照

AquesTalkDa_Stop
説明

再生の中止

構文

void AquesTalkDa_Stop(H_AQTKDA hMe)

AquesTalk_iPhone.h

引数

ｈMe

音声合成エンジンのハンドル AquesTalkDa_Create()で生成したもの

戻り値なし

AquesTalkDa_IsPlay
説明

再生中か否かを返す

構文

int AquesTalkDa_IsPlay(H_AQTKDA hMe)

AquesTalk_iPhone.h

引数

ｈMe

音声合成エンジンのハンドル AquesTalkDa_Create()で生成したもの

戻り値

1:再生中 0:再生中でない

音声波形データを返すタイプ
AquesTalk_Synthe

AquesTalk_iPhone.h

説明

かな表記音声記号列(SJIS)から音声波形を生成します構文

unsigned char * AquesTalk_Synthe(const AQTK_VOICE *pParam, const char *koe, int *size)

引数
pParam

声質パラメータ(構造体 AQTK_VOICE のアドレス)を指定

koe

音声記号列（SJIS NULL 終端）を指定

size

生成した音声データのサイズが返る[byte]（エラーの場合はエラーコードが返る）

戻り値

WAV フォーマットの音声データを返す。
ヒープ領域を関数内部で確保するので、解放は AquesTalk_FreeWave()で行う。
エラー時は、NULL を返す。このとき size にエラーコードが設定される。

AquesTalk_Synthe_Utf8

AquesTalk_iPhone.h

説明

かな表記音声記号列(UTF-8)から音声波形を生成します構文

unsigned char * AquesTalk_Synthe_Utf8(const AQTK_VOICE *pParam, const char *koe, int*size)

引数
pParam

声質パラメータ(構造体 AQTK_VOICE のアドレス)を指定

koe

音声記号列（UTF-8 NULL 終端）を指定

size

生成した音声データのサイズが返る[byte]（エラーの場合はエラーコードが返る）

戻り値

WAV フォーマットの音声データを返す。
ヒープ領域を関数内部で確保するので、解放は AquesTalk_FreeWave()で行う。
エラー時は、NULL を返す。このとき size にエラーコードが設定される。

AquesTalk_FreeWave
説明

音声データの領域を開放

構文

void AquesTalk_FreeWave(unsigned char *wav)

AquesTalk_iPhone.h

引数wav

WAV フォーマットのデータ（AquesTalk_Synthe()等で生成した音声データ）

戻り値なし

ライセンスキー関連

AquesTalk_SetDevKey

AquesTalk_iPhone.h

説明

開発ライセンスキーを設定。音声波形を生成する前に一度呼び出すことで、以降、製品版とし動作し、評価版の制限がなくなる。

構文

int AquesTalk_SetDevKey(const char *key)引数key開発ライセンスキー文字列(半角英数)

戻り値ライセンスキーが正しければ 0、正しくなければ 1 が返る。
不正なキーでも 0 を返す場合がある。このとき制限は解除されない。

AquesTalk_SetUsrKey

AquesTalk_iPhone.h

説明

使用ライセンスキーを設定。音声波形を生成する前に一度呼び出すことで、以降、合成音声データに含まれる透かしが使用ライセンス無しから取得済みに変化する。

構文

int AquesTalk_SetUsrKey(const char *key)

引数key

使用ライセンスキー、または頒布ライセンスキーの文字列(半角英数)

戻り値

ライセンスキーが正しければ 0、正しくなければ 1 が返る。
不正なキーでも、まれに 0 を返す場合がある。このときはライセンス無しのままである。

声質パラメータ
AquesTalk10 は声質パラメータの値を変更することで、様々な声種で合成できます。声質パラメータの種類と効果を以下に示します。
変数名範囲

デフォルト

説明

bas

0-2

-

声色のベースとなる基本素片 F1E,F2E,M1E のいずれかを指定

spd50 - 300

100

話速。値が大きいほど発話速度が速い。

vol0 - 300

100

音量。値が大きいほど音量が大きくなる。１００以下を指定の場合は、比例して音量が変化する。１００以上を指定した場合は、コンプレッサーが機能する。

pit

20 - 200-

声の高さがパラメータに比例する。デフォルトは基本素片毎に異なる。

acc

0 - 200-

アクセントの強さ。値が大きいほど、アクセントによるピッチの高低が大きくなる。デフォ
ルトは基本素片毎に異なる。

lmd

0 - 200

100

主に声質の高低を表現するが、より複雑な声質の変化がある。

fsc

50 - 200

100

声質の高低を表現。サンプリング周波数を変化するだけなので、これに応じて話速や声の高さも同時に変化する。

AquesTalk_iPhone.h には、声質パラメータの値をセットしたプリセット声種を複数用意しています。簡単に使う場合は、これを AquesTalk_Synthe()などの声質パラメータの引数にすることができます。

音声記号列AquesTalk10 は、かな表記の音声記号列から音声を合成します。漢字を含んだテキスト文字列から音声を合成するときは、別途、言語処理ライブラリ AqKanji2Koe を用いて漢字仮名交じりテキストから音声記号列に変換する必要があります。
音声記号列の詳細は、付属の音声記号列仕様書を参照してください。

エラーコード表関数が返すエラーコードの内容は、次の通りです。
値

内容

100

その他のエラー

101

メモリ不足

103

音声記号列指定エラー(語頭の長音、促音の連続など)

104

音声記号列に有効な読みがない

105

音声記号列に未定義の読み記号が指定された

106

音声記号列のタグの指定が正しくない

107

タグの長さが制限を越えている（または[>]がみつからない）

108

タグ内の値の指定が正しくない

120

音声記号列が長すぎる

121

１つのフレーズ中の読み記号が多すぎる

122

音声記号列が長い（内部バッファオーバー1）

アプリ開発ガイドライン
アプリケーションの開発(評価での使用を除く)は、以下のガイドラインに従ってください。

ライセンスキー
本ライブラリの動作は、開発ライセンスキーと使用ライセンスキー、頒布ライセンスキーの 3 種類の関連キーに依存します。これらのキーは、各ライセンス購入時に発行されるライセンス証に記載されています。
AquesTalk_SetDevKey()をアプリケーションの起動初期に一度呼び出します。引数には開発ライセンスキーを指定します。これにより製品版として動作し、評価版の制限がなくなります。
AquesTalk_SetUsrKey()をアプリケーションの起動初期に一度呼び出します。AquesTalk_SetDevKey()との呼び出し順序は任意です。引数には、使用ライセンスキー、または頒布ライセンスキーを指定します。
この指定により、合成音声データに含まれる透かしが、使用ライセンス無しの状態から取得済みに変化します。この変化による聴感上の違いはありません。
頒布ライセンスによりアプリを配布する場合は、頒布ライセンスキーを指定して呼び出します。
それ以外の場合は、エンドユーザが使用ライセンスキーを指定できるようにします。なお、エンドユーザが個人かつ非営利の利用の場合は使用ライセンスが不要なので、使用ライセンスキーが未指定の場合は、この関数の呼び出しをスキップして構いません。
関数の戻り値のチェックは必ず行い、エラーの場合はエンドユーザにその旨を通知してください。

声質パラメータ
エンドユーザによる声質パラメータの変更機能の有無は任意です。
変更可能にする場合、アプリケーション間での声質パラメータの値を共有するために、声質パラメータの値を写像しないでください。
例えば、話速のパラメータの範囲は 50 から 300 ですが、これを 0 から 100 の範囲にマッピングしてエンドユーザに提示しないでください。
エンドユーザに提示する各パラメータの名称には、AquesTalk_iPhone.h に記載の漢字名称(話速など)や、3 文字の構造体変数名(spd など)を用いるのが望ましいです。

文書履歴

日付版

2017/10/20

1.0

変更箇所

更新内容

更新者

新規作成

N.Y