: CriAtomExPlayer is the module for playing back audio data or Cues.
This module provides the interface for voice control, such as playing back/stopping audio data and changing playback volume.

: The CriAtomExPlayer module provides an object called "AtomEx Player" for controlling playback.
An AtomEx Player is a player object that supports various operations ranging from data input to audio output.
By using an AtomEx Player, users can play back audio data without any complicated operations.

The procedure for playing back audio data by using an Atom Player is as follows:

Creating an AtomEx Player

: To play back audio data, first, it is necessary to create an AtomEx Player.
To create an AtomEx Player, use the criAtomExPlayer_Create function.
When an AtomEx Player is created, it is necessary to set a configuration structure that specifies the specifications of the player and also it is necessary to specify a Working Memory. For details on creating a player, see Tutorials .

: [Remarks]
When an AtomEx Player is created, the configuration structure can be omitted.
(When it is omitted, the AtomEx Player is created in the default settings.)

: When the player is created successfully, a handle ( CriAtomExPlayerHn ) for controlling the player is returned as a return value.
Subsequent operations, such as setting data and starting playback, are performed on this handle.

Setting Audio Data

: To play back audio data, first, it is necessary to tell the player "which audio data must be played back".
An AtomEx Player supports playback methods suitable for input formats of audio data.
To set audio data for an AtomEx Player, it is necessary to use a data setting function suitable for the playback method.

Playback Methods and Data Setting Functions
Playback Method	Description	Data Setting Function
Cue Payback	Plays back Cues in an ACB file.	criAtomExPlayer_SetCueName criAtomExPlayer_SetCueId
AWB Playback	Plays back audio data packed in an AWB file.	criAtomExPlayer_SetWaveId
On-Memory Playback	Plays back audio data loaded on the memory.	criAtomExPlayer_SetData
File Playback	Plays back audio files.	criAtomExPlayer_SetFile

: For example, if you want to play back sample.adx in the current directory, the data can be set as follows.

/* Set sample.adx for an Atom Player */

criAtomExPlayer_SetFile(player, NULL, "sample.adx");

void criAtomExPlayer_SetFile(CriAtomExPlayerHn player, CriFsBinderHn binder, const CriChar8 *path)

Set the sound data to play (specifying a file name)

: After audio data is set, by executing the criAtomExPlayer_Start function, the audio data that has been set is played back.

: By doing the above operations, audio data can be played back. In addition, in some situations, you may want to check "the status of audio data being played back", for example, to see whether the playback of a voice has been started or whether the playback is completed.
To support these cases, each AtomEx Player provides a "status polling" mechanism.

: When the criAtomExPlayer_GetStatus function is executed for an AtomEx Player, the AtomEx Player returns a value called "status" that indicates the status of the player.
The following values are predefined for the status. The status of a player can be known from its value.

**Relationship Between Status Values and Player Statuses**
Status Value	Player Status
CRIATOMEXPLAYER_STATUS_STOP	The player has been stopped. No audio data is being played back.
CRIATOMEXPLAYER_STATUS_PREP	The player is preparing for playback. An audio data is being read, but the playback of voices has not been started.
CRIATOMEXPLAYER_STATUS_PLAYING	The player is playing back audio data. While reading audio data, the player is playing back the data.
CRIATOMEXPLAYER_STATUS_PLAYEND	The player has completed playback. The player has played back to the end of the audio data that was set.
CRIATOMEXPLAYER_STATUS_ERROR	The player has failed to play back audio data. A problem such as a read error has occurred.

When an AtomEx Player plays back audio data, the status of the AtomEx Player changes in the following order:

At the time when an AtomEx Player is created, the status of the player is STOP.
By executing the criAtomExPlayer_Start function , the status of the player changes to PREP.
When an audio data needed for playback is read, the status of the player changes to PLAYING and the playback starts.
When all data that have been set are played back to the end, the playback is complete and the status of the player changes to PLAYEND.

: [Remarks]
If the criAtomExPlayer_Start function is executed again during playback, the status of the player returns to PREP.
If any error (e.g., a data reading failure) occurs during playback, the status of the player changes to ERROR.
Also, if the criAtomPlayer_Stop function is used to stop playback, the status of the player changes to STOP.

: An unnecessary AtomEx Player can be destroyed by using the criAtomExPlayer_Destroy function.
By destroying an AtomEx Player, the Working Memory that is set when the player is created can be used for another purpose or the memory can be released.

: [Remarks]
When multiple audio data are played back sequentially, it is not necessary to destroy an AtomEx Player every time when the next playback starts.
For an AtomEx Player that has been stopped (i.e., the status of the player is STOP, PLAYEND, or ERROR), another audio data can be set by using the criAtomExPlayer_SetData function and so on, and the data can be played back by using the criAtomExPlayer_Start function .
(If the criAtomExPlayer_Start function is executed without setting another data, the audio data played back last time is played back again from the beginning.)

: [Note]
The criAtomExPlayer_SetFile function cannot be executed for an AtomEx Player currently being played back (i.e., a player whose status is PREP or PLAYING).
(A Cue ID, AWB content ID, or on-memory data can be set during playback.)

: In addition to simply playing back audio data, an Atom Player supports other functions, such as changing the volume of audio data being played back and concatenating multiple audio data to play back them.