cut-silences

用途

cut-silences 是自动化剪辑流程的第一步。它接收一段原始录制及其词级转录，只移除静音：第一个词之前和最后一个词之后的死气（dead air），以及超过阈值的词间停顿（修剪到自然的呼吸长度，而非硬性的零间隔）。它不触碰说话者的字词——口误、重录和结巴是 cut-mistakes Agent（第 2 个 Agent）的职责。

该 Agent 是确定性的、由转录驱动的，因此其输出（*.silence-transcript.json）能干净地输入到下一个 Agent 及节拍同步校验器。

何时使用

• 当被要求「cut the silences」「trim the pauses」「remove dead air」「tighten the pacing」时
• 作为主编辑工作流的第一阶段，紧接转录之后。

前置条件

一个词级转录 JSON。可以是 ElevenLabs Scribe 格式（{ words: [{ text, start, end, type }], audio_duration_secs }）或通用格式 { words: [{ text, start, end }] }。使用工作区转录器生成：

node scripts/transcribe-elevenlabs.mjs path/to/raw.mp4    # -> path/to/raw.json

使用方式

# 1) 仅规划——计算剪切，写出 EDL + 重新计时的转录（不动视频）
node .agents/skills/cut-silences/scripts/cut-silences.mjs <transcript.json> \
  --out-dir video-projects/<slug>/assets

# 2) 带视频——同时写出 ffmpeg 命令（仍不渲染）
node .agents/skills/cut-silences/scripts/cut-silences.mjs <transcript.json> \
  --video video-projects/<slug>/assets/raw.mp4 --out-dir video-projects/<slug>/assets

# 3) 渲染剪好的视频（本地 ffmpeg，重新编码，音视频保持同步）
#    加上 --apply 才会真正运行 ffmpeg
node .agents/skills/cut-silences/scripts/cut-silences.mjs <transcript.json> \
  --video video-projects/<slug>/assets/raw.mp4 --apply \
  --output video-projects/<slug>/assets/edited-silenced.mp4

选项

参数	默认值	含义
--video <path>	—	源视频；启用 ffmpeg 命令 / 渲染
--out-dir <dir>	转录文件旁边	输出写入位置
--output <path>	<video-stem>.silenced.mp4	剪切后的视频路径
--gap <s>	0.55	视为可修剪静音的最小停顿
--head-pad <s>	0.22	第一个词之前保留的静音
--tail-pad <s>	0.34	最后一个词之后保留的静音
--apply	关闭	真正运行 ffmpeg 渲染剪切

判断方式（静音规则）

• 低于 --gap（0.55 秒）的停顿不处理——属于自然语速节奏。
• 对于被修剪的停顿，会保留一段自然的呼吸，按上下文缩放：长停顿（≥2 秒）为 0.24s，句末标点（. ! ?）后为 0.20s，其他情况为 0.14s。保留的呼吸略微偏向上一短语的结尾。
• 头尾死气修剪为 --head-pad / --tail-pad。
• 删除区间会被合并；保留区间即其补集。剪切通过 ffmpeg 的 trim/atrim + concat 滤镜图渲染（写入 *.silence-filter.txt 脚本，并通过 -/filter_complex 传入），因此视频与音频保持同步。

输出（写入 --out-dir）

文件	用途
<stem>.silence-edl.json	保留/删除区间、时长、参数——即编辑列表
<stem>.silence-transcript.json	重新计时到编辑后时间轴上的文字（供第 2 个 Agent + 节拍使用）
<stem>.silence-decisions.md	人类可读的摘要 + 被修剪的最大停顿
<stem>.silence-filter.txt	ffmpeg 滤镜图（仅在有 --video 时）
<video-stem>.silenced.mp4	剪切后的视频（仅在 --apply 时）

打印到 stdout 的 JSON 摘要包含 removed、removedPct、区间计数和输出路径——便于主工作流记录和串联。

调参说明

• 口播 YouTube 默认值（--gap 0.55）会从典型原始素材中移除约 15-20% 的纯静音。降低 --gap 可获得更紧凑、更快的剪辑；提高它可保留更自然的呼吸空间。
• 如果句子边界处的剪切感觉过于激进，可提高句末呼吸值，或提高 --gap。

交接给下一个 Agent

将 <stem>.silence-transcript.json（以及渲染出的 silenced.mp4）传给 cut-mistakes Agent。因为时间戳已位于编辑后的时间轴上，下游的节拍计时和 scripts/validate-beat-sync.mjs 无需进一步调整即可工作。