# Tolan 语音助手 - 前端 这是Tolan语音助手的前端应用,使用React + TypeScript + Vite构建。 ## 功能特性 - ✅ 实时语音录音(使用Recorder.js) - ✅ 流式音频播放(MediaSource API) - ✅ WebSocket实时通信 - ✅ 动画IP三态展示(待机/倾听/说话) - ✅ 低延迟优化(目标<300ms) - ✅ 跨浏览器兼容(支持PC和移动端) ## 技术栈 - **框架**: React 18 + TypeScript - **构建工具**: Vite 5 - **状态管理**: Zustand - **样式**: Tailwind CSS - **录音**: recorder-core (xiangyuecn/Recorder) - **播放**: MediaSource API (流式播放OGG/Opus) ## 快速开始 ### 1. 安装依赖 ```bash npm install ``` ### 2. 配置环境变量 创建 `.env.local` 文件: ```bash VITE_WS_URL=ws://localhost:8000/ws/realtime ``` ### 3. 启动开发服务器 ```bash npm run dev ``` 应用将在 http://localhost:5173 启动 ### 4. 生产构建 ```bash npm run build ``` 构建产物将输出到 `dist/` 目录 ## 项目结构 ``` frontend/ ├── src/ │ ├── components/ # React组件 │ │ ├── MainPage.tsx # 主页面 │ │ ├── AnimatedCharacter.tsx # 动画IP组件 │ │ └── RecordButton.tsx # 录音按钮 │ │ │ ├── stores/ # Zustand状态管理 │ │ └── appStore.ts # 应用状态 │ │ │ ├── utils/ # 工具模块 │ │ ├── websocket.ts # WebSocket通信 │ │ ├── recorder.ts # 音频录音 │ │ └── audioPlayer.ts # 音频播放 │ │ │ ├── config.ts # 配置文件 │ ├── App.tsx # 根组件 │ ├── main.tsx # 入口文件 │ └── index.css # 全局样式 │ ├── public/ # 静态资源 ├── index.html # HTML模板 ├── package.json ├── tsconfig.json ├── vite.config.ts └── tailwind.config.js ``` ## 核心功能说明 ### 1. 音频录音 使用 `recorder-core` 实现跨平台录音,支持: - PCM格式输出(16kHz, 16bit, 单声道) - 实时数据流 - iOS兼容性处理 ```typescript const recorder = new VoiceRecorder({ sampleRate: 16000, bitRate: 16, onProcess: (pcmData) => { // 实时发送PCM数据 websocket.sendAudio(pcmData.buffer) } }) ``` ### 2. 音频播放 使用 MediaSource API 实现流式播放: - 边接收边播放 - 支持OGG/Opus格式 - 自动处理缓冲 ```typescript const player = new StreamAudioPlayer({ onPlay: () => console.log('播放开始'), onEnded: () => console.log('播放结束') }) // 追加音频块 player.appendAudioChunk(audioData) ``` ### 3. WebSocket通信 实时双向通信: - 控制消息(JSON格式) - 音频数据(二进制格式) - 自动重连机制 ```typescript const ws = new RealtimeWebSocket({ url: 'ws://localhost:8000/ws/realtime', onMessage: handleControlMessage, onAudioData: handleAudioData }) ``` ### 4. 状态管理 使用 Zustand 管理应用状态: - 动画状态(IDLE/LISTENING/SPEAKING) - 录音/播放状态 - 连接状态 - 错误处理 ## 使用说明 1. **连接服务器**: 应用启动时自动连接WebSocket服务器 2. **按住说话**: 按住录音按钮开始录音 3. **松开接收**: 松开按钮停止录音,等待AI回复 4. **实时播放**: AI回复音频实时播放 ## 浏览器兼容性 - Chrome 90+ - Safari 14+ - Firefox 88+ - Edge 90+ - iOS Safari 14+ - Android Chrome 90+ ## 注意事项 1. **HTTPS要求**: 现代浏览器要求HTTPS才能访问麦克风 - 开发环境使用 localhost 自动信任 - 生产环境需要配置SSL证书 2. **iOS兼容**: iOS需要在用户交互中初始化录音 - 首次使用需要点击激活 3. **音频格式**: - 上行:PCM (16kHz, 16bit, 单声道) - 下行:OGG/Opus ## 性能优化 - 代码分割(React.lazy) - 资源懒加载 - Tailwind CSS按需打包 - Vite构建优化 ## 开发命令 ```bash # 安装依赖 npm install # 启动开发服务器 npm run dev # 生产构建 npm run build # 预览生产构建 npm run preview # 代码检查 npm run lint ``` ## 故障排查 ### 1. 麦克风权限被拒绝 - 检查浏览器权限设置 - 确保使用HTTPS或localhost ### 2. WebSocket连接失败 - 检查后端服务是否启动 - 确认WebSocket URL配置正确 ### 3. 音频无法播放 - 检查浏览器是否支持OGG/Opus - 确认MediaSource API可用 ## 许可证 MIT