### Easy Installation

Source: https://github.com/freedomgu/faceswap-1/blob/master/INSTALL.md

Initiates the automated setup script.

```bash
python setup.py
```

--------------------------------

### Manual Installation

Source: https://github.com/freedomgu/faceswap-1/blob/master/INSTALL.md

Commands to manually install GUI dependencies, requirements, and TensorFlow variants.

```bash
conda install tk
```

```bash
pip install -r requirements.txt
```

```bash
conda install tensorflow-gpu
```

```bash
conda install tensorflow
```

--------------------------------

### Run Faceswap Without Docker

Source: https://github.com/freedomgu/faceswap-1/blob/master/INSTALL.md

Example log output showing a successful setup without Docker, including CUDA enablement and Python package installation. Note the warning about TensorFlow compatibility with CUDA 9.1.

```text
INFO    The tool provides tips for installation
        and installs required python packages
INFO    Setup in Linux 4.14.39-1-MANJARO
INFO    Installed Python: 3.6.5 64bit
INFO    Installed PIP: 10.0.1
Enable  Docker? [Y/n] n
INFO    Docker Disabled
Enable  CUDA? [Y/n] 
INFO    CUDA Enabled
INFO    CUDA version: 9.1
INFO    cuDNN version: 7
WARNING Tensorflow has no official prebuild for CUDA 9.1 currently.
        To continue, You have to build your own tensorflow-gpu.
        Help: https://www.tensorflow.org/install/install_sources
Are System Dependencies met? [y/N] y
INFO    Installing Missing Python Packages...
INFO    Installing tensorflow-gpu
INFO    Installing pathlib==1.0.1
......
INFO    Installing tqdm
INFO    Installing matplotlib
INFO    All python3 dependencies are met.
        You are good to go.
```

--------------------------------

### Get Train Help

Source: https://github.com/freedomgu/faceswap-1/blob/master/USAGE.md

View all available arguments for the train command by running the help flag.

```bash
python faceswap.py train -h
```

--------------------------------

### Get Faces in a Specific Frame

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Retrieves a list of detected faces for a given frame name from the alignments data. Each face is represented by a dictionary containing its bounding box and landmarks.

```python
# Get faces for a specific frame
frame_name = "frame_0001.png"
if alignments.frame_exists(frame_name):
    faces = alignments.get_faces_in_frame(frame_name)
    for idx, face in enumerate(faces):
        print(f"Face {idx}: x={face['x']}, y={face['y']}, w={face['w']}, h={face['h']}")
```

--------------------------------

### Clone and Enter Repository

Source: https://github.com/freedomgu/faceswap-1/blob/master/INSTALL.md

Commands to download the project source code and navigate into the directory.

```bash
git clone --depth 1 https://github.com/deepfakes/faceswap.git
```

```bash
cd faceswap
```

--------------------------------

### Create Desktop Shortcut

Source: https://github.com/freedomgu/faceswap-1/blob/master/INSTALL.md

Batch file content to launch the Faceswap GUI directly from Windows.

```batch
%USERPROFILE%\Anaconda3\envs\faceswap\python.exe %USERPROFILE%/faceswap/faceswap.py gui
```

--------------------------------

### Run Faceswap

Source: https://github.com/freedomgu/faceswap-1/blob/master/INSTALL.md

Commands to display help information or launch the graphical user interface.

```bash
python faceswap.py -h
```

```bash
python faceswap.py gui
```

--------------------------------

### View convert command help

Source: https://github.com/freedomgu/faceswap-1/blob/master/USAGE.md

Displays the full list of available arguments for the convert command.

```bash
python faceswap.py convert -h
```

--------------------------------

### Access Help Documentation

Source: https://github.com/freedomgu/faceswap-1/blob/master/USAGE.md

Use the -h flag to view available options for specific faceswap commands.

```bash
python faceswap.py extract -h
```

--------------------------------

### Preview Conversion Settings

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Previews conversion settings without performing a full conversion. Useful for verifying parameters and expected output. Requires input frames and model path.

```bash
python tools.py preview \
    -i ~/faceswap/src/source_frames \
    -m ~/faceswap/models/a_b_model
```

--------------------------------

### Train FaceSwap Models

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Configure and launch model training using command-line arguments.

```bash
python faceswap.py train \
    -A /faces/person_a \
    -B /faces/person_b \
    -m /models/swap_model \
    -t villain \
    -bs 16 \
    -it 1000000 \
    -g 1 \
    -s 100 \
    -ss 25000 \
    -ps 50 \
    -p \
    -w \
    --allow-growth \
    --memory-saving-gradients \
    --warp-to-landmarks \
    -ala /faces/person_a/alignments.json \
    -alb /faces/person_b/alignments.json \
    -L INFO
```

```bash
python faceswap.py train \
    -A /faces/person_a \
    -B /faces/person_b \
    -m /models/swap_model \
    -tia /faces/person_a \
    -tib /faces/person_b \
    -to /timelapse_output
```

--------------------------------

### Execute FaceSwap Main Commands

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Basic usage of the four primary commands: extract, train, convert, and gui.

```bash
# Extract faces from images or video
python faceswap.py extract -i /path/to/source -o /path/to/faces

# Train a model on two face sets
python faceswap.py train -A /path/to/faces/person_a -B /path/to/faces/person_b -m /path/to/model

# Convert faces using a trained model
python faceswap.py convert -i /path/to/source -o /path/to/output -m /path/to/model

# Launch the graphical user interface
python faceswap.py gui
```

--------------------------------

### Run effmpeg conversion tool

Source: https://github.com/freedomgu/faceswap-1/blob/master/README.md

Access the video conversion tool by running this command. It accepts help arguments for more details.

```bash
python tools.py effmpeg -h
```

--------------------------------

### Build and Run Faceswap Docker Image (GPU)

Source: https://github.com/freedomgu/faceswap-1/blob/master/INSTALL.md

Commands to build a Docker image for faceswap with GPU support and run it. This includes options for running with or without the GUI.

```bash
docker build -t deepfakes-gpu -f Dockerfile.gpu .
```

```bash
# without gui. tools.py gui not working.
nvidia-docker run --rm -it -p 8888:8888 \
    --hostname faceswap-gpu --name faceswap-gpu \
    -v /opt/faceswap:/srv \
    deepfakes-gpu
```

```bash
# with gui. tools.py gui working.
## enable local access to X11 server
xhost +local:
## enable nvidia device if working under bumblebee
echo ON > /proc/acpi/bbswitch
## create container 
nvidia-docker run -p 8888:8888 \
    --hostname faceswap-gpu --name faceswap-gpu \
    -v /opt/faceswap:/srv \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e DISPLAY=unix$DISPLAY \
    -e AUDIO_GID=`getent group audio | cut -d: -f3` \
    -e VIDEO_GID=`getent group video | cut -d: -f3` \
    -e GID=`id -g` \
    -e UID=`id -u` \
    deepfakes-gpu
```

```bash
docker exec faceswap-gpu python /srv/faceswap.py gui
```

--------------------------------

### Run FaceSwap GUI

Source: https://github.com/freedomgu/faceswap-1/blob/master/README.md

Launch the graphical user interface for FaceSwap by running this command. This provides an alternative to the command-line operations.

```bash
python faceswap.py gui
```

--------------------------------

### Convert with Custom Color Adjustment and Masking

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Use this command to convert videos with custom color matching (e.g., histogram matching) and masking options. Specify input, output, model, color adjustment, masking, sharpening, and the video writer.

```bash
python faceswap.py convert \
    -i ~/faceswap/src/source.mp4 \
    -o ~/faceswap/converted \
    -m ~/faceswap/models/a_b_model \
    -c match-hist \
    -M predicted \
    -sc sharpen \
    -w ffmpeg
```

--------------------------------

### View Alignments Tool Help

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Displays the help message for the alignments subcommand of the tools.py script, showing available options for managing alignments.

```bash
python tools.py alignments -h
```

--------------------------------

### Initialize DetectedFace from Bounding Box

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Initializes a DetectedFace object using a bounding box dictionary and the source image. This populates the basic face location.

```python
# Initialize from a bounding box dictionary
bounding_box = {
    "left": 100,
    "top": 50,
    "right": 300,
    "bottom": 250
}
image = np.zeros((480, 640, 3), dtype=np.uint8)  # Example image
detected_face.from_bounding_box_dict(bounding_box, image)
```

--------------------------------

### Convert video using trained model

Source: https://github.com/freedomgu/faceswap-1/blob/master/USAGE.md

Executes the face conversion process using a specified input directory, output directory, and trained model path.

```bash
python faceswap.py convert -i ~/faceswap/src/trump/ -o ~/faceswap/converted/ -m ~/faceswap/trump_cage_model/
```

--------------------------------

### Convert Sources with FaceSwap Model

Source: https://github.com/freedomgu/faceswap-1/blob/master/README.md

Use this command to apply a trained face model to your source photos. The original photos should be in the 'original' folder, and the modified output will be saved in the 'modified' folder.

```bash
python faceswap.py convert
```

--------------------------------

### Retrieve Available Plugins

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Use the PluginLoader to query available extractors, models, and converters.

