# Speechmatics STT 集成失败记录 (2026-03-03)

## 结论

**Speechmatics 的 livekit-plugins-speechmatics 插件完全不可用。**
经过一整天的深度集成和调试，四种 Turn Detection 模式全部失败，没有任何一种能在
LiveKit agents 框架 v1.4.4 下正常工作。该方案已被彻底移除，STT 回退至 OpenAI。

## 测试的四种 Turn Detection 模式及失败原因

### 1. EXTERNAL 模式
- **现象**: 只有 INTERIM_TRANSCRIPT，永远没有 FINAL_TRANSCRIPT
- **原因**: EXTERNAL 模式需要客户端手动调用 `client.finalize()` 才会产生 FINAL。
  但 LiveKit agents 框架在 VAD 检测到说话结束后**不调用** `stream.flush()`
  （不发 FlushSentinel），而是推送静音帧 + 等待 FINAL 事件。
  结果: 2 秒超时 → "final transcript not received" → 用户无回复。
- **尝试的修复**: monkey-patch `_process_audio` 在 FlushSentinel 时调用 finalize()
  → 但 FlushSentinel 根本不会到达（框架不发 flush）
- **尝试的修复 2**: debounce timer，partial 停止 400ms 后自动 promote 为 FINAL
  → 能工作但产生重复 FINAL，每个 FINAL 触发 LLM 请求导致前一个被 abort

### 2. ADAPTIVE 模式
- **现象**: 零转写输出，完全静默
- **原因**: ADAPTIVE 使用 Speechmatics SDK 内置的 Silero VAD 做客户端转弯检测，
  但 LiveKit 自己也有 Silero VAD 在运行，两个 VAD 冲突导致音频流被截断

### 3. SMART_TURN 模式
- **现象**: 连续语音被切成碎片（"有好结果。"、"收？的知识。"、"就。"）
- **原因**: 服务器端智能转弯检测过于激进，把中文连续语音切成小段，
  每段各自产生一个 FINAL_TRANSCRIPT，每个 FINAL 触发一次 LLM 请求，
  前一个请求被 abort，实测完全不可用

### 4. FIXED 模式（最后尝试）
- **配置**: `end_of_utterance_silence_trigger=1.0`（1秒静音后 finalize）
- **现象**: 仍然不工作
- **原因**: VoiceAgentClient 内置的 END_OF_UTTERANCE handler 调用 finalize()，
  但 finalize() 是异步链（create_task → emit() → _stt_message_queue → _emit_segments），
  经常输掉与 session teardown 的竞争

## 额外发现的问题

### 语言码兼容性
- Speechmatics 使用 ISO 639-3（中文为 "cmn"），LiveKit 的 `LanguageCode("cmn")`
  会自动归一化为 "zh"，而 Speechmatics API 不接受 "zh"
- 需要手动 `stt._stt_options.language = "cmn"` 绕过

### 延迟
- 即使在能产生转写的情况下，Speechmatics 的延迟也明显高于 OpenAI
- OpenAI Realtime API (gpt-4o-transcribe) 约 10 秒端到端，Speechmatics 超过 35 秒

## 时间线
- 09:00 开始集成 livekit-plugins-speechmatics
- 10:00 解决语言码映射问题
- 11:00 发现 EXTERNAL 模式无 FINAL，开始 monkey-patch
- 13:00 发现 FlushSentinel 永远不到达，理解框架架构
- 14:00 实现 debounce timer，能转写但有重复问题
- 15:00 搜索官方文档，切换到 SMART_TURN → 语音碎片化
- 16:00 切换到 FIXED 模式 → 仍然不工作
- 17:00 放弃，彻底移除所有 Speechmatics 代码，回退至 OpenAI

## 删除的文件
- `src/plugins/speechmatics_stt.py` — 整个 Speechmatics STT 工厂
- `requirements.txt` 中的 `livekit-plugins-speechmatics>=1.0.0`
- `agent.py` 中的 speechmatics 分支
- `docker-compose.yml` 中的 `SPEECHMATICS_API_KEY`
- `voice-config.entity.ts` 和 `voice-config.controller.ts` 中默认值改为 'openai'
- web-admin 设置页中的 Speechmatics 选项和 i18n 翻译