video-use

视频处理

原则

1. 大模型根据原始转录文本和按需查看的画面进行推理。 唯一值得保留的衍生产物，是按短语打包的转录文本（takes_packed.md）。其他所有内容——填充词标记、重录检测、镜头分类、强调评分——都在做决策时推导。
2. 音频优先，画面随后。 剪辑候选点来自语音边界和静音间隙。只在决策点深入查看画面。
3. 询问 → 确认 → 执行 → 迭代 → 持久化。 用户未用通俗易懂的语言确认策略前，绝不动剪辑。
4. 灵活应变。 不要假设视频属于哪种类型。先查看素材、询问用户，然后再剪辑。
5. 默认允许自由发挥。 本文档中的每个具体数值、预设、字体、颜色、时长、节奏结构和技巧，都是来自一个成功视频的实际案例，而非硬性规定。阅读它们，了解可以实现什么，以及每种做法为何奏效。然后根据素材的实际情况和用户的真实需求，做出自己的审美判断。唯一必须遵守的内容在下方的硬性规则中。 其他一切由你决定。
6. 大胆创新。 如果素材需要本文档未提及的技巧——分屏、画中画、下三分之一身份卡、反应剪辑、变速、定格、交叉淡化、匹配剪辑、L-cut、J-cut、呼吸声上的变速，等等——就去实现。辅助工具是 ffmpeg 和 PIL。它们可以实现格式支持的任何效果。无需等待许可。
7. 向用户展示前，先核验自己的输出。 如果你自己都不愿交付，就不要展示。

硬性规则（制作正确性——不可妥协）

以下事项一旦偏离，就会导致无声故障或输出损坏。它们关乎正确性，而非审美。请牢记。

1. 字幕必须在滤镜链的最后应用，位于所有叠加效果之后。否则叠加效果会遮住字幕，且不会发出提示。
2. 按片段提取 → 无损 -c copy 拼接，不要使用单次滤镜图。否则添加叠加效果时，每个片段都会被重复编码。
3. 在每个片段边界添加 30ms 音频淡入淡出（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. 绝不在单词中间剪切。 每个剪切边缘都必须对齐 Volcengine 转录文本中的单词边界。
7. 为每个剪切边缘留出余量。 工作范围：30–200ms。ASR 时间戳可能有偏差，留出余量可以吸收偏差。快节奏素材留得更少，电影感素材留得更多。
8. 仅使用逐词、逐字的 ASR 转录。 绝不使用 SRT／短语模式（会丢失亚秒级间隙数据），也绝不规范化填充词（会丢失剪辑信号）。
9. 按源素材缓存转录文本。 除非源文件本身发生变化，否则绝不重新转录。
10. 多个动画使用并行子 Agent。 绝不串行处理。通过 Agent 工具一次启动 N 个；总耗时约等于最慢任务的耗时。
11. 执行前确认策略。 用户批准通俗易懂的计划前，绝不动剪辑。
12. 所有会话输出均放入 <videos_dir>/edit/。 绝不写入 video-use/ 项目目录内。

本文档中的其他内容都是实际案例。素材需要时，可灵活调整。

目录结构

该技能位于 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 normalized Volcengine word timestamps
    ├── 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 密钥）。不要在每个会话中重复安装；冷启动时只需验证：

• VOLCENGINE_API_KEY 可从工作区根目录的 .env 或环境变量中读取。默认资源 ID 为 volc.seedasr.auc；仅在需要时使用 VOLCENGINE_RESOURCE_ID 覆盖。
• ffmpeg 和 ffprobe 位于 PATH 中。
• Python 依赖项已安装在链接到 <skill_dir>/.venv 的外部环境中；不要在同步的技能目录树内创建实际的虚拟环境。
• 如果会话需要 HyperFrames 或 Remotion 插槽，请确保 Node.js 和 npm 可用。HyperFrames 目前要求 Node.js 22+。
• 仅在首次使用时安装 yt-dlp、HyperFrames、Remotion 和 Manim。
• 首次动画设置应在插槽目录内进行，切勿在视频使用仓库根目录中进行。可通过 npx --yes hyperframes ... 调用 HyperFrames；可通过 npx create-video@latest 搭建 Remotion 项目，或在使用其 remotion render 命令前将其安装为项目本地依赖。
• 此技能内置了 skills/manim-video/。构建 Manim 插槽时请阅读其中的 SKILL.md。

辅助脚本（helpers/transcribe.py、helpers/render.py 等）与此 SKILL.md 位于同一目录。请相对于此文件所在目录解析其路径——此技能通常通过符号链接放置在 ~/.claude/skills/video-use/ 或 ~/.codex/skills/video-use/。 请使用 <skill_dir>/.venv/bin/python 调用这些脚本，以确保 Pillow、NumPy 和其他渲染依赖项以一致的方式解析。

辅助脚本

