HyperFrames上手：可编辑视频工程

大家好，我是邵奈一，一个爱折腾的实战派技术博主。

文章对你有帮助是我的荣幸，欢迎评论区交流。

0x00 教程概览

HyperFrames 把"网页代码"当成视频源：HTML 就是时间轴上的画面，AI 生成第一稿后，你拿到的不是一段黑盒 MP4，而是一份能继续改的工程。本教程跑通"建项目 → 改内容 → 导出成片 → 批量出多版本"的完整链路，重点不在"一句话出片"，而在"出完之后还能不能方便地改"。

你会做出一条可改的课程介绍短片：标题、强调色、开课日期用变量暴露，改一处即可出多个版本。

前置条件：本机装好 Node.js，能跑 npx 即可，无需提前全局安装任何包；网络可访问 npm 源。文中命令整理自 HyperFrames 官方文档（hyperframes.heygen.com）与 npx hyperframes <command> --help，未在本机逐条实跑，请以你安装版本的帮助输出为准（v0.8.145 起 Studio 已支持 GPU 编码导出，并修复了长视频导出卡在 90%、字体或素材加载停滞等问题，但本教程不依赖该版本特性）。

配图说明：文中界面图来自官方文档，统一标注"（官方）"；终端与导出类操作以代码块呈现，你本地实跑后的截图可替换对应位置。

0x01 一条命令建好工具链

HyperFrames 不需要先 npm install。npx 会按需拉取 CLI，第一次运行稍慢属正常。

新建一个项目骨架：

bash 复制代码

npx hyperframes init my-video

进入目录后，先做环境自检，确认 Chrome、FFmpeg 等渲染依赖就位：

bash 复制代码

cd my-video
npx hyperframes doctor

doctor 会报告缺失项并给出修复提示，比直接渲染报错更省时间。后续任何异常都可先跑它。

0x02 项目结构：HTML 就是视频

init 生成的目录大致如下：

复制代码

my-video/
├── BRIEF.md          视频要传达的信息
├── STORYBOARD.md     分镜与评审状态
├── SCRIPT.md         定稿旁白（有旁白时）
├── frame.md          视觉方向（需要时）
├── index.html        主合成
├── hyperframes.json  项目设置
├── compositions/     场景与可复用部件
├── assets/           图片、视频、音频、字体
└── renders/          成片

只有 index.html 加 assets/ 是必需的；其余 BRIEF.md、STORYBOARD.md 等是给 AI 与人工评审留的决策记录，简单标题卡可以全不要。

关键认知：Agent、Studio、CLI、SDK、Player 读写的是同一份文件，不存在"导出后的第二份工程"。Studio 的编辑会写回源码，Git 能直接跟踪，渲染器看到的结果也一致。这正是它和普通"一句话生成视频"工具的分界------成片背后始终有一份可编辑源。

0x03 把时间写进源码

视频的"时间"直接写在 HTML 属性里。主合成声明视口与时长：

html 复制代码

<!doctype html>
<html lang="zh">
  <body>
    <div
      id="main"
      data-composition-id="intro"
      data-start="0"
      data-duration="8"
      data-width="1920"
      data-height="1080"
    >
      <h1
        id="title"
        class="clip"
        data-start="0"
        data-duration="3"
        data-track-index="1"
      >课程开课通知</h1>

      <img
        id="cover"
        class="clip"
        data-start="2"
        data-duration="4"
        data-track-index="1"
        src="./assets/cover.png"
      />

      <div
        data-composition-id="goals"
        data-composition-src="compositions/goals.html"
        data-start="3"
        data-duration="5"
        data-track-index="2"
      ></div>
    </div>
  </body>
</html>

三个定时属性决定每个元素的命运：data-start 第几秒出现，data-duration 持续几秒，data-track-index 放在哪条轨道。上面这张图从 2 秒出现、停留 4 秒、位于轨道 1；动画时间线是可暂停、可定位的，Studio 与渲染器都能直接请求某一精确时刻，不必从头播放。

复杂项目把场景拆到 compositions/，主时间轴用 data-composition-src 引用。嵌套合成的时间也能用相对锚点，例如 data-start="after:#intro" 表示接在上一个片段之后，改前面片段时长时后面自动顺延。

0x04 在 Studio 里改：所见即所得

不想碰代码时，用 Studio 做可视化编辑：

bash 复制代码

npx hyperframes preview

它会打开本地 Studio，左侧是源文件树，中间画布，右侧参数与下方时间轴。

你在 Studio 里改的文字、颜色、时间、动画，会写回 index.html 与 compositions/。这意味着：AI 先生成一版，你在 Studio 微调，之后还能让 AI 基于这些文件继续改，三者始终围绕同一份源。评审时先看完整预览再抠细节，避免被一张好看的静帧带偏。

0x05 变量：把"该改的"和"别动的"分开

同一套设计要给多门课、多个客户出片时，把"允许变化的部分"声明成变量，布局与运动保持不变。

在合成根节点声明变量：

html 复制代码

