# Realtime Plugin 实现总结

## 项目概述

基于您提供的Android原生示例，我为DeepVoice项目创建了一个realtime插件，用于通过WebSocket接入Vocode服务器实现实时语音聊天功能。该插件已完成Android和iOS双平台实现。

## 架构设计

### 插件结构
```
local_plugins/realtime/
├── android/                        # Android实现
│   ├── build.gradle               # Android构建配置
│   ├── src/main/
│   │   ├── AndroidManifest.xml    # Android权限配置
│   │   └── kotlin/com/yunqiinnovation/realtime/
│   │       ├── RealtimePlugin.kt           # 主插件入口
│   │       ├── RealtimeAudioManager.kt     # 音频管理器（AudioRecord/AudioTrack）
│   │       └── RealtimeWebSocketManager.kt # WebSocket管理器（OkHttp）
├── ios/                            # iOS实现
│   ├── Classes/                    # Objective-C桥接文件
│   │   ├── RealtimePlugin.h
│   │   └── RealtimePlugin.m
│   ├── realtime/                   # Swift Package
│   │   ├── Package.swift
│   │   └── Sources/realtime/
│   │       ├── RealtimePlugin.swift        # 主插件入口
│   │       ├── RealtimeAudioManager.swift  # 音频管理器（AVAudioEngine）
│   │       └── RealtimeWebSocketManager.swift # WebSocket管理器（URLSession）
│   └── realtime.podspec
├── lib/
│   └── realtime.dart              # Flutter接口
├── pubspec.yaml
└── README.md
```

### 核心组件

1. **RealtimePlugin (SwiftRealtimePlugin)**
   - 主插件入口，处理Flutter方法调用
   - 管理各组件间的协调
   - 处理事件分发

2. **RealtimeAudioManager**
   - 使用AVAudioEngine进行音频录制
   - 使用AVAudioPlayerNode进行音频播放
   - 支持16kHz/16-bit/单声道格式
   - 实现20ms帧长的音频处理

3. **RealtimeWebSocketManager**
   - 使用URLSessionWebSocketTask实现WebSocket通信
   - 支持音频数据和文本消息的收发
   - 自动连接状态管理

## 技术实现对照

| 功能 | Android示例 | iOS实现 |
|------|-------------|---------|
| 音频录制 | AudioRecord | AVAudioEngine + AVAudioInputNode |
| 音频播放 | AudioTrack | AVAudioPlayerNode |
| WebSocket | OkHttp WebSocket | URLSessionWebSocketTask |
| 线程管理 | Kotlin协程 | DispatchQueue |
| 音频格式 | 16kHz/16-bit/单声道 | 16kHz/16-bit/单声道 |
| 帧长 | 20ms (320字节) | 20ms (320字节) |

## Flutter接口

### 主要类
- `RealtimeService`: 主服务类
- `RealtimeEvent`: 事件类
- `ConnectionStatus`: 连接状态枚举
- `VoiceStatus`: 语音状态枚举
- `RealtimeException`: 异常类

### 主要方法
- `initialize()`: 初始化服务
- `connect()`: 连接服务器
- `disconnect()`: 断开连接
- `startRecording()`: 开始录音
- `stopRecording()`: 停止录音
- `eventStream`: 事件流

## 使用方式

### 1. 在RealtimeController中集成
已更新`lib/modules/realtime/controllers/realtime_controller.dart`使用真实的realtime插件，取代了原来的模拟实现。

### 2. 事件监听
```dart
_realtimeService.eventStream.listen((event) {
  switch (event.type) {
    case 'connectionStatusChanged':
      // 处理连接状态变化
    case 'voiceStatusChanged':
      // 处理语音状态变化
    case 'textReceived':
      // 处理文本消息
    case 'error':
      // 处理错误
  }
});
```

## 配置要求

### 依赖配置
已添加到主项目的`pubspec.yaml`:
```yaml
realtime:
  path: local_plugins/realtime
```

### 权限配置
iOS的`Info.plist`已包含必要的麦克风权限：
```xml
<key>NSMicrophoneUsageDescription</key>
<string>需要麦克风权限用于语音识别和录音功能</string>
```

## 与Android示例的对应关系

1. **初始化对应**
   - Android: 创建AudioRecord, AudioTrack, OkHttpClient
   - iOS: 创建AVAudioEngine, AVAudioPlayerNode, URLSession

2. **录音线程对应**
   - Android: `loopRecordSend()` 协程
   - iOS: AVAudioInputNode的installTap回调

3. **播放线程对应**
   - Android: `loopPlayback()` 协程 + LinkedBlockingQueue
   - iOS: DispatchQueue + AVAudioPCMBuffer队列

4. **WebSocket对应**
   - Android: OkHttp WebSocketListener
   - iOS: URLSessionWebSocketDelegate

## 特性支持

✅ **已实现**
- Android和iOS双平台支持
- 实时音频录制和播放（16kHz/16-bit/单声道）
- WebSocket双向通信
- 状态管理和事件通知
- 错误处理
- 资源管理和清理
- 20ms帧长处理
- Kotlin协程和DispatchQueue线程管理

❌ **未实现（可扩展）**
- 音频编码（Opus等）
- 噪声消除/回声抑制
- 自动重连机制
- 音频质量自适应

## 使用注意事项

1. **服务器地址配置**
   ```dart
   // 需要替换为实际的Vocode服务器地址
   serverUrl: 'wss://your-vocode-server/ws'
   ```

2. **音频格式一致性**
   - 确保服务器支持16kHz/16-bit/单声道格式
   - 帧长固定为20ms (320字节)

3. **错误处理**
   - 监听事件流中的错误
   - 处理网络断线和重连

4. **资源管理**
   - 及时调用dispose()释放资源
   - 避免内存泄漏

## 测试建议

1. **本地测试**
   - 先用echo服务器测试WebSocket连接
   - 验证音频录制和播放功能

2. **集成测试**
   - 与真实Vocode服务器集成
   - 测试端到端语音交互

3. **性能测试**
   - 测试长时间使用的稳定性
   - 监控内存和CPU使用

这个实现为DeepVoice项目提供了完整的实时语音交互能力，可以直接与Vocode服务器进行通信，实现类似Android示例的功能。