• transcribe.py <video> — 调用 Volcengine 对单个文件进行词级时间戳转录。可选参数：--num-speakers N。结果会缓存。
• transcribe_batch.py <videos_dir> — 使用 4 个工作进程并行转录。用于多次拍摄的素材。
• pack_transcripts.py --edit-dir <dir> — 将 transcripts/*.json 转换为 takes_packed.md（短语级；静音 ≥ 0.5s 时分段）。
• 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. 自我评估（展示给用户之前）。 对渲染后的成片（而非源素材）运行 timeline_view，检查每个剪辑边界处（±1.5s 窗口）。检查每张图像是否存在以下问题：

   • 剪辑处的视觉不连续／闪烁／跳变
   • 边界处的波形尖峰（漏过 30ms 淡变的音频爆音）
   • 字幕被叠加层遮挡（违反规则 1）
   • 叠加层未对齐或显示了错误帧（违反规则 4）

   另外还要抽样查看：开头 2s、结尾 2s，以及 2–3 个中间点——检查调色一致性、字幕可读性和整体连贯性。对成片运行 ffprobe，确认时长符合 EDL 预期。

   如有任何问题：修复 → 重新渲染 → 重新评估。最多进行 3 轮自我评估——如果 3 轮后仍有问题，应告知用户，而不是无限循环。只有自我评估通过后，才能提供预览。

8. 迭代并持久化。 根据自然语言反馈重新规划并重新渲染。绝不重新转录。确认后进行最终渲染。追加内容到 project.md。

剪辑技巧（技术）

• 音频优先。 根据词语边界和静音间隙确定候选剪辑点。
• 保留情绪峰值。 笑声、妙语、强调的节拍。妙语之后应延长片段以纳入反应——笑声本身就是节拍。
• 说话人交接时，话语之间留出间隙会更好。常见时长：400–600ms。快节奏内容可缩短，电影感内容可延长。酌情判断。
• 把音频事件当作信号。 (laughs)、(sighs)、(applause) 标记了节拍。应延长片段，将它们纳入。
• 静音间隙是候选剪辑点。 ≥400ms 的静音通常最干净。150–400ms 的短语边界经视觉检查后可以使用。<150ms 不安全（处于短语中间）。
• 剪辑填充时长示例（随附的发布视频采用此方案）：保留的第一个词之前 50ms，最后一个词之后 80ms。蒙太奇节奏可更紧凑，纪录片可更宽松。保持在 30–200ms 的工作范围内（硬性规则 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 '<raw ffmpeg>' 接受任意滤镜字符串。

硬性规则：在提取过程中按片段应用（不要在拼接后应用，否则会重新编码两次）。未经测试肤色前，切勿使用激进调色。

字幕（按需）

字幕有三个值得斟酌的维度：分段（每行 1／2／3 个词或整句）、大小写（全大写／标题式大小写／自然大小写）和位置（距底部的边距）。合适的组合取决于内容。

实用风格——选择一种、调整后使用，或自行设计：

bold-overlay — 节奏快的社交媒体短篇科技发布视频。每段 2 个词，全大写，按标点断行，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 检查的片段。适用于像制作和验证网页合成内容那样完成动画，而非构建 React 组件树的场景。
• Remotion — 带组件状态的 React/CSS 合成、可复用的 React 原语，或现有的 Remotion 品牌系统。适用于用户明确要求使用 React／Remotion，或 React 合成是更简单的制作方式时。
• Manim — 正式图表、状态机、公式推导、图形变形。请阅读 skills/manim-video/SKILL.md 及其参考资料，深入了解。
• PIL + PNG sequence + ffmpeg — 简单的覆盖卡片：计数器、打字机文本、单条形显示、渐进式绘制。迭代快速，任何美术风格都适用。发布视频使用了这种方式。

对于 HyperFrames 动画片段，使用 npx --yes hyperframes init . --example blank --non-interactive --skip-skills 在 edit/animations/slot_<id>/ 中搭建片段骨架，并在其中构建 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%，尽量减少装饰
• 效果：终端／复古科技感

这只是一种风格。如果品牌风格温暖且带衬线，就采用这种风格；如果色彩丰富、活泼俏皮，也采用这种风格。如果用户提供了风格指南，就按指南执行。如果没有，就提出一种方案并确认。

并行子 Agent 任务说明——每段动画由一个通过 Agent 工具启动的子 Agent 负责。每条提示词都必须自成一体（子 Agent 不具备父级上下文）。请包含：

1. 一句话目标：“制作一段动画：[规格]。除此之外不要做任何事。”
2. 绝对输出路径（<edit>/animations/slot_<id>/render.mp4）
3. 精确技术规格：分辨率、fps、编码格式、pix_fmt、CRF、时长
4. 以具体数值表示的风格配色（RGB 元组、十六进制值，或设计系统引用）
5. 字体路径及索引
6. 逐帧时间线（何时发生什么，以及使用何种缓动）
7. 禁止项列表（无装饰、无额外内容、除非明确指定，否则不加标题）
8. 代码模式参考（将辅助函数直接复制进来，不要跨插槽导入）
9. 交付检查清单（脚本、渲染文件、通过 ffprobe 验证时长、汇报结果）
10. “不要提问。如有任何不明确之处，选择最显而易见的解释并继续。”

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

输出规格

除非用户提出了具体要求，否则应与源素材一致。常见目标规格：电影感 1920×1080@24、屏幕内容 1920×1080@30、竖屏社交媒体 1080×1920@30、4K 电影 3840×2160@24、方形 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。 速度慢，还会规范化语气词。使用已配置的 Volcengine 词级时间戳服务。
• 在合成叠加层之前将字幕烧录到底片中。 叠加层会遮住字幕。（硬性规则 1。）
• 有叠加层时使用单次滤镜图。 会导致重复编码。使用逐片段提取 → 拼接。
• 线性动画缓动。 看起来很机械。始终使用三次缓动。
• 在片段边界处硬切音频。 会出现明显爆音。（硬性规则 3。）
• 将输入文字居中于当前已有的部分字符串。 随着文字增长，文本会向左滑动。
• 为多个动画依次调用子 Agent。 始终并行执行。
• 未确认策略就开始编辑。 绝不。
• 重新转录已缓存的源文件。 不可变输入的输出也应保持不变。
• 凭空假设视频的类型。 先查看，再询问，最后编辑。