Holodeck23/video-by-code

程式碼驅動影片技能

一套可執行的工具包與生產流程，專為人類與 AI 代理組成的團隊設計，用於製作確定性的程式碼影片。所有場景程式碼都保留在儲存庫或專案工作區內；所有產出的媒體、音訊、靜態圖與驗證報告則儲存在明確的外部 $PROD 目錄中。

工作順序： 簡報 → 音訊與時序 → 風格與提示 → 3 張設計靜態圖 → 場景程式碼 → 確定性與文字邊界檢查 → 完整渲染 → 驗證與連絡表 → 交付收據

---

1. 環境檢查

在開始製作新影片前，請確保已安裝必要依賴，並從儲存庫根目錄執行 4 秒的煙霧測試：

cd starter && npm ci && cd ..
node tests/runtime-contract.mjs

---

2. 生產目錄與意圖文件（RUNBOOK.md §1–2）

1. 選擇一個程式碼檢出目錄之外的絕對生產目錄：

   PROD="/absolute/path/to/video-outputs/<project-slug>"
   mkdir -p "$PROD"/{audio,analysis,stills,renders,checks}
   

2. 將 templates/brief.md 複製到 "$PROD/brief.md"，並填入目標觀眾、核心訊息、畫面比例（1920x1080 橫式或 1080x1920 直式）、時長、語音/音樂來源以及安全區域邊距。

---

3. 音訊識別與時序（docs/04-music-audio-and-timing.md， docs/05-narration-and-captions.md）

永遠不要根據猜測的時間戳來製作動畫。請先測量實際音訊檔案並記錄其 SHA-256 雜湊值：

uv run tools/timing/audio-identity.py "$PROD/audio/source.wav" \
  --out "$PROD/analysis/identity.json" --copy-wav "$PROD/analysis/analysis.wav"

• 有聲旁白：
  • 使用本地 Kokoro ONNX TTS 合成（合併 < 4 個字的片段，並使用 --say say.json 語音字典）： uv run tools/timing/kokoro-narrate.py script.txt --out-dir "$PROD/audio" --voice af_heart --say say.json
  • 透過本地 whisper-cli 驗證語音音訊的往返正確性： uv run tools/verify/verify-narration.py "$PROD/audio/narration.wav" "$PROD/audio/timing.json"
  • 檢查腳本/歌詞對照參考文字的逐字 n-gram 提昇（lift）： python3 tools/verify/check-lift.py candidate.txt reference.txt
• 音樂 / 歌詞 / 分軌反應式音軌：
  • 透過 Demucs 分離出 6 個音軌（vocals, drums, bass, guitar, piano, other）並歸一化為 44.1 kHz WAV： uv run --python 3.12 tools/timing/separate-stems.py "$PROD/audio/song.mp3" --out-dir "$PROD/analysis"
  • 提取 120 Hz 音軌包絡線、單音音樂時間 tau、節拍/小節相位、靜音區段、features.f32 以及 100 fps 的吉他音高/顫音： uv run --python 3.12 tools/timing/analyze-stems.py "$PROD/analysis" --fps 120 --stem-pitch
  • 對齊單詞級歌詞（使用 whisper-cli、mlx-whisper、faster-whisper 或 acoustic 人聲頻段能量扭曲）： uv run tools/timing/align-words.py "$PROD/analysis/stems/vocals.wav" --script lyrics.txt --backend whisper-cli --out "$PROD/analysis/words.json"
  • 輕量級單檔案提示 / 節拍網格 / 視覺化包絡線：
    • uv run tools/timing/cue-extract.py "$PROD/audio/song.mp3" --out "$PROD/analysis/cues.json"
    • uv run --python 3.12 tools/timing/beat-grid.py "$PROD/analysis/analysis.wav" --out "$PROD/analysis/beats.json"
    • python3 tools/build-visualizer.py "$PROD/analysis/analysis.wav" --out "$PROD/analysis/features.js"

---

4. 風格選擇與提示組合（prompts/README.md）

瀏覽 prompts/styles/INDEX.md（86 種已撰寫的視覺風格卡片，橫跨 13 個系列）與 prompts/briefs/（5 種格式簡報：explainer-voiceover、vertical-short、lyric-video、instrumental-visualizer、data-story）。

組合您所選風格與簡報的完整規範：

python3 tools/build-prompt.py <style-id> --brief <brief-id> --out "$PROD/style-prompt.md"

---

5. 場景編寫合約（lib/API.md、docs/06-building-scenes.md、docs/12-advanced-engines-and-benchmarks.md）

每個場景的 HTML 頁面都載入 lib/harness.js（window.H）並可選地載入：

• lib/sound.js（window.SOUND）— 程序化 Web Audio 合成
• lib/features.js（window.FEATURES）— 120 Hz 二進制 features.f32 音軌游標、耐火起始脈衝、單音 tau(t) 與 words.json 歌詞查詢
• lib/ink-doodle.js（window.INK）— 8 fps 確定性線條沸騰、搖擺塗鴉基本元件、左對齊全大寫書寫 marker，以及 Ken Burns plate 攝影機
• lib/webgl-post.js（createPost）— 4 階段 Three.js 後製處理（FxOverShader、UnrealBloomPass、FinalGradeShader 搭配 ACES / paperMode、僅亮度衝擊反轉、故障、抖動、顆粒感與清晰 UI 疊層）

