FaceSwap Batch Tool

Modulare Bild-, Video- und Sprachverarbeitung auf Basis von InsightFace (buffalo_l + inswapper_128).

Voraussetzungen

• Python 3.12 oder 3.13
• FFmpeg im PATH (für Audio-Erhalt; ohne läuft die Verarbeitung, das Video hat dann aber keinen Ton)
• Modelle unter models/ — siehe models/README.md

Unter Windows: doppelklick auf run.bat. Das prüft der Reihe nach

1. Python 3.12/3.13 gefunden
2. Kernpakete (numpy, OpenCV, insightface, onnxruntime)
3. Modelle vorhanden und an der richtigen Stelle
4. ONNX-Provider (GPU/CPU)
5. FFmpeg im PATH
6. Eingabe\, Ausgabe\, face_library\ anlegbar und beschreibbar
7. Selbsttest: Modelle laden und eine echte Synthese-Seite ausführen
8. Reste abgebrochener Läufe aufräumen

Startkritische Probleme → Abbruch mit Erklärung. Nur Warnungen (kein FFmpeg, CPU-Modus) → Start läuft trotzdem.

Ohne Batch-Datei:

pip install -r requirements.txt
python check_environment.py     # optional, prüft alles
python face_swap.py

Qualitätsstellschrauben

Alle Filter arbeiten auf einer Gesichtsmaske aus den 5 InsightFace- Landmarken, nicht auf einem Rechteck um die BBox. Das verhindert, dass Haare, Hintergrund und Kleidung mitverändert werden.

Gemessen mit tests/measure_quality.py:

	Rechteck (alt)	Gesichtsmaske
Hintergrund verändert	27,2 %	2,1 %
Farbdrift pro Frame	0,14	0,10

config.json:

Schlüssel	Standard	Wirkung
face_mask_quality	true	Filter nur auf der Gesichtsform
color	true	LAB-Farbübergabe an den Original-Hautton
soft_blend	false	Standard aus – siehe Hinweis unten
enhance	true	lokales Unsharp-Masking
restoration	true	GFPGAN (nur wenn installiert)
ema_alpha_kps	0.40	Video-Glättung, siehe unten
occlusion_tolerance	3	Frames ohne Erkennung, die der Track verkraftet
min_swap_effect	0.008	Mindest-Wirkung, damit ein Swap gilt

Soft-Blend: warum er standardmäßig aus ist

soft_blend war früher aktiv und hat den Swap zu etwa zwei Dritteln zurückgenommen. Gemessen über den vollen Batch-Pfad (tests/probe_batch_identity.py, InsightFace-Embeddings als Identitätsmetrik): der Gewinn zur Quellperson lag bei +0,34 bis +0,53, mit abgeschaltetem Blend bei +0,81 bis +0,97.

Ursache ist die Kombination aus Blend und zu schmaler Gesichtsmaske: die Ellipse in build_face_mask() deckte nur ~30 % der BBox ab, 74 % der von inswapper veränderten Pixel lagen außerhalb und wurden mit dem Originalbild zurückgemischt — genau die Wangen-, Schläfen- und Kieferpartien, die die Identität tragen. Der Blend erzeugte zudem die Kante, die er beseitigen sollte (Nahtenergie/Innenenergie 1,38 mit gegen 1,18 ohne).

build_face_mask() nutzt deshalb jetzt einen breiteren Faktor (1,25 statt 0,80). Filter bleiben so auf der Gesichtsform, ohne den Swap zu beschneiden.

Aktivieren lässt sich soft_blend weiterhin — dann ist der Swap sichtbar schwächer. Voreingestellt bleibt er aus, weil inswappers eigener Paste-Back die Kanten bereits weich auslaufen lässt.

Video-Glättung: warum ema_alpha_kps und nicht die BBox

insightface/model_zoo/inswapper.py positioniert den Swap über target_face.kps — den 5 Landmarken — nicht über der BBox. Eine BBox-Glättung hat daher keinen Einfluss auf die Swap-Position.

Gemessen mit tests/calibrate_alpha.py:

α	Jitter	Nachführ-Lag
1,00	12,93 px	2 Frames
0,65	12,93 px	2 Frames
0,40	9,05 px	3 Frames
0,25	6,03 px	5 Frames

Zu glatt ist schlimmer als Jitter: der Track bleibt bei schneller Bewegung sichtbar stehen. 0,40 ist der gemessene Kompromiss.

Modelle

Zwei Dateien, zusammen ~855 MB:

Datei	Größe	Quelle
models/inswapper_128.onnx	529 MB	insightface v0.7
models/buffalo_l/*.onnx	326 MB	buffalo_l.zip → nach models/buffalo_l/ entpacken

Häufigster Installationsfehler: buffalo_l flach statt im Unterordner. check_environment.py erkennt das und gibt die passende move-Anweisung.

Modelle nicht ins Git

models/ ist rund 1,2 GB und war trotz .gitignore eingecheckt — das ließ jeden git clone scheitern. Falls noch im Versionsstand:

git rm -r --cached models/
git commit -m "Modelle aus dem Index entfernen (1,2 GB)"

Tests

Alle Fixtures sind prozedural gerenderte Kunstgesichter (keine echten Personen). Detektions-Scores liegen bei 0,7–0,8, sodass der echte Erkennungspfad gemessen wird.

# Schnell: je Audit-Befund ein Test (mit Modell, ~5 min auf 2 Kernen)
python tests/test_regressions.py

# Vollständig: Robustheit, Tracking, Ausfallpfade, Determinismus (~11 min)
python tests/test_robustness.py

# Qualität messen
python tests/measure_quality.py --tag masked

# Performance messen
python tests/measure_performance.py

Fixtures erzeugen: python tests/make_fixtures.py

Was die Tests abdecken

• A degenerierte Eingaben (1×1 px, schwarz, grau, 7:1-Panorama, None)
• B Tracking-Stabilität, Dropout-Recovery nach Verdeckung
• C Ausfallpfade: kein FFmpeg, defektes Video, Abbruch, Wiederaufnahme, leerer Ordner, defekte Dateien im Batch
• D Determinismus (Bild bitgleich, Video md5-gleich)
• R1–R17 Regressionen je gefundenem Fehler

Hinweise

• GFPGAN ist optional. Fehlt die Bibliothek, wird die Wiederherstellung übersprungen — kein Fehler, Bild- und Videofunktionen laufen weiter.
• Sprachklon (coqui-tts) wird lazy geladen.
• Unter Windows werden für Unicode-Pfade durchgehend die Helfer aus core/config.py verwendet (cv2_imread_unicode u. a.).