HyperFrames
HTML 是影片的真理來源。一個合成是一個帶有 data-* 屬性的 HTML 檔案,用於控制時間、一個 GSAP 時間軸用於動畫,以及 CSS 用於外觀。HyperFrames 引擎逐幀捕捉頁面,並使用 FFmpeg 編碼為 MP4/WebM。
與 manim-video 互補: 對於數學/幾何解說(方程式、3B1B 風格),請使用 manim-video。對於動態圖形、含字幕的談話頭、產品導覽、社交媒體疊層、著色器轉場,以及任何由真實影片/音訊媒體驅動的內容,請使用 hyperframes。
使用時機
- 使用者要求從文字、腳本或網站渲染影片
- 動態標題卡、下三分之一或文字排版介紹
- 含字幕的旁白影片(TTS + 與波形同步的字幕)
- 音訊反應視覺效果(節奏同步、頻譜條、脈動光暈)
- 場景間轉場(淡入淡出、擦拭、著色器扭曲、閃白)
- 社交媒體疊層(Instagram/TikTok/YouTube 風格)
- 網站轉影片流程(擷取 URL,產出宣傳片)
- 任何必須確定性地渲染成影片檔案的 HTML/CSS/JS 動畫
請勿使用此技能於:
- 純數學/方程式動畫(→
manim-video) - 圖片生成或迷因(→
meme-generation、圖片模型) - 即時視訊會議或串流
快速參考
npx hyperframes init my-video # 建立專案
cd my-video
npx hyperframes lint # 在預覽/渲染前驗證
npx hyperframes preview # 即時重新載入瀏覽器預覽(連接埠 3002)
npx hyperframes render --output final.mp4 # 渲染為 MP4
npx hyperframes doctor # 診斷環境問題
渲染標誌:--quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker(可重現) · --strict。
完整 CLI 參考:references/cli.md。
設定(一次性)
bash "$(dirname "$(find ~/.hermes/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"
此腳本會:
- 確認已安裝 Node.js >= 22 和 FFmpeg(若未安裝則列印修正指示)。
- 全域安裝
hyperframesCLI(npm install -g hyperframes@>=0.4.2)。 - 透過 Puppeteer 預先快取
chrome-headless-shell— 必備,以透過 Chrome 的HeadlessExperimental.beginFrame捕捉路徑達到最佳品質渲染。 - 執行
npx hyperframes doctor並報告結果。
若設定失敗,請參閱 references/troubleshooting.md。
步驟
1. 撰寫 HTML 前先規劃
在接觸程式碼之前,先在高層次上闡明:
- 什麼 — 敘事弧線、關鍵時刻、情感節奏
- 結構 — 合成、軌道(影片/音訊/疊層)、持續時間
- 視覺識別 — 顏色、字型、動畫特性(震撼/電影感/流暢/技術/混亂/溫暖)
- 英雄畫面 — 每個場景中,最多元素同時可見的時刻。這是你首先要建立的靜態版面。
視覺識別閘道(硬性閘道)。 在撰寫任何合成 HTML 之前,必須定義視覺識別。請勿使用預設或通用顏色(#333、#3b82f6、Roboto 表示跳過了此步驟)撰寫合成。依序檢查:
-
專案根目錄有
DESIGN.md? → 使用其中的精確顏色、字型、動畫規則和「禁止事項」限制。 -
使用者指定了風格(例如「Swiss Pulse」、「黑暗科技感」、「奢華品牌」)? → 產出一個包含
## Style Prompt、## Colors(3-5 個十六進位色碼及角色)、## Typography(1-2 個字型家族)、## What NOT to Do(3-5 個反模式)的簡潔DESIGN.md。 -
以上皆非? → 在撰寫任何 HTML 前詢問 3 個問題:
- 氛圍?(震撼 / 電影感 / 流暢 / 技術 / 混亂 / 溫暖)
- 淺色或深色畫布?
- 有任何品牌顏色、字型或視覺參考嗎?
然後根據答案產出
DESIGN.md。每個合成都必須將其調色盤和字型追溯回DESIGN.md或使用者的明確指示。
2. 建立專案
npx hyperframes init my-video --non-interactive
範本:blank、warm-grain、play-mode、swiss-grid、vignelli、decision-tree、kinetic-type、product-promo、nyt-graph。傳遞 --example <名稱> 選擇一個,或傳遞 --video clip.mp4 或 --audio track.mp3 來加入媒體。
3. 先排版再動畫
先撰寫英雄畫面的靜態 HTML+CSS — 尚未加入 GSAP。.scene-content 容器必須填滿場景(width:100%; height:100%; padding:Npx),並使用 display:flex + gap。使用內邊距將內容推向內側 — 絕對不要在內容容器上使用 position: absolute; top: Npx(當內容高於剩餘空間時會溢出)。
只有在英雄畫面看起來正確後,再加入 gsap.from() 進場(動畫到 CSS 位置)和 gsap.to() 出場(從該位置動畫離開)。
完整 data-attribute 架構和合成規則請參閱 references/composition.md。
4. 使用 GSAP 製作動畫
每個合成必須:
- 註冊其時間軸:
window.__timelines["<合成-id>"] = tl - 從暫停狀態開始:
gsap.timeline({ paused: true })— 播放器控制播放 - 使用有限的
repeat值(沒有repeat: -1— 會破壞捕捉引擎)。計算方式:repeat: Math.ceil(duration / cycleDuration) - 1。 - 為確定性的 — 沒有
Math.random()、Date.now()或時鐘邏輯。如果需要偽隨機性,請使用種子 PRNG。 - 同步建立 — 時間軸建構過程沒有
async/await、setTimeout或 Promise。
核心 GSAP API(補間、速率、間隔、時間軸)請參閱 references/gsap.md。
5. 場景間的轉場
多場景合成需要轉場。規則:
- 始終在場景之間使用轉場 — 沒有跳接。
- 始終對每個場景元素使用進場動畫(
gsap.from(...))。 - 永遠不要使用出場動畫(最後一個場景除外) — 轉場本身就是出場。
- 最後一個場景可以淡出。
使用 npx hyperframes add <轉場名稱> 安裝著色器轉場(flash-through-white、liquid-wipe 等)。完整列表:npx hyperframes add --list。
6. 音訊、字幕、TTS、音訊反應、標記高亮
- 音訊: 始終使用獨立的
<audio>元素(影片是muted playsinline)。 - TTS:
npx hyperframes tts "腳本文本" --voice af_nova --output narration.wav。使用--list列出可用語音。語音 ID 的首字母編碼語言(a/b=英文、e=西班牙文、f=法文、j=日文、z=中文等) — CLI 會自動推斷音素化區域設定;僅在需要覆蓋時傳遞--lang。非英文音素化需要系統級安裝espeak-ng。 - 字幕:
npx hyperframes transcribe narration.wav→ 字詞級轉錄。根據轉錄語氣選擇風格(炒作 / 企業 / 教學 / 說故事 / 社交 — 請參閱references/features.md中的表格)。語言規則: 除非確認音訊為英文,否則永遠不要使用.enWhisper 模型 —.en會將非英文音訊翻譯而非轉錄。每個字幕組在其出場補間之後必須有一個強制的tl.set(el, { opacity: 0, visibility: "hidden" }, group.end)殺除指令 — 否則組會將可見內容洩漏到後續組中。 - 音訊反應視覺: 在時間軸內使用
tl.call(draw, [], f / fps)的for迴圈預先提取音訊頻段(低音 / 中音 / 高音)並以逐幀取樣 — 單一長補間不會對音訊做出反應。將低音映射到scale(脈衝)、高音映射到textShadow/boxShadow(光暈)、整體振幅映射到opacity/y/backgroundColor。避免均衡器條的陳詞濫調 — 讓內容引導視覺,音訊驅動其行為。 - 標記式高亮: 文字強調的高亮、圓圈、爆發、塗鴉、素描效果是確定性的 CSS+GSAP — 請參閱
references/features.md#marker-highlighting。完全可搜尋,無需動畫 SVG 濾鏡。 - 場景轉場: 每個多場景合成必須使用轉場(沒有跳接)。從 CSS 原語(推滑、模糊淡入淡出、縮放穿過、交錯區塊)或著色器轉場(
flash-through-white、liquid-wipe、cross-warp-morph、chromatic-split等)中選擇,透過npx hyperframes add安裝。氛圍和能量表位於references/features.md#transitions。不要在相同合成中混合 CSS 和著色器轉場。
7. Lint、驗證、檢查、預覽、渲染
npx hyperframes lint # 捕捉遺失的 data-composition-id、重疊軌道、未註冊的時間軸
npx hyperframes validate # 在 5 個時間點進行 WCAG 對比度審計
npx hyperframes inspect # 視覺版面審計 — 溢出、畫布外元素、被遮蔽的文字
npx hyperframes preview # 即時瀏覽器預覽
npx hyperframes render --quality draft --output draft.mp4 # 快速迭代
npx hyperframes render --quality high --output final.mp4 # 最終交付
hyperframes validate 會取樣每個文字元素後方的背景像素,並在對比度低於 4.5:1(或大號文字低於 3:1)時發出警告。hyperframes inspect 是版面側的伴侶工具 — 它會在多個時間點執行頁面,並標記靜態 lint 無法看到的問題(只有在 4.5 秒時才會超出安全區域的字幕、當標題為最長變體時溢出的卡片、最終位於轉場著色器後方的元素)。特別是對於包含對話氣泡、卡片、字幕或緊湊排版的合成,請執行 inspect。
8. 網站轉影片(如果使用者提供 URL)
使用 references/website-to-video.md 中的 7 步驟擷取至影片工作流程:擷取 → DESIGN.md → SCRIPT.md → 分鏡 → 合成 → 渲染 → 交付。
陷阱
HeadlessExperimental.beginFrame' wasn't found— Chromium 147+ 移除了此協定。請確保使用hyperframes@>=0.4.2(會自動偵測並回退到螢幕截圖模式)。脫逃機制:export PRODUCER_FORCE_SCREENSHOT=true。請參閱 hyperframes#294 和 references/troubleshooting.md。- 系統 Chrome(非
chrome-headless-shell) — 渲染會掛起 120 秒然後超時。執行npx puppeteer browsers install chrome-headless-shell(setup.sh 會執行此操作)。hyperframes doctor會報告將使用哪個二進位檔。 - 任何地方的
repeat: -1— 會破壞捕捉引擎。始終計算有限的重複次數。 - 對稍後才進入的剪輯元素使用
gsap.set()— 該元素在頁面載入時不存在。請改為在時間軸內部、剪輯的data-start位置或之後使用tl.set(selector, vars, timePosition)。 - 內容文字內的
<br>— 強制換行不知道渲染的字型寬度,因此自然換行 +<br>會造成雙重換行。使用max-width讓文字自動換行。例外情況:短標題,其中每個字詞刻意獨立成行。 - 為
visibility或display加上動畫 — GSAP 無法補間這些屬性。請使用autoAlpha(同時處理 visibility 和 opacity)。 - 呼叫
video.play()或audio.play()— 框架負責播放。永遠不要自己呼叫這些。 - 非同步建立時間軸 — 捕捉引擎在頁面載入後同步讀取
window.__timelines。永遠不要將時間軸建構包裝在async、setTimeout或 Promise 中。 - 包在
<template>中的獨立index.html— 會對瀏覽器隱藏所有內容。只有透過data-composition-src載入的子合成才使用<template>。 - 使用影片作為音訊 — 始終使用靜音
<video>+ 獨立<audio>。
驗證
在渲染前後:
- Lint + validate + inspect 通過:
npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect(lint 捕捉結構問題,validate 捕捉對比度,inspect 捕捉視覺版面/溢出問題 — 如果出現警告,請參閱 troubleshooting.md)。 - 動畫編排 — 對於新的合成或重大動畫變更,請執行動畫地圖。
npx hyperframes init會將技能腳本複製到專案中,因此路徑是專案本地的:
輸出一個node skills/hyperframes/scripts/animation-map.mjs <合成目錄> \ --out <合成目錄>/.hyperframes/anim-mapanimation-map.json,包含每個補間的摘要、ASCII 甘特時間軸、間隔偵測、死區(>1 秒無動畫)、元素生命週期和標誌(offscreen、collision、invisible、paced-fast<0.2 秒、paced-slow>2 秒)。掃描摘要和標誌 — 修正或證明每個項目。小幅編輯時跳過。 - 檔案存在且非零:
ls -lh final.mp4。 - 持續時間符合
data-duration:ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4。 - 視覺檢查: 提取中間合成幀:
ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png。 - 音訊存在(若預期):
ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1。
如果 hyperframes render 失敗,請執行 npx hyperframes doctor 並在回報時附上其輸出。
參考資料
- composition.md — data 屬性、時間軸合約、強制規則、排版/資產規則
- cli.md — 每個 CLI 命令(init、capture、lint、validate、inspect、preview、render、transcribe、tts、doctor、browser、info、upgrade、benchmark)
- gsap.md — 適用於 HyperFrames 的 GSAP 核心 API(補間、速率、間隔、時間軸、matchMedia)
- features.md — 字幕、TTS、音訊反應、標記高亮、轉場(按需載入)
- website-to-video.md — 7 步驟擷取至影片工作流程
- troubleshooting.md — OpenClaw 修復、環境變數、常見渲染錯誤