WAIT — Stale — last commit 1y ago

• 7 active contributors
• GPL-3.0 licensed
• ⚠ Stale — last commit 1y ago
• ⚠ Single-maintainer risk — top contributor 86% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

DeepFaceLive is a real-time face-swapping application that replaces faces in live webcam streams or video files using deep neural networks (DFM/Insight face swap models). It processes video frames through a pipeline of face detection, alignment, feature extraction, and blending to enable live streaming with face transformations, running on CPU/GPU with ONNX models and DirectX acceleration on Windows. Layered monolith: apps/DeepFaceLive/backend/ contains processing pipeline (CameraSource → FaceDetector → FaceAligner → FaceSwapDFM/Insight → FaceMerger → StreamOutput), with mirrored ui/ directory containing Qt5 widgets (Q* classes) that wrap each backend module. apps/trainers/FaceAligner/ is a separate trainer app for model fine-tuning.

Content creators and streamers who want to use face-swapped avatars in real-time video calls or streams, and developers extending the face-swap pipeline with custom face models, alignment techniques, or output targets (OBS, vtubing platforms).

Actively developed with concrete face models shipped (Keanu Reeves, Mr. Bean, etc.) and a modular backend/UI separation, but appears pre-1.0: the file structure shows archived code in __dev_archived/, suggesting ongoing refactoring. No CI/CD pipeline visible (no GitHub Actions, pytest markers). Last commit recency unknown from provided data, but the detailed celebrity examples suggest recent polishing.

Single-maintainer repo (iperov) with no visible test suite or CI—regressions in face detection or alignment pipeline aren't caught automatically. DirectX/ONNX runtime dependencies are Windows-specific and pinned versions; breaking updates to those libraries could silently degrade real-time performance. Large neural network model files are not versioned in-repo (loaded at runtime), so model availability is a deployment risk.

Unknown from provided metadata. Directory structure suggests transition away from archived code (check __dev_archived/archived.zip for history), but specific active issues/PRs not visible. Focus appears to be on expanding face model library and optimizing real-time inference on consumer GPUs.

git clone https://github.com/iperov/DeepFaceLive.git
cd DeepFaceLive
pip install -r requirements.txt  # if present, else inspect setup.py
python apps/DeepFaceLive/DeepFaceLiveApp.py

Daily commands:

python apps/DeepFaceLive/DeepFaceLiveApp.py

Launches PyQt5 GUI. Expected to auto-detect cameras and load ONNX models on first run. Real-time output visible in app window; can route to OBS/vtubing software via StreamOutput module.

• apps/DeepFaceLive/DeepFaceLiveApp.py — Main application entry point that orchestrates the entire face-swap pipeline—every contributor must understand how the app initializes and manages the backend/UI lifecycle.
• apps/DeepFaceLive/backend/BackendBase.py — Abstract base class for all backend processing modules (FaceDetector, FaceSwapDFM, etc.)—defines the core interface that all pipeline stages implement.
• apps/DeepFaceLive/backend/FaceDetector.py — Detects faces in video frames using deep learning—critical first stage in the pipeline that all downstream modules depend on.
• apps/DeepFaceLive/backend/FaceSwapDFM.py — Core face-swap neural network implementation using DFM (Deep Face Model)—the primary inference engine performing actual face replacement.
• apps/DeepFaceLive/backend/FaceMerger.py — Blends and merges swapped face onto target frame with color correction—final compositing stage before output.
• apps/DeepFaceLive/backend/CameraSource.py — Captures real-time video from webcam or video file—handles input acquisition and frame buffering for the pipeline.
• apps/DeepFaceLive/ui/QBackendPanel.py — Base UI widget for backend module configuration—establishes pattern for how all backend components expose settings to the GUI.

Add a new backend face processing stage

1. Create new class inheriting from BackendBase in apps/DeepFaceLive/backend/ (apps/DeepFaceLive/backend/BackendBase.py)
2. Implement required abstract methods: _on_enable(), _on_disable(), _process(), and parameter getters (apps/DeepFaceLive/backend/YourNewStage.py)
3. Register the module in DeepFaceLiveApp.py by adding it to the pipeline chain (apps/DeepFaceLive/DeepFaceLiveApp.py)
4. Create corresponding UI widget inheriting from QBackendPanel in apps/DeepFaceLive/ui/ (apps/DeepFaceLive/ui/QYourNewStage.py)
5. Wire UI widget to backend module by adding to main UI layout (apps/DeepFaceLive/ui/QBackendPanel.py)

Add a new input source (camera, file, stream)

