# 图形界面（Phase 4）

`live-caption` 是图形界面程序：悬浮字幕窗 + 系统托盘 + 设置对话框。
**不用任何命令行参数就能完整使用**；命令行参数只保留给自动化测试（显式给出时覆盖设置）。

## 首次运行

首次启动时如果还没有「已下载且被选中」的模型，程序会先弹出**设置对话框（标题为
「实时字幕 — 首次配置」）**，并挡住主流程 —— 下载一个模型、在「当前使用」里选中它，
点「确定」之后才会出现字幕窗。

```
第一次启动 → 设置对话框 → 下载模型 → 选择「当前使用」 → 确定 → 悬浮字幕窗
```

## 字幕窗

| 操作 | 行为 |
|---|---|
| 拖动 | 移动窗口；位置会被记住 |
| 左上角语言标签 | 点击 → 打开设置对话框 |
| 底部箭头 `⌄` / `⌃` | 折叠（2 行）/ 展开（8 行） |
| 右上角 `✕` | **隐藏到托盘**（不是退出；用托盘菜单可以再显示回来） |

窗口的文本分两段显示：**已稳定**部分是白色，**尚未稳定**的尾部是灰色。这就是 Chrome
实时字幕那种「字一个个长出来、末尾会改」的观感。

> 没有托盘时（`--no-tray`，或桌面环境不支持托盘）`✕` 会直接退出程序。

## 托盘

托盘菜单有三项：

- **显示/隐藏字幕**
- **设置…**
- **退出**

单击托盘图标也会切换字幕窗的显示/隐藏。

## 设置对话框

三个页签（模型 / 显示 / 高级），底部三个按钮：

| 按钮 | 行为 |
|---|---|
| **应用** | 应用设置但**不关闭**对话框 —— 方便实时预览（改不透明度、字号时立刻能看到效果） |
| 取消 | 放弃本次改动（已经用「应用」生效过的改动不会被回滚） |
| 确定 | 应用并关闭 |

**哪些改动要重启识别后端？** 只有**模型 / 识别语言 / 采集设备**，以及高级页里的**流式参数、
线程数、模型目录**变化时才会重建后端并重启转写；透明度、字号、行数、灰色尾部这类外观改动是
即时生效的，不会打断正在进行的转写。

### 模型页

- **模型表格**：列出注册表里的所有模型（名称 / 语言 / 许可 / 状态）。第一列是注册表 id，
  状态列显示「已安装 / 未安装」，未安装时鼠标悬停会列出缺失的文件名。
- **下载**：把选中的模型下到 `~/.local/share/live-caption/models/<id>/`。
  支持设置下载源（镜像）与代理、断点续传、实时进度。下载完成会自动刷新列表。
- **校验完整性**：对选中模型的所有文件**重算 sha256**，与注册表里的期望值比对；
  失败会列出损坏的文件名（可删除后重新下载）。文件大时需要几秒。
- **删除**：删掉该模型已下载的文件。如果删的正是「当前使用」的模型，选择会被清空。
- **打开模型目录**：在文件管理器里打开模型存储目录。
- **采集设备**：默认「跟随系统默认输出」（即当前默认输出的 monitor）。
  也可以指定某个具体输出设备（如 HDMI）；列不出来或没列全时见
  [troubleshooting.md](troubleshooting.md)。
- **当前使用**：选择实际生效的模型（只列出**已安装**的）。
- **识别语言**：语言提示，多语言模型用它（例如 Nemotron 需要指定语言才不出错）；
  「自动检测」= 留空。目前提供 自动/中文/英文/日语。
- **下载源**：默认 `https://hf-mirror.com`（网络可达性最好的镜像）；可改成其它镜像或官方源。
- **代理**：不使用 / 跟随系统 / 手动设置（主机、端口、用户名、密码）。

### 显示页

