🎬 Manim AI Fixer

AI-powered Manim animation generator with automatic error fixing. Uses Google's Gemini AI to generate and self-correct Manim code until it works.

✨ Features

• 🤖 AI-Powered Code Generation - Describe animations in plain English
• 🔄 Automatic Error Fixing - AI detects and fixes errors automatically (up to 5 iterations)
• 🎥 Video Output - Generates MP4 animations ready to use
• 💾 Saves Working Code - Keeps the final Python code for reference
• 🎨 Simple CLI - Easy command-line interface
• ⚡ Fast & Free - Uses Google's free Gemini API

📋 Prerequisites

Before installing, ensure you have:

1. Node.js (v18.0.0 or higher)

node --version

Download: https://nodejs.org/

2. Python (3.8 or higher)

python --version

Download: https://python.org/

3. Manim Community Edition

pip install manim
# Verify installation
manim --version

Documentation: https://docs.manim.community/

4. FFmpeg (Required by Manim)

ffmpeg -version

Installation by OS:

• macOS: brew install ffmpeg
• Ubuntu/Debian: sudo apt install ffmpeg
• Windows: Download from https://ffmpeg.org/download.html

5. Google Gemini API Key (Free)

1. Visit: https://makersuite.google.com/app/apikey
2. Sign in with Google account
3. Click "Create API Key"
4. Copy the key (format: AIzaSy...)

Free tier limits: 60 requests/minute, 1500 requests/day

🚀 Quick Start

1. Install globally

npm install -g manim-ai-fixer

2. Set your API key

Windows (PowerShell):

$env:GEMINI_API_KEY="your_api_key_here"

Windows (Command Prompt):

set GEMINI_API_KEY=your_api_key_here

macOS/Linux:

export GEMINI_API_KEY="your_api_key_here"

3. Create your first animation

manim-ai "Create a blue circle that grows and turns red"

4. Find your video

ls output/
# output_1234567890.mp4 ← Your video!

📖 Usage

Basic Syntax

manim-ai "your animation description"

Examples

Simple Shapes:

manim-ai "Create a red square"
manim-ai "Show a triangle transforming into a circle"
manim-ai "Draw a blue pentagon"

Animations:

manim-ai "Create a circle that rotates 360 degrees"
manim-ai "Show text 'Hello World' that fades in"
manim-ai "Make a square that moves from left to right"

Mathematical Visualizations:

manim-ai "Graph the function y = x squared from -3 to 3"
manim-ai "Show a unit circle with sine and cosine"
manim-ai "Visualize the Pythagorean theorem with animated squares"

Complex Animations:

manim-ai "Create three circles in a triangle formation that rotate together"
manim-ai "Show a sine wave animating from left to right with a red dot tracing it"
manim-ai "Animate the formula E = mc² with each letter appearing one by one"

⚙️ Configuration

Option 1: Environment Variables (Temporary)

Set before each use:

# Windows PowerShell
$env:GEMINI_API_KEY="your_key"
$env:MAX_ITERATIONS="5"
$env:MANIM_QUALITY="ql"

# macOS/Linux
export GEMINI_API_KEY="your_key"
export MAX_ITERATIONS="5"
export MANIM_QUALITY="ql"

Option 2: .env File (Permanent - Recommended)

Create a .env file in your working directory:

GEMINI_API_KEY=your_api_key_here
MAX_ITERATIONS=5
MANIM_QUALITY=ql
TIMEOUT_MS=60000

Configuration Options

| Variable | Default | Description | |----------|---------|-------------| | GEMINI_API_KEY | required | Your Google Gemini API key | | MAX_ITERATIONS | 5 | Maximum retry attempts for error fixing | | MANIM_QUALITY | ql | Video quality: ql (low/fast), qm (medium), qh (high) | | TIMEOUT_MS | 60000 | Execution timeout in milliseconds (60 seconds) |

📂 Output

After successful execution, find your files in the output/ folder:

output/
├── output_1234567890.mp4      # Your generated animation video
└── final_code_1234567890.py   # The working Python/Manim code

You can:

• Share the video directly
• Edit the Python code for customization
• Learn from the generated code

🔄 How It Works

1. Input - You describe the animation in plain English
2. Generate - Gemini AI creates Manim Python code
3. Execute - Code runs with Manim to create video
4. Check - If errors occur, AI analyzes them
5. Fix - AI corrects the code automatically
6. Retry - Repeats up to 5 times until success
7. Output - Saves both video and working code

🐛 Troubleshooting

❌ "GEMINI_API_KEY not found"

Solution:

# Set the environment variable
export GEMINI_API_KEY="your_key_here"

# Or create a .env file (see Configuration section)

❌ "python not found" or "manim not found"

Solution:

# Install Python from python.org
# Then install Manim
pip install manim

# Verify
python --version
manim --version

❌ "FFmpeg not found"

Solution: Install FFmpeg for your OS (see Prerequisites section)