```python
detectors = PluginLoader.get_available_extractors("detect")
# Returns: ['cv2-dnn', 'mtcnn', 's3fd']

aligners = PluginLoader.get_available_extractors("align")
# Returns: ['cv2-dnn', 'fan']

models = PluginLoader.get_available_models()
# Returns: ['dfaker', 'dfl-h128', 'dfl-sae', 'iae', 'lightweight', 'original', 'realface', 'unbalanced', 'villain']

converters = PluginLoader.get_available_convert_plugins("color")
# Returns: ['none', 'avg-color', 'color-transfer', 'manual-balance', 'match-hist', 'seamless-clone']

# Load specific plugins
Detector = PluginLoader.get_detector("s3fd")
Aligner = PluginLoader.get_aligner("fan")
Model = PluginLoader.get_model("villain")
Trainer = PluginLoader.get_trainer("villain")
ColorPlugin = PluginLoader.get_converter("color", "match-hist")

# Get default model
default_model = PluginLoader.get_default_model()
# Returns: 'original'
```

--------------------------------

### Convert Faces using Trained Models

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Command to apply a trained model to swap faces in source media.

```bash
# Basic conversion from images
python faceswap.py convert \
    -i ~/faceswap/src/source_video_frames \
    -o ~/faceswap/converted \
    -m ~/faceswap/models/a_b_model
```

--------------------------------

### Convert with Face Filtering and Frame Ranges

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

This command allows conversion with face filtering and specific frame ranges. Useful for processing only certain parts of a video or specific faces. Requires input, output, model, and optionally face alignments, frame ranges, and face filtering.

```bash
python faceswap.py convert \
    -i ~/faceswap/src/source.mp4 \
    -o ~/faceswap/converted \
    -m ~/faceswap/models/a_b_model \
    -a ~/faceswap/faces/aligned_faces \
    -fr 100-500 1000-1500 \
    -k \
    -j 8
```

--------------------------------

### Extract Faces with FaceSwap

Source: https://github.com/freedomgu/faceswap-1/blob/master/README.md

Run this command to extract faces from the 'src' folder into the 'extract' folder. Ensure you have your raw photos in the 'src' directory.

```bash
python faceswap.py extract
```

--------------------------------

### Tools API

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

The `tools.py` script offers utilities for managing alignments, sorting faces, previewing conversions, video manipulation, and model restoration.

```APIDOC
## Tools API

### Description
Provides command-line utilities for various Faceswap tasks including alignment management, face sorting, conversion previewing, video processing, and model backup restoration.

### Method
Command-line execution using `python tools.py [subcommand]`

### Subcommands and Parameters

#### `alignments`
- **-h** - Show help message for the alignments tool.

#### `sort`
- **-i** (string) - Required - Input directory of faces.
- **-o** (string) - Required - Output directory for sorted faces.
- **-s** (string) - Required - Sorting method (e.g., `face`).

#### `preview`
- **-i** (string) - Required - Input directory of source frames.
- **-m** (string) - Required - Path to the trained model directory.

#### `effmpeg`
- **-a** (string) - Required - Action to perform (e.g., `extract`).
- **-i** (string) - Required - Input file path (e.g., video file).
- **-o** (string) - Required - Output directory path.

#### `restore`
- **-m** (string) - Required - Path to the model directory to restore.

### Request Example
```bash
# View alignments tool help
python tools.py alignments -h

# Sort extracted faces by various methods
python tools.py sort \
    -i ~/faceswap/faces/person_a \
    -o ~/faceswap/faces/person_a_sorted \
    -s face

# Preview conversion settings before full convert
python tools.py preview \
    -i ~/faceswap/src/source_frames \
    -m ~/faceswap/models/a_b_model

# Video manipulation with effmpeg
python tools.py effmpeg \
    -a extract \
    -i ~/faceswap/src/video.mp4 \
    -o ~/faceswap/src/frames

# Restore model from backup
python tools.py restore \
    -m ~/faceswap/models/a_b_model
```
```

--------------------------------

### Initialize PluginLoader

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Initializes the PluginLoader class, which is responsible for dynamically loading various types of plugins (detector, aligner, model, trainer, converter) based on the project's configuration.

```python
from plugins.plugin_loader import PluginLoader

# PluginLoader is initialized here, but no specific usage example is provided in the source.
```

--------------------------------

### Train FaceSwap Model

Source: https://github.com/freedomgu/faceswap-1/blob/master/README.md

Execute this command to train a face model using photos from two specified folders. The trained model will be saved in the 'models' folder. This process requires a dataset of faces for training.

```bash
python faceswap.py train
```

--------------------------------

### Clone Faceswap Repository

Source: https://github.com/freedomgu/faceswap-1/blob/master/INSTALL.md

Use this command to clone the faceswap repository from GitHub. This method is recommended for easy updates.

