Skip to content

About

Changeling Imago (Latin: a likeness, the Romans' wax copy of a face): one face onto any photo or video, with a completion bar and GFPGAN clean-up. Grown from roop (AGPL-3.0).

Topics

Resources

Stars

10 stars

Watchers

1 watching

Forks

Latest commit

 

History

51 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Twitter: @NorowaretaGemu License: AGPL-3.0



Python

Changeling

TensorFlow
Git PowerShell Shell Batch

Changeling Imago

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.)

A target photo, the face to put on it, and Changeling's result

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.

Getting started

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:

  1. makes a virtual environment, psdenv, in this folder
  2. installs the packages from requirements.txt (several GB the first time: PyTorch and TensorFlow, so give it a while)
  3. 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 cpu to 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.ps1 or ./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 psdenv folder and run it again.

Without the app (headless)

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.


Two styles

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).

Usage

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

Headless

Using the -s/--source, -t/--target and -o/--output argument will run the program in headless mode.



© Cursed Entertainment 2026


About

Changeling Imago (Latin: a likeness, the Romans' wax copy of a face): one face onto any photo or video, with a completion bar and GFPGAN clean-up. Grown from roop (AGPL-3.0).

Topics

Resources

Stars

10 stars

Watchers

1 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages