每天一个开源项目#93 HyperFrames：4.69万星的 HTML 视频渲染框架

GitHub Trending #1 | 2026-09-08 | Stars: 46,895 | Forks: 4,352 | 主语言: TypeScript | License: Apache-2.0 | GitHub: github.com/heygen-com/...

做产品短视频、PR 讲解、动态图字幕，最烦人的地方往往不是创意，而是工程交付。设计师要时间轴，前端更熟 HTML/CSS，AI Agent 又最擅长改文本文件。结果到了渲染阶段，大家还是得把东西搬进剪辑软件，或者写一套 React/Canvas 工程。

HyperFrames 的选择很直接：把视频当成一个可寻址、可复现的 HTML 页面。页面里用 data-start、data-duration、data-track-index 描述时间轴，用 CSS 做布局，用 GSAP、Lottie、Three.js、Anime.js 或 WAAPI 做可 seek 的动画，最后交给 headless Chrome 逐帧捕获，再用 FFmpeg 编码成 MP4、WebM、MOV 或 PNG 序列。

它的另一个现实价值在 Agent 场景。普通网页资料并不会告诉模型"视频里哪个元素该由框架控制播放，哪个元素只该改 opacity"。HyperFrames 在仓库里放了 20 个已发布技能，把视频生产拆成路由、创作、核心约束、音频、关键帧、字幕、PR-to-video 等工作流。换句话说，它不是只给人写的渲染库，也在给 Agent 设一套不容易跑偏的视频生产规矩。

📋 项目概览

项目	内容
项目名	heygen-com/hyperframes
一句话	用 HTML/CSS/动画时间轴定义视频，并把它确定性渲染为视频文件
Stars	46,895（Trending 快照）
Forks	4,352（Trending 快照）
语言	TypeScript 89.9%、JavaScript 9.4%、Shell 0.3%、Python 0.2%、CSS 0.1%
License	Apache-2.0
版本	npm `hyperframes` latest: 0.8.31；GitHub Release: v0.8.31（2026-09-07）
仓库创建时间	2026-03-10
最近默认分支提交	e5d89f7，2026-09-08，提交信息为 `feat(check): flag connectors that point at nothing and stylesheets that leak into the frame (#3736)`
开放问题	182（GitHub API 补充校验）
仓库结构	7,122 个 tracked files；`packages/` 3,393 个文件，`skills/` 909 个文件，`docs/` 1,038 个文件，`registry/` 1,351 个文件

🔥 为什么值得关注

HTML 做视频这件事并不新。Remotion 已经证明了"浏览器 + FFmpeg"能支撑工程化视频生成。HyperFrames 有意思的地方在于，它把作者模型从 React 项目降到了普通 HTML 文件。对人来说，这降低了上手成本；对 Agent 来说，这减少了项目脚手架、构建链和组件抽象带来的误判空间。

我更在意它对"时间"的处理。普通网页动画是墙钟驱动的，动画从页面加载那一刻开始跑；视频渲染需要的是任意帧可定位，1.2 秒、3.5 秒、最后一帧都必须能回放到同一个画面。HyperFrames 要求动画注册到 window.__timelines，媒体播放由框架接管，脚本不要手动 video.play() 或乱改 currentTime。这套约束看起来啰嗦，但它正是可复现渲染的底线。

源码也不像一个薄包装。packages/producer/src/services/renderOrchestrator.ts 里把渲染拆成 compile、probe、extract videos、audio、capture、encode、assemble 六个阶段；packages/core/src/compiler/compositionAssembly.ts 把子组合、样式提升、脚本作用域、变量默认值这些决策抽成 DOM-free 的纯逻辑；packages/producer/src/services/render/capturePlan.ts 用不可变的 CapturePlan 表达截图、流式编码、HDR 分层、失败回退。这个项目的复杂度主要在"让网页像视频工程一样可控"，而不是在命令行外面包一层壳。

🏗️ 核心特性

用 HTML 直接描述时间轴

