实时音视频 HarmonyOS SDK

一、功能简介

TXRealtimeASR 是实时流式语音转写引擎：

·实时流式识别：边说边出字，逐句返回识别结果。

·中间结果与稳态结果：通过 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）时使用的密钥串。

五、环境要求

六、引入 SDK

将 VoiceAI ASR SDK 引入项目工程，支持以下两种方式：

七、方式一：ohpm 仓库引入（推荐）

在工程根目录执行以下命令从 ohpm 仓库 添加依赖：

ohpm install @tencentcloud/liteavsdk_voiceai@13.6.0.237

或在 oh-package.json5 中声明依赖后执行同步：

{ "dependencies": { "@tencentcloud/liteavsdk_voiceai": "^13.6.0.237" }}

八、方式二：本地 HAR 引入

1. 下载 SDK，将 SDK 提供的 HAR 包（LiteAVSDK_VoiceAI_x.x.x.x.har）加入工程依赖。

2. 在 oh-package.json5 中声明依赖后执行同步。

九、导入 API

两种方式均通过如下方式导入 API：

import { TXRealtimeASR, TXRealtimeASRMessage, TXRealtimeASRParams, TXRealtimeASRListener } from 'path/to/tx_realtime_asr';

十、鉴权信息

启动转写前需要准备以下 TRTC 鉴权信息：

注意：关于 UserSig 的安全说明：

注意：UserSig 是用户身份的加密凭证。请勿在客户端硬编码密钥（SECRETKEY）计算 UserSig，密钥一旦泄露会导致云资源被盗用；生产环境应在业务服务端计算 UserSig，App 通过接口动态获取。

注意：UserSig 计算方式参考：

十一、权限声明

实时转写为在线服务，且必须采集麦克风音频，需在 module.json5 中同时声明网络权限与麦克风权限：

{ "requestPermissions": [ { "name": "ohos.permission.INTERNET" }, { "name": "ohos.permission.MICROPHONE" } ]}

注意：说明：

注意：ohos.permission.MICROPHONE 属于 user_grant 权限，除配置声明外，还需在运行时通过 requestPermissionsFromUser 向用户动态申请，用户授权后才能开始转写。

十二、快速开始

import { TXRealtimeASR, TXRealtimeASRMessage, TXRealtimeASRParams, TXRealtimeASRListener } from 'path/to/tx_realtime_asr';class ASRDemo { private asr: TXRealtimeASR | null = null; private listener: TXRealtimeASRListener = { onRealtimeASRStarted: (voiceId: string) => { // 转录会话已开启 }, onReceiveRealtimeASRMessage: (message: TXRealtimeASRMessage) => { if (message.isCompleted) { // 稳态结果：某句话已说完 } else { // 中间结果：正在识别中 } // 可获取该消息在音频流中的时间区间（毫秒），-1 表示未知 const start = message.startTime; const end = message.endTime; }, onRealtimeASRStopped: () => { // 转录正常停止 }, onRealtimeASRError: (errorCode: number, errorMsg: string) => { // 转录出错，errorCode 非 0 表示异常 }, onRealtimeASRVolume: (volume: number) => { // 实时音量，volume 取值 [0, 100] } }; startASR(): void { // 1. 创建实例 this.asr = new TXRealtimeASR(); // 2. 添加监听器 this.asr.addListener(this.listener); // 3. 配置参数并启动 const params: TXRealtimeASRParams = { sdkAppId: '1400000000', // TRTC 应用 ID userSig: 'your_user_sig', // 服务端下发的用户签名 voiceId: 'uuid-xxxx-xxxx-xxxx', // 识别会话 ID，建议每次调用重新生成 UUID sourceLanguage: 'zh', // 识别语言，"zh"/"en"，留空为自动识别 enableCustomCapture: false // 是否启用自定义音频采集 }; this.asr.startRealtimeASR(params); // 4.（可选）自定义采集模式：开启后自行采集并送入 PCM 音频 // const pcm: ArrayBuffer = …; // 16k、单声道、16bit 采样 // this.asr.feedPcmData(pcm, 16000, 1); } release(): void { if (this.asr) { this.asr.stopRealtimeASR(); this.asr.removeListener(this.listener); this.asr.destroy(); // 释放 native 资源，调用后本对象不可再用 this.asr = null; } }}

十五、构造

十六、销毁

十七、监听器管理

注意：说明：

注意：ArkTS 支持注册多个监听器。

十八、核心方法

十九、监听器 TXRealtimeASRListener

注意：说明：

注意：所有方法均为可选，按需实现。

21、TXRealtimeASRParams（启动参数）

22、TXRealtimeASRMessage（转录消息）

23、实验性 API

callExperimentalAPI(json: string) 用于调用实验性 / 扩展能力。入参为 JSON 字符串，返回字符串。格式：

{ "api": "<接口名>", "params": { … } }

24、setExtraParams

引擎参数配置，用于追加自定义的 ASR 引擎参数与降噪策略。

输入参数（params 字段）：

extraRequestParams 可用键名：

参数优先级规则：

1. SDK 内部生成的参数（timestamp、expired、signature、nonce 等）不可被覆盖。

2. 启动参数中的显性字段（sdkAppId、userSig、voiceId、sourceLanguage）不可被覆盖。

3. extraRequestParams 中的其余键——自由扩展，整体追加到 URL 末尾。

注意：说明：

示例：

const json: string = '{"api":"setExtraParams","params":{"extraRequestParams":"engine_model_type=bigmodel","clientDenoiseStrategy":1}}';this.asr?.callExperimentalAPI(json);

25、最佳实践与注意事项

1. 鉴权信息：userSig 应由服务端生成后下发，切勿将生成密钥硬编码到客户端。

2. voiceId 唯一性：每次调用 startRealtimeASR 建议重新生成新的 UUID 作为 voiceId。

3. 自定义采集：enableCustomCapture = true 时须主动调用 feedPcmData 送入 16bit PCM 数据，并保证 sampleRate、channels 与数据一致。

4. 中间结果与稳态结果：isCompleted = false 的文本会持续更新，仅在 isCompleted = true 时该段识别才最终确定。

5. 监听器管理：注册的 listener 对象引用须保持稳定，removeListener 需传入 addListener 时的同一对象引用。

6. 生命周期：使用完毕先 stopRealtimeASR()，再 removeListener 并置空实例引用。