1. Create new source class inheriting from BackendBase in apps/DeepFaceLive/backend/ (apps/DeepFaceLive/backend/CameraSource.py)
2. Implement frame acquisition logic in _process() method (apps/DeepFaceLive/backend/YourNewSource.py)
3. Create UI widget to configure source parameters (apps/DeepFaceLive/ui/QYourNewSource.py)
4. Register source in DeepFaceLiveApp.py (apps/DeepFaceLive/DeepFaceLiveApp.py)

Add a new output destination (virtual camera, streaming service, file)

1. Extend or create new output class inheriting from BackendBase (apps/DeepFaceLive/backend/StreamOutput.py)
2. Implement frame writing/streaming logic in _process() (apps/DeepFaceLive/backend/YourNewOutput.py)
3. Create UI configuration widget (apps/DeepFaceLive/ui/QYourNewOutput.py)
4. Register output handler in DeepFaceLiveApp.py (apps/DeepFaceLive/DeepFaceLiveApp.py)

Train a custom face swap model

1. Use TrainingDataGenerator to prepare training dataset (apps/trainers/FaceAligner/TrainingDataGenerator.py)
2. Create trainer script or extend FaceAlignerTrainerApp pattern (apps/trainers/FaceAligner/FaceAlignerTrainerApp.py)
3. Export trained model in ONNX format for runtime inference (apps/DeepFaceLive/backend/FaceSwapDFM.py)
4. Load model in corresponding backend stage (apps/DeepFaceLive/backend/FaceSwapDFM.py)

• Python + PyQt5/Qt — Cross-platform real-time GUI and rapid deep learning integration; PyQt enables responsive UI for parameter tweaking during live streaming
• ONNX Runtime — Mentioned in README logo; provides hardware-accelerated inference (CPU/GPU/DirectX) for the neural network models without vendor lock-in
• DirectX (Windows) — Enables GPU acceleration on Windows for real-time face swap inference at 30+ FPS needed for streaming
• Deep Face Models (DFM) — Specialized neural networks trained on face embeddings for high-quality identity-preserving face swaps

• Sequential pipeline architecture (detect → align → swap → merge) vs. end-to-end model

  • Why: Modularity allows swapping individual components and gradual optimization; enables visualization of intermediate steps
  • Consequence: Slightly more latency than fused model, but more maintainable and debuggable

• Real-time streaming focus (30+ FPS) over batch processing quality

  • Why: Core use case is live video calls and streaming; demands low latency
  • Consequence: Cannot use slower high-quality models; must compromise on face swap quality for speed

• ONNX models vs. PyTorch/TensorFlow directly

  • Why: Runtime inference only; ONNX is optim
  • Consequence: undefined

Model loading: Face swap models (DFM, Insight) are large files (~100-300 MB) downloaded at runtime; no local cache invalidation logic visible—if a model URL breaks, app silently fails. Real-time constraint: FaceDetector runs on every frame; if detection latency > frame duration (e.g., >33ms at 30fps), pipeline stalls and audio/video desync. GPU VRAM: Aligner + Swapper both load ONNX models; batch processing not implemented—each frame processed individually, leaving GPU underutilized. Qt thread safety: No explicit locks visible in backend; if UI thread and inference thread both touch frame data, race conditions possible. DirectX-only: Non-Windows users get no GPU acceleration path (CPU-only ONNX inference is 10x slower).

• Face landmark detection — FaceDetector.py and FaceAligner.py both rely on predicting 2D face landmarks (eye, nose, mouth corners); understanding this is essential to debug misalignment or adjust anchor points
• Affine transformation for face alignment — FaceAligner.py computes affine matrices to warp detected faces to a canonical pose; modifying this requires linear algebra (rotation, scale, translation matrices)
• ONNX Runtime inference — All neural networks (FaceDetector, FaceAligner, FaceSwapDFM) are serialized as ONNX graphs and executed via ONNX Runtime; understanding model I/O shapes and quantization is needed to swap or optimize models
• Variational autoencoders (VAE) for face encoding — FaceSwapDFM likely uses a VAE bottleneck to extract face embeddings and reconstruct swapped faces; tweaking latent dimension or reconstruction loss requires VAE knowledge
• Feathering and blending for seamless compositing — FaceMerger.py blends the swapped face into the background using feathering masks; understanding alpha blending and Gaussian blur is essential to reduce visible seams or artifacts
• PyQt5 signal/slot mechanism — UI widgets (Q* classes) communicate with backend modules via Qt signals; you must use this pattern (not raw function calls) to avoid race conditions in real-time pipeline
• Temporal coherence and optical flow — Real-time video requires frame-to-frame consistency; FaceMerger may use motion estimation to smooth jitter; understanding optical flow helps reduce flickering between swaps

