帮你快速理解、总结文档立即下载

Windows SDK

最近更新时间:2026-09-10 15:20:24
本文档已由 AI 辅助审校
我的收藏
本文档面向 Windows 平台,介绍 VoiceAI ASR SDK 的接入方式与完整 API 说明

功能简介

ITXRealtimeASR 是实时流式语音转写引擎:
实时流式识别:边说边出字,逐句返回识别结果。
中间结果与稳态结果:通过 isCompleted 区分进行中(中间结果)已说完(稳态结果)
自动 / 指定识别语言:支持 "zh"(中文)、"en"(英文)等,留空即为自动识别。
说话人区分:结果携带 speakerId-1 表示未知。
时间戳定位:结果携带 startTime / endTime,标识该消息在整个音频流中的起止位置(毫秒),-1 表示未知。
实时音量回调:通过 onRealtimeASRVolume 获取当前音量等级 [0, 100],可用于绘制音量波动效果。
自定义音频采集:可通过 enableCustomCapture 开启,自行采集 PCM 后调用 feedPcmData 送入引擎。
多监听器:通过 addListener / removeListener 注册多个回调监听器。

相比直接 WebSocket 接入的优势

相比业务方自行通过 WebSocket 对接 ASR 后端,SDK 在端侧完成音频前处理,提供以下开箱即用的能力:
端侧远场人声降噪:SDK 内置远场人声增强与降噪算法,识别过程中可消除远场人声、环境噪声的干扰,显著提升会议室、客厅、车载等远场场景的识别准确率,业务方无需自行搭建音频前处理链路。可通过实验性 API callExperimentalAPIsetExtraParams 配置 clientDenoiseStrategy 选择降噪策略(详细参见 实验性 API 中的 setExtraParams)。
声纹降噪(只识别指定人的声音):支持指定目标说话人,识别过程中只转写目标说话人的声音,自动忽略其他人的说话内容,适用于多人会议、车载多乘员等只听某一个人的场景。

接入准备

开通服务

登录 实时音视频控制台,单击创建应用 。如果您已经完成创建,可以跳过该操作。
在创建应用成功后,您可以在应用管理中获取到您的 SDKAppID 和 SDK 密钥。

SDKAppID: 控制台创建的实时音视频应用的唯一标识。
SDK 密钥:生成鉴权信息(UserSig)时使用的密钥串。

环境要求

项目
要求
操作系统
Windows 7 及以上(x86 / x64)。
编译器
支持 C++14 的 MSVC / Clang。
依赖
liteavsdk_voiceai 动态库(.dll + .lib 导入库)。
网络
实时转写为在线服务,需要可访问腾讯云的网络环境。

引入 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 用户签名,由 sdkAppIdsdkAppKeyvoiceId 三者计算得到。
关于 UserSig 的安全说明
UserSig 是用户身份的加密凭证。请勿在客户端硬编码密钥(SECRETKEY)计算 UserSig,密钥一旦泄露会导致云资源被盗用;生产环境应在业务服务端计算 UserSig,App 通过接口动态获取。
UserSig 计算方式参考:
调试阶段:可参考 调试跑通阶段如何计算 UserSig,在本地临时计算 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);
}

API 参考

工厂函数

函数
说明
liteav::ITXRealtimeASR* TXRealtimeASRCreate()
创建实例。
void TXRealtimeASRDestroy(liteav::ITXRealtimeASR* instance)
销毁实例,释放资源。

接口 ITXRealtimeASR

方法
说明
void addListener(TXRealtimeASRListener* listener)
添加回调监听器;同一监听器重复添加可能触发多次回调。
void removeListener(TXRealtimeASRListener* listener)
移除回调监听器。
void startRealtimeASR(const TXRealtimeASRParams& params)
启动实时语音转写会话。
void stopRealtimeASR()
停止实时转写,等后端算完后回调 onRealtimeASRStoppedonRealtimeASRError
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 内部生成的参数(timestampexpiredsignaturenonce 等)不可被覆盖。
2. 启动参数中的显性字段(sdkAppIduserSigvoiceIdsourceLanguage)不可被覆盖。
3. extraRequestParams 中的其余键——自由扩展,整体追加到 URL 末尾。
说明:
extraRequestParams 中出现了第 1、2 类键,SDK 将忽略并输出 WARNING 日志。
extraRequestParams 中的键与默认字段同名(如 engine_model_type),默认字段被移除,以 extraRequestParams 中的值为准。
示例:
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 数据,并保证 sampleRatechannels 与数据一致。
5. 中间结果与稳态结果isCompleted = false 的文本会持续更新,仅在 isCompleted = true 时该段识别才最终确定。
6. callExperimentalAPI 返回值:返回的 const char* 由 SDK 内部持有,请在下次调用前使用或拷贝。
7. 生命周期:销毁前先 stopRealtimeASR()removeListener,再调用 TXRealtimeASRDestroy