@gaozh1024/rn-aliyun-asr

React Native 阿里云实时语音识别 SDK

功能特性

• ✅ 实时语音识别 (Real-time ASR)
• ✅ 语音活动检测 (VAD)
• ✅ 中间结果实时返回
• ✅ 长文本连续识别
• ✅ 热词定制
• ✅ Android & iOS 双平台

安装

npm install @gaozh1024/rn-aliyun-asr
# 或
yarn add @gaozh1024/rn-aliyun-asr

iOS 额外配置

cd ios && pod install

Android 额外配置

Android 无需额外手动添加 AAR 依赖，框架会在构建时自动从 nuisdk-release.aar 解压 classes.jar 与 JNI 库。

权限配置

Android - android/app/src/main/AndroidManifest.xml

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />

iOS - ios/YourApp/Info.plist

<key>NSMicrophoneUsageDescription</key>
<string>需要麦克风权限进行语音识别</string>

快速开始

import { AliyunASR, VadMode, ASREvent } from '@gaozh1024/rn-aliyun-asr';

const asr = AliyunASR.getInstance();

// 初始化
await asr.initialize({
  appKey: 'your-app-key',
  token: 'your-token',
  logAllEvents: true,
  androidAudioConfig: {
    recorderStrategy: 'auto',
    recorderSource: 'voiceRecognition',
    recorderSourceFallbacks: ['mic', 'default', 'camcorder'],
    huaweiCompatibility: true,
  },
});

// 监听识别结果（result.text 默认已解析为纯文本）
asr.on(ASREvent.ASR_RESULT, (data) => {
  console.log('识别结果:', data.result?.text);
  console.log('原始结果:', data.result?.rawJson ?? data.result?.rawText);
});

// 调试时建议默认监听全部事件
asr.onAllEvents((data) => {
  console.log('onASREvent =>', data.eventName, data);
});

// Android 录音状态调试
asr.onAudioStateChange((data) => {
  console.log('onASRAudioState =>', data);
});

// 开始识别
await asr.startRecognition(VadMode.MODE_P2T);

Android 排障建议

• startRecognition() 按住说话请显式使用 VadMode.MODE_P2T
• 初始化时建议开启 logAllEvents: true，默认打印全部 onASREvent
• 业务层建议同时监听：
  • ASREvent.MIC_ERROR
  • ASREvent.ASR_ERROR
  • ASREvent.DIALOG_ERROR
• 对华为/Honor 设备，框架会在 androidAudioConfig.recorderStrategy = 'auto' 时优先切到用户侧 AudioRecord 兜底
• 可显式配置 Android 录音 source fallback：

await asr.initialize({
  appKey: 'your-app-key',
  token: 'your-token',
  androidAudioConfig: {
    recorderStrategy: 'user',
    recorderSource: 'voiceRecognition',
    recorderSourceFallbacks: ['mic', 'default', 'camcorder'],
  },
});

• result.text 默认会从阿里云返回 JSON 中提取 payload.result 作为纯文本
• 如需调试原始返回值，可读取 result.rawText 或 result.rawJson
• 如怀疑编码兼容问题，可先切到 PCM 排查：

await asr.initialize({
  appKey: 'your-app-key',
  token: 'your-token',
  format: 'pcm',
  logAllEvents: true,
});

文档

文档已按功能分组，便于快速查找：

📚 入门指南

• 项目说明 - 项目介绍、功能特性
• 使用文档 - 详细使用指南、API 示例、常见问题

📖 API 参考

• API文档 - 完整 API 方法、类型定义、错误码

💻 开发指南（开发者）

• 架构设计 - 整体架构设计
• 原生层实现 - Android/iOS 原生代码实现

👥 项目管理

• README-团队 - 团队总览

快速导航

| 角色 | 推荐文档 | |------|----------| | 使用者 | 使用文档 | | 开发者 | 架构设计 + 原生层实现 | | 项目负责人 | README-团队 |

示例

查看 example/App.tsx 获取完整示例代码。

变更日志

查看 版本记录 了解每个版本的详细变更。

| 版本 | 日期 | 说明 | |------|------|------| | v1.0.8 | 2026-03-25 | Android 用户录音链路修复、结果纯文本解析、事件管理优化 | | v1.0.7 | 2026-03-24 | Android ASR 参数修正、资源补齐、事件链路增强 | | v1.0.6 | 2026-03-24 | 官方文档对齐、发布准备完善、标签修复 | | v1.0.5 | 2026-03-24 | Android NativeNui 对齐、P2T 默认、iOS 线程修正 | | v1.0.4 | 2024-03-24 | 修复 Android 代码与 AAR 不匹配 | | v1.0.3 | 2024-03-24 | Android AAR 手动配置方案 | | v1.0.2 | 2024-03-24 | Android AAR 依赖传递修复（已废弃） | | v1.0.1 | 2024-03-24 | Android Gradle 8.x 兼容性修复（已废弃） | | v1.0.0 | 2024-03-24 | 首个正式版本 |

许可证

MIT