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