跳到主要內容

Hyperframes

使用 HyperFrames 創建基於 HTML 的視頻合成、動畫標題卡、社交疊加層、帶字幕的真人出鏡視頻、音頻反應視覺效果以及著色器過渡效果。HTML 是視頻的真實來源（source of truth）。當用戶希望從 HTML 合成中渲染出 MP4/WebM 視頻、希望在媒體上動畫化文本/Logo/圖表、需要同步音頻的字幕、需要 TTS 旁白，或希望將網站轉換為視頻時，請使用此技能。

技能元數據​

來源可選 — 使用 hermes skills install official/creative/hyperframes 安裝
路徑optional-skills/creative/hyperframes
版本1.0.0
作者heygen-com
許可證Apache-2.0
平臺linux, macos, windows
標籤creative, video, animation, html, gsap, motion-graphics
相關技能manim-video, meme-generation

參考：完整 SKILL.md​

信息

以下是 Hermes 在觸發此技能時加載的完整技能定義。這是技能激活時代理所看到的指令。

HyperFrames

HTML 是視頻的真實來源。合成是一個 HTML 文件，其中包含用於定時的 data-* 屬性、用於動畫的 GSAP 時間軸以及用於外觀的 CSS。HyperFrames 引擎逐幀捕獲頁面，並使用 FFmpeg 編碼為 MP4/WebM。

作為 manim-video 的補充： 對於數學/幾何解釋器（方程、3B1B 風格），請使用 manim-video。對於動態圖形、帶字幕的真人出鏡、產品導覽、社交疊加層、著色器過渡以及任何由真實視頻/音頻媒體驅動的內容，請使用 hyperframes。

何時使用​

  • 用戶要求從文本、腳本或網站渲染視頻
  • 動畫標題卡、下三分之一字幕條（lower thirds）或排版介紹
  • 帶字幕的旁白視頻（TTS + 與波形同步的字幕）
  • 音頻反應視覺效果（節拍同步、頻譜條、脈衝發光）
  • 場景間過渡（交叉淡入淡出、擦除、著色器扭曲、閃白）
  • 社交疊加層（Instagram/TikTok/YouTube 風格）
  • 網站到視頻的流程（捕獲 URL，製作宣傳片）
  • 任何必須確定性渲染為視頻文件的 HTML/CSS/JS 動畫

不要將此技能用於：

  • 純數學/方程動畫（→ manim-video）
  • 圖像生成或模因（→ meme-generation，圖像模型）
  • 實時視頻會議或流媒體

快速參考​

npx hyperframes init my-video               # scaffold a project
cd my-video
npx hyperframes lint                        # validate before preview/render
npx hyperframes preview                     # live-reload browser preview (port 3002)
npx hyperframes render --output final.mp4   # render to MP4
npx hyperframes doctor                      # diagnose environment issues

渲染標誌：--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 前的規劃​

在接觸代碼之前，從高層面闡述：

  • 內容 — 敘事弧線、關鍵時刻、情感節奏
  • 結構 — 合成、軌道（視頻/音頻/疊加層）、持續時間
  • 視覺標識 — 顏色、字體、運動特徵（爆發式 / 電影感 / 流暢 / 技術感）
  • 主幀（Hero frame） — 對於每個場景，最多元素同時可見的時刻。這是你首先構建的靜態佈局。

視覺標識門禁（硬門禁）。 在編寫任何合成 HTML 之前，必須定義視覺標識。切勿使用默認或通用顏色編寫合成（#333、#3b82f6、Roboto 表明跳過了此步驟）。按順序檢查：

  1. 項目根目錄下有 DESIGN.md 嗎？ → 使用其確切的顏色、字體、運動規則和“禁止事項”約束。

  2. 用戶指定了風格嗎（例如“瑞士脈衝”、“黑暗科技感”、“奢侈品牌”）？ → 生成一個最小的 DESIGN.md，包含 ## Style Prompt、## Colors（3-5 個帶有角色的十六進制顏色）、## Typography（1-2 個字體系列）、## What NOT to Do（3-5 個反模式）。

  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 <name> 以選擇一個模板，傳遞 --video clip.mp4 或 --audio track.mp3 以使用媒體素材進行初始化。

3. 先佈局，後動畫​

首先編寫**主視覺幀（hero frame）**的靜態 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 以獲取完整的數據屬性架構和構圖規則。

4. 使用 GSAP 製作動畫​

