程序化视频生成技能
一个确定性的、零样板的工作流，使 AI 编码代理能够从头设计、视觉 QA、评分并渲染 60fps 1080p MP4 动画视频，直接通过单个 HTML5 Canvas/SVG 文件、Python 程序化音频脚本以及无头 Playwright → FFmpeg 管道实现。
路径。 ${CLAUDE_SKILL_DIR} 是包含此 SKILL.md 的目录。在 Claude Code 中它会自动展开；在 Cursor、Codex、OpenCode 或其他代理中，请将 ${CLAUDE_SKILL_DIR} 替换为 skills/programmatic-video/ 的解析后的路径。
为什么选择确定性帧步进？
永远不要使用实时浏览器屏幕录制（例如 MediaRecorder、基于时钟的 requestAnimationFrame 捕获或实时运行的 CSS 过渡）来通过 AI 代理生成视频：
- 基于时钟的捕获会丢帧，只要 CPU 负载飙升，就会导致音频/视频漂移和卡顿。
- CSS 动画依赖于实时时间，使得无法跳转到
t = 14.20s进行即时视觉 QA。 - 盲目渲染浪费数分钟：在检查标题是否超出卡片边界之前就渲染 5000 帧，绝对会浪费工作量。
相反，使用此技能构建的每一个视频都遵守三个规则：
- 规则 1 — 帧索引的纯函数： 整个场景由
window.__setFrame(frameIndex, timeSeconds, fps)驱动，其中t = frameIndex / fps。每个位置、透明度、计数器和粒子都是t的确定性数学函数（使用基于种子的 PRNG，如mulberry32，永远不要用Math.random()）。 - 规则 2 — 完整渲染前的多模态联系表 QA： 在编码完整的 60fps MP4 之前，捕获 8-12 个关键时间戳（使用
render.mjs --timestamps ...），将它们拼接成一张contact-sheet.png（使用contact-sheet.py），然后使用你的多模态读取/查看工具检查该图像，以修复文本裁剪、重叠或低对比度问题。 - 规则 3 — 采样精确的音频 + 零磁盘膨胀的 FFmpeg 管道： 生成一个多段立体声 WAV 音轨 + 带时间戳的 SFX 提示（
synth-audio.py），然后将 Playwright 输出的 PNG 缓冲区直接流式传输到ffmpeg -f image2pipe（render.mjs）。
端到端代理工作流（6 个步骤）
步骤 1：故事板 & 场景预算
在编写代码之前，先设计一个具体的时间线表格。将视频分组为 4-8 秒的场景，并带有明确的过渡时间戳（T_cut），这些时间戳将在 scene.html 和 synth-audio.py 中共享：
| 场景 | 时间 (t) | 帧数 (60fps) | 视觉焦点 | 音频 / SFX 提示 |
|---|---|---|---|---|
| 01 — 钩子 / 提示 | 0.0s – 7.0s | 0 – 420 | CRT 终端启动、打字机日志、2.7s 处的 CTA 按钮点击 | 次脉冲 + 2.7s 处的 UI 点击/解锁提示，持续上升至 3.4s |
| 02 — 英雄指标 | 7.0s – 15.0s | 420 – 900 | 3D 透视合成波网格 + 3 个弹簧物理计数器卡片 | 7.0s 处完整的 124 BPM 合成波贝斯 + 立体声琶音器下降 |
| 03 — 深度遥测 | 15.0s – 23.0s | 900 – 1380 | 分屏进度条 + 动画半圆形量规 | 滤波器扫频 + 高帽驱动，15.0s 处次冲击 |
| 04 — 点名 & 终曲 | 23.0s – 30.0s | 1380 – 1800 | 贡献者卡片的 Bento 网格 + "JOB'S DONE!" 横幅 & 五彩纸屑 | 25.2s 处终曲和弦 + 语音/SFX 提示，28.5–30.0s 主音量淡出 |
步骤 2：编写带有 window.__setFrame(f, t, fps) 的 scene.html
编写一个自包含的 1920x1080 HTML 文件，使用 HTML5 <canvas>（和/或内联 <svg> + DOM 覆盖层），并暴露以下接口：
window.__setFrame = function(frameIndex, timeSeconds, fps = 60) {
if (window.__rafId) {
cancelAnimationFrame(window.__rafId);
window.__rafId = null;
}
const t = typeof timeSeconds === 'number' ? timeSeconds : frameIndex / fps;
renderSceneAtTime(frameIndex, t);
};
- 始终包含一个基于种子的 PRNG（
mulberry32(seed)）用于星星、粒子、五彩纸屑或噪声，确保第f帧在不同运行中位相同。 - 等待
document.fonts.ready（由render.mjs自动处理）。 - 查看 references/visual-patterns.md 获取可直接复制的代码片段（3D 透视网格、弹簧计数器、CRT 终端、量规、Bento 卡片、五彩纸屑物理效果）。
步骤 3：运行快速时间戳快照并构建 contact-sheet.png
永远不要先运行完整的 60fps 渲染。从每个场景采样 1-2 个时间戳（加上过渡中点），并构建一张单独的联系表：
# 1. 在约 3 秒内捕获 9 个关键帧 PNG
node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" \
--html ./scene.html \
--timestamps 1.8,3.0,5.2,8.5,12.5,16.5,20.5,24.5,28.0 \
--out-dir ./qa-frames
# 2. 将它们拼接成带标签的网格图像
python3 "${CLAUDE_SKILL_DIR}/scripts/contact-sheet.py" \
--dir ./qa-frames \
--cols 3 \
--thumb-width 560 \
--title "VISUAL QA CONTACT SHEET" \
--out ./contact-sheet.png
步骤 4：多模态自审循环（强制！）
在你的图像 Read / View 工具上调用 ./contact-sheet.png（以及任何看起来密集的单个 ./qa-frames/t-*.png）。对照 references/visual-qa-loop.md 中的检查清单检查每个图块：
- 是否有任何文本超出卡片边框、徽章或进度条，或与它们重叠？
- 所有数字、标签和 HUD 标题在 1080p 下是否具有高对比度且清晰易读？
- 每个场景过渡是否干净利落地完成，没有出现意外的空白/黑帧？
如果你在 contact-sheet.png 中发现任何问题，请修复 scene.html 并在继续之前重新运行步骤 3。
步骤 5：合成程序化音轨 & 混音 WAV SFX 提示
生成一个立体声 44.1 kHz WAV 音轨，其过渡上升音和 SFX 提示与 scene.html 中的确切时间戳匹配：
python3 "${CLAUDE_SKILL_DIR}/scripts/synth-audio.py" \
--duration 30.0 \
--bpm 124 \
--style synthwave \
--transitions 3.4,7.0,15.0,23.0,25.2 \
--cue "25.2:./sfx/jobs-done.wav:+1.5" \
--out ./soundtrack.wav
对于自定义多段合成或整合主题音效包（例如 jblxo/claude-code-sound-packs），请阅读 references/audio-synthesis.md。
步骤 6：通过 FFmpeg 管道渲染最终 60fps H.264 MP4
一旦视觉 QA 和音频合成通过，以完整管道模式运行 render.mjs：
node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" \
--html ./scene.html \
--duration 30 \
--fps 60 \
--audio ./soundtrack.wav \
--crf 18 \
--out ./final-video.mp4
使用 ffprobe 验证输出容器：
ffprobe -v error -show_entries format=duration,size:stream=codec_name,width,height,r_frame_rate -of default=noprint_wrappers=1 ./final-video.mp4
参考手册（按需加载）
| 主题 | 参考文件 |
|---|---|
| Canvas/SVG 视觉原语、缓动函数、基于种子的 PRNG、3D 合成波网格、量规、Bento 卡片 | references/visual-patterns.md |
| 多模态联系表 QA 循环、常见布局缺陷、时间戳选择策略 | references/visual-qa-loop.md |
| 程序化 Python/NumPy 音频合成、和弦进行、上升音、闪避、WAV SFX 提示混音 | references/audio-synthesis.md |