Kingly-Agency/deadzone

HyperFrames

HTML 是影片的唯一真實來源。一個合成就是一個 HTML 檔案，包含用於時間設定的 data-* 屬性、用於動畫的 GSAP 時間軸，以及用於外觀的 CSS。HyperFrames 引擎會逐幀擷取頁面，並使用 FFmpeg 編碼為 MP4/WebM。

與 manim-video 互補： 使用 manim-video 處理數學/幾何解說（方程式、3B1B 風格）。使用 hyperframes 處理動態圖形、附字幕的談話頭、產品導覽、社交媒體覆疊、著色器轉場，以及任何由真實影片/音訊媒體驅動的內容。

使用時機

• 使用者要求從文字、腳本或網站渲染一段影片
• 動態標題卡、下方三分之一處標題或字體排版介紹
• 附字幕的旁白影片（TTS + 與波形同步的字幕）
• 音訊反應視覺效果（節拍同步、頻譜條、脈動發光）
• 場景間轉場（淡入淡出、擦拭、著色器扭曲、閃白）
• 社交媒體覆疊（Instagram/TikTok/YouTube 風格）
• 網站轉影片流程（擷取 URL，產出宣傳影片）
• 任何必須確定性渲染為影片檔案的 HTML/CSS/JS 動畫

不要將此技能用於：

• 純數學/方程式動畫（→ manim-video）
• 圖片生成或迷因（→ meme-generation、圖片模型）
• 即時視訊會議或串流

快速參考

npx hyperframes init my-video               # 建立專案 scaffold
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"

此腳本會：

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. 使用者指定了風格（例如「Swiss Pulse」、「暗色科技風」、「奢華品牌」）？ → 生成一個簡潔的 DESIGN.md，包含 ## 風格提示、## 顏色（3-5 個十六進位色碼及角色）、## 字體排版（1-2 個字體家族）、## 禁止事項（3-5 個反模式）。

3. 以上皆非？ → 在撰寫任何 HTML 前先問 3 個問題：

   • 氛圍？（爆炸性 / 電影感 / 流暢 / 技術感 / 混亂 / 溫暖）
   • 淺色或深色畫布？
   • 有任何品牌顏色、字體或視覺參考嗎？

   然後根據答案生成 DESIGN.md。每個合成都必須將其調色盤和字體排版追溯回 DESIGN.md 或明確的使用者指示。

2. 建立 Scaffold

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() 出場動畫（從其位置移動）。

請參閱 references/composition.md 了解完整的 data-attribute 結構和合成規則。

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。

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

5. 場景間轉場

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

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

使用 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 → 逐字稿。根據轉錄稿的語氣選擇風格（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. 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' — 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 中。
• 獨立的 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
   

   輸出一個包含每次補間摘要、ASCII 甘特圖時間軸、錯開偵測、空窗期（>1 秒無動畫）、元素生命週期和標誌（offscreen、collision、invisible、paced-fast <0.2 秒、paced-slow >2 秒）的單一 animation-map.json 檔案。掃描摘要和標誌 — 修復或證明每個問題。小幅編輯時可跳過。
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 修復、環境變數、常見渲染錯誤