AI Avatar Video Generation - Phase 1

A simplified AI avatar video generation platform that creates talking head videos using HeyGen's built-in avatars and voices.

🎯 Phase 1 Overview

Phase 1 focuses on a streamlined video generation experience:

• Built-in Avatars: Choose from HeyGen's professional AI avatars
• Built-in Voices: Select from multilingual voices with emotion support
• Script-to-Video: Simply write a script and generate professional videos
• Real-time Updates: Live status updates via Supabase realtime
• Responsive Design: Works on desktop, tablet, and mobile

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm/yarn/pnpm
• Supabase project
• HeyGen API key

Installation

1. Clone and install dependencies:

   git clone <your-repo>
   cd avatars
   npm install

2. Set up environment variables:

   cp docs/environment-setup.md .env.local
   # Edit .env.local with your actual values

3. Set up the database:

   • Run the SQL from scripts/phase1-migration.sql in your Supabase SQL editor

4. Start the development server:

   npm run dev

5. Open http://localhost:3000

🏗️ Architecture

Tech Stack

• Frontend: Next.js 15, React 19, Tailwind CSS
• Backend: Next.js API Routes, Supabase
• Database: PostgreSQL (Supabase)
• AI Services: HeyGen (avatars, voices, video generation)
• Deployment: Vercel

Key Features

• Authentication: Supabase Auth with Google OAuth
• Real-time Updates: Supabase Realtime subscriptions
• Webhook Handling: HeyGen webhook processing
• Row Level Security: Secure data access

API Endpoints

• GET /api/heygen/avatars - List built-in avatars
• GET /api/heygen/voices - List built-in voices
• POST /api/video/generate - Generate video with script
• POST /api/heygen/webhook - Handle video completion

📱 Usage

1. Sign In: Use Google OAuth to authenticate
2. Create Video:
   • Choose an avatar from the gallery
   • Select a voice with desired language/emotion
   • Write your script (up to 5000 characters)
   • Customize settings (style, speed, pitch, background)
   • Click "Generate Video"
3. Monitor Progress: Real-time status updates on dashboard
4. View Results: Watch and share completed videos

🔧 Configuration

See docs/environment-setup.md for detailed environment setup instructions.

Required Environment Variables

NEXT_PUBLIC_SUPABASE_URL=your-supabase-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
HEYGEN_API_KEY=your-heygen-api-key
HEYGEN_WEBHOOK_SECRET=your-webhook-secret
PUBLIC_URL=https://your-domain.com

🚀 Deployment

Vercel Deployment

1. Connect to Vercel:

   • Import your GitHub repository
   • Vercel will auto-detect Next.js

2. Configure Environment Variables:

   • Add all environment variables to Vercel project settings
   • Set PUBLIC_URL to your Vercel domain

3. Deploy:

   • Push to main branch for automatic deployment

📚 Project Structure

app/
├── api/
│   ├── heygen/
│   │   ├── avatars/route.ts    # List built-in avatars
│   │   ├── voices/route.ts     # List built-in voices
│   │   └── webhook/route.ts    # Handle HeyGen webhooks
│   └── video/
│       └── generate/route.ts   # Generate videos
├── components/
│   ├── VideoGenerationForm.tsx # Main video creation form
│   ├── VideoCard.tsx          # Video display component
│   ├── DashboardClient.tsx    # Dashboard with real-time updates
│   └── Navbar.tsx             # Navigation component
├── dashboard/page.tsx          # User dashboard
├── video/create/page.tsx       # Video creation page
└── page.tsx                   # Landing page

lib/
├── heygen.ts                  # HeyGen API utilities
├── validators.ts              # Zod schemas
└── supabase/                  # Supabase clients

scripts/
└── phase1-migration.sql       # Database schema

🔜 Future Phases

• Phase 2: Custom avatar training from photos
• Phase 3: Custom voice cloning
• Phase 4: Advanced video editing features

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

This project is licensed under the MIT License.