Communitygithub.com

nastechresearch/nastech-agent

從 HTML 組合中渲染 MP4/WebM 影片。

nastech-agent 是什麼?

HyperFrames 是一個以 HTML 為影片創作核心來源的工具。它透過 HTML 檔案中的 `data-*` 屬性來定義時間軸,並整合 GSAP 動畫庫與 CSS 樣式,讓開發者能以網頁技術建構動態影片。其引擎會逐幀捕捉頁面渲染結果,並利用 FFmpeg 編碼輸出為 MP4 或 WebM 格式。此工具特別適合製作動態圖形、含字幕的解說影片、產品導覽、社群媒體重疊效果,以及各種需要結合真實影片或音訊媒體的創作。與專注於數學與幾何動畫的 `manim-video` 形成互補。HyperFrames 支援 Claude Code, Cursor, 以及 Codex 等 AI 代理平台,並提供完整的 CLI 指令,包括專案初始化、預覽、渲染和問題診斷,確保從設計到產出的流程順暢。其設計原則強調事前規劃視覺識別、先布局後動畫、以及使用確定性的 GSAP 時間軸,以確保渲染結果的可預測性與一致性。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nastechresearch/nastech-agent/tree/HEAD/optional-skills/creative/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                      # 診斷環境問題

preview 是一個長效的 Next.js 伺服器,會保持 Chrome 渲染工作程序開啟。使用完畢後務必將其停止(請參閱清理)— 一個被遺忘的預覽行程會讓閒置的 chrome-headless-shell 工作程序繼續存在,在沒有 GPU 的主機(如 WSL、容器、CI)上,這些程式會透過軟體 WebGL(swiftshader)無限期地佔用一個 CPU 核心。

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

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

設定(一次性)

bash "$(dirname "$(find ~/.nastech/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。使用內邊距將內容向內推 — 永遠不要在內容容器上使用 position: absolute; top: Npx(當內容高於剩餘空間時會溢出)。

只有在關鍵影格看起來正確之後,再加入 gsap.from() 進場動畫(動畫到 CSS 位置)和 gsap.to() 出場動畫(從其位置動畫離開)。

完整的 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() 或即時時鐘邏輯。如果需要偽隨機性,請使用種子偽隨機數產生器。
  • 同步建立 — 在時間軸建構過程中,不能使用 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 → 分鏡 → 組合 → 渲染 → 交付。

清理

render 是一次性的(工作程序會在完成時退出)。preview 則否 — 它會執行一個背景 Next.js 伺服器,讓 Chrome 工作程序保持常駐,直到你停止它。絕對不要任其執行:在沒有 GPU 的主機上,每個閒置工作程序的 swiftshader 處理程序會佔用一個 CPU 核心,而一個打開數天的預覽會累積多個工作程序。

當使用者完成審查時(或在開始新的預覽之前),停止預覽:

pkill -f "hyperframes.*preview"     # Studio 伺服器(釋放連接埠 3002)
pkill -f chrome-headless-shell      # 其渲染工作程序;只在沒有其他工具使用時才安全

如果不確定其他工具是否使用了 chrome-headless-shell,請先檢查:pgrep -af chrome-headless-shell。以同樣方式恢復一個卡住的主機(許多閒置工作程序佔用 CPU)— 請參閱 references/troubleshooting.md。

常見陷阱

  • 讓 preview 保持執行 — 這是一個長效伺服器,會持有 Chrome 工作程序;在 WSL/容器/CI 環境中,這些閒置工作程序每個都會佔用一個 CPU 核心(軟體 WebGL)。使用完畢後將其停止 — 請參閱清理。

  • 找不到 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 — 會破壞捕捉引擎。務必計算一個有限的 repeat 次數。

  • 對稍後才出現的剪輯元素使用 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 中。

  • 將獨立的 index.html 包在 <template> 中 — 這會將所有內容對瀏覽器隱藏。只有透過 data-composition-src 載入的子組合才能使用 <template>。

  • 使用影片來處理音訊 — 務必使用靜音 <video> + 獨立的 <audio>。

驗證

在渲染前後:

  1. 檢查 + 驗證 + 審查通過: 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.2 秒、paced-slow >2 秒)。掃描摘要和標記 — 修正或證明每個項目的合理性。小幅編輯可跳過此步驟。
  3. 檔案存在且非零: ls -lh final.mp4。
  4. 時長符合 data-duration: ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 final.mp4。
  5. 渲染記錄在專案 README 中(交付品質)。

相關技能