━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MikoVoice API ( Application Programming Interface ) 仕様
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MikoVoice の API は、次の関数を提供しています。
・MikoVoiceOutSync 音声記号文字列から音声を合成して発声（同期型）
・MikoVoiceOutAsync 音声記号文字列から音声を合成して発声（非同期型）
・MikoVoiceOutToBuf 音声記号文字列から合成した音声の波形データを渡す
・MikoVoiceOutPause 発声を休止
・MikoVoiceOutRestart 発声を再開
・MikoVoiceOutStop 発声を停止
・MikoVoiceOutGetStat 発声状態を取得
・MikoVoiceOutGetVers MikoVoice の現バージョンを取得
これらの関数に関しては、後程、詳しく説明しますが、その前に、基本事項を説明して
おきます。
MikoVoice 関連のインクルードファイル、ライブラリーファイル、実行型式ファイルに
関しては、「プログラミング」で説明しています。また、ここでは、プログラム例を
示しています。
MikoVoice には、特定の「音声記号」で発声の仕方を指定しますが、この「音声記号」
に関しては、「音声記号の説明」で説明しています。
MikoVoice の API には、「音声記号」の文字列から音声を合成する関数がありますが、
この文字列の文字コードは、ユニコードの UTF16LE にする必要があります。Shift-JIS
ではないので、ご注意ください。
MikoVoice は、同時に８音声まで重ねて出力できるようになっています。その各音声の
出力先を､「音声出力ポート」と呼んでいます。各「音声出力ポート」には、0 〜 7 の
識別番号が振られています。
１つの音声出力ポートには、８トラックまで指定できるので、原理的には最大６４音声
まで同時に発声できます。音声出力ポートでの重ね合せは、主にＯＳが担っています。
一方、トラックでの重ね合せは、MikoVoice 自身が処理しています。
本ライブラリーは、マルチスレッドで使用しても安全なように設計されています。
以下、本ライブラリー関数の詳細を説明します。ここでは、Windows プログラミング用
に定義されているデータ型（ LPCWSTR, ULONG 等 ）も使用しています。
────────────────────────────────────────
MikoVoiceOutSync 関数
機能： 音声記号文字列から音声を合成して発声する（同期型）
構文： LONG MikoVoiceOutSync( LPCWSTR text );
引数： text
音声記号文字列（ UTF16LE, ０終端 ）へのポインタ
返値： 本音声を出力したポートの番号（正常時） or -1（異常時）
説明： 本関数は、発声の完了を待って戻って来る。発声の完了と同期する。
用例： MikoVoiceOutSync( L"こ[んにちわ]" );
────────────────────────────────────────
MikoVoiceOutAsync 関数
機能： 音声記号文字列から音声を合成して発声する（非同期型）
構文： LONG MikoVoiceOutAsync( LPCWSTR text,
HWND hWnd, UINT Msg, LPARAM lParam );
引数： text
音声記号文字列（ UTF16LE, ０終端 ）へのポインタ
hWnd
発声完了メッセージの送信先ウィンドウのハンドル。
この値を NULL にすれば、当メッセージは送信されない。
Msg
発声完了メッセージの識別値。
この値は、プライベート範囲内で、ユーザーが任意に決めて良い。
lParam
発声完了メッセージの第２パラメータの値。
この値は、ユーザーが任意に決めて良い。
返値： 本音声が出力されるポートの番号（正常時） or -1（異常時）
説明： 本関数は、発声の手続きをした後すぐに戻って来る。発声の完了を待たない。
発声の完了と同期しない。そのため、発声中でも、他の処理を実行できる。
発声完了は、ウィンドウへのメッセージで通知される。そのウィンドウは、
引数の hWnd で指定する。このメッセージの識別値と第２パラメータは、
それぞれ、引数の Msg と lParam の値になり、第１パラメータ wParam は、
本関数の返値と同じになる。
本関数で発声してそれが終わるまでに、再度、本関数で発声すると、最初の
音声に次の音声が重なる。この重なりは、最大８音声まで可能。
本関数の返値は、音声が出力されたポート番号を示す。
用例： MikoVoiceOutAsync(
L"は[じめま]して、よ[ろしく]、お[ねがいしま]す。",
hWnd, WM_APP + 0x801, 1234 );
────────────────────────────────────────
MikoVoiceOutToBuf 関数
機能： 音声記号文字列から合成した音声の波形データを指定関数に渡す
構文： LONG MikoVoiceOutToBuf( LPCWSTR text, WAVRECFNC lpWavRecFnc );
引数： text
音声記号文字列（ UTF16LE, ０終端 ）へのポインタ
lpWavRecFnc
音声合成された波形データを受け取る関数へのポインタ
返値： 音声合成された波形データの総バイト数（正常時） or -1（異常時）
説明： 本関数は、音声合成された波形データを適当なサイズごとに分けて、
lpWavRecFnc のポイント先の関数に渡していく。
引数 lpWavRecFnc の型 WAVRECFNC は、次の定義になっている。
typedef BOOL (CALLBACK *WAVRECFNC)( LPCVOID, LONG );
このポイント先の関数は、下記の「 WavRecFnc 関数（形式）」参照。
補説： 合成される波形データのサイズは、音声記号文字列に依存するが、場合に
よっては膨大になるため、適当なサイズに分割して渡す形態になっている。
用例： MVoiceTest2.c 参照。ここでは、音声合成された波形データを、Windows
標準の wav 形式でファイルに書き込む例を示す。
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
WavRecFnc 関数（形式）
説明： 本関数は、MikoVoiceOutToBuf 関数から呼ばれるコールバック関数（形式）で、
音声合成された波形データを受け取る。
構文： BOOL CALLBACK WavRecFnc( LPCVOID bp, LONG bn );
引数： bp
波形データのアドレス
bn
波形データのバイト数
返値： TRUE（正常受取時）or FALSE（異常時）
補説： この返値が FALSE の時、MikoVoiceOutToBuf 関数は、以降の処理を中断し、
異常終了を示す -1 を返す。
注意： この関数は、ユーザーが定義する。MikoVoice API が提供する関数ではない。
用例： MVoiceTest2.c 参照。ここでは、受け取った波形データをファイルに書き込む
例を示す。
────────────────────────────────────────
MikoVoiceOutPause 関数
機能： 指定された音声出力ポート（複数可）の発声を一時休止する
構文： ULONG MikoVoiceOutPause( ULONG PortBits );
引数： PortBits
発声を休止する音声出力ポートを示すビット値。
このビット 0 〜 7 が、それぞれ、音声出力ポート 0 〜 7 に対応し、
そのビット値が 1 の時、そのポートが休止対象になる。
この引数のビット 0 〜 7 以外のビットは、無視される。
返値： 指定されたポートのうち休止状態に変わったポートを示すビット。
ビットとポートの対応は、引数の場合と同じ。
補説： 停止中や休止中のポートに対しては、特に何もしない。
休止中の音声出力ポートは、MikoVoiceOutRestart 関数で再開可能。
用例： MikoVoiceOutPause( 1 ); // 音声出力ポート 0 の発声を休止する
MikoVoiceOutPause( 0x03 ); // 音声出力ポート 0 と 1 の発声を休止する
MikoVoiceOutPause( -1 ); // 全音声出力ポートの発声を休止する
────────────────────────────────────────
MikoVoiceOutRestart 関数
機能： 指定された音声出力ポート（複数可）の発声を再開する
構文： ULONG MikoVoiceOutRestart( ULONG PortBits );
引数： PortBits
発声を再開する音声出力ポートを示すビット値。
このビット 0 〜 7 が、それぞれ、音声出力ポート 0 〜 7 に対応し、
そのビット値が 1 の時、そのポートが再開対象になる。
この引数のビット 0 〜 7 以外のビットは、無視される。
返値： 指定されたポートのうち再開したポートを示すビット。
ビットとポートの対応は、引数の場合と同じ。
補説： 再開は、休止したところの続きからになる。
停止中や発声中のポートに対しては、特に何もしない。
用例： MikoVoiceOutRestart( 1 ); // 音声出力ポート 0 の発声を再開する
MikoVoiceOutRestart( 0x05 ); // 音声出力ポート 0 と 2 の発声を再開する
MikoVoiceOutRestart( -1 ); // 全音声出力ポートの発声を再開する
────────────────────────────────────────
MikoVoiceOutStop 関数
機能： 指定された音声出力ポート（複数可）の発声を停止する
構文： ULONG MikoVoiceOutStop( ULONG PortBits );
引数： PortBits
発声を停止する音声出力ポートを示すビット値。
このビット 0 〜 7 が、それぞれ、音声出力ポート 0 〜 7 に対応し、
そのビット値が 1 の時、そのポートが停止対象になる。
この引数のビット 0 〜 7 以外のビットは、無視される。
返値： 指定されたポートのうち停止状態のポートを示すビット。
ビットとポートの対応は、引数の場合と同じ。
補説： 発声中や休止中のポートを一旦停止させると再開はできない。
既に停止中のポートが対象の場合、特に何もしないが、返値のビットには
反映される。
用例： MikoVoiceOutStop( 1 ); // 音声出力ポート 0 の発声を停止する
MikoVoiceOutStop( 0x06 ); // 音声出力ポート 1 と 2 の発声を停止する
MikoVoiceOutStop( -1 ); // 全音声出力ポートの発声を停止する
────────────────────────────────────────
MikoVoiceOutGetStat 関数
機能： 指定された音声出力ポートの発声状態を取得する
構文： LONG MikoVoiceOutGetStat( LONG PortId );
引数： PortId
発声状態を取得する音声出力ポートの番号（ 有効範囲： 0 〜 7 ）
返値： 発声状態を示す値。この値は、MikoVoice.h で、次のように定義されている。
#define MVO_STAT_STOPPED 0 // 停止中
#define MVO_STAT_OPENING 1 // 準備中
#define MVO_STAT_PLAYING 2 // 発声中
#define MVO_STAT_PAUSING 3 // 休止中
#define MVO_STAT_ERROR (-1) // エラー
用例： MikoVoiceOutGetStat( 0 ); // 音声出力ポート 0 の発声状態を取得
────────────────────────────────────────
MikoVoiceOutGetVers 関数
機能： MikoVoice の現在のバージョンを取得する
構文： LONG MikoVoiceOutGetVers();
引数： 無し
返値： （主バージョン）× 100 ＋（副バージョン）
補説： 例えば、主バージョンが 1 で、副バージョンが 20 の場合、返値は、120 に
なる。
────────────────────────────────────────