HyperFrames 完整教學

一份「HTML 寫到一半，影片就出來了」的開源框架 — 把 Web 標準作為 video composition (影片合成) 的權威介面，並把整個 production loop (製作流程) 設計成 AI agent 也能上手。

1. 專案定位

一句話：用 HTML 寫 composition、用 Puppeteer 對每個 frame 做 seek、用 FFmpeg 編碼成 deterministic MP4 (確定性 MP4) 的開源 video rendering framework，明確定位為 agent-first (代理優先) 的 Remotion 替代方案。

1.1 為什麼會出現 HyperFrames？

1.2 典型使用情境

• 產品 launch 影片 / 功能發表
• PR walkthrough (含 animated code diff + 旁白 + 字幕)
• Data viz / chart race / map animation
• 社群短片（含 kinetic captions、overlay、配樂）
• Docs → video / PDF → video / website → video 自動化
• 重複利用的 motion graphics 模板，內嵌進 content pipeline

1.3 核心定位：HF vs Remotion

2. 安裝指南

2.1 系統需求

• Node.js >= 22
• FFmpeg（render 階段必需）
• Bun（開發 monorepo 時必用；單純使用 CLI 可用 npx）
• Git LFS（僅在 clone 完整 repo 開發、需要 240MB 的 golden test baseline 時）

2.2 安裝方式：兩種路徑

A. AI Agent 路徑（推薦給有 Claude Code / Cursor / Gemini CLI 的人）

1npx skills add heygen-com/hyperframes

裝完後在 agent prompt 內叫：

Using /hyperframes, create a 10-second product intro with a fade-in title, a background video, and subtle background music.

Agent 會走 HF 內建的 production loop：plan → write HTML → wire animation → add media → lint → preview → render。

B. 手動 CLI 路徑（傳統開發者）

1npx hyperframes init my-video      # 建專案骨架
2cd my-video
3npx hyperframes preview            # 啟 dev server（含 live reload）
4npx hyperframes render             # 渲染成 MP4

2.3 從原始碼 build（monorepo 開發者）

 1# 1. clone（跳過 LFS 大檔可加環境變數）
 2GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/heygen-com/hyperframes.git
 3cd hyperframes
 4
 5# 2. 安裝（必用 bun，禁 pnpm）
 6bun install
 7
 8# 3. build 所有 package
 9bun run build
10
11# 4. 啟 Studio
12bun run studio   # = bun run --filter @hyperframes/studio dev

2.4 安裝流程圖

flowchart TD
    A[使用者] --> B{你怎麼寫影片?}
    B -->|AI agent| C[npx skills add heygen-com/hyperframes]
    B -->|手動 CLI| D[npx hyperframes init]
    B -->|貢獻原始碼| E[git clone + bun install]
    C --> F[在 Claude Code/Cursor prompt]
    D --> G[npx hyperframes preview]
    E --> H[bun run studio]
    F --> I[npx hyperframes render]
    G --> I
    H --> I
    I --> J[MP4 output]

3. 核心架構解析

3.1 三層架構

HyperFrames 是 HTML composition → seekable runtime → frame capture pipeline 三段式架構：

1. Composition Layer：使用者寫 index.html，內含 data-composition-id / data-start / data-duration / data-track-index 等 data attribute (資料屬性)。
2. Runtime Layer：@hyperframes/core 載入 composition 後，把 GSAP / Lottie / WAAPI / Three.js / Anime.js timeline (時間軸) 暴露成 window.__timelines.<id>，由 engine 透過 timeline.seek(t) 控制。
3. Engine Layer：@hyperframes/engine 用 Puppeteer 開無頭 Chrome，每個 frame 做 await timeline.seek(t) + await page.screenshot()，餵給 FFmpeg 編碼。

3.2 Component 互動圖