<html
  data-composition-variables='[
  {"id":"title","type":"string","label":"标题","default":"课程开课通知"},
  {"id":"date","type":"string","label":"开课日期","default":"3 月 1 日"},
  {"id":"accent","type":"color","label":"强调色","default":"#6c5ce7"}
]'
></html>

支持的类型如下：

在 HTML 里绑定变量，而不是写死：

html 复制代码

<h1 data-var-text="title">课程开课通知</h1>
<p data-var-text="date">3 月 1 日</p>
<img data-var-src="cover" src="./assets/cover.png" alt="" />

<style>
  .title { color: var(--accent); }
</style>

data-var-text 替换元素自身文字，data-var-src 替换图片或媒体地址，标量变量会作为 CSS 自定义属性 var(--accent) 可用。嵌套合成还能给同一份源传不同值：

html 复制代码

<div
  data-composition-id="card-a"
  data-composition-src="compositions/card.html"
  data-start="0"
  data-duration="3"
  data-variable-values='{"title":"A 班","accent":"#ff4d4f"}'
></div>

不改源码也能换内容，用 CLI 覆盖变量渲染：

bash 复制代码

npx hyperframes render \
  --variables '{"title":"国庆特训营","accent":"#ff4d4f"}' \
  --strict-variables \
  --output renders/holiday.mp4

--strict-variables 会把未声明或类型不符的覆盖值直接报错，防止拼错字段悄悄渲染出空内容。

边界要记清：变量改的是合成"内部"的内容，不能改视口尺寸、总渲染时长、帧率、输出格式与编码，这些由源文件或渲染设置决定。结构本身要变，走正常编辑而非变量。

0x06 交付成片：lint → check → render

导出前先过质量门，顺序固定，省得渲染一半才发现结构错。

结构检查，抓组合声明类错误：

bash 复制代码

npx hyperframes lint

完整检查，在 lint 基础上加浏览器、布局、运动与 WCAG 对比度校验：

bash 复制代码

npx hyperframes check

抽几帧预览，确认关键时间点画面正确：

bash 复制代码

npx hyperframes snapshot --at 0,2,5

确认无误后本地渲染：

bash 复制代码

npx hyperframes render --output renders/final.mp4

输出格式按投放目标选，不要盲目上 4K 或高帧率------高分辨率不会给低清素材补细节，高帧率也不会改善低帧率编排的运动：

最后一步是"看导出文件本身"，不是看预览：开 renders/final.mp4 核对开头结尾、字幕、最复杂的转场，以及时长、尺寸、格式、音轨是否都对。预览只证明项目能播，导出文件才证明交付正确。

0x07 一份设计批量出 N 条

同一套设计换不同标题、客户名，逐条改太慢。把变量值写成 JSON 数组，一次渲染多份：

json 复制代码

[
  {"name":"class-a","title":"A 班开课通知"},
  {"name":"class-b","title":"B 班开课通知"}
]

bash 复制代码

npx hyperframes render \
  --batch rows.json \
  --strict-variables \
  --output "renders/{name}.mp4"

{name} 取自每行数据的 name 字段，自动命名。并发数用 --batch-concurrency 控制，等一次稳定渲染、确认机器内存够同时跑多个时再调高，不要一上来拉满。

0x08 故障自查三板斧

渲染或预览异常时，按这个顺序定位：

bash 复制代码

npx hyperframes doctor     # 查环境依赖
npx hyperframes lint       # 查结构声明
npx hyperframes check      # 查浏览器/布局/运动/对比度

比对两个版本差异用：

bash 复制代码

npx hyperframes compare v1/ v2/

磁盘被渲染中间文件占满时清理：

bash 复制代码

npx hyperframes clean

check 能抓技术失败，但判断不了"故事讲得好不好"------修完技术错误若改动了观感，再完整看一遍预览。

0xFF 总结与下一步

核心价值一句话：HyperFrames 的价值不在"AI 替你出第一稿"，而在"它把第一稿的结构留成了可编辑工程"，让你的下一次修改有确定性的下手处。证据来自它的工程模型------Agent、Studio、CLI、渲染器共用同一份 HTML 源，Studio 编辑写回源码，变量把"该改的"与"别动的"分开。

据此给你的落地顺序：第一，先用 init 跑通一条你确实会反复改的短内容；第二，把标题、配色、日期等易变项声明成变量，固定布局与运动；第三，用 lint + check 卡质量门，再用 render 出片；第四，多版本需求直接上 --batch，别手工复制工程。

读者可改进方向：

把 lint + check + render 接进 CI，每次改源码自动出片与比对。
用 --batch 配合数据表，做"千人千面"的客户卡片或课程通知。
变量模板沉淀成内部 Catalog，新项目直接复用已确认的设计。
实拍素材与图形动画组合，用 HyperFrames 做精确编排的片头与数据解说。

原创声明 ：本文为博主原创，步骤与命令整理自 HyperFrames 官方文档（hyperframes.heygen.com）及 CLI 帮助输出；如有版本差异，以你安装版本的 npx hyperframes <command> --help 为准。

邵奈一 三百篇原创沉淀，十万+读者同行。感谢你的阅读，咱们下篇接着聊。