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.9 KiB

Raw Blame History

命令行选项

两个程序：

live-caption —— 图形界面（悬浮窗 + 托盘 + 设置）。日常使用不需要任何参数；下面的参数里，它只关心「后端与模型」「流式参数」「GUI 专用 / 测试专用」几节。
live-caption-cli —— 命令行版，只链 Qt6::Core，适合无显示环境、脚本、CI。

两边共用的选项定义在 apps/common/appcli.h。 --help 会用「（默认 X）」把默认值印在说明里。

后端与模型

选项	默认	说明
`--asr-backend <kind>`	`llama`	`llama`（Qwen3-ASR GGUF）或 `sherpa`（流式 ONNX）
`--asr-model <id>`	—	模型注册表（`data/models.json`）里的 id；sherpa 后端用它定位文件，llama 后端也可用它走注册表
`--model <path>`	—	主模型 GGUF 路径（架构须为 `qwen3vl`）
`--mmproj <path>`	—	mmproj GGUF 路径（clip + qwen3a）
`--model-dir <dir>`	`~/.local/share/live-caption/models`	覆盖模型存储目录
`--language <lang>`	空 = 自动	语言提示（`zh` / `en` / `ja` …），多语言模型需要
`--threads <n>`	`8`	推理线程数（只影响 Qwen3-ASR；流式模型固定单线程）
`--verbose`	关	输出 llama.cpp / mtmd 的详细日志

模型「未安装」时会提示缺失的文件名，并给出 scripts/fetch-models.sh <id> 的提示。

流式参数

参数的选择与实测见 docs/phase2-streaming.md。 这些参数只影响 llama 后端（Qwen3-ASR）；sherpa 的流式模型只用到「提交粒度」一个参数。

选项	默认	说明
`--stream-chunk <sec>`	`2.0`	累积多少秒音频跑一步（提交粒度）
`--stream-mode <mode>`	`incremental`	`incremental`（增量 KV 复用）/ `append`（追加式）/ `window`（滑窗）
`--stream-window <sec>`	`16`	滑窗上限；仅 `window` 模式，`0` = 不滑窗
`--stream-segment <sec>`	`30`	单段最长时长，超过就提交并重置上下文；`0` = 不限
`--unfixed-tokens <n>`	`5`	前缀回滚：丢掉最后 N 个 token（这些算「不稳定尾部」）
`--unfixed-chunks <n>`	`2`	前 N 个 chunk 不带前缀（冷启动）
`--max-tokens <n>`	`256`	单段最多生成 token 数

运行模式（仅 `live-caption-cli`）

选项	说明
`--file <path>`	整段转写一个 WAV 后退出（离线精度基线）
`--stream-file <path>`	以流式模式转写一个 WAV 后退出（验证流式策略）
`--cli-live`	实时转写并只在命令行输出（不开窗口），用于无显示环境

采集

选项	说明
`--device <sink>`	采集源（输出设备的 sink 名）；留空 = 跟随系统默认输出
`--list-devices`	列出可选的采集设备后退出（仅 `live-caption-cli`）

./build/live-caption-cli --list-devices
#   alsa_output...HiFi__Speaker__sink   ... Speaker  [默认]
#   alsa_output...HiFi__HDMI1__sink     ... HDMI / DisplayPort 1 Output
./build/live-caption-cli --asr-model zipformer-zh-2025 --cli-live --device alsa_output...HiFi__HDMI1__sink

辅助

选项	说明
`--verify-model <id>`	重算 sha256 校验模型完整性后退出（仅 `live-caption-cli`）

./build/live-caption-cli --verify-model zipformer-zh-2025
# ✅ 中文流式（k2-fsa 官方 2025-06-30） 校验通过

GUI 专用 / 测试专用

这些只在 live-caption 上有效。除 --opacity 外都是给自动化测试用的，平时不需要：界面本身提供这些功能。

选项	默认	说明
`--opacity <n>`	—	背景不透明度（20–100），覆盖设置里的值
`--no-tray`	—	不创建托盘图标（测试用；此时 `✕` 会直接退出）
`--screenshot <path>`	—	启动后自动截图并退出；同时截折叠态与展开态（`-expanded.png`）
`--screenshot-delay <sec>`	`6`	截图前等待秒数
`--screenshot-settings <path>`	—	打开设置对话框、截图后退出
`--settings-autoclose <how>`	—	自动操作设置对话框：`reject` / `close` / `accept` / `ok` / `apply`（`ok`/`apply` 是真的去点按钮）
`--quit-after <sec>`	—	运行若干秒后优雅退出（测退出路径）

--settings-autoclose + --quit-after 是当初定位「点确定程序就退出」崩溃时留下的复现手段，也可以当作界面交互的冒烟测试：

for how in reject close accept ok apply; do
  ./build/live-caption --asr-model zipformer-zh-2025 --no-tray \
      --settings-autoclose $how --quit-after 8
  echo "$how → 退出码 $?"
done

退出码

码	含义
`0`	正常结束（含 `--screenshot*`、`--quit-after` 的优雅退出）
`1`	启动失败：模型没加载起来（`live-caption-cli` 的 `--verify-model` 校验失败也是 1）

4.9 KiB Raw Blame History Unescape Escape