Communitygithub.com

Code Animation Skill

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.

What is Code Animation Skill?

This skill, Code Animation, enables AI agents to automatically create concise 1–2 minute animated explanatory videos for abstract concepts. Unlike generative AI video, it produces vector graphics calculated in the browser, with every frame being fully reproducible and editable. The process involves validating a storyboard JSON, building and rendering the animation into an MP4 video, and passing quality checks using specific measurement thresholds. It supports optional procedural audio composition that adapts to the topic (e.g., physics, math, history). With 8 predefined shot templates covering common scientific and mathematical visualization needs (e.g., orbits, warped spacetime, black holes) and a six-layer rendering architecture separating background, structural elements, main subject, annotations, text, and post-effects, this skill ensures professional-looking results. The skill is platform-agnostic, relying on Python scripts (`lint.py`, `build.py`, `render.py`, `make_audio.py`, `measure.py`) and an HTML engine (`base.html`). Key known pitfalls are documented, such as avoiding `ctx.shadowBlur`, maintaining parameter consistency, controlling file size via grain, using JPEG over PNG for frames, and not using CSS brightness for luminance adjustments.

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

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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:

ThemeSoundtrack Modification
Physics / AstronomyKeep defaults: minor, drone, sparse
Mathematics / AlgorithmsSwitch to major or Lydian mode, add some arpeggios
History / HumanitiesRemove pulse, slow down pad, add some dissonant intervals
Product / TechRemove 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."]
      ]
    }
  ]
}
FieldDescription
kindShot template name, see table below
durDuration of this shot (seconds), recommended 12–20
chapter[number, native, ENGLISH], persistent in top-left corner
subsArray of [start_second, text]; each subtitle should stay 5–6 seconds
cn / enUsed for title-type shots

Shot Templates (8)

kindVisualUse Case
titleLarge text + small English subtitleOpening
outroTwo lines of conclusionEnding
orbitElliptical orbit + polar gridPeriodic motion, gravity
precessPrecessing flower petal line + angle dialTiny deviations, precession
elevatorBox with internal rulerReference frames, equivalence principle
warpPerspective spacetime grid + leader linesCurvature, fields
evidenceConcentric lens rings + chirp waveformEvidence, signals
blackholeAccretion disk + photon ring + circular scaleExtreme 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]
}
MetricMeaningWhy
frame_diffAverage difference between consecutive framesBelow 1.5 it's a "slideshow," not an animation
moving_ratioPercentage of frames with motionBelow 70% it feels "stuck"
coveragePercentage of pixels with local structureBelow 20% the frame looks empty
lumaAverage brightnessBelow 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

  1. Add a case in drawScene() in base.html
  2. Only write L2 (the subject); use polarGrid, ringTicks, axisTicks, drawInstrument for L1, and drawLeader for L3
  3. Extract adjustable parameters into a parameter object, save to templates/shots/<name>.json
  4. 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.

Related Skills