```bash
git clone https://github.com/deepfakes/faceswap.git
```

--------------------------------

### Train FaceSwap Models

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Commands for training autoencoder models with various architectures and memory optimization settings.

```bash
# Basic training with the Original model
python faceswap.py train \
    -A ~/faceswap/faces/person_a \
    -B ~/faceswap/faces/person_b \
    -m ~/faceswap/models/a_b_model

# Train with Villain model, custom batch size, and live preview
python faceswap.py train \
    -A ~/faceswap/faces/person_a \
    -B ~/faceswap/faces/person_b \
    -m ~/faceswap/models/a_b_model \
    -t villain \
    -bs 16 \
    -it 500000 \
    -p \
    -ps 100 \
    -s 250

# Train with memory-saving options for limited VRAM
python faceswap.py train \
    -A ~/faceswap/faces/person_a \
    -B ~/faceswap/faces/person_b \
    -m ~/faceswap/models/a_b_model \
    -t dfaker \
    -bs 32 \
    --memory-saving-gradients \
    --optimizer-savings \
    --allow-growth

# Train with alignments for masked training
python faceswap.py train \
    -A ~/faceswap/faces/person_a \
    -ala ~/faceswap/faces/person_a/alignments.json \
    -B ~/faceswap/faces/person_b \
    -alb ~/faceswap/faces/person_b/alignments.json \
    -m ~/faceswap/models/a_b_model \
    -t dfl-sae \
    --warp-to-landmarks
```

--------------------------------

### Load Face for Neural Network Input

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Prepares a face for input into a neural network. This involves resizing, normalization, and potentially cropping based on coverage ratio. The result is stored in `detected_face.feed_face`.

```python
# Load face for neural network input
detected_face.load_feed_face(image, size=64, coverage_ratio=0.625, dtype="float32")
feed_face = detected_face.feed_face  # Returns normalized face for NN
```

--------------------------------

### Swap Model Direction for Conversion

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Use this command to swap the model direction, converting from B to A instead of the default A to B. Requires input, output, and model paths.

```bash
python faceswap.py convert \
    -i ~/faceswap/src/source.mp4 \
    -o ~/faceswap/converted \
    -m ~/faceswap/models/a_b_model \
    -s
```

--------------------------------

### Execute Extraction Pipeline

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Initialize the Extractor class to process images and retrieve detected faces and landmarks.

```python
from plugins.extract.pipeline import Extractor

# Initialize extractor with plugins
extractor = Extractor(
    detector="s3fd",
    aligner="fan",
    loglevel="INFO",
    configfile=None,
    multiprocess=True,
    rotate_images=None,
    min_size=20,
    normalize_method="clahe"  # Options: none, clahe, hist, mean
)

# Launch extraction
extractor.launch()

# Process images
input_queue = extractor.input_queue
input_queue.put({
    "filename": "/path/to/image.jpg",
    "image": image_array  # numpy array (H, W, 3) BGR format
})

# Get detected faces
for faces in extractor.detected_faces():
    filename = faces["filename"]
    detected_faces = faces["detected_faces"]  # List of bounding box dicts
    landmarks = faces["landmarks"]  # List of 68-point landmark arrays

    for idx, face in enumerate(detected_faces):
        print(f"Face at ({face['left']}, {face['top']}) - ({face['right']}, {face['bottom']})")
        print(f"Landmarks shape: {landmarks[idx].shape}")  # (68, 2)

# Signal completion
input_queue.put("EOF")
```

--------------------------------

### Restore Model from Backup

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Restores a faceswap model from a backup file. Requires the path to the model directory.

```bash
python tools.py restore \
    -m ~/faceswap/models/a_b_model
```

--------------------------------

### Extract Faces from Video

Source: https://github.com/freedomgu/faceswap-1/blob/master/USAGE.md

Use this command to extract faces from a video file. Specify input video and output directory. An alignments.json file will be created.

```python
python faceswap.py extract -i ~/faceswap/src/cage.mp4 -o ~/faceswap/faces/cage
```

--------------------------------

### Initialize DetectedFace Object

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Initializes an empty DetectedFace object. This object will store information about a detected face, including bounding box, landmarks, and alignment data.

```python
from lib.faces_detect import DetectedFace
import numpy as np

# Create a DetectedFace from detection results
detected_face = DetectedFace()
```

--------------------------------

### PluginLoader Class

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Dynamically loads various plugins (detector, aligner, model, trainer, converter) based on configuration settings.

```APIDOC
## PluginLoader Class

### Description
The `PluginLoader` class is responsible for dynamically loading different types of plugins used by Faceswap, such as face detectors, aligners, models, trainers, and converters. This allows for a flexible and extensible architecture where different implementations can be swapped in and out.

### Initialization
```python
from plugins.plugin_loader import PluginLoader

