更新记录
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 秒,可连续 |
使用前准备(腾讯云)
插件调用腾讯云语音识别服务,需要先在腾讯云开通:
- 开通「语音识别」服务,拿到
AppId、SecretId、SecretKey。
- 建议为密钥单独建子账号,只授予语音识别权限并设用量上限,避免额度被滥用。
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 直接放在客户端,一旦被反编译就能盗用你的腾讯云额度。
生产环境建议:
- 由你的服务端用密钥换一个短时效的临时签名,客户端只拿签名;
- 或者给密钥绑定子账号,只授予
QcloudASRFullAccess 且设置用量上限;
- 至少不要在代码里硬编码,改为登录后由服务端下发。
采样率
引擎 16k_zh 要求 16kHz 音频。插件录音固定 16kHz 单声道,
外部文件如果是 8kHz(电话录音)请把 engine 改成 8k_zh,否则识别率会明显下降。
时长与体积
一句话识别单次 ≤ 60 秒、≤ 3MB。超过会返回 9160009。
更长的音频请分段调用,或改用腾讯云的「录音文件识别」异步接口。
平台支持
| 平台 |
支持 |
| Android |
✅ |
| iOS |
❌ |
| 鸿蒙 |
❌(返回 9160007) |