Code Animation Studio (Code Animation)
Turns an abstract concept into a 1–2 minute animated short. Not generative video — every frame is a vector graphic calculated in the browser, reproducible frame-by-frame and locally editable.
The output is an MP4 file, plus a reusable storyboard.json.
Three-Step Process
# 1. Validate the storyboard
python scripts/lint.py storyboard.json
# 2. Build + Render (approx. 0.5 sec/frame)
python scripts/build.py storyboard.json out.html
python scripts/render.py --html out.html --duration 117 --fps 30 --out film.mp4
# 3. Quality check, returns non-zero if below thresholds
python scripts/measure.py film.mp4 --thresholds reference/thresholds.json
If the check fails, fix it. Don't rely on "looks okay."
Add a Soundtrack (Optional, but Highly Recommended)
The audio is also computed — no sampled material libraries, just like the visuals.
# 1. Compose a soundtrack (numpy, about 40 seconds)
python scripts/make_audio.py score.wav --storyboard storyboard.json
# 2. Mux into the video, also transcode to H.264 to reduce size
python scripts/mux.py --video film.mp4 --audio score.wav --out final.mp4 --crf 23
Default soundtrack is for space/physics themes: D minor drone, chord-changing pad per scene, an 8-second heartbeat pulse, sparse plucks, noise sweeps on transitions, and low-frequency hits at chapter markers.
Change the soundtrack parameters when changing themes, don't just reuse them:
| Theme | Soundtrack Modification |
|---|---|
| Physics / Astronomy | Keep defaults: minor, drone, sparse |
| Mathematics / Algorithms | Switch to major or Lydian mode, add some arpeggios |
| History / Humanities | Remove pulse, slow down pad, add some dissonant intervals |
| Product / Tech | Remove pad drone, change to a 90–110 BPM synth groove |
Parameters are in make_audio.py at the top: SCALE, ROOT, bpm, and the chords array in build().
storyboard.json
{
"title": "Gravity",
"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, "In 1687, Newton tied the apple and the moon together with one formula."],
[7.4, "Gravity is proportional to mass and inversely proportional to the square of distance."]
]
}
]
}
| Field | Description |
|---|---|
kind | Shot template name, see table below |
dur | Duration of this shot (seconds), recommended 12–20 |
chapter | [number, native, ENGLISH], persistent in top-left corner |
subs | Array of [start_second, text]; each subtitle should stay 5–6 seconds |
cn / en | Used for title-type shots |
Shot Templates (8)
| kind | Visual | Use Case |
|---|---|---|
title | Large text + small English subtitle | Opening |
outro | Two lines of conclusion | Ending |
orbit | Elliptical orbit + polar grid | Periodic motion, gravity |
precess | Precessing flower petal line + angle dial | Tiny deviations, precession |
elevator | Box with internal ruler | Reference frames, equivalence principle |
warp | Perspective spacetime grid + leader lines | Curvature, fields |
evidence | Concentric lens rings + chirp waveform | Evidence, signals |
blackhole | Accretion disk + photon ring + circular scale | Extreme celestial bodies |
Template parameters are in templates/shots/*.json.
Six-Layer Architecture (Why It's Ordered This Way)
L5 Post-processing bloom → vignette → grain
L4 Text Chapter label / large text / formulas / subtitles
L3 Annotations Leader lines + small labels + readout boxes
L2 Subject Core graphic of this shot
L1 Structure Grids / scales / coordinate axes
L0 Background Nebula / dot field / dust / distant stars
L1 and L3 are the source of "professional feel," not L2. A scene with only the subject looks bare; adding the structure and annotation layers instantly turns the same graphic into an "instrument interface."
base.html already implements all six layers; new shots only need to write the drawing function for L2.
Acceptance Thresholds
reference/thresholds.json:
{
"frame_diff_min": 1.5,
"moving_ratio_min": 0.70,
"coverage_min": 0.20,
"luma_range": [16, 30]
}
| Metric | Meaning | Why |
|---|---|---|
frame_diff | Average difference between consecutive frames | Below 1.5 it's a "slideshow," not an animation |
moving_ratio | Percentage of frames with motion | Below 70% it feels "stuck" |
coverage | Percentage of pixels with local structure | Below 20% the frame looks empty |
luma | Average brightness | Below 16, structure is lost in black; above 30, the dark tone is lost |
These thresholds are calibrated from real reference footage. Do not adjust them casually. See reference/findings.md for details.
Known Pitfalls (Learned the Hard Way)
1. Never use ctx.shadowBlur.
Multiple shadows per frame in software rendering will slow a single frame from 20ms to 5 seconds. Use bloom() from base.html — scale the canvas down to 1/6, then scale up and composite, two drawImage calls, nearly free.
2. Parameters must be from the same source.
There was once a bug where "the particle was running outside the path": the line was calculated with p², but the point was calculated with p. The path and the head of the same element must be driven by the same variable.
3. Grain determines file size. Per-frame random noise has very high entropy, and video encoders struggle to compress it. At grain α=0.03, 1080p30 is about 50KB/frame — a two-minute movie is about 300MB. To reduce size, lower α (around 0.015) or reduce the frame rate. Don't rely on the encoder.
4. Use JPEG for frames, not PNG. Encoding time for PNG with grain is over 4x that of JPEG (measured: 2.0s/frame vs 0.5s/frame).
5. Brightness is not a filter.
Don't use CSS brightness() to lighten — it will blow out the text along with everything else. To lighten, increase the alpha of content layers (grid, nebula, dust), following the proportions in reference/palette.json.
Extending with New Shots
- Add a
caseindrawScene()inbase.html - Only write L2 (the subject); use
polarGrid,ringTicks,axisTicks,drawInstrumentfor L1, anddrawLeaderfor L3 - Extract adjustable parameters into a parameter object, save to
templates/shots/<name>.json - Run
measure.py; all three metrics must pass for completion
Example
examples/gravity.storyboard.json — the complete storyboard for the two-minute film "Gravity," with all eight shots ready to use. Can serve as a starting point with modified text.