| 项 | 说明 |
|---|---|
| 字号 | 字幕文字大小（9–40） |
| 用灰色显示尚未稳定的尾部 | 关掉后就只显示已稳定的文本 |
| 折叠行数 / 展开行数 | 折叠态与展开态各显示几行 |
| 背景不透明度 | 20%–100%，默认 84%（纯黑底，保证任何桌面背景下文字都可读） |

### 高级页

**通用**

| 项 | 说明 |
|---|---|
| 更新粒度（秒） | 累积多少秒音频跑一步；「自动」= 由后端决定（流式模型 0.32s） |

**流式（只影响 Qwen3-ASR）** —— 这一组对应 llama 后端的流式参数，改动会重启识别后端。
选了流式 ONNX 模型（zipformer / X-ASR / Nemotron）时整组会**置灰**，因为那些模型只用「更新粒度」。

| 项 | 对应命令行 | 说明 |
|---|---|---|
| 策略 | `--stream-mode` | `incremental`（增量复用，1~2 秒就出字，推荐）/ `append`（追加式，成本平坦但需要大 chunk）/ `window`（早期的对比实现） |
| 滑窗上限（秒） | `--stream-window` | 仅 window 模式；「不限」= 不滑窗 |
| 单段最长时长（秒） | `--stream-segment` | 超过就提交并重置上下文；「不限」= 不设上限 |
| 前缀回滚 token 数 | `--unfixed-tokens` | 回滚丢弃最后 N 个 token —— 它们会显示成灰色的不稳定尾部 |
| 冷启动 chunk 数 | `--unfixed-chunks` | 前 N 个 chunk 不带前缀，避免开头重复 |
| 单段最多生成 token | `--max-tokens` | 单段生成的 token 上限 |
| 线程数 | `--threads` | 只影响 Qwen3-ASR；流式模型固定单线程（多线程反而更慢） |

**调试**

| 项 | 对应命令行 | 说明 |
|---|---|---|
| 输出详细日志 | `--verbose` | 打印 llama.cpp / mtmd 的详细日志（排查加载/推理问题时用） |
| 模型目录 | `--model-dir` | 留空 = 默认目录（占位符会显示实际路径）；一般不需要改 |

## 配置文件

所有设置存在 `QSettings` 里：`~/.config/live-caption/live-caption.conf`，组名 `[app]`。

```ini
[app]
modelId=zipformer-zh-2025      ; 当前使用的模型 id
language=                      ; 空 = 自动
captureDevice=                 ; 空 = 跟随系统默认输出
opacity=84  fontSize=15        ; 外观
showUnstableTail=true
collapsedLines=2  expandedLines=8
windowX=179  windowY=725       ; 拖动后记录的位置
mirrorBase=https://hf-mirror.com
proxyMode=0                    ; 0=不使用 1=跟随系统 2=手动
chunkSec=0  threads=8          ; 高级
streamMode=incremental         ; 高级：流式参数（只影响 Qwen3-ASR）
streamWindowSec=16  streamSegmentSec=30
unfixedTokens=5  unfixedChunks=2  maxTokens=256
verbose=false  modelDir=       ; 高级：调试
```

删掉这个文件（或其中某个键）就回到默认值。模型文件在
`~/.local/share/live-caption/models/<id>/`，不受这个文件影响。

## 自动化测试钩子（仅测试用）

界面本身的行为可以完全用命令行脚本驱动，这些选项平时用不到：

```bash
# 打开设置对话框并截图后退出
./build/live-caption --screenshot-settings /tmp/settings.png

# 自动关掉设置对话框，用来测「关闭/确定/取消/应用」各条路径是否崩溃
./build/live-caption --asr-model zipformer-zh-2025 --no-tray \
    --settings-autoclose {reject|close|accept|ok|apply} --quit-after 8

# 字幕窗自截图（折叠态 + 展开态）
./build/live-caption --asr-model zipformer-zh-2025 --no-tray \
    --screenshot /tmp/win.png --screenshot-delay 6
```

完整列表见 [cli.md](cli.md)。