README.md

Matrix-Game-2.0 Hugging Face Space Setup

🚀 Quick Setup Guide

1. Create the Space

• Go to Hugging Face Spaces
• Click "Create new Space"
• Choose Gradio as the SDK
• IMPORTANT: Set Hardware to GPU (A100) - this is crucial!

2. Upload Files

Upload these three files to your Space:

1. app.py - The main application (use the clean version provided)
2. requirements.txt - Dependencies list (properly formatted)
3. README.md - This file (optional)

3. Space Configuration

In your Space settings, ensure:

• SDK: Gradio
• Hardware: A100 GPU (required!)
• Visibility: Public or Private (your choice)

4. Key Improvements Made

✅ Fixed Issues:

• Proper requirements.txt formatting (each dependency on new line)
• Added missing dependencies (opencv, xformers, etc.)
• Used @spaces.GPU decorator for proper GPU allocation
• Simplified model downloading and setup
• Added proper error handling and timeouts
• Reduced frame limits for HF Spaces constraints

✅ HF Spaces Optimizations:

• Pre-download model weights efficiently
• Use temporary directories properly
• Clean up resources after generation
• Progress indicators for user feedback
• GPU memory management

5. Usage Tips

• First run: Will take 2-3 minutes to download model (~10GB)
• Subsequent runs: Much faster (model cached)
• Recommended: 25-75 frames for reasonable generation time
• Input images: Works best with landscapes/scenes, max 512px

6. Troubleshooting

If you get "CUDA out of memory":

• Reduce number of frames (try 25-50)
• Use smaller input images
• Restart the Space

If model download fails:

• Check internet connection in Space logs
• Verify you're using A100 GPU hardware
• Try restarting the Space

If generation is slow:

• This is normal! Video generation is compute-intensive
• A100 GPU should handle 50 frames in ~2-3 minutes
• Consider reducing frames for faster results

7. Expected Performance

• Model download: 2-3 minutes (first time only)
• 25 frames: ~1 minute generation
• 50 frames: ~2-3 minutes generation
• 75+ frames: 4-5+ minutes generation

---

🎮 What is Matrix-Game-2.0?

Matrix-Game-2.0 is an interactive world foundation model that generates real-time video content based on input images. It uses advanced diffusion techniques to create dynamic, controllable video sequences that respond to user interactions.

Key Features:

• Real-time video generation (up to 25 FPS)
• Interactive control through keyboard/mouse inputs
• Long video generation capability
• Fine-grained scene control and evolution

---

Built with ❤️ for the Hugging Face community