代碼動畫工坊(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 的配比來。
擴展新鏡頭
- 在
base.html的drawScene()裡加一個case - 只寫 L2(主體);L1 用
polarGrid/ringTicks/axisTicks/drawInstrument,L3 用drawLeader - 把可調項抽成參數物件,存到
templates/shots/<name>.json - 跑
measure.py,三個指標達標才算完成
例子
examples/gravity.storyboard.json —— 兩分鐘成片《引力》的完整分鏡,八個鏡頭全部實拍可用。可作為起點直接改文案。