Website: https://cursedprograms.github.io/Changeling-Imago/
Imago is Latin for a likeness, and the Romans' word for the wax masks cast from a person's face and kept in the family hall: a copy of a face that someone could wear. (It's also where "image" comes from.)
Put a face from one photo onto another photo or a whole video. Part of the Changeling family, all together in Changeling Studio: Imago · Imago Realtime · Tiresias (gender) · Chronos (age) · Natio (where in the world) · Cosmeta (makeup, hair, beards) · Echo (voices) · Tonsor (hairstyles) · realtime: Tiresias · Chronos · Natio · Cosmeta.
Pick the face, pick the target, press Start, and a completion bar shows what it's doing (loading, checking, extracting frames, swapping faces, making the video), how far it is and how long it has left. Sharper face (on by default) runs GFPGAN after the swap: the swap model draws the new face at 128 x 128, so on its own the face looks soft and blocky next to the rest of the picture; GFPGAN redraws it sharp. Switch it off for quicker tests, most of all on videos.
Changeling Imago grew out of roop by s0md3v, and like roop it's free software
under the GNU AGPL-3.0 (see LICENSE). Its NSFW check stays on: explicit targets are refused.
Use it on faces you have the right to use: AI-generated people, yourself, or people who agreed to it.
You need Python 3.9 - 3.12 (3.11 is best; get it from python.org) and ffmpeg on your PATH for videos. Python 3.13 and newer won't work (TensorFlow and PyTorch don't support them yet), but they can stay installed: the scripts find a 3.9 - 3.12 through the py launcher.
Then just run it:
| Windows | PowerShell | Linux / macOS / Git Bash |
|---|---|---|
run.bat |
.\run.ps1 |
./run.sh |
The first run sets everything up by itself, then opens the app:
- makes a virtual environment,
psdenv, in this folder - installs the packages from
requirements.txt(several GB the first time: PyTorch and TensorFlow, so give it a while) - downloads the models into
models/(inswapper_128.onnx,GFPGANv1.4.pth)
After that it starts straight away. Running it again only redoes what's missing or changed, so if a download fails halfway, run it again and it carries on.
- The GPU: with an NVIDIA card it uses CUDA automatically (no CUDA Toolkit or cuDNN to install: PyTorch brings its own). Add
--execution-provider cputo force the CPU. - Older cards (GTX 10xx, 4 GB): they work. CUDA 12 needs NVIDIA driver 531 or newer; check with
nvidia-smi("Driver Version") and update from nvidia.com if it's older, or the swap quietly falls back to the slow CPU. Out of video memory? Add--execution-threads 2. The face enhancer (GFPGAN) is the slow part: leave it off for tests. - Set up without opening the app:
setup.bat,.\setup.ps1or./setup.sh. - A prompt inside the environment:
activate_env.bat. - PowerShell won't run scripts? Once:
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. - Start over: delete the
psdenvfolder and run it again.
Give a source face, a target and an output, and it swaps without opening the window:
run.bat -s face.png -t clip.mp4 -o out.mp4
run.bat -s face.png -t clip.mp4 -o out.mp4 --keep-fps
The swap refuses explicit targets: the NSFW check (changeling/predictor.py) stays on.
The swap has two looks, a switch in the window: Classic (InsightFace's paste) or Deep-Live-Cam's look, written
anew after Deep-Live-Cam's ideas (dlc_style.py): a soft oval instead
of the square, the swapped face's colour matched to the skin it replaces, keep my mouth (your own lips, teeth and
tongue), a Poisson blend, opacity and sharpness. Changeling Studio and Mimic (C++) have the same switch.
From the command line: --style deep-live-cam --keep-mouth 30 (0 the lips .. 100 down to the chin).
Start the program with arguments:
python run.py [options]
-h, --help show this help message and exit
-s SOURCE_PATH, --source SOURCE_PATH select an source image
-t TARGET_PATH, --target TARGET_PATH select an target image or video
-o OUTPUT_PATH, --output OUTPUT_PATH select output file or directory
--frame-processor FRAME_PROCESSOR [FRAME_PROCESSOR ...] frame processors (choices: face_swapper, face_enhancer, ...)
--keep-fps keep target fps
--keep-frames keep temporary frames
--skip-audio skip target audio
--many-faces process every face
--reference-face-position REFERENCE_FACE_POSITION position of the reference face
--reference-frame-number REFERENCE_FRAME_NUMBER number of the reference frame
--similar-face-distance SIMILAR_FACE_DISTANCE face distance used for recognition
--temp-frame-format {jpg,png} image format used for frame extraction
--temp-frame-quality [0-100] image quality used for frame extraction
--output-video-encoder {libx264,libx265,libvpx-vp9,h264_nvenc,hevc_nvenc} encoder used for the output video
--output-video-quality [0-100] quality used for the output video
--max-memory MAX_MEMORY maximum amount of RAM in GB
--execution-provider {cpu} [{cpu} ...] available execution provider (choices: cpu, ...)
--execution-threads EXECUTION_THREADS number of execution threads
-v, --version show program's version number and exit
Using the -s/--source, -t/--target and -o/--output argument will run the program in headless mode.

