# 🧪 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数据，你可以验证整个语音对话流程的正确性。

如有任何问题，请检查浏览器控制台的日志输出，那里会有详细的调试信息。