HyperFrames
HTML 是影片的真實來源。一個合成是一個 HTML 檔案,使用 data-* 屬性控制時間、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 ~/.agent/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? → 使用其中精確的色彩、字型、動態規則和「禁止事項」限制。 -
使用者指定了風格(例如「瑞士脈動」、「暗黑科技風」、「奢華品牌」)? → 生成一份精簡的
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。使用 padding 將內容往內推 — 永遠不要對內容容器使用 position: absolute; top: Npx(當內容高於剩餘空間時會溢出)。
只有在關鍵幀看起來正確後,再加入 gsap.from() 入場動畫(動畫到 CSS 位置)和 gsap.to() 出場動畫(從 CSS 位置動畫離開)。
完整 data-attribute 模式和合成規則請參閱 references/composition.md。
4. 使用 GSAP 進行動畫
每個合成必須:
- 註冊其時間軸:
window.__timelines["<composition-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 <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)終止 — 否則群組會以可見狀態洩漏到後面的群組。 - 音訊反應視覺效果: 預先提取音訊頻段(低頻 / 中頻 / 高頻),並在時間軸內使用
for迴圈的tl.call(draw, [], f / fps)逐幀取樣 — 單一長補間不會對音訊產生反應。將低頻映射到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)
使用 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()— 元素在頁面載入時不存在。改為在時間軸內使用tl.set(selector, vars, timePosition),並設定在或晚於片段的data-start。 - 內容文字中使用
<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>。
驗證
渲染前後:
- 語法檢查 + 驗證 + 檢查通過:
npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect(語法檢查捕捉結構問題,驗證捕捉對比度,檢查捕捉視覺佈局/溢出問題 — 若出現警告請參閱 troubleshooting.md)。 - 動畫編排 — 對於新的合成或重大動畫變更,執行動畫地圖。
npx hyperframes init會將技能腳本複製到專案中,因此路徑是專案本機的:
會輸出單一node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \ --out <composition-dir>/.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 修復、環境變數、常見渲染錯誤