ManimCat

English | 简体中文

Overview

I am happy to introduce my new project, ManimCat. It is, after all, a cat.

Built on top of manim-video-generator, ManimCat is now a much broader AI-assisted creation system for math teaching visuals rather than just a single generation flow.

It is designed for classroom explanation, worked-example breakdowns, and visual reasoning tasks. You can use natural language to generate, modify, rerender, and organize both animated and static teaching visuals with video and image outputs.

The project is now organized around three clear axes: dual-mode, dual-engine, and dual-studio.

• Workflow Mode is for direct generation and rendering when you want fast outputs
• Agent Mode is for Studio-based collaborative work with longer-lived sessions, task state, review, and iteration
• ManimGX is used for animation and timeline-based mathematical storytelling
• matplotlib is used in Plot Studio for static math visuals, charts, and teaching figures
• Plot Studio is the more mature Studio path today for static visual work and iterative editing
• Manim Studio is the animation-oriented Studio path and is still at an earlier stage

Interface

UI

Workflow

Plot Studio

Examples

Prove that $1/4 + 1/16 + 1/64 + \dots = 1/3$ using a beautiful geometric method, elegant zooming, smooth camera movement, a slow pace, at least two minutes of duration, clear logic, a creamy yellow background, and a macaroon-inspired palette.

▲ Geometric Series Proof · ManimCat

Quick Start

npm install
cd frontend && npm install
cd ..
npm run dev

Open http://localhost:3000. See .env.example for environment variables and Deployment below for deployment notes.

If you want a direct Docker deployment path, you can also start from the published image wingflow/manimcat instead of building locally first. Local animation rendering uses ManimGX 0.1.1 and requires Python 3.13 or newer. The Linux wheel includes lavapipe for CPU rendering.

ManimGX uses native Typst typesetting, so local rendering needs no external TeX installation. Typst supports Chinese text and mathematics in the same expression.

For local rendering, create a Python 3.13+ virtual environment, install dependencies with python -m pip install -r requirements.txt, then set MANIMGX_PYTHON to that environment's Python executable so the app can use the renderer.

Technology

Tech Stack

• Product structure: Workflow mode for direct generation, Agent mode for Studio-based collaborative work
• Visual engines: ManimGX for animation, matplotlib for Plot Studio static figures
• Backend: Express + TypeScript, Bull + Redis, OpenAI-compatible upstream routing, Studio agent runtime, optional Supabase history storage
• Frontend: React 19, Vite, Tailwind CSS, classic generator UI, Studio workspace shell, Plot Studio minimal workspace UI
• Agent state model: session / run / task / work / result lifecycle for longer-lived studio interactions
• Realtime layer: polling for Workflow jobs, Server-Sent Events for Agent sessions, permission requests, and task updates
• Rendering runtime: Python 3.14, ManimGX 0.1.1, matplotlib, ffmpeg; ManimGX bundles fonts and typesetting
• Deployment: Docker / Docker Compose, Hugging Face Spaces

Workflow Mode

flowchart LR
    classDef ui fill:#F6F7FB,stroke:#455A64,color:#263238,stroke-width:1.2px;
    classDef logic fill:#FFF8E1,stroke:#A1887F,color:#4E342E,stroke-width:1.2px;
    classDef api fill:#E8F5E9,stroke:#5D8A66,color:#1B4332,stroke-width:1.2px;
    classDef state fill:#E3F2FD,stroke:#5C6BC0,color:#1A237E,stroke-width:1.2px;
    classDef output fill:#FCE4EC,stroke:#AD5C7D,color:#6A1B4D,stroke-width:1.2px;

    U[User prompt] --> P1
    P1[Classic UI] --> P2[Problem framing]
    P1 --> P3[Generate / Modify requests]
    P2 --> A1[Workflow APIs]
    P3 --> A1
    A1 --> R1[Upstream routing + AI generation]
    R1 --> C1[Render failure retry / patch loop]
    C1 --> B1[Queue + job state]
    B1 --> B2[Render pipeline]
    B2 --> O1[Video / images / code / timings]
    P1 -. polling / cancel .-> B1
    O1 --> P1

    class P1 ui;
    class P2,P3,R1,C1 logic;
    class A1 api;
    class B1,B2 state;
    class O1 output;

Agent Mode

flowchart LR
    classDef ui fill:#F6F7FB,stroke:#455A64,color:#263238,stroke-width:1.2px;
    classDef runtime fill:#FFF8E1,stroke:#A1887F,color:#4E342E,stroke-width:1.2px;
    classDef api fill:#E8F5E9,stroke:#5D8A66,color:#1B4332,stroke-width:1.2px;
    classDef state fill:#E3F2FD,stroke:#5C6BC0,color:#1A237E,stroke-width:1.2px;
    classDef event fill:#FCE4EC,stroke:#AD5C7D,color:#6A1B4D,stroke-width:1.2px;

    U[User instruction] --> S1
    S1[Studio UI] --> A1[Session / run APIs]
    A1 --> R1[Studio runtime service]
    R1 --> K1[Manim Studio / Plot Studio]
    K1 --> G1[Builder, Designer, Reviewer]
    G1 --> T1[Tools, skills, render / review actions]
    R1 --> S2[Session / run / task / work state]
    R1 --> E1[SSE events + permissions]
    S2 --> S1
    E1 --> S1

    class S1 ui;
    class A1 api;
    class R1,K1 runtime;
    class G1,T1,S2 state;
    class E1 event;

