270 lines
6.9 KiB
Markdown
270 lines
6.9 KiB
Markdown
# 🧪 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数据，你可以验证整个语音对话流程的正确性。
|
||
|
||
如有任何问题，请检查浏览器控制台的日志输出，那里会有详细的调试信息。
|
||
|