• deepinsight/insightface — Source of face detection/recognition models used in FaceDetector.py; provides pre-trained ONNX weights that DeepFaceLive wraps
• clerouindev/DeepFaceSwap — Similar face-swap pipeline but offline-only (no real-time streaming); good reference for face encoding/decoding math if you want to optimize latency
• s0md3v/roop — Alternative real-time face-swap using similar ONNX models; shows competing approach to frame blending and video I/O if you're exploring different architectures
• iperov/DeepFaceLab — Sister project by same author: trains custom face models (DFM) that DeepFaceLive consumes; understanding DFL's model format is required to add new swappable faces
• opencv/opencv — Underlying image codec and preprocessing library used in CameraSource, FileSource, and frame resizing; critical for debugging color space or format issues

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for backend processing pipeline (BackendBase.py and derivative classes)

The repo has a complex backend pipeline with FaceDetector, FaceAligner, FaceMarker, FaceMerger, and FaceSwap modules, but there are no visible test files. Adding unit tests would catch regressions in face processing, improve confidence in model swaps, and help new contributors understand the data flow. This is critical for a real-time video application where correctness is essential.

• [ ] Create tests/backend/ directory with test files matching each backend module
• [ ] Add unit tests for BackendBase.py covering initialization and state management
• [ ] Add integration tests for the full pipeline: CameraSource → FaceDetector → FaceAligner → FaceMerger → StreamOutput
• [ ] Create mock frame data and face detection outputs to avoid GPU/model dependencies in tests
• [ ] Add pytest configuration and GitHub Actions workflow to run tests on each PR

Create API documentation for backend module interfaces (apps/DeepFaceLive/backend/)

The backend directory has 10+ specialized modules (FaceDetector, FaceAnimator, FaceSwapDFM, etc.) but no docstrings or interface documentation explaining how they connect. New contributors struggle to understand how to add new face swap models or modify the pipeline. Documentation would accelerate onboarding.

• [ ] Add docstrings to BackendBase.py explaining the base class contract and lifecycle methods
• [ ] Document FaceDetector.py, FaceAligner.py, FaceMarker.py interfaces with input/output specs
• [ ] Document the two face swap implementations: FaceSwapDFM.py vs FaceSwapInsight.py (when to use each)
• [ ] Create docs/BACKEND_ARCHITECTURE.md with a diagram showing data flow between modules
• [ ] Add inline comments showing expected frame shapes, coordinate systems, and tensor formats

Add GitHub Actions workflow for Windows/Linux/Docker build validation

The repo has a Dockerfile and Linux build scripts (build/linux/Dockerfile, build/linux/start.sh) but no CI/CD pipeline to validate builds. Contributors can't verify cross-platform compatibility before pushing changes. A CI workflow would catch breaking changes early and document the build process.

• [ ] Create .github/workflows/build.yml with separate jobs for Windows (ONNX + DirectX), Linux, and Docker
• [ ] Add build step validation: Python dependency installation, model downloading, and basic import tests
• [ ] Add a lightweight smoke test that imports all backend modules and verifies ONNX model loading
• [ ] Document build requirements in build/BUILD_SETUP.md for local contributors (GPU requirements, DirectX setup)
• [ ] Reference build/linux/Dockerfile and build/linux/example.sh in the workflow to ensure they stay in sync

• Add unit tests for FaceAligner.py: create tests/test_face_aligner.py with synthetic face image batches, verify landmark detection consistency across rotations/scales
• Document CSW (Customizable State Widget) pattern: the UI uses a custom observable state binding system (see QCSWControl, QSliderCSWNumber); add docstrings and create docs/csw_architecture.md explaining how to wire new backend parameters to UI controls
• Implement frame dropping logic in StreamOutput.py: when GPU inference lags behind frame capture, add a FIFO queue with max-length so old frames are discarded instead of buffering forever and causing audio desync

