video-use

Video Use

原则

1. LLM 基于原始转录文本和按需获取的视觉信息进行推理。 唯一值得保留的衍生产物是经过打包的短语级转录文本（takes_packed.md）。其他内容（填充词标记、重拍检测、镜头分类、强调度评分）都在决策时即时推导。
2. 音频优先，视觉随后。 剪辑候选点来自语音边界和静音间隙。仅在决策节点处深入查看视觉内容。
3. 询问 → 确认 → 执行 → 迭代 → 持久化。 在用户以平实的语言确认剪辑策略之前，绝不动剪辑。
4. 通用化。 不要预设视频是哪种类型。先看素材，询问用户，再进行剪辑。
5. 默认拥有艺术自由。 本文档中的每个具体数值、预设、字体、颜色、时长、音高结构和技法，都只是来自某个已验证视频的示例，而非强制要求。阅读它们是为了理解什么是可能的、各自为何奏效。然后根据素材的实际内容和用户的实际需求，做出你自己的审美判断。你必须遵守的仅有下方"硬性规则"一节中的内容。 其余一切由你决定。
6. 自由创造。 如果素材需要本文未描述的技法（分屏、画中画、下三分之一身份字幕卡、反应镜头、速度渐变、定格画面、交叉淡化、匹配剪辑、L 型剪辑、J 型剪辑、呼吸间的速度渐变等等），就去实现它。辅助工具是 ffmpeg 和 PIL，它们能完成该格式支持的任何操作。无需等待许可。
7. 在向用户展示前验证你自己的输出。 如果你自己都不会发布它，就不要展示。

硬性规则（生产正确性，不可协商）

以下事项一旦偏离，就会产生静默故障或损坏的输出。它们不是审美问题，而是正确性问题。请牢记。

1. 字幕在滤镜链中最后应用，位于所有叠加层之后。否则叠加层会遮住字幕。静默故障。
2. 逐段提取 → 无损 -c copy 拼接，而非单次通过的滤镜图。否则添加叠加层时每段都会被二次编码。
3. 每个段落边界处加入 30 毫秒音频淡入淡出（afade=t=in:st=0:d=0.03,afade=t=out:st={dur-0.03}:d=0.03）。否则每次剪切都会出现可听见的爆音。
4. 叠加层使用 setpts=PTS-STARTPTS+T/TB 将叠加层的第 0 帧移至其窗口起点。否则在叠加层窗口期间你会看到动画的中间部分。
5. 总 SRT 使用输出时间线偏移量：output_time = word.start - segment_start + segment_offset。 否则拼接段落后字幕会错位。
6. 绝不切入单词内部。 将每个剪切边缘吸附到 Scribe 转录文本中的单词边界。
7. 为每个剪切边缘添加填充。 工作窗口：30–200 毫秒。Scribe 时间戳会漂移 50–100 毫秒，填充可以吸收这一漂移。节奏快的视频填充更紧，电影感强的视频填充更宽松。
8. 仅使用词级逐字 ASR。 绝不使用 SRT/短语模式（会丢失亚秒级间隙数据）。绝不使用规范化的填充词（会丢失编辑信号）。
9. 按源文件缓存转录结果。 除非源文件本身发生变化，否则绝不重新转录。
10. 多个动画使用并行子 Agent。 绝不顺序执行。通过 Agent 工具一次性生成 N 个；总耗时约等于最慢的那一个。
11. 执行前确认策略。 在用户批准以平实语言描述的计划之前，绝不动剪辑。
12. 所有会话输出都位于 <videos_dir>/edit/ 中。 绝不写入 video-use/ 项目目录内部。

本文档中的其他一切都是示例。素材需要时即可偏离。

目录结构

该 Skill 位于 video-use/ 中。用户素材存放在用户放置它们的任何位置。所有会话输出都写入 <videos_dir>/edit/。

