更新记录

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、小程序、鸿蒙（当前实现为占位，未接入）。

获取 AppID

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

SDK 下载入口（重要）：

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

安装

将本插件放到项目 uni_modules/hans-xf-speech（从插件市场安装也会自动放到该目录）。

给其他 AppID 接入（必须）

本插件是给接入方复用的。接入方必须同时完成下面两件事：

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 } from '@/uni_modules/hans-xf-speech'

xfInit({
    appId: '接入方自己的AppID',
    logEnabled: true,
})

5) 自检（建议）

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

快速开始

1) 初始化

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

xfInit({
    appId: '你的AppID',
    logEnabled: true,
    success: () => {},
    fail: (err) => console.error(err),
})

说明：

• logEnabled 默认 true
• 如需保持调用名为 init：import { xfInit as init } from '@/uni_modules/hans-xf-speech'

2) 监听回调（持续事件用 on/off）

import { onIatResult, onIatError, offIatResult, offIatError } from '@/uni_modules/hans-xf-speech'

onIatResult((e) => console.log(e.text))
onIatError((err) => console.error(err))

// 页面卸载时清理（建议在 onUnload/onHide 里做）
// offIatResult()
// offIatError()

3) IAT / TTS / ISE 调用

import { iatStart, iatStop, ttsSpeak, ttsStop, iseStart, iseStop } from '@/uni_modules/hans-xf-speech'

const iatSessionId = iatStart({})
iatStop({ sessionId: iatSessionId })

const ttsSessionId = ttsSpeak({ text: '你好' })
ttsStop({ sessionId: ttsSessionId })

const iseSessionId = iseStart({ text: '你好', category: 'read_word' })
iseStop({ sessionId: iseSessionId })

API 概览

初始化与销毁：

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

IAT（听写）：

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

TTS（合成）：

• ttsSpeak({ text, voiceName?, speed?, volume?, pitch?, engineType?, ... }) => sessionId
• ttsStop({ sessionId })
• 事件：onTtsBegin/onTtsProgress/onTtsEnd/onTtsError + 对应 off...

ISE（评测）：

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

权限与常见问题

Android：

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

iOS：

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

提示：

• UTS 原生插件需使用“自定义基座/自定义调试基座”运行；标准基座下会出现“插件未加载/方法调用失败”。