---
name: hyperframes
description: "要用 HTML 写视频、渲染成 MP4，或让 agent 做发布片、讲解片、数据片时用：一页概要讲清 HyperFrames 的导演纪律 —— 三条故事线挑一条、SPEC 把形容词换成数字并禁掉默认样子、用陌生人的眼光复查 —— 和逐帧确定的渲染合同、各类片子读什么；CLI、素材、组件库和脚本在上游（吸纳自 heygen-com/hyperframes）"
---

# HyperFrames

用代码做视频，最省事的是录一段浏览器屏幕 —— 帧率跟着机器走，每次录出来都不一样。HyperFrames 把一支片子写成一个 HTML 页面：HTML、CSS、图片和音视频，加上 GSAP 这类能拨到任意时刻的动画；渲染时在无头 Chrome 里把时间轴暂停，一帧一帧拨到时刻 t 再截图，交给 FFmpeg 合成 MP4。同一份源码每次渲染出的每一帧都一样，人还能在它的 Studio 里改同一批文件。

上游给 coding agent 配了 7 个 skill，重心不在 API，在**导演**。它观察到的失败是：不给约束时，模型每次都落到同一套默认样子 —— 深色背景里飘着小字、发光、所有东西淡入上滑、三张卡片排一排 —— 动效再好，也是围着「没有故事」打转。所以它把拍什么、长什么样、好不好，都写成要落到数字、能检查的步骤。

