spiritual-dev/explainer-short

explainer-short 是做什麼的？

製作短版直式說明影片：講者位於下半部，動態圖形位於上半部，大型字幕晶片位於中間。一個片段只傳達一個想法。主題代碼控制顏色、字型、圓角與動態效果，讓同一份腳本可以呈現溫暖、單色、高對比或活潑等不同風格。

使用時機

• 8 至 30 秒的直式教學或產品說明影片
• 可重複使用的 HTML/Canvas 渲染管線，匯出 MP4
• 無需重寫場景程式碼即可更換視覺主題

版面配置

+---------------------------+
|   動態圖形 / 卡片 (1080)   |
|                           |
|---------------------------|  <- 字幕晶片位於交界處
|   講者畫面裁切 (960)       |
|                           |
+---------------------------+
         1080 x 1920

主題系統

主題檔案存放於 template/themes/*.json（以及示範用的 sample/themes/）。作用中的主題為專案資料夾中的 theme.json。

bash template/scripts/use-theme.sh warm          # 或 mono | high-contrast | playful
# 若從已複製的專案執行：
bash scripts/use-theme.sh mono

載入主題後可用的 CSS 變數：

代碼	角色
--ink --mute	文字
--bg --bg-hi --bg-lo	舞台背景
--surface --surface-2	卡片
--accent --accent-2 --accent-3	強調色
--chip-bg --chip-fg	字幕晶片
--radius-card --radius-chip --chip-size	形狀
--headline-weight	標題字重
--font-sans --font-mono	字型（OFL 授權 woff2，置於 fonts/）

預設主題：warm（預設）、mono、high-contrast、playful。

編輯 JSON 檔案，重新執行 use-theme.sh，重新載入即可。主題本身無需建置步驟。

字型更換

1. 將開放授權的 woff2 放入 fonts/，並將授權檔案置於其旁。
2. 在主題 JSON 中設定 fonts.sans / fonts.sans_file（以及 mono）。
3. 若字型家族名稱變更，請在 index.html 中將 @font-face 指向新檔案。
4. 重新渲染一個中間幀的靜止畫面並確認。

內建預設字型：Inter + JetBrains Mono（SIL OFL）。授權文字隨附於 fonts/。

快速開始（主題展示，無需講者錄影）

npm install
node scripts/render_sample.mjs warm
node scripts/render_sample.mjs mono
# 輸出：sample/out/<preset>/<preset>.mp4 + 幀靜止畫面

需求：Node 18+、系統 Chrome 或 Chromium、ffmpeg。

完整專案管線（自含式）

1. 將 template/ 複製到新專案資料夾（或在 sample/ 內工作）。
2. 在 main.js 中編寫場景，呼叫 window.render(t) 並使用主題中的 CSS 變數。
3. 可選講者錄影：放入錄影檔案，填寫 src/edit.json，執行 python3 src/edit.py（需 numpy + soundfile），再執行 python3 src/captions.py。
4. 從技能根目錄（執行 npm install 後）：

PRESET=warm bash template/build.sh
# 或是在已複製的專案中：
SKILL_ROOT=/path/to/explainer-short PRESET=mono bash build.sh
# 或直接呼叫渲染器：
node scripts/render.mjs --dir path/to/project --preset warm --out path/to/project/out/video.mp4

5. 若 out/voice.wav 存在，執行 python3 mix.py 可將響度正規化至 -14 LUFS / -1 dBTP，build.sh 會自動混音。

template/scripts/render.mjs 也會被複製到樣板旁，讓專案保留一份本地副本。

設計原則

1. 單一想法。 一個物件、一個承諾，在結尾前兌現。
2. 手臂長度即可閱讀。 大字型、高對比、畫面上文字精簡。
3. 字幕晶片就是聲音。 保持提示簡短；最後一個字短暫停留。
4. 使用主題，不要硬編碼。 顏色、圓角與晶片大小皆來自代碼。
5. 品味中立的預設。 溫暖為預設主題；使用者自行選擇預設集。

發布前審查

每個面向評分 0-3 分。僅在平均分數至少 2.3 時發布。由獨立審查員測量主要檔案。

面向	檢查項目
停留	最後字幕停留約 0.3-0.5 秒；不可在單字中間切斷
響度	約 -14 LUFS 整合值（使用 ffmpeg loudnorm 測量）
真峰值	<= -1 dBTP
封面	結束幀或 thumbnailOffset 成為清晰的標題卡片
主題	套用代碼；無遺留硬編碼的品牌顏色
清晰度	陌生人在無音訊下能理解重點

完整評分表：references/review-rubric.md。安全區域：references/cover.md。

檔案

路徑	角色
package.json	宣告 playwright-core
template/	起始專案（HTML、主題、字型、build.sh）
template/themes/	預設主題 JSON
template/theme.js	loadTheme() -> 在 :root 上設定 CSS 變數
sample/	自含式 12 秒主題展示
scripts/render.mjs	無頭幀渲染 + ffmpeg 混流
scripts/render_sample.mjs	展示預設集的便利包裝器
references/	結構、主題、審查評分表、封面、完成
docs/	來自已驗證執行的預覽靜止畫面

代理檢查清單

• 在技能根目錄執行 npm install
• 已選擇主題預設集（或使用預設 warm）
• theme.json 與預設集相符
• 場景使用 CSS 變數，而非硬編碼的品牌顏色
• 樣本或完整建置產出 MP4
• ffprobe 確認解析度為 1080x1920 且時長符合預期
• 中間幀靜止畫面符合預設集的品牌調性
• 有音訊時，響度約 -14 LUFS 且真峰值 <= -1 dBTP
• 審查評分表平均分數 >= 2.3
• 專案中無遺留個人或第三方品牌元素