剪映口播剪辑的删留决策与音频质检：jianying-headless 项目 editing-and-qc 实操指南

• 音视频
• AI 技能
• AI 应用

本篇技术指南以 jianying-headless 仓库中 yichen-jianying-edit Skill 的剪辑判断与音频质检参考文档 为核心，讲解在无界面剪映草稿链路上如何对口播素材做语义删留、时间切口、字幕组织与四步复查，并结合 edit_plan.py 的编译实现与 plan-format.md 的计划字段，给出可直接落地的质检流程。读完本文，你将掌握一套以"可继续编辑的原生草稿"为交付物、以语义完整性为前提的口播剪辑验收方法，并理解render-audio、静音检测与 ASR 结果在该流程中的真实边界。

一、删留：一切剪辑判断的起点

口播剪辑的第一步不是找气口、也不是看波形，而是先在句段层面完成"删什么、留什么"的取舍。该 Skill 将每个区间明确归入三类：

CHECK 项必须向用户展示具体位置与影响，不能只问一句"这段删吗"——要让用户看到"如果删除 2.4s–3.0s 这一段，'目标营收'会直接接上'的 47%'，结论从'全年 47%'变成'同比 47%'"这类具体后果。

文档给出两条硬约束：

1. 先完成句段取舍，再清气口。不要在删句时顺手压缩呼吸音，避免"为了字数短删掉正常限定词，造成'比较高性价比'只剩后半个音节"的语义残缺。
2. 选中的删除区间与被保护的有效发音不能重叠。这一约束在编译器层面被强制实现：edit_plan.py的compile_plan会逐个校验keeps内protect区间的[start, end]必须落在该保留段内部（start - 1e-7 <= a < b <= end + 1e-7），否则直接抛出Protected pronunciation lies outside its keep range，见 edit_plan.py。

二、切口：为每个保留词留足发音边界

ASR 时间戳的固有误差

ASR 对短词的起止标记可能偏几十到几百毫秒，因此：

• 给每个保留词留必要的发音边界，避免切掉字头字尾；
• 但不要把相邻已删词的起音留回来——删掉的是"它"，就不能把"它"的声母残留带进下一段"我"的开头。

这与计划格式中protect字段的设计直接对应：protect是保留词的有效发音区间，可按词列多个，只有"明确无语音、且确实需要保留的画面"才允许使用空列表，参见 plan-format.md。

RMS 低能量点只是参考

RMS 的低能量点只能帮助选择切点，不能把"低于某 dB"直接当作呼吸标签。波形上的能量谷不代表语义边界，机械按 dB 切分会把词内停顿或英文拼读的间隔误删。

时间戳修正记录

必要时记录时间戳修正的证据链：原时间、修正时间、相关词、波形/试听或复转写证据。文档给出两个典型操作：

• 保留完整的"好"，去掉后面废句的"它"；
• 去掉"嗯"的尾音，同时保护接下来的"我"。

这些边界修正最终要落进 jianying-edit-plan/v1 计划的keeps[].protect与decisions数组中，由编译器统一换算成微秒级时间映射。

三、字幕组织：按语义短句，不按物理片段

长句跨多个视频物理片段时：

• 字幕按保留的语义短句组织，不要求一段视频对应一条字幕；一条字幕可以跨多个保留片段（编译器允许，起止点必须落在保留内容中，文字仅包含保留语义）；
• 单屏尽量一至两行；英文产品名会占不同宽度，需要原生画面检查；
• 字幕避开脸、界面按钮和重要数据。

编译器对字幕的加工细节见 edit_plan.py：起止点先映射到目标时间线，再增加20ms 前余量 / 40ms 后余量的轻微显示余量，并按相邻字幕顺序裁掉完全重叠；任何字幕端点落入已删除源区间都会报错，保证"文字仅包含保留语义"。

四、复查顺序：四步走，步步可验证

步骤 3 强调了一个工程细节：新版文件使用新 hash，不能覆盖旧文件后误用旧缓存。这与asr_once.py的内容绑定 ledger 设计一致——ASR 一次请求记录以素材内容 hash 为键，run遇到旧的 pending 文件或未绑定缓存时会拒绝新提交，且默认没有force开关，见 asr_once.py。

五、render-audio：文字/时间映射的候选证明，不是听感替代品

render-audio使用与草稿相同的保留区间、速度和目标长度，只导出音频，不生成视频：

python3 SKILL/scripts/edit_plan.py render-audio --plan WORK/compiled-v1/compiled.json --out WORK/voice-v1.wav --work WORK/audio-render-v1

从 edit_plan.py 的实现看，它做的事情包括：

1. 先执行validate_compiled全量校验编译计划（时间映射、帧对齐、protect 区间、字幕、音效白名单）；
2. 用 ffmpeg 把源音频抽成 48kHz 单声道 PCM；
3. 逐保留区间按atempo链变速（>2 倍拆成多个 2x 因子、<0.5 拆成多个 0.5x 因子，见tempo_filters），再施加volume线性增益与apad/atrim精确裁剪到帧网格长度；
4. 输出必须是全新 WAV，返回sha256、采样数、时长与video_rendered: false。

