关于CriAtomPlayer

CriAtomPlayer是用于播放音频数据的模块。
CriAtomPlayer模块包括音频播放的基本功能，例如播放任意音频数据、控制正在播放的音频的参数（Pan和音高）等。

CriAtomPlayer模块提供名为"AtomPlayer"的音频播放对象。
AtomPlayer是负责从数据输入到音频输出的Player对象。
通过使用AtomPlayer，用户不需要执行复杂的操作即可播放音频数据。

使用AtomPlayer播放音频数据的步骤如下。

1. 创建AtomPlayer
2. 为AtomPlayer设置音频数据。
3. 开始播放音频。
   

创建AtomExPlayer

要播放音频，必须先创建AtomPlayer。
根据要播放的音频编解码器的类型，提供几个创建AtomPlayer的函数。

例如，如果要播放ADX数据，则必须使用::criAtomPlayer_CreateAdxPlayer 函数，如果要播放HCA数据，则必须使用::criAtomPlayer_CreateHcaPlayer 函数。

创建AtomPlayer时，与初始化程序库时类似，必须指定用于确定Player规格的配置构件和工作内存。
关于Player的具体创建方法，请参照教程 。

［备注］
与程序库初始化类似，创建AtomPlayer时也可以省略配置构件。
（省略时按照预设设置创建AtomPlayer。）

如果成功创建Player，则返回用于Player的句柄（ CriAtomPlayerHn ）作为函数的返回值。
设置数据和开始播放等后续操作均在此句柄上执行。

［备注］
无论使用哪个函数，AtomPlayer创建函数始终返回::CriAtomPlayerHn 型的AtomPlayer句柄。
这是因为AtomPlayer是提供播放控制接口的"抽象Player对象 "，与编解码器无关。
（每个Player可以播放的音频编解码器类型不同，但Player控制都可以使用AtomPlayer的API。）

设置音频数据

要播放音频数据，首先必须指示Player"播放哪个音频数据"。
AtomPlayer支持与音频数据的输入格式相对应的播放方法。
为AtomPlayer设置音频数据时，必须使用与播放方式相对应的数据设置函数。

播放方式和数据设置函数

播放方式	说明	数据设置函数
AWB播放	播放打包为AWB文件的音频数据	criAtomPlayer_SetWaveId
内存播放	播放加载到内存中的音频数据	criAtomPlayer_SetData
文件播放	播放音频文件	criAtomPlayer_SetFile

例如，如果想要播放当前目录中的sample.adx，请使用如下的数据设置方法。

/* 将sample.adx设置到AtomPlayer中 */
criAtomPlayer_SetFile(player, NULL, "sample.adx");

开始播放

设置音频数据后，通过执行::criAtomExPlayer_Start 函数来播放设置的音频数据。

另外在内存播放时，执行::criAtomPlayer_Start 函数后（※），将在接下来的::criAtom_ExecuteMain 函数中开始发声，但在文件播放时和AWB播放时，要从设备读取数据后再开始播放，因此在发声开始前有数V的延迟。

※严格来说，在执行::criAtomPlayer_Start 函数后，会在启动下一个Server处理时开始发声。

如何在流播放时控制发声时间

如果想要在流播放时严格控制播放时间，必须执行以下操作。

1. 使用::criAtomPlayer_Pause 函数暂停AtomPlayer。
2. 使用::criAtomPlayer_Start 函数开始播放。
3. 等待AtomPlayer的状态变为::CRIATOMPLAYER_STATUS_PLAYING 。
4. 使用::criAtomPlayer_Pause 函数解除AtomPlayer的暂停。
   
   

通过以上步骤，在解除暂停的同时开始发声。

如何监控播放状态

通过以上操作可以播放音频数据，但根据情况，有时可能需要检查"播放中的声音状态"，例如是否开始发声？播放是否已完成？
AtomPlayer提供"状态监视" 机制来应对这些情况。

对AtomPlayer执行::criAtomPlayer_GetStatus 函数时，AtomPlayer将返回名为"状态"的值来表示Player状态。
为状态定义了以下值，可以从该值了解Player的状态。

状态和Player状态的关系

状态	Player状态
CRIATOMPLAYER_STATUS_STOP	Player正在停止。 不会播放音频数据。
CRIATOMPLAYER_STATUS_PREP	Player正在准备播放音频。 正在读取音频数据，但还没有开始发声。
CRIATOMPLAYER_STATUS_PLAYING	Player正在播放音频。 一边读取音频数据一边发声。
CRIATOMPLAYER_STATUS_PLAYEND	Player完成播放。 设置的音频数据播放到最后并结束。
CRIATOMPLAYER_STATUS_ERROR	Player播放音频失败。 发生了读取错误等问题。

AtomPlayer的状态通常随着音频播放按照以下顺序转换。

1. 创建AtomPlayer时，Player的状态为STOP。
2. 通过执行::criAtomPlayer_Start 函数，Player的状态转换为PREP。
3. 在读取播放所需的音频数据时，Player的状态转换为PLAYING，开始发声。
4. 播放完所有设置的数据时，发声结束，Player的状态转换为PLAYEND。

［备注］
如果在播放期间发生了某个错误（例如数据读取失败），则Player的状态转换为ERROR。
此外，如果使用::criAtomPlayer_Stop 函数停止播放，则Player的状态转换为STOP。
此外，与AtomExPlayer类似，AtomPlayer的状态也要进行状态转换。

丢弃Player

可以使用::criAtomPlayer_Destroy 函数丢弃不再需要的AtomPlayer。
通过丢弃AtomPlayer，可以将创建Player时设置的工作内存用于其他用途或释放内存。

［备注］
如果一个AtomPlayer依次播放多个声音，则不需要每次发声开始都丢弃。
可以使用::criAtomPlayer_SetData 函数等为停止的AtomPlayer（STOP状态、PLAYEND状态、ERROR状态的Player）设置其他音频数据，使用:criAtomPlayer_Start 函数播放。
（如果执行::criAtomPlayer_Start 函数但不重新设置数据，则从头开始播放上次播放的音频。）

［注意］
对于正在播放的AtomPlayer（PREP状态或PLAYING状态的Player），不能使用::criAtomPlayer_Set ～函数设置数据及使用::criAtomPlayer_Start 函数执行重启处理。
（将会报错。）

如果想要中止当前的播放并从头开始播放其他的音频数据，请使用::criAtomPlayer_Stop 函数停止播放，当状态变为STOP后再执行接下来的播放操作。

关于其他功能

AtomPlayer除简单播放音频外，还具有更改正在播放的声音的音量、连接多个音频数据播放等功能。