Communitygithub.com

ngocsangyem/reporeaper

封装 HeyGen HyperFrames CLI,用于以 HTML 为先的程序化视频生成。适用于短视频/社交媒体视频、产品发布片段、基于 HTML 编排的动态图形。另请参阅已安装的 remotion 技能以获取基于 React 的替代方案。

reporeaper 是什么?

该技能封装了 HeyGen 的 `hyperframes` CLI,为开发者提供了一种基于 HTML 定义视频场景和动画的程序化视频生成方式。它最适合创建 9:16 竖屏短视频、产品宣传片和动态图形,其编排逻辑完全通过 HTML 标记中的 `data-composition-id` 和 `data-start` 等属性控制。技能本身不包含 HeyGen 的源代码,而是通过 `npx` 运行指定版本的 npm 包,并提供了完整的初始化、预览、检查与渲染工作流程。它适用于 Node.js 22+ 环境,要求安装 FFmpeg,并支持通过设置 `HEYGEN_API_KEY` 进行云端渲染。对于需要 React 组件树的复杂视频生成场景,建议使用已安装的 remotion 技能。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ngocsangyem/reporeaper/tree/HEAD/.claude/skills/ak-hyperframes

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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。

参考资料

故障排除

症状操作
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 技能——仓库内所有视频/动态技能以及外部动态技能包的路由器。

相关技能