ak:hyperframes
封装 HeyGen 的 hyperframes CLI
用于以 HTML 为先的程序化视频生成。此技能仅为文档+封装——
不包含任何 HeyGen 源代码,也未复制任何 HeyGen 代理技能。以下所有命令
均通过 npx 运行已发布的 npm 包,并固定到已知稳定的版本。
适用场景
- 从 HTML/CSS 渲染的短视频/社交媒体视频(1080×1920,9:16)。
- 产品发布片段、宣传循环、动态图形,以 HTML 编排而非 React 组件或时间轴编辑器创作。
- 任何编排源数据为 HTML 标记、使用
data-composition-id/data-start时间属性(参见 references/composition-basics.md)的任务。
不适用于以 React 为主的编排、帧级插值曲线或 Remotion 的音频/字幕生态系统——请参阅已安装的 remotion 技能以获取该替代方案(基于 React 的程序化视频)。也不适用于纯 FFmpeg/ImageMagick 编码任务——请参阅 ak-media-processing 技能。
前提条件
- Node.js 22+
- 系统 PATH 中可用的 FFmpeg
- 可选:用于远程渲染的 HeyGen 云/无服务器 API 密钥(
HEYGEN_API_KEY);本地渲染无需密钥。
在开始任何渲染工作之前,请运行捆绑的验证器:
node scripts/verify-prereqs.mjs
# 或者,如需机器可读的输出:
node scripts/verify-prereqs.mjs --json
有关各平台的安装说明及固定版本验证说明,请参阅 references/env-and-deps.md。
固定 CLI 版本
以下每次调用均固定使用 [email protected]——截至 2026-08-07 的最新发布版本(npm view hyperframes version)。在升级时,请在此文件及 references/render-workflow.md 中更新此固定版本;请勿在脚本或文档中使用未固定版本的 npx -y hyperframes ...。
工作流
标准循环为 init → 编辑 HTML → 预览 → lint → 渲染。每个阶段的具体调用示例请参考 references/render-workflow.md;简短形式如下:
# 1. 初始化新的编排项目。
npx -y [email protected] init my-composition --resolution portrait
# 2. 编辑生成的 HTML 编排文件(有关 data-composition-id / data-start / data-width / data-height 的约定,请参阅 composition-basics.md)。
# 3. 在本地开发服务器中预览。
npx -y [email protected] preview my-composition
# 4. 在渲染前检查编排文件(捕获错误的时间属性)。
npx -y [email protected] lint my-composition
# 5. 渲染为 MP4。
npx -y [email protected] render my-composition --output ./assets/videos/my-composition.mp4
始终在 render 之前运行 lint——一个 lint 通过的编排文件在渲染步骤中出错的概率远低于直接跳过 lint 的编排。
编排约定
HyperFrames 编排是普通的 HTML 文件,在根元素上使用 data-composition-id、data-start、data-width 和 data-height 属性进行标注。有关完整的属性参考和完整的竖屏 1080×1920 示例,请参阅 references/composition-basics.md。
参考资料
- references/heygen-skills.md——本封装所依赖的 25 个 HeyGen 代理技能(而非重新实现);当需要更深入的 HyperFrames 专业知识(动画、关键帧、字幕、产品发布模板等)时,可通过
npx -y [email protected] skills安装它们。 - references/composition-basics.md——包含完整竖屏预设示例的 HTML 编排属性约定。
- references/render-workflow.md——完整的
init → 编辑 → 预览 → lint → 渲染流程,包含每个固定版本的调用示例。 - references/env-and-deps.md——各平台的 Node/FFmpeg/API 密钥设置。
故障排除
| 症状 | 操作 |
|---|---|
command not found: ffmpeg | 运行 node scripts/verify-prereqs.mjs 以获取针对您平台的确切修复方案。 |
npx hyperframes 报告未知标志 | 此文件中固定的版本可能落后于上游;在更新固定版本前,请运行 npx -y [email protected] --help 确认当前标志。 |
render 失败并生成空白/短小的 MP4 | 首先运行 lint;大多数渲染失败是由于 data-start/data-composition-id 属性格式错误所致。 |
| 需要远程/云端渲染 | 按照 references/env-and-deps.md 设置 HEYGEN_API_KEY,然后使用 hyperframes cloud render(一个独立的顶层命令,而非 render 的标志)——参见 references/render-workflow.md。 |
另请参阅
- 已安装的 remotion 技能(
ak-remotion)——基于 React 的程序化视频生成;当编排本质上是一个 React 组件树而非 HTML 标记时使用。 - ak-html-video 技能——另一个独立的 HTML 到 MP4 封装(
nexu-io/html-video),具有自己的模板/Studio 工作流;当任务是 HeyGen HyperFrames 编排时,请特别使用 ak-hyperframes。 - ak-motion-graphics 技能——仓库内所有视频/动态技能以及外部动态技能包的路由器。