flowchart LR
    A[index.html composition] --> B[@hyperframes/core]
    B --> C[adapter: GSAP/Lottie/CSS/WAAPI/Three.js/Anime.js]
    C --> D[window.__timelines]
    D --> E[@hyperframes/engine Puppeteer]
    E --> F[Headless Chrome seek per frame]
    F --> G[PNG frame buffer]
    G --> H[@hyperframes/producer FFmpeg encode]
    H --> I[audio mix]
    I --> J[output.mp4]
    K[@hyperframes/studio] -.preview / edit.-> A
    L[@hyperframes/player web component] -.embed.-> A
    M[@hyperframes/aws-lambda] -.distributed render.-> E

3.3 8 個套件的角色

3.4 一個最小 composition

 1<div id="stage" data-composition-id="launch" data-start="0" data-width="1920" data-height="1080">
 2  <video class="clip" data-start="0" data-duration="6" data-track-index="0"
 3         src="intro.mp4" muted playsinline></video>
 4
 5  <h1 id="title" class="clip" data-start="1" data-duration="4" data-track-index="1">
 6    Launch day
 7  </h1>
 8
 9  <audio data-start="0" data-duration="6" data-track-index="2"
10         data-volume="0.5" src="music.wav"></audio>
11
12  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
13  <script>
14    const tl = gsap.timeline({ paused: true });
15    tl.from("#title", { opacity: 0, y: 40, duration: 0.8 }, 1);
16    window.__timelines = window.__timelines || {};
17    window.__timelines.launch = tl;
18  </script>
19</div>

關鍵約定：

• data-composition-id 對應 window.__timelines.<id> 的 key
• data-start / data-duration / data-track-index 三個屬性決定 clip 在 timeline 上的位置
• { paused: true } 必要：HF engine 自己 seek，timeline 不能自動播

4. CLI 與工具腳本詳細用法

4.1 CLI 子命令

4.2 Monorepo 內的 helper script

4.3 開發指令對照表

1bun install                 # 安裝（不可用 pnpm！）
2bun run build               # build 全部 package
3bun run test                # 跑 vitest
4bun run lint                # oxlint + lint-skills
5bunx oxfmt --check <files>  # 格式檢查（pre-commit / CI 用）
6bun run studio              # 啟 Studio dev server
7bun run dev                 # = bun run studio

5. 應用場景

6. 資安掃描報告

工具：grep -rn -E "eval|exec|child_process|secret|api_key|sk-|access_key" 對 scripts/ + packages/cli/src + packages/engine/src 全掃。

6.1 結果總表

6.2 詳細說明

🟢 child_process 使用

scripts/set-version.ts:83-113 用 execSync 跑 git status / git commit / git tag — 全部是 hardcoded 命令，無 user input；只有 release maintainer 在本機跑。

packages/cli/src/telemetry/client.ts:147 用 spawn 起子 process 送 PostHog event — 命令固定，無 shell injection 面。

🟢 PostHog API key 硬編碼

packages/cli/src/telemetry/client.ts:9:

1const POSTHOG_API_KEY = "phc_zjjbX0PnWxERXrMHhkEJWj9A9BhGVLRReICgsfTMmpx";

phc_ 開頭是 PostHog public project key，設計上就是公開的，不是 secret。等同於 Google Analytics 的 GA-ID。

🟢 GEMINI_API_KEY 走環境變數

packages/cli/src/capture/contentExtractor.ts:169:

1const geminiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;

只有開「website capture + AI image caption」功能才會用到；不啟用此選項可完全不設。.env.example 已正確標註。

🟡 預設 telemetry 開啟

CLI 預設會送 PostHog event（events 包含命令使用情況、版本、平台）。介意的使用者可設 HYPERFRAMES_TELEMETRY_DISABLED=1 關閉（從 agent_runtime.ts 程式碼推測，請以 --help 為準）。

6.3 部署建議

7. FAQ

Q1. 為什麼 README 強調「不能用 pnpm install」？

