# YX ASR - Sherpa ONNX 使用指南

本文档详细说明如何使用基于 sherpa_onnx 的 YX ASR 语音识别插件。

## 🎯 核心优势

### 与原生识别的对比

| 特性 | 原生识别 | sherpa_onnx |
|------|----------|-------------|
| **网络依赖** | 需要网络 | 完全离线 |
| **隐私保护** | 数据上传云端 | 本地处理 |
| **识别一致性** | 平台差异 | 跨平台一致 |
| **自定义能力** | 受限 | 高度可定制 |
| **包体积** | 无增加 | +40-60MB |
| **识别精度** | 高(云端) | 高(本地模型) |

## 📦 安装配置

### 1. 添加依赖

```yaml
dependencies:
  yx_asr: ^1.0.0
```

### 2. 下载模型文件

从 [sherpa-onnx releases](https://github.com/k2-fsa/sherpa-onnx/releases/) 下载模型：

**推荐模型：**
- **中英双语**: `sherpa-onnx-streaming-zipformer-bilingual-zh-en-2023-02-20`
- **纯中文**: `sherpa-onnx-streaming-zipformer-zh-2023-02-13`
- **纯英文**: `sherpa-onnx-streaming-zipformer-en-2023-02-21`

### 3. 模型文件结构

```
assets/models/
├── zh-cn/                    # 中文模型
│   ├── encoder.onnx         # 编码器
│   ├── decoder.onnx         # 解码器
│   ├── joiner.onnx          # 连接器
│   └── tokens.txt           # 词汇表
├── en-us/                   # 英文模型
│   ├── encoder.onnx
│   ├── decoder.onnx
│   ├── joiner.onnx
│   └── tokens.txt
└── bilingual/               # 双语模型
    ├── encoder.onnx
    ├── decoder.onnx
    ├── joiner.onnx
    └── tokens.txt
```

## 🚀 使用方法

### 基本使用

```dart
import 'package:yx_asr/yx_asr.dart';

class SpeechRecognitionPage extends StatefulWidget {
  @override
  _SpeechRecognitionPageState createState() => _SpeechRecognitionPageState();
}

class _SpeechRecognitionPageState extends State<SpeechRecognitionPage> {
  final YxAsr _asr = YxAsr();
  String _result = '';
  bool _isListening = false;

  @override
  void initState() {
    super.initState();
    _initializeASR();
  }

  Future<void> _initializeASR() async {
    // 初始化中文模型
    final success = await _asr.initializeWithModel('assets/models/zh-cn');
    
    if (success) {
      // 监听识别结果
      _asr.onResult.listen((result) {
        setState(() {
          _result = result.recognizedWords;
        });
      });

      // 监听错误
      _asr.onError.listen((error) {
        print('错误: ${error.errorMsg}');
      });

      // 监听状态
      _asr.onListeningStatusChanged.listen((isListening) {
        setState(() {
          _isListening = isListening;
        });
      });
    }
  }

  Future<void> _toggleRecording() async {
    if (_isListening) {
      await _asr.stopListening();
    } else {
      await _asr.startListening(partialResults: true);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('语音识别')),
      body: Column(
        children: [
          Text('识别结果: $_result'),
          ElevatedButton(
            onPressed: _toggleRecording,
            child: Text(_isListening ? '停止录音' : '开始录音'),
          ),
        ],
      ),
    );
  }
}
```

### 使用录音按钮组件

```dart
RecordingButton(
  onResult: (result) {
    print('识别结果: ${result.recognizedWords}');
    print('是否最终结果: ${result.finalResult}');
    print('置信度: ${result.confidence}');
  },
  onError: (error) {
    print('错误: ${error.errorMsg}');
  },
  localeId: 'zh-CN',  // 会自动选择对应模型
  size: 80.0,
  recordingColor: Colors.red,
  idleColor: Colors.blue,
  tooltip: '点击开始录音',
)
```

### 多语言支持

```dart
class MultiLanguageASR {
  final YxAsr _asr = YxAsr();
  String _currentLanguage = 'zh-cn';

  Future<void> switchLanguage(String language) async {
    String modelPath;
    switch (language) {
      case 'zh-cn':
        modelPath = 'assets/models/zh-cn';
        break;
      case 'en-us':
        modelPath = 'assets/models/en-us';
        break;
      case 'bilingual':
        modelPath = 'assets/models/bilingual';
        break;
      default:
        modelPath = 'assets/models/zh-cn';
    }

    final success = await _asr.initializeWithModel(modelPath);
    if (success) {
      _currentLanguage = language;
      print('切换到 $language 模型成功');
    }
  }
}
```

## ⚙️ 高级配置

### 自定义采样率

```dart
await _asr.initializeWithModel(
  'assets/models/zh-cn',
  sampleRate: 16000, // 默认 16kHz
);

await _asr.startListening(
  partialResults: true,
  sampleRate: 16000,
);
```

### 错误处理

```dart
_asr.onError.listen((error) {
  switch (error.errorType) {
    case SpeechRecognitionErrorType.permissionDenied:
      // 处理权限被拒绝
      showDialog(context: context, builder: (context) => 
        AlertDialog(title: Text('需要麦克风权限')));
      break;
    case SpeechRecognitionErrorType.service:
      // 处理服务错误
      print('服务错误: ${error.errorMsg}');
      break;
    case SpeechRecognitionErrorType.audio:
      // 处理音频错误
      print('音频错误: ${error.errorMsg}');
      break;
    default:
      print('未知错误: ${error.errorMsg}');
  }
});
```

## 🔧 性能优化

### 1. 模型选择
- **小型应用**: 使用单语言模型 (~40MB)
- **多语言应用**: 使用双语模型 (~60MB)
- **专业应用**: 训练自定义模型

### 2. 内存管理
```dart
@override
void dispose() {
  _asr.dispose(); // 释放资源
  super.dispose();
}
```

### 3. 批量处理
```dart
// 对于长时间录音，定期获取结果
Timer.periodic(Duration(seconds: 5), (timer) {
  if (_asr.isListening) {
    // 可以在这里保存中间结果
  }
});
```

## 📱 平台特定配置

### Android
```xml
<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
```

### iOS
```xml
<!-- ios/Runner/Info.plist -->
<key>NSMicrophoneUsageDescription</key>
<string>此应用需要麦克风权限进行语音识别</string>
```

## 🐛 常见问题

### Q: 模型文件太大怎么办？
A: 可以考虑：
1. 使用模型压缩
2. 动态下载模型
3. 只包含必要的语言模型

### Q: 识别精度不够怎么办？
A: 可以尝试：
1. 使用更新的模型
2. 调整音频参数
3. 在安静环境中测试
4. 训练自定义模型

### Q: 如何实现实时显示？
A: 启用 `partialResults: true` 并监听结果流：
```dart
_asr.onResult.listen((result) {
  if (result.finalResult) {
    // 最终结果
    finalText = result.recognizedWords;
  } else {
    // 实时结果
    partialText = result.recognizedWords;
  }
});
```

## 📚 参考资源

- [sherpa-onnx 官方文档](https://github.com/k2-fsa/sherpa-onnx)
- [模型下载地址](https://github.com/k2-fsa/sherpa-onnx/releases/)
- [Flutter 音频处理](https://pub.dev/packages/record)

## 🤝 技术支持

如有问题，请提交 Issue 或参考示例代码。