hyperframes

HyperFrames — 从这里开始

HyperFrames 从 HTML 渲染视频——一个合成内容就是一个 HTML 文件，其 DOM 通过 data-* 属性声明时间，动画运行时可定位到任意时间，并且媒体播放由框架管理。完整的创作规范位于 /hyperframes-core；编写合成 HTML 前请先阅读。

下方是能力地图（按需加载的领域技能）和意图路由器（为任何“帮我制作视频”的请求选择工作流）。

能力地图 — 领域技能

按需加载的原子能力，不是完整的视频工作流。对于“帮我制作视频”，请使用下方的意图路由器。

你想要……	技能
创作 / 编辑 HTML 合成内容——data-* 规范、片段、轨道、子合成内容、变量	/hyperframes-core
制作动画——原子运动、场景蓝图、转场、运行时适配器（GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU）	/hyperframes-animation
创意指导——frame.md / design.md、调色板、排版、旁白、节拍规划、音频响应	/hyperframes-creative
媒体——TTS 配音、背景音乐、转录、背景移除、字幕	/hyperframes-media
媒体解析——从 HeyGen 目录查找并固定 BGM、SFX、图片、图标到 .media/，并通过清单跟踪	/media-use
CLI 开发循环——初始化、lint、验证、检查、预览、渲染、发布、诊断	/hyperframes-cli
安装注册表区块 / 组件（hyperframes add）	/hyperframes-registry

---

意图路由 — 选择工作流

本节只介绍顶层工作流；不会加载其内部参考资料或上方的领域技能。

路由前 — 确认输入，而非规格

路由需要了解视频的主题——输入内容和主题。如果未说明（例如“制作一个介绍我们产品的视频”，但没有 URL、产品、主题或素材），请先提问，再进入任何工作流——确定工作流本身就是路由决策。最多提两个问题：

• 输入——产品（URL / 简介）、一般网站、GitHub PR、要讲解的主题，还是现有的真人出镜视频？

规格默认值——直接说明，不要询问（它们不会改变路由）：宽高比为 16:9（仅当指定了竖屏发布平台——TikTok / Reels / Shorts——时使用 9:16）；旁白 / 字幕的语言 = 用户使用的语言。所选工作流会在第一步再次确认自身的具体要求。

工作流速查表

工作流	适用场景
/product-launch-video	营销、发布或推广产品——可根据产品 URL、简报或脚本制作（即使只提供了网站名称也可以）
/website-to-video	将普通网站转成视频——网站导览、作品集／着陆页展示，或利用网站视觉素材制作社交媒体短片
/faceless-explainer	根据文本讲解主题／概念——不涉及产品或 URL；所有视觉内容均由大模型生成
/pr-to-video	将 GitHub PR／代码变更制作成变更日志、功能展示、修复说明或重构讲解视频
/embedded-captions	为现有的真人出镜视频添加字幕（不改动原始素材）
/talking-head-recut	为现有的真人出镜视频添加设计感图形叠加层——下三分之一字幕条、数据标注、动态标题、引用摘录
/motion-graphics	简短、无旁白、以设计为主的动态图形——动态字体、数据／图表展示、Logo 动效、下三分之一叠加层
/music-to-video	将音乐曲目制作成与节拍同步的视频——歌词视频、幻灯片或动态宣传片；音乐决定节奏（可选：将用户提供的图片／视频按节拍剪辑）
/slideshow	演示文稿／路演幻灯片／交互式幻灯片——包含独立幻灯片、片段、分支和热点；输出为可导航的幻灯片文稿，而非渲染后的视频
/general-video	其他所有类型——较长或多场景的视频、静态循环视频／海报、自定义合成
/remotion-to-hyperframes	将现有的 Remotion (React) 合成项目迁移到 HyperFrames（迁移，而非创建）

消除歧义（仅适用于容易混淆的情况）：

• 以动作为先，无旁白（时长约 10 秒以内，动作本身就是信息）→ /motion-graphics，无论输入内容是什么。
• URL 或脚本——用于推广特定产品（哪怕只是提到网站名称）→ /product-launch-video；一般的非产品网站 → /website-to-video；GitHub PR 链接 → /pr-to-video；不涉及产品或网站的概念讲解 → /faceless-explainer。如果产品与主题的区别确实不明确，或无法判断是产品发布还是一般网站 → 询问一个问题。
• 现有素材——仅添加口语字幕 → /embedded-captions；添加经过设计的叠加卡片 → /talking-head-recut。两者都不会编辑素材本身（重新定时 / 调色 / 重新取景 / 调整顺序 / 音频处理属于 NLE 编辑，不在范围内）。
• 输入是音乐曲目（音频文件，或从视频中提取音频），且没有旁白 → /music-to-video——节奏和能量感决定音乐的剪辑节奏。（带旁白的内容仍使用与输入匹配的上述工作流；/motion-graphics 适用于非音乐驱动的短篇无旁白动态内容。）
• 演示文稿 / 演示文稿幻灯片 / 交互式演示文稿（离散幻灯片、导航、演示者模式）→ /slideshow——输出是可导航的演示文稿，而非渲染后的视频。用户明确要求“幻灯片”时，直接继续；如果用户使用相近触发词（“演示文稿 / 幻灯片 / 演示 / 转换此页面”），则在创作前由 /slideshow 确认这是否是幻灯片；如果不是，则切换到合适的非幻灯片工作流。
• 时长是参考，不是硬性门槛——根据意图选择工作流；仅当内容明显超过约 3 分钟，或属于静态 / 循环 / 自定义格式时，才使用 /general-video。