A: 因為 hyperframes 用 bun 的 workspace resolution；裝 pnpm 會生 pnpm-lock.yaml 並引入符號連結拓樸不一致，導致 @hyperframes/* 跨 package 解析失敗。永遠用 bun。

Q2. composition 一定要寫 GSAP 嗎？

A: 不一定。@hyperframes/core 內建多個 adapter：CSS animation / WAAPI / Lottie / Three.js / Anime.js / GSAP / 自訂 frame adapter。挑你會的即可。但要記得 timeline 要 paused，由 engine seek。

Q3. 跟 Remotion 比，HF 渲染 deterministic 嗎？

A: 是的，而且 HF 把 deterministic 列為核心承諾。只要相同 composition + 相同 asset，每個 frame 由 seek(t) 觸發，不受 wall-clock 影響。

Q4. License 上有什麼差別？

A: Apache 2.0（HF）vs 「Free / Company」two-tier license（Remotion）。HF 在企業內可直接商用，無使用者 / 員工人數限制。

Q5. 可以本機渲染 4K 60fps 嗎？

A: 可以，但要算清楚 Puppeteer screenshot bottleneck (瓶頸)。@hyperframes/producer 支援 worker pool，建議 4K 用多 worker；極端情境用 @hyperframes/aws-lambda 分散到 Lambda。

Q6. Studio 可以用來給非工程師編輯嗎？

A: 可以，但目前定位是 evolving（仍在快速演進），複雜編輯仍偏 dev 取向。若要做 end-user video editor，建議搭配 @hyperframes/player 做嵌入式 timeline UI。

8. 進階技巧

8.1 用 frame adapter 接入自家 engine

1// my-adapter.ts
2import type { FrameAdapter } from "@hyperframes/core";
3export const myAdapter: FrameAdapter = {
4  id: "my-engine",
5  async seek(t: number) { /* update your scene to time t */ },
6  duration() { return 6 },
7};
8window.__hyperframes_adapters ??= {};
9window.__hyperframes_adapters.launch = myAdapter;

把 <script> 內的 GSAP timeline 換成自家 adapter，HF engine 會自動偵測。

8.2 Catalog 加速 prototype

1npx hyperframes add data-chart            # 動態 chart block
2npx hyperframes add instagram-follow      # 社群 overlay
3npx hyperframes add flash-through-white   # shader transition

Block 安裝後會落到 compositions/blocks/<name>/，可直接 <include> 進主 composition。

8.3 Lambda 分散式渲染

1# 1. 部署 Lambda 函數（用 @hyperframes/aws-lambda 內建 CLI）
2npx hyperframes-lambda deploy --region us-east-1 --memory 4096
3
4# 2. 從本機派送（會把 composition tar 打包後上 S3）
5npx hyperframes-lambda render --composition launch \
6  --composition-path ./index.html --out s3://bucket/out.mp4

8.4 在 Dockerfile 內固定 Chromium 版本

複用 repo 內 Dockerfile.test 的 pattern，把 FROM node:22-bookworm-slim 配上同版 FFmpeg，可確保 CI 跟生產渲染輸出 byte-identical。

9. 整合進其他工作流

10. 重點摘要 Checklist

• HF 把 composition 寫成 plain HTML，無 React、無 bundler。
• 安裝必用 bun，禁止 pnpm install。
• timeline 必須 { paused: true }，由 engine 控 seek。
• License 是 Apache 2.0，企業內商用無限制。
• CLI 預設 telemetry 開啟（phc_ 開頭是 public key、不是 secret）。
• 8 個 package：CLI / core / engine / producer / studio / player / shader-transitions / aws-lambda。
• 與 Remotion 競爭，定位 agent-first，README 內含正面比較。
• 仍在 0.x 階段（v0.6.56），API 可能變動。

11. 進一步閱讀

• 官方 Quickstart: https://hyperframes.heygen.com/quickstart
• HF vs Remotion guide: https://hyperframes.heygen.com/guides/hyperframes-vs-remotion
• AWS Lambda 部署: https://hyperframes.heygen.com/deploy/aws-lambda
• Catalog blocks: https://hyperframes.heygen.com/catalog/blocks/data-chart
• 社群 Discord: https://discord.gg/EbK98HBPdk
• SECURITY policy: https://github.com/heygen-com/hyperframes/blob/main/SECURITY.md
• ADOPTERS.md（生產環境使用者）
• DESIGN.md（HF 設計系統 + 配色 / 字型 / 佈局指南）