blumia
6c04071bb5
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 以便给单个 页签截图。
109 lines
5.1 KiB
Markdown
109 lines
5.1 KiB
Markdown
# 命令行选项
|
||
|
||
两个程序：
|
||
|
||
- **`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](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`） |
|
||
|
||
```bash
|
||
./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`） |
|
||
|
||
```bash
|
||
./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` 是当初定位「点确定程序就退出」崩溃时留下的复现手段，
|
||
也可以当作界面交互的冒烟测试：
|
||
|
||
```bash
|
||
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） |
|