<videos_dir>/
├── <source files, untouched>
└── edit/
    ├── project.md               ← memory; appended every session
    ├── takes_packed.md          ← phrase-level transcripts, the LLM's primary reading view
    ├── edl.json                 ← cut decisions
    ├── transcripts/<name>.json  ← cached raw Scribe JSON
    ├── animations/slot_<id>/    ← per-animation source + render + reasoning
    ├── clips_graded/            ← per-segment extracts with grade + fades
    ├── master.srt               ← output-timeline subtitles
    ├── downloads/               ← yt-dlp outputs
    ├── verify/                  ← debug frames / timeline PNGs
    ├── preview.mp4
    └── final.mp4

设置

首次安装说明位于 install.md（克隆、依赖、ffmpeg、技能注册、API 密钥）。不要每次会话都重新运行它；冷启动时只需验证以下内容：

• ELEVENLABS_API_KEY 可以解析：可以来自环境变量，也可以来自 video-use 仓库根目录下的 .env。如果缺失，请让用户粘贴一个密钥，并将其写入 .env（绝不能写入用户的 <videos_dir>）。
• ffmpeg 和 ffprobe 在 PATH 中。
• Python 依赖已安装（在仓库内运行 uv sync 或 pip install -e .）。
• 如果会话需要 HyperFrames 或 Remotion 插槽，则需要可用的 Node.js 和 npm。HyperFrames 目前要求 Node.js 22+。
• yt-dlp、HyperFrames、Remotion、Manim 仅在首次使用时安装。
• 首次使用动画功能的设置在插槽目录内进行，绝不在 video-use 仓库根目录进行。HyperFrames 可以通过 npx --yes hyperframes ... 调用；Remotion 可以用 npx create-video@latest 搭建，或在使用其 remotion render 命令前安装为项目本地依赖。
• 本技能内置了 skills/manim-video/。构建 Manim 插槽时请阅读其 SKILL.md。

辅助脚本（helpers/transcribe.py、helpers/render.py 等）与此 SKILL.md 位于同一目录。请相对于包含本文件的目录解析其路径——该技能通常被符号链接到 ~/.claude/skills/video-use/ 或 ~/.codex/skills/video-use/。

辅助脚本

