feat: 优化语音速度

TEST_MODE_GUIDE.md

@@ -0,0 +1,269 @@
+# 🧪 WebSocket语音流测试模式使用指南
+
+## 概述
+
+测试模式允许你在不使用实际录音功能的情况下测试WebSocket语音流式对话功能。这对于在不支持录音的环境（如某些微信小程序开发环境）或需要使用特定测试数据的场景非常有用。
+
+## 启用测试模式
+
+在 `webUI/src/utils/config.js` 中配置：
+
+```javascript
+TEST_MODE: {
+  enabled: true,  // 设置为 true 启用测试模式，false 使用正常录音
+  audioDuration: 3,  // 测试音频时长（秒）
+  sampleRate: 16000,  // 采样率（Hz）
+  channels: 1,  // 声道数（1=单声道，2=立体声）
+  bitDepth: 16  // 位深度（8或16）
+}
+```
+
+## 测试模式特性
+
+### 启用时（enabled: true）
+- ✅ 显示 "🧪 发送测试音频" 按钮
+- ✅ 禁用自动录音功能
+- ✅ 点击按钮发送假数据到WebSocket
+- ✅ 页面提示 "测试模式：点击发送假数据"
+
+### 禁用时（enabled: false）
+- ✅ 隐藏测试按钮
+- ✅ 启用正常录音功能
+- ✅ 自动模式下自动开始录音
+
+## 使用步骤
+
+1. **启用测试模式**
+   ```javascript
+   // 在 config.js 中
+   TEST_MODE: { enabled: true }
+   ```
+
+2. **进入语音模式**
+   - 点击输入框右侧的 🎧 图标切换到语音模式
+
+3. **发送测试数据**
+   - 点击 "🧪 发送测试音频" 按钮
+   - 系统会自动生成假PCM数据并发送到WebSocket服务器
+
+4. **观察结果**
+   - STT识别结果会显示在聊天界面
+   - AI回复会实时流式显示
+   - TTS音频会实时播放
+
+## PCM音频数据格式说明
+
+### 当前生成的测试数据格式
+
+代码会自动生成符合以下规格的PCM数据：
+
+```javascript
+{
+  采样率: 16000 Hz,    // 16kHz，语音常用采样率
+  位深度: 16 bit,      // 16位有符号整数
+  声道数: 1,           // 单声道
+  字节序: Little Endian, // 小端序
+  时长: 3秒,
+  数据大小: 96000 bytes  // = 16000 * 3 * 2
+}
+```
+
+### 测试数据生成原理
+
+代码生成的是一个模拟人声的音频信号：
+- **基频**: 200Hz（人声范围）
+- **泛音**: 包含2次和3次谐波，让声音更丰富
+- **噪声**: 添加轻微随机噪声，模拟呼吸音
+- **包络**: 淡入淡出效果，让声音更自然
+
+### 如果需要使用真实音频文件
+
+如果你想使用真实的音频文件进行测试，需要先将音频转换为PCM格式：
+
+#### 1. 使用FFmpeg转换
+
+```bash
+# 从MP3/WAV转换为PCM
+ffmpeg -i input.mp3 -f s16le -acodec pcm_s16le -ar 16000 -ac 1 output.pcm
+
+# 参数说明：
+# -f s16le: 输出格式为16位小端序PCM
+# -acodec pcm_s16le: 使用16位PCM编码
+# -ar 16000: 采样率16kHz
+# -ac 1: 单声道
+```
+
+#### 2. 在代码中使用真实PCM文件
+
+修改 `ChatBox.vue` 中的 `generateTestPCMAudio()` 函数：
+
+```javascript
+// 方案A: 直接读取PCM文件
+const generateTestPCMAudio = async () => {
+  // #ifdef MP-WEIXIN
+  const fs = uni.getFileSystemManager();
+  return new Promise((resolve, reject) => {
+    fs.readFile({
+      filePath: '/static/test_audio.pcm',  // 你的PCM文件路径
+      success: (res) => {
+        resolve(res.data);  // res.data 是 ArrayBuffer
+      },
+      fail: reject
+    });
+  });
+  // #endif
+};
+
+// 方案B: 从base64字符串加载
+const TEST_PCM_BASE64 = "你的base64编码的PCM数据...";
+const generateTestPCMAudio = () => {
+  return uni.base64ToArrayBuffer(TEST_PCM_BASE64);
+};
+```
+
+#### 3. 获取音频的base64编码
+
+```bash
+# Linux/Mac
+base64 output.pcm > output_base64.txt
+
+# Windows PowerShell
+[Convert]::ToBase64String([IO.File]::ReadAllBytes("output.pcm")) > output_base64.txt
+```
+
+然后将base64字符串复制到代码中。
+
+## PCM数据格式要求
+
+### 必须满足的要求
+
+✅ **格式**: 原始PCM数据（无文件头）  
+✅ **采样率**: 16000 Hz（后端STT服务要求）  
+✅ **位深度**: 16 bit  
+✅ **声道数**: 1（单声道）  
+✅ **字节序**: Little Endian（小端序）  
+✅ **编码**: 有符号整数（Signed Integer）  
+
+### 数据大小计算
+
+```
+数据大小（字节）= 采样率 × 时长（秒）× 声道数 × (位深度/8)
+
+示例：3秒的音频
+= 16000 × 3 × 1 × 2
+= 96000 bytes
+= 93.75 KB
+```
+
+## 注意事项
+
+⚠️ **测试数据限制**
+- 生成的测试数据是简单的合成音，不包含真实语音内容
+- STT识别结果可能为空或乱码（取决于STT服务对合成音的处理）
+- 如需测试真实识别，请使用真实录音的PCM数据
+
+⚠️ **WebSocket模式要求**
+- 测试模式需要配合WebSocket模式使用
+- 确保在 `ChatBox.vue` 中设置 `isWebSocketMode.value = true`
+- 确保WebSocket服务器正在运行
+
+⚠️ **性能考虑**
+- 较长的音频文件会占用更多内存
+- 建议测试音频时长不超过5秒
+- 如需长时间测试，可以循环发送短音频
+
+## 调试技巧
+
+### 查看浏览器控制台
+
+测试模式会输出详细日志：
+
+```
+[TestMode] 生成测试PCM音频: {
+  sampleRate: 16000,
+  duration: "3秒",
+  channels: 1,
+  bitDepth: "16位",
+  dataSize: "96000 bytes",
+  frequency: "200 Hz"
+}
+[TestMode] 开始发送测试音频数据
+[VoiceMode] 测试音频已通过WebSocket发送
+```
+
+### 验证数据格式
+
+在浏览器控制台检查：
+
+```javascript
+// 检查生成的数据
+const data = generateTestPCMAudio();
+console.log('数据类型:', data instanceof ArrayBuffer);
+console.log('数据大小:', data.byteLength, 'bytes');
+console.log('预期大小:', 16000 * 3 * 2, 'bytes');
+```
+
+## 故障排除
+
+### 问题1: 点击按钮无反应
+- 检查是否已进入语音模式（点击🎧图标）
+- 检查是否启用了WebSocket模式
+- 查看浏览器控制台是否有错误
+
+### 问题2: STT识别结果为空
+- 这是正常的，合成音不包含真实语音内容
+- 使用真实PCM录音文件进行测试
+
+### 问题3: WebSocket连接失败
+- 检查后端服务是否运行
+- 检查 `config.js` 中的 `WS_BASE_URL` 配置
+- 检查网络连接和防火墙设置
+
+### 问题4: 音频无法播放
+- 检查返回的TTS音频格式
+- 查看浏览器控制台的音频播放日志
+- 确认播放权限已授予
+
+## 示例代码
+
+### 完整的测试流程示例
+
+```javascript
+// 1. 配置测试模式
+// config.js
+export const API_CONFIG = {
+  TEST_MODE: {
+    enabled: true,
+    audioDuration: 3,
+    sampleRate: 16000,
+    channels: 1,
+    bitDepth: 16
+  }
+};
+
+// 2. 进入语音模式
+toggleVoiceMode(); // 点击🎧图标
+
+// 3. 发送测试数据
+sendTestAudio(); // 点击测试按钮
+
+// 4. 观察回调
+voiceStreamWs.on('sttResult', (text) => {
+  console.log('识别结果:', text);
+});
+
+voiceStreamWs.on('sentence', (sentence) => {
+  console.log('完整句子:', sentence);
+});
+
+voiceStreamWs.on('audioChunk', (audioData) => {
+  console.log('收到音频:', audioData.byteLength, 'bytes');
+});
+```
+
+## 总结
+
+测试模式为你提供了一个便捷的方式来测试WebSocket语音流功能，无需实际录音设备。通过生成符合格式的假PCM数据，你可以验证整个语音对话流程的正确性。
+
+如有任何问题，请检查浏览器控制台的日志输出，那里会有详细的调试信息。
+