The Problem
Face swapping and manipulation tools are typically research codebases with poor CLI ergonomics, no job management, and no way to run unattended batch operations. This repo addresses that by packaging face manipulation into a production-oriented tool with a documented command surface, job queue, and headless execution mode.
What This Does
faceswap (a fork of facefusion) is a Python-based face manipulation platform. The core entry point is facefusion.py, which exposes commands for running, benchmarking, and managing jobs. The facefusion/ package is organized by responsibility: faceanalyser.py, facedetector.py, and facelandmarker.py handle detection; processors/modules/ contains the actual manipulation processors (e.g., faceswapper.py, agemodifier.py, lipsyncer.py); jobs/ implements the job queue with jobmanager.py and jobrunner.py.
The UI layer in facefusion/uis/ provides Gradio-based components for interactive use, while the CLI supports headless and batch modes. The ffmpeg.py and ffmpegbuilder.py modules handle video encoding, and download.py manages model acquisition. The test suite is substantial—40 files covering CLI paths, job management, and core utilities.
How To Use It
Setup: Install dependencies with pip install -r requirements.txt from the repo root. The README warns that installation requires technical skill and points to platform-specific installers.
Configuration: No environment variables are required. Model files are downloaded automatically via download.py. Optional configuration lives in facefusion.ini, and CLI options are defined in args.py.
Running it: The primary entry point is python facefusion.py. The README documents these commands:
python facefusion.py run # interactive UI python facefusion.py headless-run # no UI python facefusion.py batch-run # batch processing python facefusion.py benchmark # performance testing python facefusion.py job-create # create a job python facefusion.py job-submit # queue a job python facefusion.py job-run # execute queued jobs
Real-World Use
A media forensics lab needs to process a batch of videos through face swapping for a client demonstration. The workflow: use job-create to define a job with source and target faces, job-submit to queue it, then job-run-all to process the batch unattended. The benchmark command lets the team compare processor performance across hardware before committing to a large run. The job system also supports retry (job-retry) for failed items, which matters when processing large video files that may hit transient encoding errors.
Code Health & Issues
Med - No dependency lockfile - requirements.txt pins nothing, so builds are non-reproducible. CI runs will drift over time. Med - No license file in repo root - LICENSE.md exists but the README badge references OpenRAIL-AS; verify the actual license text matches the claim. Low - Single CI workflow - .github/workflows/ci.yml exists, but coverage is unverified; the README references Coveralls but no config file is present. Low - Large module count - 126 files in facefusion/ suggests possible over-fragmentation, but the naming is consistent and test coverage is broad. Low - No input validation on CLI - args.py and clihelper.py handle parsing, but there's no evidence of schema validation for user-supplied paths or options.
The test suite is a genuine strength—40 files covering both unit and CLI integration paths. The codebase is well-organized with clear separation between processors, jobs, and UI layers.
The Bottom Line
A mature, well-structured face manipulation tool with a real job system and solid test coverage. The lack of dependency pinning is the main operational risk for production use. Suitable for teams needing scriptable, batch-oriented face processing rather than one-off experimentation.