Wing900/ManimCat

What is ManimCat?

ManimCat is a web‑based, AI‑assisted workspace for creating mathematical visualisations. It lets you type a natural‑language prompt (e.g. "show a geometric proof of the series 1/4+1/16+…") and, behind the scenes, an LLM designs a scene, writes the appropriate Manim (animation) or matplotlib (static plot) code, runs the code, and returns a video or image that you can embed in a lesson.

The system works in two main ways:

Mode	When you’d use it	What it does
Workflow mode	You just want a quick picture or short video.	A single request is sent to an LLM, the generated code is rendered, and the result is streamed back to the UI.
Agent (Studio) mode	You need an interactive, multi‑step session –‑ refining a visual, reviewing renders, or building a series of related figures.	A long‑lived “studio” session keeps state (tasks, runs, results). You can iterate, ask the agent to modify code, approve renders, and organise work in a dedicated workspace.

Both modes support two rendering engines:

• Manim Community Edition – for timeline‑based animations.
• matplotlib – for static charts and teaching figures (the “Plot Studio”).

---

How it works (high‑level architecture)

User (browser) ──► React UI (Vite + Tailwind) ──► Express/TS backend
                                            │
                                            ├─► Bull + Redis queue
                                            │   (job scheduling, retries)
                                            ├─► OpenAI‑compatible LLM API
                                            │   (scene design → code generation)
                                            └─► Python runtime
                                                ├─► Manim CE (animation)
                                                └─► matplotlib (static)

• Frontend – a modern React app (React 19, Vite) that shows classic generation UI, the Studio workspace, and Plot Studio tools.
• Backend – Node/Express services that accept generation requests, push jobs to a Redis‑backed Bull queue, and stream status updates via Server‑Sent Events.
• Rendering – a Python container runs Manim or matplotlib, compiles LaTeX, and uses ffmpeg to produce video/audio files.
• State & persistence – optional Supabase tables can store session history; otherwise everything lives in memory/Redis.
• Deployment – Docker (or Docker Compose) works locally; a single‑container image (wingflow/manimcat) can be deployed to Hugging Face Spaces.

---

Getting started quickly

# Clone and install the Node side
npm install
cd frontend && npm install

# Run locally (frontend + backend)
npm run dev   # opens http://localhost:3000

If you prefer Docker:

docker pull wingflow/manimcat
docker run -p 7860:7860 wingflow/manimcat

The UI will let you type a prompt, choose video or image, and watch the generation progress.

---

Who might find this useful?

• Teachers & educators who want custom, on‑the‑fly math animations without writing Manim code.
• Students looking for visual explanations of concepts they type in.
• Content creators (YouTubers, MOOCs) who need a fast way to prototype math‑heavy visuals.
• Researchers experimenting with AI‑driven code generation for scientific visualisation.

---

Limitations & maintenance notes

• The author is a hobbyist maintainer, so response times on issues/PRs may be slow.
• Studio mode is still maturing; the animation‑focused “Manim Studio” is less feature‑complete than Plot Studio.
• You need access to an OpenAI‑compatible model (or another provider) for the LLM part; the project supplies configuration hooks but does not ship a model.
• Persistent storage of rendered videos requires external volume handling – otherwise rebuilds delete them.

---

License

AGPL‑3.0‑or‑later. Third‑party code from manim-video-generator (MIT) is either rewritten or kept under its original attribution.

---

In short: ManimCat is an AI‑augmented, dual‑mode web app that turns natural‑language math prompts into animated or static visuals using Manim and matplotlib, with a richer “Studio” experience for iterative, collaborative creation.