README.md

---
title: FaceOff-FaceSwapper
emoji: 🎭
colorFrom: purple
colorTo: blue
sdk: gradio
sdk_version: "5.50.0"
app_file: app.py
pinned: true
license: other
suggested_hardware: zero-a10g
---

# FaceOff-FaceSwapper

Hugging Face Space for the **V3 persistent-template** head-swap workflow built on LTX-Video.

## How it works

1. Upload a **guide video** (the body/performance you want to keep)
2. Upload a **reference face image** (the identity to transfer)
3. Write or paste a **text prompt** in the structured format below
4. Click **Generate**

The reference face is composited into a green chroma side-strip on every frame of the
guide video, giving the model continuous identity conditioning. The composed video is
then re-rendered (video-to-video) with the swapped head. The strip is cropped from the
final output automatically.

### Prompt format

```
head_swap:
FACE: <detailed identity description from the reference image>
ACTION: <performance description from the guide video — body, clothing, movement only>
```

**Example:**
```
head_swap:
FACE: Male, fair skin, approximately 25-30 years old, short light brown hair,
blue eyes, clean-shaven, athletic build, wearing a navy blue t-shirt.

ACTION: A person walks confidently toward the camera in an outdoor plaza,
arms crossed, smiling.
```

## Models used

| Component | Source |
|-----------|--------|
| Full pipeline (transformer, VAE, text encoder, scheduler) | [Lightricks/LTX-Video-0.9.8-13B-distilled](https://huggingface.co/Lightricks/LTX-Video-0.9.8-13B-distilled) |
| BFS head-swap LoRA | [Alissonerdx/BFS-Best-Face-Swap-Video](https://huggingface.co/Alissonerdx/BFS-Best-Face-Swap-Video) (`ltx-2/head_swap_v2_multimodes.safetensors`) |
| Auto-describe | [Salesforce/blip2-opt-2.7b](https://huggingface.co/Salesforce/blip2-opt-2.7b) |
| Face alignment | InsightFace `buffalo_l` (CPU) |
| Optional enhancement | GFPGAN v1.4 |

## Logs

**Container logs** (runtime output):
```bash
curl -N \
     -H "Authorization: Bearer $HF_TOKEN" \
     "https://api.hf.space/v1/Jds20001/FaceOff-FaceSwapper/logs/run"
```

**Build logs** (Docker build output):
```bash
curl -N \
     -H "Authorization: Bearer $HF_TOKEN" \
     "https://api.hf.space/v1/Jds20001/FaceOff-FaceSwapper/logs/build"
```

## Ethical use

This tool is intended for **filmmakers, VFX artists, and researchers**.
You must have explicit consent from any person whose likeness you process.
See the [full model card](https://huggingface.co/Alissonerdx/BFS-Best-Face-Swap-Video) for the complete terms.