name: video-subtitle description: 本地视频/音频字幕生成（零云 API）。支持抽音轨、Whisper 本地识别、专名校对词表、中英双语字幕、VAD 静音过滤、断句优化、字幕样式控制、批量处理、可选硬烧/封装。当用户需要给视频配字幕、转写音频、生成中英双语字幕，或要求"本地/离线/不调 API"完成时调用。

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

工作流程

1. 先跑 python scripts/cli.py --check 确认 ffmpeg + 引擎就绪（缺什么会明确提示）。
2. 执行识别：python scripts/cli.py 输入.mp4 --wordlist assets/wordlist.example.json。
3. 看生成的 srt 校对；需要画面带字幕时最后再 --burn（硬烧不可逆，先校后烧）。
4. 批量：把多个文件或目录直接作为参数传入即可。

命令模板

# 依赖自检（不处理文件，只报环境）
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

关键参数

校对词表（重点）

Whisper 对同音字、专有名词最容易翻车。把专属词列进词表，识别后自动纠一遍。 支持字典式 {"错": "正"} 或列表式 [{"wrong":"错","right":"正"}]，长词优先匹配。 示例见 assets/wordlist.example.json（已含角色名/命理术语样例，按需替换）。

7w4.net收录了海量优质技能插件。

注意事项

• 双语 = 同音频跑两次模型（transcribe + translate），CPU 较慢但可用。
• Windows 中文硬烧坑：用 --font-name "Microsoft YaHei" 或 --font-file 指定中文字体（详见 references/usage.md）。
• 识别非 100% 准确，专名密集内容务必过词表 + 人工校对。
• 详细安装、词表格式、VAD、样式、双语、Docker 见 references/usage.md。

这个 Skill 质量不错，核心功能齐全，文档写得清楚明白，对国内用户很友好（镜像切换、缓存重定位）。依赖自检、中文字体处理等细节考虑周到，使用起来比较省心。不足是测试覆盖不够全面，部分边界情况的稳定性有待验证。如果你是普通用户，按文档操作基本不会踩坑，但识别结果仍需人工核对。