Tolan/frontend

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. 安装依赖

npm install

2. 配置环境变量

创建 .env.local 文件：

VITE_WS_URL=ws://localhost:8000/ws/realtime

3. 启动开发服务器

npm run dev

应用将在 http://localhost:5173 启动

4. 生产构建

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兼容性处理

const recorder = new VoiceRecorder({
  sampleRate: 16000,
  bitRate: 16,
  onProcess: (pcmData) => {
    // 实时发送PCM数据
    websocket.sendAudio(pcmData.buffer)
  }
})

2. 音频播放

使用 MediaSource API 实现流式播放：

• 边接收边播放
• 支持OGG/Opus格式
• 自动处理缓冲

const player = new StreamAudioPlayer({
  onPlay: () => console.log('播放开始'),
  onEnded: () => console.log('播放结束')
})

// 追加音频块
player.appendAudioChunk(audioData)

3. WebSocket通信

实时双向通信：

• 控制消息（JSON格式）
• 音频数据（二进制格式）
• 自动重连机制

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构建优化

开发命令

# 安装依赖
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