# @gaozh1024/rn-aliyun-asr

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

## 功能特性

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

## 安装

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

### iOS 额外配置

```bash
cd ios && pod install
```

### Android 额外配置

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

### 权限配置

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

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

**iOS** - `ios/YourApp/Info.plist`

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

## 快速开始

```typescript
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：

```typescript
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 排查：

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

## 文档

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

### 📚 入门指南
- [项目说明](https://github.com/gaozh1024/rn-aliyun-asr/blob/main/docs/01-%E5%85%A5%E9%97%A8%E6%8C%87%E5%8D%97/%E9%A1%B9%E7%9B%AE%E8%AF%B4%E6%98%8E.md) - 项目介绍、功能特性
- [使用文档](https://github.com/gaozh1024/rn-aliyun-asr/blob/main/docs/01-%E5%85%A5%E9%97%A8%E6%8C%87%E5%8D%97/%E4%BD%BF%E7%94%A8%E6%96%87%E6%A1%A3.md) - 详细使用指南、API 示例、常见问题

### 📖 API 参考
- [API文档](https://github.com/gaozh1024/rn-aliyun-asr/blob/main/docs/02-API%E6%96%87%E6%A1%A3/API%E6%96%87%E6%A1%A3.md) - 完整 API 方法、类型定义、错误码

### 💻 开发指南（开发者）
- [架构设计](https://github.com/gaozh1024/rn-aliyun-asr/blob/main/docs/03-%E5%BC%80%E5%8F%91%E6%8C%87%E5%8D%97/%E6%9E%B6%E6%9E%84%E8%AE%BE%E8%AE%A1.md) - 整体架构设计
- [原生层实现](https://github.com/gaozh1024/rn-aliyun-asr/blob/main/docs/03-%E5%BC%80%E5%8F%91%E6%8C%87%E5%8D%97/%E5%8E%9F%E7%94%9F%E5%B1%82%E5%AE%9E%E7%8E%B0.md) - Android/iOS 原生代码实现

### 👥 项目管理
- [README-团队](https://github.com/gaozh1024/rn-aliyun-asr/blob/main/docs/04-%E5%9B%A2%E9%98%9F%E7%AE%A1%E7%90%86/README-%E5%9B%A2%E9%98%9F.md) - 团队总览

## 快速导航

| 角色 | 推荐文档 |
|------|----------|
| **使用者** | [使用文档](./docs/01-入门指南/使用文档.md) |
| **开发者** | [架构设计](./docs/03-开发指南/架构设计.md) + [原生层实现](./docs/03-开发指南/原生层实现.md) |
| **项目负责人** | [README-团队](./docs/04-团队管理/README-团队.md) |

## 示例

查看 [example/App.tsx](https://github.com/gaozh1024/rn-aliyun-asr/blob/main/example/App.tsx) 获取完整示例代码。

## 变更日志

查看 [版本记录](https://github.com/gaozh1024/rn-aliyun-asr/tree/main/docs/05-%E7%89%88%E6%9C%AC%E8%AE%B0%E5%BD%95) 了解每个版本的详细变更。

| 版本 | 日期 | 说明 |
|------|------|------|
| [v1.0.8](https://github.com/gaozh1024/rn-aliyun-asr/blob/main/docs/05-%E7%89%88%E6%9C%AC%E8%AE%B0%E5%BD%95/v1.0.8.md) | 2026-03-25 | Android 用户录音链路修复、结果纯文本解析、事件管理优化 |
| [v1.0.7](https://github.com/gaozh1024/rn-aliyun-asr/blob/main/docs/05-%E7%89%88%E6%9C%AC%E8%AE%B0%E5%BD%95/v1.0.7.md) | 2026-03-24 | Android ASR 参数修正、资源补齐、事件链路增强 |
| [v1.0.6](https://github.com/gaozh1024/rn-aliyun-asr/blob/main/docs/05-%E7%89%88%E6%9C%AC%E8%AE%B0%E5%BD%95/v1.0.6.md) | 2026-03-24 | 官方文档对齐、发布准备完善、标签修复 |
| [v1.0.5](https://github.com/gaozh1024/rn-aliyun-asr/blob/main/docs/05-%E7%89%88%E6%9C%AC%E8%AE%B0%E5%BD%95/v1.0.5.md) | 2026-03-24 | Android NativeNui 对齐、P2T 默认、iOS 线程修正 |
| [v1.0.4](https://github.com/gaozh1024/rn-aliyun-asr/blob/main/docs/05-%E7%89%88%E6%9C%AC%E8%AE%B0%E5%BD%95/v1.0.4.md) | 2024-03-24 | **修复 Android 代码与 AAR 不匹配** |
| [v1.0.3](https://github.com/gaozh1024/rn-aliyun-asr/blob/main/docs/05-%E7%89%88%E6%9C%AC%E8%AE%B0%E5%BD%95/v1.0.3.md) | 2024-03-24 | Android AAR 手动配置方案 |
| [v1.0.2](https://github.com/gaozh1024/rn-aliyun-asr/blob/main/docs/05-%E7%89%88%E6%9C%AC%E8%AE%B0%E5%BD%95/v1.0.2.md) | 2024-03-24 | Android AAR 依赖传递修复（已废弃） |
| [v1.0.1](https://github.com/gaozh1024/rn-aliyun-asr/blob/main/docs/05-%E7%89%88%E6%9C%AC%E8%AE%B0%E5%BD%95/v1.0.1.md) | 2024-03-24 | Android Gradle 8.x 兼容性修复（已废弃） |
| [v1.0.0](https://github.com/gaozh1024/rn-aliyun-asr/blob/main/docs/05-%E7%89%88%E6%9C%AC%E8%AE%B0%E5%BD%95/v1.0.0.md) | 2024-03-24 | 首个正式版本 |

## 许可证

MIT