文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>语音识别>SDK 文档>在线 SDK 文档>客户端 SDK>HarmonyOS NEXT>实时说话人分离

实时说话人分离

最近更新时间：2026-06-29 15:22:00

我的收藏

本页目录：

1. 接入准备

1.1 SDK 获取

实时说话人分离 Harmony SDK 以及 Demo 的下载地址: 接入 SDK 下载。

1.2 接入须知

开发者在调用前请先查看实时说话人分离的 接口说明，了解接口的使用要求和使用步骤。
该接口需要手机能够连接网络（3G、4G、5G 或 Wi-Fi 等）
运行 Demo 必须设置 AppID、SecretID、SecretKey，可在 API 密钥管理 中获取。

1.3 开发环境

添加实时说话人分离 SDK har
"dependencies": {
    "qcloudrealtimespeaksep": "file:../qcloudrealtimespeaksep.har"
}
注意：
需根据实际路径替换配置。

2. 快速接入

以下为 Demo 中的代码片段，完整代码请参考 SDK 交付包内的 Demo 工程。

2.1 配置识别任务

import { QCloud, SpeakSeparationBuilder } from 'qcloudrealtimespeaksep'
...
let builder: SpeakSeparationBuilder = new SpeakSeparationBuilder()
builder.appID = this._app_id
builder.secretID = this._secret_id
builder.secretKey = this._secret_key
builder.token = this._token

2.2 启动识别任务

使用上面的 Builder 可以创建并启动识别任务。说话人分离场景下，识别结果通过 onData 回调返回包含说话人信息的 JSON 数据。
// 设置引擎模型类型为说话人分离专用模型
builder.setApiParam(QCloud.RealTime.kEngineModelType, '16k_zh_en_speaker')

this._controller = builder.build(
      this._source, {
      onData: (data: string) => {
        console.log(`----- ${data}`)
        // 解析说话人分离结果
        let resp = JSON.parse(data)
        if (resp.code == 0 && resp.sentences && resp.sentences.sentence_list) {
          for (let sentence of resp.sentences.sentence_list) {
            // sentence.speaker_id: 说话人ID
            // sentence.sentence: 识别文本
            // sentence.sentence_type: 0=非稳态(中间结果), 1=稳态(最终结果)
            // sentence.start_time: 开始时间(ms)
            // sentence.end_time: 结束时间(ms)
            console.log(`[Speaker${sentence.speaker_id}] ${sentence.sentence}`)
          }
        }
      },
      onSilence: () => {
        this._controller?.cancel()
        console.log(`----- silence`)
      },
      onVolume: (db) => {
        this._volume = db
      },
      onLogger(level, message) {
        console.log(`${message}`)
      },
    })

2.3 停止识别任务

停止识别任务可以通过控制器的 stop 方法停止。
this._controller!.stop()
当数据源的 empty 返回 true 时识别也会停止。

3. 主要接口类和方法说明

3.1 SpeakSeparationBuilder 类说明

SpeakSeparationBuilder 继承自QCloud.RealTime.Builder，用于创建说话人分离识别任务。

方法
1. setApiParam(key: string, value: string | number | null): SpeakSeparationBuilder
设置请求后台 WebSocket 时的参数，后台支持参数请参考 实时说话人分离（WebSocket）。
名称
类型
描述
key
string
请求后台的参数名称
value
string|number|null
请求后台的参数值，null 时将删除已设置的参数，number 会转为 string 后设置
说明：
返回 SpeakSeparationBuilder 实例自身，支持链式调用。

2. getApiParam(key: string): string | number | null
获取已设置的请求参数。
名称
类型
描述
key
string
参数名称
3. build(source: DataSource, listener: Listener): Controller
创建并启动识别任务同时返回识别任务控制器。

属性
名称
类型
描述
appID
string
腾讯云 AppID
secretID
string
腾讯云临时 SecretId
secretKey
string
腾讯云临时 SecretKey
token
string
腾讯云临时 token，为空字符串时表示不使用临时授权，临时授权参考 获取联合身份临时访问凭证
slice
number
分片时间，单位 ms，开启 opus 时必须为40的倍数，不建议更改此参数
enableOpus
boolean
开启 opus 编码
enableSilence
boolean
开启静音检测，开启后识别到静音后会触发一次静音回调，不会停止任务
enableDetectVolume
boolean
开启音量检测，开启后会通过音量回调返回当前音量
silenceTimeout
number
静音检测时长，开启静音检测后生效
loggerLevel
LoggerLevel
日志等级,日志回调只会返回大于该等级的日志
saveDataPath
string
保存音频数据路径,路径为空不生效,否则将会存储数据源读取到的音频数据到该路径
host
string
自定义 WebSocket 连接的 host 地址,为空字符串时则使用默认域名

3.2 Controller 类说明

Controller 用于控制识别任务的流程。