• High · Potential Deepfake Misuse Risk — apps/DeepFaceLive/, build/samples/. DeepFaceLive is a real-time face swap application that could be used to create deepfakes without consent. The application processes real faces and can swap them with other identities. The README explicitly mentions public face models of real people (Keanu Reeves, etc.), raising concerns about potential misuse for impersonation, fraud, or non-consensual content creation. Fix: Implement: (1) Watermarking or digital signatures on output, (2) Clear user consent workflows, (3) Usage logging and audit trails, (4) Terms of service explicitly prohibiting non-consensual use, (5) Consider implementing liveness detection to prevent pre-recorded substitution
• High · No Visible Access Control Mechanism — apps/DeepFaceLive/backend/CameraSource.py, apps/DeepFaceLive/backend/FileSource.py, apps/DeepFaceLive/backend/StreamOutput.py. The codebase shows camera access (CameraSource.py, FileSource.py, StreamOutput.py) without apparent permission validation or access control checks. The application directly accesses camera and file resources without demonstrable security controls. Fix: Implement: (1) Permission checks before camera/file access, (2) User consent dialogs, (3) Audit logging for resource access, (4) Restrict access to appropriate user roles
• Medium · Model Files in Repository — build/animatables/, build/samples/. The repository contains face model files and sample media (videos, images) in the build/ directory. These binary files increase attack surface and could potentially be replaced with malicious models. Pre-trained models are opaque and difficult to audit for poisoning attacks. Fix: Implement: (1) Move large model files to external CDN with integrity verification (hashes/signatures), (2) Add model signature verification before loading, (3) Document model provenance, (4) Implement hash verification in code before model usage
• Medium · No Visible Input Validation — apps/DeepFaceLive/backend/FileSource.py, apps/DeepFaceLive/ui/QFileSource.py. File processing components (FileSource.py) and UI input widgets lack visible input validation. Video/image file processing could be vulnerable to malformed file attacks or path traversal if file paths are user-controllable. Fix: Implement: (1) Strict file type validation, (2) Path traversal prevention, (3) File size limits, (4) Sandboxed file processing, (5) Safe deserialization practices
• Medium · Archived/Trash Files in Repository — __dev_archived/archived.zip, __dev_archived/_trash.txt. The __dev_archived/ directory contains archived.zip and _trash.txt files, suggesting potential removal of development artifacts. These could contain sensitive information, hardcoded secrets, or deprecated code with vulnerabilities. Fix: Implement: (1) Remove archived files from repository, (2) Review archived.zip contents for sensitive data, (3) Use proper git history cleanup if secrets were committed, (4) Enforce pre-commit hooks to prevent archival artifacts
• Medium · Missing Dependency Management Documentation — Repository root - missing dependency file. No dependency file (requirements.txt, setup.py, pyproject.toml) is provided for analysis. Without visible dependency management, it's impossible to assess for known vulnerabilities, outdated packages, or supply chain risks. Fix: Implement: (1) Add requirements.txt with pinned versions, (2) Use dependency scanning tools (pip-audit, safety), (3) Implement automated dependency updates, (4) Document all third-party libraries and licenses
• Low · GPU/Hardware Resource Access — apps/DeepFaceLive/backend/. The application accesses GPU resources (likely DirectX based on README mentioning logo) without visible resource limits or DoS protections. Malicious input could theoretically consume excessive GPU memory. Fix: Implement: (1) GPU memory limits, (2) Processing timeouts, (3) Resource monitoring and throttling, (4) Graceful handling of resource exhaustion
• Low · Docker Configuration Not Fully Visible — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/iperov/DeepFaceLive shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live iperov/DeepFaceLive repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/iperov/DeepFaceLive.

What it runs against: a local clone of iperov/DeepFaceLive — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in iperov/DeepFaceLive | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 577 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of iperov/DeepFaceLive. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/iperov/DeepFaceLive.git
#   cd DeepFaceLive
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of iperov/DeepFaceLive and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "iperov/DeepFaceLive(\\.git)?\\b" \\
  && ok "origin remote is iperov/DeepFaceLive" \\
  || miss "origin remote is not iperov/DeepFaceLive (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "apps/DeepFaceLive/DeepFaceLiveApp.py" \\
  && ok "apps/DeepFaceLive/DeepFaceLiveApp.py" \\
  || miss "missing critical file: apps/DeepFaceLive/DeepFaceLiveApp.py"
test -f "apps/DeepFaceLive/backend/BackendBase.py" \\
  && ok "apps/DeepFaceLive/backend/BackendBase.py" \\
  || miss "missing critical file: apps/DeepFaceLive/backend/BackendBase.py"
test -f "apps/DeepFaceLive/backend/FaceDetector.py" \\
  && ok "apps/DeepFaceLive/backend/FaceDetector.py" \\
  || miss "missing critical file: apps/DeepFaceLive/backend/FaceDetector.py"
test -f "apps/DeepFaceLive/backend/FaceSwapDFM.py" \\
  && ok "apps/DeepFaceLive/backend/FaceSwapDFM.py" \\
  || miss "missing critical file: apps/DeepFaceLive/backend/FaceSwapDFM.py"
test -f "apps/DeepFaceLive/backend/FaceMerger.py" \\
  && ok "apps/DeepFaceLive/backend/FaceMerger.py" \\
  || miss "missing critical file: apps/DeepFaceLive/backend/FaceMerger.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 577 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~547d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/iperov/DeepFaceLive"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.