Communitygithub.com

代碼動畫工坊

將抽象概念製作成 1–2 分鐘的動畫短片。**非生成式影片**——每一幀都在瀏覽器中以向量方式計算,可逐幀重現、可局部修改。

代碼動畫工坊 是什麼?

這是一個以程式碼驅動的動畫技能,專為科普與技術演示設計。它能根據故事大綱產生結構化的 `storyboard.json`,並經由瀏覽器渲染管道(build + render)產出 MP4 影片。整個流程包含自動化校驗(lint)、渲染(以約 0.5 秒/幀的速度)、與可量化指標的品質檢查(measure),確保動畫不淪為「投影片」。可選的配樂生成功能同樣以純程式方式合成(numpy),不依賴任何素材庫。 此技能支援 8 種鏡頭模板(如軌道、進動、電梯、彎曲時空等),並採用六層渲染架構(背景、結構、主體、標註、文字、後期),以強化畫面的專業感。它特別適用於物理、數學、歷史人文或產品技術等主題的動畫創作,並提供詳盡的已知陷阱清單(如影子模糊、參數不一致、顆粒壓縮等)與擴展新鏡頭的指引。 支援的平台概念上包括任何可執行 Python 與瀏覽器渲染的環境(如 Claude Code、Cursor、Codex),但本技能設計為獨立命令列工具,不限定特定代理平台。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Shang-en-yee/code-animation-skill/tree/HEAD

在你喜歡的 AI 中提問

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

說明文件

代碼動畫工坊(Code Animation)

把一個抽象概念做成 1–2 分鐘的動畫短片。不是生成式影片——每一幀都是瀏覽器裡算出來的向量畫面,可逐幀重現、可局部修改。

產物是一個 MP4,加一份可複用的 storyboard.json。


三步流程

# 1. 校驗分鏡
python scripts/lint.py storyboard.json

# 2. 建構 + 渲染(約 0.5 秒/幀)
python scripts/build.py storyboard.json out.html
python scripts/render.py --html out.html --duration 117 --fps 30 --out film.mp4

# 3. 品檢,不達標會回傳非零
python scripts/measure.py film.mp4 --thresholds reference/thresholds.json

品檢不過就改,不要靠「看起來還行」驗收。

加配樂(可選,但強烈建議)

音訊同樣是算出來的,不取樣任何素材庫——和畫面一個道理。

# 1. 合成配樂(numpy,約 40 秒)
python scripts/make_audio.py score.wav --storyboard storyboard.json

# 2. 合進影片,順便轉 H.264 壓體積
python scripts/mux.py --video film.mp4 --audio score.wav --out final.mp4 --crf 23

預設配樂是太空/物理題材的底:D 小調長音鋪底 + 每鏡換和弦的 pad + 8 秒一次的心跳脈衝 + 稀疏撥弦,轉場處有雜訊掃頻、章節處有低頻落點。

換題材時要換配樂參數,不要直接套:

題材配樂改法
物理 / 天文保留預設:小調、長音、稀疏
數學 / 演算法換成大調或里底亞調式,加一點規律性的琶音
歷史 / 人文去掉脈衝,pad 變慢,加一點不和諧音程
產品 / 技術去掉 pad 長音,改成 90–110 BPM 的合成器律動

參數都在 make_audio.py 頂部的 SCALE / ROOT / bpm 三個常數,和 build() 裡的 chords 陣列。


storyboard.json

{
  "title": "引力",
  "fps": 30,
  "palette": { "bg": "#08090F", "ink": "#E6DCCB", "dim": "#8A8177", "accent": "#E0813C" },
  "scenes": [
    {
      "id": "open",
      "kind": "title",
      "dur": 6.0,
      "cn": "引力",
      "en": "GRAVITY"
    },
    {
      "id": "newton",
      "kind": "orbit",
      "dur": 16.0,
      "chapter": ["I", "蘋果與月亮", "THE APPLE AND THE MOON"],
      "subs": [
        [0.6,  "1687 年,牛頓用一個公式,把蘋果和月亮綁在了一起。"],
        [7.4,  "引力與質量成正比,與距離的平方成反比。"]
      ]
    }
  ]
}
欄位說明
kind鏡頭模板名,見下表
dur該鏡時長(秒),建議 12–20
chapter[序號, 中文, ENGLISH],左上角常駐
subs[起始秒, 文字] 陣列;每螢幕逗留 5–6 秒為宜
cn / en標題類鏡頭用