如果匹配的工作流未安装

选定工作流后，检查它是否确实可用。如果匹配的工作流技能未安装，不要猜测着应付——告诉用户先安装：

• 仅安装此工作流： npx skills add heygen-com/hyperframes --skill <workflow-name>（例如 --skill pr-to-video——仅使用名称，不带开头的 /）。
• 一次安装所有工作流： npx skills add heygen-com/hyperframes --all（核心技能 + 所有工作流，跳过选择器）。

用户运行后，重新读取该工作流的技能并继续。

保持技能为最新版本

HyperFrames 技能有版本管理。npx hyperframes init 会检查已安装技能是否与 GitHub 上的最新版本一致；只要有任何技能过时或缺失，就会安装 / 刷新完整技能集。因此，全新初始化的项目始终包含完整的最新技能集（对已是最新版本的项目重新运行 init 则不会执行任何操作）。检查只需与 GitHub 快速往返一次；如果处于离线状态（或受到速率限制），则会在短暂超时后改为安装，因此 init 不会因网络故障而彻底失败。创建工作流会通过 init 搭建项目，因此每次启动新项目都会运行此检查，并在技能过时时从 GitHub 获取最新技能。--skip-skills 标志目前已失效（这是等待 skills.sh 注册表更新期间的临时措施）：传入该标志不再跳过检查，因此每次 init 都会检查 GitHub。CI / 测试通过 HYPERFRAMES_SKIP_SKILLS=1 环境变量跳过检查。

如果任务的行为与预期不符，或准备进行长时间构建之前，请确认已安装的技能为最新版本：

• 检查： npx hyperframes skills check（添加 --json 可获取机器可读的结果；任何技能过时或缺失时都会以非零状态码退出）。
• 更新： npx hyperframes skills update——将完整技能集更新至最新版本，并安装所有尚未安装的技能（与 init 的安装步骤相同）。

当 render / lint / validate 运行检测到技能过时时，CLI 也会显示一行提醒。

工作流详情

/product-launch-video

• 输入： 正在推广的产品——(a) 产品 URL（使用无头 Chrome 抓取素材和品牌标识），(b) 提及产品网站的脚本 / 简报，即使没有链接也可以（PLV 会解析并抓取该网站，除非用户选择退出），或 (c) 无法推导出网站的脚本 /“不要抓取”（无采集模式——选择一个提供配色板和设计系统的风格预设）。提供的脚本可以是逐字旁白，也可以是按场景重新编排的内容——PLV 会询问。
• 输出： 将产品发布 / SaaS 宣传视频制作为 HyperFrames 合成 → MP4。（最佳时长：30–90 秒）。
• 触发语：“为 X 制作发布视频”“为我们的网站制作宣传视频”“用一分钟介绍我的 SaaS”“把我的脚本改成 60 秒宣传视频”“纯文字发布视频，不要抓取”。

/website-to-video

• 输入： 要转成视频的一般网站 / URL——目标是制作一个展示网站的视频，而不是产品发布视频。使用无头 Chrome 捕获真实屏幕截图和品牌素材。
• 输出： 利用网站自身视觉素材制作网站导览 / 作品集 / 落地页展示 / 社交短片 → MP4。
• 触发语：“把这个网站转成视频”“制作网站导览，来自”“用我们的主页制作社交短片”“我只有一个 URL——帮我做点东西”。

/faceless-explainer

• 输入： 要进行讲解的任意文本——主题、文章或笔记，不涉及推广产品，也没有要捕获的网站。（从 /product-launch-video 派生；不使用无头 Chrome。）
• 输出： 无露脸讲解视频 → MP4；每个场景的所有视觉内容均由大模型生成（排版 / 抽象图形 / 图表 / 数据可视化）；随附 pin-and-paper 预设。（最佳时长：30–90 秒）。
• 触发语：“制作关于 X 的无露脸讲解视频”“用视频讲解 DNS 的工作原理”“把这篇文章改成讲解视频”“根据我的笔记制作讲解视频”。

/pr-to-video

• 输入： 一个 GitHub 拉取请求——PR URL、owner/repo#N 引用，或“这个 PR”——通过 gh CLI 读取（不是要抓取的网站）。
• 输出： 代码变更讲解视频（变更日志 / 功能展示 / 修复 / 重构）→ MP4——包含差异高亮、前后对比、文件树和影响场景。≤（最佳时长：30–90 秒）。
• 触发语：“为这个 PR 制作视频”“把 PR #1187 改成变更日志视频”“根据 github.com/org/repo/pull/123 制作发布说明视频”。