# Initialization typically happens internally within Faceswap, 
# but can be instantiated directly if needed.
# loader = PluginLoader()
```

### Usage

The `PluginLoader` is generally used internally by the Faceswap application to load the appropriate components based on configuration files or command-line arguments. Specific methods for loading each plugin type (e.g., `load_detector`, `load_model`) are called internally.

### Example (Conceptual)
```python
# This is a conceptual example of how PluginLoader might be used internally.
# Actual usage depends on the Faceswap application's structure.

# Assuming a configuration specifies 'dlib' as the detector
# detector = PluginLoader.load_detector('dlib')

# Assuming a configuration specifies 'a_b_model' as the model
# model = PluginLoader.load_model('a_b_model')

# The PluginLoader handles finding the plugin files, importing them, 
# and instantiating the correct classes.
```
```

--------------------------------

### Generate video from frames

Source: https://github.com/freedomgu/faceswap-1/blob/master/USAGE.md

Stitches individual image frames back into a single video file using libx264 encoding.

```bash
ffmpeg -i video-frame-%0d.png -c:v libx264 -vf "fps=25,format=yuv420p" out.mp4
```

--------------------------------

### Save and Backup Alignments

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Saves the current alignments data to the specified file and creates a timestamped backup of the previous state. Essential for preserving work.

```python
# Save changes and backup
alignments.backup()  # Creates timestamped backup
alignments.save()    # Writes current data
```

--------------------------------

### Train Model with Two Face Sets

Source: https://github.com/freedomgu/faceswap-1/blob/master/USAGE.md

Train a model using two sets of extracted faces. Specify input directories for each face set (A and B) and the output directory for the model.

```bash
python faceswap.py train -A ~/faceswap/faces/trump -B ~/faceswap/faces/cage -m ~/faceswap/trump_cage_model/
```

```bash
python faceswap.py train -A ~/faceswap/faces/trump -B ~/faceswap/faces/cage -m ~/faceswap/trump_cage_model/ -p
```

--------------------------------

### Extract Faces from Source Media

Source: https://github.com/freedomgu/faceswap-1/blob/master/USAGE.md

Commands to extract faces from directories of images or individual video files using the faceswap CLI.

```bash
python faceswap.py extract -i ~/faceswap/src/trump -o ~/faceswap/faces/trump
```

```bash
python faceswap.py extract -i ~/faceswap/src/trump.mp4 -o ~/faceswap/faces/trump
```

```bash
python faceswap.py extract -i ~/faceswap/src/cage -o ~/faceswap/faces/cage
```

--------------------------------

### Load DetectedFace from Alignment Dictionary

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Loads the state of a DetectedFace object from a previously saved alignment dictionary. Requires the alignment data and the source image.

```python
# Load from alignment file entry
detected_face.from_alignment(alignment_dict, image=image)
```

--------------------------------

### Initialize Alignments Class

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Initializes the Alignments class to manage alignment data for a set of frames. Specify the folder containing frames, the base filename for alignments, and the serializer format (e.g., 'json').

```python
from lib.alignments import Alignments

# Load or create alignments file
alignments = Alignments(
    folder="/path/to/source/folder",
    filename="alignments",
    serializer="json"  # Options: json, pickle, yaml
)
```

--------------------------------

### Faceswap Convert API

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

The `faceswap.py convert` command is used for performing the face swapping process with various customization options.

```APIDOC
## Faceswap Convert API

### Description
Performs face swapping on video or image inputs with options for color adjustment, masking, face filtering, and model direction.

### Method
Command-line execution using `python faceswap.py convert`

### Parameters

#### Common Parameters
- **-i** (string) - Required - Input file or directory path.
- **-o** (string) - Required - Output directory path.
- **-m** (string) - Required - Path to the trained model directory.

#### Optional Parameters
- **-c** (string) - Color adjustment method (e.g., `match-hist`).
- **-M** (string) - Mask type (e.g., `predicted`).
- **-sc** (string) - Sharpening method (e.g., `sharpen`).
- **-w** (string) - Video writer backend (e.g., `ffmpeg`).
- **-a** (string) - Path to a directory containing aligned faces for filtering.
- **-fr** (string) - Frame range(s) to process (e.g., `100-500 1000-1500`).
- **-k** - Keep extracted faces after processing.
- **-s** - Swap model direction (B to A instead of A to B).

### Request Example
```bash
# Convert with custom color adjustment and masking
python faceswap.py convert \
    -i ~/faceswap/src/source.mp4 \
    -o ~/faceswap/converted \
    -m ~/faceswap/models/a_b_model \
    -c match-hist \
    -M predicted \
    -sc sharpen \
    -w ffmpeg

