CriAtomPlayer

CriAtomPlayer is the module for playing back audio data.
The CriAtomPlayer module has basic functions related to audio playback, such as the function for playing back any audio data and the function for controlling the parameters (panning and pitch) of audio data being played back.

The CriAtomPlayer module provides an object called "Atom Player" for audio playback.
An Atom Player is a player object that supports various operations ranging from data input to audio output.
By using an Atom 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:

1. Create an Atom Player.
2. Set audio data to the Atom Player.
3. Start playing back the audio data.
   

Creating an Atom Player

To play back audio data, first, it is necessary to create an Atom Player.
Several functions for creating an Atom Player are available according to the type of the codec of the audio data to be played back.

For example, it is necessary to use the criAtomPlayer_CreateAdxPlayer function to play back an ADX data and the criAtomPlayer_CreateHcaPlayer function to play back a HCA data

When an Atom 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 as in the case of initializing the library.
For details on creating a player, see Tutorials .

[Remarks]
As in the case of initializing the library, when an Atom Player is created, the configuration structure can be omitted.
(When it is omitted, the Atom Player is created in the default settings.)

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

[Remarks]
Regardless of which function is used, Atom Player creation functions always return a CriAtomPlayerHn type of Atom Player handle.
This is because an Atom Player is an "abstracted player object" that provides an interface for controlling playback independent of the codec of audio data.
(Although audio codecs that can be played back vary depending on each player, APIs for controlling the player can be used in common between Atom Players.)

Setting Audio Data

To play back audio data, first, it is necessary to tell the player "which audio data must be played back".
An Atom Player supports playback methods suitable for input formats of audio data.
To set audio data for an Atom 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
AWB Playback	Plays back audio data packed in an AWB file.	criAtomPlayer_SetWaveId
On-Memory Playback	Plays back audio data loaded on the memory.	criAtomPlayer_SetData
File Playback	Plays back audio files.	criAtomPlayer_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 */
criAtomPlayer_SetFile(player, NULL, "sample.adx");

Starting Playback

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

Note that in an on-memory playback, immediately after the criAtomPlayer_Start function is executed (*), audio playback starts in the subsequent criAtom_ExecuteMain function , but in a file playback or an AWB playback, the playback starts after data are read from a device, and therefore, a delay of some V occurs before the playback starts.

Strictly speaking, the audio playback starts when subsequent server processing is performed after the criAtomPlayer_Start function is executed.

Controlling Audio Playback Timing in Streaming Playback

To precisely control playback timing in streaming playback, the following procedure must be performed.

1. Use the criAtomPlayer_Pause function to pause the Atom Player.
2. Use the criAtomPlayer_Start function to start playback.
3. Wait until the status of the Atom Player changes to CRIATOMPLAYER_STATUS_PLAYING .
4. Use the criAtomPlayer_Pause function to cancel the pause of the Atom Player.
   
   

By performing the above procedure, audio playback starts when the pause is canceled.

Monitoring Playback Status

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 Atom Player provides a "status polling" mechanism.

When the criAtomPlayer_GetStatus function is executed for an Atom Player, the Atom 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
CRIATOMPLAYER_STATUS_STOP	The player has been stopped. No audio data is being played back.
CRIATOMPLAYER_STATUS_PREP	The player is preparing for playback. An audio data is being read, but the playback of voices has not been started.
CRIATOMPLAYER_STATUS_PLAYING	The player is playing back audio data. While reading audio data, the player is playing back the data.
CRIATOMPLAYER_STATUS_PLAYEND	The player has completed playback. The player has played back to the end of the audio data that was set.
CRIATOMPLAYER_STATUS_ERROR	The player has failed to play back audio data. A problem such as a read error has occurred.

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

1. At the time when an Atom Player is created, the status of the player is STOP.
2. By executing the criAtomPlayer_Start function , the status of the player changes to PREP.
3. When an audio data needed for playback is read, the status of the player changes to PLAYING and the playback starts.
4. 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 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.
Note that the status of an Atom Player changes in the same way as an AtomEx Player.

Destroying a Player

An unnecessary Atom Player can be destroyed by using the criAtomPlayer_Destroy function.
By destroying an Atom 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 Atom Player every time when the next playback starts.
For an Atom 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 criAtomPlayer_SetData function and so on, and the data can be played back by using the criAtomPlayer_Start function .
(If the criAtomPlayer_Start function is executed without setting another data, the audio data played back last time is played back again from the beginning.)

[Note]
For an Atom Player in a playback state (i.e., the player status is PREP or PLAYING), it is not possible to use the ::criAtomPlayer_Set~ functions to set data or the criAtomPlayer_Start function to perform restart processing.
(An error will occur.)

If you want to stop the current playback and play back another audio data from the beginning, first, use the criAtomPlayer_Stop function to stop the playback, and then after the status changes to STOP, perform subsequent playback operations.

Other Functions

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.

Next:About CriAtomDbas