06 — 管道与状态

本章说明让各模块松耦合协作的跨模块基础设施。

SystemState — 单一事实源

vocal10n.state.SystemState 是一个 QObject，承载 UI 关注的所有状态：模型状态、启用标记、语言以及四个实时文本缓冲区（当前/累计 × 源/翻译）。

关键属性：

• stt_status、llm_status、tts_status、tts_qwen3_status：ModelStatus（UNLOADED、LOADING、LOADED、ERROR）。
• stt_enabled、llm_enabled、tts_enabled、tts_source_enabled、tts_target_enabled、speaker_tagging。
• source_language、target_language：Language 枚举。
• current_*_text、accumulated_*_text：由工作线程更新的字符串。

每个属性都配套 *_changed Qt 信号，仅在值实际变化时触发。UI 组件订阅这些信号，工作线程通过内部 RLock 保护的 setter 写入。

Event Dispatcher

vocal10n.pipeline.events 定义：

• EventType（在 vocal10n.constants）—— 如 STT_PARTIAL、STT_CONFIRMED、TRANSLATION_PARTIAL、TRANSLATION_CONFIRMED、TTS_STARTED、TTS_FINISHED、PIPELINE_READY。
• 数据类载荷：Event、TextEvent、TranslationEvent。
• EventDispatcher：线程安全 subscribe(type, callback) / publish(event)，通过 get_dispatcher() 获取。

模块只需发布和订阅自己关心的事件，从而实现 STT、LLM、TTS 的解耦。

Latency Tracker

vocal10n.pipeline.latency.LatencyTracker 以 utterance id 为键记录各阶段时间戳，并给 UI 提供滚动窗口聚合指标：

• stt_partial_ms：麦克风帧到首个 partial。
• stt_confirmed_ms：麦克风帧到 confirmed。
• translation_ms：confirmed 到翻译结果。
• tts_ttfa_ms：翻译到首帧可听音频（TTFA）。

PipelineCoordinator

vocal10n.pipeline.coordinator.PipelineCoordinator 管理会话生命周期，而非逐事件业务流：

• start_session()：若任一 output.* 开关开启，则创建 FileWriter，订阅 STT_CONFIRMED 与 TRANSLATION_CONFIRMED，并发布 PIPELINE_READY。
• stop_session()：刷新缓冲、取消订阅写入器、收尾 SRT/TXT/WAV。
• 可持有 AudioCapture 引用，让 WAV 写入器按正确会话偏移读取环形缓冲。

协调器不负责模型加载/卸载，这部分在各模块 controller 内。

模块 Controller

UI 与下列 controller 交互：

• vocal10n.stt.controller.STTController：加载/卸载、语言切换、启停，持有 STTWorker。
• vocal10n.llm.controller.LLMController：加载/卸载、prompt 更新、KB 热重载、防抖翻译。
• vocal10n.tts.controller.TTSController：GPT-SoVITS 路径（服务健康、队列、播放）。
• vocal10n.tts.qwen3_controller.Qwen3TTSController：Qwen3-TTS 的等价控制面。

controller 是 UI tab 持有的唯一业务入口，负责写入 SystemState 并订阅 dispatcher 事件。