code-explainer

---

A film here is a folder of plain files: film.json places clips on tracks, and each motion-graphics scene is a React component animated with GSAP. Because it is code, a coding agent can write it, read its own errors, look at the frames it made and fix them — and you can review the diff.

my-film/code/
├── film.json          the running order: tracks of mg / video / audio clips
├── mg/intro.tsx       a scene — React + GSAP, every frame a pure function of time
├── assets/            footage, images, audio, fonts (yours, or fetched with `anim` commands)
├── skills/            the manuals your agent reads before it writes
└── AGENTS.md          the editor's manual (CLAUDE.md is the same file)

The engine owns the clock. Scenes never run their own timers, so every frame is reproducible: what you see in the preview is exactly what anim render writes to the mp4.

Quick start

Requirements: Node.js 22+ and ffmpeg on your PATH. The first anim check, look or render downloads the headless Chromium every frame is drawn with (via Playwright, about 100 MB, once).

npm install -g animspark
anim new "a 20-second launch video for a note-taking app" --sec 20 --dir notes-launch
cd notes-launch/code

Open the folder in your agent and ask for the film. It reads AGENTS.md and the skills, writes film.json and mg/*.tsx, and checks its own work with anim check and anim look.

While it works, watch the film take shape:

anim preview

anim preview is a timeline player that follows every save: the picture refreshes in place, the timeline re-evaluates, and compile or runtime errors appear with links to the exact line in your editor. It is read-only on purpose — the source is the single place a film changes.

When it's right:

anim render              # → .anim-out/film.mp4

Commands

Every command takes --help.

How a film is made

film.json is the edit. Clips have a start (at), an optional source window (time) and a transform; tracks stack top to bottom.

{
  "stage": { "w": 1920, "h": 1080 },
  "tracks": [
    { "kind": "mg", "clips": [
      { "id": "intro", "src": "mg/intro", "at": 0 },
      { "id": "card",  "src": "mg/card",  "at": 4.2 }
    ] },
    { "kind": "audio", "clips": [
      { "id": "bed", "src": "assets/audio/music/bed.ts", "at": 0, "volume": 0.4 }
    ] }
  ]
}

A scene is a component. Animate with useGSAP; the host drives the timeline, so seeking to any frame gives the same picture.

import { useRef } from 'react';
import { gsap } from 'gsap';
import { useGSAP } from '@gsap/react';

export const durationSec = 4;

export default function Intro() {
  const root = useRef<HTMLDivElement>(null);
  useGSAP(() => {
    gsap.from('.word', { yPercent: 120, stagger: 0.08, duration: 0.9, ease: 'expo.out' });
  }, { scope: root });
  return (
    <div ref={root} style={{ position: 'absolute', inset: 0, display: 'grid', placeItems: 'center', background: '#0b0b10' }}>
      <h1 style={{ fontFamily: 'Inter', fontSize: 140, color: '#fff', overflow: 'hidden' }}>
        {'Write films in code'.split(' ').map((w) => <span key={w} className="word" style={{ display: 'inline-block', marginRight: 32 }}>{w}</span>)}
      </h1>
    </div>
  );
}

Music is code too. assets/audio/music/bed.ts above is a muspark score — chords, arpeggios, drums, a General MIDI soundfont — rendered to audio on your machine. No account, no samples to license.

Fonts from a library of 200+ open-licensed families (Latin, Chinese, Japanese, Korean) load by name — write fontFamily: 'Playfair Display' and the preview and render both fetch it.

Scene libraries ship in the box: formulas, code and scientific plots (@animspark/stem), score views (@muspark/ui), plus three.js, p5, d3, world-atlas and the rest of the allow-listed npm packages — charts and maps are drawn straight with d3, and the skills show how.

Voice, sound effects and images

Everything above runs offline. Some things can't be written as code: narration, sound effects, transcription, stock images. Those are anim commands backed by AnimSpark Cloud — run anim login once with an API key — or by your own provider keys through an open provider interface. See docs/cloud.md.

anim audio voice --language en --prompt "warm, confident narrator"   # pick a voice
anim audio tts --voice <voiceId> --text "Meet Notes. The fastest way to think."
anim audio sfx --prompt "soft UI click" --sec 1

Use with your agent

anim new writes AGENTS.md and CLAUDE.md, so Claude Code, Codex and Cursor pick up the manual on their own. Prefer tools? anim mcp exposes check, look, render and the media commands over MCP. Setup snippets for each agent are in docs/agents.md.

What's in this repository