使用手冊

第 02 期 · 開源工具 / AI Agent 影片渲染

用 HTML 定義影片, 逐格渲染成 MP4。

HeyGen 開源的 HyperFrames 實戰手冊。用 HTML 與 data 屬性定義影片時間軸,經無頭 Chrome 逐格擷取與 FFmpeg 編碼產生確定性 MP4。涵蓋環境需求、安裝、套件總覽、動畫適配器與完整渲染流程。

HyperFrames 是 HeyGen 開源的影片渲染框架。你用 HTML、CSS 與 data 屬性描述一支影片的時間軸,框架在無頭 Chrome 中逐格擷取畫面,再交給 FFmpeg 編碼成 MP4。相同輸入永遠產生相同輸出,且 composition 是純 HTML,任何 LLM 都能直接生成。這份手冊涵蓋環境需求、兩種安裝路徑、套件總覽、動畫適配器與完整渲染流程。

heygen-com/hyperframes
星標
—
分支
—
授權
—
資料截至
—
閱讀時間
8 分
更新日期
開啟原始報告
GitHub Stars
24.2k
動畫適配器
6
執行環境需求
Node 22+
開源授權
Apache 2.0
本頁章節

01這到底是什麼

把一支影片, 當成一個網頁來定義。

HyperFrames 是 HeyGen 開源的影片渲染框架,授權為 Apache 2.0。核心主張只有一句:用建構網頁的方式來定義影片。你寫一份 HTML 文件,每個元素用 data 屬性標註時間與圖層,框架把它逐格擷取、編碼成 MP4。它不是影片編輯器,也不是雲端 SaaS,而是一條可在本機執行、也可部署為渲染後端的管線。

運作機制是確定性的。每一格的時間由 frame = floor(time × fps) 計算,框架透過 Chrome 的 beginFrame API 把頁面 seek 到該時間點、擷取畫面,再交給 FFmpeg 編碼。相同輸入永遠產生相同輸出,不依賴即時播放速度,因此渲染結果可重現、可進版本控制。

設計目標明確指向 AI agent。composition 是純 HTML,任何 LLM 都能生成,不需要學專有格式;CLI 預設非互動,所有輸入透過旗標傳入、輸出為純文字、遇錯即停。對 coding agent 而言,「產生一支影片」與「產生一個網頁」是同一類任務。

  1. HTML composition

  2. headless Chrome

  3. 逐格 seek & capture

  4. FFmpeg encode

  5. MP4

Write HTML. Render video. Built for agents.

— HyperFrames 專案標語 · github.com/heygen-com/hyperframes

02環境需求與安裝

兩條安裝路徑: 交給 agent,或自己跑 CLI。

環境需求只有兩項:Node.js 22 以上與 FFmpeg。FFmpeg 負責最後的影格編碼,需先安裝於系統(macOS 可用 brew install ffmpeg)。確認後,依你是否使用 AI coding agent 選一條路徑。

路徑 A:讓 AI coding agent 接管

若你用 Claude Code、Cursor 等支援 skills 的 agent,一行指令即可把 HyperFrames 的 skill 加進去。agent 之後就能直接讀 HTML、產生 composition、呼叫渲染。

bash
# 把 HyperFrames skill 加進你的 coding agent
npx skills add heygen-com/hyperframes

路徑 B:手動使用 CLI

不接 agent 也能直接用 CLI。init 建立專案、preview 在瀏覽器即時預覽(支援 live reload)、render 輸出 MP4。

bash
npx hyperframes init my-video
cd my-video
npx hyperframes preview      # 瀏覽器即時預覽 · live reload
npx hyperframes render       # 渲染為 MP4

03套件總覽 · Monorepo

六個套件, 一條渲染管線。

HyperFrames 以 monorepo 切成數個套件,各司一段管線。日常只需要 hyperframes CLI;其餘套件在你需要程式化整合、自訂引擎或分散式渲染時才會直接接觸。下方是官方文件列出的核心套件。

CLI · 01

hyperframes

命令列工具

入口套件。提供 init、preview、render、add 等指令,預設非互動、可被 agent 完整驅動。

