Communitygithub.com

HTML Motion Pipeline (9:16 解說影片,VO + SFX → MP4)

將 HTML 動畫流水線轉換為 9:16 規格的 MP4 解說影片,內建用戶語音與音效同步,支援 2D 平面動畫風格,適用於 Reels/TikTok 等教育科技帳號。

HTML Motion Pipeline (9:16 解說影片,VO + SFX → MP4) 是什麼?

這是一個專為 AI 代理設計的影片製作技能,能將 HTML/GSAP 動畫流水線轉換為 9:16 直式 MP4 解說影片。它支援用戶自備的語音檔案(非 TTS),並自動進行逐字字幕、節點連線動畫、以及音效同步。技能內建多項自動化檢查機制,包括版面溢出檢測、文字重疊偵測、以及內容垂直平衡分析,確保影片品質。此技能已通過實際案例驗證(「什麼是 Function Calling?」影片,長度 44.6 秒,解析度 1080×1920,包含 31 個音效),主要用於 Cursor、Claude Code 等 AI 開發工具。使用者只需提供語音檔案與腳本,技能會自動完成語音分割、節奏調整、逐字轉寫、動畫建構、音效混合、幀渲染與最終編碼。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/hasbiridwan57-creator/hermes-video-motion-skills/tree/main/html-motion-pipeline

在你喜歡的 AI 中提問

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

說明文件

HTML Motion Pipeline(9:16 解說影片,VO + SFX → MP4)

已驗證流程。每個步驟在 assets/pipeline/ 中都有現成可用的指令。 完整實作參考:assets/pipeline/index.fc-reference.html(Function Calling 專案 — 複製後替換內容,不要從頭撰寫)。