鏡頭模板(8 個)

kind畫面適用
title大字 + 英文小標開篇
outro兩行結論落版
orbit橢圓軌道 + 極座標網格週期運動、引力
precess進動花瓣線 + 角度盤微小偏差、進動
elevator方框 + 內部刻度參照系、等效原理
warp透視時空網格 + 引線標註彎曲、場
evidence透鏡同心環 + 啁啾波形證據、訊號
blackhole吸積盤 + 光子環 + 環形刻度極端天體

模板參數見 templates/shots/*.json。


六層架構(為什麼這麼排)

L5 後期    bloom → 暗角 → 顆粒
L4 文字    章節標 / 大字 / 公式 / 字幕
L3 標註    引線 + 小標籤 + 讀數框
L2 主體    本鏡核心圖形
L1 結構    網格 / 刻度 / 座標軸
L0 背景    星雲 / 點陣 / 塵埃 / 遠星

L1 和 L3 是「專業感」的來源,不是 L2。一個只有主體的畫面會顯得簡陋;加上結構層和標註層,同一張圖立刻變成「儀器介面」。

base.html 已經實現全部六層,新鏡頭只要寫 L2 的繪製函數。


驗收閾值

reference/thresholds.json:

{
  "frame_diff_min": 1.5,
  "moving_ratio_min": 0.70,
  "coverage_min": 0.20,
  "luma_range": [16, 30]
}
指標含義為什麼
frame_diff相鄰影格平均差低於 1.5 就是「幻燈片」,不是動畫
moving_ratio有運動的幀佔比低於 70% 會有「卡住」感
coverage有局部結構的像素佔比低於 20% 畫面顯得空
luma平均亮度低於 16 時結構全沉在黑色裡;高於 30 會丟掉暗調基調

這些閾值是用真實參考片校準出來的,別隨便調高。 詳見 reference/findings.md。


已知坑(血淚)

1. 永遠不要用 ctx.shadowBlur。 軟體渲染下幾十處逐幀陰影會把單幀從 20ms 拖到 5 秒。用 base.html 裡的 bloom() —— 畫布縮到 1/6 再放大疊加,兩次 drawImage,幾乎免費。

2. 參數必須同源。 曾經出現過「質點跑在線外面」的 bug:線用 p² 算,點用 p 算。同一元素的路徑和頭部必須由同一個變數驅動。

3. 顆粒決定檔案大小。 逐幀隨機雜訊熵極高,影片編碼器壓不動。顆粒 α=0.03 時 1080p30 約 50KB/幀——兩分鐘片子約 300MB。 要小就降 α(0.015 左右)或降幀率,別指望編碼器。

4. 幀格式用 JPEG,不要 PNG。 帶顆粒的 PNG 編碼耗時是 JPEG 的 4 倍以上(實測 2.0s/幀 vs 0.5s/幀)。

5. 亮度不是濾鏡。 不要用 CSS brightness() 提亮——會把文字一起吹白。要提亮就提內容層的 alpha(網格、星雲、塵埃),按 reference/palette.json 的配比來。


擴展新鏡頭

  1. 在 base.html 的 drawScene() 裡加一個 case
  2. 只寫 L2(主體);L1 用 polarGrid / ringTicks / axisTicks / drawInstrument,L3 用 drawLeader
  3. 把可調項抽成參數物件,存到 templates/shots/<name>.json
  4. 跑 measure.py,三個指標達標才算完成

例子

examples/gravity.storyboard.json —— 兩分鐘成片《引力》的完整分鏡,八個鏡頭全部實拍可用。可作為起點直接改文案。

相關技能