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 # 診斷環境問題
preview 是一個長效的 Next.js 伺服器,會保持 Chrome 渲染工作程序開啟。使用完畢後務必將其停止(請參閱清理)— 一個被遺忘的預覽行程會讓閒置的 chrome-headless-shell 工作程序繼續存在,在沒有 GPU 的主機(如 WSL、容器、CI)上,這些程式會透過軟體 WebGL(swiftshader)無限期地佔用一個 CPU 核心。
渲染標記:--quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker(可重現) · --strict。
完整的 CLI 參考:references/cli.md。
設定(一次性)
bash "$(dirname "$(find ~/.nastech/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。使用內邊距將內容向內推 — 永遠不要在內容容器上使用 position: absolute; top: Npx(當內容高於剩餘空間時會溢出)。
只有在關鍵影格看起來正確之後,再加入 gsap.from() 進場動畫(動畫到 CSS 位置)和 gsap.to() 出場動畫(從其位置動畫離開)。
完整的 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()或即時時鐘邏輯。如果需要偽隨機性,請使用種子偽隨機數產生器。 - 同步建立 — 在時間軸建構過程中,不能使用
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 → 分鏡 → 組合 → 渲染 → 交付。
清理
render 是一次性的(工作程序會在完成時退出)。preview 則否 — 它會執行一個背景 Next.js 伺服器,讓 Chrome 工作程序保持常駐,直到你停止它。絕對不要任其執行:在沒有 GPU 的主機上,每個閒置工作程序的 swiftshader 處理程序會佔用一個 CPU 核心,而一個打開數天的預覽會累積多個工作程序。
當使用者完成審查時(或在開始新的預覽之前),停止預覽:
pkill -f "hyperframes.*preview" # Studio 伺服器(釋放連接埠 3002)
pkill -f chrome-headless-shell # 其渲染工作程序;只在沒有其他工具使用時才安全
如果不確定其他工具是否使用了 chrome-headless-shell,請先檢查:pgrep -af chrome-headless-shell。以同樣方式恢復一個卡住的主機(許多閒置工作程序佔用 CPU)— 請參閱 references/troubleshooting.md。
常見陷阱
-
讓
preview保持執行 — 這是一個長效伺服器,會持有 Chrome 工作程序;在 WSL/容器/CI 環境中,這些閒置工作程序每個都會佔用一個 CPU 核心(軟體 WebGL)。使用完畢後將其停止 — 請參閱清理。 -
找不到
HeadlessExperimental.beginFrame— 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— 會破壞捕捉引擎。務必計算一個有限的 repeat 次數。 -
對稍後才出現的剪輯元素使用
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 中。 -
將獨立的
index.html包在<template>中 — 這會將所有內容對瀏覽器隱藏。只有透過data-composition-src載入的子組合才能使用<template>。 -
使用影片來處理音訊 — 務必使用靜音
<video>+ 獨立的<audio>。
驗證
在渲染前後:
- 檢查 + 驗證 + 審查通過:
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 <composition-dir> \ --out <composition-dir>/.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=noprint_wrappers=1:nokey=1 final.mp4。 - 渲染記錄在專案 README 中(交付品質)。