scripts package

The Scripts Package is the entry point into Faceswap.

extract module

Main entry point to the extract process of FaceSwap

class scripts.extract.Extract(arguments: Namespace)

Bases: object

The Faceswap Face Extraction Process.

The extraction process is responsible for detecting faces in a series of images/video, aligning these faces and then generating a mask.

It leverages a series of user selected plugins, chained together using plugins.extract.pipeline.

The extract process is self contained and should not be referenced by any other scripts, so it contains no public properties.

Parameters:

arguments (argparse.Namespace) – The arguments to be passed to the extraction process as generated from Faceswap’s command line arguments

process() → None

The entry point for triggering the Extraction Process.

Should only be called from lib.cli.launcher.ScriptExecutor

class scripts.extract.Filter(threshold: float, filter_files: list[str] | None, nfilter_files: list[str] | None, extractor: Extractor)

Bases: object

Obtains and holds face identity embeddings for any filter/nfilter image files passed in from the command line.

Parameters:

• filter_files (list or None) – The list of filter file(s) passed in as command line arguments

• nfilter_files (list or None) – The list of nfilter file(s) passed in as command line arguments

• extractor (Extractor) – The extractor pipeline for obtaining face identity from images

property active

True if filter files have been passed in command line arguments. False if no filter files have been provided

Type:

bool

property embeddings: ndarray

The filter embeddings

Type:

numpy.ndarray

property n_embeddings: ndarray

The n-filter embeddings

Type:

numpy.ndarray

class scripts.extract.PipelineLoader(path: str | list[str], extractor: Extractor, aligned_filenames: list[str] | None = None)

Bases: object

Handles loading and reloading images into the extraction pipeline.

Parameters:

• path (str or list of str) – Full path to a folder of images or a video file or a list of image files

• extractor (Extractor) – The extractor pipeline for obtaining face identity from images

• aligned_filenames (list, optional) – Used for when the loader is used for getting face filter embeddings. List of full path to image files that exist in path that are aligned faceswap images

add_skip_list(skip_list: list[int]) → None

Add a skip list to the ImagesLoader

Parameters:

skip_list (list) – A list of indices corresponding to the frame indices that should be skipped by the load() function.

check_thread_error() → None

Check if any errors have occurred in the running threads and raise their errors

property file_list: list[str]

A full list of files in the source location. If the input is a video then this is a list of dummy filenames as corresponding to an alignments file

Type:

list

property is_video: bool

True if the input location is a video file, False if it is a folder of images

Type:

bool

join() → None

Join all open loader threads

launch() → None

Launch the image loading pipeline

property process_count: int

The number of images or video frames to be processed (IE the total count less items that are to be skipped from the skip_list)

Type:

int

reload(detected_faces: dict[str, plugins.extract.extract_media.ExtractMedia]) → None

Reload images for multiple pipeline passes

train module

Main entry point to the training process of FaceSwap

class scripts.train.PreviewInterface(use_preview: bool)

Bases: object

Run the preview window in a thread and interface with it

Parameters:

use_preview (bool) – True if pop-up preview window has been requested otherwise False

property buffer: PreviewBuffer

The thread save preview image object

Type:

PreviewBuffer

property should_quit: bool

Check whether an exit request has been made. True if an exit request has been made otherwise False.

Raises:

Error – Re-raises any error within the preview thread

Type:

bool

property should_refresh: bool

Check whether the preview should be updated and return the value. If True is returned then resets the refresh trigger back to False

Type:

bool

property should_save: bool

Check whether a save request has been made. If True is returned then save trigger is set back to False

Type:

bool

property should_toggle_mask: bool

Check whether the mask should be toggled and return the value. If True is returned then resets mask toggle back to False

Type:

bool

shutdown() → None

Send a signal to shutdown the preview window.

class scripts.train.Train(arguments: argparse.Namespace)

Bases: object

The Faceswap Training Process.

The training process is responsible for training a model on a set of source faces and a set of destination faces.

The training process is self contained and should not be referenced by any other scripts, so it contains no public properties.

Parameters:

arguments (argparse.Namespace) – The arguments to be passed to the training process as generated from Faceswap’s command line arguments

process() → None

The entry point for triggering the Training Process.

Should only be called from lib.cli.launcher.ScriptExecutor

convert module

Module Summary

Convert	The Faceswap Face Conversion Process.
DiskIO	Disk Input/Output for the converter process.
OptionalActions	Process specific optional actions for Convert.
Predict	Obtains the output from the Faceswap model.

Module

Main entry point to the convert process of FaceSwap

class scripts.convert.Convert(arguments: Namespace)

Bases: object

The Faceswap Face Conversion Process.

The conversion process is responsible for swapping the faces on source frames with the output from a trained model.

It leverages a series of user selected post-processing plugins, executed from lib.convert.Converter.

The convert process is self contained and should not be referenced by any other scripts, so it contains no public properties.

Parameters:

arguments (argparse.Namespace) – The arguments to be passed to the convert process as generated from Faceswap’s command line arguments

process() → None

The entry point for triggering the Conversion Process.

Should only be called from lib.cli.launcher.ScriptExecutor

Raises:

FaceswapError – Error raised if the process runs out of memory

class scripts.convert.ConvertItem(inbound: ~plugins.extract.extract_media.ExtractMedia, feed_faces: list[lib.align.aligned_face.AlignedFace] = <factory>, reference_faces: list[lib.align.aligned_face.AlignedFace] = <factory>, swapped_faces: ~numpy.ndarray = array([], dtype=float64))

Bases: object

A single frame with associated objects passing through the convert process.

Parameters:

• input (ExtractMedia) – The ExtractMedia object holding the filename, image and attr:list of DetectedFace objects loaded from disk

• feed_faces (list, Optional) – list of lib.align.AlignedFace objects for feeding into the model’s predict function

• reference_faces (list, Optional) – list of lib.align.AlignedFace objects at model output sized for using as reference in the convert functionfor feeding into the model’s predict

• swapped_faces (np.ndarray) – The swapped faces returned from the model’s predict function

feed_faces: list[lib.align.aligned_face.AlignedFace]

inbound: ExtractMedia

reference_faces: list[lib.align.aligned_face.AlignedFace]

swapped_faces: ndarray = array([], dtype=float64)

class scripts.convert.DiskIO(alignments: Alignments, images: ImagesLoader, predictor: Predict, arguments: Namespace)

Bases: object

Disk Input/Output for the converter process.

Background threads to:

• Load images from disk and get the detected faces

• Save images back to disk

Parameters:

• alignments (lib.alignmnents.Alignments) – The alignments for the input video

• images (lib.image.ImagesLoader) – The input images

• predictor (Predict) – The object for generating predictions from the model

• arguments (argparse.Namespace) – The arguments that were passed to the convert process as generated from Faceswap’s command line arguments

property completion_event: Event

Event is set when the DiskIO Save task is complete

Type:

event.Event

property draw_transparent: bool

True if the selected writer’s Draw_transparent configuration item is set otherwise False

Type:

bool

property load_queue: EventQueue

The queue that images and detected faces are ” “loaded into.

Type:

EventQueue

property load_thread: MultiThread

The thread that is running the image loading operation.

Type:

lib.multithreading.MultiThread

property pre_encode: Callable[[np.ndarray, T.Any], list[bytes]] | None

Selected writer’s pre-encode function, if it has one, otherwise None

Type:

python function

property save_thread: MultiThread

The thread that is running the image writing operation.

Type:

lib.multithreading.MultiThread

class scripts.convert.OptionalActions(arguments: Namespace, input_images: list[np.ndarray], alignments: Alignments)

Bases: object

Process specific optional actions for Convert.

Currently only handles skip faces. This class should probably be (re)moved.

Parameters:

• arguments (argparse.Namespace) – The arguments that were passed to the convert process as generated from Faceswap’s command line arguments

• input_images (list) – List of input image files

• alignments (lib.align.Alignments) – The alignments file for this conversion

class scripts.convert.Predict(queue_size: int, arguments: Namespace)

Bases: object

Obtains the output from the Faceswap model.

Parameters:

• queue_size (int) – The maximum size of the input queue

• arguments (argparse.Namespace) – The arguments that were passed to the convert process as generated from Faceswap’s command line arguments

property centering: CenteringType

The centering that the model was trained on (“head”, “face” or “legacy”)

Type:

str

property coverage_ratio: float

The coverage ratio that the model was trained at.

Type:

float

property faces_count: int

The total number of faces seen by the Predictor.

Type:

int

property has_predicted_mask: bool

True if the model was trained to learn a mask, otherwise False.

Type:

bool

property in_queue: EventQueue

The input queue to the predictor.

Type:

EventQueue

launch(load_queue: EventQueue) → None

Launch the prediction process in a background thread.

Starts the prediction thread and returns the thread.

Parameters:

load_queue (EventQueue) – The queue that contains images and detected faces for feeding the model

load_aligned(item: ConvertItem) → None

Load the model’s feed faces and the reference output faces.

For each detected face in the incoming item, load the feed face and reference face images, correctly sized for input and output respectively.

Parameters:

item (ConvertMedia) – The convert media object, containing the ExctractMedia for the current image

property out_queue: EventQueue

The output queue from the predictor.

Type:

EventQueue

property output_size: int

The size in pixels of the Faceswap model output.

Type:

int

property thread: MultiThread

The thread that is running the prediction function from the Faceswap model.

Type:

MultiThread

property verify_output: bool

True if multiple faces have been found in frames, otherwise False.

Type:

bool

fsmedia module

Module Summary

Alignments	Override lib.align.Alignments to add custom loading based on command line arguments.
DebugLandmarks	Draw debug landmarks on face output.
Images	Handles the loading of frames from a folder of images or a video file for extract and convert processes.
PostProcess	Optional pre/post processing tasks for convert and extract.
finalize	Output summary statistics at the end of the extract or convert processes.

Module

Helper functions for extract and convert.

Holds the classes for the 2 main Faceswap ‘media’ objects: Images and Alignments.

Holds optional pre/post processing functions for convert and extract.

class scripts.fsmedia.Alignments(arguments: Namespace, is_extract: bool, input_is_video: bool = False)

Bases: Alignments

Override lib.align.Alignments to add custom loading based on command line arguments.

Parameters:

• arguments (argparse.Namespace) – The command line arguments that were passed to Faceswap

• is_extract (bool) – True if the process calling this class is extraction otherwise False

• input_is_video (bool, optional) – True if the input to the process is a video, False if it is a folder of images. Default: False

class scripts.fsmedia.DebugLandmarks(*args, **kwargs)

Bases: PostProcessAction

Draw debug landmarks on face output. Extract Only

process(extract_media: ExtractMedia) → None

Draw landmarks on a face.

Parameters:

extract_media (ExtractMedia) – The ExtractMedia object that contains the faces to draw the landmarks on to

class scripts.fsmedia.Images(arguments: Namespace)

Bases: object

Handles the loading of frames from a folder of images or a video file for extract and convert processes.

Parameters:

arguments (argparse.Namespace) – The command line arguments that were passed to Faceswap

property images_found: int

The number of frames that exist in the video file, or the folder of images.

Type:

int

property input_images: str | list[str]

Path to the video file if the input is a video otherwise list of image paths.

Type:

str or list

property is_video: bool

True if the input is a video file otherwise False.

Type:

bool

load() → Generator[tuple[str, np.ndarray], None, None]

Generator to load frames from a folder of images or from a video file.

Yields:

• filename (str) – The filename of the current frame

• image (numpy.ndarray) – A single frame

load_one_image(filename) → ndarray

Obtain a single image for the given filename.

Parameters:

filename (str) – The filename to return the image for

Returns:

The image for the requested filename,

Return type:

numpy.ndarray

class scripts.fsmedia.PostProcess(arguments: Namespace)

Bases: object

Optional pre/post processing tasks for convert and extract.

Builds a pipeline of actions that have optionally been requested to be performed in this session.

Parameters:

arguments (argparse.Namespace) – The command line arguments that were passed to Faceswap

do_actions(extract_media: ExtractMedia) → None

Perform the requested optional post-processing actions on the given image.

Parameters:

extract_media (ExtractMedia) – The ExtractMedia object to perform the action on.

Returns:

The original ExtractMedia with any actions applied

Return type:

ExtractMedia

class scripts.fsmedia.PostProcessAction(*args, **kwargs)

Bases: object

Parent class for Post Processing Actions.

Usable in Extract or Convert or both depending on context. Any post-processing actions should inherit from this class.

Parameters:

• args (tuple) – Varies for specific post process action

• kwargs (dict) – Varies for specific post process action

process(extract_media: ExtractMedia) → None

Override for specific post processing action

Parameters:

extract_media (ExtractMedia) – The ExtractMedia object to perform the action on.

property valid: bool

True if the action if the parameters passed in for this action are valid, otherwise False

Type:

bool

scripts.fsmedia.finalize(images_found: int, num_faces_detected: int, verify_output: bool) → None

Output summary statistics at the end of the extract or convert processes.

Parameters:

• images_found (int) – The number of images/frames that were processed

• num_faces_detected (int) – The number of faces that have been detected

• verify_output (bool) – True if multiple faces were detected in frames otherwise False.