HyperFrames 的最小心智模型是"DOM 节点就是 clip"。视频、图片、音频、嵌套 composition 都是时间轴上的元素，开始时间、持续时间、轨道层级写在 data-* 属性上。

html 复制代码

<div id="stage" data-composition-id="launch" data-start="0" data-width="1920" data-height="1080">
  <video
    class="clip"
    data-start="0"
    data-duration="6"
    data-track-index="0"
    src="intro.mp4"
    muted
    playsinline
  ></video>

  <h1 id="title" class="clip" data-start="1" data-duration="4" data-track-index="1">
    Launch day
  </h1>

  <audio
    data-start="0"
    data-duration="6"
    data-track-index="2"
    data-volume="0.5"
    src="music.wav"
  ></audio>

  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
  <script>
    const tl = gsap.timeline({ paused: true });
    tl.from("#title", { opacity: 0, y: 40, duration: 0.8 }, 1);
    window.__timelines = window.__timelines || {};
    window.__timelines.launch = tl;
  </script>
</div>

这段例子背后的规矩很关键：元素何时出现在画面上由 data-start 和 data-duration 决定，视觉变化由动画时间轴决定，媒体 seek 由框架负责。脚本只描述动画，不接管播放器。

渲染管线从预检到编码都有独立阶段

@hyperframes/producer 的 README 把执行路径写得很清楚：本地文件服务启动后，Chrome 加载 composition，渲染器按帧 seek，截图或 BeginFrame 捕获每一帧，FFmpeg 编码，音频轨混合，最后做输出文件整理。源码里的阶段拆分和 README 对得上。

text 复制代码

HTML composition
      │
      ▼
compile: 解析 composition、变量、子组合、静态约束
      │
      ▼
probe: 浏览器侧探测时长、媒体可播放性、ready 状态
      │
      ▼
extract videos: 抽取源视频帧，建立 frame lookup
      │
      ▼
audio: 抽取与混音音频轨
      │
      ▼
capture: Headless Chrome 逐帧捕获，按计划选择截图/流式/HDR 路径
      │
      ▼
encode + assemble: FFmpeg 编码、拼接分片、生成最终文件

支持透明视频、HDR、PNG 序列和分布式渲染，但边界写得比较实

输出格式不是只有 MP4。Producer 文档列出 mp4、webm、mov、png-sequence，其中 WebM 走 VP9 alpha，MOV 走 ProRes 4444，PNG 序列保留 RGBA 帧。这里有明确限制：HDR 和 alpha 不能同时使用；Linux 上 alpha 会回退到截图捕获；PNG 序列的音频是旁路 audio.aac，不是单个 muxed 文件。

输出	编码/容器	Alpha	典型用途	文档边界
MP4	H.264 或 H.265/HDR10	不支持	社交平台、普通成片	默认路径
WebM	VP9 + `yuva420p`	支持	Web 透明覆盖层	Safari 支持不完整
MOV	ProRes 4444	支持，10-bit	进入剪辑软件	文件体积通常更大
PNG sequence	RGBA PNG	支持，无损	AE/Nuke/Fusion 后处理	音频写为 sidecar

分布式部分也不是一句"支持云渲染"带过。@hyperframes/producer/distributed 暴露 planV2、renderChunkV2、assembleV2。Plan v2 使用 immutable manifest 和 content-addressed artifacts，worker 只物化自己需要的依赖。这个设计更像一条能接 Lambda、Cloud Run、K8s 或 Temporal 的渲染中间层。

给 Agent 的技能不是装饰，而是路由层

仓库里有 32 个 SKILL.md，其中 skills/ 下发布了 20 个对外技能，.claude/skills 和 .agents/skills 里还有镜像或内部技能。入口技能 /hyperframes 先判断项目状态，再把任务路由到 /product-launch-video、/faceless-explainer、/pr-to-video、/embedded-captions、/motion-graphics、/slideshow 等工作流。

text 复制代码

