HyperFrames 是 HeyGen 開源的影片渲染框架。你用 HTML、CSS 與 data 屬性描述一支影片的時間軸,框架在無頭 Chrome 中逐格擷取畫面,再交給 FFmpeg 編碼成 MP4。相同輸入永遠產生相同輸出,且 composition 是純 HTML,任何 LLM 都能直接生成。這份手冊涵蓋環境需求、兩種安裝路徑、套件總覽、動畫適配器與完整渲染流程。
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 而言,「產生一支影片」與「產生一個網頁」是同一類任務。
環境需求只有兩項:Node.js 22 以上與 FFmpeg。FFmpeg 負責最後的影格編碼,需先安裝於系統(macOS 可用 brew install ffmpeg)。確認後,依你是否使用 AI coding agent 選一條路徑。
若你用 Claude Code、Cursor 等支援 skills 的 agent,一行指令即可把 HyperFrames 的 skill 加進去。agent 之後就能直接讀 HTML、產生 composition、呼叫渲染。
不接 agent 也能直接用 CLI。init 建立專案、preview 在瀏覽器即時預覽(支援 live reload)、render 輸出 MP4。
npx hyperframes render --output demo.mp4 直接指定輸出檔名,無需任何互動式提示,因此可被腳本或 agent 完整自動化。
HyperFrames 以 monorepo 切成數個套件,各司一段管線。日常只需要 hyperframes CLI;其餘套件在你需要程式化整合、自訂引擎或分散式渲染時才會直接接觸。下方是官方文件列出的核心套件。
影片時間軸不寫在 JSON,而是直接標在 HTML 元素上。下表是官方文件列出的核心 data 屬性,逐格渲染時由 runtime 讀取。
| data 屬性 | 作用 |
|---|---|
data-composition-id |
標記 composition 根節點,定義一支影片的範圍。 |
data-width / data-height |
畫布尺寸,例如 1920 × 1080。 |
data-start |
元素進場時間(秒)。 |
data-duration |
元素持續長度(秒)。 |
data-track-index |
圖層順序,決定元素的疊放層級。 |
data-volume |
音量控制,套用於音訊或含聲影片元素。 |
逐格渲染的前提是動畫必須可被精準定位到任意時間點。HyperFrames 用 Frame Adapter 模式,把這層抽象成適配器,任何「可 seek 的 runtime」都能接上。官方文件列出六種已支援的動畫來源。
| 適配器 | 典型用途 |
|---|---|
GSAP |
時間軸動畫、緩動與複雜編排。 |
CSS |
transition 與 keyframe,純樣式驅動的動態。 |
WAAPI |
Web Animations API,瀏覽器原生時間軸控制。 |
Anime.js |
輕量 JavaScript 動畫程式庫。 |
Lottie |
After Effects 匯出的向量動畫。 |
Three.js |
WebGL 3D 場景與相機動畫。 |
以下實作要點均出自官方文件,聚焦在新手最容易踩到的時間軸與確定性細節。
data-start 與 data-duration 的單位是秒,實際影格由 frame = floor(time × fps) 換算。先想清楚 fps,再排時間軸,避免進場點落在非整數影格上。
元素疊放不靠 CSS z-index,而是 data-track-index。把背景影片、字卡、音訊分配到不同 track,渲染時的合成順序才會穩定可預期。
背景音樂與含聲影片的音量用 data-volume 控制,而非依賴媒體檔本身的響度。多個音軌混音時逐一設定,避免單軌蓋過旁白。
npx hyperframes preview 在瀏覽器開即時預覽並支援 live reload,改 HTML 即時可見。確認時間軸無誤後再跑 render,省下整段逐格擷取的等待。
npx hyperframes add <component> 會把目錄中的現成片段裝進專案,例如 flash-through-white 這類轉場。從積木起步比從零寫動畫快。
相同輸入永遠產生相同輸出。這代表 composition 的 HTML 可進 Git、可在 CI 重現渲染,review 影片變更時比對的是文字 diff,而非二進位檔。
來源 · 官方文件 · 核心概念以下示範一支六秒的產品開場:一段背景影片、一行標題字卡、一軌配樂。先用 CLI 建立專案,檢視它生成的 HTML composition,改幾個 data 屬性,預覽後渲染。整段流程不需要任何專有時間軸格式,所有時序都標在 HTML 上。
從 init 到 demo.mp4,沒有任何專有時間軸檔。所有時序都是 HTML 元素上的 data-start 與 data-duration,圖層是 data-track-index。預覽階段改的是同一份 HTML,渲染階段讀的也是同一份,兩者不會分歧。
因為渲染確定性,這份 composition.html 可直接進 Git。team review 影片改動時看的是文字 diff,CI 也能重跑出位元相同的輸出。對 AI agent 而言,產生與修改影片,和產生與修改網頁是同一種操作。
render 會失敗;macOS 可用 brew install ffmpeg 先補上。
@hyperframes/aws-lambda 分散式渲染。
data-start、data-duration 是秒,實際影格經 floor(time × fps) 取整。排時間軸時先確定 fps,避免關鍵畫面落在預期外的影格。
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)。