為什麼選擇這個流水線

  • 確定性:GSAP 時間軸 paused,逐幀尋找 → MP4 = 預覽。
  • 用戶自己的語音(ElevenLabs/麥克風檔案),非 TTS;可控制語速。
  • 自動版面稽核:偵測文字超出畫布與碰撞其他元素 — 必須通過後才能完整渲染(節省 1338 幀的渲染)。
  • 整齊的連線:錨點位於節點邊緣,置於底層(請參閱陷阱 #1)。

主要原則(這是核心)

視覺服務於腳本與語音,而非反過來。

  1. 螢幕上顯示的所有內容都必須在腳本中且由語音說出。有趣但未旁白的元素 → 刪除,無論多好看。
  2. 反之,腳本中每個重要想法/句子都必須有自己的圖像,在該短語被說出時出現。僅作為靜態文字的句子 = 「沉悶」場景 → 添加視覺元素。
  3. 場景多不是問題 — 關鍵是每個場景都要跟隨語音與腳本。
  4. 更多圖像與動畫 = 更好(更有活力)。不要吝嗇添加視覺元素;視覺豐富度是加分,不是缺點。
  5. 視覺的順序與時機 = 語音中提及的順序與時機(來自轉寫時間戳),而非自行決定。
  6. 視覺細節品質也需維護:圖示必須清楚可辨識其意涵,元素平衡且不懸浮。

流程(依序執行)

#步驟輸出
1取得用戶語音 + 按段落分割(呼吸停頓)meta.json
2透過 ffmpeg atempo 調整語速 + 插入停頓;選擇變體vo.wav
3逐字轉寫(faster-whisper,pip install faster-whisper)assets/words.json
4建構 index.html(8 個場景跟隨語音時機)+ sfx_score.pyHTML + SFX WAV
5混合語音 + 音效 → public/full_mix.mp3最終音訊
6版面稽核(audit2.mjs + audit_s2.mjs)— 必須 0 溢出報告
7渲染幀(render_frames.mjs)→ 1338 張 PNGframes/
8編碼(encode.sh)→ MP4public/*.mp4
9檢查最終 MP4 視覺 — 從 MP4 提取幀,透過視覺分析確認乾淨

一次性設定

cd <專案目錄>
npm init -y && npm install playwright-core gsap
pip install faster-whisper   # 用於逐字轉寫
# 需要:Google Chrome (/Applications/Google Chrome.app),ffmpeg

流水線腳本

assets/pipeline/:

  • render_frames.mjs — 逐幀尋找時間軸,以 1080×1920 @30fps 截圖。
  • snap.mjs — 拍攝特定秒數的快照(node snap.mjs 1.0 6.5 17.5)用於視覺檢查。
  • audit2.mjs — 檢查所有場景:文字超出畫布 / 進入下方 UI 區域(>1560px)/ 碰撞。
  • audit_s2.mjs — 在許多時間點稽核 1 個場景(sc2)(偵測過早顯現、貼近邊緣)。
  • audit_overlap.mjs — 偵測真正重疊的文字(文字×文字、文字×圖片、文字×按鈕)。智慧區分真實碰撞與 by-design 的:SVG 容器內的標籤、刪除線/貫穿線、並排的彈性字幕 → 不報告。執行 node assets/pipeline/audit_overlap.mjs → 目標為 TOTAL 重疊: 0。
  • audit_center.mjs — 偵測「懸掛在上方」的內容(下方 2/3 空白)。計算每個場景的內容邊界框,測量與理想中心點(y≈960 用於 1920px)的偏差。偏差 > 250px = ⚠ 懸掛。執行 node assets/pipeline/audit_center.mjs。
  • typing-prompt.js — 「打字提示」動畫配方(編碼/AI 主題核心):提示逐字輸入 + 游標閃爍,然後應用程式回應(變色 → 錯誤 → 修正 → 迭代)。完整範例:影片倉庫 09-vibe-coding/index.html 場景 SK4。
  • encode.sh — ffmpeg → H.264 yuv420p CRF18 + AAC 192k + +faststart。
  • sfx_score.py — 與文字時機同步的程序化音效配樂。
  • index.fc-reference.html — 完整實作(複製並替換內容)。

HTML 慣例(在 index.fc-reference.html 中)

  • #stage 1080×1920,點狀網格背景;#world(相機支架,每個場景微調縮放);場景 = .scene(可見性隱藏,透過時間軸顯示/隱藏)。
  • 逐字字幕:assets/words.json → 分組成 ≤4 個字的區塊,每個區塊一個 .line(position:absolute,堆疊以免擴展盒子),當前字 .on,關鍵字 .key(琥珀色)。位置距底部 390px(安全避開 Reels/TikTok 約 360px 的底部 UI)。
  • 連線:函式 link(svg,idA,idB) 計算節點邊緣的錨點(edge/edgeT)— 連線不會從標誌中心穿出。SVG .wires 作為** .scene 的第一個子元素**(z-index:0)以位於卡片(z-index:2)後方。平滑曲線(彎曲 ≤26px),顏色灰 #7A8188 8px;活躍連線 .hot 琥珀色 15px。
  • 代理標誌:OPENCLAW_SVG 內嵌(紅色龍蝦),自動安裝到每個包含 🤖 的 .node.dark。如需其他身份可更換。
  • GSAP 確定性:時間軸 paused,暴露 window.__tl 和 window.__updateSub。模式 ?t=<秒數> 用於靜態快照(無頭模式),?debug 用於手動拖動。

觸發詞

使用者提到 「pipeline motion explainer」,或要求「9:16 動態解說影片」,或說「像上次的 Function Calling 影片那樣」 → 載入此技能。不是 motion-format / bang-motion(其他技能)。用戶語音始終作為檔案在每次對話中提供 — 此技能儲存的是運作方式,而非音訊/內容資產。

陷阱(請勿重複)

  1. 連線穿過標誌/文字 → 確保:(a) SVG 連線是場景的第一個子元素,(b) z-index:0 的連線與 z-index:2 的卡片,(c) 錨點使用 link() 在邊緣。
  2. 字幕遮蓋卡片 / 進入 UI 區域 → 每行 1 個堆疊(absolute),每個區塊最多 4 個字,bottom ≥ 390px。
  3. 渲染時 window.tl 未定義 → 暴露的名稱必須是 window.__tl(使用 __),否則 74% 的幀會相同/靜止。檢查:md5 frames/* | uniq -c。
  4. 渲染背景被重新啟動 → 確保沒有舊的 render_frames 在執行(pgrep -fl render_frames)再開始新渲染;先刪除 frames/。
  5. DOM 稽核不能取代視覺檢查最終 MP4。 稽核查溢出與邊界框碰撞,但無法偵測連線穿過標誌或文字遮蓋卡片 — 這些只會出現在最終像素中。編碼後,從 MP4 提取關鍵幀(ffmpeg -ss <t> -i out.mp4 -frames:v 1 f.png),然後透過 vision_analyze 分析。
  6. 「懸掛在上方」的內容(下方 2/3 空白)。 這最常被忽略,因為一般稽核只檢查溢出而非平衡。原因:所有 .hero 的子元素使用 position:absolute → flexbox justify-content:center 對它們無效。解決方案:讓 .hero 的子元素成為正常流(block/flex flow),只有重疊元素(徽章/刪除線/標記)保持 absolute。必須執行 audit_center.mjs — 中心偏差 > 250px = 失敗。
  7. 視覺不跟隨腳本(最具破壞性)。 不要因為動畫在跑就認為場景「完成」。實際案例:相關性圖表與年齡圖表出現在螢幕上,但語音從未提及它們。渲染前的強制性腳本稽核:(a) 提取語音逐字轉寫 + 時間戳(words.json),(b) 對應「這個短語在螢幕上的出現時間?」,(c) 出現在螢幕但不在腳本中的元素 → 刪除;腳本中僅作為靜態文字的短語 → 添加視覺元素。視覺順序 = 語音提及順序。
  8. 渲染 OOM(Mac 8GB)。 Chromium 在列印數百張截圖時累積記憶體 → 中途崩潰(「Target page closed」)。解決方案:每約 400 幀重新啟動瀏覽器 + 自動恢復(跳過已存在且 > 20KB 的幀)。不要在單次瀏覽器工作階段中渲染超過 2500 幀。
  9. 修訂後舊幀混入。 如果只修訂部分場景且只刪除該範圍的幀,frames/ 會變得混雜(例如 2770 個檔案但只需要 2574)。最安全的方法:在完整渲染前刪除整個 frames/。如果要恢復,請在編碼前驗證檔案數量 = 總幀數。
  10. Emoji 逃過 DOM 稽核。 使用者要求無 emoji — 如果沒有自動檢查,emojis 可能會因為邊界框稽核不看字元類型而逃過。渲染前,執行 Python 正規表達式尋找 emoji 字元;如果找到 → 替換為內嵌 SVG。圖示始終使用 SVG。 re.findall(r'[\U0001F300-\U0001FAFF\u2600-\u27BF\u2B00-\u2BFF\uFE0F]', html) → 必須為 0。
  11. 圖示與視覺細節必須在其顯示尺寸下可辨識 — DOM 稽核與版面稽核無法捕捉「圖示不清楚」。 一個 SVG 可能在程式碼中形狀正確,但在渲染尺寸下(例如圖表中 180px 的圖示)看起來像別的東西:開放大腦輪廓圖示可能被誤認為雲/花,而非大腦。修正: 在完整渲染前,從 MP4 提取幀並放大(裁切)關鍵圖示/圖表,然後透過 vision_analyze 評估 — 「這是否清楚可辨識為 X?」。如果模糊,簡化形狀(實心剪影優於開放輪廓)並增大尺寸。邊界框稽核僅檢查位置,不檢查形狀可讀性。
  12. 比較元素需平衡(A-vs-B 長條/柱狀)必須屬於同一個視覺群組。 長條「懸浮」在其父卡片之外(分離的絕對定位)破壞平衡,且當內容高度變化時容易覆蓋其他元素。實際案例:萎縮/強壯肌肉長條懸浮在健身房卡片外,然後碰撞其他卡片。修正: 將每個長條放入其自己的卡片/儲存格內;不同的長條長度是故意的(長度 = 數值),但卡片寬度與基準線必須相同。每次版面修訂後透過 audit_overlap 檢查。
  13. 文字重疊雖然看起來「只有一點點」。 不要相信眼睛;使用 audit_overlap.mjs 來測量真實的邊界框。巨大的 ?、裝飾性大數字或長標題經常無意識地覆蓋其他文字。
  14. 編碼/AI 主題若無打字動畫會感覺死氣沉沉。 靜態文字無法傳達 vibe coding 的運作方式。使用 typing-prompt.js 配方:提示逐字輸入 + 游標閃爍 + 應用程式回應(變色 → 錯誤 → 修正 → 迭代)。
  15. 來自網路的標誌/圖示:下載官方 SVG(來自 jsDelivr CDN / GitHub 品牌倉庫),然後作為文字內嵌在 HTML 中 — 不要使用 <img src> 指向外部檔案,這樣無頭渲染就不必依賴網路。移除 SMIL 動畫以確保輸出確定性。

語音規則(使用者 Hasbi)

  • 製作語音必須是使用者自己的聲音(傳送的 ElevenLabs 檔案),而非 TTS。
  • 透過 procedural-sfx 技能使用程序化音效(無需 ElevenLabs 點數)。
  • MP4 傳送後刪除原始幀與輔助檔案(frames/、shots/、各段落的 *.wav)— MacBook 儲存空間有限。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

motion-format

Bikin video motion graphic lewat chat dengan alur kerja Motion Format — Reels/TikTok/Shorts 9:16, YouTube 16:9, atau feed 1:1 — dari brief sampai MP4 bersuara (voiceover + efek suara ElevenLabs, subtitle per kata). Punya resep gaya siap pakai dari seri konten Motion Format: Isometrik Dibongkar (cara kerja mesin, 3D), Sejarah 3D Sinematik (bangunan & peristiwa bersejarah), Tubuh Manusia Anime (organ tubuh), Dunia 2D Bertekstur (noir, cat air, ukiran, lanskap anime), Kartun Cel Cerah (tokoh menjelaskan), Peta Relief Sinematik (geografi, jalur, wilayah), dan Promo Produk & Iklan (UMKM, aplikasi, flash sale) — plus cara meracik gaya sendiri. Gunakan setiap kali user meminta "video", "konten Reels/TikTok/Shorts", "explainer", "video edukasi", "video penjelasan", "promo", "iklan", "intro", "animasi", "motion graphic", menyebut salah satu gaya di atas atau "Resep Gaya", ingin menambah voiceover/efek suara/subtitle, ingin merevisi video yang sudah ada, atau ingin merender jadi MP4 — walau tida

video-motion

SOP induk untuk bikin video motion/explainer bersuara via chat (9:16 Reels/TikTok, 16:9 YouTube, 1:1 feed) — menggabungkan alur kerja Motion Format (brief→gaya→naskah→ suara→adegan→render), hukum sinematik Bang Motion (video bukan slide, deterministik, gaya dari tema), dan pipeline HTML→MP4 teruji (html-motion-pipeline: faster-whisper, SFX prosedural, CDP render, audit layout, subtitle aman Reels). Gunakan bila user minta video motion/explainer/animasi/promo, atau "kayak video sebelumnya" — walau tidak menyebut "motion graphic".

相關技能