用户请求
  │
  ├─ 已有 HyperFrames 项目：直接 inspect / check / render / edit
  │
  ├─ 明确 Remotion 迁移：进入 remotion-to-hyperframes
  │
  └─ 新建内容：intent interview 写 BRIEF.md
          │
          ▼
    路由到具体 workflow skill
          │
          ▼
    按需加载 core / animation / keyframes / audio / registry / media-use
          │
          ▼
    生成 HTML composition，运行 check，预览或渲染

这里要分清楚：技能文件本身是 Agent-mediated 规则，不是操作系统沙箱，也不是保证模型一定不犯错的 linter。真正的可执行约束来自 CLI 的 check、lint、runtime validation、布局检查、对比度检查、测试脚本和 CI。HyperFrames 做得较好的地方是把两层放在一个仓库里，让 Agent 规则能指向可运行的检查命令。

验证命令覆盖静态、运行时和视觉布局

CLI 的 check 命令不是简单 lint。已校验的 v0.8.31 help 显示，它会在一个浏览器会话里跑 lint、runtime、layout、motion、WCAG contrast verification，并支持 --samples、--at、--at-transitions、--snapshots、--frame-check、--caption-zone 等参数。

检查面	相关命令或源码	作用
静态 composition 约束	`hyperframes lint` / `hyperframes check`	捕获常见 HTML、轨道、时长、引用问题
运行时验证	`hyperframes validate` / `check` pipeline	在 headless Chrome 中加载页面，检查脚本和媒体状态
布局检查	`check --samples`、`--at`、`--at-transitions`	对多个时间点检查溢出、转场缝隙等问题
对比度	`check --contrast`，默认开启	对画面采样做 WCAG AA 检查
可视证据	`check --snapshots`、`snapshot`、`compare`	保存关键帧或对比图，方便人工复核

仓库测试和性能门槛比较重

浅克隆审计显示，仓库有 7,122 个 tracked files，packages/ 下约 76.9 万行文本，测试或 fixture 路径约 1,241 个。Player 的性能基线文件给出了一组内部门槛：冷加载 P95 2,000 ms、暖加载 P95 1,000 ms、scrub latency P95 isolated 80 ms、inline 33 ms、parity SSIM 最低 0.93。这些是仓库内置基线，不等价于我在本机复跑后的独立 benchmark。

指标	仓库内置阈值	说明
`compLoadColdP95Ms`	2000 ms	composition 冷加载 P95 上限
`compLoadWarmP95Ms`	1000 ms	composition 暖加载 P95 上限
`scrubLatencyP95IsolatedMs`	80 ms	隔离场景 scrub 延迟 P95
`scrubLatencyP95InlineMs`	33 ms	inline 场景 scrub 延迟 P95
`paritySsimMin`	0.93	渲染一致性的 SSIM 底线
`allowedRegressionRatio`	0.1	可接受回归比例

🔬 技术架构深度解析

HyperFrames 可以拆成四层：作者协议、运行时、渲染生产线、Agent 工作流。它们都在同一个 monorepo 里，但权责并不一样。

text 复制代码

┌──────────────────────────────────────────────────────────┐
│ Authoring layer                                           │
│ HTML + CSS + data-* timing + GSAP/WAAPI/Lottie/Three.js   │
└────────────────────────────┬─────────────────────────────┘
                             │
┌────────────────────────────▼─────────────────────────────┐
│ Core runtime                                               │
│ parse clips, mount/unmount, media seek, variables,        │
│ sub-composition assembly, frame adapters                  │
└────────────────────────────┬─────────────────────────────┘
                             │
┌────────────────────────────▼─────────────────────────────┐
│ Producer / Engine                                          │
│ local file server, Chrome session, BeginFrame/screenshot, │
│ video frame extraction, audio mix, FFmpeg encode          │
└────────────────────────────┬─────────────────────────────┘
                             │
┌────────────────────────────▼─────────────────────────────┐
│ Tooling surface                                            │
│ CLI, Studio, Player, AWS Lambda, Cloud Run, SDK, skills   │
└──────────────────────────────────────────────────────────┘

