字幕精修后时间轴绝不漂移的秘密:wdkns-skills的check_clean_srt.py校验脚本实现细节与±150毫秒复核
字幕精修后时间轴绝不漂移的秘密:wdkns-skills的check_clean_srt.py校验脚本实现细节与±150毫秒复核
在 wdkns-skills 开源项目中,subtitle-refine 技能负责把 ASR 识别的原始 SRT 字幕精修为可上线版本,而随附的 check_clean_srt.py 校验脚本则自动复核精修后的时间轴与文本,帮你揪出时间轴漂移、语气词漏删、超长字幕等问题。本文带你拆解它的实现细节和 ±150 毫秒复核机制。
一、为什么字幕精修后时间轴会“漂移”?
字幕精修通常要做四件事:纠正识别错别字、删掉“嗯、啊、呃”等语气词、删除重复口误、把超过 14 字的长条拆分成短条。任何一步稍有不慎,都会引发连锁反应:
- 拆分错位:长条拆成两段时,如果第二段的结束时间比原条短了几十毫秒,后面所有字幕就整体“早退”了;
- 误删拉伸:删掉一条有意义的字幕后,若把前后字幕拉长补空窗,时间轴会整体“迟到”;
- 文本串位:把前一条的词“借”到当前条里修顺句子,字幕与音频对不上。
SKILL.md 中把时间轴要求写得非常明确:处理后字幕必须与原音频严格同步,不得出现全局时间漂移;单条字幕起止时间相对语音边界的偏差应尽量控制在 ±100 到 150 毫秒内。
而 check_clean_srt.py 的“秘密”,就是把上述软性要求变成可机器判定的硬性规则——只要脚本跑完没有报错,时间轴就不可能漂移。
二、一键校验:check_clean_srt.py 怎么用?
脚本是独立可运行的,只需把原始字幕和清洗后的字幕作为位置参数传入:
python3 scripts/check_clean_srt.py raw.srt clean.srt
python3 scripts/check_clean_srt.py raw.srt clean.srt --allowed-deletions '284,415,450'
python3 scripts/check_clean_srt.py raw.srt clean.srt --fail-on-warnings
它的设计思路是双轨制:
| 级别 | 含义 | 触发后果 |
|---|---|---|
| issues(硬错误) | 违反长度、标点、时间轴边界、删除白名单等规则 | 直接判为不通过 |
| warnings(启发式告警) | 语气词残留、口吃重复、疑似激进改写等可疑信号 | 默认仅提示,供人工回听复核 |
这种设计很务实:能 100% 确定的问题(比如时间越界)直接报错拦截;而“是不是漏删了语气词”这类需要人耳判断的问题,只给出告警线索,不替你做决定。
三、硬性规则:哪些问题会被直接判为错误?
脚本启动后先用 TIME_RE 正则 把 00:01:02,345 --> 00:01:05,678 这类时间轴解析成毫秒整数,后续所有比较都基于整数毫秒,避免了浮点误差。
随后对每条清洗后的字幕执行硬检查,以下情况都会产生 issue:
| 检查项 | 规则说明 |
|---|---|
| 空文本 | 条目没有文字内容 |
| 多行文本 | 单条字幕内出现了换行 |
| 标点残留 | 仍含中英文标点(清洗后的字幕不应带标点) |
| 超长字幕 | 可见字符数超过 14 字 |
| 负时长 | 结束时间早于开始时间 |
| 超出原范围 | 条目落在其“归属原条”的时间范围之外 |
| 非法删除 | 原条被删了,但既不是纯语气词,也不在 --allowed-deletions 白名单中 |
| 拆分越界 | 拆分后首段起点 ≠ 原起点,或末段终点 ≠ 原终点 |
| 段间断档/重叠 | 相邻拆分段没有做到首尾精确衔接 |
| 全局乱序 | 按时间排序后开始时间出现回退 |
四、启发式告警:捕捉语气词残留与口吃重复
硬规则拦不住“文本层面的小毛病”,脚本因此内置了四个启发式探测器,只报 warning 不拦截:
- 语气词残留 🎙️:检测整条只有“嗯啊呃哈欸诶唉哎哦额恩”组成的条目,或首尾残留 1~2 个语气字符的句子;
- 重复口吃:捕捉“我我”“这这”这类单字叠写(2 字词仅限“我你他她它这那哪有很都也就再会想要去来从把被跟和在说让给得的地”等易口吃字),以及连续出现的 ≤2 字短词重复;巧妙的是,脚本内置了
爸爸、妈妈、谢谢、看看等合法 AA 词白名单,不会误伤正常词汇; - 停顿空格缺失:以“来+那/你/我…”开头、或以“是吧/对吧/对吗/行吧/行吗/是不是/对不对”结尾的条目,通常会提示该补一个空格;
- 短时长闪现:时长低于
--min-duration-ms(默认 400 毫秒)的条目会被点名,方便人工确认是否一闪而过。
五、时间轴复核的核心:为什么绝不漂移?
这是整个脚本最精妙的部分,核心逻辑集中在 归属查找与分组 这段实现里,可分为四步:
第一步:双指针找“归属原条”。 脚本把清洗后条目按开始时间排序,同时用一个指针扫描原始条目——只要原条的结束时间 ≤ 当前清洗条目的开始时间,指针就前进。这样每条清洗字幕都能 O(1) 地找到自己的“主人”:包含它开始时刻的那条原始字幕。
第二步:硬性包含检查。 清洗条目的开始时间不能早于主人的开始时间,结束时间不能晚于主人的结束时间,否则直接报 outside original range。这一条就锁死了全局漂移:任何一条字幕都逃不出原条的时间框,自然不可能“整体提前或滞后”。
第三步:不拆分必须原样,拆分必须严丝合缝。
- 若原条只对应一个清洗条目,要求起止时间与原始完全相等——清洗只做文字修改,时间轴一个毫秒都不能动;
- 若原条被拆成多段,要求首段起点 = 原起点、末段终点 = 原终点、且每一段的结束时刻精确等于下一段的开始时刻(edge-aligned)。总覆盖时长与原条完全一致,既不能多也不能少。
第四步:删除白名单与全局顺序。 被整条删除的原始字幕,必须是纯语气词条目,或者被用户通过 --allowed-deletions '284,415' 显式放行;最后再全局校验一遍开始时间的单调性,作为兜底。
六、文本漂移与“串位”检测:防改写也防借词
除了时间轴,脚本还会做两道文本复核,把“字幕级清洗、禁止改写”的原则落地:
- 激进改写检测:先去掉空格比较,相同则放行;若仍不同,再经过一次保守归一化(去首尾语气字符、折叠短口吃、折叠重复前缀片段)后比较;如果归一化后还不一样,且相似度(
SequenceMatcher)≤ 0.45,则告警possible aggressive rewrite,意味着当前条目可能被大幅改写; - 邻条串位检测(text carryover):如果清洗后的文本与前一条或后一条原始字幕的相似度 ≥ 0.72,且比与自身的相似度高出 0.20 以上,则怀疑是从邻条“借词修顺”,触发
possible text carryover告警。
这两道防线配合 SKILL.md 的“保守优先”工作原则,共同保证精修只做字幕级清洗,不碰语义。
七、±150 毫秒复核:脚本兜底 + 人工回听
那么标题里的 ±150 毫秒体现在哪?答案是:机器能判的交给脚本,机器判不了的交给耳朵。
脚本通过“原范围内 + 不拆分零改动 + 拆分严丝合缝”三条硬规则,保证时间轴绝对不发生漂移——这是 0 毫秒容错的底线。而 ±150 毫秒是留给人工回听复核的容差窗口:当脚本给出短时长闪现、语气词残留等 warning 时,人工可以微调该条的边界,但偏差必须控制在 ±100~150 毫秒内,确保字幕贴合语音片段,不出现明显早挂或滞留。
也就是说,issues=0 是自动化的及格线,warnings 列表则是人工复核的工作清单——两者配合,才是完整的时间轴 double check 流程。
八、参数与退出码速查表 ⚙️
| 参数 | 默认值 | 作用 |
|---|---|---|
raw_srt / clean_srt |
必填 | 原始字幕与清洗后字幕路径 |
--allowed-deletions |
空 | 逗号分隔的、允许整条删除的原始字幕编号 |
--min-duration-ms |
400 | 短时长告警阈值(毫秒) |
--fail-on-warnings |
关闭 | 存在告警时返回非零退出码 |
--latin-word-as-one-char |
关闭 | 连续英文数字串按 1 个字计长 |
| 退出码 | 含义 |
|---|---|
0 |
全部通过 |
2 |
存在硬性错误(issues) |
3 |
无硬错误,但有告警且启用了 --fail-on-warnings |
脚本运行时会先输出 raw_entries、clean_entries、issues、warnings 四个统计值,再逐条列出具体问题与 warning: ... 告警,方便在 CI 或工作流中直接消费退出码。
九、写在最后
subtitle-refine 技能的完整工作流是:读取原始 SRT → 逐条清洗、纠错、按需拆分 → 整理非 filler 删除白名单 → 运行 check_clean_srt.py 做规则检查与时间轴复核 → 对告警位点人工回听。
它的精髓在于把“不漂移”从一句口号变成一组可执行的断言:归属包含检查锁死全局边界,不拆分零改动锁死单条边界,首尾对齐拆分锁死局部边界,±150 毫秒的人工回听兜住最后一段模糊地带。四层防线层层收紧,这就是精修后时间轴绝不漂移的秘密。
更多精修规则与交付约定,可参考 SKILL.md;技能元信息见 agents/openai.yaml。