Stitchface

Getting Stitchface to actually work for batch face replacement

Most people approach Stitchface with the wrong expectations. They download it, run the default configuration on a single photo, get decent results, and assume they understand the tool. That's when things fall apart. The real work starts when you need to process dozens of images with consistent lighting and angle variation, which is the actual use case for anyone doing serious work. Stitchface is a face-blending and replacement toolkit built around seamless integration of swapped faces into source images. It uses landmark detection, mesh warping, and color matching to blend the target face into the source scene. The pipeline sounds straightforward until you realize how fragile the alignment step is. One off-by-one pixel error in landmark detection and the entire blend looks wrong in ways that are hard to debug. I spent three weeks trying to get consistent results across a batch of group photos where people were at varying distances from the camera. The default settings handled close-up portraits fine, but faces in the background kept producing halos around the jawline. The issue wasn't the blending algorithm itself. It was the landmark confidence threshold being too loose for smaller face regions. I dropped the minimum confidence score from 0.5 to 0.75 and switched to a subpixel refinement pass, which cleaned up the boundary artifacts almost entirely. Took about twenty minutes to adjust.

The installation and setup process

You can grab Stitchface from its official GitHub repository. The standard install involves cloning the repo, setting up a Python virtual environment, and installing the dependencies. Make sure you're running Python 3.8 or later. The pre-built models download automatically on first run, but they require a stable internet connection and roughly 2GB of disk space for the landmark detection and blending weights. Once installed, the basic command structure looks like this: stitchface process --source input.jpg --target face.jpg --output result.jpg

That command runs the default pipeline. It detects landmarks on both faces, computes the warp transform, applies the blend, and writes the output. For a single image, this usually takes between five and fifteen seconds depending on your GPU. Without a GPU, expect it to take thirty to sixty seconds per image.

Batch processing and automation

Here's where the tool actually becomes useful. You can pass a directory of source images and a directory of target faces, and Stitchface will match them based on detected face positions. The matching is purely positional by default, which means the first face detected in each source image gets the first target face you provide. This is both a feature and a limitation. If you have multiple faces in a source image and want specific targets assigned to specific positions, you need to use the JSON configuration file to define explicit mappings. A typical config file looks like this: {
"matches": [
{"source_image": "group1.jpg", "face_index": 0, "target": "person_a.jpg"},
{"source_image": "group1.jpg", "face_index": 1, "target": "person_b.jpg"}
]
}

Run it with stitchface batch --config mappings.json --output-dir results/. Processing a folder of fifty images with this setup took me about eight minutes on a machine with an RTX 3070. Same job without batching, running each image individually through a loop, took roughly forty minutes because of the overhead from repeated model loading.

Common failures and workarounds

Stitchface struggles with extreme angles. If a face in the source image is turned more than about forty-five degrees from frontal, the landmark detector starts losing points, and the mesh warp produces visible distortions around the nose and cheek area. I found that enabling the --robust-alignment flag helps marginally, but it doesn't solve the problem. The practical workaround is to rotate the source image so the face is closer to frontal before running the pipeline, then rotate the output back. You can do this in a preprocessing step with a simple ImageMagick command or any batch image tool. Another failure mode is high-contrast lighting between the target face and the source image. If you paste a face shot in bright studio lighting onto a photo taken at night, the color mismatch is obvious even after the blending pass. Stitchface does attempt color transfer using methods like Reinhard or mLAB color space adjustment, but it can't generate illumination that doesn't exist in the source. The fix is to preprocess the target face with exposure and color grading to approximate the source scene's lighting before running the blend. This step alone is what separated acceptable results from reject-quality output in my workflow.

Performance considerations

The memory usage can get steep if you're processing high-resolution images. The tool loads entire images into memory during the warp and blend stages, so a batch of 4K images will consume significant RAM. I've seen it use up to 8GB of memory during a single large job. If you're working with a constrained system, resizing images to a maximum dimension of 1920 pixels before processing reduces memory usage dramatically with minimal quality loss for most practical purposes. The CPU fallback is slow but functional. If you don't have a compatible NVIDIA GPU, the tool falls back to CPU execution automatically. Don't bother trying to force CUDA on unsupported hardware. Just accept the longer processing times and structure your workflow accordingly. Overnight batch runs are normal for CPU-only setups.

Where Stitchface falls short

It doesn't handle hairline blending well on its own. The current mesh-based approach creates visible seams along the hair boundary, especially when the target and source have different hair colors or textures. You'll need to use a secondary inpainting or feathering step after the main blend to clean up those edges. Some people in the community have patched this with additional Postern-like refinement passes, but it's not something the default build handles. There's also no built-in support for video. If you need frame-by-frame face replacement in a video, you're looking at extracting frames, running Stitchface on each one, and reassembling. That's a separate pipeline entirely and introduces synchronization issues that are annoying to debug. For video work, dedicated tools in that space might be more appropriate. The documentation is functional but sparse. The README covers the basics, but edge cases and advanced configuration options are scattered across GitHub issues. If you run into something that isn't documented, searching the issue tracker for similar problems usually surfaces a workaround that the maintainers have discussed but never formalized in the docs.