作者协议层最重要的是"谁拥有时间"。packages/core/docs/core.md 明确要求 composition 声明 data-width、data-height，clip 声明 data-start、data-duration 和 data-track-index。框架管理 primitive clip 的 timeline entries、媒体播放、clip 生命周期和媒体加载；转场、视觉动效、文字运动交给脚本。这个分工避免了脚本一边改媒体状态、框架一边 seek 的双控制问题。

子组合系统是另一个容易出错的点。compositionAssembly.ts 的注释解释得很具体：同一套 assembly 决策会被 Node 编译路径和浏览器 runtime 路径使用，I/O 不同，但决策不能漂移。它收集 style、script、link、变量默认值载体，处理 data-composition-src，还有 20 层嵌套上限和循环引用跳过逻辑。这个文件 DOM-free、filesystem-free、network-free，是为了能被 linkedom 和浏览器 DOM 共同调用。

渲染层的状态机比 README 更能说明工程难度。CapturePlan 把 SDR streaming、SDR disk、HDR layered 三类捕获路径建成不可变对象，失败回退只能通过 replanAfterFailure。例如 streaming 不可用时可以回退 disk；drawElement 自检失败时强制走 screenshot；内存耗尽时 worker 数可能降到 1。这比一堆布尔值安全，因为无效组合不容易在中间状态里冒出来。

text 复制代码

createCapturePlan
  │
  ├─ useLayeredComposite=true  ─► hdr_layered + forceScreenshot
  │
  ├─ useStreamingEncode=true   ─► sdr_streaming
  │        │
  │        ├─ streaming_unavailable ─► sdr_disk
  │        ├─ draw_element_verify   ─► screenshot fallback
  │        └─ capture_failure(memory) ─► workerCount 降级 / 路由回退
  │
  └─ otherwise                 ─► sdr_disk

服务端接口也比较完整。packages/producer/src/server.ts 暴露 POST /render、POST /render/stream、GET /render/queue、POST /lint、GET /health、GET /outputs/:token。HandlerOptions 里有 artifactTtlMs、maxConcurrentRenders、rendersDir、outputUrlPrefix。它默认同时执行 2 个 render，并用 FIFO 队列处理并发。这说明 Producer 不只是 CLI 内部函数，也可以作为渲染服务嵌进别的系统。

