Communitygithub.com

jgilb17/jpg

從 HTML 合成 MP4/WebM 影片。將 HTML 作為影片的源頭,透過逐幀擷取並編碼為影片。

jpg 是什麼?

這是一個名為 HyperFrames 的 AI 技能,能夠將 HTML 合成為 MP4 或 WebM 格式的影片。其核心概念是將 HTML 視為影片的唯一真相來源(source of truth),使用者可以透過在 HTML 檔案中添加 `data-*` 屬性來控制時序、使用 GSAP 動畫庫來製作動畫效果,以及使用 CSS 來設計外觀。HyperFrames 引擎會逐幀擷取網頁的畫面,並透過 FFmpeg 編碼輸出為最終影片。此技能非常適合製作動態圖形、含字幕的談話頭影片、產品導覽、社群媒體疊加層、場景轉場,以及任何由實際影片或音訊媒體驅動的內容。它能與處理數學幾何動畫的 `manim-video` 技能互補。支援的平台包括 Claude Code、Cursor、Codex 等 AI Agent 工具。使用流程包含規劃、建立專案、撰寫靜態佈局、使用 GSAP 製作動畫、處理場景轉場、加入音訊與字幕、以及最終的 lint/驗證/預覽/渲染步驟。此工具特別強調視覺識別的規範(必須有 DESIGN.md 或明確的設計方向)、動畫的確定性(禁止非確定性行為如 `Math.random()`)、以及嚴格的場景轉場規則。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jgilb17/jpg/tree/HEAD/.claude/skills/hyperframes

在你喜歡的 AI 中提問

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

說明文件

HyperFrames

HTML 是影片的唯一真相來源。一個合成 (composition) 由一個帶有 data-* 屬性控制時序的 HTML 檔案、一個 GSAP 時間軸 (timeline) 控制動畫,以及 CSS 控制外觀所組成。HyperFrames 引擎會逐幀擷取網頁畫面,並透過 FFmpeg 編碼為 MP4/WebM 格式。

與 manim-video 互補: 數學/幾何圖解(方程式、3B1B 風格)請使用 manim-video。動態圖形、含字幕的談話頭、產品導覽、社群媒體疊加層、著色器轉場,以及任何由實際影片/音訊媒體驅動的內容,請使用 hyperframes。

使用時機

  • 使用者要求根據文字、腳本或網站產生已渲染的影片
  • 動畫標題卡、下三分之一字幕 (lower thirds) 或排版介紹
  • 附字幕的旁白影片(語音合成 + 與波形同步的字幕)
  • 音訊響應式視覺效果(節拍同步、頻譜條、脈動光暈)
  • 場景轉場(淡入淡出、擦除、著色器扭曲、閃白)
  • 社群媒體疊加層(Instagram/TikTok/YouTube 風格)
  • 網站轉影片流程(擷取網址,產出宣傳影片)
  • 任何必須確定性地渲染為影片檔案的 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 ~/.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) —— 對於每個場景,當最多元素同時可見的瞬間。這是你會先構建的靜態版面。

視覺識別柵門(HARD-GATE)。 在撰寫任何合成 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 <名稱> 選擇一個,或使用 --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["<合成-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。

核心 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. 音訊、字幕、語音合成、音訊響應式、標記

  • 音訊: 始終使用獨立的 <audio> 元素(影片是 muted playsinline)。
  • 語音合成 (TTS): npx hyperframes tts "腳本文字" --voice af_nova --output narration.wav。使用 --list 列出可用語音。語音 ID 的第一個字母編碼語言(a/b=英文、e=西班牙文、f=法文、j=日文、z=中文等)—— CLI 會自動推斷音素化器 (phonemizer) 的語言環境;僅在需要覆蓋時傳遞 --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。避免等化器條的陳腔濫調 —— 讓內容引導視覺,音訊驅動其行為。
  • 標記式強調: 文字強調的 highlight、circle、burst、scribble、sketchout 效果是確定性的 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. 網站轉影片(如果使用者提供網址)

使用 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(同時處理 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 <合成目錄> \
      --out <合成目錄>/.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 —— 字幕、語音合成、音訊響應式、標記強調、轉場(按需載入)
  • website-to-video.md —— 7 步驟擷取轉影片工作流程
  • troubleshooting.md —— OpenClaw 修復、環境變數、常見渲染錯誤

相關技能