SETUP.md

# CogVideoX Keyframe Interpolation - Quick Setup

This directory contains the **bare minimum files** needed to run the CogVideoX Keyframe Interpolation Gradio app.

## 📁 Contents

```
CogVideoXInterp/
├── README.md                   # HuggingFace Spaces README
├── app.py                      # Main Gradio application
├── requirements.txt            # Python dependencies
├── cogvideox_interpolation/    # Core pipeline module
│   ├── datasets.py            # Dataset loading (not needed for inference)
│   └── pipeline.py            # Custom interpolation pipeline
└── SETUP.md                    # This file
```

**Total size:** ~64KB (model downloads separately)

---

## 🚀 Quick Start

### Local Setup

1. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

2. **Run the app:**
   ```bash
   python app.py
   ```

3. **Open browser:**
   Navigate to `http://localhost:7860`

### GPU Requirements

- **Minimum:** 16GB VRAM (RTX 4060 Ti 16GB, RTX 4080)
- **Recommended:** 24GB VRAM (RTX 3090, RTX 4090)

---

## 🤗 Deploy to HuggingFace Spaces

### Method 1: Web Upload

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Choose **Gradio** as SDK
4. Upload all files from this directory
5. Select GPU hardware (T4 minimum, A10G recommended)
6. Space will auto-deploy!

### Method 2: Git Push

```bash
# Create a Space on HuggingFace first, then:
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# Copy files
cp -r /path/to/CogVideoXInterp/* .

# Push
git add .
git commit -m "Initial commit"
git push
```

### HuggingFace Spaces Hardware Options

| Hardware | VRAM | Speed | Cost/hr |
|----------|------|-------|---------|
| CPU | 0GB | ❌ Won't work | Free |
| T4 | 16GB | ⚠️ Slow (5-8 min) | ~$0.60 |
| A10G | 24GB | ✅ Good (2-4 min) | ~$3.15 |
| A100 | 40GB | ✅ Fast (1-2 min) | ~$7.00 |

**Note:** Model will auto-download on first run (~20GB)

---

## 📝 Usage

1. **Load Model** - Enter model path or use default `feizhengcong/CogvideoX-Interpolation`
2. **Upload Images** - Provide start and end frame
3. **Write Prompt** - Describe the motion/transition
4. **Generate** - Wait 2-5 minutes for video

### Example Prompts

✅ "A person walks forward slowly, their body moving naturally with each step"

✅ "The camera smoothly pans from left to right, revealing the scene"

✅ "A dancer gracefully transitions from one pose to another"

---

## 🔧 Troubleshooting

### Out of Memory

Reduce parameters in the app:
- Frames: 49 → 25
- Steps: 50 → 30

### Model Download Fails

Check internet connection. Model is ~20GB and downloads to:
- Linux/Mac: `~/.cache/huggingface/`
- Windows: `C:\Users\USERNAME\.cache\huggingface\`

### Import Errors

Make sure all files from this directory are in the same location, especially the `cogvideox_interpolation/` folder.

---

## 📚 More Information

For detailed documentation, see the parent repository at:
https://github.com/feizc/CogvideX-Interpolation

**Model:** https://huggingface.co/feizhengcong/CogvideoX-Interpolation

**License:** Apache 2.0