02 — 架构

进程模型

Vocal10n 由两个协作进程运行：

flowchart LR
    App["vocal10n.app<br/>(venv_main)<br/>PySide6 UI · STT · LLM"]
    SoVITS["GPT-SoVITS api_v2.py<br/>(venv_tts subprocess)"]
    Qwen3["Qwen3-TTS server<br/>(venv_qwen3tts subprocess)"]
    OBS["OBS Browser Source"]

    App <-->|"HTTP :9880"| SoVITS
    App <-.->|"HTTP (alt backend)"| Qwen3
    App -->|"HTTP :5124"| OBS

选择 Qwen3-TTS 后端时，会从 vocal10n.tts.qwen3_server 启动额外托管子进程。任意时刻仅有一个 TTS 后端激活；UI 通过 tts_container_tab 切换。

线程模型

主进程由 Qt 主线程和少量工作线程组成。边界由 vocal10n.pipeline.events 中的 EventDispatcher（发布/订阅）定义。

线程	所属	职责
Qt 主线程	QApplication	UI、signal/slot 分发、SystemState 读写
STTWorker	vocal10n.stt.worker	拉取音频帧、运行 Whisper、发布文本事件
AudioCapture 回调	sounddevice	麦克风块 → 环形缓冲 + AEC
LLMWorker（位于 LLMController）	vocal10n.llm.controller	翻译 confirmed 与 pending 文本
TTSQueue 工作线程	vocal10n.tts.queue	拉取翻译文本并调用 TTS HTTP API
音频播放线程	vocal10n.tts.audio_output	sounddevice 输出流 + 交叉淡化
文件写入线程	vocal10n.pipeline.file_writer	异步 SRT/TXT/WAV I/O
GPU 监控线程	vocal10n.utils.gpu	周期性采样显存/利用率

SystemState（vocal10n.state.SystemState）是带 threading.RLock 的 QObject。每个属性 setter 都会发出 Qt 信号，UI 组件无需轮询即可绑定。

数据流（Happy Path）

flowchart TD
    Mic(["mic chunk"]) --> Cap["AudioCapture<br/>16 kHz mono · 0.2 s"]
    Cap --> AEC["AEC<br/>NLMS + double-talk detector"]
    AEC --> Whisper["Whisper sliding window<br/>window_seconds = 6.5"]
    Whisper --> Segs["STTEngine.transcribe<br/>SegmentResult[]"]
    Segs --> Filt["HallucinationFilter<br/>dedup · phonetic correction"]

    Filt --> Partial{{"STT_PARTIAL"}}
    Filt --> Confirmed{{"STT_CONFIRMED"}}

    Partial --> OBSlive["OBS overlay<br/>(live)"]

    Confirmed --> LLMp["LLMController.translate_pending"]
    Confirmed --> LLMc["LLMController.translate_confirmed"]

    LLMp --> TPartial{{"TRANSLATION_PARTIAL"}}
    LLMc --> TConfirmed{{"TRANSLATION_CONFIRMED"}}

    TPartial --> OBSlive
    TConfirmed --> Q["TTSQueue.enqueue"]
    TConfirmed --> FW["FileWriter<br/>TXT · SRT"]
    TConfirmed --> OBS2["OBS overlay<br/>(confirmed)"]

    Q --> HTTP["TTS HTTP"] --> Play["AudioPlayer"]

模块映射

src/vocal10n/
├── app.py              # 入口：创建 QApplication、主题、状态、MainWindow。
├── config.py           # YAML 加载、点号键访问、get_config 单例。
├── constants.py        # 枚举：Language、ModelStatus、EventType。
├── state.py            # SystemState QObject（线程安全、发信号）。
│
├── stt/
│   ├── audio_capture.py
│   ├── playback_aec.py
│   ├── engine.py
│   ├── filters.py
│   ├── transcript.py
│   ├── diarizer.py
│   ├── controller.py
│   └── worker.py
│
├── llm/
│   ├── engine.py
│   ├── api_backend.py
│   ├── corrector.py
│   ├── translator.py
│   ├── rag.py
│   └── controller.py
│
├── tts/
│   ├── client.py
│   ├── server_manager.py
│   ├── queue.py
│   ├── audio_output.py
│   ├── controller.py
│   ├── qwen3_server.py
│   ├── qwen3_client.py
│   └── qwen3_controller.py
│
├── pipeline/
│   ├── events.py
│   ├── coordinator.py
│   ├── latency.py
│   └── file_writer.py
│
├── obs/
│   ├── server.py
│   └── overlay.html
│
├── ui/
│   ├── main_window.py
│   ├── section_a.py
│   ├── section_b.py
│   ├── tabs/
│   ├── widgets/
│   └── styles/theme.qss
│
└── utils/
    ├── gpu.py
    └── logger.py

完整仓库目录见 03 — 仓库结构。