# 🎥 Brovio HeyGen Video Creator

A production-ready Node.js/Express server that integrates with HeyGen's API to create AI-generated videos with avatars and voices. Features a modern web interface, S3 storage integration, and automated video processing.

## 🌐 Live Production

**URL:** https://vids.brovio.cloud/

**Status:** ✅ Deployed and operational on Coolify

## ✨ Features

- **Modern Web UI** - Dark theme with animated geometric headers
- **Video Creation** - Create videos with AI avatars and voices
- **Gallery Management** - Browse, filter, and manage completed videos
- **Real-time Processing** - Background polling for video status updates
- **S3 Storage** - Automatic upload to Hetzner Object Storage
- **API Endpoints** - Full REST API for programmatic access
- **Health Checks** - Docker-ready with health monitoring

## 🚀 Quick Start

### Local Development

```bash
# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Edit .env with your credentials
# Required: HEYGEN_API_KEY, S3 credentials

# Start the server
npm run heygen:server

# Access at http://localhost:4005
```

### Environment Variables

```env
# HeyGen API Configuration
HEYGEN_API_KEY=your_api_key_here
HEYGEN_AVATAR_ID=Brandon_Business_Sitting_Front_public
HEYGEN_VOICE_ID=3787b4ab93174952a3ad649209f1029a

# S3/Object Storage Configuration
S3_ENDPOINT=https://hel1.your-objectstorage.com
S3_BUCKET=brovio-ai-news
S3_ACCESS_KEY=your_access_key
S3_SECRET_KEY=your_secret_key
S3_REGION=eu-north-1
S3_PUBLIC_READ=true

# Server Configuration
PORT=4005
```

## 📦 Production Deployment

### Docker Build

```bash
# Build image
docker build -t brovio-heygen-server .

# Run container
docker run -p 4005:4005 --env-file .env brovio-heygen-server
```

### Coolify Deployment

1. **Repository:** `brovio/brovio-heygen-server`
2. **Branch:** `main`
3. **Build Method:** Dockerfile
4. **Port:** 4005
5. **Environment Variables:** Set in Coolify dashboard
6. **Health Check:** `/health` endpoint

See `DEPLOYMENT_READY.md` for detailed deployment instructions.

## 🔌 API Endpoints

### Public Endpoints

- `GET /` - Main video creator UI
- `GET /gallery.html` - Video gallery
- `GET /processing.html` - Processing videos
- `GET /stats.html` - Analytics dashboard
- `GET /help.html` - API documentation
- `GET /health` - Health check

### HeyGen Integration

- `GET /api/heygen/avatars` - List available avatars
- `GET /api/heygen/voices` - List available voices
- `POST /api/heygen/generate` - Create new video
- `GET /api/heygen/status/:id` - Check video status
- `GET /api/heygen/download/:id` - Get video download URL

### Video Management

- `GET /api/videos` - List all videos
- `GET /api/videos/:id` - Get specific video
- `POST /api/videos` - Create video record
- `PATCH /api/videos/:id` - Update video
- `DELETE /api/videos/:id` - Delete video
- `POST /api/videos/:id/repair` - Repair video metadata

### Background Processing

- `POST /api/process-videos` - Manually trigger video processing
- Auto-processes completed videos every 30 seconds

## 🧪 Testing

```bash
# Install Playwright
npm install -D @playwright/test

# Run all tests
npm test

# Run specific test file
npx playwright test tests/api.spec.js

# Run with UI
npx playwright test --ui
```

## 📁 Project Structure

```
brovio-heygen-server/
├── v3/
│   ├── heygen_server.js      # Main Express server
│   ├── public/                # Web interface
│   │   ├── index.html         # Video creator
│   │   ├── gallery.html       # Video gallery
│   │   ├── processing.html    # Processing monitor
│   │   ├── stats.html         # Analytics
│   │   ├── help.html          # API docs
│   │   └── styles.css         # Modern design system
│   └── data/
│       └── videos.json        # Video metadata
├── tests/                     # Playwright tests
├── Dockerfile                 # Production container
├── .dockerignore             # Build exclusions
├── package.json              # Dependencies
└── .env.example              # Environment template
```

## 🎨 Frontend Features

- **Dark Navigation** - Gradient branding with sticky positioning
- **Animated Headers** - Geometric shapes with flowing animations
- **Responsive Design** - Works on desktop and mobile
- **Real-time Stats** - Processing/completed/failed counts
- **Filter & Sort** - Gallery filtering and view modes
- **Time Estimates** - Processing time predictions

## 🔧 Development

### Scripts

```bash
npm run heygen:server    # Start HeyGen server (port 4005)
npm test                 # Run Playwright tests
npm run test:ui          # Run tests with UI
```

### Adding New Features

1. API endpoints → `v3/heygen_server.js`
2. Frontend pages → `v3/public/*.html`
3. Styling → `v3/public/styles.css`
4. Tests → `tests/*.spec.js`

## 🐛 Troubleshooting

### Videos Not Storing in S3

Check S3 configuration in `/api/debug/env`:
```bash
curl http://localhost:4005/api/debug/env
```

### Frontend Not Loading

Verify static files are served:
```bash
ls -la v3/public/
```

### Health Check Failing

Check server logs:
```bash
docker logs <container_id>
```

## 📚 Documentation

- `DEPLOYMENT_READY.md` - Comprehensive deployment guide
- `COOLIFY_SIMPLE_GUIDE.md` - ELI5 deployment instructions
- `PROJECT_CONTEXT_SUMMARY.md` - Project context and history

## 🔐 Security

- ✅ Secrets stored in environment variables
- ✅ API keys masked in debug endpoints
- ✅ HTTPS enabled via Let's Encrypt
- ✅ Production builds exclude dev dependencies
- ✅ `.dockerignore` prevents sensitive files in image

## 📊 Monitoring

- **Health Checks:** Docker health check every 30s
- **Background Processing:** Auto-processes videos every 30s
- **Stats Dashboard:** Real-time analytics at `/stats.html`

## 🤝 Contributing

1. Create feature branch
2. Make changes
3. Add tests
4. Update documentation
5. Submit pull request

## 📄 License

Proprietary - Brovio