TTS播放器

以下描述了如何使用灵云TTS播放器功能。

1. TTS播放器简介

TTS播放器封装了灵云SDK的TTS模块并且实现了实时播放的功能，能将任意文字信息实时转化为标准流畅的自然语音并朗读出来。

2. TTS能力

TTS播放器封装了灵云SDK的TTS能力，其许多概念仍然是基于TTS基础API的。建议在使用灵云TTS播放器之前， 先熟悉 TTS能力 的相关内容。

在使用灵云TTS播放器之前，需要选择合适的TTS模块和能力以及音频编解码库， 具体请参见 选择模块和能力 和 音频编解码库。

3. 初始化

在使用播放器之前，仍然需要先初始化系统模块，请参见 系统模块的初始化/终止。

3.1 创建播放器对象

在初始化系统模块之后，就可以使用 hci_tts_player_init() 创建播放器对象，同时需要设置初始化参数和回调函数参数。

3.2 设置初始化参数

初始化参数主要是设置本地资源库的路径等。

// 设置回调参数及用户数据
PLAYER_CALLBACK_PARAM paramcallback;

paramcallback.pfnStateChange = PlayerEventStateChangeCallback;
paramcallback.pfnProgressChange = PlayerProgressChangeCallback;
paramcallback.pfnPlayerError = PlayerErrorCallback;
paramcallback.pvStateChangeUsrParam = NULL;
paramcallback.pvProgressChangeUsrParam = NULL;
paramcallback.pvPlayerErrorUsrParam = NULL;

// 设置初始化参数
// initCapKeys: 如果使用本地能力，配置需要使用的能力，SDK利用此信息初始化本地音库，云端能力不需要设置此项
// dataPath: 如果使用本地能力，需要设置本地音库文件路径
const char* pszConfig = "initCapKeys=tts.local.synth,dataPath=/mount/myapp/Document";

PLAYER_ERR_CODE playerRet = PLAYER_ERR_NONE;
playerRet = hci_tts_player_init(pszConfig, &paramcallback);

如果是只使用云端能力，可以直接指定初始化配置串为空或者NULL。

3.3 设置回调函数

为了能接收播放器内部信息，如状态信息、播放情况及错误信息等，应用层需要实现播放器的回调函数接口。 回调函数通过 PLAYER_CALLBACK_PARAM 参数传递给 hci_tts_player_init() 函数。 下面的代码示例实现了回调函数接口的写法：

// 事件回调，通知外部播放器状态的变化，如开始播放、播放完毕等
void PlayerEventChangeCallback(
                                                        _MUST_ _IN_ PLAYER_EVENT ePlayerEvent,
                                                        _OPT_ _IN_ void * pUsrParam )
{
                
        // ePlayerEvent - 可能出现的事件：
        // PLAYER_EVENT_BEGIN: 开始播放
        // PLAYER_EVENT_BUFFERING: 播放缓冲，等待合成数据
        // PLAYER_EVENT_BUFFERING_END: 缓冲结束，继续播放
        // PLAYER_EVENT_PAUSE: 暂停播放
        // PLAYER_EVENT_RESUME: 恢复播放
        // PLAYER_EVENT_END: 播放完毕

}

// 进度回调，通知外部当前正在播放文本的起止位置
void PlayerProgressChangeCallback(
                                                        _MUST_ _IN_ PLAYER_EVENT ePlayerEvent,
                                                        _MUST_ _IN_ int nStart,
                                                        _MUST_ _IN_ int nStop,
                                                        _OPT_ _IN_ void * pUsrParam )
{
  
        //可以在此处截取当前正在播放的字符串，显示给用户
        // ePlayerEvent - 可能出现的事件：
        // PLAYER_EVENT_PROGRESS

}

// 出错回调，通知外部出现的错误
void PlayerErrorCallback(
                                        _MUST_ _IN_ PLAYER_EVENT ePlayerEvent,
                                        _MUST_ _IN_ HCI_ERR_CODE eErrorCode,
                                        _OPT_ _IN_ void * pUsrParam 
{
        // ePlayerEvent - 可能出现的事件：
        // PLAYER_EVENT_DEVICE_ERROR
        // PLAYER_EVENT_ENGINE_ERROR    }

4. 合成播放

通过 hci_tts_player_start() 来播放由文本合成的语音数据，示例如下：

// 配置选项 
// capKey: 设置语音合成的能力（发音人）
// audioFormat: 设置语音合成的音频格式
char * pszConfig = "capKey=tts.local.synth,audioFormat=pcm16k16bit";

// 合成文本是UTF8编码，有些平台需要转换
char * pszText = "要播放的文本";

// 开始合成指定文本并实时播放
errCode = hci_tts_player_start(pszText, pszConfig);

这里的配置项pszConfig包括了初始化会话的配置项（capKey，也即发音人）、合成选项以及播放设备ID（deviceId）选项。

• capKey选项请参见 TTS能力描述 。
• 合成选项设置请参照TTS基础API的 合成选项。
• deviceId选项用于指定播放设备的ID，不指定则为系统自动匹配（WAVE_MAPPER）。
  
  

要注意的是：播放器支持的格式audioFormat只有pcm。windows平台支持pcm8K16bit pcm16k16bit, ios平台支持pcm8k8bit pcm8k16bit pcm11k8bit pcm11k16bit pcm16k8bit pcm16k16bit。

start() 函数会在后台启动一个线程进行播放，因此此函数会立即退出。播放的状态变化或者是否错误可以通过回调函数来获得。另外 回调函数还可以获得当前合成的文本位置，开发者可根据此位置信息实现类似高亮显示这样的功能。

5. 暂停和恢复

可以使用 hci_tts_player_pause() 和 hci_tts_player_resume() 来暂停和恢复播放过程。

//暂停播放
PLAYER_ERR_CODE playerRet = PLAYER_ERR_NONE;
playerRet = hci_tts_player_pause();

//恢复播放
PLAYER_ERR_CODE playerRet = PLAYER_ERR_NONE;
playerRet = hci_tts_player_resume();

6. 停止

可以使用 canStop() 来检查当前是否可以被停止，只有当播放器处于 PLAYER_STATE_PLAYING 或者 PLAYER_STATE_PAUSE时， 才能够被停止。

可以使用 stop() 来停止播放过程。

bool bCanStop = hci_tts_player_can_stop();

if (bCanStop) {
        PLAYER_ERR_CODE playerRet = hci_tts_player_stop();
}

7. 获取播放器状态

可以使用 hci_tts_player_get_state() 来获取播放器当前状态

PLAYER_STATE playerState = hci_tts_player_get_state();
switch (playerState)
{
        // 不同状态的处理
        ...
}

8. 反初始化

当不再使用TTS播放器的时候，需要反初始化TTS播放器，示例如下：

//反初始化tts_player
PLAYER_ERR_CODE playerRet = PLAYER_ERR_NONE;
playerRet = hci_tts_player_release();

当不再使用其它灵云能力时，需要反初始化系统模块，请参见 系统模块的初始化/终止。