❌ API Rate Limit Exceeded

Issue: Free tier allows 60 requests/minute

Solution:

• Wait 1 minute and try again
• Reduce MAX_ITERATIONS in config
• Consider Google AI Studio paid tier for higher limits

❌ Execution Timeout

Issue: Complex animations take too long

Solution:

# Increase timeout (in .env or environment)
TIMEOUT_MS=120000  # 2 minutes

❌ Code Still Fails After 5 Iterations

Solution:

• Try simplifying your prompt
• Break complex animations into smaller parts
• Check the generated code in temp/ folder for issues
• Manually edit the Python code and run with manim directly

💡 Tips for Best Results

✅ Good Prompts

• Specific: "Create a blue circle that rotates clockwise"
• Simple: Start with basic shapes and animations
• Clear: "Show a square transforming into a triangle"

❌ Avoid

• Vague: "Make something cool"
• Too complex: "Create a full quantum physics simulation with 50 objects"
• Ambiguous: "Do the thing with colors"

🎯 Prompt Examples by Difficulty

Beginner:

manim-ai "Create a green circle"
manim-ai "Show a red square"

Intermediate:

manim-ai "Create a circle that transforms into a square"
manim-ai "Show text 'Hello' that fades in and out"

Advanced:

manim-ai "Graph sine and cosine functions on the same axes"
manim-ai "Visualize a binary search tree with 7 nodes"

🏗️ Development

Clone and Setup

git clone https://github.com/yourusername/manim-ai-fixer.git
cd manim-ai-fixer
npm install

Create .env file

cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

Run Locally

npm start "Create a simple circle"

Project Structure

manim-ai-fixer/
├── src/
│   ├── index.js           # Main orchestrator & entry point
│   ├── gemini-service.js  # Gemini AI API service
│   ├── manim-runner.js    # Manim code executor
│   ├── config.js          # Configuration loader
│   └── utils.js           # Helper functions (logging, formatting)
├── bin/
│   └── cli.js             # CLI entry point for npm
├── output/                # Generated videos and code
├── temp/                  # Temporary Python files
├── .env                   # Your API keys (not in git)
├── .gitignore            # Git ignore patterns
├── package.json          # npm configuration
└── README.md            # This file

🔧 Advanced Usage

Using with npm scripts

If you clone the repository:

# Run with default test prompt
npm test

# Run with custom prompt
npm start "your prompt here"

# Development mode (auto-reload)
npm run dev

Programmatic Usage

import { ManimPipeline } from 'manim-ai-fixer';

const pipeline = new ManimPipeline();
await pipeline.run("Create a rotating cube");

Custom Configuration

import { config } from 'manim-ai-fixer/src/config.js';

// Override defaults
config.maxIterations = 10;
config.manimQuality = 'qh';  // High quality

📊 System Requirements

| Component | Minimum | Recommended | |-----------|---------|-------------| | Node.js | 18.0.0 | Latest LTS | | Python | 3.8 | 3.10+ | | RAM | 4GB | 8GB+ | | Disk Space | 2GB | 5GB+ | | Internet | Required | Stable connection |

🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow existing code style
• Add comments for complex logic
• Test thoroughly before submitting
• Update README if adding features

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Manim Community - Amazing animation library
  • Website: https://www.manim.community/
  • GitHub: https://github.com/ManimCommunity/manim
• Google Gemini AI - Powerful AI model
  • Website: https://deepmind.google/technologies/gemini/
• FFmpeg - Video processing
  • Website: https://ffmpeg.org/

📞 Support & Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• npm: Package Page

🎓 Learn More

Manim Resources

• Official Documentation
• Example Gallery
• Discord Community

Google Gemini AI

• API Documentation
• Pricing

⭐ Show Your Support

If this project helped you, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting features
• 📢 Sharing with others

📈 Changelog

Version 1.0.0 (2024)

• ✨ Initial release
• 🤖 Gemini AI integration
• 🔄 Automatic error fixing
• 🎥 Video generation
• 📝 Code saving

🔮 Roadmap

• [ ] Support for more AI models (Claude, GPT-4)
• [ ] Interactive prompt builder
• [ ] Animation templates library
• [ ] Web-based UI
• [ ] Batch processing
• [ ] Custom styling presets

Made with ❤️ using AI and Manim

 ___  ___            _              ___  _____   ______  _
 |  \/  |           (_)            / _ \|_   _| |  ___|(_)
 | .  . |  __ _  _ __  _  _ __ _ | |_| | | |   | |_    _ __  __ ___  _ __
 | |\/| | / _` || '_ \| || '_ ` ||  _  | | |   |  _|  | |\ \/ // _ \| '__|
 | |  | || (_| || | | || || | | || | | |_| |_  | |    | | >  <|  __/| |
 \_|  |_/ \__,_||_| |_||_||_| |_|\_| |_/\___/  \_|    |_|/_/\_\\___||_|

Happy Animating! 🎬✨