video-by-code

视频代码生成技能

一个可运行的工具包和生产工作流程，专为人机协作团队打造，用于生成确定性的代码驱动视频。所有场景代码保留在仓库或项目工作区内；所有生成的媒体、音频素材、静帧和验证报告都存放在明确的外部 $PROD 目录中。

工作顺序： 简介 → 音频与定时 → 风格与提示 → 3张设计静帧 → 场景代码 → 确定性与文本边界关卡 → 完整渲染 → 验证与联系表 → 交付回执

---

1. 环境与冒烟测试

在构建新视频之前，确保已安装起始依赖项，并从仓库根目录通过4秒冒烟测试：

cd starter && npm ci && cd ..
node tests/runtime-contract.mjs

---

2. 生产目录与意图（RUNBOOK.md §1–2）

1. 选择一个代码检出目录之外的绝对生产目录：

   PROD="/绝对/路径/到/视频输出/<项目标识符>"
   mkdir -p "$PROD"/{audio,analysis,stills,renders,checks}
   

2. 将 templates/brief.md 复制到 "$PROD/brief.md"，并填写目标受众、核心要点、宽高比（1920x1080 横屏或 1080x1920 竖屏）、时长、语音/音乐来源以及安全区域边距。

---

3. 音频身份与定时（docs/04-music-audio-and-timing.md， docs/05-narration-and-captions.md）

切勿根据猜测的时间戳进行动画。首先测量实际音频文件并记录其 SHA-256 哈希值：

uv run tools/timing/audio-identity.py "$PROD/audio/source.wav" \
  --out "$PROD/analysis/identity.json" --copy-wav "$PROD/analysis/analysis.wav"

• 旁白：
  • 通过本地 Kokoro ONNX TTS 合成（使用 < 4 词片段合并和 --say say.json 语音词典）： uv run tools/timing/kokoro-narrate.py script.txt --out-dir "$PROD/audio" --voice af_heart --say say.json
  • 通过本地 whisper-cli 验证合成音频的往返一致性： uv run tools/verify/verify-narration.py "$PROD/audio/narration.wav" "$PROD/audio/timing.json"
  • 检查脚本/歌词相对于参考文本的逐字 n-gram 提升： python3 tools/verify/check-lift.py candidate.txt reference.txt
• 音乐/歌词/音轨反应型轨道：
  • 通过 Demucs 分离 6 个音轨（vocals, drums, bass, guitar, piano, other）并归一化为 44.1 kHz WAV： uv run --python 3.12 tools/timing/separate-stems.py "$PROD/audio/song.mp3" --out-dir "$PROD/analysis"
  • 提取 120 Hz 音轨包络、单调音乐时间 tau、节拍/小节相位、静音、features.f32 以及 100 fps 的吉他音高/颤音： uv run --python 3.12 tools/timing/analyze-stems.py "$PROD/analysis" --fps 120 --stem-pitch
  • 对齐词级歌词（whisper-cli， mlx-whisper， faster-whisper 或 acoustic 人声带能量扭曲）： uv run tools/timing/align-words.py "$PROD/analysis/stems/vocals.wav" --script lyrics.txt --backend whisper-cli --out "$PROD/analysis/words.json"
  • 轻量级单文件提示/节拍网格/可视化包络：
    • uv run tools/timing/cue-extract.py "$PROD/audio/song.mp3" --out "$PROD/analysis/cues.json"
    • uv run --python 3.12 tools/timing/beat-grid.py "$PROD/analysis/analysis.wav" --out "$PROD/analysis/beats.json"
    • python3 tools/build-visualizer.py "$PROD/analysis/analysis.wav" --out "$PROD/analysis/features.js"

---

4. 风格选择与提示组装（prompts/README.md）

浏览 prompts/styles/INDEX.md（13 个系列的 86 个作者视觉风格卡片）和 prompts/briefs/（5 个格式简介：explainer-voiceover， vertical-short， lyric-video， instrumental-visualizer， data-story）。

为所选风格和简介组装组合规范：

python3 tools/build-prompt.py <风格-id> --brief <简介-id> --out "$PROD/style-prompt.md"

---

5. 场景创作契约（lib/API.md， docs/06-building-scenes.md， docs/12-advanced-engines-and-benchmarks.md）

每个场景 HTML 页面加载 lib/harness.js（window.H）并可选择加载：

• lib/sound.js（window.SOUND）—— 程序化 Web 音频合成
• lib/features.js（window.FEATURES）—— 120 Hz 二进制 features.f32 音轨光标、不应期起始脉冲、单调 tau(t) 和 words.json 歌词查找
• lib/ink-doodle.js（window.INK）—— 8 fps 确定性线沸腾、摇摆涂鸦原语、左对齐全大写书写 marker 和 Ken Burns plate 相机
• lib/webgl-post.js（createPost）—— 4 阶段 Three.js 后处理（FxOverShader， UnrealBloomPass， FinalGradeShader（带 ACES / paperMode），仅亮度冲击反转、毛刺、抖动、颗粒感和清晰 UI 叠加）

每个页面暴露：

