README.md

---
title: Face Swap Image To Video
emoji: 🎭
colorFrom: purple
colorTo: pink
sdk: docker
app_port: 7860
pinned: false
license: other
---

# Face Swap: Image → Video

Upload a face photo and a target video; the app swaps the face from your
photo onto every face it detects in the video, frame by frame, and
re-attaches the original audio.

It uses:
- **insightface** (`buffalo_l`) for face detection/analysis
- **inswapper_128.onnx** for the actual face swap
- **onnxruntime-gpu** to run on a GPU
- **ffmpeg** to remux the original audio back onto the output

This Space builds from a custom `Dockerfile` (lean `python:3.10-slim` base)
rather than the Gradio SDK's auto-build, which avoids compiling Python from
source and pulling in a huge C toolchain — the auto-build path was timing
out during `apt-get` on this dependency stack. Build should now take a few
minutes instead of 40+.

## Setup on Hugging Face

1. Create a new Space → SDK: **Docker** (not Gradio).
2. Upload all files in this folder (`Dockerfile`, `app.py`,
   `requirements.txt`, `README.md`) to the Space repo root.
3. In **Settings → Hardware**, select a **rented GPU** tier (e.g. T4 small,
   T4 medium, or A10G) — CPU Basic will work but will be very slow for
   video.
4. Build/restart the Space. On first launch it downloads:
   - the `buffalo_l` face analysis model (auto, via `insightface`)
   - `inswapper_128.onnx` (auto, via a Hugging Face Hub mirror — see below)

### If the download is slow

- The app already enables `hf_transfer` (parallel chunked downloads), which
  is usually a big speedup over a plain single-stream download.
- **Turn on Persistent Storage** in Settings → this is the biggest win: without
  it, the ~530 MB model gets re-downloaded every time the Space restarts or
  wakes from sleep. With it, you only pay for the slow download once.
- Check the Space logs — the app prints which mirror it's trying
  (`[model-download] trying ...`). If it's stuck on one mirror, that mirror
  may be throttled; you can reorder/edit `INSWAPPER_MIRRORS` in `app.py` to
  try a different one first, or download the file yourself and upload it
  directly to the Space root as `inswapper_128.onnx` (skips the download
  entirely).

### If the automatic model download fails

`inswapper_128.onnx` (~530 MB) isn't included in this zip because it's a
large binary model file, and its original hosting has moved around over
time. `app.py` tries a few known public mirrors on the Hub automatically.
If all of them fail (mirrors do occasionally disappear), just download the
file yourself from wherever you can find a trusted copy and drop it into
the Space's root folder as `inswapper_128.onnx` — the app checks for a
local copy first before trying to download anything.

## Files

| File               | Purpose                                          |
|--------------------|---------------------------------------------------|
| `Dockerfile`       | Lean build: python:3.10-slim + ffmpeg + pip deps |
| `app.py`           | Gradio UI + face-swap pipeline                   |
| `requirements.txt` | Python packages                                  |
| `README.md`        | This file / Space metadata header                |

## Responsible use

Only upload media you have the rights and consent to modify. Don't use
this to impersonate real people without their permission, create
non-consensual explicit content, or spread misinformation. You are
responsible for how you use the output.

## Local testing

```bash
pip install -r requirements.txt
python app.py
```

(You'll need `ffmpeg` installed locally too, and a CUDA-capable GPU +
matching drivers for `onnxruntime-gpu` to actually use the GPU — otherwise
it'll fall back to CPU.)