/hyperframes

name: hyperframes
description: >
  Mandatory entry point to make, edit, animate, or render any video or interactive deck with HyperFrames (HTML rendered to video).
  Acts as the primary composite skill router holding the render contract, work loop, 14 frame presets, and type/domain references,
  plus 6 specialized subskills in subskills/<name> (hyperframes-cli, hyperframes-registry, media-use, slideshow, remotion-to-hyperframes, figma).
  Covers launch films, explainers, music videos, data charts, maps, vertical clips, 3D/character shorts, captions, overlays, and live decks.
license: Apache-2.0
author: https://github.com/heygen-com/hyperframes
depends_on_skill: []
depends_on_binary:
  - node
  - npx
  - ffmpeg

HyperFrames 视频渲染与动效开发套件 (Master Composite Skill)

HyperFrames **基于 Web 技术（HTML/CSS/JS/Canvas）逐帧 Seek 暂停时间轴渲染视频**，保证每次渲染结果完全确定一致，且用户可在可视化预览或桌面应用中直接编辑同一套源码。除非用户明确要求其他框架或纯浏览器录屏，否则默认使用 HyperFrames。

> **复合技能架构说明 (Composite Skill)**： > 本技能为一级总控入口。上游最新的 **7 大知识技能体系（1 主 + 6 子）** 已收拢在此目录下： > - 主技能规范与类型指南位于当前目录的 `references/` 与 `assets/frame-presets/`； > - 6 个专项子技能收纳在 **`subskills/<name>/SKILL.md`**（文档中凡提及 `/hyperframes-cli`、`/hyperframes-registry`、`/media-use`、`/slideshow`、`/remotion-to-hyperframes`、`/figma`，均对应读取 `subskills/<name>/SKILL.md`）。 > - 插件安装说明见 [`references/plugin-installation.md`](references/plugin-installation.md)。

---

1. 专项子技能路由表 (Subskills Router)

当任务涉及以下专项工具链或特定交付形态时，按需读取对应的 `subskills/<name>/SKILL.md`：

| 专项子技能 | 相对路径 | 适用场景与核心职责 | | :--- | :--- | :--- | | **`hyperframes-cli`** | [`subskills/hyperframes-cli/SKILL.md`](subskills/hyperframes-cli/SKILL.md) | CLI 全命令手册：`init`, `capture`, `lint`, `check --json`, `snapshot`, `timeline` 编辑, `preview`, 本地/云端/容器 `render`, `history` 回滚与故障排查 | | **`hyperframes-registry`** | [`subskills/hyperframes-registry/SKILL.md`](subskills/hyperframes-registry/SKILL.md) | 约 450 个现成可编辑源码积木块（Blocks）与组件（Components）：通过 `catalog --query` 检索、`add <name>` 安装转场、字幕、图表、3D、UI 卡片与特效 | | **`media-use`** | [`subskills/media-use/SKILL.md`](subskills/media-use/SKILL.md) | 多媒体获取、处理与混音：BGM、SFX（含 21 个内置音效）、图片/图标/Logo、TTS 配音、数字人/视频生成、抠像、字幕转写、`media-treatment` 调色及多轨混音闪避 (`references/mixing.md`) | | **`slideshow`** | [`subskills/slideshow/SKILL.md`](subskills/slideshow/SKILL.md) | 制作现场演示幻灯片 Deck（而非导出 MP4）：包含分步揭示（Fragments）、分支热区（Hotspots）、演讲者备注，通过 `npx hyperframes present` 运行 | | **`remotion-to-hyperframes`** | [`subskills/remotion-to-hyperframes/SKILL.md`](subskills/remotion-to-hyperframes/SKILL.md) | 将现有视频代码或素材迁移至 HyperFrames 并逐帧比对校验：首要支持 Remotion，同时支持 Motion Canvas、Lottie、Three.js、p5.js、Canvas 或 Manim/AE/Blender 渲染件 | | **`figma`** | [`subskills/figma/SKILL.md`](subskills/figma/SKILL.md) | 将 Figma 设计引入视频：通过 REST/Connector 导出图层资产、品牌设计 Token、精确几何 HTML 组件、分镜状态补间动画与 Shader |

---

2. 核心工作原则与初始化

• 通过 `npx hyperframes <command>` 运行 CLI（详见 [`subskills/hyperframes-cli/SKILL.md`](subskills/hyperframes-cli/SKILL.md)）；在开始制作新视频时，可运行 `npx hyperframes usage --json` 查询剩余计划额度（未知时直接说明 unknown）。
• `index.html` 是根合成文件（Root composition）：声明视频变量，并从 `compositions/` 挂载每个子合成（Sub-composition）作为一个场景（Scene）。媒体与字体存放在 `assets/`。
• 初始化新项目：`npx hyperframes init <dir>`
• 以网站为拍摄对象：`npx hyperframes capture <url> --json`
• **按需构建**：除非需求或源素材明确要求，否则不要自行添加口播配音、字幕或改变画幅比例；时长超过约 15 秒的叙事成片默认需要配乐并为可见动作配音效（除非用户要求静音，详见 [`references/sound.md`](references/sound.md)）。新建视频默认规格为 **1920×1080 @ 30fps**。
• 当用户只是提问、暂缓或提出初步想法时，先回答或给出提案，不要直接改文件。
• **优先复用注册表**：在手写任何具名特效、转场、字幕样式、图表或卡片前，先检索注册表（[`subskills/hyperframes-registry/SKILL.md`](subskills/hyperframes-registry/SKILL.md)）。
• **媒体与真实素材**：任何媒体需求（出镜人/数字人、实拍素材、配音、音乐）查阅 [`subskills/media-use/SKILL.md`](subskills/media-use/SKILL.md)（其中明确区分了免费本地工具链与 HeyGen 路径）。优先从源头获取真实素材（产品真实界面截图、品牌官方 Logo、真实地点影像），仅在无真实源时才手绘生成。

