HyperFrames
HyperFrames 是一个 HTML → MP4 渲染器(Apache 2.0 许可)。合成物是带有 data-start、data-duration、data-track-index 属性的纯 HTML 文件;渲染器通过无头 Chrome 帧精确地驱动时间线,并将帧通过管道送入 FFmpeg。技能 hyperframes-prompt-builder 是营销引擎的调度入口点;本技能包含创作规则。
何时调用
- 某个作品通过路由(通过
PROVIDERS.md或 frontmatter 中的provider_override.video: hyperframes)路由到 HyperFrames 提供方。 - 任务是
motion-typography、data-viz-reel、programmatic-short,或任何需要从声明的变量中获得确定性输出的合成(例如,每周 KPI 短片,在输入新数字时不变地重新渲染)。 - 需要将已批准的静态图像(引语卡、轮播幻灯片)提升为动态短片,而不改变排版系统。
- 编排器需要一个可重新渲染的制品:相同的合成,不同的
--variables,字节相同的基线。
输入
composition_id:字符串。用于项目目录和data-composition-id的简短标识符。aspect:9:16|1:1|16:9|4:5。duration_seconds:整数。合成总长度。scenes:数组。每个{ id, start_s, duration_s, role: "hook" | "body" | "cta", copy?, asset_ref? }。design_tokens:对象。品牌颜色、主要/次要字体族、间距比例。当存在clients/<slug>/design.md时从中获取。variables:数组,可选。声明的参数,调用方可以在渲染时覆盖{ id, type, label, default }。assets:对象,可选。{ video?, audio?, images[] }——项目下的本地路径。output_dir:字符串。渲染器写入 MP4 的目录(默认为outputs/<client>/<date>/<piece-id>/)。
过程
- 首先阅读品牌上下文。 加载
clients/<active-client>/design.md(或传入的设计令牌)。在知道令牌之前拒绝创作 HTML——仅当客户端没有设计令牌时回退到仓库内的默认值。 - 大声规划叙事弧(场景、节奏、过渡、节拍),然后再编写标记。前 1.5 秒是钩子,主体,CTA 在尾部。
- 先布局后动画。 首先编写最终的屏幕布局——将元素定位到它们最终的位置。使用
gsap.from()动画进入这些位置;只有最后一个场景可以使用gsap.to()退出。 - 编写 HTML。 根
<html>携带data-composition-id、data-width、data-height。每个剪辑携带id、data-start、data-duration、data-track-index。使用data-composition-variables(<html>上的 JSON 数组)参数化;运行时使用window.__hyperframes.getVariables()读取。 - 将每个时间线注册为暂停状态。
const tl = gsap.timeline({ paused: true }); window.__timelines["<id>"] = tl;——框架驱动播放。没有无限重复、没有Math.random()、没有基于时间的逻辑、没有异步时间线构建。 - 每个场景之间都有过渡。 没有跳切。使用上游
references/transitions.md中列出的编目过渡(淡入淡出、擦除、遮罩、着色器)。 - 视频和音频。
<video>必须静音;音频位于单独的<audio>元素中,位于自己的轨道上。 - 本地验证,使用
npx hyperframes lint,然后使用npx hyperframes inspect(文本溢出、容器裁剪)。只有两者都通过才渲染。委托给hyperframes-cli技能。 - 输出清单。 在 MP4 旁边写入
manifest.json,包含{ composition_id, aspect, duration_seconds, variables_resolved, lint_pass, inspect_pass, render_settings }。这是CLAUDE.md中完成标准所要求的。
输出
project_path:字符串。HyperFrames 项目目录的路径。composition_html:字符串。创作的index.html内容(或project_path下的路径)。render_args:对象。传递给npx hyperframes render的标志(--fps、--quality、--variables、--strict)。expected_artifact:字符串。渲染后将在output_dir下出现的 MP4 路径。cost_estimate_usd:数字。本地渲染——仅计算时间;如果是 DRY_RUN,报告 0;否则根据--workers× duration 估算。
不可协商的规则
- 每个元素都有一个入场动画(
gsap.from())。 - 所有时间线一开始都是暂停的,并注册在
window.__timelines上。 - 合成逻辑中没有
Math.random()、没有Date.now()、没有 setTimeout 驱动的动画。 - 视频轨道静音;绝不在
<video>中嵌入音频。 - 如果客户端副本可能是变量,则永不将其直接烘焙到标记中——将其声明在
data-composition-variables中,以便相同合成可以针对新作品重新渲染。 - 永不编辑
outputs/下已渲染的 MP4;改为重新运行hyperframes render。
示例
示例 1:每周 KPI 短片(程序化短片)
输入:{ composition_id: "kpi-weekly-w21", aspect: "9:16", duration_seconds: 12, scenes: [{ id: "hook", start_s: 0, duration_s: 2, role: "hook", copy: "Semana 21" }, { id: "metric", start_s: 2, duration_s: 8, role: "body" }, { id: "cta", start_s: 10, duration_s: 2, role: "cta", copy: "Veja o detalhamento" }], variables: [{ id: "leads", type: "number", label: "Novos leads", default: 0 }, { id: "delta_pct", type: "number", label: "Variação %", default: 0 }] }
输出:一个项目位于 outputs/<client>/<date>/kpi-weekly-w21/ 下,其 index.html 读取两个数值变量并对其进行动画处理;render_args.--variables 按作品解析它们。
示例 2:运动引语卡(动态排版)
输入:{ composition_id: "quote-marcos-2026-05", aspect: "1:1", duration_seconds: 6, scenes: [{ id: "main", start_s: 0, duration_s: 6, role: "body", copy: "Coloque a sua marca onde os olhos já estão." }] }
输出:一个动态排版合成,尊重活动客户端的字体配对,具有遮罩文本入场和对最终帧的柔和保持。
失败模式
- 缺少
design.md且未传入设计令牌:停止并询问。不要自行发明调色板。 npx hyperframes lint报告错误(缺失data-composition-id、重叠轨道、未注册的时间线):阻止渲染直到修复。npx hyperframes inspect报告任何场景的文本溢出:优先重排版面布局,而不是将字号缩小到系统最小值以下。- 音频轨道长于合成
duration_seconds:修剪音频,永远不要扩展duration_seconds来适应。 - 合成在任何地方使用了
Math.random()或墙上时钟时间:在渲染前重构为声明的变量或种子确定性生成器。
相关技能
hyperframes-cli:lint、inspect、preview、render 命令。创作后始终调用。hyperframes-prompt-builder:营销引擎专家,将作品简报转换为本技能期望的输入形状,当矩阵解析为hyperframes时由video-prompt-builder调用。video-prompt-builder:通用调度器。qa-tech-specs:验证渲染的 MP4 是否符合平台规范(宽高比、时长、安全区域)。compliance-<active client>:渲染后对渲染制品和从变量解析的屏幕副本运行。
上游参考
完整的上游技能(合成模式、过渡目录、音频响应、字幕、数据动态):https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes