How to Use the Faceswap GUI for Training and Conversion: Complete Workflow Guide

The Faceswap GUI provides a Tkinter-based visual interface that wraps the underlying command-line tools, allowing users to configure training parameters and conversion settings through intuitive tabs while executing heavy GPU workloads in background processes.

The deepfakes/faceswap project includes a comprehensive graphical interface that eliminates the need for complex terminal commands when training deep learning models or performing face swaps on media. This Faceswap GUI dynamically generates configuration panels from the codebase, manages subprocesses for resource-intensive tasks, and captures real-time logs in a built-in console. Understanding the relationship between the visual components and their underlying Python modules enables you to troubleshoot issues and customize workflows effectively.

Architecture Overview

The Faceswap GUI operates as a thin wrapper around the core scripts located in scripts/ and plugins/. When you execute scripts/gui.py, the application initializes a FaceswapGui object (a subclass of tk.Tk defined at lines 30-46) that constructs the main window, menubar, and paned interface.

Key architectural components include:

• Configuration Management: The lib/gui/gui_config.py module handles .ini file parsing through load_config() and exposes available commands via get_commands(), which populates the tabbed notebook interface.
• Command Notebook: Located in lib/gui/command.py, this dynamically generates tabs (Extract, Train, Convert) based on the command list retrieved from the configuration.
• Process Management: The ProcessWrapper class spawns separate Python processes when you initiate training or conversion, ensuring the Tkinter interface remains responsive during GPU-intensive operations.
• Log Capture: The ConsoleOut widget in lib/gui/display.py streams stdout and stderr from background processes into the GUI's lower console pane.

Launching the Faceswap GUI

You can start the interface from the repository root using the entry point defined in scripts/gui.py. The Gui.process() method (lines 86-94) parses arguments, instantiates the main window, and enters the Tkinter main loop.

Command-Line Launch

Execute the following from your terminal to start the GUI with default settings:

python3 scripts/gui.py

To use a custom configuration file containing default paths, fonts, or layout preferences:

python3 scripts/gui.py --configfile my_faceswap.ini

Programmatic Launch

You can also embed the GUI launcher within another Python script by importing the Gui class and passing an argument namespace:

from scripts.gui import Gui
import argparse

parser = argparse.ArgumentParser()
parser.add_argument('--debug', action='store_true')
parser.add_argument('--configfile', type=str, default=None)
args = parser.parse_args(['--debug'])

gui = Gui(args)  # Creates FaceswapGui internally

gui.process()    # Runs the Tkinter mainloop

Training Models via the Faceswap GUI

The Train tab provides a visual frontend to the training pipeline implemented in plugins/train/training.py. When configured, the GUI invokes trainer classes located in plugins/train/trainer/ (such as original.py) through a background process.

Step-by-Step Training Workflow

1. Select the Train Tab: The GUI generates this tab dynamically from the command list returned by get_commands() in lib/gui/gui_config.py.

2. Configure Dataset: Point to a folder containing aligned face images. The GUI calls initialize_images() to cache thumbnails for preview purposes.

3. Choose Model Architecture: Select from available trainers (e.g., Original, DFaker, Lightweight) via a dropdown populated by scanning plugins/train/model/.

4. Set Hyperparameters: Adjust epochs, batch size, and learning-rate warm-up through spin-box widgets. These values serialize to a temporary configuration consumed by plugins/train/training.py.

5. Initiate Training: Clicking the Start button triggers ProcessWrapper.start_task(), which executes scripts/train.py in a subprocess. The ConsoleOut pane displays live TensorBoard events and iteration logs from plugins/train/trainer/_display.py.

6. Monitor Progress: The StatusBar updates with current iteration counts, while the console shows loss metrics. The process runs independently of the main GUI thread to prevent interface freezing.

7. Session Persistence: Upon completion or manual stopping, the GUI automatically calls LastSession.save() to preserve your configuration for subsequent training resumes.

Example: Starting Training Programmatically

While the GUI handles this internally, the underlying subprocess call follows this pattern:

from lib.gui import ProcessWrapper

wrapper = ProcessWrapper()
wrapper.start_task(['python', 'scripts/train.py',
                    '--model', 'original',
                    '--dataset', '/path/to/aligned',
                    '--epochs', '20'])

Converting Media with the Faceswap GUI

The Convert tab interfaces with scripts/convert.py and the core engine in lib/convert.py to apply trained models to images or videos. This process swaps faces in source media using the weights generated during training.

Conversion Workflow

1. Access the Convert Tab: Like the Train tab, this is generated dynamically from get_commands() in the GUI configuration.

2. Select Trained Model: The model selector scans your models directory for .h5 checkpoint files and lists available weights compatible with the selected architecture.

3. Input Source Media: Browse or drag-and-drop images and video files. The GUI generates preview thumbnails via get_images() to confirm correct file selection.

4. Configure Output Options: Set the output format, resolution, face-swap masking strength, and audio retention preferences through the options panel.

5. Execute Conversion: The Convert button launches scripts/convert.py through ProcessWrapper.start_task(). Progress indicators and any errors stream to the ConsoleOut display in real-time.

6. Review Results: Converted media saves to your specified output directory, with the GUI providing direct access to open the destination folder upon completion.

Example: Conversion Subprocess Call

The GUI constructs and executes commands similar to the following when you start conversion:

wrapper.start_task(['python', 'scripts/convert.py',
                    '--model-dir', '/models',
                    '--model', 'original_128.h5',
                    '--input-dir', '/media/source',
                    '--output-dir', '/media/output'])

Summary

The Faceswap GUI streamlines deep learning workflows by wrapping command-line functionality in a Tkinter interface:

• Launch the application via python3 scripts/gui.py, optionally specifying a custom configuration file with --configfile.
• Train models by configuring datasets and architectures in the Train tab, which executes plugins/train/training.py in a background ProcessWrapper while displaying logs via ConsoleOut.
• Convert media through the Convert tab, which invokes scripts/convert.py and lib/convert.py to apply trained weights to source files.
• Monitor all operations through the built-in console and status bar without blocking the main UI thread.
• Resume work easily via automatic session saving through LastSession.save().

Frequently Asked Questions

How do I launch the Faceswap GUI with a custom configuration file?

Pass the --configfile argument followed by the path to your .ini file when starting the application: python3 scripts/gui.py --configfile my_config.ini. The lib/gui/gui_config.py module parses this file via load_config() to set default fonts, layout options, and command-specific presets before building the interface.

What happens when I click the Start button in the Training tab?

Clicking Start invokes ProcessWrapper.start_task(), which spawns a separate Python process running scripts/train.py with your selected parameters. This separation keeps the Tkinter interface responsive while the trainer class (e.g., plugins/train/trainer/original.py) handles GPU-intensive optimization. Output streams to the ConsoleOut widget in lib/gui/display.py.

Can I run training and conversion simultaneously in the GUI?

Yes, because the GUI uses ProcessWrapper to spawn independent subprocesses for each operation, you can queue or run multiple tasks concurrently. However, be mindful of GPU memory limitations, as both processes will compete for the same graphics card resources unless configured to use different devices.

Where does the GUI save my training session progress?

The GUI automatically calls LastSession.save() when training ends or is manually stopped, storing your configuration and current state. This allows you to resume training later by reloading the GUI, which reads the saved session and repopulates the Training tab with your previous dataset paths, model selection, and hyperparameters.

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