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

```mermaid
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**

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

2. **Create virtual environment**

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

3. **Install dependencies**

   ```bash
   cd backend
   pip install -r requirements.txt
   ```

4. **Configure environment**

   Create `.env` file in the root directory:

   ```env
   GEMINI_API_KEY=your_gemini_api_key_here
   ```

5. **Update FFmpeg path** (Windows)

   Edit [main.py](backend/main.py#L13) and set your FFmpeg path:

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

### Running the Application

```bash
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](backend/main.py) line 13:

```python
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:**

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

**Response:**

```json
{
  "status": "started"
}
```

### GET `/status`

Check the current generation status.

**Response:**

```json
{
  "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](https://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](https://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:
   ```dockerfile
   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](https://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](https://github.com/SayedZahur786)
- Repository: [Animetrix_AI](https://github.com/SayedZahur786/Animetrix_AI)

---

**Made with ❤️ using AI and Manim**