Deployment

Hugging Face Spaces (Docker)

Use the repository's Dockerfile, listening on port 7860. Its startup script launches embedded Redis; Docker Compose is not needed inside the Space.

Configure environment variables in Space Settings. Store sensitive values in Secrets, never in the repository, Dockerfile, or frontend:

BYOK users configure their upstream in the UI. For server-side Studio session persistence, set STUDIO_DATA_MODE=server and ENABLE_STUDIO_DB=true, and configure Supabase with the required tables. Multiple replicas also require shared Redis and accessible render-file storage.

Before syncing to Spaces, commit the changes to publish on main, then run:

./scripts/sync-space.ps1

On Linux/macOS, run bash scripts/sync-space.sh. By default, the script publishes committed main to the space and space-show remotes, overwriting their remote main; check the remote URLs first. It injects Space metadata. Uncommitted changes are excluded from the deployment snapshot.

Deployment notes:

• Without persistent storage, treat container videos, workspaces, and Redis data as temporary: rebuilds may remove them. Database-backed sessions do not preserve video files.
• Run npm audit --omit=dev and address security findings before public deployment. After startup, check /health, then verify a real model request and video playback.
• Local Docker checks covered the web UI, Manim, LaTeX, Chinese text, Matplotlib, and MiniLM inference. HF hosting, CatKey, and Supabase integration still require verification after deployment.

Major Additions

This project is a substantial rework built on top of the original foundation. The main additions I personally designed and implemented are:

Generation and Rendering

• Added a dedicated image workflow alongside video generation
• Added YON_IMAGE anchor-based segmented rendering for multi-image outputs
• Added two-stage AI generation: a concept designer produces a scene design, then a code generator writes the Manim code
• Added AI-driven code retry: when a render fails, the error is fed back to the model to regenerate and re-render automatically
• Added rerender-from-code and AI-assisted modify-and-render flows
• Added stage timing breakdown shared by both image and video jobs
• Added background music mixing for rendered videos
• Added render-failure event collection and export for debugging and reliability work

Product and Interface

• Rebuilt the frontend as a separate React + TypeScript + Vite application
• Added problem framing before generation to help structure user requests
• Added reference image upload support
• Added a unified workspace for generation history and usage views
• Added a usage metrics dashboard with daily charts, success rates, and timing breakdowns
• Added a prompt template manager for viewing and overriding system prompts per role
• Added dark / light theme toggle
• Added a waiting-state 2048 mini-game
• Added a refreshed visual style, settings panels, and provider configuration flows

Infrastructure and Routing

• Reworked the backend around Express + Bull + Redis
• Added retry, timeout, cancellation, and status-query flows
• Added support for third-party OpenAI-compatible APIs and custom provider configuration
• Added server-side upstream routing by ManimCat key
• Kept optional multi-profile frontend provider rotation for local use
• Added optional Supabase-backed persistent history storage

Studio Agent

• Added a separate Agent Mode driven by a Studio runtime rather than the classic one-shot generation flow
• Defined the long-lived Studio state model around session / run / task / work / result
• Added builder, designer, and reviewer roles inside the Studio agent system
• Added workspace tools, render tools, local skills, and subagent orchestration
• Added Server-Sent Events for live Studio updates plus permission request / reply handling
• Added Studio review, pipeline, work, and permission panels in the frontend

Plot Studio and Manim Studio

• Added two distinct Studio workspaces: Plot Studio for matplotlib-based static visuals and Manim Studio for animation-oriented workflows
• Added Plot Studio output history browsing, work reordering, and a minimal split workspace layout
• Established the dual-engine product direction: Manim for animated mathematical storytelling, matplotlib for static teaching figures and charts

License and Copyright

The current version of this repository is licensed under AGPL-3.0-or-later. See LICENSE for the full text.

• Third-party attribution and notices: THIRD_PARTY_NOTICES.md
• Chinese third-party notices: THIRD_PARTY_NOTICES.zh-CN.md
• Contribution guide: CONTRIBUTING.md

Historical Versions

ManimCat early versions included code from manim-video-generator (MIT). Historical commits and historical releases remain governed by the license terms that were published with those versions. The current version has removed or independently rewritten the corresponding implementations.

Maintenance Notes

Because my time is limited and I am an independent hobbyist rather than a full-time professional maintainer, I currently cannot provide fast review cycles or long-term maintenance for external contributions. Pull requests are welcome, but review may take time.

If you have good suggestions or discover a bug, feel free to open an Issue for discussion. I will improve the project at my own pace. If you want to make large-scale changes on top of this work, you are also welcome to fork it and build your own version.

If this project gave you useful ideas or helped you in some way, that is already an honor for me.

Star History

[Star History Chart]

Acknowledgements

• rohitg00/manim-video-generator
• anomalyco/opencode
• academa-labs/manimgx — animation engine and Manim-compatible API
• Linux.do
• Alibaba Cloud Bailian