README.md

� Animetrix AI - AI Educational Animation Generator

Create professional educational animations from natural language using AI and Manim

---

📋 Overview

Animetrix AI is an intelligent animation generation platform that transforms simple text descriptions into high-quality educational videos. Powered by Google Gemini AI and Manim Community Edition, it automatically interprets concepts, generates animation code, and renders professional videos with synchronized voiceovers.

Key Features

• 🤖 AI-Powered Generation — Natural language to animated video pipeline
• 🎬 Synchronized Narration — Step-by-step voiceover perfectly timed with animations
• 🎨 Professional Quality — Clean Manim animations with smart post-processing
• 🔧 Self-Correcting — Automatic error detection and code sanitization
• 🚀 Production Ready — FastAPI backend with modern web interface

---

🏗 Architecture

graph TD
    A[User Prompt] --> B[Teacher Module]
    B --> C[Gemini AI - Outline Generation]
    C --> D[Structured JSON with Steps]
    D --> E[Narrator - Per-Step Audio]
    E --> F[Compiler - Code Generation]
    F --> G[Gemini AI - Manim Code]
    G --> H[Code Sanitization]
    H --> I[Runner - Manim Rendering]
    I --> J[Video + Audio Merge]
    J --> K[Final MP4 Output]

Pipeline Stages

1. Teacher (teacher.py) - Converts prompts into structured educational outlines
2. Narrator (narrator.py) - Generates per-step narration audio with gTTS
3. Compiler (compiler.py) - Creates clean Manim code with audio synchronization
4. Runner (runner.py) - Executes rendering and merges audio/video

---

🛠 Tech Stack

Backend

• FastAPI - High-performance async API framework
• Google Gemini 2.5 Flash - AI model for outline and code generation
• Manim Community Edition - Professional animation engine
• gTTS - Text-to-speech for narration
• MoviePy - Audio/video processing

Frontend

• Tailwind CSS - Modern, responsive design
• Three.js - Animated particle background
• Vanilla JavaScript - Lightweight, no framework overhead

Infrastructure

• Python 3.8+
• FFmpeg for video encoding
• Environment-based configuration

---

📁 Project Structure

animetrix-ai/
├── backend/
│   ├── main.py              # FastAPI application & pipeline orchestration
│   ├── teacher.py           # Outline generation (Gemini)
│   ├── compiler.py          # Code generation & sanitization (Gemini)
│   ├── runner.py            # Manim rendering
│   ├── narrator.py          # Audio generation & merging
│   ├── requirements.txt     # Python dependencies
│   ├── static/
│   │   └── index.html       # Web interface
│   └── media/               # Generated videos & audio
├── .env                     # Environment variables
├── .gitignore
└── README.md

---

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• FFmpeg installed and in PATH
• Google Gemini API key

Installation

1. Clone the repository

   git clone https://github.com/SayedZahur786/Animetrix_AI.git
   cd Animetrix_AI
   

2. Create virtual environment

   python -m venv venv
   venv\Scripts\activate  # Windows
   # source venv/bin/activate  # Linux/Mac
   

3. Install dependencies

   cd backend
   pip install -r requirements.txt
   

4. Configure environment

   Create .env file in the root directory:

   GEMINI_API_KEY=your_gemini_api_key_here
   

5. Update FFmpeg path (Windows)

   Edit main.py and set your FFmpeg path:

   ffmpeg_path = r"C:\path\to\ffmpeg\bin"
   

Running the Application

cd backend
uvicorn main:app --reload

Open your browser and navigate to:

http://localhost:8000

---

🎯 Usage

1. Enter a prompt in the text area (e.g., "Explain the Pythagorean theorem with a visual proof")
2. Click Generate to start the pipeline
3. Monitor progress through real-time status updates:
   • Planning (outline generation)
   • Coding (Manim script creation)
   • Executing (animation rendering)
4. Watch the result - video automatically plays when ready

Example Prompts

• "Show how compound interest grows over time"
• "Visualize the concept of derivatives with a tangent line"
• "Demonstrate bubble sort algorithm step by step"
• "Explain photosynthesis with animated diagrams"

---

🔧 Configuration

Environment Variables

