HyperFrames
HTML 是影片的真實來源。一個合成是一個帶有 data-* 時間屬性、GSAP 時間軸用於動畫、以及 CSS 用於外觀的 HTML 檔案。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 參考:參考文檔/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並報告結果。
若設定失敗,請參閱參考文檔/故障排除.md。
程序
1. 在撰寫 HTML 之前先規劃
在接觸程式碼之前,請先在高層次說明:
- 什麼 — 故事弧線、關鍵時刻、情感節奏
- 結構 — 合成、軌道(影片/音訊/疊加層)、持續時間
- 視覺識別 — 顏色、字體、動畫角色(爆炸性 / 電影感 / 流暢 / 技術性)
- 英雄幀 — 對於每個場景,同時有最多元素可見的時刻。這是您將首先建構的靜態佈局。
視覺識別關卡(嚴格關卡)。 在撰寫任何合成 HTML 之前,必須定義視覺識別。請勿使用預設或通用顏色(#333、#3b82f6、Roboto 表示此步驟被跳過)來撰寫合成。按順序檢查:
-
專案根目錄有
DESIGN.md? → 使用其中確切的顏色、字體、動畫規則和「什麼不要做」的限制。 -
使用者指定了風格(例如「瑞士脈動」、「暗黑科技風」、「奢華品牌」)? → 產生一個最簡的
DESIGN.md,包含## Style Prompt、## Colors(3-5 個十六進位碼及其角色)、## Typography(1-2 個字體家族)、## What NOT to Do(3-5 個反模式)。 -
以上皆非? → 在撰寫任何 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 <name> 來選擇一個,傳遞 --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() 退出動畫(從 CSS 位置動畫離開)。
請參閱參考文檔/合成.md以了解完整的 data-attribute 架構和合成規則。
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.md以了解核心 GSAP API(補間、緩動、錯開、時間軸)。
5. 場景間的轉場
多場景合成需要轉場。規則:
- 始終在場景之間使用轉場 — 沒有跳剪。
- 始終對每個場景元素使用進入動畫 (
gsap.from(...))。 - 永遠不要使用退出動畫,除非是最終場景 — 轉場本身就是退出。
- 最終場景可以淡出。
使用 npx hyperframes add <transition-name> 來安裝著色器轉場(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. 規格檢查、驗證、檢查、預覽、渲染
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 是佈局端的伴侶 — 它會在多個時間點執行頁面,並標記靜態規格檢查無法看到的問題(一個字幕在 4.5 秒時才超出安全區域、一個卡片在其標題是最長變體時溢出、一個元素最終位於轉場著色器後面)。特別是在包含對話氣泡、卡片、字幕或緊湊排版的合成上執行 inspect。
8. 網站到影片(如果使用者提供 URL)
使用參考文檔/網站到影片.md中的 7 步驟擷取到影片工作流程:擷取 → DESIGN.md → SCRIPT.md → 分鏡圖 → 合成 → 渲染 → 交付。
陷阱
'HeadlessExperimental.beginFrame' wasn't found— Chromium 147+ 移除了此協定。確保您使用的是hyperframes@>=0.4.2(會自動偵測並回退到螢幕截圖模式)。逃生艙:export PRODUCER_FORCE_SCREENSHOT=true。請參閱 hyperframes#294 和參考文檔/故障排除.md。- 系統 Chrome(不是
chrome-headless-shell) — 渲染會掛起 120 秒然後超時。執行npx puppeteer browsers install chrome-headless-shell(setup.sh 會執行此操作)。hyperframes doctor會報告將使用哪個二進位檔案。 - 任何地方的
repeat: -1— 會破壞擷取引擎。始終計算一個有限的循環次數。 - 在稍後進入的剪輯元素上使用
gsap.set()— 該元素在頁面載入時不存在。請在時間軸內部使用tl.set(selector, vars, timePosition),在剪輯的data-start時間點或之後使用。 - 內容文字內部的
<br>— 強制換行不知道渲染的字體寬度,因此自然換行 +<br>會雙重換行。使用max-width讓文字自動換行。例外情況:簡短的顯示標題,其中每個字刻意位於自己的行上。 - 對
visibility或display進行動畫 — GSAP 無法對這些進行補間。請使用autoAlpha(同時處理可見性和不透明度)。 - 呼叫
video.play()或audio.play()— 框架擁有播放控制權。永遠不要自行呼叫這些。 - 非同步建構時間軸 — 擷取引擎會在頁面載入後同步讀取
window.__timelines。永遠不要在時間軸建構中包裹async、setTimeout或 Promise。 - 獨立的
index.html包裹在<template>中 — 會對瀏覽器隱藏所有內容。只有透過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.2s、paced-slow>2s)。掃描摘要和標記 — 修復或證明每個。對小編輯跳過此步驟。 - 檔案存在且非零:
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 修復、環境變數、常見渲染錯誤