Communitygithub.com

zengbaocheng/hermes-tech-hub

使用 HyperFrames 創建基於 HTML 的影片合成、動態標題卡片、社群疊加層、帶字幕的對嘴說話影片、音訊反應視覺效果和著色器轉場。HTML 是影片的真實來源。當用戶想要從 HTML 合成渲染 MP4/WebM、想要為文字/標誌/圖表進行動畫處理、需要與音訊同步的字幕、想要 TTS 旁白或想將網站轉換為影片時使用此技能。

hermes-tech-hub 是什麼?

此技能基於 HyperFrames 提供全面的影片生成功能。核心概念是「HTML 是影片的真實來源」,透過撰寫帶有 `data-*` 時間屬性的 HTML 檔案、GSAP 時間軸和 CSS 樣式,來精準控制影片的每一幀,最終由 FFmpeg 編碼輸出為 MP4 或 WebM 格式。它與 `manim-video` 技能互補,專門處理動態圖形、對嘴說話影片、產品導覽、社群媒體疊加層、著色器轉場等需要實際影片/音訊媒體驅動的場景。支援多種平台如 Claude Code、Cursor、Codex 等 AI 編碼工具。工作流程強調在撰寫任何 HTML 前先規劃視覺風格(強制要求 `DESIGN.md`),然後逐步建構場景、使用 GSAP 進行動畫、並在渲染前透過 lint、validate 和 inspect 等指令進行嚴格驗證。它還整合了 TTS 語音合成、基於 Whisper 的字幕生成(需注意非英文語言的模型選擇)、音訊反應視覺效果、以及場景轉場(CSS 或著色器)。最後,它提供詳細的渲染指令和驗證清單,確保輸出影片的品質與穩定性。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/zengbaocheng/hermes-tech-hub/tree/HEAD/creative/hyperframes

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

HyperFrames

HTML 是影片的真實來源。一個合成是一個帶有 data-* 時間屬性、GSAP 時間軸用於動畫、以及 CSS 用於外觀的 HTML 檔案。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 參考:參考文檔/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 並報告結果。

若設定失敗,請參閱參考文檔/故障排除.md。

程序

1. 在撰寫 HTML 之前先規劃

在接觸程式碼之前,請先在高層次說明:

  • 什麼 — 故事弧線、關鍵時刻、情感節奏
  • 結構 — 合成、軌道(影片/音訊/疊加層)、持續時間
  • 視覺識別 — 顏色、字體、動畫角色(爆炸性 / 電影感 / 流暢 / 技術性)
  • 英雄幀 — 對於每個場景,同時有最多元素可見的時刻。這是您將首先建構的靜態佈局。

視覺識別關卡(嚴格關卡)。 在撰寫任何合成 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. 先佈局,後動畫

先撰寫英雄幀的靜態 HTML+CSS — 還沒有 GSAP。.scene-content 容器必須填滿場景(width:100%; height:100%; padding:Npx),並使用 display:flex + gap。使用內邊距將內容推向內側 — 切勿在內容容器上使用 position: absolute; top: Npx(當內容高於剩餘空間時會溢出)。

只有在英雄幀看起來正確之後,才新增 gsap.from() 進入動畫(動畫到 CSS 位置)和 gsap.to() 退出動畫(從 CSS 位置動畫離開)。

請參閱參考文檔/合成.md以了解完整的 data-attribute 架構和合成規則。

4. 使用 GSAP 進行動畫

每個合成必須:

  • 註冊其時間軸:window.__timelines["<合成-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.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 → 逐字稿。根據轉錄稿語調選擇風格(炒作 / 企業 / 教學 / 說故事 / 社交 — 請參閱 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)

使用參考文檔/網站到影片.md中的 7 步驟擷取到影片工作流程:擷取 → DESIGN.md → SCRIPT.md → 分鏡圖 → 合成 → 渲染 → 交付。

陷阱

  • 'HeadlessExperimental.beginFrame' wasn't found — Chromium 147+ 移除了此協定。確保您使用的是 hyperframes@>=0.4.2(會自動偵測並回退到螢幕截圖模式)。逃生艙:export PRODUCER_FORCE_SCREENSHOT=true。請參閱 hyperframes#294 和參考文檔/故障排除.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。
  • 獨立的 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 <合成目錄> \
      --out <合成目錄>/.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 — 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 修復、環境變數、常見渲染錯誤

相關技能