更新记录

1.0.0（2026-08-28）

1.0.0（2026-08-28）

• 首次发布。
• iOS：Apple Speech 本机音频文件识别。
• Android：内置 sherpa-onnx 英文 Zipformer 模型，支持常见系统可解码音频格式。
• HarmonyOS：Core Speech Kit 端侧 PCM/WAV 文件识别。
• 提供统一能力检测、错误码、超时和资源释放 API。

平台兼容性

uni-app(4.61)

uni-app x(4.61)

其他

cw-local-speech

面向 uni-app 与 uni-app x 的 UTS 端侧语音转文字插件。公共 API 在三端一致，音频不会由插件上传到业务服务器。

平台实现

跨三端录音时，建议统一生成 16kHz、单声道、16-bit PCM WAV，避免平台格式差异。

安装

把整个 cw-local-speech 目录放到项目的 uni_modules 下：

你的项目/
└── uni_modules/
    └── cw-local-speech/

Android 端包含 AAR 和原生库，需要重新制作自定义基座或正式打包。iOS 的 Info.plist 权限文案会由 UTS 插件合并。HarmonyOS 需 HBuilderX 4.61+ 和可用的 DevEco Studio/HarmonyOS SDK。

使用

import {
  getLocalSpeechCapability,
  recognizeAudioFile,
  releaseLocalSpeech
} from '@/uni_modules/cw-local-speech'

const capability = getLocalSpeechCapability()
console.log('本机能力', capability)

recognizeAudioFile({
  path: audioPath,
  // iOS/Android 默认 en-US；HarmonyOS 默认 zh-CN。
  // 跨端业务建议根据 capability.platform 显式传入。
  locale: capability.platform == 'harmony' ? 'zh-CN' : 'en-US',
  timeoutMs: 120000,
  success: (result) => {
    console.log('识别文本', result.text)
  },
  fail: (error) => {
    console.error(error.errCode, error.errMsg, error.nativeCode)
  },
  complete: () => {
    console.log('识别结束')
  }
})

// 页面不再使用识别时可释放 Android 常驻模型；iOS/HarmonyOS 为安全空操作。
releaseLocalSpeech()

uni-app x 的 .uvue 页面也可以导入类型：

import {
  recognizeAudioFile,
  SpeechRecognizeOptions
} from '@/uni_modules/cw-local-speech'

const options = {
  path: audioPath,
  locale: 'en-US',
  success: (result) => console.log(result.text),
  fail: (error) => console.error(error.errMsg)
} as SpeechRecognizeOptions

recognizeAudioFile(options)

API

getLocalSpeechCapability(locale?)

同步返回平台、是否支持、可用语种、输入格式、原生引擎和限制。调用识别前应先检查 supported。

recognizeAudioFile(options)

识别一个已存在的本地音频文件，只回调一次最终结果。

• path：必填，绝对路径、file:// 或 uni 本地相对路径。
• locale：iOS/Android 默认 en-US，HarmonyOS 默认 zh-CN。
• timeoutMs：默认 120000。Android 是软超时：回调按时失败，但底层正在执行的本地推理只能在本轮完成后释放。
• numThreads：Android 专用，1-4，默认 2。
• sampleRate/channels/sampleBits：HarmonyOS 原始 .pcm 描述，必须分别为 16000/1/16；WAV 从文件头读取。

releaseLocalSpeech()

释放 Android 常驻 sherpa-onnx 模型。不要在识别过程中调用。

错误码

上架与隐私说明

• 插件没有网络请求，也不申请 Android 网络权限。
• iOS 使用系统 Speech 权限，且明确设置 requiresOnDeviceRecognition=true。
• HarmonyOS 的 ohos.permission.MICROPHONE 来自 Core Speech Kit 官方集成要求；本插件当前只读取调用方指定的音频文件，不主动开启麦克风。
• Android AAR 中包含 sherpa-onnx、ONNX Runtime 和英文模型。发布前请同时保留 LICENSE 与 THIRD_PARTY_NOTICES.md。

真机验收建议

1. 各准备一段 5-10 秒的 16kHz 单声道 PCM WAV。
2. 开启飞行模式后分别识别，确认没有网络依赖。
3. iOS 分别测试已下载/未下载语种资源；Android 测试首次模型解包；HarmonyOS 必须使用标准系统真机。
4. 验证成功、文件不存在、语种不支持、超时四条回调路径都只执行一次 complete。