文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>口语评测（新版）>SDK 文档>客户端 SDK>HarmonyOS NEXT 说明

HarmonyOS NEXT 说明

最近更新时间：2025-08-13 16:11:32

我的收藏

本页目录：

接入准备

SDK 获取

口语评测 HarmonyOS NEXT SDK 以及 Demo 的下载地址。点击下载 SDK。

接入须知

开发者在调用前请先查看 智聆口语评测（新版）相关接口，了解接口的使用要求和使用步骤。
该接口需要手机能够连接网络（3G、4G、5G 或 Wi-Fi 等）。
运行 Demo 必须设置 AppID、SecretID、SecretKey，您可前往 API 密钥管理 页面进行获取。
如果需要使用临时密钥的方式接入，具体流程可以参考 临时密钥兑换流程。

SDK 导入

1. 下载并解压 HarmonyOS NEXT SDK 压缩包，压缩包包含 demo、sdk 和 doc，其中 sdk/qcloudsoe_v1.x.x.har 为口语评测的 SDK。
2. 在工程中添加依赖库，oh-package.jsons 中添加以下依赖：
"dependencies": {
    "QCloudSOE": "file:../../sdk/qcloudsoe_v1.0.0_96b6073.har"
  }
3. 请根据实际路径替换配置。

快速接入

以下为 demo 中的代码片段，完整代码请参考 sdk/demo 工程。

配置评测任务

配置评测任务相关参数：
let builder = new QCloud.SOE.Builder
builder.appID = this._app_id
builder.secretID = this._secret_id
builder.secretKey = this._secret_key
builder.token = this._token
// SDK参数配置
builder.vadVolume = this._vad_volume
builder.vadInterval = this._vad_interval
// API 参数配置
builder.setApiParam(QCloud.SOE.kServerEngineType, this._server_engine_type)
builder.setApiParam(QCloud.SOE.kEvalMode, this._eval_mode)
builder.setApiParam(QCloud.SOE.kScoreCoeff, this._score_coeff)
builder.setApiParam(QCloud.SOE.kRefText, this._ref_text)
builder.setApiParam(QCloud.SOE.kSentenceInfoEnabled, this._sentence_info_enable)

启动评测任务

使用上面的 Builder 可以创建并启动评测任务：
this._controller = builder.build(
      this._source, {
      onData: (data) => {
        this._logger.log(data)
      },
      onVolume: (db) => {
        this._volume = db
      },
      onVad: (val) => {
        this._vad = val
        console.log(`vad ${val}`)
      },
      onLogger: (level, message) => {
        this._logger.log(message)
      },
    })

停止评测任务

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

主要接口类和方法说明

Builder 类说明

Builder 用于创建评测任务。

方法

1. setApiParam(key: string, value: string | number | null)
设置请求后台 Websocket 时的参数，后台支持参数请参见 智聆口语评测（新版）相关接口。
名称
类型
描述
key
string
请求后台的参数名称
value
string|number|null
请求后台的参数值，null 时将删除已设置的参数，number 会转为 string 后设置
2. getApiParam(key: string): string | 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的倍数，不建议更改此参数
VadVolume
number
静音检测音量阈值
VadInterval
number
静音检测时长阈值
LoggerLevel
LoggerLevel
日志等级，日志回调只会返回大于该等级的日志
SaveDataPath
string
保存音频数据路径，路径为空不生效，否则将会存储数据源读取到的音频数据到该路径

Controller 类说明

Controller 用于控制评测任务的流程。

方法

1. stop(): void
停止评测任务，调用此方法会向后台发送停止评测的消息，成功停止后 task 会结束。

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

属性

名称
类型
描述
task
Promise<void>
评测任务，评测任务正常结束则此 Promise 正常返回,否则抛出异常
voice_id
string
连接成功后的 voiceid，否则为空字符

Listener 类说明

Listener 类用于接收评测过程中的信息。

属性

名称
类型
描述
onData?
(data: string) => void
收到后台 websocket 的消息后回调该方法
onParseData
(data: Server.Chunk) => void
解析后服务端的数据，数据结构参考 智聆口语评测（新版）相关接口 中接口调用流程的返回结构说明
onLogger?
(level: LoggerLevel, message: string) => void
日志回调，Builder 的 loggerLevel 会影响此回调的内容
onVad?
(value: boolean) => void
静音回调，静音检测为边缘触发，仅在 SDK 判断静音状态改变时回调，检测到静音为 false
onVolume?
(db: number) => void
音量回调，音量范围为0 - 120

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 时，此方法需返回ms *16 * 2长度的数据,此方法发生的异常会通过task抛出

错误码

评测任务抛出类型为 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
数据源返回的数据长度不符合要求
中国站
目录