FaceSwap-Pro

Pipeline local y modular de reemplazo facial con GPU NVIDIA. Mantiene los flujos por fotograma existentes y añade un backend temporal nativo para DreamID-V sobre Wan 2.1 1.3B. La etiqueta visible es configurable por perfil; el perfil DreamID-V para RTX 5070 Ti no dibuja marcas sobre los fotogramas y conserva un manifiesto JSON separado.

Backends incluidos

Backend	Generador	Geometría	Estado
insightface_inswapper	INSwapper 128	Ninguna dentro del generador	Compatible y rápido
insightface_inswapper_mediapipe_mesh	INSwapper 128	Postproceso por malla MediaPipe	Compatible, no 3D-aware generativo
hififace_3dmm	HifiFace 256	Identidad condicionada por 3DMM dentro del generador	3DMM-aware real
dreamid_v	DreamID-V + Wan 2.1 1.3B	Diffusion Transformer temporal sobre clips	Backend de vídeo, 480p/720p

El alias histórico mediapipe_3d_hybrid permanece para no romper YAML antiguos, pero emite una advertencia de obsolescencia. El nombre era impreciso porque MediaPipe solo deformaba la salida 2D después de generarla.

Arquitectura

FaceAnalyzer ───────────────┐
                           ├─► tracking y selección de identidad
FaceGenerator / FaceSwapper┘
        │
        ├─ tracking multiinstancia (actor + reflejos)
        ├─ INSwapper 128
        ├─ INSwapper + postproceso por malla
        └─ HifiFace + extractor 3DMM + Semantic Facial Fusion
                                      │
                                      ▼
                      máscara aprendida / composición ROI
                                      │
                                      ▼
                              NVENC + manifiesto

VideoSwapBackend
        └─ DreamID-V Faster + Wan 2.1 1.3B
                    │
                    ├─ banco de referencias por pose/calidad
                    ├─ tracking real del sujeto objetivo
                    ├─ ventanas solapadas + worker persistente
                    ├─ stitching guiado por flujo
                    ├─ composición selectiva con oclusiones
                    └─ codificación final + métricas + C2PA/manifiesto

Las capacidades del modelo se declaran mediante ModelCapabilities:

• geometry_conditioning: geometría usada dentro del generador;
• geometry_postprocess: corrección aplicada después de generar;
• truly_3d_aware: verdadero únicamente para condicionamiento interno conocido.

Instalación base

En Windows/NVIDIA se recomienda el instalador del proyecto, que evita que la dependencia histórica de InsightFace vuelva a introducir onnxruntime CPU:

powershell -ExecutionPolicy Bypass -File .\scripts\setup_windows.ps1
conda activate FaceSwap-Pro
faceswap-pro doctor

Si el entorno ya existe y solo vas a actualizar el código, reinstala FaceSwap-Pro con --no-deps después de asegurar sus dependencias; no uses un pip install -e . normal sobre un entorno NVIDIA con ORT GPU porque pip puede intentar satisfacer InsightFace con la distribución CPU onnxruntime.

El instalador base prepara también el backend opcional por malla salvo que se use -SkipMeshAssist. MediaPipe queda fijado a 0.10.21, compatible con el nuevo backend de ControlNet Aux.

Fine-Tuning de Difusión: SDXL/FLUX + LoRA + ControlNet

En Windows/NVIDIA usa el instalador dedicado dentro del entorno Conda existente:

conda activate FaceSwap-Pro
powershell -ExecutionPolicy Bypass -File .\scripts\setup_diffusion_backend_windows.ps1

Este flujo fija las combinaciones sensibles de MediaPipe/ControlNet Aux y TensorBoard/protobuf, conserva onnxruntime-gpu sin reinstalar ORT CPU y configura Accelerate en BF16 cuando la GPU lo admite. Valida después con:

faceswap-pro doctor --diffusion

doctor muestra este backend en diffusion_finetuning_backends y detalla SDXL/FLUX en la sección diffusion_finetuning; no se mezcla con model_backends porque es un servicio separado de entrenamiento/generación. Consulta docs/diffusion_finetuning_backend.md.

La generación de difusión admite target_reference para seleccionar una identidad concreta del vídeo. Con inputs/target_faces/target.jpg, InsightFace sigue únicamente a esa persona, SDXL/FLUX genera una ROI facial y el resultado se recompone sobre el frame original. Las demás personas permanecen sin modificar; si el objetivo no aparece, se conserva el frame.

Preparar HifiFace 3DMM

La integración usa la implementación externa MIT xuehy/HiFiFace-pytorch. El código y los pesos no se redistribuyen dentro de este ZIP.

Los recursos auxiliares se guardan en models/hififace/auxiliary; no se usa un directorio llamado aux, porque AUX es un nombre reservado en Windows.

1. Instala juntos una build CUDA de PyTorch y su torchvision compatible con tu controlador y GPU.
2. Instala las dependencias de soporte:

python -m pip install -e ".[hififace3d]"

