How to Configure Training Preview and Timelapse in Faceswap: A Complete Guide

Enable the live preview by adding -p to your training command, and generate a timelapse by supplying all three required path arguments (--timelapse-input-A, --timelapse-input-B, and --timelapse-output).

The deepfakes/faceswap repository provides built-in visualization tools that let you monitor training progress in real time and export periodic snapshots for retrospective analysis. Configuring these features requires specific command-line arguments defined in the CLI parser and handled by the training subsystem. This guide explains the exact flags, file paths, and internal mechanisms that control the preview window and timelapse generation.

Enabling the Live Training Preview

The live preview opens a Tkinter window that refreshes after each save iteration, showing side-by-side source and swapped faces so you can judge model quality without stopping training.

Command-Line Arguments

Add the -p or --preview flag when launching the training script. This argument is registered in lib/cli/args_train.py (line 265) with the option tuple ("-p", "--preview"). When present, scripts/train.py instantiates the PreviewInterface class at line 66:

self._preview = PreviewInterface(self._args.preview)

Preview Window Mechanics

The PreviewInterface class (defined in scripts/train.py) coordinates with the preview subsystem located in tools/preview/. The actual window rendering is handled by tools/preview/preview.py, while image composition occurs in tools/preview/viewer.py.

During training, the system checks self._preview.should_toggle_mask and calls self._preview.update() around lines 322-344 of scripts/train.py. This triggers the viewer to rebuild display images via methods like update_tk_image() and reload() inside tools/preview/viewer.py, refreshing the canvas with the latest model outputs.

Note: Closing the preview window does not terminate training; the process continues in the background until you manually stop the script.

Setting Up Training Timelapse

A timelapse saves a snapshot image after every training iteration to a specified folder, creating a sequence you can compile into a video.

Required Arguments

You must provide all three arguments together or the parser raises a FaceswapError (validation logic in lib/cli/args_train.py lines 155-157). The arguments are defined between lines 230-263:

• -x / --timelapse-input-A: Path to the alignment folder containing source faces (side A).
• -y / --timelapse-input-B: Path to the alignment folder containing target faces (side B).
• -z / --timelapse-output: Destination folder where timelapse frames are written.

How Timelapse Generation Works

1. Argument Validation: scripts/train.py calls _set_timelapse() at line 58, which packages the three paths into a dictionary:

   timelapse_kwargs = {
       "input_a": self._args.timelapse_input_a,
       "input_b": self._args.timelapse_input_b,
       "output": get_folder(self._args.timelapse_output)
   }

2. Trainer Integration: The Timelapse object is instantiated inside plugins/train/trainer/_display.py (line 77). When a save iteration occurs, the trainer passes the kwargs to self._timelapse.output_timelapse(timelapse_kwargs) (lines 340-341).

3. Image Generation: Inside _display.py, the output_timelapse() method calls self._samples.images = self._feeder.generate_preview(is_timelapse=True) (lines 577-580). The core face-swapping logic resides in lib/training/generator.py at line 859 (generate_preview(is_timelapse=True)), which pulls faces from the specified input folders, runs inference, and writes the results to the output directory.

Each iteration produces a new image file, creating an ordered sequence (e.g., frame_0000.jpg, frame_0001.jpg) suitable for encoding with ffmpeg.

Complete Configuration Example

The following command enables both features simultaneously:

python -m scripts.train \
    -A /path/to/aligned_A \
    -B /path/to/aligned_B \
    -m /path/to/model \
    -p \
    -x /path/to/aligned_A \
    -y /path/to/aligned_B \
    -z /path/to/timelapse_output

• -A and -B specify your training datasets.
• -p activates the live preview window.
• -x, -y, and -z enable timelapse generation, reading from the alignment folders and writing frames to the designated output path.

Summary

• Enable preview: Add -p or --preview to open a live Tkinter window that updates after every save iteration via PreviewInterface in scripts/train.py.
• Enable timelapse: Supply all three required paths (--timelapse-input-A, --timelapse-input-B, --timelapse-output) defined in lib/cli/args_train.py; the system validates these in _set_timelapse() and triggers generation logic in plugins/train/trainer/_display.py.
• Image creation: Both features rely on generate_preview() inside lib/training/generator.py to render swapped faces, with timelapse mode setting is_timelapse=True to force disk writes instead of window display.
• Independence: Preview and timelapse can operate separately or together; neither blocks the training loop managed by scripts/train.py.

Frequently Asked Questions

Can I enable timelapse without the live preview window?

Yes. According to the source code in scripts/train.py, the preview and timelapse systems are independent. You can omit -p and still provide -x, -y, and -z to generate timelapse frames in the background without opening the Tkinter interface. The _set_timelapse() method (line 58) processes the timelapse arguments regardless of the preview flag status.

Why does the training script require both input folders for the timelapse?

The generate_preview(is_timelapse=True) method in lib/training/generator.py (line 859) needs access to actual face data from both sides to create a meaningful swapped output. The validation logic in lib/cli/args_train.py (lines 155-157) enforces that all three timelapse arguments must be present simultaneously; if any are missing, the parser raises a FaceswapError to prevent incomplete configuration.

Where are the timelapse images actually saved on disk?

The images are written to the path specified by --timelapse-output (or -z). In scripts/train.py (line 58), this path is processed through get_folder(), which ensures the directory exists before the trainer begins. Inside plugins/train/trainer/_display.py (lines 577-580), each save iteration writes a new frame to this location using the naming convention defined in the generator, producing a sequentially ordered set of images.

Does enabling the preview or timelapse slow down training?

The preview window updates only after save iterations (controlled by the save_interval configuration), so it does not block every training step. However, timelapse generation forces an additional forward pass through the model to generate preview images, which adds minor overhead during save events. Both features run in the main thread alongside the trainer, as implemented in scripts/train.py around lines 322-344, but they do not significantly impact overall training speed on modern hardware.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}