# 常见问题

## 点 `✕` 之后窗口不见了

这是设计如此：**`✕` 是隐藏到托盘**，不是退出（否则关掉就再也没法打开了）。
用托盘菜单的「显示/隐藏字幕」或单击托盘图标可以再显示回来；要退出用托盘菜单的「退出」。

如果连托盘图标也没有（桌面环境不支持托盘，或用 `--no-tray` 启动），`✕` 会直接退出程序。

## 首次启动弹出设置对话框

没有「已下载且被选中」的模型时，程序必须先让你准备一个模型才能工作，所以会先弹设置。
在「模型」页选一个模型点「下载」，然后在「当前使用」里选中它，点「确定」即可。
直接点「取消」= 放弃启动（程序退出）。

## 没有字幕 / 转写全是空白

按顺序排查：

1. **系统真的在播放声音吗？** 采集的是「正在播放的音频」，没有播放就没有字幕。
2. **采集设备是否选错？** 默认跟随**系统默认输出**。如果声音是从 HDMI 出去的、而默认输出是
   Speaker（或反过来），就会采到静音。用 `--list-devices` 看有哪些设备，在设置里显式指定一个。
   ```bash
   ./build/live-caption-cli --list-devices
   ```
3. **音量和静音状态**：确认系统和该应用的音量不为 0、没有静音。
4. 从终端启动看输出，采集/加载失败会打印原因：
   ```bash
   ./build/live-caption      # 或 ./build/live-caption-cli --cli-live ...
   ```

## 提示「模型未安装」/ 缺失某些文件

模型文件不完整。两种办法：

- 在设置对话框里选中该模型 → 「校验完整性」看哪些文件坏了 → 「删除」后重新「下载」；
- 命令行：`./build/live-caption-cli --verify-model <id>` 查看，`./scripts/fetch-models.sh <id>` 重新下。

## 「校验失败，损坏的文件: …」

说明文件内容与注册表里的 sha256 对不上（下载被截断、磁盘问题等）。在设置里**删除该模型再重新下载**
即可。下载支持断点续传，网络抖动不会前功尽弃。

## 下载很慢 / 下载失败

- 默认下载源是 `https://hf-mirror.com`（实测可达性最好）。可在设置里换成别的镜像或官方源。
- 需要走代理时，在设置里把「代理」设为「跟随系统」或「手动设置」并填主机/端口/账号。
- 大模型有几百 MB～1GB，首次下载慢是正常的；同一个文件不会重复下载。

## 日语 / 其它语言效果不好

这是模型能力问题，不是 bug。结论见 [asr-backends.md](asr-backends.md#推荐组合按语言装包) 的推荐组合：

| 语言 | 建议 |
|---|---|
| 中文 | `zipformer-zh-2025`（最快最准）或 X-ASR |
| 英文 | `xasr-zh-en-480` |
| 日语 | `nemotron35-560ms` + 设置里把「识别语言」改成**日语**（不指定语言会串） |
| 其它 | `qwen3-asr-0.6b-q8`（52 语言兜底，CPU 占用高但最准） |

注意：多语言模型（Nemotron / Qwen3-ASR）**要在设置里选对语言**，否则「自动」可能识别成别的语言。

## Wayland 下窗口不置顶 / 位置不对

X11 下正常。Wayland 没有通用的「置顶悬浮层」协议，需要 `wlr-layer-shell`，属于 Phase 5。
当前建议在 X11 会话下使用。

## 构建时警告「未找到 sherpa-onnx，流式 ONNX 后端将不可用」

正常，说明流式后端被跳过了。要启用：

```bash
ls ~/.local/opt/sherpa-onnx/include/sherpa-onnx/c-api/c-api.h
cmake -S . -B build -DSHERPA_ONNX_ROOT=$HOME/.local/opt/sherpa-onnx
```

它需要自带的 `libonnxruntime.so`（`ldd build/live-caption` 可以确认解析到了）。

## 启动时打印 `setHighDpiScaleFactorRoundingPolicy must be called…`

与本事无关：一个 5 行的空白 Qt 程序在同样的会话里也会打印。是桌面会话设了
`QT_SCALE_FACTOR_ROUNDING_POLICY` 导致的，可以忽略。

## Qwen3-ASR 的 GGUF 装不进去（加载失败）

模型与运行时**必须锁版本**：只有 ggml-org 官方 GGUF（`general.architecture = qwen3vl`）能用；
社区量化常见的是 `qwen3asr` / `qwen3_asr`，不兼容。细节见
[phase0-verification.md](phase0-verification.md)。

## 点了「确定」程序就退出了

这是早期版本的一个 bug（`QApplication` 默认「最后一个窗口关闭 = 退出」，而首次启动时设置对话框
正是唯一窗口），**已经修好**。如果还在复现，请重新构建后再试；仍复现请附上
`coredumpctl info <PID>` 的调用栈。