HyperFrames 是做什麼的?
總覽
HyperFrames 是 HeyGen 開源(Apache-2.0)的框架,能將 HTML、CSS、媒體與動畫轉換為確定性的 MP4 影片——相同輸入必定產生相同輸出。它會解析帶有 data-* 時間屬性的 HTML 組合,驅動無頭 Chrome 逐幀搜尋並擷取畫面,最後透過 FFmpeg 編碼為影片。無需建置步驟、不強制使用 React,也無需為每次渲染付費。它專為代理友善而設計:CLI 預設為非互動模式,因此能順暢嵌入自動化內容管線。
使用此技能來建立專案骨架、撰寫 HTML 組合、透過即時重新載入預覽,以及渲染幀精準的影片——包括由 GSAP、CSS、Lottie、Three.js、Anime.js 或 Web Animations API 驅動的動畫。
使用說明
前置需求
開始前請確認環境:
- Node.js 22+(
node --version) - FFmpeg 已加入 PATH(
ffmpeg --version) - 無頭 Chrome/Chromium 會在首次執行時由引擎自動下載。
建立專案
npx hyperframes init my-video # 建立專案(產生 index.html + package.json)
cd my-video
若要在既有的 AI 代理工作區中進行代理管理的設定,可使用 npx skills add heygen-com/hyperframes 安裝此技能。
撰寫組合
組合是純粹的 index.html 檔案。根階段元素宣告畫布與組合 ID;子元素透過 data-* 屬性宣告它們出現的時機與持續時間。時間單位為秒。
| 屬性 | 用途 |
|---|---|
data-composition-id | 命名組合(作為 render/inspect 的目標) |
data-start | 元素進入時間軸的時間(秒) |
data-duration | 元素停留在時間軸上的持續時間(秒) |
data-width / data-height | 畫布尺寸(像素,位於階段元素上) |
data-track-index | 音訊或影片堆疊的圖層/軌道順序 |
data-volume | 音量,0.0–1.0 |
預覽與渲染
npx hyperframes preview # 在瀏覽器中預覽,撰寫時可即時重新載入
npx hyperframes render # 在無頭 Chrome 中逐幀搜尋,透過 FFmpeg 編碼為 MP4
npx hyperframes lint # 在渲染前驗證組合結構
npx hyperframes inspect # 印出組合中繼資料(持續時間、軌道、尺寸)
解析度來自階段元素的 data-width/data-height;幀率、輸出路徑與編碼器為渲染參數(請執行 npx hyperframes render --help 查閱您安裝版本的正確旗標,因為旗標名稱會隨版本演進)。由於輸出具有確定性,重新渲染未變更的輸入可安全地使用快取。
使用元件目錄
預先建置的區塊(轉場、疊加層、字幕、動畫圖表、地圖、特效)可安裝至專案中:
npx hyperframes add flash-through-white # 一個轉場
npx hyperframes add data-chart # 一個動畫圖表區塊
npx hyperframes add instagram-follow # 一個社交疊加層
在 hyperframes.heygen.com/catalog 瀏覽完整目錄,然後透過 add 指令依名稱加入區塊。
動畫
任何可搜尋、幀精準的動畫都能運作,因為引擎會確定性地搜尋每個時間軸位置,而非即時錄製。支援的轉接器:GSAP、CSS 動畫、Lottie、Three.js、Anime.js、WAAPI 以及自訂幀轉接器。請避免依賴時間的隨機性或 Date.now()/時鐘驅動的運動——將動畫進度繫結至組合時間軸,這樣搜尋結果才能重現。
代理/CI 管線
CLI 為非互動模式,因此典型的自動化流程為:產生/模板化 HTML → hyperframes lint → hyperframes render → 收集 MP4。對於大規模渲染,@hyperframes/aws-lambda 套件可啟用分散式 Lambda 渲染。
範例
範例 1:渲染產品發表組合
index.html:
<div id="stage" data-composition-id="launch"
data-start="0" data-width="1920" data-height="1080">
<video data-start="0" data-duration="6" src="intro.mp4"></video>
<h1 id="title" data-start="1" data-duration="4">Launch day</h1>
<audio data-start="0" data-duration="6" data-volume="0.8" src="music.wav"></audio>
</div>
npx hyperframes inspect # 確認:launch,6 秒,1920x1080
npx hyperframes lint # 在花費渲染時間前進行驗證
npx hyperframes render # 產生 1080p MP4
範例 2:可搜尋的 GSAP 標題動畫
<div id="stage" data-composition-id="title-card"
data-start="0" data-width="1080" data-height="1080">
<h1 id="headline" data-start="0" data-duration="3">Q3 Results</h1>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
// 將進度繫結至時間軸(引擎搜尋時暫停 tween),而非即時時間。
const tl = gsap.timeline({ paused: true });
tl.from("#headline", { y: 80, opacity: 0, duration: 1 })
.to("#headline", { scale: 1.05, duration: 2 });
window.__seek = (t) => tl.seek(t); // 引擎逐幀呼叫
</script>
</div>
npx hyperframes preview # 即時迭代,然後:
npx hyperframes render
指引
- 確定性優先。 將所有運動繫結至組合時間軸。避免在渲染期間使用
Math.random()、Date.now()、即時迴圈或網路呼叫——它們會破壞可重現性。 - 先 lint 再渲染。
hyperframes lint能以低成本發現結構/時間錯誤;渲染才是昂貴的步驟。 - 在階段元素上設定畫布。
data-width/data-height位於根組合元素;子元素的時間設定(data-start/data-duration)位於各個元素上,單位為秒。 - 驗證工具鏈。 大多數失敗可追溯至缺少 FFmpeg 或 Node < 22,或是防火牆阻止 Chromium 下載。
- 使用
--help查閱正確旗標。render/add選項會因版本而異;請依據安裝的 CLI 確認 fps/輸出/編碼器旗標,而非直接假設。 - 優先使用目錄區塊。
hyperframes add會拉取已維護、可搜尋的元件,避免自行編寫轉場與圖表。 - 透過 Lambda 擴展。 對於批次/大型任務,使用
@hyperframes/aws-lambda進行渲染,而非執行長時間的本地作業。 - 將媒體素材放在本地並納入版本控制。 使用穩定路徑引用素材;渲染期間的遠端擷取會破壞確定性與可重現性。