# Convert with face filtering and frame ranges
python faceswap.py convert \
    -i ~/faceswap/src/source.mp4 \
    -o ~/faceswap/converted \
    -m ~/faceswap/models/a_b_model \
    -a ~/faceswap/faces/aligned_faces \
    -fr 100-500 1000-1500 \
    -k \
    -j 8

# Swap model direction (B to A instead of A to B)
python faceswap.py convert \
    -i ~/faceswap/src/source.mp4 \
    -o ~/faceswap/converted \
    -m ~/faceswap/models/a_b_model \
    -s
```

### Response

#### Success Response (Output Logs)
- **INFO** - Output Directory: [path]
- **INFO** - Reading alignments from: [path]
- **INFO** - Loading Model from [plugin]
- **Converting** - Progress indicator and completion status.

#### Response Example
```
INFO    Output Directory: /home/user/faceswap/converted
INFO    Reading alignments from: '/home/user/faceswap/src/source_video_frames/alignments.json'
INFO    Loading Model from Villain plugin...
Converting: 100%|████████████████| 1500/1500 [15:30<00:00]
```
```

--------------------------------

### Extract Faces from Folder

Source: https://github.com/freedomgu/faceswap-1/blob/master/USAGE.md

Use this command to extract faces from a folder of images. Specify input folder and output directory. An alignments.json file will be created.

```python
python faceswap.py extract -i ~/faceswap/faces/trump -o ~/faceswap/faces/trump
```

--------------------------------

### Extract Faces from Media

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Commands for detecting and aligning faces from source images or videos.

```bash
# Basic extraction from a folder of images
python faceswap.py extract \
    -i ~/faceswap/src/person_a \
    -o ~/faceswap/faces/person_a

# Extract from video with S3FD detector and FAN aligner
python faceswap.py extract \
    -i ~/faceswap/src/video.mp4 \
    -o ~/faceswap/faces/person_a \
    -D s3fd \
    -A fan \
    -sz 256

# Extract with face filtering and quality controls
python faceswap.py extract \
    -i ~/faceswap/src/person_a \
    -o ~/faceswap/faces/person_a \
    -D mtcnn \
    -A fan \
    -min 60 \
    -bt 10.0 \
    -een 5 \
    --align-eyes \
    -L VERBOSE
```

--------------------------------

### Update Faceswap

Source: https://github.com/freedomgu/faceswap-1/blob/master/INSTALL.md

Commands to pull the latest code and update project dependencies.

```bash
git pull --all
```

```bash
python update_deps.py
```

--------------------------------

### Convert DetectedFace to Alignment Dictionary

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Converts the DetectedFace object into a dictionary format suitable for storage in alignment files. Includes position, size, landmarks, and a hash.

```python
# Convert to alignment dictionary for storage
alignment_dict = detected_face.to_alignment()
# Returns: {"x": 100, "w": 200, "y": 50, "h": 200, "landmarksXY": [...], "hash": "..."}
```

--------------------------------

### Extract Frames from Video using Effmpeg

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Extracts frames from a video file using the effmpeg tool. Specify the action ('extract'), input video, and output directory for frames.

```bash
python tools.py effmpeg \
    -a extract \
    -i ~/faceswap/src/video.mp4 \
    -o ~/faceswap/src/frames
```

--------------------------------

### Extract video frames with FFMPEG

Source: https://github.com/freedomgu/faceswap-1/blob/master/USAGE.md

Splits a video file into individual image frames.

```bash
ffmpeg -i /path/to/my/video.mp4 /path/to/output/video-frame-%d.png
```

--------------------------------

### Load Aligned Face for Training

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Loads and aligns a face from the source image for training purposes. Allows specifying the output size and whether to align eyes. The aligned face is stored in `detected_face.aligned_face`.

```python
# Load aligned face for training (256x256 default)
detected_face.load_aligned(image, size=256, align_eyes=True)
aligned_face = detected_face.aligned_face  # Returns aligned face image
```

--------------------------------

### Set Landmarks for DetectedFace

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Sets the facial landmarks (e.g., 68-point landmarks) for a DetectedFace object. Landmarks are provided as a NumPy array of XY coordinates.

```python
# Set landmarks (68-point facial landmarks)
detected_face.landmarksXY = np.array([
    [120, 80], [125, 85], # ... 68 landmark points
])
```

--------------------------------

### Convert Processed Frames

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Apply color adjustments, masks, and output writers during the conversion phase.

```bash
python faceswap.py convert \
    -i /source/frames \
    -o /output \
    -m /models/swap_model \
    -al /source/frames/alignments.json \
    -c match-hist \
    -M predicted \
    -sc sharpen \
    -w ffmpeg \
    -ref /source/original_video.mp4 \
    -osc 100 \
    -fr 1-1000 \
    -a /faces/aligned_subset \
    -j 8 \
    -g 1 \
    -L VERBOSE
```