Variable	Description	Required
GEMINI_API_KEY	Google Gemini API key	Yes

FFmpeg Configuration

Update the FFmpeg path in main.py line 13:

ffmpeg_path = r"M:\Ap\ffmpeg-7.1.1-essentials_build\ffmpeg-7.1.1-essentials_build\bin"

---

📡 API Reference

POST /generate

Generate an educational animation from a text prompt.

Request Body:

{
  "prompt": "Explain Newton's first law of motion"
}

Response:

{
  "status": "started"
}

GET /status

Check the current generation status.

Response:

{
  "stage": "executing",
  "message": "Rendering Animation Frames...",
  "video_path": null,
  "error": null
}

GET /video/{path}

Retrieve the generated video file.

---

🐛 Troubleshooting

Issue	Solution
FFmpeg not found	Ensure FFmpeg is installed and path is correctly set in main.py
Gemini API errors	Verify your API key is valid and has sufficient quota
Import errors	Run pip install -r requirements.txt in the backend directory
Manim rendering fails	Check that Manim CE is properly installed: pip install manim

---

🌐 Free Deployment Options

Option 1: Render.com (Recommended)

Best for: Simple, automated deployments

• ✅ Free tier with 750 hours/month
• ✅ Auto-deploy from GitHub
• ✅ Built-in SSL
• ⚠️ Spins down after inactivity (cold starts ~30s)

Steps:

1. Push code to GitHub
2. Connect to Render.com
3. Create new Web Service
4. Add environment variable: GEMINI_API_KEY
5. Build command: cd backend && pip install -r requirements.txt
6. Start command: cd backend && uvicorn main:app --host 0.0.0.0 --port $PORT

Option 2: Railway.app

Best for: Quick deployments with generous free tier

• ✅ $5 free credit/month
• ✅ No sleep/cold starts
• ✅ GitHub integration

Steps:

1. Connect GitHub repo to Railway.app
2. Add GEMINI_API_KEY in Variables
3. Set start command: cd backend && uvicorn main:app --host 0.0.0.0 --port $PORT

Option 3: Fly.io

Best for: Global edge deployment

• ✅ Free tier: 3 shared VMs
• ✅ Global CDN
• ✅ Fast performance

Steps:

1. Install Fly CLI: curl -L https://fly.io/install.sh | sh
2. Login: fly auth login
3. Launch: fly launch
4. Set secrets: fly secrets set GEMINI_API_KEY=your_key

Option 4: Google Cloud Run

Best for: Pay-per-use, scales to zero

• ✅ 2 million requests/month free
• ✅ No cold start issues
• ✅ Integrated with Google services

Steps:

1. Create Dockerfile in project root:

   FROM python:3.10-slim
   RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*
   WORKDIR /app
   COPY backend/requirements.txt .
   RUN pip install --no-cache-dir -r requirements.txt
   COPY backend/ .
   EXPOSE 8080
   CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]
   

2. Deploy: gcloud run deploy animetrix-ai --source .

Option 5: Hugging Face Spaces

Best for: ML/AI community exposure

• ✅ Free GPU access (limited)
• ✅ Great for demos
• ✅ Built-in community

Steps:

1. Create new Space at huggingface.co/spaces
2. Select "Gradio" or "Streamlit" SDK
3. Push code to Space repository
4. Add GEMINI_API_KEY in Space secrets

Comparison Table

Platform	Free Tier	Cold Starts	Deployment	Best For
Render.com	✅ 750h/month	Yes (~30s)	Easiest	Beginners
Railway.app	✅ $5 credit	No	Easy	Active projects
Fly.io	✅ 3 VMs	Minimal	Moderate	Performance
Google Cloud Run	✅ 2M requests	Minimal	Advanced	Scale
Hugging Face	✅ Free GPU	No	Easy	ML Community

💡 Recommendation: Start with Render.com for easiest setup, then migrate to Railway.app or Fly.io for production use.

---

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

---

📄 License

This project is open source and available under the MIT License.

---

👨‍💻 Author

Sayed Zahur

• GitHub: @SayedZahur786
• Repository: Animetrix_AI

---

Made with ❤️ using AI and Manim