一、功能简介
ITXRealtimeASR 是实时流式语音转写引擎：
·实时流式识别：边说边出字，逐句返回识别结果。
·中间结果与稳态结果：通过 isCompleted 区分进行中（中间结果）与已说完（稳态结果）。
·自动 / 指定识别语言：支持 "zh"（中文）、"en"（英文）等，留空即为自动识别。
·说话人区分：结果携带 speakerId，-1 表示未知。
·时间戳定位：结果携带 startTime / endTime，标识该消息在整个音频流中的起止位置（毫秒），-1 表示未知。
·实时音量回调：通过 onRealtimeASRVolume 获取当前音量等级 [0, 100]，可用于绘制音量波动效果。
·自定义音频采集：可通过 enableCustomCapture 开启，自行采集 PCM 后调用 feedPcmData 送入引擎。
·多监听器：通过 addListener / removeListener 注册多个回调监听器。
二、相比直接 WebSocket 接入的优势
相比业务方自行通过 WebSocket 对接 ASR 后端，SDK 在端侧完成音频前处理，提供以下开箱即用的能力：
·端侧远场人声降噪：SDK 内置远场人声增强与降噪算法，识别过程中可消除远场人声、环境噪声的干扰，显著提升会议室、客厅、车载等远场场景的识别准确率，业务方无需自行搭建音频前处理链路。可通过实验性 API callExperimentalAPI 的 setExtraParams 配置 clientDenoiseStrategy 选择降噪策略（详细参见 实验性 API 中的 setExtraParams）。
·声纹降噪（只识别指定人的声音）：支持指定目标说话人，识别过程中只转写目标说话人的声音，自动忽略其他人的说话内容，适用于多人会议、车载多乘员等只听某一个人的场景。
三、开通服务
登录 实时音视频控制台，单击创建应用 。如果你已经完成创建，可以跳过该操作。
在创建应用成功后，你可以在应用管理中获取到你的 SDKAppID 和 SDK 密钥。
·SDKAppID： 控制台创建的实时音视频应用的唯一标识。
·SDK 密钥：生成鉴权信息（UserSig）时使用的密钥串。
四、环境要求
| 项目 | 要求 |
| 操作系统 | Windows 7 及以上（x86 / x64）。 |
| 编译器 | 支持 C++14 的 MSVC / Clang。 |
| 依赖 | liteavsdk_voiceai 动态库（.dll + .lib 导入库）。 |
| 网络 | 实时转写为在线服务，需要可访问腾讯云的网络环境。 |
五、引入 SDK
1. 下载 Windows SDK
2. 头文件：将 SDK 的 include 目录加入工程附加包含目录，引入：
#include "tx_realtime_asr.h"
3. 链接库：将 liteavsdk_voiceai.lib（导入库）加入 附加依赖项，并确保运行时 liteavsdk_voiceai.dll 位于可执行文件目录或系统 PATH。
4. 导出符号：API 通过 LITEAVSDK_API 导出，工程无需定义 LITEAV_EXPORTS（该宏仅 SDK 内部构建使用）。
六、鉴权信息
启动转写前需要准备以下 TRTC 鉴权信息：
| 参数 | 说明 |
| sdkAppId | TRTC 应用 ID，可在腾讯云 TRTC 控制台获取。 |
| voiceId | 识别会话 ID，参与 userSig 计算，建议每次调用时重新生成 UUID 传入。 |
| userSig | TRTC 用户签名，由 sdkAppId、sdkAppKey、voiceId 三者计算得到。 |
注意：关于 UserSig 的安全说明：
注意：UserSig 是用户身份的加密凭证。请勿在客户端硬编码密钥（SECRETKEY）计算 UserSig，密钥一旦泄露会导致云资源被盗用；生产环境应在业务服务端计算 UserSig，App 通过接口动态获取。
注意：UserSig 计算方式参考：
七、实例创建与销毁
SDK 通过 C 风格工厂函数创建 / 销毁实例：
extern "C" liteav::ITXRealtimeASR* TXRealtimeASRCreate();extern "C" void TXRealtimeASRDestroy(liteav::ITXRealtimeASR* instance);
八、快速开始
#include "tx_realtime_asr.h"#include <string>using namespace liteav;// 1. 实现监听器class MyASRListener : public TXRealtimeASRListener { public: void onRealtimeASRStarted(const char* voiceId) override { // 转录会话已开启，voiceId 为识别会话 ID } void onReceiveRealtimeASRMessage(const TXRealtimeASRMessage& message) override { if (message.isCompleted) { // 稳态结果：某句话已说完，sourceText 为最终识别文本 } else { // 中间结果：正在识别中，sourceText 为实时暂存文本 } // 可获取该消息在音频流中的时间区间（毫秒），-1 表示未知 int start = message.startTime; int end = message.endTime; } void onRealtimeASRStopped() override { // 转录正常停止 } void onRealtimeASRError(int errorCode, const char* errorMsg) override { // 转录出错，errorCode 非 0 表示异常 } void onRealtimeASRVolume(int volume) override { // 实时音量，volume 取值 [0, 100] }};void RunASR() { // 2. 创建实例 ITXRealtimeASR* asr = TXRealtimeASRCreate(); // 3. 设置监听器（注意保持监听器对象在会话期间有效） static MyASRListener listener; asr->addListener(&listener); // 4. 配置参数并启动 TXRealtimeASRParams params; params.sdkAppId = "1400000000"; // TRTC 应用 ID params.userSig = "your_user_sig"; // 服务端下发的用户签名 params.voiceId = "uuid-xxxx-xxxx-xxxx"; // 识别会话 ID，建议每次调用重新生成 UUID params.sourceLanguage = "zh"; // 识别语言，"zh"/"en"，留空为自动识别 params.enableCustomCapture = false; // 是否启用自定义音频采集 asr->startRealtimeASR(params); // 5.（可选）自定义采集模式：开启后自行采集并送入 PCM 音频 // const int16_t pcm[160]; // 16k、单声道、16bit 采样 // asr->feedPcmData(pcm, 160, 16000, 1); // 6. 停止转录（正常停止后回调 onRealtimeASRStopped） asr->stopRealtimeASR(); // 7. 移除监听并销毁 asr->removeListener(&listener); TXRealtimeASRDestroy(asr);}
九、工厂函数
| 函数 | 说明 |
| liteav::ITXRealtimeASR* TXRealtimeASRCreate() | 创建实例。 |
| void TXRealtimeASRDestroy(liteav::ITXRealtimeASR* instance) | 销毁实例，释放资源。 |
十、接口 ITXRealtimeASR
| 方法 | 说明 |
| void addListener(TXRealtimeASRListener* listener) | 添加回调监听器；同一监听器重复添加可能触发多次回调。 |
| void removeListener(TXRealtimeASRListener* listener) | 移除回调监听器。 |
| void startRealtimeASR(const TXRealtimeASRParams& params) | 启动实时语音转写会话。 |
| void stopRealtimeASR() | 停止实时转写，等后端算完后回调 onRealtimeASRStopped 或 onRealtimeASRError。 |
| void feedPcmData(const int16_t* data, size_t length, uint32_t sampleRate, uint32_t channels) | 自定义采集时送入 PCM 音频数据。data：16bit PCM 采样数据；length：采样点个数（int16_t 元素数量，非字节数）；sampleRate：采样率（Hz）；channels：通道数。 |
| const char* callExperimentalAPI(const char* jsonStr) | 实验性 API 调用，入参为 JSON 字符串，返回字符串。 |
十一、监听器 TXRealtimeASRListener
注意：说明：
注意：所有回调均已切换到 UI 线程，调用方无需关心线程安全。
| 回调 | 说明 |
| void onRealtimeASRStarted(const char* voiceId) | 实时转录开启成功的回调。voiceId 为识别会话 ID。 |
| void onReceiveRealtimeASRMessage(const TXRealtimeASRMessage& message) | 收到实时转录消息的回调，message 包含转录文本和完成状态。 |
| void onRealtimeASRStopped() | 实时转录停止的回调（正常停止）。 |
| void onRealtimeASRError(int errorCode, const char* errorMsg) | 实时转录出错的回调。errorCode 非 0 表示异常，errorMsg 为错误信息。 |
| void onRealtimeASRVolume(int volume) | 实时音量回调。volume 为音量等级，取值范围 [0, 100]。 |
十二、TXRealtimeASRParams（启动参数）
| 字段 | 类型 | 默认值 | 说明 |
| sdkAppId | const char* | nullptr | TRTC 应用 ID。 |
| userSig | const char* | nullptr | TRTC 用户签名。 |
| voiceId | const char* | nullptr | 识别会话 ID，建议每次调用时重新生成 UUID 传入。 |
| sourceLanguage | const char* | nullptr | 识别语言，例如 "zh"、"en"，留空即为自动识别。 |
| enableCustomCapture | bool | false | 是否启用自定义音频采集；为 true 时须通过 feedPcmData 送入音频。 |
十三、TXRealtimeASRMessage（转录消息）
| 字段 | 类型 | 默认值 | 说明 |
| segmentId | const char* | nullptr | 消息段的唯一标识 ID。 |
| sourceText | const char* | nullptr | 识别出的源语言文本（对应协议 voice_text_str）。 |
| isCompleted | bool | false | 转录是否结束：false=进行中（中间结果），true=已说完（稳态结果）。 |
| speakerId | int | -1 | 说话人 ID，-1 表示未知。 |
| startTime | int | -1 | 本消息在整个音频流中的起始时间（毫秒），-1 表示未知。 |
| endTime | int | -1 | 本消息在整个音频流中的结束时间（毫秒），-1 表示未知。 |
注意：说明：
注意：TXRealtimeASRParams 中的 const char* 字段在 startRealtimeASR 调用期间须保持有效；TXRealtimeASRMessage 中的字符串指针仅在回调内有效，异步使用请自行拷贝。
十四、实验性 API
callExperimentalAPI(const char* jsonStr) 用于调用实验性 / 扩展能力。入参为 JSON 字符串，返回字符串。格式：
{ "api": "<接口名>", "params": { … } }
十五、setExtraParams
引擎参数配置，用于追加自定义的 ASR 引擎参数与降噪策略。
输入参数（params 字段）：
| 参数 | 类型 | 说明 |
| extraRequestParams | string | Query String 格式的引擎参数，整体追加到 ASR URL 末尾。 |
| clientDenoiseStrategy | int | 降噪策略：0=关闭，1=录音笔场景，2=AI 对话场景，3=语音输入场景（默认）。 |
extraRequestParams 可用键名：
| 键名 | 说明 | 默认值 |
| engine_model_type | 引擎模型类型，如 "bigmodel"、"16k_zh_en"。 | bigmodel |
| needvad | 是否开启 VAD：0=关闭，1=开启。 | 1 |
| filter_dirty | 脏词过滤：0=不过滤，1=过滤，2=替换为 *。 | 0 |
| filter_modal | 语气词过滤：0=不过滤，1=部分，2=严格。 | 0 |
| filter_punc | 句末标点过滤：0=不过滤，1=过滤。 | 0 |
| convert_num_mode | 数字转换：0=不转，1=智能转换，3=数学转换。 | 1 |
| vad_silence_time | VAD 静音断句阈值（ms），范围 240-1000。 | 1000 |
| max_speak_time | 强制断句时间（ms），范围 5000-90000。 | 60000 |
参数优先级规则：
1. SDK 内部生成的参数（timestamp、expired、signature、nonce 等）不可被覆盖。
2. 启动参数中的显性字段（sdkAppId、userSig、voiceId、sourceLanguage）不可被覆盖。
3. extraRequestParams 中的其余键——自由扩展，整体追加到 URL 末尾。
注意：说明：
示例：
const char* json = R"({"api":"setExtraParams","params":{"extraRequestParams":"engine_model_type=bigmodel","clientDenoiseStrategy":1}})";asr->callExperimentalAPI(json);
十六、最佳实践与注意事项
1. 鉴权信息：userSig 应由服务端生成后下发，切勿将生成密钥硬编码到客户端。
2. voiceId 唯一性：每次调用 startRealtimeASR 建议重新生成新的 UUID 作为 voiceId。
3. 字符串生命周期：TXRealtimeASRParams 中的 const char* 字段在启动调用期间须保持有效；回调中的字符串指针仅在回调内有效。
4. 自定义采集：enableCustomCapture = true 时须主动调用 feedPcmData 送入 16bit PCM 数据，并保证 sampleRate、channels 与数据一致。
5. 中间结果与稳态结果：isCompleted = false 的文本会持续更新，仅在 isCompleted = true 时该段识别才最终确定。
6. callExperimentalAPI 返回值：返回的 const char* 由 SDK 内部持有，请在下次调用前使用或拷贝。
7. 生命周期：销毁前先 stopRealtimeASR() 并 removeListener，再调用 TXRealtimeASRDestroy。