live-caption/docs/cli.md

# 命令行选项

两个程序：

- **`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` 的流式模型只用到「提交粒度」一个参数。

| 选项 | 默认 | 说明 |
|---|---|---|
| `--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-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） |