feat: 本地视频 AI 字幕生成器 (ffmpeg + faster-whisper GPU + 可选 LLM)

CLI 流水线: probe / transcribe / burn 三个子命令, 支持批量、通配符、断点续跑。

识别 (纯本地 GPU, 音频不出本机):

faster-whisper large-v3 (ctranslate2, int8_float16), RTX 4060 8GB 实测 17-19x 实时
自动处理 PyPI ctranslate2 缺 CUDA 运行库的问题: 进程内 RTLD_GLOBAL 预加载 nvidia-cublas/cuda-runtime, 无需手动 export LD_LIBRARY_PATH

断句与字幕质量:

词级时间戳 + 标点优先切分超长行, 相邻碎片合并, 纯语气词/标点行过滤
静默钳制 + 单条字幕 12s 硬封顶, 防止 whisper 幻觉词/长停顿被写进字幕时长

可选 LLM 后处理 (默认关闭, OpenAI 兼容 API, 如 DeepSeek):

逐批 JSON 结构化润色/翻译, 失败自动回退原文, 不阻塞流水线

缓存与重放:

caps.json 持久化 whisper 原始段(含词级时间戳), 识别参数与断句参数解耦
只改断句或补/撤 LLM 时走 [重放] 秒级重算, 零 GPU

其他:

11 项单元测试 (SRT 序列化/时间轴归一化/断句/静默钳制)
scripts/run_all.sh 批量脚本, scripts/validate_srt.py 字幕质量校验

subgen — 本地视频 AI 字幕生成器

ffmpeg 抽音轨 → faster-whisper (large-v3, 本地 NVIDIA GPU 推理) → 规则断句 → SRT/ASS 字幕，外加可选的大模型 API 润色 / 中英翻译模块（DeepSeek 或任意 OpenAI 兼容端点）。

识别全程本地 GPU，音频不出本机；LLM 只处理纯文本，不配 key 也能跑。
适合中文授课/讲座视频（含 agent、API、LLM 等英文术语的中英混读）。

安装（一次性）

conda create -n subgen python=3.11 -y
conda install -n subgen -c conda-forge ffmpeg -y
/home/chenshaoqin/miniconda3/envs/subgen/bin/pip install -e ./subgen

首次识别前会自动下载模型（Systran/faster-whisper-large-v3，约 3GB）。国内网络请加上:

export HF_ENDPOINT=https://hf-mirror.com     # HF 镜像
export HF_HUB_DISABLE_XET=1                  # 镜像站不支持 xet 新协议, 必须禁用

说明:

PyPI 的 ctranslate2 不自带 CUDA 运行库。本工具已内置自动处理（进程内预加载 nvidia-cublas/cuda-runtime 轮子的 so），无需手动 export LD_LIBRARY_PATH。

模型默认 Systran/faster-whisper-large-v3，int8_float16 计算，RTX 4060 8GB 显存约用 4GB。

用法

ENV=~/miniconda3/envs/subgen/bin
$ENV/subgen probe "*.mkv"                      # 先看哪些视频有音轨、多长
$ENV/subgen transcribe "第一讲-*.mkv" -o subtitles --language zh
$ENV/subgen transcribe 视频.mkv --max-seconds 600   # 调试: 只跑前 10 分钟
$ENV/subgen transcribe "*.mkv" -o subtitles --with-llm            # 启用 LLM 润色
$ENV/subgen transcribe "*.mkv" -o subtitles --with-llm --translate-to en  # 中英双语
$ENV/subgen burn 视频.mkv 视频.srt -o burned/   # 可选: 烧录进画面

LLM 环境变量（transcribe --with-llm 时才需要）:

变量	默认
`SUBGEN_LLM_API_KEY` (或 `OPENAI_API_KEY`)	无 → 跳过 LLM
`SUBGEN_LLM_BASE_URL`	`https://api.deepseek.com/v1`
`SUBGEN_LLM_MODEL`	`deepseek-chat`

常用参数

参数	说明	默认
`--model`	faster-whisper 模型	`Systran/faster-whisper-large-v3`
`--compute-type`	`int8_float16` / `int8` / `float16`	`int8_float16`
`--language`	`zh` / `en` / `auto`	`zh`
`--max-chars`	单行字幕最大字符数	`20`
`--max-seconds N`	只处理前 N 秒(调试)	全片
`--format`	`srt` / `ass`	`srt`
`--force`	忽略已有产物重跑	关

产物、缓存与”零 GPU 重放”

输出 <视频名>.srt（与视频同目录或用 -o）；翻译模式另产 <视频名>.en.srt 与 <视频名>.zh-en.srt。
每个视频在输出目录下留一个 .subgen-<视频名>/ 缓存目录：
- caps.json — whisper 原始段（含词级时间戳 raw）+ 断句结果，几百 KB~1MB/视频；
- meta.json — 本次运行的识别/断句/LLM 参数；
- 中间 wav（16kHz，约 115MB/小时）默认跑完即删。
识别缓存（raw）与断句参数解耦：
- 参数全一致 → [跳过]；
- raw 在、只改了断句（如 --max-chars）或想补/撤 LLM 润色 → [重放] 秒级重算，不重新 GPU 识别；
- 改了模型/语言/VAD 等识别参数 → 才重新解码。
断句：短碎片合并、按词级时间戳+标点切分超长行、语气词/纯标点行过滤；字幕时长硬封顶 12s（防 whisper 把长静默/幻觉时间戳挂进字幕）； LLM 批次失败自动回退原文，不影响整体。
实测速度（RTX 4060 Laptop, large-v3 int8_float16）：约 17–19× 实时，1 小时视频约 3–4 分钟。

说明与限制

需要至少一个带音轨的视频；无音轨文件会被探测并跳过。
识别速度：RTX 4060 Laptop 上 large-v3 约 10–12× 实时（1 小时视频约 5–6 分钟）。
不做说话人分离、不做画面 OCR（本期范围外）。
备选引擎：中文更专精可换 FunASR paraformer-zh（subgen/asr.py 留了扩展点）。
质量校验: python scripts/validate_srt.py ../subtitles/*.srt 输出每条字幕的时间轴/行宽统计。