CriAtomPlayerについて

CriAtomPlayerは、音声データを再生するためのモジュールです。
CriAtomPlayerモジュールには、任意の音声データを再生する機能や、再生中の音声のパラメーター（パンやピッチ）をコントロールする機能等、音声再生に関する基本的な機能が含まれています。

CriAtomPlayerモジュールには、"Atomプレーヤ"という音声再生用のオブジェクトが用意されています。
Atomプレーヤは、データの入力から音声の出力までをケアするプレーヤオブジェクトです。
Atomプレーヤを使用することで、ユーザは複雑な操作なしに音声データを再生することが可能となります。

Atomプレーヤを使用して音声データを再生する手順は、以下のとおりです。

1. Atomプレーヤを作成する。
2. Atomプレーヤに音声データをセットする。
3. 音声の再生を開始する。
   

Atomプレーヤの作成

音声を再生するためには、まず初めにAtomプレーヤを作成する必要があります。
Atomプレーヤの作成は、再生する音声コーデックの種別に応じて、いくつかの関数が用意されています。

例えば、ADXデータを再生したい場合には criAtomPlayer_CreateAdxPlayer 関数を、HCAデータを再生したい場合には criAtomPlayer_CreateHcaPlayer 関数を使用する必要があります。

Atomプレーヤを作成する際には、ライブラリ初期化時同様、プレーヤの仕様を指定するコンフィグ構造体と、ワークメモリを指定する必要があります。

［備考］
ライブラリの初期化同様、Atomプレーヤ作成時もコンフィグ構造体は省略可能です。
（省略時はデフォルト設定でAtomプレーヤが作成されます。）

プレーヤの作成に成功すると、関数の戻り値として、プレーヤを制御するためのハンドル（ CriAtomPlayerHn ）が返されます。
データのセットや、再生の開始等、以降の操作は全てこのハンドルに対して行います。

［備考］
どの関数を使用した場合でも、Atomプレーヤ作成関数は必ず CriAtomPlayerHn 型のAtomプレーヤハンドルを返します。
これは、Atomプレーヤがコーデックに依存しない再生制御のためのインターフェースを提供する"抽象化されたプレーヤオブジェクト"であるためです。
（プレーヤごとに再生できる音声コーデックの種類は異なりますが、プレーヤの制御についてはAtomプレーヤ用のAPIが共通で利用可能です。）

音声データのセット

音声データを再生するには、まず初めに、"どの音声データを再生するか"をプレーヤに対して指示する必要があります。
Atomプレーヤは音声データの入力形式に対応した再生方法をサポートしています。
Atomプレーヤに対して音声データのセットする場合は、再生方式に対応したデータ設定関数を使う必要があります。

再生方式とデータ設定関数

再生方式	説明	データ設定関数
AWB再生	AWBファイルにパッキングされた音声データの再生	criAtomPlayer_SetWaveId
オンメモリ再生	メモリ上にロードされた音声データの再生	criAtomPlayer_SetData
ファイル再生	音声ファイルの再生	criAtomPlayer_SetFile

例えば、カレントディレクトリにあるsample.adxを再生したい場合、データをセットする方法は以下のようになります。

/* sample.adxをAtomプレーヤにセットする */
criAtomPlayer_SetFile(player, NULL, "sample.adx");

再生の開始

音声データセット後、 criAtomPlayer_Start 関数を実行することで、セットした音声データが再生されます。

尚、オンメモリ再生時は、 criAtomPlayer_Start 関数実行直後（※）、次の criAtom_ExecuteMain 関数内で発音が開始されますが、ファイル再生時やAWB再生時には、デバイスから一旦データを読み込んでから再生を開始するため、発音開始までに数Vの遅延を伴います。

※厳密には、 criAtomPlayer_Start 関数実行後、次のサーバ処理が動作するタイミングで発音が開始されます。

ストリーム再生時に発音のタイミングを制御する方法

ストリーム再生時に厳密の再生タイミングを制御したい場合、以下の操作を行う必要があります。

