convert package

The Convert Package handles the various plugins available for performing conversion in Faceswap

mask package 

mask.mask_blend module 

Plugin to blend the edges of the face between the swap and the original face.

class plugins.convert.mask.mask_blend.Mask(mask_type: str, output_size: int, coverage_ratio: float, configfile: str | None = None, config: FaceswapConfig | None = None)

Bases: object

Manipulations to perform to the mask that is to be applied to the output of the Faceswap model.

Parameters:

mask_type (str) – The mask type to use for this plugin
output_size (int) – The size of the output from the Faceswap model.
coverage_ratio (float) – The coverage ratio that the Faceswap model was trained at.
configfile (str, Optional) – Optional location of custom configuration ini file. If None then use the default config location. Default: None
config (lib.config.FaceswapConfig, Optional) – Optional pre-loaded lib.config.FaceswapConfig. If passed, then this will be used over any configuration on disk. If None then it is ignored. Default: None

run(detected_face: DetectedFace, source_offset: ndarray, target_offset: ndarray, centering: Literal['legacy', 'face', 'head'], predicted_mask: ndarray | None = None) → tuple[numpy.ndarray, numpy.ndarray]

Obtain the requested mask type and perform any defined mask manipulations.

Parameters:

detected_face (lib.align.DetectedFace) – The DetectedFace object as returned from scripts.convert.Predictor.
source_offset (numpy.ndarray) – The (x, y) offset for the mask at its stored centering
target_offset (numpy.ndarray) – The (x, y) offset for the mask at the requested target centering
centering ([“legacy”, “face”, “head”]) – The centering to obtain the mask for
predicted_mask (numpy.ndarray, optional) – The predicted mask as output from the Faceswap Model, if the model was trained with a mask, otherwise None. Default: None.

Returns:

mask (numpy.ndarray) – The mask with all requested manipulations applied
raw_mask (numpy.ndarray) – The mask with no erosion/dilation applied

writer package 

writer._base module 

Parent class for output writers for faceswap.py converter

class plugins.convert.writer._base.Output(output_folder: str, configfile: str | None = None)

Bases: object

Parent class for writer plugins.

Parameters:

output_folder (str) – The full path to the output folder where the converted media should be saved
configfile (str, optional) – The full path to a custom configuration ini file. If None is passed then the file is loaded from the default location. Default: None.

cache_frame(filename: str, image: ndarray) → None

Add the incoming converted frame to the cache ready for writing out.

Used for ffmpeg and gif writers to ensure that the frames are written out in the correct order.

Parameters:

filename (str) – The filename of the incoming frame, where the frame index can be extracted from
image (class:numpy.ndarray) – The converted frame corresponding to the given filename

close() → None: Override for specific converted frame writing close methods

property is_stream: bool

Whether the writer outputs a stream or a series images.

Writers that write to a stream have a frame_order paramater to dictate the order in which frames should be written out (eg. gif/ffmpeg)

Type:: bool

output_filename(filename: str, separate_mask: bool = False) → list[str]

Obtain the full path for the output file, including the correct extension, for the given input filename.

NB: The plugin must have a config item ‘format’ that contains the file extension to use this method.

Parameters:

filename (str) – The input frame filename to generate the output file name for
separate_mask (bool, optional) – True if the mask should be saved out to a sub-folder otherwise False

Returns:

The full path for the output converted frame to be saved to in position 1. The full path for the mask to be output to in position 2 (if requested)

Return type:

list

pre_encode(image: ndarray, **kwargs) → Any

Some writer plugins support the pre-encoding of images prior to saving out. As patching is done in multiple threads, but writing is done in a single thread, it can speed up the process to do any pre-encoding as part of the converter process.

If the writer supports pre-encoding then override this to pre-encode the image in lib.convert to speed up saving.

Parameters:: image (numpy.ndarray) – The converted image that is to be run through the pre-encoding function
Returns:: If None then the writer does not support pre-encoding, otherwise return output of the plugin specific pre-enccode function
Return type:: Any or None

write(filename: str, image: Any) → None

Override for specific frame writing method.

Parameters:

filename (str) – The incoming frame filename.
image (Any) – The converted image to be written. Could be a numpy array, a bytes encoded image or any other plugin specific format

plugins.convert.writer._base.get_config(plugin_name: str, configfile: str | None = None) → dict

Obtain the configuration settings for the writer plugin.

Parameters:

plugin_name (str) – The name of the convert plugin to return configuration settings for
configfile (str, optional) – The full path to a custom configuration ini file. If None is passed then the file is loaded from the default location. Default: None.

Returns:

The requested configuration dictionary

Return type:

dict

writer.ffmpeg module 

Video output writer for faceswap.py converter

class plugins.convert.writer.ffmpeg.Writer(output_folder: str, total_count: int, frame_ranges: list[tuple[int, int]] | None, source_video: str, **kwargs)

Bases: Output

Video output writer using imageio-ffmpeg.

Parameters:

output_folder (str) – The folder to save the output video to
total_count (int) – The total number of frames to be converted
frame_ranges (list or None) – List of tuples for starting and end values of each frame range to be converted or None if all frames are to be converted
source_video (str) – The full path to the source video for obtaining fps and audio
kwargs (dict) – Any additional standard plugins.convert.writer._base.Output key word arguments.

close() → None: Close the ffmpeg writer and mux the audio

write(filename: str, image: ndarray) → None

Frames come from the pool in arbitrary order, so frames are cached for writing out in the correct order.

Parameters:

filename (str) – The incoming frame filename.
image (numpy.ndarray) – The converted image to be written

writer.gif module 

Animated GIF writer for faceswap.py converter

class plugins.convert.writer.gif.Writer(output_folder: str, total_count: int, frame_ranges: list[tuple[int, int]] | None, **kwargs)

Bases: Output

GIF output writer using imageio.

Parameters:

output_folder (str) – The folder to save the output gif to
total_count (int) – The total number of frames to be converted
frame_ranges (list or None) – List of tuples for starting and end values of each frame range to be converted or None if all frames are to be converted
kwargs (dict) – Any additional standard plugins.convert.writer._base.Output key word arguments.

close() → None: Close the GIF writer on completion.

write(filename: str, image) → None

Frames come from the pool in arbitrary order, so frames are cached for writing out in the correct order.

Parameters:

filename (str) – The incoming frame filename.
image (numpy.ndarray) – The converted image to be written

writer.opencv module 

Image output writer for faceswap.py converter Uses cv2 for writing as in testing this was a lot faster than both Pillow and ImageIO

class plugins.convert.writer.opencv.Writer(output_folder: str, **kwargs)

Bases: Output

Images output writer using cv2

Parameters:

output_folder (str) – The full path to the output folder where the converted media should be saved
configfile (str, optional) – The full path to a custom configuration ini file. If None is passed then the file is loaded from the default location. Default: None.

close() → None: Does nothing as OpenCV writer does not need a close method

pre_encode(image: ndarray, **kwargs) → list[bytes]

Pre_encode the image in lib/convert.py threads as it is a LOT quicker.

Parameters:: image (numpy.ndarray) – A 3 or 4 channel BGR swapped frame
Returns:: List of bytes objects ready for writing. The list will be of length 1 with image bytes object as the only member unless separate mask has been requested, in which case it will be length 2 with the image in position 0 and mask in position 1
Return type:: list

write(filename: str, image: list[bytes]) → None

Write out the pre-encoded image to disk. If separate mask has been selected, write out the encoded mask to a sub-folder in the output directory.

Parameters:

filename (str) – The full path to write out the image to.
image (list) – List of bytes objects of length 1 (containing just the image to write out) or length 2 (containing the image and mask to write out)

writer.patch module 

Face patch output writer for faceswap.py converter Extracts the swapped Face Patch from faceswap rather than the final composited frame along with the transformation matrix for re-inserting the face into the origial frame

class plugins.convert.writer.patch.Writer(output_folder: str, patch_size: int, **kwargs)

Bases: Output

Face patch writer for outputting swapped face patches and transformation matrices

Parameters:

output_folder (str) – The full path to the output folder where the face patches should besaved
patch_size (int) – The size of the face patch output from the model
configfile (str, optional) – The full path to a custom configuration ini file. If None is passed then the file is loaded from the default location. Default: None.

close() → None: Outputs json file if requested

pre_encode(image: ndarray, **kwargs) → list[list[bytes]]

Pre_encode the image in lib/convert.py threads as it is a LOT quicker.

Parameters:

image (numpy.ndarray) – A 3 or 4 channel BGR swapped face batch as float32
canvas_size (tuple[int, int]) – The size of the canvas (x, y) that the transformation matrix applies to.
matrices (numpy.ndarray, optional) – The transformation matrices for extracting the face patches from the original frame. Must be provided if an image is provided, otherwise None to insert a dummy matrix

Returns:

List of bytes objects ready for writing. The list will be of length 1 with image bytes object as the only member unless separate mask has been requested, in which case it will be length 2 with the image in position 0 and mask in position 1

Return type:

list

write(filename: str, image: list[list[bytes]]) → None

Write out the pre-encoded image to disk. If separate mask has been selected, write out the encoded mask to a sub-folder in the output directory.

Parameters:

filename (str) – The full path to write out the image to.
image (list[list[bytes]]) – List of list of bytes objects of containing all swapped faces from a frame to write out. The inner list will be of length 1 (mask included in the alpha channel) or length 2 (mask to write out separately)

writer.pillow module 

Image output writer for faceswap.py converter

class plugins.convert.writer.pillow.Writer(output_folder: str, **kwargs)

Bases: Output

Images output writer using Pillow

Parameters:

output_folder (str) – The full path to the output folder where the converted media should be saved
configfile (str, optional) – The full path to a custom configuration ini file. If None is passed then the file is loaded from the default location. Default: None.

close() → None: Does nothing as Pillow writer does not need a close method

pre_encode(image: ndarray, **kwargs) → list[_io.BytesIO]

Pre_encode the image in lib/convert.py threads as it is a LOT quicker

Parameters:: image (numpy.ndarray) – A 3 or 4 channel BGR swapped frame
Returns:: List of BytesIO objects ready for writing. The list will be of length 1 with image bytes object as the only member unless separate mask has been requested, in which case it will be length 2 with the image in position 0 and mask in position 1
Return type:: list

write(filename: str, image: list[_io.BytesIO]) → None

Write out the pre-encoded image to disk. If separate mask has been selected, write out the encoded mask to a sub-folder in the output directory.

Parameters:

filename (str) – The full path to write out the image to.
image (list) – List of BytesIO objects of length 1 (containing just the image to write out) or length 2 (containing the image and mask to write out)