**这一页是概要地图，不是操作手册。** 它讲清导演纪律、渲染合同和各类片子读什么；命令、素材、组件库和脚本[在上游](#upstream)。

## 导演纪律 { #discipline }

一支超过 15 秒、要讲点什么的片子 —— 发布片、讲解片、PR 视频、回顾、有叙事的音乐视频 —— 按这个顺序走：定一件事，写三条故事线挑一条，写 SPEC，做出来，复查。改已有项目、给素材加字幕、只有一个点子的短片段（一行动态字、一次地图推进）跳过前两步，需求本身就是故事；用户给了脚本、分镜或参考片，照用户的。

### 先定一件事 { #one-thing }

- **是什么，一句话**：发布片是「你现在可以……」，讲解片是观众必须懂的那一个想法，PR 视频是改了什么、为什么要紧。整个版本（「2.0」「有什么新东西」）不是一件事，取它的头条
- **看完记住的那一句**，用观众的话，不用品牌口号
- **一个观众做一件真事当脊梁**：从需要它的那一刻到拿到结果，一份真数据（一条查询、一个文件、一个数字）从开头一路带到收尾；讲解片的脊梁是一个具体例子从头算到尾
- **事实和创意分开**：屏幕上每个说法都追得到来源，用户自己的文案一字不改。来源没说的不说 —— 「40 分钟降到 2 分钟」不能写成「快 20 倍」；示例数字标明示意；拿不到的界面放带标注的占位，不画假的

### 三条故事线，挑一条 { #storylines }

- **三条是三支不同的片子**，不是一支片子换三个标题：各有自己的世界（在哪发生、长什么样）、手法（故事是什么）和形式（镜头和剪辑怎么承载）。先写五个以上点子，每个一行配一种手法和一种形式，去掉题材撑不住的，留差异最大的三条，其中一条是第一反应不会挑的大胆版
- 手法举例：某人一天里的一刻、角色替你干活、功能本身当钩子、先放成品再拉远看来处、同一件东西跨应用流转、之前和之后、大字扛论点、一个真数字落地、带着输入发问（「如果你的⟨网站⟩能直接变成视频？」）、物件本身就是解释
- 形式举例：一镜到底、物接物（这一镜结尾的东西打开下一镜）、无尽推进、穿过一个世界、踩拍硬切、匹配剪辑、分屏收成一个、一帧不断重排。三条全是场景之间平切，等于没试过形式
- **每条写五样**：名字、手法加形式、两句话说观众看到什么感到什么；开头两秒具体是什么；节拍一行（钩子 → … → 片尾卡）；外观一行；声音一行
- **故事线只是文字**，挑定之前什么都不做。按故事挑 —— 陌生人跟得上、记得住、有他认识的人或处境 —— 不按最抢眼的画面挑；推荐放第一个、带一句理由，三条都存进 `STORYLINES.md`
- 用户在场：给三条然后停下等挑，别的不问，只写一行假设（时长范围、画幅、配乐还是配音、每一项收费的东西旁边写免费替代）。用户要直接出文件：按推荐做，回复里各用一行交代另两条

### 开头、节拍和字 { #hook }

- **第 0 帧就是缩略图**：不黑屏、不只放 logo。开头两秒最密 —— 功能作用在一个认得出的东西上、一个制造需要的真实时刻、带着输入的问题；然后让旧办法在屏幕上失败，产品再来解围。开场只拍往提示框里打字，是生成片的标志
- **35 秒上下的发布片**常见节拍：钩子 ~8% → 张力 ~12% → 揭晓 ~8%（20–30% 处点名）→ 证明 ~40%（真界面里 3–6 个动词：贴、选、看它生成、发布）→ 高潮 ~20%（60–80% 处，全片最大的画面，只一次）→ 主张 ~8% → 片尾卡 ~8%。时长跟着故事走，需求里的时长是范围，不硬凑
- **一支片子走几个世界**，各有自己的背景、光和尺度，从屏幕上已有的物件进下一个世界；不要一整块深色画布上飘着小界面
- **字**：标题每行最多 6 个词、一次一行、不带句号；要读的字停 0.5 秒加每词 0.3 秒，最后一行至少 2 秒。只看字，陌生人能懂；只看画面，讲的是同一个故事。不做要点列表页，只用来源里的真数字，有配音时屏幕不逐字重复配音
- **品牌只重重落一次**，通常在片尾卡，而且是演出来的（被带进来、打出来、擦出来），之前只出现在产品和故事里；强调色要配给：一个高亮词、高潮、片尾卡

### SPEC：形容词换成数字 { #spec }

形容词是默认样子藏身的地方。给模型「高级、现代、干净」，它就拿自己的默认填满每个空，每次都一样；每把一个形容词换成数字，就从默认手里收回一个决定。所以做任何一个场景之前，先在项目根写 `SPEC.md` —— 给自己的导演简报，照它做、照它查，复查改了片子就改它：

```text
GOAL:    片尾观众感到什么、做什么，一句话
OUTPUT:  宽 × 高，帧率
TIME:    秒数 × 帧率 = 帧数；有音乐写 BPM 和每拍几帧
LOOK:    底色（色值、纹理和用量）、墨色、唯一的强调色和它能出现的地方；
         标题字体 + 字重 + 像素字号 + 字距，正文同样；
         媒介（纸和墨、照片、产品界面、玻璃、黏土、3D 棚拍）和它的数字；
         光和深度：阴影偏移、模糊和不透明度、颗粒 %、暗角 %
OBJECTS: 故事要观众认出的每样东西，用让它不靠标签也认得出的材质和细节画：
         镜子是带亮边和支架的镀银玻璃，不是一根条
MOTION:  按角色命名的缓动曲线（进、移、出、镜头）；弹簧写阻尼比；时长和错开写帧数
SHOTS:   每镜一行：帧范围、唯一的主动作、观众读到什么（和读的时间窗）、声音、怎么交给下一镜
BANNED:  下面的默认样子，加上这支片子绝不能变成的样子
QA:      要检查哪几帧，每帧必须看到什么
```

| 形容词 | 换成 |
|---|---|
| 高级 | 带数字的材质：2% 颗粒的缎面纸，无缝背景上的产品配 0.55 的接触阴影，粗糙度 0.05 的铬 |
| 现代 | 一个镜头和一套字号：一次 30 帧的推镜、只用一条缓动，标题占画面高 9%、字距 −2% |
| 干净 | 网格和配额：12 栏、96 px 边距，强调色每镜只给一个词 |
| 动感 | 踩拍剪，每小节（4 拍）换一次版式，每镜一个主动作 |
| 俏皮 | 位置和缩放上阻尼 0.45–0.6 的弹簧（不用在不透明度和颜色上），姿势夸张 10–30% |
| 电影感 | 一个镜头和一组光：35 mm 取景、左上主光、背后轮廓光、6% 暗角 |

- **构图数字**：主体至少占画面高或宽的 40%，空画面中间一个小东西不算一镜；每镜一个主动作，次要动作走 50–70% 的距离、晚 100–200 ms 起步，其余不动；全片每 2–4 秒有新东西
- **要读的字**至少是短边的 2.6%（1080 下 28 px）；字太多就删字，不缩字号
- **信息卡不一样**（口播上的 B-roll、数据节拍、竖屏讲解卡）：2.5 秒内信息全部上屏然后停住，随便暂停在哪一帧都是一张完成的海报
- **外观是一种媒介的规则，不是一组配色**：孔版印刷就是五样 —— 纸（一种平涂色加纤维噪点）、墨 A（所有要读的字和结构线）、墨 B（一种荧光强调色，每帧一个焦点）、套印（两墨相叠出第三色，B 版偏 3 px）、网点（所有渐变都是点）。动也从媒介来：画面是一版一版印上去的，不是淡入的

### 默认禁用 { #banned }

不做决定时，生成的片子就落在这些地方。每一条都禁，除非品牌自己的素材或用户给的参考用了，而且只能照它那样用：

- 黑色或深藏青的虚空当底，小元素飘在中间
- 辉光、泛光、霓虹、镜头光晕、发光的球和环，当装饰的漂浮粒子
- 紫蓝渐变、网格渐变、玻璃卡片
- 米白纸底配衬线大标题、斜体强调词、「01 / 02」编号、小号等宽大写标签、胶囊按钮
- 全部居中；全部同时淡入；每个元素都淡入加上滑；每个场景同一种进场
- 读的时候字在动，标题落定后还在漂、在缩；标题和界面上呼吸、浮动、脉动的循环；界面元素回弹；点击波纹
- 当装饰的角标、边框、角括号、HUD 读数
- 三张卡片一排、KPI 网格、压暗的截图上叠标题
- logo 缩在角落

**清单随片子增长**：每次渲染后，点名这一版用了哪些默认样子，清单上的或新的都算，加进本片的 BANNED 行，再改掉。角色的呼吸、眨眼、过冲是表演，不算。

### 复查：陌生人的眼光 { #review }

时间轴是你写的，你知道会发生什么；观众只看一遍、全速、常常在手机上。`check` 管坏没坏，复查管弱不弱 —— 当一个苛刻的动效导演，不当得意的作者。新片和每次改了时间或版式，都在回复或渲染之前过一遍。

- **先量再看**：量得出的先量 —— 一行字停得太短读不完、3 秒以上画面没变化、字小于短边 2.6%、第 0 帧是空的、15 秒以上没声音。警告是问题不是规矩：要么改，要么故意留着并写明原因。数字和眼睛不一致时信数字，被裁的标签、只停 0.6 秒的字在联系表上看都没问题
- **看三张联系表**：每个场景刚开始和中间各一帧、每个节拍一帧；每个剪辑点前后 0.2 秒一条；节拍帧缩到手机宽（360 px）一张
- **先像陌生人一样描述**：给每个节拍帧写一句话，点名画面里每个物件 —— 需要解释的物件（「那些条是镜子」）是 P0。再按顺序读节拍帧：陌生人跟得上吗、每一帧引出下一帧吗；逐镜对照 SPEC；点名出现的默认样子，加进 BANNED，先改它们
- **再按问题一问一遍**：认得出是什么吗（形状像别的东西、材质像塑料、产品界面像样机）· 主体和背景分得开吗 · 取景和接触（裁切、字贴边或压在平台界面下、该接触的东西飘着）· 第一次看的节奏（字比读的时间短、东西没有动作就蹦出来、剪辑点跳、所有东西沿同一条曲线一起动）· 生成味 · 遮住字只看画面还讲得通吗 · 手机宽度下要读的字读得清吗
- **问题写成一行**：`t=4.2s · 哪里 · 问题 → 具体改法 · 什么不动`。P0 破坏阅读或合同（读不清、错的、坏的、主镜头里有生成味），P1 削弱片子（死段、高潮软、剪辑点跳），P2 打磨。修完所有 P0 和值得修的 P1，先字、再时间、再细节，改完只截改过的帧。**不给片子打十分制的分** —— 分数找不出要改什么。片子嫌忙，删掉三分之一的动作，留下引导视线的那些
- **能开子 agent 就换一双眼睛**：只给它分镜和三张联系表，要回 P0、P1 行，改还是你自己改；改之前先提交或复制一份项目，改坏了能退
- **交付说明写进 `REVIEW.md`**，回复里放短版：做了哪些创意决定、没做的那几条故事线；量了什么、只看了什么、谁都没查的（声音是量的，没人听过）；最弱的一镜和多给时间会怎么改；故意留下的警告和理由。下一轮改动前先读它

## 渲染合同：每一帧只由时间决定 { #contract }

渲染器把每一帧单独拨到时刻 t 再截，帧不按顺序来 —— 所以画面上的一切必须是时间轴时间的函数，跟上一帧、跟墙上的钟都没关系。上游的 `check` 能查出大部分违规，每条附一行改法。

- **不碰会变的源头**：不用 `Date.now()`、不带种子的 `Math.random()`、网络请求、计时器、无限循环（`repeat: -1`），随机都用带种子的 PRNG。3D、粒子、物理在加载时一次算好存成数组，按 t 去查，`render(t)` 保持纯函数
- **时间写在标签上**：每个带时间的元素有 `class="clip"`、`data-start`、`data-duration`（秒），在 `[start, start + duration)` 里显示；片长就是根节点的 `data-duration`，超出的剪掉，提前结束就停在最后一帧
- **时间轴最后登记**：每个合成建一条暂停的时间轴，tween 全部建完再登记到 `window.__timelines`；先登记、后异步构建，渲染出来是空白
- **动画碰对的属性**：不 tween `.clip` 本身的 `display`、`visibility`，动它的子元素；动 transform，不动 `left`、`top`、`width`、`height`；不对媒体 `play()`、`pause()`、seek
- **渲染时不联网**：素材和字体都落进项目的 `assets/`，路径从项目根写起
- **留给人改**：一个场景一个子合成，带时间的元素写在 HTML 里、各有稳定的 id，文案、品牌色、可换的素材做成变量 —— Studio 改的就是这些标签

## 各类片子读什么 { #types }

上游按片型和环节各写了一篇，开工前读对应那篇。每类一句要点：

| 片子或环节 | 上游那篇 | 要点 |
|---|---|---|
| 发布、推广、功能片 | `types/launch.md` | 20–45 秒；产品画面全是真界面，缺的放带标注的占位；先交代工作区，再把动作抽出来放大 1.6–2 倍，最后把结果放回原处 |
| 讲解、教程 | `types/explainer.md` | 30–90 秒；从观众熟悉的人和处境、和他会问的问题进，装置在处境里出现；图一拍长一部分，不一次甩出整张 |
| 音乐视频 | `types/music.md` | 歌的段落就是剪辑的段落；每句词一个画面，画它的意思，不画字 |
| 图表、数字 | `types/data.md` | 一次一个数字，先被前一个场景挣来，再变成实物；高亮一条、其余灰掉，标注在点上，不要图例 |
| 竖屏短视频 | `types/vertical.md` | 1080×1920 上顶部 168 px 和 1330 px 以下不放字；第 0 帧就是钩子；镜头 1–2 秒 |
| 3D、模拟、生成 | `types/3d.md` | 一个主物件，钻进去，别绕着转；模拟加载时算好，按 t 查 |
| 角色、吉祥物、故事短片 | `types/character.md` | 情绪变化走一次表演（预备、挤压、新表情、落定）；各部件错开，不同步 |
| 网站、PR、真实地点、动态字 | `film.md` | 网站用它自己的截图，不重搭；地点用真实影像，相机运动先烘成视频 |
| 字幕；口播上的卡片 | `captions.md`；`overlays.md` | 字幕 2–6 个词一组、一次只显示一组、每组结束硬清掉；静止的卡片 8 秒就死 |
| 动效：缓动、标题、转场 | `motion.md` | 落地慢、离场干净；按角色挑缓动，不全用同一条；转场一片 3–5 种，每种由屏幕上的东西引起；标题落定后纹丝不动 |
| 外观 | `look.md` | 依次取项目的设计规范、品牌、用户给的参考、题材本身；参考只取语法，不取内容 |
| 声音 | `sound.md` | 15 秒以上讲事情的片子要有配乐和动作音效；每个音效在屏幕上有原因，峰值比画面晚一帧 |

## 这里只有地图，引擎在上游 { #upstream }

导演纪律和片型在这页读就够；要真做出片子，得装上游。上游 7 个 skill 分工如下，约 80 篇 reference、60 多个脚本约 8700 行、13 套幻灯片外观预设、约 450 个现成的块和组件，这页一样没收：

- `hyperframes` —— 入口，先读：渲染合同、工作循环，上面那些片型和环节的 reference 都挂在它下面
- `hyperframes-cli` —— 命令按活计分：起项目、检查、截帧看片、改时间线、预览、本地或云端渲染
- `hyperframes-registry` —— 约 450 个现成的转场、叠加层、标题、字幕样式、图表、地图、3D、镜头运动，装进来就是可改的源码；手写任何有名字的效果之前先搜它
- `media-use` —— 找或做素材：配乐、音效、图片图标、logo、配音、数字人、转写、抠像、调色，HeyGen 付费和本地免费两条路
- `slideshow` —— 做现场放映的 deck，出的是能翻页的网页，不渲染 MP4
- `remotion-to-hyperframes` —— 把 Remotion 等别的工具做的片子搬进来，逐帧和原片对比
- `figma` —— 从 Figma 取素材、品牌色、组件和分镜

装法：Claude Code 装插件，`claude plugin marketplace add heygen-com/hyperframes` 再 `claude plugin install hyperframes@hyperframes`，之后用 `/hyperframes:hyperframes`；别的 agent 跑 `npx hyperframes skills update`，装上前四个核心 skill。命令行要 Node.js 22+ 和 FFmpeg。自己决定要花钱的 HeyGen 调用（数字人视频、HeyGen 配音、曲库音乐）先问用户，用户点名要的直接跑。

<div class="zx-no-copy" markdown>

---

维护记录：[从哪来、改了什么](../maintenance/skills/hyperframes.md)。正常使用不用看，出问题再看。

</div>