README.md

metadata

title: RealFace350
emoji: 🎭
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.44.1
python_version: 3.12
app_file: app.py
pinned: true
suggested_hardware: a10g-small

FaceFusion 3.5.0

AI-powered face swapping application using FaceFusion 3.5.0 on HuggingFace Spaces.

Overview

FaceFusion is a comprehensive face swapping and enhancement tool that uses AI technology to perform:

• Face swapping: Replace faces in images and videos
• Face enhancement: Improve facial details and quality
• Frame enhancement: Upscale and enhance video frames
• Background removal: Extract subjects from backgrounds
• Batch processing: Process multiple files efficiently

Features

Core Functionality

• 🎭 Face Swapping: High-quality face replacement in images and videos
• ✨ Face Enhancement: AI-powered facial detail improvement
• 🎨 Frame Enhancement: Video quality upscaling
• 🖼️ Background Removal: Clean subject extraction
• 📦 Batch Processing: Efficient multi-file processing

Technology Stack

• FaceFusion Version: 3.5.0
• Python Version: 3.12 (required)
• Gradio SDK: 5.44.1
• ONNX Runtime: 1.23.2
• OpenCV: 4.12.0.88
• Execution Mode: Auto-detect (GPU/CPU)

🚀 GPU Acceleration

Automatic GPU/CPU Detection

This Space automatically detects available hardware:

• ✅ GPU Available: Uses CUDA for faster processing (10-20x speedup)
• ⚠️ No GPU: Falls back to CPU mode (slower but free)

Supported GPUs

• NVIDIA T4 (16GB VRAM) - $0.40-0.60/hour
• NVIDIA A10G (24GB VRAM) - $1.00-1.50/hour ⭐ Recommended
• NVIDIA A100 (40GB VRAM) - For enterprise workloads

How to Enable GPU

1. Go to Space Settings
2. Select Hardware → Choose GPU tier (e.g., "A10G small")
3. Click Save → Space will restart with GPU

Performance Comparison

Task	CPU Mode	GPU (A10G)	Speedup
Single image (1080p)	~10-20 sec	~1-3 sec	10-20x
Video (30s, 1080p)	~10-20 min	~1-2 min	10-20x

Cost

• CPU Mode: Free (but slower)
• GPU Mode: $0.40-1.50/hour (only when running)

System Requirements

Minimum (CPU Mode)

• Python: 3.12
• RAM: 8 GB
• GPU: Not required
• Cost: Free

Recommended (GPU Mode)

• Python: 3.12
• GPU: NVIDIA A10G (24GB VRAM) ⭐
• RAM: 16 GB
• Cost: ~$1.00/hour

Dependencies

• FFmpeg (for video processing)
• ONNX Runtime (with CUDA support for GPU)
• OpenCV
• Gradio (for web interface)
• PyTorch (for GPU detection)

Installation & Usage

On HuggingFace Spaces

This Space is pre-configured and ready to use. Simply:

1. Open this Space
2. Wait for the automatic installation (first launch only)
3. Use the Gradio interface to upload and process your media

Local Installation

If you want to run this locally:

# Clone the repository
git clone https://github.com/facefusion/facefusion
cd facefusion

# Update pip (required for FaceFusion 3.5.0)
python -m pip install --upgrade "pip>=25.0"

# Install dependencies
python install.py --onnxruntime default --skip-conda

# Launch the UI
python facefusion.py run --execution-providers cpu

Directory Structure

When uploaded to HuggingFace Spaces, the structure should be:

/
├── app.py                          # HuggingFace Spaces launcher
├── README.md                       # This file
├── .gitattributes                  # Git LFS configuration
└── Original_facefusion-3.5.0/      # FaceFusion source code
    ├── facefusion.py               # Main entry point
    ├── install.py                  # Installation script
    ├── requirements.txt            # Python dependencies
    ├── facefusion/                 # Core modules
    ├── facefusion.ini              # Configuration file
    └── ...

Usage Guide

Basic Workflow

1. Upload Source: Upload the image/video you want to modify
2. Upload Target: Upload the face image you want to use
3. Configure Settings: Adjust processing parameters as needed
4. Process: Click the process button
5. Download: Download the result

Supported Formats

• Images: JPG, PNG, BMP, WEBP
• Videos: MP4, AVI, MOV, MKV, WEBM

Processing Modes

• CPU Mode: Default (slower but free)
• GPU Mode: Available with paid GPU hardware (10-20x faster)

Performance Notes

CPU Mode

• Processing Speed: Slower than GPU mode
• Recommended: Use for images or short video clips
• Video Processing: May take several minutes depending on length
• Cost: Free

GPU Mode

• Processing Speed: 10-20x faster than CPU
• Recommended: For long videos or batch processing
• Video Processing: Significantly faster (1-2 minutes for 30s 1080p video)
• Cost: $0.40-1.50/hour depending on GPU tier

Optimization Tips

• Use lower resolution source materials when possible
• Process shorter video segments for faster results
• Consider batch processing for multiple files
• Enable GPU for faster processing (see "GPU Acceleration" section)

Limitations

HuggingFace Spaces Constraints

• Free Tier: CPU only (no GPU acceleration)
• Paid Tier: GPU available ($0.40-1.50/hour)
• Memory: Limited to Space tier allocation
• Timeout: Long-running processes may timeout
• Storage: Temporary file storage only

FaceFusion Constraints

• Face Detection: Requires clear, front-facing faces
• Video Length: Very long videos may exceed processing limits
• Quality: Both CPU and GPU modes produce high quality results (GPU is just faster)

Troubleshooting

Common Issues

Issue: "FaceFusion directory not found"

• Solution: Ensure Original_facefusion-3.5.0 is uploaded to the Space

Issue: "Installation failed"

• Solution: Check the logs for specific dependency errors

Issue: "Processing timeout"

• Solution: Try shorter videos or lower resolution inputs

Issue: "Out of memory"

• Solution: Use smaller input files or lower processing settings

References

Official Resources

• FaceFusion GitHub: https://github.com/facefusion/facefusion
• FaceFusion Documentation: https://github.com/facefusion/facefusion/wiki
• HuggingFace Spaces Docs: https://huggingface.co/docs/hub/spaces

Related Spaces

• Sample Implementation: https://huggingface.co/spaces/ddeweese/facefusion2.6_copy

License

FaceFusion is licensed under the terms specified in the original repository. Please refer to the LICENSE file in the Original_facefusion-3.5.0 directory.

Credits

• FaceFusion: Original project by the FaceFusion team
• HuggingFace Spaces: Hosting platform
• Gradio: Web interface framework

Version History

• v3.5.0: Current version with Python 3.12 support
• Features: Face swapping, enhancement, batch processing
• Platform: HuggingFace Spaces with CPU execution

---

Note: This Space automatically detects GPU availability. For faster processing, enable GPU hardware in Space Settings. Free tier users can still use CPU mode at no cost.