每個構圖必須：

  • 註冊其時間軸：window.__timelines["<composition-id>"] = tl
  • 初始暫停：gsap.timeline({ paused: true })——由播放器控制播放
  • 使用有限的 repeat 值（禁止 repeat: -1——這會破壞捕獲引擎）。計算方式：repeat: Math.ceil(duration / cycleDuration) - 1。
  • 具有確定性——禁止使用 Math.random()、Date.now() 或基於牆鍾時間的邏輯。如果需要偽隨機性，請使用 seeded PRNG（種子偽隨機數生成器）。
  • 同步構建——在時間軸構建周圍禁止使用 async/await、setTimeout 或 Promise。

請參閱 references/gsap.md 以獲取核心 GSAP API（tweens、eases、stagger、timelines）。

5. 場景之間的過渡​

多場景構圖需要過渡。規則如下：

  1. 場景之間始終使用過渡——禁止硬切（jump cuts）。
  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 "Script text" --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) 清除操作——否則字幕組會洩漏並顯示在後續組中。
  • 音頻反應式視覺效果： 預提取音頻頻段（低音/中音/高音），並在時間軸內通過 for 循環 tl.call(draw, [], f / fps) 每幀採樣——單個長 tween 不會對音頻產生反應。映射關係：低音 → scale（脈衝），高音 → textShadow/boxShadow（發光），整體振幅 → opacity/y/backgroundColor。避免均衡器條形圖的陳詞濫調——讓內容引導視覺，音頻驅動其行為。
  • 標記式高亮： 用於強調文本的高亮、圓圈、爆發、塗鴉、素描效果是確定性的 CSS+GSAP 實現——參見 references/features.md#marker-highlighting。完全可.seekable（可跳轉），無動畫 SVG 濾鏡。
  • 場景過渡： 每個多場景構圖必須使用過渡（禁止硬切）。從 CSS 原語（推滑、模糊交叉淡入淡出、縮放穿過、交錯塊）或通過 npx hyperframes add 使用的著色器過渡（flash-through-white、liquid-wipe、cross-warp-morph、chromatic-split 等）中選擇。情緒和能量表位於 references/features.md#transitions。不要在同一個構圖中混合使用 CSS 和著色器過渡。

7. Lint、驗證、檢查、預覽、渲染​

npx hyperframes lint              # catches missing data-composition-id, overlapping tracks, unregistered timelines
npx hyperframes validate          # WCAG contrast audit at 5 timestamps
npx hyperframes inspect           # visual layout audit — overflow, off-frame elements, occluded text
npx hyperframes preview           # live browser preview
npx hyperframes render --quality draft --output draft.mp4    # fast iteration
npx hyperframes render --quality high --output final.mp4     # final delivery

hyperframes validate 會對每個文本元素背後的背景像素進行採樣，並對對比度低於 4.5:1（大文本為 3:1）的情況發出警告。hyperframes inspect 是佈局方面的輔助工具——它在多個時間戳運行頁面，並標記靜態 lint 無法發現的問題（例如僅在 4.5 秒時超出安全區域的字幕、標題為最長變體時溢出的卡片、最終位於過渡著色器後面的元素）。特別是在包含對話氣泡、卡片、字幕或緊湊排版的構圖上運行 inspect。

8. 網站轉視頻（如果用戶提供 URL）​

使用 references/website-to-video.md 中的 7 步捕獲到視頻工作流：capture → DESIGN.md → SCRIPT.md → storyboard → composition → render → deliver。

常見陷阱​

  • 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（同時處理可見性和不透明度）。
  • 調用 video.play() 或 audio.play() — 框架擁有播放控制權。切勿自行調用這些方法。
  • 異步構建時間軸 — 捕獲引擎在頁面加載後同步讀取 window.__timelines。切勿將時間軸構建包裹在 async、setTimeout 或 Promise 中。
  • ** standalone index.html 被 <template> 包裹** — 這會向瀏覽器隱藏所有內容。只有通過 data-composition-src 加載的子組合才使用 <template>。
  • 使用視頻承載音頻 — 始終使用靜音的 <video> + 單獨的 <audio>。

驗證​

在渲染前後執行以下操作：

  1. Lint + 驗證 + 檢查通過： 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.2s、paced-slow >2s）。掃描摘要和標誌 — 修復或證明每個問題的合理性。小幅編輯可跳過此步驟。
  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 — 數據屬性、時間軸契約、不可協商的規則、排版/資源規則
  • 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 修復、環境變量、常見渲染錯誤