Communitygithub.com

sairam0424/MindForge

使用 HyperFrames 建立基於 HTML 的影片合成、動態標題卡、社交封面、附字幕的說話者影片、音訊反應視覺效果以及著色器轉場。以 HTML 作為影片的真實來源。

MindForge 是什麼?

此技能透過 HyperFrames 引擎,將 HTML/CSS/JS 轉換為影片,適用於需要從 HTML 合成渲染 MP4/WebM 的場景。它支援多種影片製作需求,包括動態文字、標誌、圖表、社交封面、與音訊同步的字幕、文字轉語音(TTS)、以及將網站轉換為影片。技能強調先定義視覺識別(色彩、字型、動態風格)再撰寫 HTML 的嚴格流程,並提供 CLI 工具進行專案初始化、預覽、渲染與驗證。主要平台為 Node.js 環境,依賴 FFmpeg、GSAP、Puppeteer 等工具,可產出高品質的確定性影片輸出。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sairam0424/MindForge/tree/HEAD/.agent/skills/hyperframes

在你喜歡的 AI 中提問

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

說明文件

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                      # 診斷環境問題

渲染標誌:--quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker(可重現) · --strict。

完整 CLI 參考:references/cli.md。

設定(一次性)

bash "$(dirname "$(find ~/.agent/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. 使用者指定了風格(例如「瑞士脈動」、「暗黑科技風」、「奢華品牌」)? → 生成一份精簡的 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。使用 padding 將內容往內推 — 永遠不要對內容容器使用 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() 或時鐘邏輯。若需要偽隨機性,請使用種子 PRNG。
  • 同步建立 — 在時間軸建構時不要使用 async/await、setTimeout 或 Promise。

核心 GSAP API(補間、緩動、間隔、時間軸)請參閱 references/gsap.md。

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) 終止 — 否則群組會以可見狀態洩漏到後面的群組。
  • 音訊反應視覺效果: 預先提取音訊頻段(低頻 / 中頻 / 高頻),並在時間軸內使用 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 → 分鏡 → 合成 → 渲染 → 傳遞。

常見陷阱

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

驗證

渲染前後:

  1. 語法檢查 + 驗證 + 檢查通過: npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes 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 — 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 修復、環境變數、常見渲染錯誤

相關技能