技能教程 · TUTORIAL
字幕处理 · 详细教程
纯本地处理 srt / ass / vtt 字幕：格式互转、校正时间轴、合并双语、清洗广告语。零第三方依赖，不联网。
这是什么
subtitle-tools 是一个跑在你自己机器上的字幕处理工具，处理 srt / vtt / ass。它能做格式互转、时间轴整体偏移或按比例缩放、双语合并、清洗广告语/水印句。
零依赖：这三种都是纯文本格式，标准库足够，不用装任何第三方库。
适合谁 / 不适合谁
- ✅ 字幕对不上、快了几秒、格式要换（srt/ass/vtt 互转）。
- ✅ 双语字幕合并、把字幕时间轴归零做切片。
- ✅ 批量删字幕里的广告语或水印句。
- ❌ 不处理图形字幕（
.sup、.idx、DVD/蓝光里的图形式字幕，那是图片，得 OCR）。 - ❌ 不做翻译、不做语音识别：只搬移和调整已有字幕。
怎么部署
- 下载解压：点页面顶部的「下载 …」拿到 zip，解压得到一个
subtitle-tools/文件夹（里面是SKILL.md和scripts/）。 - 装进 AI 助手：把整个
subtitle-tools/文件夹放进你所用助手的 skills 目录，助手就能自动发现它 ——
- WorkBuddy / CodeBuddy（用户级）：
~/.workbuddy/skills/subtitle-tools/，Windows 上是C://Users//<你的用户名>//.workbuddy//skills//subtitle-tools//； - 只想在某个项目里用：
<项目目录>/.workbuddy/skills/subtitle-tools/。
- 零依赖：这个包不需要装任何依赖，放进去就能跑。
- 用起来：直接跟助手说要做什么（例：「把这个 srt 转成 ass」），它会调用；想手动跑也行：
python scripts/sub.py --help用法
铁律：先体检，再动手。先跑 info，别凭感觉改。结果一律写到 --out，不覆盖输入文件。
info —— 体检（只读）
python scripts/sub.py info 字幕.srt输出格式、条数、总时长、单条时长，以及问题清单（时间轴重叠、过短 <0.7s、过长 >7s、空文本）。
convert —— 格式互转
python scripts/sub.py convert 字幕.ass --to srt --out 字幕.srt --apply
python scripts/sub.py convert 字幕.srt --to txt --out 台词.txt --apply # 提取纯文本去翻译支持 srt / vtt / ass / txt（txt 只导文本，方便送去翻译）。
shift —— 时间轴整体偏移
python scripts/sub.py shift 字幕.srt --by +2.5 --out 新.srt --apply # 整体延后 2.5 秒
python scripts/sub.py shift 字幕.srt --by -1.2s --out 新.srt --apply # 整体提前 1.2 秒正数延后、负数提前；时间不会跑到负数（夹到 0）。
scale —— 按比例缩放（帧率 / 倍速修正）
python scripts/sub.py scale 字幕.srt --factor 1.001 --out 新.srt --apply
python scripts/sub.py scale 字幕.srt --fps-from 23.976 --fps-to 25 --out 新.srt --apply网上下载的 23.976fps 字幕配 25fps 视频会越来越不同步，用 --fps-from/--fps-to 让它算倍率；播放器倍速后字幕对不上，用 --factor 反着调。
merge —— 双语合并
python scripts/sub.py merge 中文.srt 英文.srt --out 双语.srt --apply
python scripts/sub.py merge 中文.srt 英文.srt --order 副上主下 --out 双语.srt --apply按时间重叠最多自动配对；没配上对的条目会保留，不会丢。
clean —— 清洗
python scripts/sub.py clean 字幕.srt --remove "字幕组" --remove "广告" --out 干净.srt --apply
python scripts/sub.py clean 字幕.srt --strip-style --min-duration 0.7 --out 干净.srt --apply| 开关 | 作用 |
|---|---|
--remove 正则 | 删掉文本匹配该正则的整条条目，可重复给 |
--strip-style | 去掉 <i> <b> <font> 和 ASS 的 {\...} 覆盖标签 |
--min-duration N | 把短于 N 秒的条补到 N 秒 |
--merge-short N | 合并间隔 ≤N 秒的相邻条目 |
slice —— 切一段
python scripts/sub.py slice 字幕.srt --start 00:01:30 --end 00:05:00 --rewind --out 片段.srt --apply--rewind 把时间轴归零（切出来的片段从 00:00:00 开始），做切片、做样片时用。
已知边界（如实说，不吹）
- 只处理文本和时间轴：ASS 的样式、字体、颜色、位置、特效在读入时会被剥掉，转回 ass 只用内置的一个默认样式。
- 不处理图形字幕：
.sup、.idx、DVD/蓝光图形式字幕不支持。 - 不做翻译、不做语音识别：只搬移和调整已有字幕。
- 双语合并按时间重叠配对，两份字幕时间轴差太多会配对错，先各自
shift对齐再合并。
想要加功能
包里目前是 SKILL.md + scripts/sub.py。想要图形字幕 OCR、自动翻译对接、或接进你们自己的系统 → 用页面底部的联系方式找我，说清场景，我帮你做。