每個頁面都公開：

• <canvas id="c" width="1920" height="1080"></canvas>（或直式則為 1080 × 1920）
• window.DURATION（秒）與 window.FPS（預設 30）
• window.__ready（字型與快取離屏底圖準備就緒後 resolve 的 Promise）
• window.__renderFrame = (t) => { ... } — t 以秒為單位的純函數。
  • 每個影格以 ctx.reset()（或平衡的 save() / restore()）開始。
  • 在影格迴圈外部使用 H.rng(seed) 與 H.noise(seed)；永遠不要在影格之間推進可變狀態。
  • 透過 H.paperTexture(...) 或 H.offscreen(key, w, h, fn) 快取紙張/表面紋理一次。
  • 公開 window.__textBounds = () => [...] 以取得故事關鍵文字（{text, critical: true, left, right, top, bottom}），讓自動化安全區域檢查可以驗證每個影格。
• window.scoreSound = (k) => { ... } — 在固定時間軸時間點排程程序化聲音事件（當提供 --voice 時會自動抑制背景音樂/音軌）。

測試中的關鍵生產規則

• 安全區域邊距與字重： 在 macOS Chrome 上，Arial 僅提供 400 與 700 字重（600 會 snap 到 700 粗體並使行寬增加約 9%）。務必在所有影格上審核 measureText(s).actualBoundingBox*（1080x1920 直式短片的範圍為 x: 80..960, y: 190..1640）。
• 連續攝影機風格（transit-map、pan-and-zoom）： 在 beat[i].start 開始攝影機插值（當 i 在 beat[i].start 切換時，切勿使用 beat[i].start - preRoll，這會導致 1 影格跳躍），在 0.20 秒 內淡出節拍局部疊層，並保護世界空間標籤，使其僅在裁剪後的地圖視口內繪製。

---

6. 渲染靜態圖、檢查確定性與渲染主影片（docs/07-rendering.md）

1. 尋找確定性檢查點：

   node starter/determinism.mjs path/to/film.html
   

2. 設計靜態圖檢查點（在完整渲染前檢查開頭、密集中間與結尾影格）：

   node starter/render.mjs path/to/film.html --stills 1.5,12.0,24.0 --outdir "$PROD/stills"
   

3. 完整 MP4 渲染：
   • 參考用單工作 Playwright 渲染器（預設 30 fps Canvas2D + 程序化音訊）：

     node starter/render.mjs path/to/film.html \
       --out "$PROD/renders/master.mp4" --fps 30 --audio page \
       --voice "$PROD/audio/narration.wav"
     

   • 多工作 GPU WebSocket 渲染器（60 fps Three.js / WebGL / 動態排版）：

     node tools/render/parallel-ws-render.mjs \
       --url "http://127.0.0.1:5173/?capture=1" --duration <DURATION> --fps 60 --workers 4 \
       --audio "$PROD/analysis/analysis.wav" --out "$PROD/renders/master.mp4"
     

   • 無瀏覽器 Python + Pillow rawvideo 渲染器（含字幕的工作簿與教學）：

     uv run tools/render/workbook-render.py \
       --spec workbook.json --audio "$PROD/audio/narration.wav" --out-dir "$PROD/renders"
     

---

7. 強制驗證檢查點（docs/08-verification.md）

每個生產流程都必須執行並將以下檢查記錄在 "$PROD/checks/" 中，然後才能交接：

1. 串流、解碼、同步與音量檢查點：

   uv run tools/verify/verify-video.py "$PROD/renders/master.mp4" \
     --expect-seconds <DURATION> --fps 30 --width <W> --height <H> \
     --json "$PROD/checks/verify-video.json"
   

2. 連絡表視覺檢查：

   uv run tools/verify/contact-sheet.py "$PROD/renders/master.mp4" \
     "$PROD/checks/contact-sheet.jpg" --n 16 --cols 4 --tile-width 270
   

   目視檢查 contact-sheet.jpg 與場景靜態圖，確認無文字裁切、標籤重疊或非預期的空白/凍結影格。
3. 轉場與剪輯流暢度審計：

   uv run tools/verify/cut-harshness.py "$PROD/renders/master.mp4" \
     --top 15 --json "$PROD/checks/cut-harshness.json"
   

4. 外觀與色板診斷：

   uv run tools/verify/measure-look.py "$PROD/renders/master.mp4" \
     --samples 16 --json "$PROD/checks/measure-look.json"
   

5. 全影格文字邊界審計： 遵循 tests/layout.mjs 中的模式，驗證 fillText 文字邊界與 window.__textBounds() 在 0 .. frames-1 的每個影格上。

---

8. 打包與交付（RUNBOOK.md §12）

完成 "$PROD/qa.md"（來自 templates/qa.md）與 "$PROD/delivery.md"（來自 templates/delivery.md）。將機器驗證結果（PASS / WARN 處置）與人類創意觀看及聆聽核准結果分開報告。

主要參考資料

• README.md — 快速入門與章節索引
• RUNBOOK.md — 12 步驟人機協作生產檢查清單
• lib/API.md — 精確的 H 圖形與 SOUND 程序化音訊合約
• examples/README.md — 已完成的作品範例（橫式、直式與風格研究）
• docs/10-pitfalls.md — 症狀 → 原因 → 修復對照表