🎬 PIYX AI

Open-Source Live Educational Audio-Video Generator

Transform any prompt, equation, or complex concept into studio-grade animated video lessons powered by Gemini and Manim.

---

⚡ Highlights

• 🪄 Prompt-to-Video in Seconds: Turn complex questions into visually stunning 2D/3D animated lessons.
• 📐 3Blue1Brown-Style Visuals: Automatic generation of programmatic animations using Manim (Community Edition).
• 🧠 Multi-Modal AI Reasoning: Uses Google Gemini to generate structured scenes, mathematical formulas, and synced speech scripts.
• 🎙️ Synchronized Voiceover: Built-in Edge TTS narration engine aligned with visual animations.
• 🚀 1-Command Deploy & Run: Fully containerized with Docker and Docker Compose.
• 🌐 100% Free Tier Compatible: Optimized for zero-cost deployment using Vercel & Hugging Face Spaces.

---

🗺️ Table of Contents

• Highlights
• Architecture
• Tech Stack
• Quick Start
  • Option A: Docker Compose (Fastest)
  • Option B: Local Development
• Environment Variables
• Roadmap
• Contributing
• Community
• Security
• License

---

🏗️ Architecture

flowchart LR
    subgraph Client["Frontend (Next.js 16)"]
        UI[Interactive Web Interface]
        Player[Video Player & Downloader]
    end

    subgraph Server["Backend (FastAPI)"]
        API[REST API Gateway]
        PromptBuilder[Prompt Builder & Context Engine]
        ManimEngine[Manim Execution Sandbox]
        TTS[Edge TTS Voiceover Engine]
    end

    subgraph AI["AI Providers"]
        Gemini[Google Gemini API]
    end

    subgraph Output["Artifacts"]
        Scenes[Python Scene Scripts]
        MP4[HD MP4 Renderings]
    end

    UI -->|1. Submit Query| API
    API -->|2. Build Structured Prompt| PromptBuilder
    PromptBuilder -->|3. Generate Animation Code| Gemini
    Gemini -->|4. Return Valid Manim Script| ManimEngine
    ManimEngine -->|5. Render Scene Frames| MP4
    TTS -->|6. Generate Audio| MP4
    MP4 -->|7. Stream & Playback| Player

Loading

---

💻 Tech Stack

Component	Technology	Description
Frontend	Next.js 16 + React 19	App Router, Server/Client components, dynamic streaming
Styling	Tailwind CSS v4	Modern design system, sleek dark mode & glassmorphism
Backend	FastAPI	High-performance asynchronous Python API
Animation Engine	Manim CE	Mathematical animation engine inspired by 3Blue1Brown
Audio / Narration	Edge TTS	Natural neural voice generation
Video Processing	FFmpeg	Video encoding, frame assembly, and audio muxing
AI LLM	Google Gemini	Code generation, reasoning, and scene synthesis
Containerization	Docker	Multi-stage production container builds

---

🚀 Quick Start

Prerequisites

• Git
• Docker & Docker Compose (for container setup)
• Node.js v20+ & Python 3.11+ (for local manual setup)
• Google Gemini API Key (free to obtain)

---

Option A: Docker Compose (Fastest)

# 1. Clone the repository
git clone https://github.com/Piyushbijarania/PIYX.git
cd PIYX

# 2. Set your Gemini API Key
echo GEMINI_API_KEY=your_gemini_api_key_here > .env

# 3. Launch everything in containers
docker compose up --build

• 🌐 Web App: http://localhost:3000
• 📚 API Docs: http://localhost:8000/docs

---

Option B: Local Development

1. Backend Setup

cd backend
python -m venv .venv

# On Windows
.venv\Scripts\activate
# On macOS/Linux
source .venv/bin/activate

pip install -r requirements.txt
cp .env.example .env
# Edit .env and set your GEMINI_API_KEY

python main.py

2. Frontend Setup

cd ../frontend
npm install
cp .env.example .env.local

npm run dev

Open http://localhost:3000 in your browser.

---

⚙️ Environment Variables

Backend (backend/.env)

Variable	Required	Description	Default
GEMINI_API_KEY	Yes	Google Gemini API Key	-
PORT	No	Port for backend server	8000
HOST	No	Host binding	0.0.0.0
MANIM_QUALITY	No	Video quality (low_quality, medium_quality, high_quality)	medium_quality

Frontend (frontend/.env.local)

Variable	Required	Description	Default
NEXT_PUBLIC_BACKEND_URL	No	Base URL of deployed backend	http://localhost:8000

---

🗺️ Roadmap

• Initial FastAPI + Gemini Manim code generator
• Next.js 16 modern dark-mode frontend
• Docker & Docker Compose containerization
• Dynamic API routing & Free-tier cloud support
• 🎨 Interactive Scene Editor: Edit Manim code directly in the browser with live re-rendering
• 🗣️ Multi-Language Voiceovers: Support 20+ languages for worldwide education
• 💾 Cloud Storage Provider Plugins: S3, Supabase, Cloudinary export integrations
• 📱 Mobile Native Client: React Native / Flutter cross-platform app
• 🧪 Automated Scene Unit Testing: Visual regression testing for generated videos

---

🤝 Contributing

Contributions make the open-source community an inspiring place to learn, inspire, and create. Any contributions you make are greatly appreciated!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feat/AmazingFeature)
3. Commit your Changes (git commit -m 'feat: add some AmazingFeature')
4. Push to the Branch (git push origin feat/AmazingFeature)
5. Open a Pull Request

Please read our Contributing Guide and Code of Conduct for full details.

Looking for where to start? Check out issues tagged with good first issue.

---

👥 Contributors

Thanks to all the amazing people who have contributed to PIYX!

---

⭐ Star History

---

💬 Community

• GitHub Discussions — Ask questions, suggest ideas, and show off what you've generated.
• GitHub Issues — File bugs or technical issues.

---

🛡️ Security

Please review our Security Policy to report any vulnerabilities responsibly.

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

Made with ❤️ by the PIYX AI Community