agentvfx

你来指挥；引擎负责渲染。你永远不需要为某个片段编写着色器代码。你只需选择一个模板、一个预设以及几个类型化的参数，将它们写入一个 FX 乐谱（JSON），然后引擎会在 headless Chrome（WebGL2）中渲染，用 ffmpeg 编码 H.264，并进行闪光审计。

所有命令都应从此文件夹（技能根目录）运行。乐谱中的路径相对于当前目录解析。

1. 检查机器

node scripts/vfx.mjs doctor

ok: true 表示找到了带 GPU WebGL2 的 Chrome 和 ffmpeg。否则请阅读 blockers 并告知用户需要安装什么（CHROME_PATH、FFMPEG_PATH）。Blender 5.x 仅在需要背景板时使用（BLENDER_PATH）。

2. 选择外观

node scripts/vfx.mjs list            # 系列、模板 ID、输入类型、预设
node scripts/vfx.mjs list --json     # 附带描述

input 指明了模板需要什么：generative（不需要任何东西）、footage（需要 input.video）或 either。从一个预设开始，每次最多更改两到三个参数。在发明更多参数之前，先向用户展示结果。

3. 编写乐谱

模式定义：schemas/fx-score.schema.json。最小化示例：

{ "version": 1, "template": "lattice", "preset": "vermilion-fine",
  "input": { "video": "test-media/clip-01.mp4", "audio": "test-media/beat-132.mp3" },
  "durationSec": 4, "seed": 47, "out": "my-lattice" }

durationSec 为 3–5。seed 使渲染可重复。
params 覆盖预设（名称和范围来自模板的 fx.json）。
bindings 将参数绑定到音频特征（bass、onset、beat、bands.N 等），可设置 gain、offset、attackMs、releaseMs。保持 attack 在 onset 帧上，release 时间短（约 60 毫秒）：响应迅速显得专业，过度平滑则显得像演示。
hits 在 onset 或 beat 时触发额外模板；cuts 在 beat 时硬切割叠加层；stack 在基础层之上叠加最多两个模板。
labels 和 textStyle 设置引擎的文本层（使用已安装字体的名称；缺失时使用通用后备字体）。

无需渲染即可验证：

node scripts/vfx.mjs validate my-score.json

4. 渲染与查看

node scripts/vfx.mjs render my-score.json --out out/my-lattice --width 640 --height 360

先预览小尺寸（640x360），最终版本再提高分辨率。该命令会打印 JSON，其中包含影片路径、闪光结果和静帧图像。在向任何人描述片段之前，先打开 stills/sheet.png 和每一个 strip。你没有看过的渲染就算没完成。

5. 闪光安全

每次渲染都附带闪光审计（每秒普通闪光和红色闪光次数，遵循 WCAG 2.3.1 风格）。默认模式 stage 保持全强度，并在超出限制时写入 SAFETY.txt。"safety": { "mode": "broadcast-safe" } 会强制限制；"safeVariant": true 会在完整版本旁添加 film.safe.mp4。当片段超出限制时，要明确告知用户。

6. 背景板（可选，Blender）

node scripts/plate.mjs --scene terminalcore --shot gallery --out out/plate --width 640 --height 360 --seconds 4

程序化场景，无需下载资源。使用此背景板的 film.mp4 作为 input.video。--quality final 速度较慢（每 1080p 帧约 2 分钟）；开始之前请征询用户意见。详见 references/plates.md。

7. 无声循环

node scripts/loop.mjs out/my-lattice/film.mp4 reels/my-lattice.mp4 --preview reels/preview/my-lattice.webp --audit out/my-lattice/loop-flash.json

先正向播放片段，再反向播放（无接缝，无音轨），并对播放两次的循环进行闪光审计。退出码 3 表示循环超出了闪光限制。反向播放可能会在转折点处使闪光加倍；--hold 6 会在每个转折点暂停六帧，这通常能使循环回到限制之内。一个红色变化在反向播放时变成红色闪光的情况无法通过这种方式修复——如实告知用户，让用户决定。

8. 在网页上实时使用

node scripts/export-web.mjs lattice collage --out out/web

写入一个自包含的运行时环境、选定的模板和一个演示页面。尊重 prefers-reduced-motion。详见 references/web.md。

规则

永远不要分发或提交你没有权利重新分发的音乐。渲染的运动可能来自某首曲目，而发布的循环保持无声。
参考用于启发灵感，而非复制。不要复制他人作品中的帧、徽标、标记或字体文件。
不要打包字体文件。使用已安装字体的名称；缺失时会自动回退。

references/template-format.md —— 模板的构建方式（fx.json、pass、预设、文本层）。
references/plates.md —— Blender 背景板。
references/web.md —— 网页运行时 API。

智能体视效