- CriAtomExPlayerは、音声データやキューを再生するためのモジュールです。
音声データの再生／停止や、ボリューム変更等、発音制御のためのインターフェースを提供します。
- CriAtomExPlayerモジュールには、"AtomExプレーヤ"という再生制御用のオブジェクトが用意されています。
AtomExプレーヤは、データの入力から音声の出力までをケアするプレーヤオブジェクトです。
AtomExプレーヤを使用することで、ユーザは複雑な操作なしに音声データを再生することが可能となります。
- Atomプレーヤを使用して音声データを再生する手順は、以下のとおりです。
- AtomExプレーヤを作成する。
- AtomExプレーヤに音声データをセットする。
- 音声の再生を開始する。
AtomExプレーヤの作成
- 音声を再生するためには、まず初めにAtomExプレーヤを作成する必要があります。
AtomExプレーヤの作成には、 criAtomExPlayer_Create 関数を使用します。
AtomExプレーヤ作成時には、プレーヤの仕様を指定するコンフィグ構造体と、ワークメモリを指定する必要があります。
- ［備考］
AtomExプレーヤ作成時のコンフィグ構造体は省略可能です。
（省略時はデフォルト設定でAtomExプレーヤが作成されます。）
- プレーヤの作成に成功すると、関数の戻り値として、プレーヤを制御するためのハンドル（ CriAtomExPlayerHn ）が返されます。
データのセットや、再生の開始等、以降の操作は全てこのハンドルに対して行います。
音声データのセット
- 音声データを再生するには、まず、"どの音声データを再生するか"をプレーヤに対して指示する必要があります。
AtomExプレーヤは音声データの入力形式に対応した再生方法をサポートしています。
AtomExプレーヤに対して音声データのセットする場合は、再生方式に対応したデータ設定関数を使う必要があります。
| 再生方式 | 説明 | データ設定関数 |
|---|---|---|
| キュー再生 | ACBファイル内のキューの再生(ID指定) | criAtomExPlayer_SetCueId |
| キュー再生 | ACBファイル内のキューの再生(キュー名指定) | criAtomExPlayer_SetCueName |
再生の開始
- 音声データセット後、::criAtomExPlayer_Start 関数を実行することで、セットした音声データが再生されます。
再生状態の監視方法
- 以上の操作で音声データの再生は可能ですが、シチュエーションによっては、発音は開始されたのか？再生は完了したのか？といった、"再生中の音声の状態"をチェックしたい場面もあります。
こういったケースに備え、AtomExプレーヤには"ステータスポーリング"の仕組みが用意されています。
- AtomExプレーヤに対し、::criAtomExPlayer_GetStatus 関数を実行すると、AtomExプレーヤは"ステータス"と呼ばれるプレーヤの状態を示す値を返します。
ステータスには以下のような値が定義されており、この値からプレーヤの状態を知ることが可能です。
| ステータス | プレーヤの状態 |
|---|---|
| CRIATOMEXPLAYER_STATUS_STOP | プレーヤは停止中です。 音声データは再生されていません。 |
| CRIATOMEXPLAYER_STATUS_PREP | プレーヤは再生準備中です。 音声データを読み込み中ですが、発音は開始されていません。 |
| CRIATOMEXPLAYER_STATUS_PLAYING | プレーヤは音声再生中です。 音声データを読み込みながら、発音を行っています。 |
| CRIATOMEXPLAYER_STATUS_PLAYEND | プレーヤは再生を完了しました。 セットされた音声データを終端まで再生し終えました。 |
| CRIATOMEXPLAYER_STATUS_ERROR | プレーヤは音声の再生に失敗しました。 リードエラー等の問題が発生しました。 |
- 音声再生に伴い、AtomExプレーヤのステータスは通常以下の順に遷移します。
- AtomExプレーヤを作成した時点では、プレーヤのステータスはSTOP状態です。
- criAtomExPlayer_Start 関数を実行することで、プレーヤのステータスはPREP状態に遷移します。
- 再生に必要な音声データが読み込まれた時点で、プレーヤのステータスがPLAYING状態に遷移し、発音が開始されます。
- セットされたデータを全て再生し終えた時点で、発音が終了し、プレーヤのステータスはPLAYEND状態に遷移します。
- ステータスの遷移を図に示すと、以下のようになります。
- ［備考］
再生中に再度 criAtomExPlayer_Start 関数を実行すると、プレーヤのステータスはPREP状態に戻ります。
再生中に何らかのエラー（データ読み込みの失敗等）が発生した場合、プレーヤのステータスはERROR状態に遷移します。
また、::criAtomExPlayer_Stop 関数で再生を停止させた場合には、プレーヤのステータスはSTOP状態に遷移します。
PLAYEND状態やERROR状態のプレーヤに対して criAtomExPlayer_Start 関数を実行した場合も、ステータスはPREP状態に遷移します。
プレーヤの破棄
- 不要になったAtomExプレーヤについては、::criAtomExPlayer_Destroy 関数で破棄することが可能です。
AtomExプレーヤを破棄することで、プレーヤ作成時にセットしたワークメモリを他の用途に転用したり、メモリを解放することが可能になります。
- ［備考］
1つのAtomExプレーヤは複数の音声を順次再生する場合には、発音開始毎に破棄する必要はありません。
停止中のAtomExプレーヤ（STOP状態かPLAYEND状態、ERROR状態のプレーヤ）に対しては、 criAtomExPlayer_SetCueId 関数等で他の音声データをセットし、 criAtomExPlayer_Start 関数で再生させることが可能です。
（データを再セットせずに criAtomExPlayer_Start 関数を実行した場合、前回再生した音声が再度頭から再生されます。）
その他の機能について
- AtomExプレーヤには、音声を単純に再生する以外に、再生中の音声のボリュームを変更したり、複数の音声データを連結して再生するといった機能があります。