/embedded-captions

• 输入： 要添加字幕的现有对着镜头讲话的视频（MP4）——实际视频素材，不是 URL 或简报。使用本地工具转录（Whisper，无需 API 密钥），并进行抠像（RVM），使主体可以遮挡字幕。
• 输出： 保持原始素材不变，只添加字幕图层——标准（逐字字幕下三分之一轨道 + 一段嵌入主体后方的高潮字幕）或电影风格（所有字幕均合成在主体后方）。时长不限。
• 触发语：“给这个视频添加字幕”“把字幕放在主体后方”“给我的短片添加电影风格字幕”。

/talking-head-recut

• 输入： 要配上屏幕图形的现有对着镜头讲话 / 访谈 / 播客视频（MP4）——实际视频素材。使用本地工具转录（Whisper）。短片会在下方完整播放，且保持原样。
• 输出： 在同一段素材上添加与转录文本同步的定时图形叠加卡片——动态标题、下三分之一字幕条、数据提示、引述、侧边栏、画中画。时长不限。
• 触发语：“为这个视频添加包装”“为我的演讲添加图形叠加 / 下三分之一字幕条 / 数据提示”“把这段访谈剪成带图形包装的版本”。

/motion-graphics

• 输入： 短小、以设计为主导的动态图形，其中运动本身就是信息——通常时长不足约 10 秒，没有旁白。类型包括：动态排版、统计数据／数字递增动画、图表亮相、Logo 动效、下三分之一字幕／叠加层，或由搜索结果驱动的页面／推文／标题镜头。
• 输出： 短小的动态图形 → MP4，或用于下三分之一字幕／提示框的透明叠加层（带 Alpha 通道的 WebM／MOV）。
• 触发词：“制作一个 8 秒的 Logo 动效”“为这项统计数据制作动画”“一个动态排版风格的片头”“把这条推文做成动态图形”“透明的下三分之一字幕叠加层”。

/music-to-video

• 输入： 一首音乐曲目——音频文件，或用于提取音频的视频——没有旁白，也不捕捉网站内容。可选加入用户提供的图片／视频素材。系统会将曲目分析一次，生成确定性的节拍／能量图谱（audiomap.json），整个视频都基于该图谱构建。
• 输出： 与节拍同步的 HyperFrames 合成 → MP4，音乐决定视频节奏。排版和模板是基础配置（完整视频无需任何素材）；提供的媒体素材会按同一节拍网格剪辑（按节拍剪辑／Ken Burns 效果）。歌词视频、幻灯片、动态促销视频等类型由逐帧选择决定，流水线不会据此分支处理。
• 触发词：“为这首歌制作视频”“基于这首曲目制作节拍同步视频”“歌词视频”“把这段音乐做成视频”“配合这个节拍的音乐可视化／动态促销视频”。

/slideshow

• 输入： 要制作的演示文稿／路演材料／交互式演示文稿——可以是简介、提纲，或要转换成幻灯片的现有页面。不是要求渲染视频；如果意图不明确，该技能会在制作前确认：“你想把它做成 HyperFrames 幻灯片吗？”
• 输出： 可运行的 HyperFrames 合成 + 一个JSON 岛，播放器的 SlideshowController 会读取它，将 GSAP 时间轴转换为可导航的演示文稿——包含独立幻灯片、逐步显示内容、分支序列、热点导航、演讲者模式和演讲者备注。交付物是演示文稿，而不是 MP4。
• 触发词：“制作路演材料／演示文稿／幻灯片”“交互式演示文稿”“把这个页面转换成幻灯片”“带演讲者模式的幻灯片”。

/general-video

• 输入： 以上类型之外的任何内容——创意简介、需要制作动画的单个元素，或对正在制作的合成进行编辑。不限输入类型和时长。
• 输出： 通过原有流程制作 HyperFrames 合成（时长／格式不限）：设计系统 → 扩展提示词 → 规划 → 先布局后制作动画 → 构建（委派给 hyperframes-* 技能）→ 验证。
• 触发词：“制作标题卡”“为这个制作动画”“更长的品牌宣传片／精彩集锦”“多场景合成”“静态循环动画／海报”，以及任何不属于上述类别的“制作视频”请求。

/remotion-to-hyperframes

• 输入： 现有 Remotion（React）合成的源代码——用户明确要求移植／转换／迁移。单向转换（Remotion → HyperFrames）；不用于根据输入创建内容。仅仅提及 Remotion 并不会触发该技能。
• 输出： 根据 Remotion 源代码转换而来的 HyperFrames HTML 合成，并与 Remotion 渲染结果进行评分比较（SSIM 评估工具 + 分级测试语料库）。
• 触发词：“把我的 Remotion 项目移植到 HyperFrames”“转换这个 Remotion 合成”“从 Remotion 迁移”。