expo-speech-recognition:React Native Expo 语音识别终极指南,一个库搞定 iOS/Android/Web 三平台

原创2026-11-02 10:46:041,675 阅读

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-speech-recognition 在 Web、Android、iOS 三平台运行的 Expo 语音识别演示界面

核心功能一览: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";或改用端侧识别。

源码与示例在哪里?

想深入实现细节,可以从以下文件入手:

也可以把仓库克隆到本地跑示例:

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 项目中做语音识别的首选方案。

登录后查看全文
expo-speech-recognition