prstyaDev/FaceFusion-Face-Swap-Hyperswap

👽 FaceFusion Face Swap HYPERSWAP (CPU)

Industry leading face manipulation platform with built-in quality analysis

---

✨ Features

🔄 Face Swapping

• Multiple Models Support:
  • Hyperswap_1b_256.onnx - Best quality in most cases (recommended)
  • Hyperswap_1a_256.onnx - Most stable, fewer artifacts
  • Inswapper-128 - Works great with face enhancer
• High Quality PNG Output - No quality loss
• Face Selector - Choose specific faces with order/index control
• CPU-Based Processing - Unlimited usage, no GPU quota

✅ NEW: Face Quality Checker

Analyze source images before swapping to ensure optimal results!

Quality Checks:

• 🔍 Blur Detection - Ensures image sharpness
• 💡 Lighting Quality - Checks for proper exposure
• 📏 Face Size - Validates face is large enough
• 📐 Face Angle - Detects extreme poses
• 👁️ Occlusion Detection - Checks for obstructions

Benefits:

• Get instant feedback on image quality
• Receive specific recommendations
• Avoid poor quality swaps
• Save time with pre-validation

Read Full Documentation →

🎨 Face Enhancement

• GPEN-BFR-512 - Best quality enhancer (70-80% strength recommended)
• Multiple enhancement models available
• Optional feature for better results

---

🚀 Quick Start

Option 1: Use This Space Directly

1. Upload your source image (the face you want to use)
2. (Optional) Click "Check Face Quality" to validate image quality
3. Upload your target image (where you want to apply the face)
4. Select face swap model (Hyperswap_1b_256 recommended)
5. Click "Start" and wait for processing
6. Download your result!

Option 2: Duplicate to Your Account (Recommended)

Why duplicate?

• ⚡ No queue waiting
• 🔒 Private space for your use
• 🆓 100% FREE on Hugging Face
• ⚙️ Full control (can restart if needed)

How to duplicate:

1. Click the 3 dots menu (top right corner)
2. Select "Duplicate this Space"
3. Choose Private visibility
4. Click Create
5. Enjoy unlimited private usage!

---

📖 Usage Guide

Face Quality Checker (New!)

1. Upload Source Image first
2. Click "Check Face Quality" button
3. Review the quality report:
   • ✅ Green = Good quality
   • ⚠️ Yellow = Acceptable with warnings
   • ❌ Red = Poor quality, improvements needed
4. Follow recommendations if needed
5. Proceed with face swapping if quality is good

Example Report:

## ✅ Overall Quality: GOOD

### Quality Checks:
✅ Blur Detection: Image sharpness is excellent (Score: 156.3)
✅ Lighting Quality: Lighting is optimal (Brightness: 128.5)
⚠️ Face Size: Face is small (142px), quality may be reduced
✅ Face Angle: Face angle is frontal (8.2°)
✅ Occlusion Detection: Face is clearly visible (Score: 0.96)

Model Recommendations

🏆 Hyperswap_1b_256.onnx (Recommended)

• Best quality in most cases
• Use WITHOUT face enhancer
• Known issue: Occasionally fails on specific faces (try 1a if this happens)

🛡️ Hyperswap_1a_256.onnx (Most Stable)

• Most reliable, fewer bugs
• Use WITHOUT face enhancer
• Good fallback if 1b fails

⚡ Inswapper-128

• Classic model, proven results
• Use WITH GPEN-BFR-512 enhancer at 70-80% strength
• Slower but very reliable

Face Selection

• Use Face Order to choose which face to swap
• Only the first face in the given order will be selected
• Adjust Face Index if multiple faces are detected

---

💡 Tips for Best Results

Image Quality

✅ Use well-lit, frontal photos
✅ Ensure faces are clear and sharp
✅ Avoid extreme angles or poses
✅ Face size should be >200px
✅ Remove obstructions (hats, hands, glasses)

Processing Tips

• First try Hyperswap_1b without enhancer
• If result has artifacts, try Hyperswap_1a
• For classic workflow, use Inswapper-128 + GPEN-BFR-512
• Check face quality BEFORE swapping to save time
• If processing takes >30 seconds, space may be frozen - restart it

---

⚙️ Technical Details

System

• CPU-Based Processing - No GPU required
• Python 3.12 - Latest stable version
• Gradio 5.50.0 - Modern web interface
• Based on FaceFusion v3.3.2 - Modified Edition

Models

• Multiple face swap models (ONNX format)
• Multiple face enhancer options
• All models run efficiently on CPU

Output

• High quality PNG format
• No compression artifacts
• Preserves image dimensions

---

🐛 Troubleshooting

Space is frozen / taking too long (>30 sec)

• This is a known Gradio bug
• Solution: Go to Settings → Restart the Space
• Note: You need to duplicate the space to your account first

Face swap doesn't work

• Try different model (Hyperswap_1a instead of 1b)
• Check face quality first with Quality Checker
• Ensure both images have clearly visible faces
• Try without face enhancer first

Poor quality results

• Run Face Quality Checker before swapping
• Follow the recommendations provided
• Use better source images (frontal, well-lit, sharp)
• Try with face enhancer (GPEN-BFR-512 at 70-80%)

Multiple faces detected

• Use Face Order to select the correct face
• Adjust Face Index if needed
• Quality Checker will analyze the first face only

---

📚 Documentation

• Face Quality Checker Guide - Detailed quality checker documentation
• Implementation Summary - Technical implementation details
• FaceFusion Docs - Official FaceFusion documentation

---

🎯 Use Cases

• Portrait photography enhancement
• Social media content creation
• Film and video production
• Creative projects
• Research and development

---

⚠️ Responsible AI Usage

Please use this technology responsibly and ethically:

• ✅ Obtain consent before swapping someone's face
• ✅ Clearly disclose AI-generated content
• ✅ Respect privacy and copyright
• ✅ Follow local laws and regulations
• ❌ Do not create misleading or harmful content
• ❌ Do not use for fraud or deception
• ❌ Do not violate others' rights

---

📄 License

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

---

🙏 Acknowledgments

• Based on FaceFusion by the FaceFusion team
• Modified Edition with additional features
• Face Quality Checker - Custom implementation
• Hosted on Hugging Face Spaces

---

💬 Support & Community

Having issues or questions?

1. Check the Troubleshooting section
2. Read the documentation
3. Duplicate the space for better performance
4. Check FaceFusion's official docs

---

🚀 Happy Face Swapping!

Remember:

• Use Face Quality Checker before swapping
• Duplicate space for unlimited private use
• Start with Hyperswap_1b_256 model
• Follow responsible AI practices

Enjoy creating amazing content! 👽✨