blumia
d234b9658d
The README still listed the settings UI as "todo" and its quick start told users to download models into the working directory; phase 3 still described the caption window's close button as "quit" and used the wrong binary name. Bring the docs up to date and fill the gaps: a GUI guide (first run, settings tabs, tray, download, verify), a full CLI option reference marking the test-only flags, a troubleshooting page, the model registry's size/sha256 fields plus a licence/size table, the RTF measurement caveat (llama-cli 0.19 vs the in-process 0.56), and a note that the streaming-ONNX backend has its own code path. phase0/phase1 experiment docs are marked as historical. 文档与现状对齐：README 的 Phase 4 从「待做」改为完成、快速开始不再让人把模型下到当前 目录；phase3 的 ✕ 说明改为「隐藏到托盘」、用法改用 live-caption；新增 GUI/CLI/排错三份 文档；asr-backends 补上注册表的 size/sha256 字段与模型许可/体积表；phase0 补上 RTF 口径 说明（llama-cli 的 0.19 与程序内的 0.56）；phase2 补上「流式 ONNX 走另一条分支」的说明。
95 lines
4.4 KiB
Markdown
95 lines
4.4 KiB
Markdown
# 常见问题
|
||
|
||
## 点 `✕` 之后窗口不见了
|
||
|
||
这是设计如此：**`✕` 是隐藏到托盘**，不是退出（否则关掉就再也没法打开了）。
|
||
用托盘菜单的「显示/隐藏字幕」或单击托盘图标可以再显示回来；要退出用托盘菜单的「退出」。
|
||
|
||
如果连托盘图标也没有（桌面环境不支持托盘，或用 `--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>` 的调用栈。
|