DEPLOYMENT_GUIDE.md

# 🚀 Complete Deployment Guide to Hugging Face

## Before You Start

### Prerequisites
- A Hugging Face account ([Sign up here](https://huggingface.co/join))
- A Google API key with Gemini API access ([Get one here](https://aistudio.google.com/app/apikey))
- At least 5-10 video clips (MP4 format recommended)

---

## Part 1: Create Your Hugging Face Space

### Step 1: Create New Space
1. Go to https://huggingface.co/spaces
2. Click the **"Create new Space"** button (top right)
3. Fill in the details:
   - **Owner**: Your username
   - **Space name**: Choose a name (e.g., `ai-video-generator`)
   - **License**: Apache 2.0 (recommended)
   - **Select the Space SDK**: Choose **Gradio**
   - **Space hardware**: Start with **CPU basic** (free) - you can upgrade later
   - **Space visibility**: Public or Private (your choice)
4. Click **"Create Space"**

---

## Part 2: Upload Your Code Files

### Step 2: Upload Main Files via Web Interface

1. You should now be in your Space's main page
2. Click on **"Files and versions"** tab
3. Click **"Add file"** → **"Upload files"**
4. Upload these files (download from the artifacts above):
   - `app.py`
   - `requirements.txt`
   - `packages.txt`
   - `README.md`
   - `.gitignore`
   - `.gitattributes`
5. In the commit message box, type: `Initial commit - upload main files`
6. Click **"Commit changes to main"**

### Alternative: Using Git (Advanced)

If you're comfortable with Git:

```bash
# Clone your space
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# Copy your files
cp /path/to/downloaded/app.py .
cp /path/to/downloaded/requirements.txt .
cp /path/to/downloaded/packages.txt .
cp /path/to/downloaded/README.md .
cp /path/to/downloaded/.gitignore .
cp /path/to/downloaded/.gitattributes .

# Commit and push
git add .
git commit -m "Initial commit - upload main files"
git push
```

---

## Part 3: Configure API Key

### Step 3: Add Google API Key

🚨 **CRITICAL**: Never put your API key directly in the code!

1. In your Space, click **"Settings"** (gear icon in top right)
2. Scroll down to **"Repository secrets"**
3. Click **"New secret"**
4. Enter:
   - **Name**: `GOOGLE_API_KEY`
   - **Value**: Paste your actual Google API key
5. Click **"Add"**

---

## Part 4: Upload Video Clips

### Step 4: Create video_clips Folder and Upload Videos

**Option A: Using Web Interface**

1. Go back to **"Files and versions"** tab
2. Click **"Add file"** → **"Upload files"**
3. Create folder structure by typing: `video_clips/`
4. Upload your video files (.mp4, .avi, .mkv, or .mov)
5. If videos are larger than 10MB, you'll need to use Git LFS (see below)
6. Commit with message: `Add video clips`

**Option B: Using Git with LFS for Large Files**

```bash
# Make sure you're in your cloned space directory
cd YOUR_SPACE_NAME

# Install Git LFS if not already installed
git lfs install

# Create video_clips folder
mkdir video_clips

# Copy your video files
cp /path/to/your/videos/*.mp4 video_clips/

# Add and commit
git add video_clips/
git commit -m "Add video clips"
git push
```

**Video Requirements:**
- At least 5-10 video clips
- Formats: .mp4, .avi, .mkv, or .mov
- Resolution: 720p or 1080p recommended
- Duration: 5-30 seconds per clip works best

---

## Part 5: Optional - Add Background Music

### Step 5: Upload Background Music (Optional)

1. Go to **"Files and versions"**
2. Click **"Add file"** → **"Upload files"**
3. Create folder: `background_music/`
4. Upload your music file (.mp3 or .wav)
5. Commit with message: `Add background music`

---

## Part 6: Wait for Build and Test

### Step 6: Monitor Build Process

1. Go back to your Space's main page (click the Space name at top)
2. Click on **"Logs"** tab
3. Watch the build process:
   - Installing system packages (imagemagick, ffmpeg)
   - Installing Python packages
   - Starting the app

**Build Status Indicators:**
- 🟡 Yellow "Building": In progress
- 🟢 Green "Running": Successfully built!
- 🔴 Red "Failed": Check logs for errors

### Step 7: Test Your App

Once the status shows **"Running"**:

1. Go to the **"App"** tab
2. You should see your video generator interface!
3. Test it:
   - Enter some text (e.g., "Hello world, this is a test video")
   - Select a voice
   - Click "Generate Video"
   - Wait for the video to generate

---

## Part 7: Troubleshooting Common Issues

### Issue 1: "Video clips folder not found"
**Solution**: Upload videos to the `video_clips` folder (Step 4)

### Issue 2: "TTS failed: Error"
**Solution**: 
- Check that API key is correctly set in Settings → Repository secrets
- Verify the key name is exactly `GOOGLE_API_KEY`
- Test your API key at https://aistudio.google.com/

### Issue 3: Build Fails
**Solution**:
- Check the Logs tab for specific error messages
- Common fixes:
  - Ensure `requirements.txt` is properly uploaded
  - Ensure `packages.txt` is properly uploaded
  - Try restarting the Space (Settings → Factory reboot)

### Issue 4: Out of Memory
**Solution**:
- Upgrade to better hardware (Settings → Change hardware)
- Or use fewer/smaller video clips

### Issue 5: Videos Upload Fails
**Solution**:
- Use Git LFS for files over 10MB
- Or use smaller video files
- Or compress videos before uploading

---

## Part 8: Optimize and Share

### Step 8: Upgrade Hardware (Optional)

For better performance:
1. Go to **Settings**
2. Scroll to **"Hardware"**
3. Choose a better option:
   - **CPU Upgrade** ($0.60/hour)
   - **T4 GPU** ($0.60/hour) - Recommended for faster processing
   - **A10G GPU** ($3/hour) - For very fast processing
4. Click **"Update"**

### Step 9: Share Your Space

Your Space is now live! Share it:
- **Direct URL**: `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`
- Click **"Share"** button to get embed codes
- Add to your portfolio or website

---

## Quick Checklist

Use this to ensure everything is set up:

- [ ] ✅ Created Hugging Face Space
- [ ] ✅ Uploaded `app.py`
- [ ] ✅ Uploaded `requirements.txt`
- [ ] ✅ Uploaded `packages.txt`
- [ ] ✅ Uploaded `README.md`
- [ ] ✅ Added `GOOGLE_API_KEY` to Repository secrets
- [ ] ✅ Uploaded video clips to `video_clips/` folder
- [ ] ✅ (Optional) Uploaded background music
- [ ] ✅ Space shows "Running" status
- [ ] ✅ Tested video generation successfully

---

## Need Help?

1. **Check Logs**: Always check the Logs tab for error messages
2. **Community**: Ask in [Hugging Face Discord](https://discord.gg/hugging-face)
3. **Documentation**: [Gradio Spaces Docs](https://huggingface.co/docs/hub/spaces-sdks-gradio)

---

## Summary of File Locations

After setup, your Space structure should look like:

```
your-space-name/
├── app.py                    ✅ Main application file
├── requirements.txt          ✅ Python dependencies
├── packages.txt             ✅ System dependencies  
├── README.md                ✅ Documentation
├── .gitignore               ✅ Git ignore rules
├── .gitattributes           ✅ LFS configuration
├── video_clips/             ✅ Your video files (REQUIRED!)
│   ├── clip1.mp4
│   ├── clip2.mp4
│   └── clip3.mp4
├── background_music/        ⭕ Optional music files
│   └── bgmusic.mp3
├── voice_over/              ⚙️ Auto-created by app
└── exports/                 ⚙️ Auto-created by app
```

**Legend:**
- ✅ = Required, you upload this
- ⭕ = Optional
- ⚙️ = Auto-created by the app

---

## 🎉 Congratulations!

You've successfully deployed your AI Video Generator to Hugging Face Spaces! 

Now you can create amazing videos with AI voiceovers and animated subtitles right from your browser.