更新记录

1.0.0（2026-05-05）

1.0.0

平台兼容性

uni-app(4.25)

uni-app x(4.25)

其他

KGD-AliNui-Transcriber UTS 插件使用说明

1. 插件定位

kgd-ali-nui-transcriber 是一个 UTS API 插件，用于在 uni-app 和 uni-app x 中接入阿里云智能语音 Android 实时语音识别能力。

相较于旧的 App原生语言插件，当前版本：

• 走 UTS插件 发布分类
• 可兼容 uni-app 与 uni-app x
• 保留 Android 原生混编源码

2. 适用范围

• uni-app
• uni-app x
• Android App

当前未实现：

• iOS
• harmonyOS
• web
• 小程序

3. 最低兼容要求

• HBuilderX 4.25+
• Android 5.0+
• minSdkVersion 21

说明：

• UTS插件 本身在 uni-app 中从 HBuilderX 3.6+ 开始支持
• UTS插件 在 uni-app x 中从 HBuilderX 3.9+ 开始支持
• 但本插件使用了 UTS原生混编，因此建议最低按 HBuilderX 4.25+ 使用

4. 插件结构

kgd-ali-nui-transcriber/
├── package.json
├── README.md
└── utssdk/
    ├── interface.uts
    └── app-android/
        ├── AndroidManifest.xml
        ├── index.uts
        ├── AliNuiBridge.kt
        ├── AliNuiManager.java
        └── libs/
            ├── nuisdk-release.aar
            └── fastjson-1.1.46.android.jar

5. 安装方式

将插件放入项目：

your-project/
└── uni_modules/
    └── kgd-ali-nui-transcriber/

然后前端直接引入：

import {
  init,
  onTranscriberEvent,
  startTranscriber,
  stop,
  cancel,
  release,
  getVersion
} from "@/uni_modules/kgd-ali-nui-transcriber"

6. Android 权限

插件依赖以下权限：

• android.permission.INTERNET
• android.permission.RECORD_AUDIO
• android.permission.ACCESS_NETWORK_STATE
• android.permission.MODIFY_AUDIO_SETTINGS

其中录音权限会在调用 startTranscriber 时主动请求。

7. API 说明

7.1 getVersion

获取底层 SDK 版本。

const result = getVersion()
console.log(result)

7.2 init

初始化阿里云语音 SDK。

const result = init({
  appKey: "你的appKey",
  token: "你的token",
  url: "wss://nls-gateway.cn-shanghai.aliyuncs.com:443/ws/v1",
  deviceId: "demo-device",
  logLevel: "info",
  saveLog: false,
  saveWav: false
})

常用参数：

• appKey
• token
• url
• deviceId
• logLevel
• saveLog
• saveWav
• debugPath
• serviceMode

7.3 onTranscriberEvent

注册实时转写事件监听器。

onTranscriberEvent((event) => {
  console.log(event)
})

建议在页面加载后先注册，再调用 startTranscriber。

7.4 startTranscriber

开始实时语音识别。

startTranscriber({
  appKey: "你的appKey",
  token: "你的token",
  sampleRate: 16000,
  format: "pcm",
  enableIntermediateResult: true,
  enablePunctuationPrediction: true
})

常用参数：

• appKey
• token
• sampleRate
• format
• enableIntermediateResult
• enablePunctuationPrediction
• dialogParams
• nlsConfig
• startParams

7.5 stop

正常结束识别：

const result = stop()

7.6 cancel

取消识别：

const result = cancel()

7.7 release

释放资源：

const result = release()

8. 回调事件

常见事件：

• start
• transcriber_started
• partial_result
• transcriber_complete
• asr_error
• mic_error
• stop
• cancel
• release

其中最常用的是：

• partial_result 中间识别结果
• transcriber_complete 最终识别结果

建议优先读取字段：

• type
• code
• message
• result
• taskId

9. demo 说明

同目录下附带了一个示例工程：

• demo-app

使用方式：

1. 用 HBuilderX 打开 demo-app
2. 确认 uni_modules/kgd-ali-nui-transcriber 存在
3. 运行到 Android 真机
4. 页面会先注册 onTranscriberEvent
5. 填入 appKey
6. 填入 AccessKeyId
7. 填入 AccessKeySecret
8. 点击“初始化”
9. 点击“开始转写”

10. token 说明

demo 为了便于联调，支持客户端直连阿里云 CreateToken 接口：

• 输入 AccessKeyId
• 输入 AccessKeySecret
• 自动换取 token

但正式环境不建议这样做。

推荐生产方案：

• App 请求你的服务端
• 服务端调用阿里云 CreateToken
• 服务端返回临时 token
• App 再调用本插件

11. 上传插件市场注意事项

发布时请选择：

• UTS插件

不要再选择：

• App原生语言插件

打 zip 时请确保：

• zip 根目录直接是 package.json
• zip 根目录直接是 utssdk/

不要多包一层外层目录。

12. 后续建议

如果你准备继续完善，建议下一步做这几件事：

1. 增加 iOS 实现
2. 增加错误码文档
3. 改为服务端 token
4. 增加更完整的结果事件封装
5. 加入插件市场详情页文案与截图