220 lines
6.0 KiB
Markdown
220 lines
6.0 KiB
Markdown
# Day 13: TTS 播放优化与事件循环阻塞修复
|
||
|
||
**日期**：2025-12-11
|
||
**目标**：解决 TTS 音频播放断续问题、修复服务器退出问题
|
||
|
||
---
|
||
|
||
## 📅 工作摘要
|
||
|
||
### 1. 核心问题发现 ✅
|
||
|
||
**症状**：TTS 音频播放断断续续，每隔几秒才播放几个字
|
||
|
||
**根因**：`omni_client.py` 中使用**同步迭代器**处理 Omni API 响应，阻塞了整个 asyncio 事件循环
|
||
|
||
```python
|
||
# 问题代码（已修复）
|
||
async def stream_chat(...):
|
||
completion = client.chat.completions.create(stream=True, ...)
|
||
for chunk in completion: # ← 同步迭代，阻塞事件循环！
|
||
yield OmniStreamPiece(...)
|
||
```
|
||
|
||
### 2. Omni 客户端异步化 ✅
|
||
|
||
**修复**：使用 `threading.Thread` + `asyncio.Queue` 解耦同步 API 调用
|
||
|
||
```python
|
||
# 修复后的代码
|
||
async def stream_chat(...):
|
||
queue = asyncio.Queue()
|
||
|
||
def _sync_stream(): # 在独立线程中运行
|
||
for chunk in completion:
|
||
loop.call_soon_threadsafe(queue.put_nowait, OmniStreamPiece(...))
|
||
|
||
thread = threading.Thread(target=_sync_stream, daemon=True)
|
||
thread.start()
|
||
|
||
while True:
|
||
item = await queue.get() # 非阻塞等待
|
||
if item is None: break
|
||
yield item
|
||
```
|
||
|
||
### 3. 客户端 TTS 预缓冲机制 ✅
|
||
|
||
**问题**：即使服务器端修复后，TTS 仍断断续续（Underrun）
|
||
|
||
**原因**：Omni API 每 ~2 秒返回一个音频块，客户端播放速度快于接收速度
|
||
|
||
**解决方案**：在 `main.cpp` 中实现预缓冲机制
|
||
|
||
| 参数 | 值 | 说明 |
|
||
|------|---|------|
|
||
| PRE_BUFFER_FRAMES | 16000 | 预缓冲 1 秒音频再播放 |
|
||
| MIN_PLAY_FRAMES | 8000 | 最小播放阈值 0.5 秒 |
|
||
| 批次大小 | 1600 帧 | 每次播放 100ms |
|
||
|
||
```cpp
|
||
// 客户端预缓冲逻辑
|
||
static std::vector<int16_t> tts_buffer;
|
||
static bool is_buffering = true;
|
||
|
||
// 接收时：追加到缓冲区
|
||
tts_buffer.insert(tts_buffer.end(), samples, samples + frames);
|
||
|
||
// 播放时：积累足够再开始
|
||
if (tts_buffer.size() >= PRE_BUFFER_FRAMES) {
|
||
is_buffering = false; // 开始播放
|
||
}
|
||
```
|
||
|
||
### 4. 服务器退出修复 ✅
|
||
|
||
**问题**：Ctrl+C 后进程挂起，不返回 shell
|
||
|
||
**修复**：在 lifespan 中捕获 CancelledError，并启动强制退出线程
|
||
|
||
```python
|
||
@asynccontextmanager
|
||
async def lifespan(app):
|
||
# ... 启动逻辑 ...
|
||
try:
|
||
yield
|
||
except asyncio.CancelledError:
|
||
pass # Ctrl+C 正常行为
|
||
finally:
|
||
print("[LIFESPAN] 应用关闭完成")
|
||
# 强制退出线程
|
||
def _force_exit():
|
||
time.sleep(0.5)
|
||
os._exit(0)
|
||
threading.Thread(target=_force_exit, daemon=True).start()
|
||
```
|
||
|
||
### 5. 其他修复 ✅
|
||
|
||
- **TTS 上采样**：8kHz → 16kHz（在 `audio_stream.py`）
|
||
- **TTS 缓存机制**：WebSocket 断开时缓存音频，重连后发送
|
||
- **WebSocket 引用保护**：防止模型加载期间 ws 被清空
|
||
|
||
---
|
||
|
||
## 📝 代码变更汇总
|
||
|
||
| 文件 | 变更内容 |
|
||
|------|---------|
|
||
| `omni_client.py` | 使用线程+队列解耦同步 API 调用 |
|
||
| `main.cpp` | 添加 TTS 预缓冲机制 |
|
||
| `app_main.py` | lifespan 捕获 CancelledError + 强制退出线程 |
|
||
| `audio_stream.py` | TTS 上采样、缓存机制、WebSocket 引用保护 |
|
||
|
||
---
|
||
|
||
## 🔴 遗留问题
|
||
|
||
### 1. TTS 音频仍有轻微断续
|
||
|
||
**现象**：
|
||
- 预缓冲后首次播放流畅
|
||
- 后续仍偶发 `Underrun occurred`
|
||
|
||
**根因**：
|
||
- Omni API 流式响应速度慢（每 ~2 秒一个块）
|
||
- 客户端播放速度（实时）> 服务器推送速度
|
||
|
||
**客户端日志示例**：
|
||
```
|
||
[AUD-PLAY] Pre-buffer full, starting playback
|
||
[AUD-PLAY] Played 4000 frames, remaining: 14399
|
||
[AudioPlayer] Underrun occurred, recovering...
|
||
```
|
||
|
||
### 2. WebSocket 仍偶发断开
|
||
|
||
**现象**：长时间对话后出现 `websocket.send after websocket.close`
|
||
|
||
**原因**：模型加载或其他长时间操作期间，WebSocket 超时断开
|
||
|
||
---
|
||
|
||
## 🚀 改进方向
|
||
|
||
### 方案 A：切换到 HTTP `/stream.wav` 模式（推荐）
|
||
|
||
服务器**已支持** `/stream.wav` 端点，参考 ESP32S3 的成功实现：
|
||
|
||
```cpp
|
||
// ESP32 的 HTTP 流式播放（已验证可用）
|
||
WiFiClient cli;
|
||
cli.connect(SERVER_HOST, SERVER_PORT);
|
||
cli.print("GET /stream.wav HTTP/1.1\r\n...");
|
||
// 持续读取 WAV 数据并播放
|
||
```
|
||
|
||
**优势**：
|
||
- HTTP 流比 WebSocket 更稳定
|
||
- 服务器已实现，只需修改客户端
|
||
- ESP32 方案成熟，可直接参考
|
||
|
||
### 方案 B：增大 ALSA 缓冲区
|
||
|
||
当前客户端 ALSA 缓冲区较小（1280 帧 = 80ms），可尝试增大：
|
||
|
||
```cpp
|
||
// 增大 ALSA 缓冲区
|
||
snd_pcm_hw_params_set_buffer_size(handle, params, 16000); // 1秒
|
||
snd_pcm_hw_params_set_period_size(handle, params, 4000); // 250ms
|
||
```
|
||
|
||
### 方案 C：服务器端预生成完整响应
|
||
|
||
在 Omni API 调用前等待完整响应再发送，牺牲首次延迟换取流畅播放：
|
||
|
||
```python
|
||
# 收集完整响应再发送
|
||
full_audio = b""
|
||
async for piece in stream_chat(...):
|
||
full_audio += piece.audio_bytes
|
||
# 一次性发送
|
||
await send_tts(full_audio)
|
||
```
|
||
|
||
---
|
||
|
||
## 🔜 下一步开发
|
||
|
||
1. **实现 HTTP `/stream.wav` 客户端**（~150 行 C++ 代码）
|
||
- 添加 HTTP 客户端线程
|
||
- 解析 WAV 头
|
||
- 读取 chunked 数据并播放
|
||
|
||
2. **测试验证**
|
||
- 验证 HTTP 模式播放流畅度
|
||
- 对比 WebSocket 模式性能
|
||
|
||
3. **摄像头 VBV 缓冲区优化**
|
||
- 继续调整编码参数
|
||
- 减少 `VBV buffer full` 警告
|
||
|
||
---
|
||
|
||
## 📊 测试结果
|
||
|
||
| 测试项 | 修复前 | 修复后 |
|
||
|--------|--------|--------|
|
||
| TTS 块间隔 | 5-15 秒 | ~2 秒 |
|
||
| 首次播放延迟 | 立即 | ~1 秒（预缓冲） |
|
||
| Underrun 频率 | 每块一次 | 偶发 |
|
||
| 服务器退出 | 挂起 | 正常返回 |
|
||
|
||
---
|
||
|
||
## 📂 参考文件
|
||
|
||
- ESP32S3 固件：`AvaotaF1/ESP32S3/compile.ino`（HTTP `/stream.wav` 播放实现）
|
||
- 服务器端点：`audio_stream.py` → `/stream.wav`
|
||
- 客户端代码：`avaota_app_demo/src/main.cpp`
|