--------------------------------

### Iterate Through All Faces in Alignments

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Iterates through all frames and detected faces within the alignments data. Provides the frame name, list of faces, face count, and full path for each frame.

```python
# Iterate through all faces
for frame_name, face_list, face_count, full_name in alignments.yield_faces():
    print(f"{frame_name}: {face_count} faces")
```

--------------------------------

### Alignments Class

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Manages alignments files, which store face detection and landmark data for each frame in a video or image sequence.

```APIDOC
## Alignments Class

### Description
The `Alignments` class provides functionality to read, write, and manipulate alignments files. These files are crucial for storing and accessing face detection bounding boxes and facial landmarks for each frame, enabling consistent face tracking and swapping.

### Initialization
```python
from lib.alignments import Alignments

alignments = Alignments(
    folder="/path/to/source/folder",
    filename="alignments",
    serializer="json"  # Options: json, pickle, yaml
)
```

### Methods

#### `frame_exists(frame_name)`
- Checks if the specified frame exists in the alignments data.
- **Parameters**:
    - **frame_name** (string) - The name of the frame file.
- **Returns** (bool): True if the frame exists, False otherwise.

#### `get_faces_in_frame(frame_name)`
- Retrieves a list of detected faces for a given frame.
- **Parameters**:
    - **frame_name** (string) - The name of the frame file.
- **Returns** (list): A list of dictionaries, where each dictionary represents a face with its coordinates (`x`, `y`, `w`, `h`).

#### `add_face(frame_name, alignment_data)`
- Adds a new face detection record to a specified frame.
- **Parameters**:
    - **frame_name** (string) - The name of the frame file.
    - **alignment_data** (dict) - A dictionary containing the face's alignment information (e.g., `x`, `w`, `y`, `h`, `landmarksXY`, `hash`).
- **Returns** (int): The index of the added face.

#### `filter_hashes(valid_hashes, filter_out=False)`
- Filters the alignments data based on a list of valid face hashes. Can be used to keep or remove specific faces.
- **Parameters**:
    - **valid_hashes** (list) - A list of hashes to filter by.
    - **filter_out** (bool) - If True, removes faces with hashes *not* in `valid_hashes`. If False (default), keeps only faces with hashes *in* `valid_hashes`.

#### `backup()`
- Creates a timestamped backup of the current alignments file.

#### `save()`
- Writes the current alignments data to the alignments file.

#### `yield_faces()`
- An iterator that yields information about each frame and its detected faces.
- **Yields**:
    - `frame_name` (string): The name of the frame file.
    - `face_list` (list): The list of detected faces for the frame.
    - `face_count` (int): The number of faces detected in the frame.
    - `full_name` (string): The full path to the frame file.

### Properties
- **frames_count** (int) - The total number of frames with detected faces.
- **faces_count** (int) - The total number of faces detected across all frames.
- **have_alignments_file** (bool) - True if an alignments file exists for the specified folder, False otherwise.

### Request Example
```python
from lib.alignments import Alignments

# Load or create alignments file
alignments = Alignments(
    folder="/path/to/source/folder",
    filename="alignments",
    serializer="json"  # Options: json, pickle, yaml
)

# Check alignments status
print(f"Frames with faces: {alignments.frames_count}")
print(f"Total faces detected: {alignments.faces_count}")
print(f"File exists: {alignments.have_alignments_file}")

# Get faces for a specific frame
frame_name = "frame_0001.png"
if alignments.frame_exists(frame_name):
    faces = alignments.get_faces_in_frame(frame_name)
    for idx, face in enumerate(faces):
        print(f"Face {idx}: x={face['x']}, y={face['y']}, w={face['w']}, h={face['h']}")

# Add a new face to a frame
new_alignment = {
    "x": 150,
    "w": 180,
    "y": 75,
    "h": 180,
    "landmarksXY": [[160, 100], [170, 105], ...],  # 68 points
    "hash": "abc123..."
}
face_index = alignments.add_face("frame_0002.png", new_alignment)

# Filter faces by hash (for cleanup)
valid_hashes = ["hash1", "hash2", "hash3"]
alignments.filter_hashes(valid_hashes, filter_out=False)  # Keep only these faces

# Save changes and backup
alignments.backup()  # Creates timestamped backup
alignments.save()    # Writes current data

# Iterate through all faces
for frame_name, face_list, face_count, full_name in alignments.yield_faces():
    print(f"{frame_name}: {face_count} faces")
```
```

--------------------------------

