更新记录

1.0.2（2026-04-09）

• 导出结构调整：移除 utssdk/index.uts，改为各平台 index.uts 直接显式导出
• 文档与示例优化：补充 API / 事件 / 错误码说明，统一示例写法
• 错误信息完善：补齐 TTS / ISE 相关错误码文案

1.0.1（2026-02-27）

• 文档增强：补充“接入方使用自有 AppID”接入步骤（Android/iOS SDK 替换路径、10407 排查、自定义基座要求）
• 文档说明：明确 SDK 下载入口使用旧版 dispatcher（https://www.xfyun.cn/sdk/dispatcher）
• 发布信息：版本号更新为 1.0.1
• 本次无 API 变更

1.0.0（2026-01-27）

• 初始版本：支持 App-Android / App-iOS 的在线 IAT/TTS/ISE
• 提供 onXxx/offXxx 事件回调注册方式

平台兼容性

uni-app(4.87)

uni-app x(4.87)

hans-xf-speech

讯飞语音（IAT 听写 / TTS 合成 / ISE 评测）UTS 插件。

支持：

• App-Android（Android 5.0+）
• App-iOS
• uni-app x / uni-app（App 端）

当前不支持：

• Web
• 小程序
• 鸿蒙

说明：鸿蒙目录当前是占位实现，调用会返回 9090001（not implemented on this platform），不算可用支持。

获取 AppID

在讯飞开放平台创建应用，开通所需能力后获得 AppID。

SDK 下载入口（重要）：

• 请使用旧版 dispatcher：https://www.xfyun.cn/sdk/dispatcher
• 当前插件验证通过的是旧版 dispatcher 下载包，新版下载入口的包形态暂不作为本文档基准

安装

将本插件放到项目 uni_modules/hans-xf-speech。

从插件市场安装时，也会自动落到这个目录。

给其他 AppID 接入（必须）

本插件默认内置的是示例 SDK。接入方必须同时完成下面两件事：

1. 业务代码里 xfInit 传入自己的 appId
2. 用该 appId 对应下载的 SDK 二进制替换插件内置 SDK

只改 appId 或只换 SDK 都不行，常见报错是 10407 用户校验失败。

1) 下载接入方自己的 SDK

• Android / iOS 都从旧版 dispatcher 下载：https://www.xfyun.cn/sdk/dispatcher
• 下载包建议按 appid 归档保存，避免团队内混用

2) 替换 Android SDK 文件

从 Android SDK 根目录 libs/ 复制（不要用 sample 目录）：

• libs/Msc.jar
• libs/arm64-v8a/libmsc.so
• libs/armeabi-v7a/libmsc.so

覆盖到项目：

• uni_modules/hans-xf-speech/utssdk/app-android/libs/Msc.jar
• uni_modules/hans-xf-speech/utssdk/app-android/libs/arm64-v8a/libmsc.so
• uni_modules/hans-xf-speech/utssdk/app-android/libs/armeabi-v7a/libmsc.so

3) 替换 iOS SDK 文件

从 iOS SDK 复制：

• lib/iflyMSC.framework/

覆盖到项目：

• uni_modules/hans-xf-speech/utssdk/app-ios/Frameworks/iflyMSC.framework/

4) 初始化时传入接入方 AppID

import {
    xfInit,
    XfInitOptions,
} from '@/uni_modules/hans-xf-speech'

const initOptions : XfInitOptions = {
    appId: '接入方自己的AppID',
    logEnabled: true,
}

xfInit(initOptions)

5) 自检（建议）

• xfInit 成功后调用一次 iatStart 做冒烟
• 若出现 10407，优先检查：
  1. xfInit 的 appId 是否正确
  2. Android/iOS SDK 是否确实替换为同一 appId 下载包
  3. Android 是否误用了 sample 下的 so
  4. 是否仍在使用旧的自定义基座或缓存产物（清理后重编）

快速开始