因此它证明文字/时间映射和候选剪口成立，但ffmpeg 的变速实现与剪映不同，不能替代剪映真实听感检查。剪映的时间吸附、重采样与变速滤波与 ffmpeg 存在差异，最终听感必须回到剪映草稿上验收。

六、静音检测报告：只列候选，不当结论

• 建议关注超过 180–250ms 的间隔，阈值随素材调整；
• 词内停顿、英文拼读的间隔不应机械删除；
• 没有静音段不等于完全没有呼吸声——静音检测只反映能量低点，不反映气口质量；
• 没有解码错误也不等于剪辑质量通过——encoded-and-decoded这类状态只代表容器/编码链路完整，不代表内容正确，这一点在 export-macos.md 的验收说明中被反复强调。

七、ASR 名称纠错：画面与上下文优先

ASR 拼错Aisa、Vibe Coding、Skill、Similarweb、GEO、KOL等名称时：

• 用画面和上下文校正字幕，保留原声；
• 区分识别器偶发重复与真正重口，不要为了让转写文本"完美"而无休止重跑、压缩词尾。

名称纠错属于replace_text/字幕层修改，走 edit-existing-macos.md 的独立副本编辑链路，不改原草稿。

八、停止条件与交付要求

同时满足以下条件即可交付：

1. 没有未解决的明确语义或剪口问题；
2. 字幕映射完整；
3. 原生草稿通过保存和冷启动（在剪映中保存、退出、冷重开后回读结构一致，见 headless-macos.md）。

追加检查的唯一理由是"新改动、新失败或明确未解疑点"，不能无限循环。

不能声称已经人耳全片试听、没有任何气口或完成导出，除非本次确有相应证据——这是该 Skill 对质检声明的事实边界。

最终交付强调草稿状态：转写记录、SRT 与删留方案按任务需要保留，不用为了质检默认生成 MP4；成片导出仅在用户明确要求时通过 export-macos.md 的冻结快照链路进行。

九、与计划格式和编译器的联动

editing-and-qc.md描述的删留判断最终以结构化形式进入 jianying-edit-plan/v1 输入计划：

{ "schema": "jianying-edit-plan/v1", "source": "/absolute/path/persistent-assets/source.mp4", "source_sha256": "本次副本的 SHA-256", "source_duration": 10.0, "fps": 30, "speed": 1.5, "voice_volume": 1.0, "settings_confirmed": true, "keeps": [ {"start": 0.0, "end": 2.4, "protect": [[0.08, 2.32]], "reason": "完整开场"}, {"start": 3.0, "end": 6.0, "protect": [[3.08, 5.92]], "reason": "保留重说中更完整的一遍"} ], "subtitles": [ {"start": 0.08, "end": 2.32, "text": "这里是第一句"}, {"start": 3.08, "end": 5.92, "text": "这里是后一句"} ], "decisions": [{"action": "DELETE", "start": 2.4, "end": 3.0, "reason": "气口"}] }

关键联动点：

• settings_confirmed表示 Agent 已从用户请求取得参数，字段自身不能代替用户指令；
• check_decisions_pending=false只能在 CHECK 项解决后填写——未决定的删除不能伪装成最终计划；
• 编译器向内选择可容纳完整发音的整帧区间，不自动延长保留区间；无解时报错，应调整低能量处的边界，而不是删保护词来通过检查；
• voice_volume是 0–4 的线性增益（edit_plan.py校验范围），先检查源音量与峰值再决定是否调整，不机械套用 2 倍；
• 编译输出的compiled.json与subtitles.srt一同供 headless_draft.py from-compiled 转换为多轨草稿计划，之后才进入 build / verify / publish 的无界面草稿链路。

十、质检与验收的事实边界

贯穿全文的原则是"每个结论都要有对应证据"：

• 结构回读（verify）不代替播放验收，原生保存会把时间吸附到帧网格，回读容差为一帧，但这不是允许删除发音保护区的理由，口播时间映射仍由edit_plan.py在 build 前审查；
• 无界面链路与剪映真实渲染之间的差异（变速算法、音量叠加、帧数行为）都被显式记录，例如叠化区间两路同相音频叠加约 +6.03dB 的样本测量，见 export-macos.md；
• 历史本机验收记录（含 11.4.0/11.4.2 的 6 秒 6 轨草稿、几何蒙版、线性关键帧、叠化转场等）汇总于核心项目 docs/VERIFICATION.md，但每次用户交付仍需对应的画面、声音和保存验收，历史样本不能替代当前素材。

综上，editing-and-qc.md给出的是一套以"语义优先、证据驱动"为内核的口播质检方法论：删留在句段、切口在保护、复查按四步、结论靠证据。配合edit_plan.py的帧级编译与asr_once.py的内容绑定 ledger，它把"剪映无界面口播剪辑"从凭感觉删减，推进到可复现、可校验、可交接原生草稿的工程化流程。

• 音视频
• AI 技能
• AI 应用