### Add a New Face Alignment to a Frame

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Adds a new face's alignment data to a specified frame. This includes the face's bounding box, landmarks, and a unique hash. Returns the index of the added face.

```python
# Add a new face to a frame
new_alignment = {
    "x": 150,
    "w": 180,
    "y": 75,
    "h": 180,
    "landmarksXY": [[160, 100], [170, 105], ...],  # 68 points
    "hash": "abc123..."
}
face_index = alignments.add_face("frame_0002.png", new_alignment)
```

--------------------------------

### Sort Extracted Faces

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Sorts extracted faces in a directory based on specified criteria (e.g., 'face'). Useful for organizing and preparing datasets. Requires input, output, and sorting method.

```bash
python tools.py sort \
    -i ~/faceswap/faces/person_a \
    -o ~/faceswap/faces/person_a_sorted \
    -s face
```

--------------------------------

### Check Alignments File Status

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Provides information about the current state of the alignments file, including the number of frames with detected faces, the total number of faces, and whether an alignments file already exists.

```python
# Check alignments status
print(f"Frames with faces: {alignments.frames_count}")
print(f"Total faces detected: {alignments.faces_count}")
print(f"File exists: {alignments.have_alignments_file}")
```

--------------------------------

### DetectedFace Class

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Represents a detected face, storing its bounding box, landmarks, and alignment information, with methods for loading and processing face images.

```APIDOC
## DetectedFace Class

### Description
The `DetectedFace` class encapsulates the data for a single detected face, including its location, facial landmarks, and alignment details. It provides methods to load and prepare face images for training or conversion.

### Methods

#### `from_bounding_box_dict(bounding_box, image)`
- Initializes the `DetectedFace` object from a dictionary containing bounding box coordinates (`left`, `top`, `right`, `bottom`) and the source image.

#### `load_aligned(image, size=256, align_eyes=True)`
- Loads and aligns the face from the given `image` to a specified `size`. `align_eyes` attempts to align based on eye positions.
- **Returns**: The aligned face image.

#### `load_feed_face(image, size=64, coverage_ratio=0.625, dtype='float32')`
- Loads and prepares the face for input into a neural network, resizing to `size` and applying normalization.
- **Returns**: The processed face image suitable for NN input.

#### `to_alignment()`
- Converts the `DetectedFace` object's data into a dictionary format suitable for saving to an alignments file.
- **Returns**: A dictionary containing face coordinates, landmarks, and hash.

#### `from_alignment(alignment_dict, image=None)`
- Populates the `DetectedFace` object from a dictionary obtained from an alignments file. Optionally uses an `image` to recalculate certain properties.

### Properties
- **landmarksXY** (numpy.ndarray) - A NumPy array containing the X, Y coordinates of facial landmarks.
- **aligned_face** (numpy.ndarray) - The processed, aligned face image after calling `load_aligned`.
- **feed_face** (numpy.ndarray) - The processed face image ready for neural network input after calling `load_feed_face`.

### Request Example
```python
from lib.faces_detect import DetectedFace
import numpy as np

# Create a DetectedFace from detection results
detected_face = DetectedFace()

# Initialize from a bounding box dictionary
bounding_box = {
    "left": 100,
    "top": 50,
    "right": 300,
    "bottom": 250
}
image = np.zeros((480, 640, 3), dtype=np.uint8)  # Example image
detected_face.from_bounding_box_dict(bounding_box, image)

# Set landmarks (68-point facial landmarks)
detected_face.landmarksXY = np.array([
    [120, 80], [125, 85], # ... 68 landmark points
])

# Load aligned face for training (256x256 default)
detected_face.load_aligned(image, size=256, align_eyes=True)
aligned_face = detected_face.aligned_face  # Returns aligned face image

# Load face for neural network input
detected_face.load_feed_face(image, size=64, coverage_ratio=0.625, dtype="float32")
feed_face = detected_face.feed_face  # Returns normalized face for NN

# Convert to alignment dictionary for storage
alignment_dict = detected_face.to_alignment()
# Returns: {"x": 100, "w": 200, "y": 50, "h": 200, "landmarksXY": [...], "hash": "..."}

# Load from alignment file entry
detected_face.from_alignment(alignment_dict, image=image)
```
```

--------------------------------

### Filter Faces by Hash

Source: https://context7.com/freedomgu/faceswap-1/llms.txt

Filters the alignments data to keep or remove faces based on a list of valid hashes. Useful for cleaning up duplicate or unwanted detections. `filter_out=False` keeps only the specified hashes.

```python
# Filter faces by hash (for cleanup)
valid_hashes = ["hash1", "hash2", "hash3"]
alignments.filter_hashes(valid_hashes, filter_out=False)  # Keep only these faces
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.