AidVoice C++ API 接口文档
💡注意 使用 AidVoice-SDK C++ 开发需要了解如下事项：
- 编译时需要包含头文件，存放路径 /usr/local/include/aidlux/aidvoice/aidvoice_speech.hpp
- 链接时需要指定库文件，存放路径 /usr/local/lib/libaidvoice_speech.so
具体功能类型.enum FeatureType
FeatureType 用于在初始化 AidVoice SDK 时指定核心业务模块。由于 AidVoice SDK 包含多种语音功能，开发者在创建功能实例（Object）时，必须通过此枚举明确指定具体的语音功能。目前 SDK 已支持语音识别 (ASR) 与语音合成 (TTS) 功能，更多语音功能正在持续接入中。。
| 成员变量名 | 类型 | 值 | 描述 |
|---|---|---|---|
| TYPE_DEFAULT | uint8_t | 0 | 无效数据类型 |
| TYPE_ASR | uint8_t | 1 | 语音识别 |
| TYPE_TTS | uint8_t | 2 | 语音合成 |
模型类型.enum ModelType
ModelType定义了 AidVoice SDK 支持的推理模型算法。用户需根据应用场景选择合适的模型。目前仅支持 ASR 的 whisper_bash 与 sensevoice_small 模型。
| 成员变量名 | 类型 | 值 | 描述 |
|---|---|---|---|
| TYPE_DEFAULT | uint8_t | 0 | 无效数据类型 |
| TYPE_WHISPER | uint8_t | 1 | whipser_base模型 |
| TYPE_SENSEVOICE | uint8_t | 2 | sensevoice_samll模型 |
| TYPE_MELOTTS_CHINESE | uint8_t | 2 | melotts_chinese模型 |
| TYPE_MELOTTS_ENGLISH | uint8_t | 2 | melotts_english模型 |
💡注意
特别说明:
TYPE_WHISPER 与 TYPE_SENSEVOICE 为 ASR 模型，且均具备多语言支持（中、英等）。
- 英文场景： 建议优先选择 TYPE_WHISPER，其在英文识别精度与语义理解上表现更佳。
- 中文场景： 建议优先选择 TYPE_SENSEVOICE，其在中文识别精度与语义理解上表现更佳。
TYPE_MELOTTS_CHINESE 与 TYPE_MELOTTS_ENGLISH 为 TTS 模型，分别支持中文与英文语音合成。
音频类型.enum AudioType
在进行语音识别（ASR）或语音合成（TTS）任务时，需要明确输入/输出音频的编码格式与采样属性。通过设置此枚举，SDK 能够正确解析音频流数据或生成指定格式的音频文件。
| 成员变量名 | 类型 | 值 | 描述 |
|---|---|---|---|
| TYPE_DEFAULT | uint8_t | 0 | 无效数据类型 |
| TYPE_WAV | uint8_t | 1 | WAV格式音频 |
| TYPE_PCM | uint8_t | 2 | PCM格式音频 |
💡注意
为了确保语音识别（ASR）的准确度及系统稳定性，送入 SDK 的原始音频流必须严格符合以下标准：
- 采样频率：固定为 16k Hz。
- 声道配置：仅支持 单声道 (Mono) 输入。
- 数据精度：必须为 16-bit (Sign 16-bit) 深度。
目前 TTS 模块仅支持输出 WAV 格式的音频流；而相关音频枚举值主要用于 ASR 模块，作为其识别不同输入音频类型的判别依据
日志级别.enum LogLevel
AidVoiceSDK 提供有设置日志相关信息的接口（后续会介绍），如果需要指定 AidVoiceSDK 当前使用哪个日志级别，就需要使用此日志级别枚举。
| 成员变量名 | 类型 | 值 | 描述 |
|---|---|---|---|
| INFO | uint8_t | 0 | 消息 |
| WARNING | uint8_t | 1 | 警告 |
| ERROR | uint8_t | 2 | 错误 |
| FATAL | uint8_t | 3 | 致命错误 |
| DEBUG | uint8_t | 4 | 调试 |
| OFF | uint8_t | 5 | 关闭 |
返回结果状态.enum ResultStatus
ResultStatus 用于定义所有 SDK 执行的返回状态。通过检查该枚举值，开发者可以判断当前执行流程是否成功执行。若返回非成功状态，可根据具体的错误信息进行故障排查。
| 成员变量名 | 类型 | 值 | 描述 |
|---|---|---|---|
| AV_OK | uint8_t | 0 | 执行成功 |
| AV_ERR_INVALID_ARG | uint8_t | 1 | 无效参数 |
| AV_ERR_LOAD_FILE | uint8_t | 2 | 文件加载失败 |
| AV_ERR_RUN_FAIL | uint8_t | 3 | 运行时错误 |
| AV_ERR_UNSUPPORTED | uint8_t | 4 | 不支持当前操作 |
| AV_ERR_GENERATE_OBJECT | uint8_t | 5 | 创新创建失败 |
| AV_OTHER | uint8_t | 6 | 其它 |
全局配置信息类.class FeatureConfig
FeatureConfig 结构体用于存储构建具体功能对象所需的全部配置信息。在初始化 SDK 实例前，开发者需要先实例化此类，并根据业务需求设置功能类型、模型选择及日志级别。
成员变量列表
FeatureConfig包含如下的这些参数：
| 成员 | feature_type |
| 类型 | FeatureType |
| 默认 | 无默认值 |
| 描述 | 指定 SDK 的业务模式，语音（识别/合成等） |
| 成员 | model_type |
| 类型 | ModelType |
| 默认 | 无默认值 |
| 描述 | 指定功能对象所使用的模型 |
| 成员 | log_type |
| 类型 | LogLevel |
| 默认 | TYPE_OFF |
| 描述 | 指定日志级别 |
语音识别 ASR 相关接口
本节详细介绍 AidVoice SDK 中与自动语音识别（ASR）相关的核心 API 接口。开发者可以通过这些接口完成从 ASR 实例创建、音频流数据送入到识别结果获取的全流程操作。
功能说明： ASR 模块旨在将输入的 16k/单声道/16位深原始音频流实时或离线转换为文本信息。目前支持 senseVoice_small 与 whisper_base 两种主流推理模型。
语音识别模式.enum ASRMode
ASRMode 用于定义语音识别结果的输出策略。开发者需根据应用场景的实时性要求，选择增量反馈（流式）或整句输出（非流式）模式。
| 成员变量名 | 类型 | 值 | 描述 |
|---|---|---|---|
| TYPE_STREAM | uint8_t | 0 | 流式输出：可返回中间转录结果 |
| TYPE_NOSTREAM | uint8_t | 1 | 非流式输出：每次处理返回最终转录结果 |
💡注意
特别说明:
- 流式处理 (Streaming)：在音频处理过程中实时生成临时转录结果。随着后续音频流的输入，SDK 会不断修正并更新中间文本。该模式允许在音频缓冲区完全处理结束前返回数据，能显著降低首字响应延迟，提升交互体验；
- 非流式处理 (Non-Streaming)：基于固定的音频时长进行转录。若提前检测到语音结束（如用户主动停止输入）或语音时长不足，系统将立即提前生成并返回最终转录文本；
💡注意
不同推理模型对单次处理的音频时长有严格限制，开发者在配置非流式转录或预处理音频段时需特别注意：
- TYPE_WHISPER：单次支持的最大音频输入长度为 24s。
- TYPE_SENSEVOICE：单次支持的最大音频输入长度为 15s。
- 若单次送入的音频数据超过上述限制，SDK 将输入音频数据截断，被截断的后续音频将自动触发开启新一轮的转录任务。
语音转录状态.enum AsrStatus
AsrStatus 用于标识 ASR 返回的文本结果在当前识别轮次中的状态。通过解析此状态，开发者可以区分当前获得的是“正在修正的中间词”还是“已确定的最终语句”。
| 成员变量名 | 类型 | 值 | 描述 |
|---|---|---|---|
| TYPE_PARTIAL | uint8_t | 0 | 转录的中间过程，转录未结束 |
| TYPE_FINAL | uint8_t | 1 | 转录的最终结果，转录完成 |
💡注意
特别说明:
- 流式模式 (TYPE_STREAM)：流式模式时，若结果状态信息为PARTIAL，表示当前音频缓冲区尚未完全处理之前返回的中间结果。只有当状态信息标志为FINAL时，表示当前缓冲区数据处理完成。
- 非流式模式 (TYPE_NOSTREAM)：非流式模式下，每次转录的状态信息都为FINAL。
//流式模型：
I am. TYPE_PARTIAL
I am a boy. TYPE_PARTIAL
I am a boy. I like Aplux. TYPE_FINAL
//非流式模型：
I am a boy. I like Aplux. TYPE_FINALASR结果返回类.class AsrResult
AsrResult 结构体用于承载 ASR 输出的转录数据以及转录状态。当 SDK 完成一段音频的处理后，会将识别出的文本内容及其对应的实时状态（中间或最终）封装在此类中返回给开发者。
成员变量列表
AsrResult包含如下的这些参数：
| 成员 | status |
| 类型 | AsrStatus |
| 默认 | 无默认值 |
| 描述 | 当前返回结果的转录状态 |
| 成员 | text |
| 类型 | std::string |
| 默认 | 无默认值 |
| 描述 | 当前转录的文本结果 |
| 成员 | id |
| 类型 | int |
| 默认 | 0 |
| 描述 | 返回结果的id值 |
ASR错误返回类.class AsrError
AsrError 结构体用于承载 ASR 输出的异常信息。当接口调用返回非成功状态时，开发者可以通过此类获取具体的错误代码及详细的描述文本
成员变量列表
AsrError包含如下的这些参数：
| 成员 | status |
| 类型 | ResultStatus |
| 默认 | 无默认值 |
| 描述 | 错误信息状态 |
| 成员 | error_code |
| 类型 | int |
| 默认 | 无默认值 |
| 描述 | 错误码 |
| 成员 | message |
| 类型 | std::string |
| 默认 | 无默认值 |
| 描述 | 当前返回的错误信息 |
ASR回调接口类.class ASRCallbacks
ASRCallbacks 是一个虚基类，用于定义 SDK 向应用层推送数据的监听接口。开发者需要继承此类并实现其中的虚函数，从而异步获取识别结果或错误信息。
获取转录结果.onResult()
当 ASR 底层处理完一段音频并生成文本时，会自动触发此回调。
| API | onResult |
| 描述 | 语音识别结果回调函数 |
| 参数 | result:转录结果对象，包含当前识别到的文本内容和结果状态 |
| 返回 | void |
| API | onError |
| 描述 | 错误信息回调函数。用于接收并处理 ASR 运行期间产生的各类异常 |
| 参数 | error:错误信息对象，包含当前错误描述和错误码等 |
| 返回 | void |
class ASRCallbacksImpl : public ASRCallbacks
{
public:
void onResult(const AsrResult &result) override
{
string asrResult = result.text;
int sid = result.id;
AsrStatus status = result.status;
printf("=================\n");
std::cout << "sid: " << sid << std::endl;
std::cout << "asrResult: \n"
<< asrResult << std::endl;
std::cout << "status: " << (int)status << std::endl;
printf("=================\n");
total_echo = sid;
}
void onError(const AsrError &error) override
{
int errCode = error.error_code;
int errStatus = (int)error.status;
string errMsg = error.message;
printf("=================\n");
std::cout << "errMsg: " << errMsg << std::endl;
printf("=================\n");
}
~ASRCallbacksImpl() = default;
};ASR核心业务类.class AidVoiceASR
AidVoiceASR 是 SDK 的功能主体，负责管理语音识别的完整生命周期。开发者通过该类提供的接口进行模型加载、音频数据推送以及识别任务的停止。该类必须配合 FeatureConfig 进行初始化。
创建实例对象.create_asr()
该接口是使用 SDK 的第一步。它根据传入的全局配置信息（如功能类型、模型类型等），在内存中构建并初始化具体的 ASR 识别对象。
| API | create_asr |
| 描述 | 根据传入的配置对象构建具体的 ASR 实例 |
| 参数 | cfg:全局配置参数，用于指定模型类型及日志级别 |
| 返回 | 成功返回 AidVoiceASR 实例指针。 失败则返回 nullptr |
💡注意
特别说明:
- 在调用此接口前，请确保 cfg.feature_type 已设置为 TYPE_ASR
设置模式.set_mode()
该接口用于设置 ASR 的工作模式。开发者可以根据业务需求（如实时语音交互或离线长文本转写），将其设置为流式或非流式模式。
| API | set_mode |
| 描述 | 设置 ASR 识别的工作模式 |
| 参数 | mode：具体的识别模式 |
| 返回 | void |
设置回调.set_callback()
该接口用于将用户实现的回调监听实例注册到 ASR 中。注册后，SDK 将通过该实例异步推送转录文本（onResult）或错误信息（onError）。
| API | set_callback |
| 描述 | 注册回调监听对象，用于接收异步返回的识别结果 |
| 参数 | cb：用户定义的 ASRCallbacks 实现类的实例指针 |
| 返回 | void |
//这里必须动态开辟空间 由 AidVoice 底层释放
ASRCallbacksImpl *mASRCallbacks = new ASRCallbacksImpl();
// 注册后，对象的所有权将移交给 AidVoice 内部
asr->set_callback(mASRCallbacks);💡注意
特别说明:
- 传入的回调实例必须使用 new 关键字在堆上动态开辟空间, 且一旦调用了 set_callback，该指针的生命周期将由 AidVoice 底层接管。SDK 会在 ASR 实例销毁时自动进行 delete 操作。
设置最大音频处理时长.set_echo_ms()
该接口用于配置 ASR 单次推理任务所能接收的最大音频长度，单位ms。
| API | set_echo_ms |
| 描述 | 设置 ASR 单次推理处理的音频时长阈值 |
| 参数 | echo_ms: 单次处理时长阈值 |
| 返回 | void |
💡注意
设置此参数时，必须遵守所选模型的单词处理上限：
- whisper模型： 不得超过 24000 (24s)。
- sensevoie模型：echo_ms 不得超过15000（15s）。
设置流式反馈间隔.set_step_ms()
该接口专为流式模式（TYPE_STREAM） 设计，用于配置 ASR 返回中间转录结果（PARTIAL 状态）的时间频率。
| API | set_step_ms |
| 描述 | 设置流式转录结果的回调频率（单位：毫秒）。即每累计处理指定时长的音频，便触发一次回调。 |
| 参数 | step_ms：结果反馈的时间步长。 |
| 返回 | void |
💡注意
特別注意：
- 该设置仅在流式模式下生效。在非流式模式下，系统将忽略此配置，直接在识别完成后返回最终结果。
- step_ms 设置的越小，实时性越高。在麦克风实时输入场景下，step_ms设置过小，可能导致输出不连贯的情况。因为底层 SDK 为了保证“当前时刻”的实时性，采用了覆盖式缓存策略。若模型处理速度赶不上音频送入速度，尚未处理的旧数据可能会被新送入的音频覆盖，从而导致识别结果不连贯。
设置音频保存.set_save_audio()
该接口主要用于麦克风实时输入场景。开启后，SDK 将自动捕获麦克风接收的原始音频流并以wav格式保存到本地。
| API | set_save_audio |
| 描述 | 配置是否将麦克风输入的原始音频数据保存到本地。 |
| 参数 | save_audio：布尔值，true表示开启保存。 false表示关闭（默认值）。 |
| 返回 | void |
初始化接口.init()
ASR 对象创建之后，需要执行一些初始化操作（比如环境检查、资源构建等）。
| API | init |
| 描述 | 完成推理所需的相关的初始化工作 |
| 参数 | void |
| 返回 | 0 值则说明初始化操作执行成功，否则非 0 值就说明执行失败 |
// ASR 初始化，返回值非0则报错
int ret = asr->init();
if (ret != EXIT_SUCCESS)
{
printf("asr->init() failure!\n");
return EXIT_FAILURE;
}数据输入.write()
在 ASR 实例成功调用 init() 之后，即可通过 write() 接口送入待识别的音频数据。SDK 支持多种数据源输入，以适配文件转写、流式录音等不同业务场景。
音频文件作为输入数据
该接口直接读取本地音频文件进行识别。
| API | write |
| 描述 | 传入 16kHz 采样率的 WAV 音频文件路径。SDK 将自动解析文件并进行识别 |
| 参数 | wav_16k_file：本地音频文件的绝对路径或相对路径 |
| 返回 | 0 值则说明操作执行成功，否则非 0 值就说明执行失败 |
// 音频文本作为输入数据，返回值非0则报错
std::string wave_path = "audio.wav";
int ret = asr->write(wave_path);
if (ret != EXIT_SUCCESS)
{
printf("asr->write() failure!\n");
return EXIT_FAILURE;
}💡注意
特別注意：
音频文件必须为单声道、16bit 位深的wav/pcm格式，采样率需为 16000Hz
原始字节流作为作为输入数据
该接口接收内存中的原始音频字节流。
| API | write |
| 描述 | 向 ASR 推送原始音频字节流。 |
| 参数 | data:指向音频数据缓冲区的指针 len:缓冲区数据的字节长度 |
| 返回 | 0 值则说明操作执行成功，否则非 0 值就说明执行失败 |
// 原始字节流作为输入数据，返回值非0则报错
char *data = new char[fileLen];
// ... 此处填充音频数据 ..
int ret = asr->write(data, data_size);
if (ret != EXIT_SUCCESS)
{
printf("asr->write() failure!\n");
return EXIT_FAILURE;
}float数组作为输入数据
该接口接收浮点型音频采样数据，适用于已完成预处理并转换为标准浮点格式的音频流。
| API | write |
| 描述 | 向 ASR 推送float类型的音频采样数组 |
| 参数 | auido_data:包含音频采样点的float数组 |
| 返回 | 0 值则说明操作执行成功，否则非 0 值就说明执行失败 |
// flaot数组作为输入数据，返回值非0则报错
std::vector<float> audio_;
// ... 此处填充音频数据 ..
int ret = asr->write(audio_);
if (ret != EXIT_SUCCESS)
{
printf("asr->write() failure!\n");
return EXIT_FAILURE;
}麦克风实时语音输入.audio_mircophone()
该接口会根据设置麦克风id，来调用麦克风驱动进行音频采集，并将获取的数据直接送入 ASR 底层。
| API | audio_mircophone |
| 描述 | 启动指定 id 的麦克风设备，并开始实时语音识别 |
| 参数 | id：麦克风硬件设备 id，默认设备为 0 |
| 返回 | 0 值则说明操作执行成功，否则非 0 值就说明执行失败 |
💡注意
特別注意：
- 该接口仅支持流式模式（TYPE_STREAM）。在调用此接口前，必须先调用 set_mode(TYPE_STREAM)。
- 在终端运行环境，支持通过 Ctrl + C 捕获系统信号来安全停止输入流。若在采集过程中断开麦克风设备，ASR 也将并自动终止输入。
//执行后，便会启动id为1的麦克风设备，实时接收语音
asr->audio_mircophone(1);ASR 停止输入.stop()
该接口用于通知 ASR 底层音频流已结束。调用后，ASR 将处理完缓冲区内剩余的所有音频，并触发相应的 onResult 回调。
| API | stop |
| 描述 | 停止音频输入 |
| 参数 | void |
| 返回 | 0 值则说明操作执行成功，否则非 0 值就说明执行失败 |
ASR 对象销毁.asr_destory()
在所有语音识别任务结束且不再需要使用 ASR 功能时，必须调用此接口。它将彻底释放资源。
| API | asr_destory |
| 描述 | 彻底销毁 ASR 实例并释放关联的所有资源 |
| 参数 | void |
| 返回 | 0 值则说明操作执行成功，否则非 0 值就说明执行失败 |
语音合成 TTS 相关接口
本节详细介绍 AidVoice SDK 中与语音合成（TTS）相关的核心 API 接口。开发者可以通过这些接口实现从 TTS 实例创建、合成文本送入到最终音频获取的全流程操作。
功能说明： TTS 模块旨在将输入的文本转换为对应的音频文件。目前支持 melotts_chinese 与 melotts_english 两种主流推理模型。
语音合成模式.enum TTSMode
TTSMode 用于配置合成音频的输出策略。开发者需根据应用场景的实时性要求，选择整局输出或分段输出。
| 成员变量名 | 类型 | 值 | 描述 |
|---|---|---|---|
| TYPE_WHOLE | uint8_t | 0 | 整局输出：待整句文本全部合成完成后，一次性回调完整音频 |
| TYPE_FRAGMENT | uint8_t | 1 | 分段输出：根据标点符号或语义停顿进行切片，合成短句即刻输出 |
💡注意
特别说明:
- 整局输出 (whole)：将完整文本作为单一任务进行处理，待所有音频数据合成完毕后一次性触发结果回调，保证了输出音频的完整性
- 分段输出 (fragment)：根据标点符号及语义停顿点将长文本智能切分为多个短句片段，每完成一个片段的合成便立即输出。
合成音频状态.enum TTSStatus
TTSStatus 用于标识 TTS 引擎返回音频结果的实时状态。通过解析此状态，开发者可以准确判定当前接收到的是任务过程中的“部分片段”还是“最终结果”
| 成员变量名 | 类型 | 值 | 描述 |
|---|---|---|---|
| TYPE_PARTIAL | uint8_t | 0 | 合成的完整音频 |
| TYPE_FINAL | uint8_t | 1 | 合成的部分音频 |
💡注意
特别说明:
- 分段输出 (TYPE_FRAGMENT)：分段模式时，若结果状态信息为PARTIAL，表示当前音频仅为整段文本的一个中间切片（如一个短句）。只有当状态信息标志为FINAL时，才代表该次合成任务（当前句子）已彻底结束。
- 整局输出 (TYPE_WHOLE)：整局模式下，每次音频合成的状态信息都为FINAL。
TTS结果返回类.class TTSResult
TTSResult 结构体用于承载 TTS 合成的音频以及音频状态。当 SDK 合成一段音频之后，会将音频的相关信息及其对应的音频状态（部分或最终）封装在此类中返回给开发者。
成员变量列表
TTSResult包含如下的这些参数：
| 成员 | status |
| 类型 | TTSStatus |
| 默认 | 无默认值 |
| 描述 | 当前返回音频的状态 |
| 成员 | audio_name |
| 类型 | std::string |
| 默认 | 无默认值 |
| 描述 | 当前输出音频的文件名 |
| 成员 | audio_len |
| 类型 | double |
| 默认 | 0 |
| 描述 | 当前输出音频的时长，单位（s） |
| 成员 | seq |
| 类型 | int |
| 默认 | 1 |
| 描述 | 表示当前返回的音频块属于输入文本合成序列中的第几个片段 |
| 成员 | id |
| 类型 | int |
| 默认 | 0 |
| 描述 | 返回结果的id值 |
TTS错误返回类.class TTSError
TTSError 结构体用于承载 TTS 输出的异常信息。当接口调用返回非成功状态时，开发者可以通过此类获取具体的错误代码及详细的描述文本
成员变量列表
TTSError包含如下的这些参数：
| 成员 | status |
| 类型 | ResultStatus |
| 默认 | ResultStatus::AV_OTHER |
| 描述 | 错误信息状态 |
| 成员 | error_code |
| 类型 | int |
| 默认 | -1 |
| 描述 | 错误码 |
| 成员 | message |
| 类型 | std::string |
| 默认 | 无默认值 |
| 描述 | 当前返回的错误信息 |
TTS回调接口类.class TTSCallbacks
TTSCallbacks 是一个虚基类，用于定义 SDK 向应用层推送数据的监听接口。开发者需要继承此类并实现其中的虚函数，从而异步获取识别结果或错误信息。
获取转录结果.onResult()
当 TTS 底层处理完一段文本并生成音频时，会自动触发此回调。
| API | onResult |
| 描述 | 语音合成结果回调函数 |
| 参数 | result:合成结果对象，包含当前合成音频相关信息和音频状态 |
| 返回 | void |
| API | onError |
| 描述 | 错误信息回调函数。用于接收并处理 TTS 运行期间产生的各类异常 |
| 参数 | error:错误信息对象，包含当前错误描述和错误码等 |
| 返回 | void |
class TTSCallbacksImpl : public TTSCallbacks
{
public:
void onResult(const TTSResult &result) override
{
std::string audio_name = result.audio_name;
double audio_len = result.audio_len;
int seq = result.seq;
int sid = result.id;
TTSStatus status = result.status;
printf("=================\n");
std::cout << "sid: " << sid << std::endl;
std::cout << "audio_name:"<< audio_name << std::endl;
std::cout << "audio_len: " << (double)audio_len << std::endl;
std::cout << "seq: " << (int)seq << std::endl;
std::cout << "status: " << (int)status << std::endl;
printf("=================\n");
}
void onError(const TTSError &error) override
{
int errCode = error.error_code;
int errStatus = (int)error.status;
string errMsg = error.message;
printf("=================\n");
std::cout << "errMsg: " << errMsg << std::endl;
printf("=================\n");
}
~TTSCallbacksImpl() = default;
};TTS核心业务类.class AidVoiceTTS
AidVoiceTTS 是 SDK 的功能主体，负责管理语音合成的完整生命周期。开发者通过该类提供的接口进行模型加载、合成文本推送以及音频合成任务的停止。该类必须配合 FeatureConfig 进行初始化。
创建实例对象.create_tts()
该接口是使用 SDK 的第一步。它根据传入的全局配置信息（如功能类型、模型类型等），在内存中构建并初始化具体的 TTS 语音合成对象。
| API | create_tts |
| 描述 | 根据传入的配置对象构建具体的 TTS 实例 |
| 参数 | cfg:全局配置参数，用于指定模型类型及日志级别 |
| 返回 | 成功返回 AidVoiceTTS 实例指针。 失败则返回 nullptr |
💡注意
特别说明:
- 在调用此接口前，请确保 cfg.feature_type 已设置为 TYPE_TTS
设置模式.set_mode()
该接口用于设置 TTS 的工作模式。开发者可以根据业务需求，将其设置为整局输出或片段输出。默认情况下 TTS 工作在整局模式（TYPE_WHOLE）。
| API | set_mode |
| 描述 | 设置 TTS 的工作模式 |
| 参数 | mode：具体的工作模式 |
| 返回 | void |
设置回调.set_callback()
该接口用于将用户实现的回调监听实例注册到 TTS 中。注册后，SDK 将通过该实例异步推送合成音频信息（onResult）或错误信息（onError）。
| API | set_callback |
| 描述 | 注册回调监听对象，用于接收异步返回的音频合成信息 |
| 参数 | cb：用户定义的 TTSCallbacks 实现类的实例指针 |
| 返回 | void |
//这里必须动态开辟空间 由 AidVoice 底层释放
TTSCallbacksImpl *mTTSCallbacks = new TTSCallbacksImpl();
// 注册后，对象的所有权将移交给 AidVoice 内部
tts->set_callback(mTTSCallbacks);💡注意
特别说明:
- 传入的回调实例必须使用 new 关键字在堆上动态开辟空间, 且一旦调用了 set_callback，该指针的生命周期将由 AidVoice 底层接管。SDK 会在 TTS 实例销毁时自动进行 delete 操作。
初始化接口.init()
TTS 对象创建之后，需要执行一些初始化操作（比如环境检查、资源构建等）。
| API | init |
| 描述 | 完成推理所需的相关的初始化工作 |
| 参数 | void |
| 返回 | 0 值则说明操作执行成功，否则非 0 值就说明执行失败 |
// TTS 初始化，返回值非0则报错
int ret = tts->init();
if (ret != EXIT_SUCCESS)
{
printf("tts->init() failure!\n");
return EXIT_FAILURE;
}数据输入.write()
在 TTS 实例成功初始化（即调用 init() 返回成功）后，开发者可通过 write() 接口提交待合成的文本数据。该接口支持批量文本送入（字符串数组进行接收），并采用异步方式返回合成的音频。
| API | write |
| 描述 | 向 TTS 投递文本数据。接口接收一个字符串数组（vector<string>），支持一次性提交多段独立文本 |
| 参数 | 待合成的文本数组。数组中的每一个元素将被视为一个独立的合成任务 |
| 返回 | 0 值则说明操作执行成功，否则非 0 值就说明执行失败 |
// 字符数组作为输入数据，返回值非0则报错
std::vector<std::string> str_vec = {"I am a boy.", "I like Aplux."};
int ret = tts->write(str_vec);
if (ret != EXIT_SUCCESS)
{
printf("tts->write() failure!\n");
return EXIT_FAILURE;
}💡注意
特別注意：
文本数据送入后，系统将通过回调接口异步返回合成后的音频流。输出音频严格遵循以下规格： *文件封装：标准 WAV 格式 *采样率：44100 Hz *声道数：Mono (单声道)
TTS 停止输入.stop()
该接口用于通知 TTS 引擎当前输入阶段已结束。调用后，SDK 不再接收新的文本输入，但会确保已送入缓冲区的剩余文本处理完毕。
| API | stop |
| 描述 | 正式关闭文本输入流 |
| 参数 | void |
| 返回 | 0 值则说明操作执行成功，否则非 0 值就说明执行失败 |
TTS 对象销毁.tts_destory()
当所有音频合成任务已结束，且应用生命周期内不再需要使用 TTS 功能时，必须调用此接口。该操作将彻底释放 SDK 占用的系统资源。
| API | tts_destory |
| 描述 | 彻底销毁 TTS 实例并释放关联的所有资源 |
| 参数 | void |
| 返回 | 0 值则说明操作执行成功，否则非 0 值就说明执行失败 |
其它方法
AidVoice SDK 除了提供前述的那些推理相关的接口，也提供如下一些辅助接口
获取麦克风列表.show_mircophone_dev()
在调用 audio_mircophone() 之前，建议先调用此接口枚举当前系统可用的音频输入设备，以便获取正确的设备 ID
| API | show_mircophone_dev |
| 描述 | 列出系统中所有可用的麦克风硬件设备。该接口会将设备名称及其对应的 ID 打印至标准输出（Stdout）或日志系统中 |
| 参数 | void |
| 返回 | 0 值则说明初始化操作执行成功，否则非 0 值就说明执行失败 |
获取当前 AidVoice SDK 版本.get_library_version()
获取当前 AidVoice SDK 的版本相关信息。
| API | get_library_version |
| 描述 | 获取当前 AidVoice SDK 的版本相关信息。 |
| 参数 | void |
| 返回 | string:版本信息 |
获取当前日志级别.get_log_level()
| API | get_log_level |
| 描述 | 获取当前的日志级别 |
| 参数 | void |
| 返回 | LogLevel:日志级别 |
设置日志级别.set_log_level()
| API | set_log_level |
| 描述 | 设置日志级别 |
| 参数 | LogLevel:日志级别 |
| 返回 | 默认返回 0 值 |
日志输出到标准终端.log_to_console()
| API | log_to_console |
| 描述 | 设置日志信息输出到标准错误终端 |
| 参数 | void |
| 返回 | 默认返回 0 值 |
日志输出到文本文件.log_to_file()
| API | log_to_file |
| 描述 | 设置日志信息输出到指定的文本文件 |
| 参数 | path_and_prefix:日志文件的存放路径与名称前缀 also_to_console：标识是否同时输出日志到 stderr 终端，默认值为 false |
| 返回 | 0 值则说明执行成功，否则非 0 值就说明执行失败 |
AidVoice C++ 示例程序
AidVoice ASR 音频识别示例程序
以音频文本识别为例，其 CPP 示例程序大致包含如下几个部分：
//全局配置信息
AidLux::AidVoice::FeatureConfig cfg;
cfg.feature_type = FeatureType::TYPE_ASR;
cfg.model_type = ModelType::TYPE_WHISPER;
//构建 ASR 对象
auto asr = AidLux::AidVoice::create_asr(cfg);
if (!asr)
{
printf("create_asr failure!\n");
return EXIT_FAILURE;
}
//继承回调接口
class ASRCallbacksImpl : public ASRCallbacks
{
public:
void onResult(const AsrResult &result) override
{
string asrResult = result.text;
int sid = result.id;
AsrStatus status = result.status;
printf("=================\n");
std::cout << "sid: " << sid << std::endl;
std::cout << "asrResult: \n"
<< asrResult << std::endl;
std::cout << "status: " << (int)status << std::endl;
printf("=================\n");
total_echo = sid;
}
void onError(const AsrError &error) override
{
int errCode = error.error_code;
int errStatus = (int)error.status;
string errMsg = error.message;
printf("=================\n");
std::cout << "errMsg: " << errMsg << std::endl;
printf("=================\n");
}
~ASRCallbacksImpl() = default;
};
//创建回调接口类，并设置回调接口
ASRCallbacksImpl *mASRCallbacks = new ASRCallbacksImpl();
asr->set_callback(mASRCallbacks);
//音频对象初始化
int ret = asr->init();
if (ret != EXIT_SUCCESS)
{
printf("asr->init() failure!\n");
return EXIT_FAILURE;
}
//送入音频文本数据
ret = asr->write(wave_path);
if (ret != EXIT_SUCCESS)
{
printf("asr->write() failure!\n");
return EXIT_FAILURE;
}
//停止输入数据
ret = asr->stop();
if (ret != EXIT_SUCCESS)
{
printf("asr->stop() failure!\n");
return EXIT_FAILURE;
}
//对象销毁
ret = asr->asr_destory();
if (ret != EXIT_SUCCESS)
{
printf("asr->asr_destory() failure!\n");
return EXIT_FAILURE;
}AidVoice TTS 音频合成示例程序
音频合成 CPP 示例程序大致包含如下几个部分：
//全局配置信息
AidLux::AidVoice::FeatureConfig cfg;
cfg.feature_type = FeatureType::TYPE_TTS;
cfg.model_type = ModelType::TYPE_MELOTTS_ENGLISH;
//构建 TTS 对象
auto tts = AidLux::AidVoice::create_tts(cfg);
if (!tts)
{
printf("create tts failure!\n");
return EXIT_FAILURE;
}
//设置tts工作模式
tts->set_mode(TTSMode::TYPE_WHOLE);
//继承回调接口
class TTSCallbacksImpl : public TTSCallbacks
{
public:
void onResult(const TTSResult &result) override
{
std::string audio_name = result.audio_name;
double audio_len = result.audio_len;
int seq = result.seq;
int sid = result.id;
TTSStatus status = result.status;
printf("=================\n");
std::cout << "sid: " << sid << std::endl;
std::cout << "audio_name:"<< audio_name << std::endl;
std::cout << "audio_len: " << (double)audio_len << std::endl;
std::cout << "seq: " << (int)seq << std::endl;
std::cout << "status: " << (int)status << std::endl;
printf("=================\n");
}
void onError(const TTSError &error) override
{
int errCode = error.error_code;
int errStatus = (int)error.status;
string errMsg = error.message;
printf("=================\n");
std::cout << "errMsg: " << errMsg << std::endl;
printf("=================\n");
}
~TTSCallbacksImpl() = default;
};
//创建回调接口类，并设置回调接口
TTSCallbacksImpl *mTTSCallbacks = new TTSCallbacksImpl();
tts->set_callback(mTTSCallbacks);
//TTS 对象初始化
int ret = tts->init();
if (ret != EXIT_SUCCESS)
{
printf("tts->init() failure!\n");
return EXIT_FAILURE;
}
//送入合成文本
std::vector<std::string> str_vec = {"This is an example of text to speech using Melo for English. How does it sound?"};
ret = tts->write(str_vec);
if (ret != EXIT_SUCCESS)
{
printf("tts->write() failure!\n");
return EXIT_FAILURE;
}
//停止输入数据
ret = tts->stop();
if (ret != EXIT_SUCCESS)
{
printf("tts->stop() failure!\n");
return EXIT_FAILURE;
}
//对象销毁
ret = tts->tts_destory();
if (ret != EXIT_SUCCESS)
{
printf("tts->tts_destory() failure!\n");
return EXIT_FAILURE;
}💡注意
更多的使用实例存放于如下路径：
- cpp 示例程序路径：/usr/local/share/aidvoice/examples/asr/cpp/
至此，已经展示了 AidVoice SDK 的所有接口内容。