3. Clona la implementación. En Windows no uses un git clone normal: el repositorio contiene AdaptiveWingLoss/aux.py y AUX es un nombre reservado por NTFS. El instalador scripts/setup_windows.ps1 ya aplica automáticamente un checkout compatible. Para hacerlo manualmente:

git clone --depth 1 --no-checkout `
  https://github.com/xuehy/HiFiFace-pytorch.git `
  .\third_party\HiFiFace-pytorch

git -C .\third_party\HiFiFace-pytorch config core.protectNTFS false
git -C .\third_party\HiFiFace-pytorch sparse-checkout set --no-cone `
  "/*" "!/AdaptiveWingLoss/aux.py"
git -C .\third_party\HiFiFace-pytorch checkout --force

4. Descarga desde las fuentes indicadas por esa implementación:

models/hififace/
├── standard_model/
│   └── generator_320000.pth
└── auxiliary/
    ├── Deep3DFaceRecon/epoch_20_new.pth
    ├── arcface/ms1mv3_arcface_r100_fp16_backbone.pth
    └── BFM/
        ├── 01_MorphableModel.mat
        ├── BFM_exp_idx.mat
        ├── BFM_front_idx.mat
        ├── BFM_model_front.mat
        ├── Exp_Pca.bin
        ├── facemodel_info.mat
        ├── select_vertex_id.mat
        ├── similarity_Lm3D_all.mat
        └── std_exp.txt

BFM requiere obtener los archivos bajo sus propias condiciones. Usa únicamente checkpoints de una fuente confiable: los checkpoints PyTorch pueden contener datos serializados ejecutables.

5. Valida todo el perfil antes de procesar:

faceswap-pro doctor --config .\config\quality_3dmm.yaml

El bloque hififace_3dmm.ready debe ser true.

Preparar DreamID-V para GPU NVIDIA de 16 GB

DreamID-V puede usar el mismo entorno Conda que los demás backends. El instalador selectivo evita duplicar OpenCV u ONNX Runtime CPU e instala una ruta SDPA nativa que prioriza cuDNN/Flash/Efficient Attention, conserva las longitudes reales y evita el fallback matemático extremadamente lento. Consulta docs/dreamidv.md para la estructura completa.

El perfil quality_dreamidv.yaml usa dreamidv_faster.pth, 832×480, 49 fotogramas y 16 pasos. El perfil speed_dreamidv.yaml conserva la misma resolución pero usa 8 pasos y 5 fotogramas de solape para pruebas o vídeos largos.

En GPU de 16 GB, los perfiles alternan la residencia del DiT y del VAE: el DiT sale de CUDA durante la codificación/decodificación VAE y el VAE sale durante la difusión. El VAE se ejecuta en BF16, el modelo se mueve una sola vez por etapa y la salida se codifica por fotograma, evitando una copia FP32 del clip completo.

La versión 0.5.4 conserva los mismos pasos, resolución, guía y solape de cada perfil. Optimiza únicamente trabajo redundante: Q/K/V se entregan a SDPA como vistas cuando el kernel lo admite, RoPE y embeddings invariantes se reutilizan entre las dos pasadas de guidance, y los tensores pequeños de UniPC evitan rutas CPU innecesarias. Cada optimización tiene fallback automático al comportamiento compatible del checkout externo. La revisión 0.5.4 también hace las cachés compatibles con torch.inference_mode y garantiza que las cachés dependientes del clip se liberen antes de volver a cargar el VAE.

DWPose global se guarda en .faceswap_cache/dreamidv_pose junto al destino y se invalida si cambia el vídeo, FPS, número de frames o modelos ONNX. Durante una ejecución, un productor acotado prepara los siguientes clips mientras la GPU procesa el actual; esto no modifica los frames ni el orden de generación.

Valida primero los archivos y la GPU:

faceswap-pro doctor --config .\config\quality_dreamidv.yaml

Ejecuta:

faceswap-pro run --config .\config\quality_dreamidv.yaml

Para una ejecución más rápida:

faceswap-pro run --config .\config\speed_dreamidv.yaml

El backend divide vídeos largos en ventanas 4n+1 solapadas y desplaza fronteras a cortes de escena. Primero precalcula DWPose para todos los clips en un proceso separado; después cierra ese proceso, libera su VRAM y carga DreamID-V una sola vez. InsightFace también libera sus sesiones GPU tras completar el tracking. El worker registra el backend SDPA que realmente ejecutó cada forma de atención; los perfiles incluidos desactivan MATH, de modo que una incompatibilidad de kernel falla rápido en vez de consumir muchas horas. Si el worker de difusión falla, se reinicia de forma controlada en lugar de degradar silenciosamente a la CLI lenta. La referencia objetivo se usa para seguir a la persona correcta y la salida se recompone únicamente dentro de sus máscaras temporales. Si la misma identidad aparece directamente y reflejada en un espejo, ambas regiones se incluyen en la composición.

Cada ejecución temporal genera también métricas JSON, una hoja visual entrada/salida, hashes cacheados de modelos y C2PA opcional. Consulta docs/mejoras_calidad_2026.md para el mapa completo.

Ejecutar

Flujo actual, sin cambios

faceswap-pro run --config .\config\quality.yaml

INSwapper asistido por malla

faceswap-pro run --config .\config\quality_mesh_assisted.yaml

Generación condicionada por 3DMM

faceswap-pro run --config .\config\quality_3dmm.yaml

quality_3d.yaml es un alias legible del perfil quality_3dmm.yaml.

Espejos y varias apariciones del sujeto

Todos los perfiles incluidos permiten dos apariciones simultáneas de la identidad objetivo mediante:

tracking:
  max_target_faces: 2

Cada aparición mantiene una trayectoria, suavizado y flujo óptico independientes; el orden cambiante del detector no mezcla el rostro directo con su reflexión. En el pipeline por fotogramas se genera y compone un reemplazo por rostro. En DreamID-V la máscara DWPose se cruza con el tracking antes de la difusión: se conserva el componente preciso del actor principal y se añaden máscaras para las apariciones coincidentes que falten, como reflejos. La composición final vuelve a usar la misma unión para conservar intactas las demás personas y el fondo.

Usa max_target_faces: 1 para recuperar el comportamiento conservador anterior, o un valor mayor cuando una escena contenga varios espejos. El límite se aplica solo a rostros cuya similitud supere identity.target_min_similarity.

Rutas personalizadas

--model-path admite archivos o directorios:

# Archivo ONNX
faceswap-pro run `
  --model-path .\models\inswapper_128.onnx `
  --config .\config\quality.yaml

# Directorio de checkpoint HifiFace
faceswap-pro run `
  --model-path .\models\hififace\standard_model `
  --config .\config\quality_3dmm.yaml

Los alias antiguos --model y --swapper-model continúan disponibles.

Qué significa “3D-aware” en este proyecto

hififace_3dmm no es un simple warper. El generador obtiene coeficientes de forma 3DMM de source y target, conserva la identidad/forma del source y combina expresión y pose del target antes de sintetizar. Después, Semantic Facial Fusion predice una máscara y conserva iluminación, fondo y oclusiones dentro del propio modelo.

Esto es condicionamiento generativo por 3DMM, no un avatar 3D explícito con rig, texturas editables o render físico. El perfil sigue siendo independiente por frame; la consistencia temporal neuronal queda como una extensión separada futura.

Logs y perfilado de rendimiento

Todos los comandos crean automáticamente la carpeta logs/ con exactamente dos archivos acumulativos en formato JSON Lines:

• logs/logs.jsonl: inicio y fin de ejecución, advertencias, bloqueos prolongados, fallos de hilos y excepciones con traceback.
• logs/profile.jsonl: spans jerárquicos, métricas por fotograma y rostro, esperas de colas/futuros, tiempos de decodificación, detección, tracking, swap, composición, restauración, alimentación al encoder, memoria Python y estadísticas cProfile por función. En DreamID-V también incorpora la telemetría del worker: carga de modelos, VRAM asignada/reservada, VAE, cada forward del DiT, paso de difusión, pasada condicional/no condicionada, escritura, heartbeats y cProfile por clip. Cuando el runtime no admite perfiles simultáneos, conserva los spans atómicos y registra explícitamente esa limitación sin detener el procesamiento.

El archivo de perfil añade también eventos span_summary ordenados por tiempo total, con conteo, promedio, mínimo, máximo y CPU acumulada por operación. Cada línea incluye run_id, timestamp, proceso e hilo, por lo que varias ejecuciones pueden convivir en los mismos archivos y filtrarse sin perder el historial. La ruta puede cambiarse para una ejecución completa colocando la opción global antes del comando:

faceswap-pro --log-dir .\diagnostico run --config .\config\quality.yaml

El perfilado es intencionalmente detallado y añade cierta sobrecarga; sus mediciones permiten localizar cuellos de botella a nivel de etapa, fotograma, rostro y función.

Pruebas

pytest -q

La suite cubre contratos, configuración, tracking multiinstancia y reflejos, ventanas DreamID-V solapadas, banco multi-referencia, composición selectiva, métricas visuales, caché de hashes, C2PA, compatibilidad del flujo anterior, HifiFace y el adaptador 3DMM.

Uso responsable

Procesa únicamente material propio o autorizado. El perfil DreamID-V no añade una marca visible, pero mantiene un manifiesto JSON, intenta incrustar C2PA y conserva los frames originales cuando el sujeto es ambiguo o no está localizado. Revisa por separado las licencias del código, los pesos, Wan 2.1, BFM e InsightFace.

Fine-Tuning de difusión (LoRA + ControlNet)

El proyecto incluye ahora un backend SOLID opcional para personalización con SDXL LoRA y generación condicionada mediante OpenPose + Depth ControlNet. Está desacoplado del pipeline de reemplazo facial existente y expone una API FastAPI para datasets, jobs de entrenamiento y generación sobre imagen o vídeo.

Consulta docs/diffusion_finetuning_backend.md para instalación, arquitectura y endpoints.