import {
    xfInit,
    destroy,
    onIatResult,
    onIatError,
    onTtsProgress,
    onIseResult,
    iatStart,
    iatStop,
    ttsSpeak,
    ttsStop,
    iseStart,
    iseStop,
    XfInitOptions,
    IatStartOptions,
    IatStopOptions,
    TtsSpeakOptions,
    TtsStopOptions,
    IseStartOptions,
    IseStopOptions,
    IatResultEvent,
    XfSpeechFail,
    TtsProgressEvent,
    IseResultEvent,
} from '@/uni_modules/hans-xf-speech'

const initOptions : XfInitOptions = {
    appId: '你的AppID',
    logEnabled: true,
    success: (res) => console.log('init ok', res),
    fail: (err) => console.error('init fail', err),
}

xfInit(initOptions)

onIatResult((e : IatResultEvent) => {
    console.log('iat text', e.text)
    console.log('iat raw', e.raw)
    console.log('iat isLast', e.isLast)
})

onIatError((err : XfSpeechFail) => {
    console.error('iat error', err)
})

onTtsProgress((e : TtsProgressEvent) => {
    console.log('tts progress', e.progress, e.beginPos, e.endPos)
})

onIseResult((e : IseResultEvent) => {
    console.log('ise raw', e.raw)
})

const iatStartOptions : IatStartOptions = {
    domain: 'iat',
    language: 'zh_cn',
    accent: 'mandarin',
    asrPtt: true,
}

const iatSessionId = iatStart(iatStartOptions)

const ttsSpeakOptions : TtsSpeakOptions = {
    text: '你好，我是讯飞语音。',
    voiceName: 'xiaoyan',
}

const ttsSessionId = ttsSpeak(ttsSpeakOptions)

const iseStartOptions : IseStartOptions = {
    text: '你好',
    category: 'read_word',
}

const iseSessionId = iseStart(iseStartOptions)

// 根据业务时机停止
const iatStopOptions : IatStopOptions = { sessionId: iatSessionId }
const ttsStopOptions : TtsStopOptions = { sessionId: ttsSessionId }
const iseStopOptions : IseStopOptions = { sessionId: iseSessionId }

iatStop(iatStopOptions)
ttsStop(ttsStopOptions)
iseStop(iseStopOptions)

// 页面销毁时建议解绑监听并销毁实例
// destroy()

使用约定

1) 推荐统一使用 xfInit

• Android 同时导出了 init 和 xfInit
• iOS 仅导出 xfInit
• 为了跨平台一致，建议业务侧统一使用 xfInit

2) sessionId 是会话标识，不是多实例路由句柄

• iatStart / ttsSpeak / iseStart 成功时都会返回一个递增的 sessionId
• 当前实现里，IAT、TTS、ISE 各自都只维护一个活跃 native 实例
• 同类能力再次 start/speak 时，会覆盖前一次活跃会话
• stop/cancel 里的 sessionId 目前主要用于业务对账和日志记录，内部不会按多个实例做路由
• 建议始终传最近一次返回的 sessionId

3) onXxx/offXxx 是单槽位监听

• 每个事件类型只保存一个回调
• 再次调用 onIatResult(fn) 会覆盖前一个 fn
• offIatResult() / offTtsProgress() 这类方法不需要传原回调，调用即清空

4) destroy() 会清空监听

• destroy() 会释放 native 实例
• 同时会清空已经注册的所有 onXxx 监听
• 如果你先 destroy() 再重新 xfInit()，需要重新绑定监听

5) success 只表示“已成功发起”，不表示“流程已完成”

• iatStart / ttsSpeak / iseStart 的 success，表示 native 已接受启动请求
• 真正结束要看对应的 onIatResult(isLast=true)、onTtsEnd、onIseResult(isLast=true) 或错误回调

API 概览

初始化与销毁：

• xfInit({ appId, logEnabled?, success?, fail?, complete? })
• setLogEnabled({ enabled, success?, fail?, complete? })
• destroy()

IAT（听写）：

