0 Fork 0

Files

T

blumia 6c04071bb5 feat(gui): expose the streaming and debug options in the advanced page

These were command-line only. Add them to the settings dialog so the whole
feature set is reachable without arguments: stream mode, window limit,
segment limit, prefix-rollback token count, cold-start chunk count, max
tokens per step, thread count, verbose logging and the model directory. The
streaming group is grouped and greyed out for streaming-ONNX models, which
only use the commit granularity. The backend fingerprint now includes them,
so changing one restarts the recogniser; appearance changes still apply live.

Also add a test-only --settings-tab so a specific page can be screenshotted.

设置「高级」页补上原来只有命令行才有的选项：流式策略/滑窗上限/单段最长/前缀回滚
token 数/冷启动 chunk 数/单段最多生成 token/线程数/详细日志/模型目录。流式那一组
单独成组，选了流式 ONNX 模型时置灰（它们只用「更新粒度」）。这些值纳入「后端指纹」，
改动会重启识别后端；外观类改动仍然即时生效。另加测试用 --settings-tab 以便给单个
页签截图。

2026-10-12 17:36:43 +08:00

5.1 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 的流式模型只用到「提交粒度」一个参数。同一组参数在 GUI 的「高级 → 流式」里也有（选了流式 ONNX 模型时那一组会置灰）。

选项	默认	说明
`--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-tab <tab>`	—	截图设置对话框时先切到某个页签（`0`–`2` 或 `模型`/`显示`/`高级`）
`--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）

5.1 KiB Raw Blame History Unescape Escape