Video Subtitle（本地字幕生成）v1.2
本地脚本流水线：抽音轨 → Whisper 识别 → 词表校对 → 断句优化 → 输出 srt/vtt（可选双语、硬烧、封装）。
零云 API、零按量费用。默认模型 base，默认源语言 zh。
v1.1 重构为 SubtitleEngine 类 + CLI 薄封装，新增依赖自检 / 流式进度 / VAD / 断句优化 / 字幕样式 / 批量处理 / 配置文件 / Docker。
v1.2 经真实端到端跑通后修复三处硬伤，并补上模型下载镜像 / 缓存重定位 / 离线运行。
何时用
- 给视频/音频配字幕，且不想调云 API（隐私 / 省 token / 省钱）
- 需要中英双语字幕
- 内容含专属名词（角色名、命理术语、品牌），需要识别后自动纠一遍
- 一次要处理一批视频/整目录
前置依赖（一次性）
ffmpeg（抽音轨、烧录、封装）—— 必须加入 PATH- ASR 引擎二选一：
pip install faster-whisper（推荐，支持 VAD）或pip install openai-whisper - 首次运行自动下载模型权重（base≈140MB）到
~/.cache/huggingface - 国内直连 huggingface.co 通常超时 → 程序会自动探测并切到 hf-mirror.com
- 家目录不可写时用
--download-root D:/models/whisper重定位缓存 - 依赖自检：
python scripts/cli.py --check
工作流程
- 先跑
python scripts/cli.py --check确认 ffmpeg + 引擎就绪（缺什么会明确提示）。 - 执行识别：
python scripts/cli.py 输入.mp4 --wordlist assets/wordlist.example.json。 - 看生成的 srt 校对；需要画面带字幕时最后再
--burn（硬烧不可逆，先校后烧）。 - 批量：把多个文件或目录直接作为参数传入即可。
命令模板
# 依赖自检（不处理文件，只报环境）
python scripts/cli.py --check
# 中文视频 -> 中文 srt + 词表校对（最常用）
python scripts/cli.py 输入.mp4 --wordlist assets/wordlist.example.json
# 整目录批量 + 词表
python scripts/cli.py ./videos/ --wordlist assets/wordlist.example.json
# 中文视频 -> 中英双语 srt（开启 VAD + 断句优化）
python scripts/cli.py 输入.mp4 --mode bilingual --vad --wordlist assets/wordlist.example.json
# 中文视频 -> 仅英文 srt
python scripts/cli.py 输入.mp4 --mode translate
# 直接给音频
python scripts/cli.py 录音.m4a --lang zh
# 用配置文件（推荐保存偏好）
python scripts/cli.py 输入.mp4 --config config.example.toml
# 硬烧进画面 + 自定义字号/字体（Windows 防中文方块）
python scripts/cli.py 输入.mp4 --burn --font-name "Microsoft YaHei" --font-size 28
# 封装软字幕流到 mp4（播放器可开关，推荐交付）
python scripts/cli.py 输入.mp4 --mux
# 三种形态叠加：外挂 srt + 封装软字幕 + 硬烧，一次出齐
python scripts/cli.py 输入.mp4 --mux --burn
# 追求精度（需 GPU/耐心）
python scripts/cli.py 输入.mp4 --model large-v3 --mode bilingual --vad
关键参数
| 参数 | 默认 | 说明 |
|---|---|---|
--lang |
zh |
源语言代码 |
--model |
base |
档位：tiny/base/small/medium/large-v3 |
--mode |
transcribe |
transcribe/translate/bilingual |
--wordlist |
无 | 校对词表 JSON（字典式或列表式均可） |
--vad |
关 | VAD 静音过滤（仅 faster-whisper 生效，省算力、减误识） |
--burn |
关 | 硬烧进视频（不可关） |
--mux |
关 | 封装软字幕流到 mp4（可开关） |
--format |
srt |
外挂字幕格式 srt/vtt |
--font-size / --font-name / --font-file |
24 / 系统默认 | 烧录字幕样式（防中文方块用 font-file 最稳） |
--engine |
auto |
auto 优先 faster-whisper，回退 openai-whisper |
--device / --compute-type |
auto |
自动检测 GPU/CPU 与精度（CPU→int8，GPU→float16） |
--config |
无 | TOML 配置文件（见 config.example.toml） |
--hf-mirror |
自动 | 权重镜像端点，国内用 https://hf-mirror.com |
--download-root |
无 | 权重缓存目录（家目录不可写 / 想放大盘时用） |
--no-auto-mirror |
— | 关闭「官方站不可达时自动切镜像」 |
inputs |
— | 支持多个文件或目录（批量） |
校对词表（重点）
Whisper 对同音字、专有名词最容易翻车。把专属词列进词表，识别后自动纠一遍。
支持字典式 {"错": "正"} 或列表式 [{"wrong":"错","right":"正"}]，长词优先匹配。
示例见 assets/wordlist.example.json（已含角色名/命理术语样例，按需替换）。
注意事项
- 双语 = 同音频跑两次模型（transcribe + translate），CPU 较慢但可用。
- Windows 中文硬烧坑：用
--font-name "Microsoft YaHei"或--font-file指定中文字体（详见references/usage.md）。 - 识别非 100% 准确，专名密集内容务必过词表 + 人工校对。
- 详细安装、词表格式、VAD、样式、双语、Docker 见
references/usage.md。
