blumia
d234b9658d
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 走另一条分支」的说明。
107 lines
4.9 KiB
Markdown
107 lines
4.9 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` 的流式模型只用到「提交粒度」一个参数。
|
||
|
||
| 选项 | 默认 | 说明 |
|
||
|---|---|---|
|
||
| `--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） |
|