• <canvas id="c" width="1920" height="1080"></canvas>（竖屏为 1080 × 1920）
• window.DURATION（秒）和 window.FPS（默认为 30）
• window.__ready（在字体和缓存的离屏画板准备就绪后解决的 Promise）
• window.__renderFrame = (t) => { ... } —— 以秒为单位的 t 的纯函数。
  • 每帧以 ctx.reset()（或平衡的 save()/restore()）开始。
  • 在帧循环外部使用 H.rng(seed) 和 H.noise(seed)；切勿跨帧推进可变状态。
  • 通过 H.paperTexture(...) 或 H.offscreen(key, w, h, fn) 一次性缓存纸张/表面纹理。
  • 暴露 window.__textBounds = () => [...] 用于故事关键文本（{text, critical: true, left, right, top, bottom}），以便自动化安全区域检查可以验证每一帧。
• window.scoreSound = (k) => { ... } —— 在固定时间线时间戳安排程序化声音事件（当提供 --voice 时自动抑制背景/音乐）。

来自测试的关键生产规则

• 安全区域边距和字体粗细： 在 macOS Chrome 上，Arial 仅提供粗细 400 和 700（600 会捕捉到 700 粗体并使线条宽度增加约 9%）。始终审核 measureText(s).actualBoundingBox* 跨所有帧（对于 1080x1920 竖屏短片，x: 80..960, y: 190..1640）。
• 连续相机风格（transit-map， 平移和缩放）： 在 beat[i].start 开始相机插值（当 i 在 beat[i].start 切换时，切勿使用 beat[i].start - preRoll，这会导致 1 帧跳跃），在 0.20 s 内淡出节拍局部叠加层，并保护世界空间标签，使其仅在裁剪后的地图视口内绘制。

---

6. 渲染静帧，检查确定性与渲染主视频（docs/07-rendering.md）

1. 寻求确定性关卡：

   node starter/determinism.mjs path/to/film.html
   

2. 设计静帧关卡（在完整渲染前检查开场、密集中间和结束帧）：

   node starter/render.mjs path/to/film.html --stills 1.5,12.0,24.0 --outdir "$PROD/stills"
   

3. 完整 MP4 渲染：
   • 参考单 Worker Playwright 渲染器（默认 30 fps Canvas2D + 程序化音频）：

     node starter/render.mjs path/to/film.html \
       --out "$PROD/renders/master.mp4" --fps 30 --audio page \
       --voice "$PROD/audio/narration.wav"
     

   • 多 Worker GPU WebSocket 渲染器（60 fps Three.js / WebGL / 动态排版）：

     node tools/render/parallel-ws-render.mjs \
       --url "http://127.0.0.1:5173/?capture=1" --duration <时长> --fps 60 --workers 4 \
       --audio "$PROD/analysis/analysis.wav" --out "$PROD/renders/master.mp4"
     

   • 无浏览器 Python + Pillow rawvideo 渲染器（带字幕的工作簿和教程）：

     uv run tools/render/workbook-render.py \
       --spec workbook.json --audio "$PROD/audio/narration.wav" --out-dir "$PROD/renders"
     

---

7. 强制性验证关卡（docs/08-verification.md）

每个产品必须在移交前运行这些检查并将结果记录在 "$PROD/checks/" 中：

1. 流、解码、同步和响度关卡：

   uv run tools/verify/verify-video.py "$PROD/renders/master.mp4" \
     --expect-seconds <时长> --fps 30 --width <宽> --height <高> \
     --json "$PROD/checks/verify-video.json"
   

2. 联系表视觉检查：

   uv run tools/verify/contact-sheet.py "$PROD/renders/master.mp4" \
     "$PROD/checks/contact-sheet.jpg" --n 16 --cols 4 --tile-width 270
   

   目视检查 contact-sheet.jpg 和场景静帧，查看文本裁剪、标签重叠或意外的空白/冻结帧。
3. 过渡和剪辑突兀度审计：

   uv run tools/verify/cut-harshness.py "$PROD/renders/master.mp4" \
     --top 15 --json "$PROD/checks/cut-harshness.json"
   

4. 外观和调色板诊断：

   uv run tools/verify/measure-look.py "$PROD/renders/master.mp4" \
     --samples 16 --json "$PROD/checks/measure-look.json"
   

5. 全帧文本边界审计： 按照 tests/layout.mjs 中的模式，验证跨帧 0 .. frames-1 的 fillText 墨迹边界和 window.__textBounds()。

---

8. 打包与交付（RUNBOOK.md §12）

完成 "$PROD/qa.md"（来自 templates/qa.md）和 "$PROD/delivery.md"（来自 templates/delivery.md）。将机器验证（PASS/WARN 处置）与人工创意观看和聆听批准分开报告。

关键参考

• README.md —— 快速入门和章节索引
• RUNBOOK.md —— 12 步人机协作生产检查表
• lib/API.md —— 精确的 H 图形和 SOUND 程序化音频契约
• examples/README.md —— 已实践的横屏、竖屏和风格研究示例
• docs/10-pitfalls.md —— 症状 → 原因 → 修复表