1. criAtomPlayer_Pause 関数を使用し、Atomプレーヤをポーズ変更にする。
2. criAtomPlayer_Start 関数で再生を開始する。
3. Atomプレーヤのステータスが CRIATOMPLAYER_STATUS_PLAYING になるのを待つ。
4. criAtomPlayer_Pause 関数でAtomプレーヤのポーズを解除する。
   
   

以上の手順を踏むことで、ポーズ解除と同時に発音が開始されます。

再生状態の監視方法

以上の操作で音声データの再生は可能ですが、シチュエーションによっては、発音は開始されたのか？再生は完了したのか？といった、"再生中の音声の状態"をチェックしたい場面もあります。
こういったケースに備え、Atomプレーヤには"ステータスポーリング"の仕組みが用意されています。

Atomプレーヤに対し、 criAtomPlayer_GetStatus 関数を実行すると、Atomプレーヤは"ステータス"と呼ばれるプレーヤの状態を示す値を返します。
ステータスには以下のような値が定義されており、この値からプレーヤの状態を知ることが可能です。

ステータスとプレーヤの状態の関係

ステータス	プレーヤの状態
CRIATOMPLAYER_STATUS_STOP	プレーヤは停止中です。 音声データは再生されていません。
CRIATOMPLAYER_STATUS_PREP	プレーヤは再生準備中です。 音声データを読み込み中ですが、発音は開始されていません。
CRIATOMPLAYER_STATUS_PLAYING	プレーヤは音声再生中です。 音声データを読み込みながら、発音を行っています。
CRIATOMPLAYER_STATUS_PLAYEND	プレーヤは再生を完了しました。 セットされた音声データを終端まで再生し終えました。
CRIATOMPLAYER_STATUS_ERROR	プレーヤは音声の再生に失敗しました。 リードエラー等の問題が発生しました。

音声再生に伴い、Atomプレーヤのステータスは通常以下の順に遷移します。

1. Atomプレーヤを作成した時点では、プレーヤのステータスはSTOP状態です。
2. criAtomPlayer_Start 関数を実行することで、プレーヤのステータスはPREP状態に遷移します。
3. 再生に必要な音声データが読み込まれた時点で、プレーヤのステータスがPLAYING状態に遷移し、発音が開始されます。
4. セットされたデータを全て再生し終えた時点で、発音が終了し、プレーヤのステータスはPLAYEND状態に遷移します。

［備考］
再生中に何らかのエラー（データ読み込みの失敗等）が発生した場合、プレーヤのステータスはERROR状態に遷移します。
また、 criAtomPlayer_Stop 関数で再生を停止させた場合には、プレーヤのステータスはSTOP状態に遷移します。
なお、Atomプレーヤのステータスは、AtomExプレーヤと同じようにステータス遷移が行われます。

プレーヤの破棄

不要になったAtomプレーヤについては、 criAtomPlayer_Destroy 関数で破棄することが可能です。
Atomプレーヤを破棄することで、プレーヤ作成時にセットしたワークメモリを他の用途に転用したり、メモリを解放することが可能になります。

［備考］
1つのAtomプレーヤは複数の音声を順次再生する場合には、発音開始毎に破棄する必要はありません。
停止中のAtomプレーヤ（STOP状態かPLAYEND状態、ERROR状態のプレーヤ）に対しては、::criAtomPlayer_SetData 関数等で他の音声データをセットし、 criAtomPlayer_Start 関数で再生させることが可能です。
（データを再セットせずに criAtomPlayer_Start 関数を実行した場合、前回再生した音声が再度頭から再生されます。）

［注意］
再生中のAtomプレーヤ（PREP状態またはPLAYING状態のプレーヤ）に対しては、 criAtomPlayer_Set ～関数によるデータのセットや、 criAtomPlayer_Start 関数によるリスタート処理はできません。
（エラーになります。）

現在の再生を中止し、他の音声データを再度頭から再生したい場合には、一旦 criAtomPlayer_Stop 関数で再生を停止させ、ステータスがSTOP状態になってから次の再生操作を行ってください。

その他の機能について

Atomプレーヤには、音声を単純に再生する以外に、再生中の音声のボリュームを変更したり、複数の音声データを連結して再生するといった機能があります。

Next:CriAtomDbasについて