# Motion Diagram

Agent-driven animated diagram renderer. Turn an API/flow/architecture description
into an **animated MP4** (glowing pulses traveling edges, node pops, camera focus,
8-bit sfx) or an **Instagram-style carousel** (silent GIF + WebP slides).

Built for content creators. Designed to be driven by an AI agent over **MCP** —
the agent designs the scene, this tool renders it.

## Showcase

| Pendulum simulation                                        | Fourier graph approximation                       |
| ---------------------------------------------------------- | ------------------------------------------------- |
| [Download MP4](assets/showcase/pendulum.mp4)               | [Download MP4](assets/showcase/fourier-graph.mp4) |
| Formula overlay, velocity vector, deterministic simulation | Safe `sin(x) + sin(3x)/3 + sin(5x)/5` graph trace |

Source scenes: [`examples/pendulum-math.json`](examples/pendulum-math.json), [`examples/fourier-graph.json`](examples/fourier-graph.json).

## Stack

- Remotion (React → MP4 via headless Chrome + ffmpeg)
- dagre (auto-layout)
- ffmpeg (sfx synthesis, GIF→WebP)
- MCP SDK (agent interface)

## Install

```bash
# one-off, no install
npx motion-diagram render examples/login-flow.json -- --out login.mp4

# or global
npm install -g motion-diagram

# or from a clone
npm install
```

Check prerequisites (Node >=18, ffmpeg, deps):

```bash
npx motion-diagram doctor
```

First render downloads a headless Chrome (~once). Full guide: `docs/INSTALL.md`.

## CLI

```bash
# video (MP4 + sfx)
npm run render examples/login-flow.json -- --out output/login-flow.mp4

# carousel (GIF + WebP per node group)
npm run render examples/login-flow.json -- --mode carousel --out output/login-carousel

# live preview studio
npm run studio
```

## Scene JSON

Agent emits nodes, edges, and a timeline. See `docs/SCHEMA.md`.

```jsonc
{
  "meta": { "title": "Login Flow", "fps": 30, "width": 1920, "height": 1080 },
  "nodes": [
    { "id": "client", "label": "Client", "shape": "rect", "icon": "user" },
    { "id": "api", "label": "API", "shape": "rect", "icon": "server" },
    { "id": "db", "label": "DB", "shape": "stadium", "icon": "database" },
  ],
  "edges": [
    { "id": "e1", "from": "client", "to": "api", "label": "POST /login" },
    { "id": "e2", "from": "api", "to": "db", "label": "query" },
  ],
  "timeline": [
    { "at": 0, "type": "reveal-node", "target": "client" },
    { "at": 8, "type": "reveal-node", "target": "api" },
    { "at": 16, "type": "reveal-node", "target": "db" },
    { "at": 24, "type": "reveal-edge", "target": "e1" },
    { "at": 42, "type": "reveal-edge", "target": "e2" },
    {
      "at": 60,
      "type": "pulse",
      "edge": "e1",
      "color": "#38bdf8",
      "onArrive": { "flash": true, "sfx": "beep" },
    },
    {
      "at": 95,
      "type": "pulse",
      "edge": "e2",
      "color": "#34d399",
      "onArrive": { "flash": true, "sfx": "ding" },
    },
  ],
}
```

## Motion primitives

| type          | effect                                              |
| ------------- | --------------------------------------------------- |
| `reveal-node` | node pops in (spring scale + fade)                  |
| `reveal-edge` | edge draws like a pen                               |
| `pulse`       | glowing comet travels edge (data flow), multi-color |
| `flash`       | node glow burst                                     |
| `camera`      | pan/zoom focus to a node                            |

## Sound

Bundled 8-bit sfx in `public/sfx/`: `beep`, `whoosh`, `ding`. Chosen **per event**
by the agent (`sfx` / `onArrive.sfx`), or `none`. Swap the WAV files to rebrand.

## Icons

`user client server api database cloud queue cache lock key gear bolt globe
mobile mail file check cross warning`

## MCP + skill install (for AI agents)

Motion Diagram is designed to be driven by an AI agent over MCP. Install the
skill into your agent with one command:

```bash
# auto-detect installed agents and register the MCP server
npx motion-diagram install-skill

# or target a specific client
npx motion-diagram install-skill --client cursor
npx motion-diagram install-skill --client claude
npx motion-diagram install-skill --client pi
```

This writes a `motion-diagram` entry into each agent's MCP config:

| Agent          | Config file                                    |
| -------------- | ---------------------------------------------- |
| Cursor         | `~/.cursor/mcp.json`                           |
| Claude Desktop | `claude_desktop_config.json` (OS-specific dir) |
| Pi             | `~/.pi/agent/mcp.json`                         |

Installing the npm package also runs this automatically (`postinstall`), so a
plain `npm install -g motion-diagram` registers the skill for any detected agent.
Restart your agent afterward to load the tools.

### Manual config

Any MCP client works — point it at the `motion-diagram-mcp` command:

```json
{
  "mcpServers": {
    "motion-diagram": {
      "command": "npx",
      "args": ["-y", "motion-diagram-mcp"]
    }
  }
}
```

Run the server directly for debugging:

```bash
npx motion-diagram-mcp        # or, from a clone: npm run mcp
```

Tools:

- `get_scene_schema` — call first, returns authoring contract
- `render_motion_diagram` — scene → MP4
- `render_carousel` — scene → GIF/WebP slides (by node `group`)
- `render_math_visualizer` — formula, function graph, or pendulum simulation → MP4

Math authoring: `docs/MATH_SCHEMA.md`. Agent guidance: `skills/math-visualizer/SKILL.md`.

Agent guidance: `docs/AGENT_SKILL.md`. Contributing: `CONTRIBUTING.md`.

## Project layout

```
src/core/    parser, layout (dagre), timeline normalizer
src/scenes/  Remotion components (node, edge, pulse, composition, root)
src/render/  MP4 + carousel render orchestration
src/cli/     CLI entry
src/mcp/     MCP server
public/sfx/  bundled 8-bit sounds
docs/        SPEC, SCHEMA, AGENT_SKILL
examples/    sample scenes
```

```

```