Core · 02

@hyperframes/core

型別 · 解析 · runtime

型別定義、HTML 解析、執行期 runtime 與 linter。所有上層套件的共同基礎。

Engine · 03

@hyperframes/engine

擷取引擎

page-to-video 擷取引擎。負責在無頭 Chrome 中逐格 seek 與 capture。

Producer · 04

@hyperframes/producer

渲染管線

完整渲染管線。串接擷取與 FFmpeg 編碼,輸出最終 MP4。

Studio · 05

@hyperframes/studio

視覺編輯器

瀏覽器內的視覺化 composition 編輯器,可調整時間軸與圖層。

Lambda · 06

@hyperframes/aws-lambda

分散式渲染

在 AWS Lambda 上做分散式渲染,把長影片切片平行擷取後合併。

composition 的 data 屬性

影片時間軸不寫在 JSON,而是直接標在 HTML 元素上。下表是官方文件列出的核心 data 屬性,逐格渲染時由 runtime 讀取。

data 屬性作用
data-composition-id標記 composition 根節點,定義一支影片的範圍。
data-width / data-height畫布尺寸,例如 1920 × 1080。
data-start元素進場時間(秒)。
data-duration元素持續長度(秒)。
data-track-index圖層順序,決定元素的疊放層級。
data-volume音量控制,套用於音訊或含聲影片元素。

04動畫適配器 · 實作要點

任何可 seek 的動畫,都能入鏡。

逐格渲染的前提是動畫必須可被精準定位到任意時間點。HyperFrames 用 Frame Adapter 模式,把這層抽象成適配器,任何「可 seek 的 runtime」都能接上。官方文件列出六種已支援的動畫來源。

適配器典型用途
GSAP時間軸動畫、緩動與複雜編排。
CSStransition 與 keyframe,純樣式驅動的動態。
WAAPIWeb Animations API,瀏覽器原生時間軸控制。
Anime.js輕量 JavaScript 動畫程式庫。
LottieAfter Effects 匯出的向量動畫。
Three.jsWebGL 3D 場景與相機動畫。

以下實作要點均出自官方文件,聚焦在新手最容易踩到的時間軸與確定性細節。

要點 01 · 時間以秒計,影格由 fps 推導

data-start 與 data-duration 的單位是秒,實際影格由 frame = floor(time × fps) 換算。先想清楚 fps,再排時間軸,避免進場點落在非整數影格上。

來源 · 官方文件 · 渲染管線

要點 02 · 圖層順序用 data-track-index

元素疊放不靠 CSS z-index,而是 data-track-index。把背景影片、字卡、音訊分配到不同 track,渲染時的合成順序才會穩定可預期。

來源 · 官方文件 · 資料屬性

要點 03 · 音量交給 data-volume

背景音樂與含聲影片的音量用 data-volume 控制,而非依賴媒體檔本身的響度。多個音軌混音時逐一設定,避免單軌蓋過旁白。

來源 · 官方文件 · 資料屬性

要點 04 · 先 preview 再 render

npx hyperframes preview 在瀏覽器開即時預覽並支援 live reload,改 HTML 即時可見。確認時間軸無誤後再跑 render,省下整段逐格擷取的等待。

來源 · 官方文件 · CLI

要點 05 · 用 add 套用目錄積木

npx hyperframes add <component> 會把目錄中的現成片段裝進專案,例如 flash-through-white 這類轉場。從積木起步比從零寫動畫快。

來源 · 官方文件 · CLI

要點 06 · 確定性讓輸出可進版控

相同輸入永遠產生相同輸出。這代表 composition 的 HTML 可進 Git、可在 CI 重現渲染,review 影片變更時比對的是文字 diff,而非二進位檔。

來源 · 官方文件 · 核心概念

05完整渲染流程

從 init 到 MP4, 一支六秒開場片。

以下示範一支六秒的產品開場:一段背景影片、一行標題字卡、一軌配樂。先用 CLI 建立專案,檢視它生成的 HTML composition,改幾個 data 屬性,預覽後渲染。整段流程不需要任何專有時間軸格式,所有時序都標在 HTML 上。

