# Realtime 实时语音聊天模块

## ⚠️ 当前状态

**此模块为功能预览版本，提供完整的实时语音对话功能。**

通过原生插件实现语音识别、AI对话和语音合成的完整语音交互体验。

## 概述

Realtime模块实现了类似ChatGPT app的实时语音对话功能，当前版本提供：

- ✅ **完整语音交互** - 实时语音识别、AI对话和语音合成
- ✅ **状态管理** - 聆听、思考、回答状态的可视化
- ✅ **动画效果** - 基于Shader的流动云效果，支持音频振幅驱动
- ✅ **字幕显示** - 可选择开启/关闭的字幕模式
- ✅ **智能UI** - 根据连接状态自动调整按钮可用性

## 界面设计

### 布局结构
- **顶部状态区域** - 显示当前状态和字幕模式切换按钮
- **中间可视化区域** - 圆形Shader动画，根据音频振幅呈现呼吸效果
- **底部控制区域** - 主控制按钮和状态指示器

### 状态指示
- 🔵 **聆听状态** - 蓝色动画，接收用户语音输入
- 🟠 **思考状态** - 橙色动画，AI处理中
- 🟢 **回答状态** - 绿色动画，AI语音输出
- ⚪ **空闲状态** - 灰色静态，等待交互

### 字幕模式
- **默认关闭** - 初始状态下不显示任何字幕内容
- **手动切换** - 通过右上角按钮手动开启/关闭字幕
- **完整隐藏** - 关闭时字幕区域完全不显示，不占用界面空间
- **智能布局** - 开启时圆形动画自动上移，字幕区域占据下半屏

### 交互控制
- **录音按钮** - 仅在成功连接AI服务器且开始录音后可用
- **连接状态** - 未连接时录音按钮显示不可用状态
- **状态反馈** - 按钮颜色和可点击性根据连接状态动态调整

## 使用方法

### 路由导航

```dart
// 跳转到实时语音对话页面
Get.toNamed(Routes.realtime);
```

### 交互流程

1. **自动连接** - 页面加载后自动尝试连接AI服务器
2. **等待连接** - 录音按钮在连接成功前保持不可用状态
3. **开始录音** - 连接成功后自动开始录音，录音按钮变为可用
4. **语音对话** - 用户说话 → AI处理 → 语音回复
5. **字幕控制** - 可随时通过右上角按钮切换字幕显示

## 技术架构

### 控制器 (RealtimeController)
- **连接管理**: WebSocket连接到AI服务器
- **状态同步**: `isConnected`, `isListening`, `isSpeaking`
- **字幕控制**: `isSubtitleMode` 默认为false，用户手动控制
- **消息管理**: 智能去重，避免流式响应重复显示
- **音频处理**: 原生层计算RMS值，Flutter层接收并控制动画

### 视图组件
- **RealtimeView** - 主视图容器，响应式布局
- **ShaderMicFlow** - 基于GLSL Shader的流动云动画组件
- **AutoScrollList** - 自动滚动的字幕列表

### 原生集成
- **RealtimeService** - 原生音频处理和WebSocket通信
- **音频格式** - 16kHz, 1声道, 16位PCM
- **实时传输** - 低延迟音频流处理
- **RMS计算** - 原生层实时计算音频振幅

## 默认行为

### 字幕模式
- **初始状态**: 关闭 (`isSubtitleMode.value = false`)
- **显示逻辑**: 仅在用户手动开启时显示字幕内容
- **空间占用**: 关闭时字幕区域高度为0，不影响其他UI元素
- **切换效果**: 平滑动画过渡，圆形动画位置和大小同步调整

### 按钮状态
- **录音按钮**: 默认不可用，连接成功且开始录音后才可点击
- **状态指示**: 通过颜色和图标变化反映当前可用性
- **交互反馈**: 不可用时点击无效果，避免误操作

## 开发计划

### 已完成功能 ✅
- [x] 完整语音交互流程
- [x] 实时WebSocket通信
- [x] Shader流动云动画
- [x] RMS音频振幅计算
- [x] 智能UI状态管理
- [x] 字幕模式控制
- [x] 消息去重优化

### 计划增强 ⏳
- [ ] 多语言语音识别
- [ ] 语音中断检测
- [ ] 音频质量自适应
- [ ] 离线降级处理
- [ ] 语音情感识别

## 注意事项

1. **网络依赖** - 需要连接到AI服务器 (ws://192.168.1.11:8000/ws)
2. **麦克风权限** - 需要获取麦克风使用权限
3. **音频会话** - 自动管理音频会话，支持蓝牙设备
4. **资源管理** - 页面关闭时自动清理音频资源和网络连接

## 自定义配置

### 修改服务器地址

```dart
// 在RealtimeController中修改连接URL
await _realtimeService.initialize(
  serverUrl: 'ws://your-server:port/ws',
  // ... 其他参数
);
```

### 调整UI布局

```dart
// 修改字幕模式下圆形动画位置
alignment: controller.isSubtitleMode.value 
    ? const Alignment(0, -0.9)  // 调整Y轴位置
    : const Alignment(0, -0.25),
```

### 音频参数调优

```dart
// 在初始化时调整音频参数
sampleRate: 16000,    // 采样率
channels: 1,          // 声道数
bitsPerSample: 16,    // 位深度
```

## 技术栈

- **Flutter SDK**: >= 3.0.0
- **GetX**: >= 4.6.5 (状态管理)
- **Flutter Shaders**: >= 0.0.6 (Shader动画)
- **原生插件**: Realtime服务 (音频处理)
- **WebSocket**: 实时通信协议

## 版本信息

- **当前版本**: v1.0.0 (Production)
- **最后更新**: 2024年
- **状态**: 完整功能实现