README.md

metadata

title: FaceSwapLite
emoji: 🎃
colorFrom: purple
colorTo: red
sdk: gradio
sdk_version: 4.44.1
app_file: app.py
pinned: false
license: mit

🎃 FaceSwapLite 🎃

Professional AI-Powered Face Swapping for Videos with Advanced Quality Enhancements

Transform faces in videos with state-of-the-art AI models and professional-grade post-processing.

✨ Features

Core Technology

• InsightFace: Industry-leading face detection and recognition
• INSwapper: High-quality face swapping with 128-dimensional embeddings
• SCRFD: Fast and accurate face detection
• ArcFace: Robust face recognition and matching

� NEW: Professional Quality Enhancements

GFPGAN Face Restoration

• Automatically enhances swapped faces
• Fixes artifacts and blur
• Improves skin texture and details
• Maintains natural appearance

Advanced Post-Processing

• Smart Color Correction: Matches lighting and skin tone automatically
• Temporal Smoothing: Eliminates flickering and frame jitter
• Detail Preservation: Maintains sharpness with intelligent sharpening
• Aggressive Face Tracking: Stable swaps during fast motion and occlusions

Anti-Flickering Technology

• Frame-by-frame face tracking with IOU matching
• Occlusion tolerance (handles objects passing in front of faces)
• Cached swap results for stability during detection failures
• Adaptive confidence thresholds based on tracking history

🚀 Quick Start

Simple Mode (Recommended)

1. Upload your target video
2. Upload ONE source face image (the face you want to insert)
3. Click "Start processing"
4. Download your result!

The app automatically replaces the first/main face in the video.

Advanced Mode

1. Upload your target video
2. Upload Target Face (specific face to replace from video)
3. Upload Source Face (new face to insert)
4. Adjust threshold if needed (default 0.5 works best)
5. Click "Start processing"

🎨 Quality Enhancement Pipeline

Original Video Frame
        ↓
Face Detection (SCRFD)
        ↓
Face Recognition (ArcFace)
        ↓
Face Swap (INSwapper 128)
        ↓
GFPGAN Enhancement ★ NEW
        ↓
Color Correction
        ↓
Detail Sharpening
        ↓
Temporal Smoothing
        ↓
Professional Output

🚀 Quick Start

Online Usage

Visit the Hugging Face Space to use the application directly in your browser.

Local Installation

1. Clone the repository

git clone https://huggingface.co/spaces/minhho/FaceSwapLite-1.0
cd FaceSwapLite-1.0

2. Install dependencies

pip install -r requirements.txt

3. Download the face swapping model

   • Download inswapper_128.onnx from InsightFace Model Zoo
   • Place it in the root directory

4. Run the application

python app.py

📖 Usage

Web Interface

1. Upload a target video (MP4 format)
2. For each face you want to swap:
   • Upload the target face from the video (face to replace)
   • Upload the source face (replacement face)
   • Adjust the transparency slider (0.0-1.0, default: 0.2)
3. Click "⏳ Start processing"
4. Download the result video

Command Line

python script.py --video path/to/video.mp4 --face path/to/target_face.jpg,path/to/source_face.jpg,0.2

Arguments:

• --video: Path to the target video
• --face: Face swap configuration (can be used multiple times)
  • Format: target_face,source_face,threshold
• --force_cpu: Force CPU execution (optional)
• --colab_performance: Optimize for Google Colab (optional)

⚙️ Configuration

Execution Modes

The application automatically detects and uses the best available execution provider:

• CPU Mode: Default fallback, works on all systems
• CUDA Mode: NVIDIA GPU acceleration (recommended for best performance)
• CoreML Mode: Apple Silicon optimization
• TensorRT Mode: Advanced NVIDIA GPU optimization

Performance Tips

• For faster processing, use a CUDA-compatible GPU
• Reduce video resolution for quicker processing
• Process shorter video segments for testing
• On Colab, use the --colab_performance flag

🛠️ Technical Details

Architecture

• Face Detection: SCRFD (Sample and Computation Redistributed Face Detection)
• Face Recognition: ArcFace with ResNet-50 backbone
• Face Swapping: INSwapper model (128x128)
• Backend: ONNX Runtime for optimized inference

Requirements

• Python 3.8+
• FFmpeg (for video processing)
• 8GB+ RAM recommended
• GPU with 4GB+ VRAM (optional, for faster processing)

📁 Project Structure

FaceSwapLite/
├── app.py                 # Gradio web interface
├── refacer.py            # Core face swapping logic
├── script.py             # Command-line interface
├── requirements.txt      # Python dependencies
├── inswapper_128.onnx   # Face swapping model
├── recognition/          # Face detection and recognition modules
│   ├── scrfd.py         # Face detector
│   ├── arcface_onnx.py  # Face recognition
│   └── ...
└── out/                  # Output directory for processed videos

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• InsightFace for the face analysis models
• ONNX Runtime for efficient model inference
• Gradio for the web interface

⚠️ Disclaimer

This software is provided for educational and research purposes only. Please use responsibly and ethically. Do not use this tool for creating misleading or harmful content. Always obtain proper consent before swapping someone's face.

📧 Contact

For questions or support, please open an issue on the GitHub repository.

---

Note: Make sure you have the required model files (inswapper_128.onnx) before running the application. The InsightFace models will be automatically downloaded on first run.