• transcribe.py <video>：单文件 Scribe 调用。--num-speakers N 可选。结果会缓存。
• transcribe_batch.py <videos_dir>：4 个 worker 并行转录。用于多条素材（multi-take）。
• pack_transcripts.py --edit-dir <dir>：transcripts/*.json → takes_packed.md（短语级别，在静音 ≥ 0.5 秒处断开）。
• timeline_view.py <video> <start> <end>：胶片条与波形 PNG。按需进行视觉细查。不是扫描工具，应在关键决策点使用，而不是频繁使用。
• render.py <edl.json> -o <out>：逐段提取 → 拼接 → 叠加层（PTS 偏移）→ 字幕最后处理。--preview 用于快速 720p 预览。--build-subtitles 可内联生成 master.srt。
• grade.py <in> -o <out>：基于 ffmpeg 滤镜链的调色。提供预设，并支持用 --filter '<raw>' 自定义。

对于动画，使用 Bash 创建 <edit>/animations/slot_<id>/，并通过 Agent 工具启动子 Agent。

流程

1. 盘点。 对每个源文件运行 ffprobe。对目录运行 transcribe_batch.py。运行 pack_transcripts.py 生成 takes_packed.md。抽样查看一两个 timeline_view，形成直观的视觉第一印象。

2. 预扫描问题。 通读一遍 takes_packed.md，记录口误、明显的口齿错误或需要避免的表述。整理成简单列表，并纳入编辑简报。

3. 沟通。 用平实的语言描述你看到的内容。提出与素材相关的问题。需收集：内容类型、目标时长/画幅比例、审美/品牌方向、节奏感受、必须保留的时刻、必须剪掉的时刻、动画与调色偏好、字幕需求。不要使用固定清单，每次的合适问题都不同。

4. 提出策略。 用 4–8 句话说明：整体形态、镜头选择、剪辑方向、动画方案、调色方向、字幕风格、时长估算。等待确认。

5. 执行。 通过编辑子 Agent 简报生成 edl.json。在存在歧义的时刻深入查看 timeline_view。并行子 Agent 制作动画。按片段应用调色。通过 render.py 合成。

6. 预览。 运行 render.py --preview。

7. 自我评估（向用户展示之前）。 对渲染输出（而非源文件）在每个剪辑边界（±1.5 秒窗口）运行 timeline_view。检查每张图像是否存在：

   • 剪辑处的视觉不连续、闪烁或跳变
   • 边界处的波形尖峰（漏过 30ms 淡入淡出的爆音）
   • 字幕被遮挡（违反规则 1）
   • 叠加层错位或显示错误画面（违反规则 4）

   同时抽样：前 2 秒、后 2 秒以及 2–3 个中间点，检查调色一致性、字幕可读性和整体连贯性。对输出运行 ffprobe，确认时长与 EDL 预期一致。

   要测量音频，不要假设：运行 ffmpeg -i out.mp4 -af ebur128=peak=true -f null - 获取综合响度和真峰值，并分段计算 RMS（对白、纯音乐、片尾字幕卡）。若片尾字幕卡比对白低 15 dB，或音效大于语音，即为缺陷。你无法聆听：需说明这一点，并报告数值。

   对于用户将要发布的内容（发布会、宣传、广告），还需另派出一个评审子 Agent，提供渲染文件、EDL 以及用户提供的任何参考视频。简报要求其以挑剔为主、不要夸奖：给出结论、按严重程度排列的问题（附时间码和证据，如画面帧与音量数值），以及应优先修复的 5 项改进。新视角能发现作者已经习以为常的问题，例如被剪断的包袱台词、0.5 秒的梗图，或手机尺寸下难以辨认的 28px 文字。

   如有任何检查未通过：修复 → 重新渲染 → 重新评估。自我评估最多进行 3 轮，若 3 轮后仍有问题，应告知用户，而非无休止地循环。只有在自我评估通过后，才展示预览。

8. 迭代并保存。 接收自然语言反馈，重新规划，重新渲染。切勿重新转录。确认后输出最终渲染版本。将记录追加到 project.md。

剪辑技巧

• 音频优先。 从词边界和静音间隙中寻找候选剪辑点。
• 保留高潮。 笑声、包袱、强调节点。延伸到包袱之后，包含观众反应——笑声本身就是节拍。
• 说话人交接处适合留出一定的间隔。常用值为 400–600 毫秒。节奏快的内容可短一些，电影感强的内容可长一些。这属于审美判断。
• 音频事件作为信号。 (laughs)、(sighs)、(applause) 标记节拍点。剪辑时需延伸到这些事件之后。
• 静音间隙是剪辑候选点。 静音 ≥400 毫秒通常最干净。150–400 毫秒的短语边界可用，但需进行视觉检查。小于 150 毫秒则不安全（可能切在短语中间）。
• 示例剪辑留白（随本项目发布的发布视频所用）：第一个保留词之前 50 毫秒，最后一个词之后 80 毫秒。蒙太奇式的快节奏可更紧凑，纪录片风格可更宽松。须保持在 30–200 毫秒的工作窗口内（硬性规则 7）。
• 绝不孤立地处理音频与视频。 每个剪辑点都必须在两条轨道上同时成立。

打包后的转录稿（主要阅读视图）

pack_transcripts.py 会读取所有 transcripts/*.json，生成一个 markdown 文件，其中每个 take 都是一组短语级别的行，每行前面带有 [start-end] 时间范围。遇到静音 ≥ 0.5s 或说话人切换时，短语会断开。编辑子 Agent 正是通过读取这个文件来选择剪辑点的。它只靠文本就能提供词边界精度，而且消耗的 token 只有原始 JSON 的 1/10。

示例行：

## C0103  (duration: 43.0s, 8 phrases)
  [002.52-005.36] S0 Ninety percent of what a web agent does is completely wasted.
  [006.08-006.74] S0 We fixed this.

编辑子 Agent 简报（用于多 take 选择）

当任务是“在多个片段中为每个镜头选出最佳 take”时，请按照如下结构的简报启动一个专用子 Agent。结构是关键部分，音高形态示例则不是。

You are editing a <type> video. Pick the best take of each beat and 
assemble them chronologically by beat, not by source clip order.

INPUTS:
  - takes_packed.md (time-annotated phrase-level transcripts of all takes)
  - Product/narrative context: <2 sentences from the user>
  - Speaker(s): <name, role, delivery style note>
  - Expected structure: <pick an archetype or invent one>
  - Verbal slips to avoid: <list from the pre-scan pass>
  - Target runtime: <seconds>

Common structural archetypes (pick, adapt, or invent):
  - Tech launch / demo:   HOOK → PROBLEM → SOLUTION → BENEFIT → EXAMPLE → CTA
  - Tutorial:             INTRO → SETUP → STEPS → GOTCHAS → RECAP
  - Interview:            (QUESTION → ANSWER → FOLLOWUP) repeat
  - Travel / event:       ARRIVAL → HIGHLIGHTS → QUIET MOMENTS → DEPARTURE
  - Documentary:          THESIS → EVIDENCE → COUNTERPOINT → CONCLUSION
  - Music / performance:  INTRO → VERSE → CHORUS → BRIDGE → OUTRO
  - Or invent your own.

RULES:
  - Start/end times must fall on word boundaries from the transcript.
  - Pad cut boundaries (working window 30–200ms).
  - Prefer silences ≥ 400ms as cut targets.
  - Unavoidable slips are kept if no better take exists. Note them in "reason".
  - If over budget, revise: drop a beat or trim tails. Report total and self-correct.

OUTPUT (JSON array, no prose):
  [{"source": "C0103", "start": 2.42, "end": 6.85, "beat": "HOOK",
    "quote": "...", "reason": "..."}, ...]

Return the final EDL and a one-line total runtime check.

调色（按需使用）

你的任务是分析画面，而不是套用预设。通过 timeline_view 查看一帧画面，判断哪里有问题，调整一项内容，然后再次查看。

思维模型参考 ASC CDL。按通道计算：out = (in * slope + offset) ** power，然后应用全局饱和度。slope 作用于高光，offset 作用于阴影，power 作用于中间调。

滤镜链示例（grade.py 提供 --list-presets；可将其作为起点使用，也可自行组合）：

• warm_cinematic：复古/技术风格，轻微的青橙分离，降低饱和度。曾用于真实的发布视频。适用于真人口播。
• neutral_punch：最小化校正：提升对比度并加入轻柔的 S 曲线。不做色相偏移。
• none：直接复制。用户未提出要求时的默认值。

对于其他情况，如人像、自然、产品、音乐视频、纪录片，请自行设计滤镜链。grade.py --filter '<原始 ffmpeg>' 可接受任意滤镜字符串。

硬性规则：在提取过程中按片段应用（不要在拼接后再处理，那样会导致二次编码）。在未测试肤色之前，切勿过于激进。

字幕（按需使用）

字幕有三个值得考虑的维度：分块（每行 1/2/3 个词或一整句）、大小写（UPPER/Title/Natural）和位置（距底部的边距）。合适的组合取决于内容。

已有样式：可选择、调整或自行设计：

bold-overlay：适用于短视频形式的技术发布、节奏快的社交内容。每块约 2 个词，全大写，在标点和 ≥ 0.3s 的停顿处断开；如果某条字幕时长不足 0.35s，则扩展到 3 个词，而不是闪现一条字幕（见 render.py 中的 chunk_words）。字体为 Helvetica 18 Bold，白字加描边，MarginV=35。render.py 已将其作为 SUB_FORCE_STYLE 内置。

FontName=Helvetica,FontSize=18,Bold=1,
PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,BackColour=&H00000000,
BorderStyle=1,Outline=2,Shadow=0,
Alignment=2,MarginV=35

natural-sentence（如果你自行设计此模式）：适用于叙事、纪录片、教育类内容。每块 4–7 个词，句子式大小写，在自然停顿处断开，MarginV=60–80，字号更大以便阅读，最大宽度略宽。没有内置的 force_style，如有需要请自行设计。

如果以上两种都不合适，请自行设计第三种样式。硬性规则：字幕最后添加（规则 1），并使用输出时间线偏移（规则 5）。

动画（按需使用）

动画应与内容和品牌相匹配。请从对话中获取调色板、字体和视觉语言，切勿假设默认值。如果用户没有告诉你，请在策略阶段提出调色板方案，并在确认后再开始制作。

工具选项：

为每个动画位选择合适的引擎。不要仅因为动画与网页相关就默认使用 Remotion。

• HyperFrames — 基于浏览器的 HTML/CSS/GSAP 视频合成：产品 UI 动效、网站转视频或样机转视频录制、动态排版、落地页/分镜宣传片、数据驱动的 UI 状态、透明 WebM 叠层，以及需要确定性逐帧捕获并通过 HyperFrames lint/validate/render 检查的片段。当动画应当像 Web 合成那样编写和验证，而不是作为 React 组件树时，它最合适。
• Remotion — 基于 React/CSS 的合成，适用于需要组件状态、可复用 React 基础组件，或已有 Remotion 品牌体系的场景。当用户明确要求 React/Remotion，或 React 合成是更简单的编写模型时，它最合适。
• Manim — 正式图表、状态机、公式推导、图形变形。深入内容请阅读 skills/manim-video/SKILL.md 及其参考资料。
• PIL + PNG 序列 + ffmpeg — 简单的叠层卡片：计数器、打字机文字、单条柱状图揭示、逐步绘制。迭代快，可任意定制美学风格。启动视频即采用此方案。

对于 HyperFrames 插槽，请在 edit/animations/slot_<id>/ 内使用 npx --yes hyperframes init . --example blank --non-interactive --skip-skills 搭建插槽，在该目录中构建 HTML 合成，运行适合该插槽的 HyperFrames 检查（lint、validate，条件允许时加一次草稿渲染），然后使用 npx --yes hyperframes render . -o render.mp4 生成最终叠层视频；需要透明通道时则使用 --format webm -o render.webm。将 EDL 叠层的 file 指向实际渲染输出的路径。

对于 Remotion 插槽，请将 Remotion 项目隔离在同一插槽目录内，使用 npx create-video@latest 搭建，或在该处本地安装 Remotion，通过项目本地的 remotion render 命令将合成渲染为 render.mp4，并使用 ffprobe 验证时长和分辨率。

以上方案均非必选。如有需要，可自行组合混合方案（例如 PIL 背景上叠加 HyperFrames 或 Remotion 图层）。

时长经验法则（视上下文而定）：

• 与旁白同步的讲解。 观众需要在 1 倍速下能读懂内容。大致下限为 3 秒，简单卡片通常为 5–7 秒，复杂图表为 8–14 秒。启动视频中简单卡片每张为 5–7 秒。
• 节拍同步的点缀（音乐视频、快节奏蒙太奇）。0.5–2 秒即可——它们是视觉点缀，而非信息载体。"1 倍速下可读"的规则变为"1 倍速下可辨认"，而非"完全可解析"。
• 最后一帧至少停留 1 秒再切换（通用规则）。
• 配合人声旁白： 总时长 ≥ narration_length + 1s（通用规则）。
• 切勿并行揭示相互独立的元素——人眼无法同时追踪两个新事物。一次一个，停顿，再下一个。

动画高潮时间点（与旁白同步的规则）： 获取高潮词的时间戳。将叠层起始时间提前 reveal_duration 秒，使落定帧恰好与口述的高潮词重合。若不做此同步，动画会显得与内容脱节。

缓动（通用——切勿使用 linear，它看起来生硬机械）：

def ease_out_cubic(t):    return 1 - (1 - t) ** 3
def ease_in_out_cubic(t):
    if t < 0.5: return 4 * t ** 3
    return 1 - (-2 * t + 2) ** 3 / 2

单次揭示使用 ease_out_cubic（缓慢落定）。持续绘制使用 ease_in_out_cubic。

打字文字锚定技巧： 以完整字符串的宽度居中，而非以部分字符串的宽度居中——否则文字会在揭示过程中向左滑动。

示例调色板（启动视频所用——无数风格中的一种）：

• 背景 (10, 10, 10) 近黑色
• 强调色 #FF5A00 / (255, 90, 0) 橙色
• 标签 (110, 110, 110) 暗灰色
• 字体：Menlo Bold，路径 /System/Library/Fonts/Menlo.ttc（索引 1）
• 强调色不超过 2 种，约 40% 留白，极简装饰
• 效果：终端/复古科技感

这只是一种风格。如果品牌风格温暖且带衬线体，就采用该风格；如果品牌色彩鲜明、活泼，就采用相应风格。如果用户提供了风格指南，则遵循该指南；如未提供，则提出一种方案并请用户确认。 字体会静默失败。 如果网页字体没有加载，文字会以回退字体渲染且不报任何错误，视频最终呈现的是"几乎是 Arial"。在 HyperFrames/Remotion 中，应先等待字体加载完成，再进行断言：if (!document.fonts.check('700 76px "Inter"')) throw new Error(...)。在 PIL 中，务必传入明确的字体路径，不要依赖默认字体。

实例演示："展示剪辑"开场（为本工具制作的发布视频）。前 3 秒不使用片头标题卡，而是直接可视化剪辑过程本身：每个转录词在其 Scribe 时间戳处弹出，词下方的条形图由真实音频包络绘制；一个语气词（"嗯嗯嗯"）在被说出时逐字放大，变为橙色，并在音频被剪掉的同一帧于画面上被删除，下一行立即出现。这种效果之所以成立，是因为画面与声音由同一份数据驱动：一个 Remotion 合成项目读取由 Python 生成的、逐帧精确的词语/包络 JSON，因此二者不可能产生偏差。只要故事线是"我们删掉了某些内容"，就可以使用这一思路：让删除动作可见。

并行子 Agent 任务说明 —— 每个动画都是通过 Agent 工具派生的一个子 Agent。每条提示词都必须自包含（子 Agent 没有父级上下文）。请包含以下内容：

1. 一句话目标："Build ONE animation: [spec]. Nothing else."（构建一个动画：[规格]。除此之外不做任何其他事。）
2. 绝对输出路径（<edit>/animations/slot_<id>/render.mp4）
3. 精确的技术规格：分辨率、帧率、编码器、pix_fmt、CRF、时长
4. 具体的风格调色板数值（RGB 元组、十六进制色值，或对设计系统的引用）
5. 字体路径及字体索引
6. 逐帧时间线（何时发生什么，以及缓动方式）
7. 反面清单（"不要外框、不要多余元素、除非指定否则不要标题"）
8. 代码模式参考（将辅助函数内联复制，不要跨槽位导入）
9. 交付检查清单（脚本、渲染、通过 ffprobe 验证时长、提交报告）
10. "不要提问。如有任何歧义，选择最明显的理解方式并继续执行。"

一个子 Agent 对应一个文件（文件名必须唯一，避免并行 Agent 相互覆盖）。

音乐与音效（如有需要）

声音是生成视频听起来显得廉价的关键所在。以下是发布剪辑中总结的规则：

• 少用音效。 每个音效都应与某个可见事件相对应（一次切换、一次落点、一次点击）。18 秒内使用约 20 个通用的呼啸声/渐强音/冲击音，听起来很普通；约 8 个则显得经过设计。
• 音效需踩准画面。 大多数音效都有起始段（在瞬态到来前有静默或渐强）。应测量这段时长（首个采样点超过峰值约 -30 dBFS 的位置），并将文件起始位置提前 attack 秒，使其早于可见的接触帧。
• 人声出现时压低音乐（相对于纯音乐电平约降低 -12 至 -15 dB），并在音效提示或结束卡片之前将音乐淡出，而不是让音乐自身的尾音在你的行动号召文案下衰减。
• 统一母带处理： 先混音为 PCM，再对最终混音进行两遍 loudnorm（-14 LUFS，真峰值 ≤ -1 dBTP）。随后按段落进行测量（参见自我评估）。
• 音乐风格由用户决定。 生成的音乐默认偏"激昂"；可提供两种风格迥异的音乐底色，由用户自行试听选择。不要声称某个混音听起来很好——我们只能对其进行测量。

输出规格

除非用户另有要求，应与源素材保持一致。常见目标：1920×1080@24 电影感、1920×1080@30 屏幕内容、1080×1920@30 竖屏社交媒体、3840×2160@24 4K 影院、1080×1080@30 方形。render.py 会将任意源素材的缩放默认设为 1080p；如需其他目标，请传入 --filter 或修改提取命令。值得询问用户哪种交付格式最为重要。

EDL 格式

{
  "version": 1,
  "sources": {"C0103": "/abs/path/C0103.MP4", "C0108": "/abs/path/C0108.MP4"},
  "ranges": [
    {"source": "C0103", "start": 2.42, "end": 6.85,
     "beat": "HOOK", "quote": "...", "reason": "Cleanest delivery, stops before slip at 38.46."},
    {"source": "C0108", "start": 14.30, "end": 28.90,
     "beat": "SOLUTION", "quote": "...", "reason": "Only take without the false start."}
  ],
  "grade": "warm_cinematic",
  "overlays": [
    {"file": "edit/animations/slot_1/render.mp4", "start_in_output": 0.0, "duration": 5.0}
  ],
  "subtitles": "edit/master.srt",
  "total_duration_s": 87.4
}

grade 为预设名称或原始 ffmpeg 滤镜。overlays 为已渲染的动画片段。subtitles 为可选项，且最后应用。

记忆 —— project.md

每次会话在 <edit>/project.md 中追加一个段落：

## Session N — YYYY-MM-DD

**Strategy:** one paragraph describing the approach
**Decisions:** take choices, cuts, grades, animations + why
**Reasoning log:** one-line rationale for non-obvious decisions
**Outstanding:** deferred items

启动时，如果 project.md 存在，则先读取它，用一句话概括上一次会话，然后再询问是否继续。

反模式

以下做法无论采用何种风格都会反复失败：

• 分层的预计算编解码格式，带有 USABILITY / 语气标签 / 镜头层。过度设计。应在决策时从转录稿中推导。
• 手工调校的片段打分函数。 大模型选择的效果比你编写的任何启发式规则都好。
• Whisper 的 SRT / 短语级输出。 会丢失亚秒级的间隔数据。始终使用逐词、逐字原样的转录。
• 在 CPU 上本地运行 Whisper。 速度慢，而且会规范化语气词。改用托管的 Scribe。
• 在叠加层合成之前将字幕烧录进底片。 叠加层会遮挡字幕。（硬性规则 1。）
• 存在叠加层时使用单遍 filtergraph。 会造成双重重新编码。应使用逐段提取 → 拼接。
• 线性动画缓动。 看起来生硬机械。始终使用三次方缓动。
• 未经验证的网页字体。 加载失败时会无声地回退到系统字体。渲染前需断言字体已加载。
• 每次转场都加入现成音效。 应将每个效果与可见事件绑定，并限制数量。
• 多个动画使用顺序执行的子 Agent。 应始终并行。
• 在确认策略之前就开始编辑。 绝对不要。
• 重新转录已缓存的源文件。 不可变输入的输出也是不可变的。
• 想当然地判断视频类型。 先观察，再提问，最后编辑。