ZardLi1115/zedclaw

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 ~/.zedclaw/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"

此腳本會：

1. 確認已安裝 Node.js >= 22 和 FFmpeg（若無則顯示修復說明）。
2. 全域安裝 hyperframes CLI（npm install -g hyperframes@>=0.4.2）。
3. 透過 Puppeteer 預先快取 chrome-headless-shell — 這對於透過 Chrome 的 HeadlessExperimental.beginFrame 捕捉路徑獲得最佳品質渲染是必要的。
4. 執行 npx hyperframes doctor 並報告結果。

若設定失敗，請參閱 references/troubleshooting.md。

程序

1. 在編寫 HTML 之前先規劃

在接觸程式碼之前，先在高層次上闡明：

• 什麼 — 敘事弧線、關鍵時刻、情感節奏
• 結構 — 合成作品、軌道（影片/音訊/覆蓋層）、持續時間
• 視覺識別 — 顏色、字型、動態特性（爆炸性 / 電影感 / 流暢 / 技術感）
• 主畫面 — 對於每個場景，最多元素同時可見的時刻。這是你將首先建立的靜態佈局。

視覺識別關卡（硬性關卡）。 在編寫任何合成 HTML 之前，必須先定義視覺識別。請勿使用預設或通用顏色（#333、#3b82f6、Roboto 表示跳過了此步驟）來編寫合成作品。依序檢查：

1. 專案根目錄是否有 DESIGN.md？ → 使用其中精確的顏色、字型、動態規則和「不該做的事」限制。
2. 使用者指定了風格（例如「瑞士脈動」、「暗黑科技風」、「奢華品牌」）？ → 生成一個包含 ## Style Prompt、## Colors（3-5 個十六進位色碼及其角色）、## Typography（1-2 個字型家族）、## What NOT to Do（3-5 個反模式）的最小化 DESIGN.md。
3. 以上皆非？ → 在編寫任何 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() 出場動畫（從 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() 或時鐘邏輯。如果需要偽隨機性，請使用種子亂數產生器。
• 同步建立 — 時間軸建構過程中不能使用 async/await、setTimeout 或 Promise。

核心 GSAP API（補間、緩動、交錯、時間軸）請參閱 references/gsap.md。

5. 場景之間的轉場

多場景合成作品需要轉場。規則：

1. 始終在場景之間使用轉場 — 不要有跳接。
2. 始終對每個場景元素使用進場動畫（gsap.from(...)）。
3. 永遠不要使用出場動畫，最後一個場景除外 — 轉場本身就是出場。
4. 最後一個場景可以淡出。

使用 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 → 單字級別的文字記錄。根據文字記錄的語調選擇風格（hype / corporate / tutorial / storytelling / social — 請參閱 references/features.md 中的表格）。語言規則： 除非確認音訊是英語，否則永遠不要使用 .en whisper 模型 — .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）

使用 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（同時處理可見度和透明度）。
• 呼叫 video.play() 或 audio.play() — 框架擁有播放控制權。永遠不要自己呼叫這些方法。
• 非同步建立時間軸 — 捕捉引擎在頁面載入後同步讀取 window.__timelines。永遠不要將時間軸建構包裝在 async、setTimeout 或 Promise 中。
• 將獨立的 index.html 包裹在 <template> 中 — 這會對瀏覽器隱藏所有內容。只有透過 data-composition-src 載入的子合成作品才能使用 <template>。
• 使用影片作為音訊 — 始終使用靜音 <video> + 獨立的 <audio>。

驗證

在渲染之前和之後：

1. 通過 lint + validate + inspect： npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect（lint 捕捉結構性問題，validate 捕捉對比度問題，inspect 捕捉視覺佈局/溢出問題 — 如果出現警告，請參閱 troubleshooting.md）。
2. 動畫編排 — 對於新的合成作品或重大的動畫變更，執行動畫地圖。npx hyperframes init 會將技能腳本複製到專案中，因此路徑是專案本機的：

   node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
     --out <composition-dir>/.hyperframes/anim-map
   

   輸出一個單一的 animation-map.json，包含每個補間的摘要、ASCII 甘特時間軸、交錯檢測、停滯區域（>1 秒無動畫）、元素生命週期，以及旗標（offscreen、collision、invisible、paced-fast <0.2 秒、paced-slow >2 秒）。掃描摘要和旗標 — 修正或證明每個問題的合理性。小幅編輯可跳過此步驟。
3. 檔案存在且非零： ls -lh final.mp4。
4. 持續時間符合 data-duration： ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4。
5. 視覺檢查： 提取一個合成作品中間的幀：ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png。
6. 如有預期則檢查音訊是否存在： 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 修復、環境變數、常見渲染錯誤