wdkns-skills 字幕精修工作流:如何把ASR原始字幕清洗成可上线的中文SRT(14字限制与时间轴细节全解)
wdkns-skills 字幕精修工作流:如何把ASR原始字幕清洗成可上线的中文SRT(14字限制与时间轴细节全解)
wdkns-skills 仓库中的 subtitle-refine 技能,专门负责把 ASR 语音识别产生的原始 SRT 字幕,清洗成一份可直接上线发布的完整中文 clean.srt:修正识别错误、删除语气词、按 14 字限制拆分超长条目,并用随附脚本做最终的时间轴复核。适合纪录片、访谈、口播、录屏等对字幕质量有要求的场景。
一、字幕精修是什么:保守清洗,而非润色改写
传统做法容易把口语字幕"改漂亮",但上线字幕的第一原则是忠于原音频。subtitle-refine 的核心理念是"保守优先":
- ✅ 只做字幕级纠错:修 ASR 识别错误(如"的地得"、"他她它"),不总结、不扩写、不书面化
- ✅ 删除规则从严:只有纯语气词独立条目可整体删除;其余删除必须整理 allowlist 并逐条说明
- ✅ 不做"修顺":像"给我支持"改"支持我"这类"更通顺"的改写一律不允许
- ⏱️ 严格同步:所有调整限于当前条目及其局部范围,不造成后续字幕整体提前或滞后
完整规则见 SKILL.md,可直接交给 AI Agent 作为执行规范。
二、7 步工作流:从原始 ASR 到可交付 SRT
| 步骤 | 动作 | 关键点 |
|---|---|---|
| 1️⃣ 读取原始 srt | 确认总条数、超长条目 | 不覆盖原始文件 |
| 2️⃣ 明确计数口径 | 默认脚本口径;英文单词可视为 1 字 | 加 --latin-word-as-one-char |
| 3️⃣ 逐条清洗拆分 | 纠错、删语气词、断句、时间轴控制 | 直接整理成完整 clean.srt |
| 4️⃣ (可选)并行处理 | 长文件按编号/时间范围分给子代理 | 主代理必须手工整合,不依赖合并脚本 |
| 5️⃣ 整理 allowlist | 非 filler 删除条目逐条登记 | 交付时逐条列出 |
| 6️⃣ 运行校验脚本 | 规则检查 + 时间轴复核 | 见 check_clean_srt.py |
| 7️⃣ 人工复核告警 | 语气词残留、过短闪现、文本串位 | 时间轴 double check |
推荐流程原文位于 SKILL.md。
三、文本清洗核心规则:14 字限制怎么拆
3.1 14 字限制与准确断句拆分
这是最容易踩坑的一条:每条字幕最长 14 字,单条内不换行。超长时要做"准确断句"而不是机械截断:
- 例:
还得谢谢各位母亲对家里的付出→ 拆为还得谢谢各位母亲+对家里的付出 - 拆分后各子条目用
123a、123b这类临时编号,优先保留原始block_id - 英文单词默认算一个字,可用
--latin-word-as-one-char统一口径
字数检查逻辑在 check_clean_srt.py,超长会在输出中直接报 text longer than 14 chars。
3.2 语气词、标点与停顿空格
- 删无意义语气词:"嗯、啊、呃、哈"等;清洗后字幕不带任何标点
- 补子句间停顿空格:
来那你就先开始→来 那你就先开始 - 删明显重复字眼:脚本会识别"我我"这类短口吃和重复词块残留,见 find_repeat_signal
四、时间轴细节全解:如何保证与音频严格同步
时间轴是字幕精修的"隐形考点",规则集中在 SKILL.md 时间轴要求:
- 未拆分的条目:默认起止时间保持原样,改动时间会被脚本判为
unsplit subtitle timing changed - 拆分条目:所有子条目必须完全落在原字幕时间范围内,子条目之间不得重叠,首尾衔接、总覆盖时长与原条目一致
- 时间分配:优先依据语义停顿和说话节奏;无法判断时按子句有效字符数比例分配,禁止机械平均切分
- 单条贴合度:起止相对语音边界的偏差尽量控制在 ±100~150 毫秒
- 过短闪现防护:单条时长过短(默认 <400ms)会触发
short duration告警,避免无意义空窗
校验侧的对应实现:时间归属与拆分边界检查。
五、一键校验:check_clean_srt.py 使用指南
脚本支持"无拆分"和"含 123a/123b 拆分"两类输入,常用命令:
# 基础校验
python3 skills/subtitle-refine/scripts/check_clean_srt.py raw.srt clean.srt
# 登记允许的删除条目
python3 skills/subtitle-refine/scripts/check_clean_srt.py raw.srt clean.srt --allowed-deletions '284,415,450'
# 告警也视为失败(用于 CI 卡点)
python3 skills/subtitle-refine/scripts/check_clean_srt.py raw.srt clean.srt --allowed-deletions '284,415' --fail-on-warnings
# 英文单词按 1 字计
python3 skills/subtitle-refine/scripts/check_clean_srt.py raw.srt clean.srt --latin-word-as-one-char
📊 脚本输出分两级:
- issues(错误,退出码 2):残留标点、超 14 字、负时长、超出原时间范围、拆分未对齐边界、非 filler 条目被删等
- warnings(启发式告警):语气词残留、重复口吃残留、疑似缺停顿空格、疑似激进改写(文本相似度 <0.45)、疑似文本串位
告警逻辑详见 规则检查实现,CLI 参数定义在 check_clean_srt.py。
六、交付清单:上线前逐项核对
按 交付要求 说明以下信息:
- ✅ 输出文件路径(默认
xxx.clean.srt,不覆盖原始文件) - ✅ 是否存在允许删除条目(allowlist)
- ✅ 是否执行了校验脚本
- ✅ 是否仍有需人工回听复核的告警位点
七、快速开始:把技能装进你的 Agent 环境
git clone https://gitcode.com/gh_mirrors/wd/wdkns-skills
cp -R wdkns-skills/skills/subtitle-refine ~/.codex/skills/
然后在 Codex 中直接输入(来自 agents/openai.yaml 的默认提示词):
使用 $subtitle-refine 对这个中文 SRT 字幕文件做精修与校验,直接输出完整的 clean.srt。
小结:subtitle-refine 把"14 字限制、语气词删除、停顿空格、拆分时间对齐、±150ms 贴合度"这些零散经验,沉淀为一套可执行规范 + 可运行校验脚本的完整工作流。规则定得越严,脚本查得越细,交付的字幕就越接近"上线即可播"。