更新记录

1.0.0(2026-11-20)

  • 首版发布:录音识别、文件 / URL 识别、实时流式识别三种用法。
  • 录音固定 16kHz 单声道,与中文引擎采样率一致,识别更准。
  • 支持 mp3 / wav / m4a / aac / amr / pcm 等 9 种格式,按扩展名自动推断。
  • 实时识别提供中间结果与音量回调,可直接画波形。
  • 结果返回纯文本,同时保留原始报文,方便排查。
  • 10 个语义化错误码,失败原因可直接展示给用户。
  • Android 支持;鸿蒙暂不支持(返回 9160007)。

平台兼容性

uni-app x(4.25)

Chrome Safari Android iOS 鸿蒙 微信小程序
× × √ × × ×

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
× × × √

uni-speech-asr · 语音转文字

接入腾讯云语音识别(ASR),把语音转成文字。支持三种用法:

用法 适用场景 实时性 时长限制
录音识别 startRecord → stopRecord 按住说话、语音输入框 说完后 1-2 秒出结果 ≤ 60 秒 / ≤ 3MB
文件 / URL 识别 recognizeFile / recognizeUrl 已有录音、客服工单、上传的语音 提交后返回 ≤ 60 秒 / ≤ 3MB
实时流式识别 startRealtime → onRealtimeResult 会议记录、长语音、边说边看 边说边出字 单句 ≤ 60 秒,可连续

使用前准备(腾讯云)

插件调用腾讯云语音识别服务,需要先在腾讯云开通:

  1. 开通「语音识别」服务,拿到 AppId、SecretId、SecretKey。
  2. 建议为密钥单独建子账号,只授予语音识别权限并设用量上限,避免额度被滥用。
  3. init() 时传入以上三项即可,换密钥重新调用 init() 会释放旧实例。

常用引擎型号:

型号 适用
16k_zh 中文通用,默认
16k_zh_en 中英混合
8k_zh 电话音质(8kHz 录音)

热词表可在控制台维护,hotwordId 传入后能明显提升专有名词识别率。

快速开始

import { init, startRecord, stopRecord, onRealtimeResult } from '@/uni_modules/uni-speech-asr'

// 1. 必须先初始化,否则所有接口返回 9160002
init({
  appId: '你的 AppId',
  secretId: 'AKIDxxxx',
  secretKey: 'xxxx',
  engine: '16k_zh',           // 可选,默认 16k_zh
  success: (res) => console.log('就绪,引擎', res.engine),
  fail: (err) => console.error(err.errCode, err.errMsg, err.detail)
})

录音识别

startRecord({
  success: (res) => console.log('开始录音', res.path, res.sampleRate)
})

// 用户说完
stopRecord({
  success: (res) => {
    console.log(res.text)      // 纯文本
    console.log(res.costMs)    // 识别耗时
  },
  fail: (err) => console.error(err.errMsg)
})

文件 / URL 识别

recognizeFile({
  path: '/storage/emulated/0/Download/a.mp3',
  format: 'mp3',              // 可省略,按扩展名推断
  filterPunc: 1,              // 过滤句末句号
  success: (res) => console.log(res.text)
})

recognizeUrl({
  url: 'https://example.com/a.mp3',
  success: (res) => console.log(res.text)
})

实时流式识别

onRealtimeResult((ev) => {
  if (ev.type == 'volume') volume = ev.volume      // 0-100,可画波形
  if (ev.type == 'partial') preview = ev.text      // 中间结果,会不断被覆盖
  if (ev.type == 'final') transcript += ev.text + '\n'   // 定稿句,只增不改
})

startRealtime({ vadSilenceTime: 1000 })
// ...
stopRealtime({ success: (res) => console.log(res.text) })

API

方法 说明
init(options) 初始化。换密钥时重新调用即可,会释放旧实例
startRecord(options?) 开始录音(16kHz 单声道 AAC,输出 .m4a)
stopRecord(options?) 停止录音并识别;recognize: false 只保存不识别
cancelRecord(options?) 取消录音并删除临时文件
recognizeFile(options) 识别本地音频文件
recognizeUrl(options) 识别可公网访问的音频 URL
startRealtime(options?) 开始实时流式识别
stopRealtime(options?) 停止实时识别,返回累计文本
onRealtimeResult(cb) 订阅实时识别事件(可多个)
offRealtimeResult(cb?) 取消订阅;不传参清空全部
getState(options?) 查询就绪 / 录音 / 识别状态与麦克风权限
getVersion() 插件版本

识别参数(通用)

参数 默认 说明
engine 16k_zh 引擎模型。16k_zh 中文、16k_zh_en 中英混合、8k_zh 电话音质
format 按扩展名推断 mp3 / wav / m4a / aac / amr / pcm / ogg-opus / speex / silk
hotwordId 空 热词表 id,用于提升专有名词识别率
filterDirty 0 0 不过滤脏话 / 1 过滤
filterModal 0 0 不过滤语气词 / 1 部分过滤 / 2 严格过滤
filterPunc 1 0 保留句末句号 / 1 过滤
convertNumMode 1 1 智能转阿拉伯数字 / 0 全转中文数字
reinforceHotword 1 热词增强开关

错误码

错误码 含义
9160001 参数错误
9160002 尚未初始化,请先调用 init()
9160003 音频文件不存在或不可读
9160004 录音权限未授予
9160005 录音失败
9160006 识别失败(网络 / 密钥 / 服务端错误),err.detail 里有原始信息
9160007 当前平台不支持(鸿蒙)
9160008 正在识别中,请稍候
9160009 音频超出限制(>60 秒或 >3MB)
9160010 实时识别不可用

注意事项

密钥安全(重要)

secretId / secretKey 直接放在客户端,一旦被反编译就能盗用你的腾讯云额度。 生产环境建议:

  1. 由你的服务端用密钥换一个短时效的临时签名,客户端只拿签名;
  2. 或者给密钥绑定子账号,只授予 QcloudASRFullAccess 且设置用量上限;
  3. 至少不要在代码里硬编码,改为登录后由服务端下发。

采样率

引擎 16k_zh 要求 16kHz 音频。插件录音固定 16kHz 单声道, 外部文件如果是 8kHz(电话录音)请把 engine 改成 8k_zh,否则识别率会明显下降。

时长与体积

一句话识别单次 ≤ 60 秒、≤ 3MB。超过会返回 9160009。 更长的音频请分段调用,或改用腾讯云的「录音文件识别」异步接口。

平台支持

平台 支持
Android ✅
iOS ❌
鸿蒙 ❌(返回 9160007)

隐私、权限声明

1. 本插件需要申请的系统权限列表:

需要 RECORD_AUDIO、INTERNET、ACCESS_NETWORK_STATE

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

音频会上传至腾讯云语音识别服务进行转写,插件自身不额外存储或转发;密钥由使用方自行配置,请勿硬编码在客户端长期使用

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。