0 Fork 0

Files

T

blumia d234b9658d docs: refresh docs to match the current state, add GUI/CLI/troubleshooting

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 走另一条分支」的说明。

2026-10-12 17:29:45 +08:00

4.4 KiB

Raw Permalink Blame History

常见问题

点 `✕` 之后窗口不见了

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

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

首次启动弹出设置对话框

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

没有字幕 / 转写全是空白

按顺序排查：

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

从终端启动看输出，采集/加载失败会打印原因：

./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 的推荐组合：

语言	建议
中文	`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 后端将不可用」

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

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。

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

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

4.4 KiB Raw Permalink Blame History Unescape Escape