• iatStart(options) => sessionId
• iatStop({ sessionId })
• iatCancel({ sessionId })
• 事件：onIatBegin/onIatEnd/onIatVolume/onIatResult/onIatError + 对应 off...

TTS（合成）：

• ttsSpeak(options) => sessionId
• ttsStop({ sessionId })
• 事件：onTtsBegin/onTtsProgress/onTtsEnd/onTtsError + 对应 off...

ISE（评测）：

• iseStart(options) => sessionId
• iseStop({ sessionId })
• iseCancel({ sessionId })
• 事件：onIseBegin/onIseEnd/onIseVolume/onIseResult/onIseError + 对应 off...

返回约定：

• iatStart / ttsSpeak / iseStart 失败时返回 0
• 成功时返回的 sessionId，与 success(res) 里的 res.sessionId 一致

API 详细说明

xfInit(options)

用于初始化讯飞 SDK，调用其他能力前必须先执行。

说明：

• appId 不能为空，否则返回 9020002
• Android 在相同 appId 已初始化时会跳过重复初始化并直接成功返回
• Android 在切换到新 appId 时会先 destroy() 再重新初始化

setLogEnabled(options)

动态切换插件日志和 native SDK 日志。

destroy()

释放插件内部持有的 IAT / TTS / ISE native 实例，并清空全部监听。

IAT（语音听写）

iatStart(options)

开始一次听写会话。

说明：

• 常见中文在线听写组合为：domain: 'iat'、language: 'zh_cn'、accent: 'mandarin'
• 其他取值是否可用，取决于讯飞控制台开通能力和所用 SDK 能力包
• 再次调用 iatStart 会覆盖前一个活跃听写会话

iatStop({ sessionId })

正常结束当前听写。

说明：

• stop 是正常收尾，通常仍可能继续收到最终结果和结束事件
• 建议在业务侧保留最近一次 sessionId 并原样传回

iatCancel({ sessionId })

取消当前听写。

说明：

• cancel 用于立即中断
• 取消后不保证还能收到最终结果

IAT 事件

onIatBegin(callback)

开始录音时触发，回调参数：

onIatBegin((event : IatBeginEvent) => {
    console.log(event.sessionId)
})

onIatEnd(callback)

结束录音时触发，回调参数：

onIatEnd((event : IatEndEvent) => {
    console.log(event.sessionId)
})

onIatVolume(callback)

音量变化时触发，回调参数：

onIatVolume((event : IatVolumeEvent) => {
    console.log(event.sessionId, event.volume)
})

onIatResult(callback)

识别结果回调，回调参数：

onIatResult((event : IatResultEvent) => {
    console.log(event.sessionId)
    console.log(event.text)
    console.log(event.isLast)
    console.log(event.raw)
})

字段说明：

• text：插件根据 SDK 增量结果拼接后的当前完整文本
• isLast：是否最后一条结果
• raw：讯飞 SDK 原始结果字符串，当前实现为 JSON 字符串

onIatError(callback)

错误回调，参数为错误对象。

onIatError((error : XfSpeechFail) => {
    console.error(error.errCode, error.errMsg, error.data)
})

常见场景：

• 未初始化直接调用，返回 9020001
• 启动失败，返回 9030001
• 原始 JSON 解析失败，返回 9030004

TTS（语音合成）

ttsSpeak(options)

开始一次语音合成。

说明：

• text 不能为空，否则返回 9020002
• 如果当前已经在播报，新一次 ttsSpeak 会先停止上一段播报，再开始新的播报
• voiceName、speed、volume、pitch 当前没有插件侧兜底默认值，省略时沿用讯飞 SDK 默认行为

ttsStop({ sessionId })

停止当前播报。

TTS 事件

onTtsBegin(callback)

onTtsBegin((event : TtsBeginEvent) => {
    console.log(event.sessionId)
})

onTtsProgress(callback)

onTtsProgress((event : TtsProgressEvent) => {
    console.log(event.sessionId)
    console.log(event.progress, event.beginPos, event.endPos)
})

字段说明：

