帮你快速理解、总结文档立即下载
文档中心>实时音视频>AI 智能语音>语音识别（ASR）>实时语音识别>HarmonyOS SDK

HarmonyOS SDK

最近更新时间：2026-09-08 10:09:30
我的收藏

本页目录：

本文档面向 HarmonyOS 平台，介绍 VoiceAI ASR SDK 的接入方式与完整 API 说明。

功能简介

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

接入准备

开通服务

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

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

环境要求

项目
要求
系统
HarmonyOS NEXT / 对应 API 版本。
语言
ArkTS。
依赖
libliteavsdk_voiceai.so 及配套 ArkTS API。

引入 SDK

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

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

在工程根目录执行以下命令从 ohpm 仓库 添加依赖：
ohpm install @tencentcloud/liteavsdk_voiceai
或在 oh-package.json5 中声明依赖后执行同步：
{
  "dependencies": {
    "@tencentcloud/liteavsdk_voiceai": "^x.x.x"
  }
}

方式二：本地 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 鉴权信息：
参数
说明
sdkAppId
TRTC 应用 ID，可在腾讯云 TRTC 控制台获取。
voiceId
识别会话 ID，参与 userSig 计算，建议每次调用时重新生成 UUID 传入。
userSig
TRTC 用户签名，由 sdkAppId、SDK 密钥（即 sdkAppKey）、voiceId 三者计算得到。
关于 UserSig 的安全说明：
UserSig 是用户身份的加密凭证。请勿在客户端硬编码密钥（SECRETKEY）计算 UserSig，密钥一旦泄露会导致云资源被盗用；生产环境应在业务服务端计算 UserSig，App 通过接口动态获取。
UserSig 计算方式参考：
调试阶段：可参考 调试跑通阶段如何计算 UserSig，在本地临时计算 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;
    }
  }
}

API 参考

类 TXRealtimeASR

构造

方法
说明
constructor()
创建新实例，构造函数内完成原生资源分配。

销毁

方法
说明
destroy(): void
显式释放 native 资源（对齐其他平台的 destroy）。调用后本对象不可再使用，会同时清空已注册的监听器。使用完毕务必调用。

监听器管理

说明：
ArkTS 支持注册多个监听器。
方法
说明
addListener(listener: TXRealtimeASRListener): void
添加回调监听器。
removeListener(listener: TXRealtimeASRListener): void
移除之前添加的监听器。

核心方法

方法
说明
startRealtimeASR(params: TXRealtimeASRParams): void
启动实时语音转写会话。
stopRealtimeASR(): void
停止实时转录，等后端算完后回调 onRealtimeASRStopped 或 onRealtimeASRError。
feedPcmData(data: ArrayBuffer, sampleRate: number, channels: number): void
自定义采集时送入 PCM 音频数据。data：16bit PCM 字节数据；sampleRate：采样率（Hz）；channels：通道数。
callExperimentalAPI(json: string): string
实验性 API 调用，入参为 JSON 字符串，返回字符串。

监听器 TXRealtimeASRListener

说明：
所有方法均为可选，按需实现。
回调
说明
onRealtimeASRStarted?(voiceId: string): void
实时转录开启成功的回调。voiceId 为识别会话 ID。
onReceiveRealtimeASRMessage?(message: TXRealtimeASRMessage): void
收到实时转录消息的回调，message 包含转录文本和完成状态。
onRealtimeASRStopped?(): void
实时转录停止的回调（正常停止）。
onRealtimeASRError?(errorCode: number, errorMsg: string): void
实时转录出错的回调。errorCode 非 0 表示异常。
onRealtimeASRVolume?(volume: number): void
实时音量回调。volume 为音量等级，取值范围 [0, 100]。

参数与数据结构

TXRealtimeASRParams（启动参数）

字段
类型
说明
sdkAppId
string
TRTC 应用 ID。
userSig
string
TRTC 用户签名。
voiceId
string
识别会话 ID，建议每次调用时重新生成 UUID 传入。
sourceLanguage
string
识别语言，例如 "zh"、"en"，留空即为自动识别。
enableCustomCapture
boolean
是否启用自定义音频采集；为 true 时须通过 feedPcmData 送入音频。

TXRealtimeASRMessage（转录消息）

字段
类型
说明
segmentId
string
消息段的唯一标识 ID。
sourceText
string
识别出的源语言文本（对应协议 voice_text_str）。
isCompleted
boolean
转录是否结束：false=进行中（中间结果），true=已说完（稳态结果）。
speakerId
number
说话人 ID，-1 表示未知。
startTime
number
本消息在整个音频流中的起始时间（毫秒），-1 表示未知。
endTime
number
本消息在整个音频流中的结束时间（毫秒），-1 表示未知。

实验性 API

callExperimentalAPI(json: string) 用于调用实验性 / 扩展能力。入参为 JSON 字符串，返回字符串。格式：
{ "api": "<接口名>", "params": { ... } }

setExtraParams

引擎参数配置，用于追加自定义的 ASR 引擎参数与降噪策略。
输入参数（params 字段）：
参数
类型
说明
extraRequestParams
string
Query String 格式的引擎参数，整体追加到 ASR URL 末尾。
clientDenoiseStrategy
int
降噪策略：0=关闭（默认），1=开启（Percepnet）。
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 末尾。
说明：
若 extraRequestParams 中出现了第 1、2 类键，SDK 将忽略并输出 WARNING 日志。
若 extraRequestParams 中的键与默认字段同名（如 engine_model_type），默认字段被移除，以 extraRequestParams 中的值为准。
示例：
const json: string = '{"api":"setExtraParams","params":{"extraRequestParams":"engine_model_type=bigmodel","clientDenoiseStrategy":1}}';
this.asr?.callExperimentalAPI(json);

最佳实践与注意事项

鉴权信息：userSig 应由服务端生成后下发，切勿将生成密钥硬编码到客户端。
voiceId 唯一性：每次调用 startRealtimeASR 建议重新生成新的 UUID 作为 voiceId。
自定义采集：enableCustomCapture = true 时须主动调用 feedPcmData 送入 16bit PCM 数据，并保证 sampleRate、channels 与数据一致。
中间结果与稳态结果：isCompleted = false 的文本会持续更新，仅在 isCompleted = true 时该段识别才最终确定。
监听器管理：注册的 listener 对象引用须保持稳定，removeListener 需传入 addListener 时的同一对象引用。
生命周期：使用完毕应参考 快速开始 中的 release 方法，依次调用 stopRealtimeASR() 和 destroy() 来完整释放资源。之后再移除监听器并置空实例引用。
中国站