bash
<!-- 每個元素用 data 屬性標時間與圖層 -->
<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"
         src="intro.mp4" muted playsinline></video>
  <h1 id="title" data-start="1" data-duration="4">Launch day</h1>
  <audio data-start="0" data-duration="6" src="music.wav"></audio>
</div>
~/projects/launch-intro · hyperframes cli


# 1 · 建立專案,CLI 產生範本 composition
$ npx hyperframes init launch-intro


ok: ✓ created launch-intro/
    # composition.html   assets/   hyperframes.config.*
$ cd launch-intro


# 2 · 編輯 composition.html,排好三條 track
  data-composition-id="launch"  ·  1920×1080
    track 0  video  intro.mp4   start 0  duration 6
    track 1  h1     Launch day  start 1  duration 4
    track 2  audio  music.wav   start 0  duration 6


# 3 · 本機即時預覽,確認時間軸
$ npx hyperframes preview


ok: ▶ preview server · http://localhost:5173
    # watching composition.html · live reload on
  把標題 data-start 從 1 改成 0.5,瀏覽器立即重繪。


# 4 · 從目錄加一個轉場積木
$ npx hyperframes add flash-through-white


ok: ✓ added component · flash-through-white
    # inserted into composition.html · track 3


# 5 · 逐格擷取並編碼成 MP4
$ npx hyperframes render --output demo.mp4


# [launch headless chrome · load composition "launch"]
# [fps 30 · 6.0s · 180 frames · frame = floor(time × fps)]
# [seek + capture via beginFrame ............. 180/180]
# [encode with ffmpeg · H.264 · 1920×1080 ......... done]


ok: ✓ wrote demo.mp4 · 6.0s · 1920×1080 · 30fps
hl: 相同的 composition.html 再跑一次,輸出逐格相同。

時間軸標在 HTML 上,輸出由 fps 決定。 同一份 composition,渲染幾次都一樣。

— 確定性渲染,讓影片成為可進版控的純文字資產

這段流程的關鍵

從 init 到 demo.mp4,沒有任何專有時間軸檔。所有時序都是 HTML 元素上的 data-start 與 data-duration,圖層是 data-track-index。預覽階段改的是同一份 HTML,渲染階段讀的也是同一份,兩者不會分歧。

因為渲染確定性,這份 composition.html 可直接進 Git。team review 影片改動時看的是文字 diff,CI 也能重跑出位元相同的輸出。對 AI agent 而言,產生與修改影片,和產生與修改網頁是同一種操作。

06先看清楚這些

上手前, 先確認邊界。

07進階路徑

把 HyperFrames 接進你的管線。

CLI 只是入口。當你要程式化生成影片、自訂擷取引擎或規模化渲染時,直接使用對應套件。以下是幾條官方文件支持的延伸方向。

延伸方向

1. 用 Studio 視覺化編輯。@hyperframes/studio 提供瀏覽器內的 composition 編輯器,讓你以視覺方式調整時間軸與圖層,再匯回 HTML。

**2. 程式化串接管線。**需要在後端按需產生影片時,直接使用 @hyperframes/producer 的渲染管線與 @hyperframes/engine 的擷取引擎,把 HyperFrames 當成渲染後端。

3. 上 AWS Lambda 做分散式渲染。@hyperframes/aws-lambda 把長影片切片、平行擷取再合併,縮短整體渲染時間,適合量大或即時的場景。

**4. 從目錄積木起步。**用 npx hyperframes add <component> 套用現成片段(如 flash-through-white 轉場),再以 data 屬性微調,比從零寫動畫快。

**5. 交給 coding agent。**用 npx skills add heygen-com/hyperframes 把 skill 裝進 Claude Code 或 Cursor。composition 是純 HTML,agent 可直接生成與修改,再呼叫 render 輸出。

延伸閱讀

① hyperframes.heygen.com/introduction:官方文件,核心概念、資料屬性與 CLI 完整說明。 ② github.com/heygen-com/hyperframes:原始碼、套件結構與授權(Apache 2.0)。

Write HTML. Render video. Built for agents.

— HyperFrames · heygen-com/hyperframes