pedro-cmyks/explainer-video-skill

說明影片，統一風格

每支影片共享同一種視覺風格與動態語言，最初是為 CRM 說明影片所建構。 黃金參考檔案為 reference/desk-crm-explainer.html（84.5 秒，9 個場景，虛構產品 Desk CRM） 及其影格網格 reference/contact.png。如有疑問，請開啟參考檔案並複製其模式。

此技能中的檔案：

路徑	說明
templates/explainer-template.html	從這裡開始。完整的輔助工具包，包含 3 個範例場景（標題、附游標點擊的卡片、片尾）。
templates/apply-theme.mjs	將 themes/ 中的主題套用到影片 HTML（--theme studio --html explainer.html，--list）。原地執行。
themes/*.json	每個主題的外觀與音效（house、studio、ember、tide）：顏色、漸層、字型、卡片圓角、標誌標記、音樂調性、進行、節奏、琶音。house 為預設主題。
templates/render.mjs	Playwright 影格步進器，輸出至 ffmpeg。影片、海報、連絡表、靜止畫面。原地執行，永不複製。
templates/compose.py	Numpy 音樂背景，加上與場景本地時間同步的音效，經過母帶處理並混合。每個影片複製一份。
templates/voiceover.sh	選用的 macOS say 語音旁白，在音樂下自動降低音量。使用參數原地執行。
checklist.md	審查檢查清單。每個項目在交付前都必須通過。
reference/	參考 HTML 及其連絡表。永不編輯。
examples/tidy-tasks/	從範本建構的簡短完成影片（20 秒）：包含 HTML、其 compose.py 及連絡表。

每台機器設定一次：在技能資料夾中執行 npm install 和 npx playwright install chromium（它有一個 package.json），以及 ffmpeg 和 Python 3 搭配 numpy。當無法啟動時，render.mjs 會說明缺少什麼。

視覺風格

一種動態語言，多種樣貌。以下描述預設主題 house。主題會更改色板代碼、漸層、字型、卡片圓角、標誌標記及音樂；它永不更改動態、游標、字幕或檢查清單。相同主題加上相同場景會產生完全相同的影片，逐影格一致。 主題位於 themes/*.json（house、studio、ember、tide）；node $SK/apply-theme.mjs --list 列出它們，而 --theme <name> --html explainer.html 會將一個主題套用到 HTML 頂部的 THEME 區塊。compose.py 從同一區塊讀取音樂設定。簡要說明會指定主題；若無，則使用 house。若要建立新主題，請複製一個 json，更改代碼，保持 gr、am 和 rd 可辨識為綠色、琥珀色和紅色，選擇一個存在於渲染機器上的字型，並在使用前檢查連絡表的對比度。 每個場景的主題（選用）：將更多主題物件貼入 THEMES，並為場景指定 theme: 'studio'。色板、漸層和卡片圓角會在 1 秒的交叉淡入淡出中變形；字型和標誌標記在邊界處切換；音樂保持第一個主題。當影片本身關於多樣性時使用它；一個主題是正常情況。

舞台：1920x1080 SVG，字型 'Avenir Next', 'Helvetica Neue', Helvetica, Arial, sans-serif（主題 font）。

背景，三層，在主題內永不更改：

• 徑向漸層，中心位於 50% / 30%，r 75%：#172638 -> #111b26（60%）-> #0f1720
• 點陣網格：40 px 圖案，r 1.6 點 #22303f，透明度 70%
• 字幕區域：底部 200 px（y 880..1080）淡出至 #0b121a，透明度 90%

色板代碼（範本中的 C，保留名稱）：

代碼	十六進位	用途
bg	#0f1720	頁面，淡出至黑色的目標
s1	#141d27	卡片表面
s2	#1b2733	行、嵌入區域、內部面板
bd	#2a3a4b	邊框、網格線、空點
tx	#e6edf3	主要文字
mu	#a0b1c5	次要文字、欄位標題
bl	#3b82f6	動作、選取、封包、游標爆發、品牌強調字詞
gr	#2fca73	完成、啟用、增益、成功
am	#f59e0b	注意、熱點、離群值
rd	#ef4444	僅用於損失或錯誤
off	#3a4a5c	非活動狀態點
paper/ink	#f3f6fa / #1b2733	淺色文件頁面
light blue	#93c5fd、核心 #dbeafe	套索、高亮、封包核心
click spark	#ffd166	點擊爆發的交替輻條

漸層：logoG 藍色 #3b82f6 到綠色 #2fca73（對角線），用於標誌磁磚和底線；hotG 琥珀色到紅色，用於「熱點」長條；blueBar #2563eb 到 #3b82f6；areaG 綠色 38% 到 0，在圖表下方。

形狀：

• 卡片：圓角 26，填充 s1，2 px bd 描邊，陰影 dy 16, blur 20, 黑色 42%（card()）。
• 行：圓角 14..18，填充 s2，高度 52..80，間距 64..96 px。
• 晶片：完整藥丸形，高度 40，顏色填充 16%，標籤 24 px / 600 使用該顏色（chip()）。
• 主要按鈕：圓角 22，高度 84，純色 bl，白色 34 px / 700 標籤，柔和發光脈衝直到點擊。
• 圖示和藥丸的小陰影：dy 8, blur 8, 黑色 45%（#shs）。
• 應用程式視窗（參考 dashboard()）：66 px 頂部欄，s2，交通燈點 r 8（rd、am、gr，透明度 80%）， 214 px 側邊欄，#111922，導航項目高 48 圓角 14，活動項目 bl，透明度 20%，KPI 磁磚圓角 18。
• 狀態點 r 14；頭像環 4 px 加上 25% 光暈；鎖來自 lock()。
• 品牌標記：標誌 46 px 加上名稱 28 / 700，位置 (56, 40)，透明度 85%，從場景 2 開始顯示直到片尾。

字型比例（px / 粗細）：品牌字 132 / 700（片尾 96），標語 58 / 500 mu，結束語 56 / 600， 字幕 50 / 600，大數字 52..64 / 700 等寬，卡片標題 34..40 / 700，行文字 26..28 / 600， 標籤和晶片 24 / 600，沒有低於 22 的。品牌字字母間距 -1%。

構圖規則：

• 內容位於 y 120..860 和 x 140..1780。字幕區域和品牌標記角落保持空白。 這包括靜止游標：保持其尖端在 y <= 800（箭頭大約從尖端向下延伸 75 px）。
• 任何根據文字調整大小的元素（刪除線、底線、高亮框、藥丸）都從 textW(str, size, weight) 取得寬度， 從不使用猜測的常數。
• 永遠不要讓畫面的三分之二留空。當內容左右分割時，使用流程線、封包或頁面扇形 連接中間。將整個場景群組（G(s, {x: SX})）移位以重新置中。
• 每個場景一個想法。最多並排兩張卡片加上一個詳細卡片。
• 資料始終是虛構的：客戶 A、Northwind、Maple Ridge、Bluebird、Harbor Point、ACC 01。

動態語言

緩動工具包（在範本中）：E 三次進出（所有項目的預設值），EO 三次出（穩定）， EB 帶約 10% 過衝的反彈出（彈出效果：卡片、晶片、徽章、圖示），esine 用於繪製路徑， fadeIO(t, a, b, 0.35) 用於游標透明度，五次方出 1 - (1 - x)^5 用於計數器。 確定性：僅使用 rng(seed)，永不使用 Math.random 或牆上時鐘。

入場：

• 卡片：0.5 秒內淡入並上升 20 px，或 0.7 秒內縮放 mix(0.92, 1, EB)。
• 列表行：間隔 0.08..0.12 秒，從 x -20 / -30 或 y +16 滑入，每個 0.5 秒。
• 彈出效果：EB 在 0.5..0.7 秒內。徽章縮放 0.7 -> 1。
• 品牌字：從中心開始的剪裁擦拭，持續 0.8 秒，並上升 34 px；標誌使用 pathLength 繪製。

游標工具包（drawCursor、curPos）：

• 白色箭頭路徑 ARROW，#0b1118 3.4 px 外框，投影 dx 4 dy 7 blur 4，透明度 50%，基礎縮放 1.1。
• keys: [[t, x, y], ...] 以本地秒為單位，(x, y) 是箭頭尖端。滑動使用三次進出加上 距離 12% 的水平弧線（最大 110 px）。傾斜跟隨水平速度（每 px 0.35 度，最大 14 度）。
• 典型滑動 0.7..1.5 秒。從畫面外 (1880, 1080) 進入，大約在場景開始後 1.5 秒。
• 在點擊前至少 0.15 秒到達，並精確地位於控制項的中心。
• 點擊：在點擊時（0.34 秒視窗，從 0.1 秒前開始）壓縮 x +16% 和 y -22%，然後是 0.6 秒的 爆發：藍色環 r 8 -> 54，厚度 6 -> 1 px，加上 8 個交替白色 / #ffd166 的輻條。
• 被點擊的控制項使用 press() 下陷至縮放 0.93，其發光脈衝停止。
• 動作後，滑動到一個安靜的休息點（在卡片之間，例如 (1010, 800)）並保持。隨場景淡出。
• trail 在繪製時添加一個 12 點的藍色彗星尾巴；pos 用於自訂路徑（套索）取代 keys。

標誌性動作（要複製的參考場景）：

• 套索：游標使用 esine 繪製一個搖擺的橢圓，虛線 #93c5fd 5 px（16 12，流動）， 閉合時實線並帶有 0.35 秒的發光閃爍和 7% 填充，然後圖示沿曲線路徑飛入一個幽靈框架， 該框架凝固成應用程式視窗（sBefore）。
• 封包：發光點（r 22 發光加上 r 12 #dbeafe 核心）帶有 6 點彗星尾巴，在 S 曲線上，三次進出 在 1.2..1.45 秒內，虛線引導線以 24 px/s 流動，發送者閃爍藍色，到達時綠色環（packet()、sClose）。
• 狀態點：灰色 -> 綠色，帶有環爆發（r 14 -> 40，0.6 秒）和 1.25x 彈出，然後呼吸發光 0.25 + 0.2 sin(3t)。警告：琥珀色，每隔 1.3 秒重複環，短暫抖動（statusDot()、sStatus）。
• 圖表繪製：pathFrom 在 1.5..3.7 秒內顯示線條，6..7 px 綠色，areaG 填充，發光頭部點 （r 18 發光加上 r 10 白色）。長條從零開始錯開 0.18 秒增長。熱圖儲存格錯開彈出（sAlgos、sHistory）。
• 計數器：使用五次方出在 1.0 秒內計數，等寬數字。
• 頁面扇形：頁面離開按鈕，扇形穿過中心（旋轉 -10、-3.5、3.5、10 度，60 px 跳躍）， 然後每個跳躍 110 px 進入一個托盤，縮放 0.56，錯開 0.55 秒；托盤在滿時發出綠色光（sReports）。
• 組織扇形：從點擊的頭像繪製線條到團隊欄位，鎖扣閉合，虛線輪廓將辦公桌分組（sBook）。
• 檢查清單（範本工具包）：checkbox() 圓形複選框，點擊時下陷、彈出綠色並繪製其勾號； strike(x, y, textW(...) + 8, u) 劃掉標籤；每個複選發送一個 packet() 到一個 progressRing()， 該環在每次到達時緩動一步，並在關閉時發光。一個列表場景包含複選框 + 刪除線 + 封包 + 環 （參見 examples/tidy-tasks/）。

轉場：場景是背對背的。每個場景在其最後 0.5 秒淡出，下一個在其前 0.5 秒淡入， 並帶有 0.985 -> 1 的縮放穩定（透過背景下沉）。第一個場景從實體開始，片尾以其自己的 0.6 秒淡出至 bg 結束。 一個轉場影格故意幾乎空白；不要「修復」它。

保持與閒置動態：每個影格都有東西在移動。使用流動的虛線偏移、呼吸發光（sin(3t)）、 bob() 浮動 3..5 px、慢速旋轉器（60 度/秒）、漂移圖示（18 / 14 px）。在場景的最後一個節拍後至少保持 1.5 秒的 停頓，以便字幕讀完。

複製規則

• 英文字幕，句子大小寫，以句點結尾。一或兩行，每行最多約 48 個字元。
• 螢幕顯示時間（字幕在 0.45..1.05 秒內淡入，在 dur - 0.75 時淡出）必須至少每 4 個字 1 秒，且 永遠不少於 2.5 秒。實際上，一個場景絕不會少於約 5 秒。
• 字幕或畫面上不使用破折號作為標點符號（沒有 em dash、en dash 或空格連字號）。使用逗號和句點。
• 僅限真實陳述。畫面上的數字（客戶、帳戶、間隔）來自使用者或產品，從不虛構。 範本數字標記為 PLACEHOLDER。沒有真實數字（預告片、虛構產品）？將片尾 STATS 設為 純文字，例如 ['Simple lists', 'Daily focus', 'Clear progress']：藥丸彈出而不是計數。
• 無真實客戶資料：無真實姓名、帳號、餘額、電子郵件或客戶的標誌。使用虛構集合。
• 標題和片尾不帶字幕；標語和結束語負責這項工作。

架構

• 一個自包含的 HTML 檔案，無網路連線，無函式庫。SVG 舞台加上一個 IIFE 腳本。
• render(t) 是純函數：它僅從 t 重建 #frame innerHTML。暴露為 window.renderAt(t)， 並附帶 window.TOTAL_DURATION 和 window.SCENES_INFO。如果 URL 中沒有 #manual，它會即時循環。
• SCENES = [{ id, start, dur, fn, cap }]，背對背。將每個條目保持在一行，並按照該鍵順序， 且 const TOTAL = <number>; 作為字面量：compose.py 使用正則表達式解析兩者。
• 場景是 fn(lt, dur) -> { svg, cursor? }，使用本地時間 lt。場景內的所有節拍時間都是本地 常數（click、send(i)、onT(i)），音訊腳本會鏡像這些。
• 輔助函數：數學（clamp lin E EO EB mix f rng fadeIO bob）、SVG（T G R Ci card chip check avatar lock logo wordmark textW）、 圖表（pathFrom walk scalePts spark areaChart bez）、動態（ring statusDot packet press progressRing checkbox strike）、 游標（curPos drawCursor）、caption。當透明度約為 0 時，G() 返回 ''，因此隱藏層是免費的。
• 繪製順序：場景內容、字幕、品牌標記、游標最後。
• const STATS = [...] 保持在一行，並在行的開頭：compose.py 讀取它作為片尾音效。

工作流程

1. 簡報。受眾、產品、3..6 個附真實數字的真實陳述、長度（完整版 60..90 秒，預告片 20..40 秒）、發布位置、 以及主題（house、studio、ember、tide，或一個新的 json）。
2. 分鏡腳本。一個表格，包含場景 ID、持續時間、字幕、視覺隱喻、游標動作和節拍時間。 敘事弧：鉤子（標誌、標語）-> 之前（痛點）-> 每個場景一個功能 -> 片尾（統計或文字藥丸、結束語）。 在建構前根據複製規則檢查字幕時間。
3. 建構。在工作資料夾中，將 SK 設為此技能的 templates 資料夾 （例如 SK=~/.claude/skills/explainer-video/templates）： cp $SK/explainer-template.html explainer.html && cp $SK/compose.py . 永不編輯技能副本。 套用主題：node $SK/apply-theme.mjs --theme <name> --html explainer.html（如果主題是 house 則跳過）。 設定 BRAND，替換範例卡片場景，在標記的區塊中添加場景，更新 starts 和 TOTAL， 設定 STATS。從參考檔案中提取模式。
4. 預覽。在瀏覽器中開啟 HTML（它會循環），然後在每個點擊、著陸和邊界處渲染靜止畫面： node $SK/render.mjs --html explainer.html --stills 3.2,4.9,8.6 --stills-dir critique/v1。
5. 渲染。node $SK/render.mjs --html explainer.html --out name.mp4 寫入 MP4、-poster.png 和 -contact.png。
6. 審查。根據 checklist.md 閱讀連絡表和靜止畫面。每個項目都必須通過；修正，重新渲染，重新審查。
7. 交付。傳送 MP4、連絡表（PNG）、至少一張海報影格，以及 HTML。除非要求，否則不傳送音訊或 compose.py。