• progress：当前播放进度百分比
• beginPos：当前片段起始字符位置
• endPos：当前片段结束字符位置

onTtsEnd(callback)

onTtsEnd((event : TtsEndEvent) => {
    console.log(event.sessionId)
})

onTtsError(callback)

错误回调，参数为错误对象。

onTtsError((error : XfSpeechFail) => {
    console.error(error.errCode, error.errMsg, error.data)
})

ISE（语音评测）

iseStart(options)

开始一次语音评测。

说明：

• text 不能为空，否则返回 9020002
• 常见 category 包括 read_word、read_sentence，具体以讯飞评测能力文档为准
• 当前插件不负责解析评测 XML 或其他原始结构，只透出 raw

iseStop({ sessionId })

正常结束当前评测。

iseCancel({ sessionId })

取消当前评测。

ISE 事件

onIseBegin(callback)

onIseBegin((event : IseBeginEvent) => {
    console.log(event.sessionId)
})

onIseEnd(callback)

onIseEnd((event : IseEndEvent) => {
    console.log(event.sessionId)
})

onIseVolume(callback)

onIseVolume((event : IseVolumeEvent) => {
    console.log(event.sessionId, event.volume)
})

onIseResult(callback)

onIseResult((event : IseResultEvent) => {
    console.log(event.sessionId)
    console.log(event.raw)
    console.log(event.isLast)
})

字段说明：

• raw：讯飞 SDK 原始评测结果字符串
• iOS 当前明确配置为 XML 结果
• Android 当前直接透出 SDK resultString，业务侧应按原始内容自行解析，不要假设插件已经做字段标准化

onIseError(callback)

错误回调，参数为错误对象。

onIseError((error : XfSpeechFail) => {
    console.error(error.errCode, error.errMsg, error.data)
})

错误对象

所有 fail 和 onXxxError 都会收到同一结构的错误对象：

{
    errSubject: 'hans-xf-speech',
    errCode: 9030001,
    errMsg: 'iat start failed',
    data: {
        nativeCode: 20006,
        nativeDescription: '启动录音失败',
    },
}

字段说明：

• errSubject：固定为 hans-xf-speech
• errCode：插件错误码
• errMsg：插件错误描述
• data：附加信息，可包含 field、nativeCode、nativeDescription、message、raw

错误码

平台差异

Android

• 导出 init 和 xfInit，推荐统一使用 xfInit
• IAT 支持 engineType、ptt、asrPtt
• TTS 支持 engineType
• IAT / TTS 省略 engineType 时，内部使用云端引擎默认值

iOS

• 仅导出 xfInit
• IAT 不透出 engineType
• TTS 不透出 engineType
• IAT 的 asrPtt 省略时会按 false 处理
• ISE 结果当前明确设置为 XML 字符串

鸿蒙

• 当前为占位实现
• 初始化、启动、停止等调用都会返回 9090001
• 不建议在生产环境按已支持能力接入

权限与常见问题

Android

• 需要权限：RECORD_AUDIO、INTERNET、ACCESS_NETWORK_STATE
• 运行时需向系统申请麦克风权限，否则可能出现 “启动录音失败（nativeCode=20006）”

iOS

• 需在 Info.plist 声明麦克风用途：NSMicrophoneUsageDescription
• 插件已提供默认文案，可按需修改

自定义基座

• UTS 原生插件需使用“自定义基座/自定义调试基座”运行
• 标准基座下常见现象是“插件未加载”或“方法调用失败”

监听没有回调

优先检查：

• 是否在 xfInit 成功后再调用 start/speak
• 页面是否已经调用过 destroy()，导致监听被清空
• 是否重复调用 onXxx，把之前的回调覆盖掉了
• 是否在页面卸载时被 offXxx() 清掉了

10407 用户校验失败

优先检查：

• xfInit 传入的 appId 是否为接入方自己的 AppID
• Android / iOS SDK 二进制是否已整体替换为同一 appId 下载的版本
• 是否仍在运行旧基座或缓存产物