版本面上也要分开看：GitHub Release 最新是 v0.8.31，npm hyperframes latest 也是 0.8.31，仓库 packages 里大部分 @hyperframes/* 也是 0.8.31；@hyperframes/sdk-playground 在源码里是 0.6.106。这种差异不一定是问题，但说明它是 monorepo 多包发布，不该把所有包都写成同一个"产品版本"。

📖 README 核心内容摘要

README 给 HyperFrames 的定位是"Write HTML. Render video. Built for agents." 它推荐两条入口：人可以直接用 CLI 初始化项目、预览、渲染；Agent 可以先安装 HyperFrames skills，再由 /hyperframes 路由到具体工作流。

CLI 路径很短，Node.js 要求是 22+，本地渲染还需要 FFmpeg。v0.8.31 的命令面包括 init、preview、render、lint、check、validate、snapshot、compare、benchmark、doctor、skills、cloud、lambda、cloudrun、tts、transcribe、remove-background 等。render --help 里确认支持 --format mp4|webm|mov|gif|png-sequence、--workers、--resolution、--variables、--batch、--docker、--browser-gpu、--low-memory-mode 等参数。

Agent 技能部分的设计不是一次性塞满上下文。入口 /hyperframes 是 router，先判断任务类型和项目状态，再按需安装 workflow skill；domain skills 则覆盖 core、animation、keyframes、creative、audio、media、registry、figma 等层。README 里写的"默认 core set + 按需 workflow"与 skills/SKILL.md 的路由表一致。

README 还把 HyperFrames 和 Remotion 做了比较。两者都使用 headless Chrome 和 FFmpeg；Remotion 的作者模型是 React components，HyperFrames 的作者模型是 HTML + CSS + seekable animation。这个取舍有代价：React 生态的组件化能力更成熟；HyperFrames 则把 Agent 可读写的纯文本 composition 放在第一优先级。

Producer API 可以直接嵌入 TypeScript 服务：

typescript 复制代码

import { createRenderJob, executeRenderJob } from "@hyperframes/producer";

const job = createRenderJob({
  inputPath: "./my-composition.html",
  outputPath: "./output.mp4",
  width: 1920,
  height: 1080,
  fps: 30,
});

const result = await executeRenderJob(job, (progress) => {
  console.log(`${Math.round(progress.percent * 100)}%`);
});

console.log(result.outputPath);

分布式渲染 API 则把控制器和 worker 拆开：

typescript 复制代码

import { planV2, renderChunkV2, assembleV2 } from "@hyperframes/producer/distributed";

const planResult = await planV2(
  projectDir,
  { fps: 30, width: 1920, height: 1080, format: "mp4" },
  "/tmp/plan-v2",
);

const chunk = await renderChunkV2("/tmp/plan-v2", 0, "/tmp/chunks/0.mp4");
await assembleV2("/tmp/plan-v2", ["/tmp/chunks/0.mp4", "/tmp/chunks/1.mp4"], "/tmp/output.mp4");

这些 API 示例来自 README 与源码导出面，适合说明结构；生产使用时仍要根据部署环境处理 Chrome、FFmpeg、字体、缓存目录、GPU 和并发资源。

🚀 快速上手

下面的命令按 v0.8.31 的 --help 输出核验过，适合先跑一个空白工程，再进入检查和渲染。真实渲染是否成功取决于本机 Chrome/Chromium、FFmpeg、字体和媒体文件环境。

bash 复制代码

npx hyperframes@0.8.31 init my-video --example blank --non-interactive
cd my-video
npx hyperframes@0.8.31 check
npx hyperframes@0.8.31 render --format mp4 --output renders/demo.mp4

如果是给 Agent 安装 HyperFrames 的核心技能集，可以用：

bash 复制代码

npx hyperframes@0.8.31 skills update

如果只是检查本机依赖，先跑：

bash 复制代码

npx hyperframes@0.8.31 doctor --json

一个最小 composition 可以长这样。重点不是视觉多复杂，而是时间归属清楚：clip 的出现时间写在属性上，动画注册成 paused timeline，框架在渲染时按帧 seek。

html 复制代码

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
    <style>
      body { margin: 0; background: #111; color: white; font-family: system-ui; }
      [data-composition-id="demo"] { display: grid; place-items: center; overflow: hidden; }
      #title { font-size: 88px; letter-spacing: -0.04em; }
    </style>
  </head>
  <body>
    <div data-composition-id="demo" data-start="0" data-width="1920" data-height="1080">
      <h1 id="title" class="clip" data-start="0" data-duration="4" data-track-index="1">
        HTML to MP4
      </h1>
      <script>
        window.__timelines = window.__timelines || {};
        const tl = gsap.timeline({ paused: true });
        tl.from("#title", { opacity: 0, y: 48, duration: 0.8 });
        tl.to("#title", { scale: 1.08, duration: 2.4 });
        tl.to("#title", { opacity: 0, y: -32, duration: 0.8 });
        window.__timelines.demo = tl;
      </script>
    </div>
  </body>
</html>

实际项目里，我建议把 quickstart 分成三步：先用 check 把 composition 结构跑通，再用 snapshot 或 compare 看关键帧，最后才 render。视频生成的失败经常不是编码器问题，而是某个媒体没 ready、字幕出界、转场在一帧里重叠了。

📊 增长速度与社区热度

Trending 快照保留了总 Stars 和 Forks，没有保留每个仓库的当日新增 Stars。因此这里不编造"今日新增"。HyperFrames 从 2026-03-10 创建到 2026-09-08 快照约 181.9 天，按 46,895 Stars 粗算，生命周期平均约 257.8 Stars/天。这个数只能看作累计热度基线，不能替代真实日增曲线。

指标	数值	说明
Trending 排名	#1 / 14	2026-09-08 快照
Stars	46,895	快照值
Forks	4,352	快照值
Open Issues	182	GitHub API 补充校验
Watchers	131	GitHub API 补充校验
Top contributor commits	1,732 / 1,001 / 881	前三位贡献者，API 补充校验
最近 Release	v0.8.31	2026-09-07 发布
最近 5 个 Release	v0.8.31、v0.8.30、v0.8.29、v0.8.28、v0.8.27	2026-09-03 到 2026-09-07 之间发布
仓库大小	412,122 KB	GitHub API 元数据

完整 Trending 榜单如下，排名来自快照数组顺序；当日 Stars 字段未被预跑脚本保留。

Rank	Repository	Language	Stars	Daily Stars
1	heygen-com/hyperframes	TypeScript	46,895	未保留
2	microsoft/markitdown	Python	180,949	未保留
3	mksglu/context-mode	TypeScript	21,092	未保留
4	jo-inc/camofox-browser	JavaScript	10,026	未保留
5	MoonTechLab/LunaTV	TypeScript	9,987	未保留
6	affaan-m/ECC	JavaScript	253,326	未保留
7	coreyhaines31/marketingskills	JavaScript	48,373	未保留
8	The-Swarm-Corporation/AutoHedge	Python	5,407	未保留
9	BraveOPotato/FckSignups	TypeScript	3,994	未保留
10	bytedance/deer-flow	Python	81,990	未保留
11	openai/skills	Python	26,219	未保留
12	lightpanda-io/browser	Zig	35,052	未保留
13	pascalorg/editor	TypeScript	22,520	未保留
14	ruvnet/ruflo	TypeScript	71,529	未保留

社区活跃度要分两面看。一面是 release 频率很高，最近几天连续发布，默认分支在快照日也有功能和修复提交；另一面是仓库年轻、issues 已经到 182，star 增长速度明显高于普通基础设施项目。对生产团队来说，这意味着生态热，但接口和最佳实践可能还在快变。

🎯 适用场景

场景	为什么适合	需要注意
产品发布短片	HTML/CSS 能复用网站视觉语言，Agent 可以从 URL、文案和素材生成 composition	品牌一致性仍要人工看关键帧，不能只信文字检查
PR / changelog 视频	仓库自带 `/pr-to-video` 工作流，适合把代码变化转成讲解视频	需要 GitHub 访问权限和清晰的变更范围
自动化社交短视频	CLI、batch variables、模板和 registry 适合批量生成同构内容	大批量渲染要规划 Chrome/FFmpeg/缓存目录资源
字幕和 talking-head 包装	有 embedded captions、talking-head recut、audio 等技能和媒体处理命令	口播素材质量、转写准确率和字幕安全区要复核
数据可视化 / chart / map 动画	Web 技术栈天然适合图表、SVG、Canvas、Three.js	动画必须可 seek，不能依赖 wall-clock side effect
分布式渲染服务	Producer server、AWS Lambda、Cloud Run、Plan v2 分片接口已经在仓库里	WebM/HDR/alpha 等格式在分布式路径上有边界，部署前要按格式验收
Agent 视频生产流水线	20 个发布技能提供路由、创作、检查和领域知识	技能是模型遵循的协议，不能替代沙箱、权限控制和人工审片

💡 总结

HyperFrames 最值得看的地方，不是"HTML 也能做视频"这个标题，而是它把网页、视频、Agent 三个工程世界接到了一起。HTML 负责可读写的结构，data-* 负责时间和轨道，runtime 负责 seek 与媒体生命周期，Producer 负责 Chrome 捕获和 FFmpeg 输出，skills 负责把 Agent 从"随便写个网页动画"拉回视频生产流程。

它还年轻，版本号停在 0.x，release 节奏很快，API 和工作流可能继续变。可这类项目一旦跑通，价值很实在：开发者不用离开文本工程环境，就能把设计、代码、素材、旁白和渲染串成一条可自动化的流水线。对需要批量生成技术视频、产品短片、PR 讲解或字幕包装的团队，HyperFrames 已经值得认真试一次。