属性
名称
类型
描述
task
Promise<void>
识别任务,识别任务正常结束则此 Promise 正常返回，否则抛出异常
voice_id
string
连接成功后的 voiceid，否则为空字符
方法
1. stop(): void
停止识别任务，调用此方法会向后台发送停止识别的消息,成功停止后 task 会结束。

2. cancel(): void
取消识别任务，调用此方法会取消当前识别任务，成功取消后 task 会抛出 SDKErrorImpl 类型的异常，且此异常的 code 为 CANCEL_ERROR。

3. writeContent(content: string): void
在识别过程中向服务端发送一条 string 类型的自定义文本消息（透传业务上下文/控制信令，JSON 格式，详情参考交付 Demo 源码）。消息作为 WebSocket 文本帧透传给服务端，不参与音频通道的处理。
名称
类型
描述
content
string
要发送的上下文
调用条件： 仅在合法识别中状态下可调用：
WebSocket 已建立且首个携带 voice_id 的响应已下发
调用方尚未调用 stop()/cancel()
任务尚未因服务端 final 或错误而结束

异常说明： 校验失败会同步抛出 SDKError：
PARAMETER_ERROR: content 为空
NETWORK_ERROR: WebSocket 未就绪、任务已停止/取消/结束/失败，或底层 send 失败

3.3 Listener 类说明

Listener 类用于接收识别过程中的信息。
注意：
在说话人分离场景下，识别结果统一通过 onData 返回。
属性
名称
类型
描述
onData?
(data: string) => void
收到后台 WebSocket 的消息后回调该方法，返回包含说话人分离信息的 JSON 数据
onLogger?
(level: LoggerLevel, message: string) => void
日志回调，Builder 的 loggerLevel 会影响此回调的内容
onSilence?
() => void
静音回调，开启 Builder 的 enableSilence 后检测到静音后回调
onVolume?
(db: number) => void
音量回调，开启 Builder 的 enableDetectVolume 后回调
onData 回调数据格式
{
  "code": 0,
  "message": "success",
  "voice_id": "xxx",
  "sentences": {
    "sentence_list": [
      {
        "sentence": "识别的文本内容",
        "sentence_type": 1,
        "sentence_id": 0,
        "speaker_id": 0,
        "start_time": 0,
        "end_time": 3000
      }
    ]
  }
}

字段说明：
字段名
类型
描述
sentence
string
识别的文本内容
sentence_type
number
0=非稳态（中间结果，可能被后续结果修正），1=稳态（最终结果，不会再改变）
sentence_id
number
句子序号
speaker_id
number
说话人 ID，用于区分不同说话人
start_time
number
句子开始时间（毫秒）
end_time
number
句子结束时间（毫秒）

3.4 DataSource 类说明

DataSource 类用来提供用于识别的音频数据。
属性
名称
类型
描述
voice_format
string
音频编码，目前仅支持 pcm，即数据类型为16000hz，16bit，小端的 pcm 数据流
empty
boolean
返回是否还有音频数据
start
() => Promise<void>
SDK 开始识别时会调用此方法，此方法发生的异常会通过 task 抛出
stop
() => Promise<void>
SDK 停止识别时会调用此方法，此方法发生的异常会通过 task 抛出
read
(ms: number) => Promise<ArrayBuffer>
SDK 读取音频数据，ms 为读取数据的时长，voice_format 为 pcm 时，此方法需返回40 *16 * 2长度的数据，此方法发生的异常会通过 task 抛出

4. 错误码

识别任务抛出类型为 SDKErrorImpl 时的错误码。
错误码
名称
描述
-1
UNKNOWN_ERROR
未知错误
1
NETWORK_ERROR
网络错误
2
SERVER_ERROR
服务端错误,详情通过 message 查看
3
SIGNATURE_ERROR
签名错误
4
PARAMETER_ERROR
参数错误，Builder 设置的参数无法创建识别任务
5
CANCEL_ERROR
取消错误，调用 cancel 方法取消任务时出现
6
CREATE_FILE_ERROR
创建文件失败
7
DATA_LENGTH_ERROR
数据源返回的数据长度不符合要求

5. 常见问题

5.1 speaker_context_id 的作用？

speaker_context_id 是服务端返回的声纹 ID（24h 内有效）。将上次返回的 ID 通过 setApiParam 传入下次识别任务，可使同一说话人的 ID 保持连续，适用于多轮对话场景。
// 将上次识别返回的 speaker_context_id 传入下次任务
builder.setApiParam('speaker_context_id', lastSpeakerContextId)

5.2 sentence_type=0 和 sentence_type=1 的区别？

sentence_type=0：中间态（非稳态），可能被后续结果修正，建议实时显示时使用灰色样式。
sentence_type=1：确定态（稳态），不会再改变，适合最终展示。

5.3 cancel 与 stop 的区别？

stop：自然结束当前识别任务，等待服务端返回最终结果后再关闭连接。
cancel：立即终止识别，不等待服务端返回任何结果，直接关闭 WebSocket 连接。
中国站