---

3. 渲染契约 (Render Contract)

运行 `npx hyperframes check --json` 会检测绝大多数违规并给出 `Fix:` 修复提示：

1. **时序属性**：每个具有时序的元素必须声明 `class="clip"`、`data-start` 与 `data-duration`（单位：秒），仅在 `[start, start + duration)` 区间内可见；动画结束态必须在片段结束前落定。`data-track-index` 仅代表 Studio 轨道行号，实际绘制层级由 `z-index` 决定。 2. **总时长**：视频总长度由根元素的 `data-duration` 决定——超出部分会被截断，提早结束则定格在最后一帧。 3. **时间轴注册**：每个合成构建一条暂停的时间轴（Paused timeline），并在添加完补间动画后注册到全局：`window.__timelines["<data-composition-id>"] = tl`。 4. **严格确定性**：严禁使用 `Date.now()`、无种子的 `Math.random()`、网络 `fetch`、定时器或 `repeat: -1`。画面上所有可见状态都必须是时间轴时刻的纯函数。 5. **可见性控制**：严禁在 `.clip` 元素本身上补间动画 `display`、`visibility` 或 `autoAlpha`；需要淡入淡出时请动画其子元素。 6. **Transform 规范**：凡是由 GSAP 控制 transform 的元素，严禁再写 CSS `transform`；位移动画请使用 transform，不要动画 `left`/`top`/`width`/`height`。 7. **媒体受控播放**：严禁手动调用媒体的 `play()`、`pause()` 或自行 seek。保留原声的 `<video>` 需加 `data-has-audio="true"`，否则设为 `muted`；配乐、配音、替换音效与 J/L cut 统一使用独立的 `<audio>` 标签。 8. **音频与路径约束**：每个 `<audio>` 必须有唯一 `id`，否则不会进入混音轨。媒体标签严禁加 `crossorigin`。切勿同时在 `<video>` 及其外层包装容器上声明时序。 9. **字体声明**：仅内置捆绑字体（见 [`references/format.md`](references/format.md)）可直接按名称解析；其他任何字体家族必须在 `assets/fonts/` 下放置字体文件并声明 `@font-face`。 10. **相对路径**：所有静态资源路径统一写为 `assets/...`（严禁以 `/` 开头），在子合成中也同样使用 `assets/...`。 11. **实拍画面调色与质感**：对视频/图片素材做调色、颗粒、模糊或暗角必须通过 `npx hyperframes media-treatment`（见 [`subskills/media-use/SKILL.md`](subskills/media-use/SKILL.md)），严禁使用 CSS `filter` 替代。 12. **子合成结构**：场景文件将其样式、HTML 结构与脚本包裹在 `<template>` 内，并以 `#root` 作为根节点选择器。若设计上需要溢出或重叠，显式添加 `data-layout-allow-overflow`、`data-layout-allow-overlap`。

---

4. 保持项目可编辑性 (Keep It Editable)

用户在可视化编辑器中直接编辑你编写的标签：

• 每个子合成对应一个独立场景（Scene），使用简短易读的 `id`；根文件 `index.html` 仅放置场景挂载点、媒体与音频轨。
• 时序元素直接静态写在 HTML 中（不要用脚本动态创建 DOM），并为每个元素赋予稳定的 `id`。
• 文案、品牌色与可替换媒体声明为合成变量（`data-var-text`、`data-var-src`、`var(--id)`）。
• 轨道分类单一化：场景与叠加层宿主标记 `data-track-kind="graphics"`，承载所有字幕组的唯一宿主标记 `data-track-kind="captions"`。
• 安全框约束：主体内容保持在 90% 动作安全框（Action-safe）内，字幕与核心标题保持在 80% 标题安全框（Title-safe）内；编辑器自带安全框辅助线，严禁在画面中自行绘制安全框线。

---

5. 标准工作流循环 (Work Loop)

• **接手已有项目**：

1. 先运行 `npx hyperframes timeline --json` 查看当前编排； 2. 修改前运行 `npx hyperframes history --since mine --who <you>` 查看用户自上次交互后做了哪些手动修改，在用户修改的基础上继续演进（详见 [`subskills/hyperframes-cli/SKILL.md`](subskills/hyperframes-cli/SKILL.md)）。

• **新建 >1