expo-speech-recognition:React Native Expo 语音识别终极指南,一个库搞定 iOS/Android/Web 三平台
expo-speech-recognition:React Native Expo 语音识别终极指南,一个库搞定 iOS/Android/Web 三平台
expo-speech-recognition 是面向 React Native Expo 项目的语音识别库,它将 iOS 的 SFSpeechRecognizer、Android 的 SpeechRecognizer 与 Web 的 SpeechRecognition 封装成同一套 API,让你在 iOS、Android、Web 三端用一份代码实现实时语音转文字。除实时识别外,它还支持录音持久化、离线(端侧)识别、音频文件转写和音量计等功能。
核心功能一览:Expo 语音识别能做什么?
| 功能 | 说明 | 平台要求 |
|---|---|---|
| 实时语音识别 | 麦克风说话即时转文字,事件模型对齐 Web Speech API | iOS 17+、Android 12+、Chrome/Safari 桌面 |
| 连续识别与中间结果 | continuous + interimResults,边说边出结果 |
Android 13+、iOS 17+ |
| 离线端侧识别 | requiresOnDeviceRecognition,音频不出设备 |
Android 13+(需下载语言模型)、iOS |
| 录音持久化 | 识别同时把音频存成本地文件 | Android 13+、iOS |
| 音频文件转写 | 传入本地文件 URI 直接转文字 | Android 13+、iOS |
| 音量计 | 实时获取麦克风音量,可做 UI 反馈动画 | 全平台 |
| Web Speech API 补丁 | 为第三方库补齐 SpeechRecognition 全局对象 |
移动端 + Web |
安装与配置:30 秒完成 Expo 语音识别库设置
第 1 步:安装依赖
npm install expo-speech-recognition
旧版 SDK 可指定版本安装,例如
npm install expo-speech-recognition@sdk-54。
第 2 步:在 app.json 中配置 config plugin
{
"expo": {
"plugins": [
[
"expo-speech-recognition",
{
"microphonePermission": "Allow $(PRODUCT_NAME) to use the microphone.",
"speechRecognitionPermission": "Allow $(PRODUCT_NAME) to use speech recognition."
}
]
]
}
}
这个 config plugin(实现见 app.plugin.js)会自动完成两件容易踩坑的事:
- 在 iOS 的 Info.plist 中写入麦克风与语音识别权限描述;
- 在 Android 的 AndroidManifest 中写入语音识别服务的包可见性声明(
queries),避免 Android 11+ 上找不到识别服务。
如果你是新建的 Expo 项目(还没有 ios/ 和 android/ 目录),配置完成后需要执行 npx expo run:ios 或 npx expo run:android 重新生成原生工程。
快速上手:用 Hook 实现实时语音转文字
最简单的方式是 useSpeechRecognitionEvent Hook(源码见 src/useSpeechRecognitionEvent.ts):
import {
ExpoSpeechRecognitionModule,
useSpeechRecognitionEvent,
} from "expo-speech-recognition";
useSpeechRecognitionEvent("result", (event) => {
setTranscript(event.results[0]?.transcript);
});
useSpeechRecognitionEvent("error", (event) => {
console.log("error:", event.error, event.message);
});
const handleStart = async () => {
const result = await ExpoSpeechRecognitionModule.requestPermissionsAsync();
if (!result.granted) return;
ExpoSpeechRecognitionModule.start({
lang: "en-US",
interimResults: true, // 边说边出中间结果
});
};
识别过程中可用 stop() 正常结束(会尝试返回最终结果),或用 abort() 立即取消。核心 API 与类型定义位于 src/ExpoSpeechRecognitionModule.ts 和 src/ExpoSpeechRecognitionModule.types.ts。
常用事件速查
| 事件 | 触发时机 |
|---|---|
start / end |
识别开始 / 服务断开(始终是最后一个事件) |
result |
识别出一段文字,isFinal 区分最终/中间结果 |
error |
发生错误,error 字段为错误码 |
speechstart |
检测到声音(不一定是有效语音) |
audiostart / audioend |
录音开始 / 结束(开启持久化时带文件 uri) |
volumechange |
音量变化,值为 -2 到 10 |
languagedetection |
语言检测结果(仅 Android 14+ 端侧识别) |
权限请求指南:如何正确请求麦克风与语音识别权限
开始识别前务必先请求权限,否则会收到 error 事件且错误码为 not-allowed。库提供了细粒度的权限 API:
requestPermissionsAsync():一次请求麦克风 + 语音识别权限(iOS 是两项权限,Android 只有麦克风权限);requestMicrophonePermissionsAsync():只请求麦克风权限,适合仅使用端侧识别的场景;requestSpeechRecognizerPermissionsAsync():iOS 专属,网络识别专用;getPermissionsAsync():只查询、不弹窗,适合启动时静默检测。
iOS 上语音识别权限可能被"屏幕使用时间"的隐私限制或 MDM 企业配置拦截,此时 getPermissionsAsync() 返回的 restricted 字段会为 true,可以据此给用户更明确的提示。
实用进阶:录音持久化与音频文件转写
保存录音文件:在 start() 时开启 recordingOptions.persist: true,audioend 事件中即可拿到本地文件路径(Android 存为 16kHz PCM WAV,iOS 默认 32-bit Float PCM)。这份录音可以直接发给 Whisper、Deepgram 等第三方服务做二次精转。
转写音频文件:把 audioSource.uri 指向本地音频文件即可不用麦克风转写,支持 16kHz 的 WAV / MP3 / OGG 等格式。长音频建议开启 requiresOnDeviceRecognition 走端侧识别以避免网络限速。示例音频文件见 example/assets/audio/readme.md 与 example/assets/audio-remote/,对应演示组件为 TranscribeLocalAudioFileDemo.tsx。
音量计动画:开启 volumeChangeEventOptions.enabled: true 后监听 volumechange 事件,值小于 0 视为听不清。完整动画示例参考 VolumeMeteringAvatar.tsx。
给第三方库打补丁:如果你的项目依赖了使用 Web Speech API 的第三方库,可以用 ExpoWebSpeechRecognition(src/ExpoWebSpeechRecognition.ts)替换 webkitSpeechRecognition / SpeechRecognition 全局对象,让它们在移动端也能工作。
平台兼容性速查:哪些设备能用哪些功能
移动端(React Native):
| 功能 | Android 12- | Android 13 | Android 14+ | iOS 17+ |
|---|---|---|---|---|
| 基础识别 | ✅ | ✅ | ✅ | ✅ |
| 连续识别 | ❌ | ✅ | ✅ | ✅ |
| 端侧离线识别 | ❌ | ✅ | ✅ | ✅ |
| 录音 / 文件转写 | ❌ | ✅ | ✅ | ✅ |
| 语言检测 | ❌ | ❌ | ✅* | ❌ |
| 标点自动添加 | ❌ | ✅* | ✅* | ✅ |
* Android 上仅端侧识别可用。
Web 端:Chrome 桌面版 ✅、Safari 桌面版 16+ ✅、Chrome 移动端 ✅;Firefox 与 Brave 桌面版暂不可用。
常见问题排查:语音识别不可用、报错怎么办?
Android 上识别服务不可用或卡住
- Android 13+:确认设备已安装并启用
com.google.android.tts(Speech Recognition & Synthesis); - Android 12 及以下:确认 Google app(
com.google.android.googlequicksearchbox)已安装并启用; - 可用
getSpeechRecognitionServices()查看设备上实际可用的识别服务列表。
Android 端侧离线识别不生效
- 先用
getSupportedLocales()查看已安装的语言模型,通常为空; - 再调用
androidTriggerOfflineModelDownload({ locale: "en-US" })触发系统下载离线模型。
iOS 上扬声器被麦克风拾取(回音)
- 开启
iosVoiceProcessingEnabled: true,增加防反馈信号处理。
Android 13+ 开始/结束识别时有"哔"声
- 这是底层 API 的硬编码行为,开启
continuous: true或录音持久化即可绕过。
单词/字母识别率低
- iOS 设置
iosTaskHint: "confirmation";Android 在androidIntentOptions中加入EXTRA_LANGUAGE_MODEL: "web_search";或改用端侧识别。
源码与示例在哪里?
想深入实现细节,可以从以下文件入手:
- 库的入口与导出清单:src/index.ts
- Web 端实现:src/ExpoSpeechRecognitionModule.web.ts
- Android 原生实现:android/src/main/java/expo/modules/speechrecognition/ExpoSpeechRecognitionModule.kt、ExpoSpeechService.kt
- iOS 原生实现:ios/ExpoSpeechRecognitionModule.swift、ios/ExpoSpeechRecognizer.swift
- 功能齐全的示例 App(含设置面板与各项演示):example/App.tsx,运行说明见 example/README.md
也可以把仓库克隆到本地跑示例:
git clone https://gitcode.com/gh_mirrors/ex/expo-speech-recognition
总结
expo-speech-recognition 用一套统一的 Hook + Module API,抹平了 iOS、Android、Web 三端语音识别的差异:装包、配插件、请求权限、调用 start() 四步即可上线语音输入能力;录音持久化、文件转写、离线识别和音量计则覆盖了会议纪要、语音备忘录、语音搜索等常见场景。当前版本 58.0.0 与 Expo SDK 58 对齐,采用 MIT 协议,是 Expo 项目中做语音识别的首选方案。
