modaux: face_detector

Trying to make ControlNet hold a face in a specific spot - portrait composition, a face that stays put while everything else changes - and discovering most preprocessors ignore faces entirely is a rite of passage. controlaux_face_detector (listed in your node menu as "modaux: face_detector") is the one that doesn't. It's part of the ControlNet Auxiliar pack, a small wrapper around Hugging Face's controlnet_aux library, and its entire job is to find up to a handful of faces and draw a map of where they are.

The output is exactly what it sounds like: a black image with white regions painted over each face, technically a MediaPipe face-mesh map. You feed that into a face ControlNet - the SD/SDXL-era controlnet_mediapipe_face checkpoints - and generation has to put a face there. It's the old-school way to control face placement and face angle, the ancestor of today's adapter-style identity tools, and it still works.

The name is a lie in the best way. "Detector" sounds like it's calling a service, but there's no API and no key. Everything runs locally through Google's MediaPipe, and this is the only node in the whole pack that skips the model download - every sibling pulls weights from lllyasviel/Annotators on Hugging Face the first time it runs, while the face detector's model is bundled inside the mediapipe pip package. First run, no internet, done.

How it works

MediaPipe's FaceMesh runs in static-image mode, finds up to max_faces faces, and renders a filled-in mesh map for each one. If it finds nothing, it prints "No faces detected in controlnet image" to your terminal and hands back a solid black image. That matters more than it sounds: a black map tells your ControlNet "no face here," and you'll sit there wondering why the condition went completely dead.

The inputs that matter

The first three are the ones you mostly leave alone:

• image - whatever you want faces found in.
• detect_resolution and image_resolution - both default 512 (range 256–1024). The first is the resolution the detector actually analyzes at; the second is the resolution the map is resized to before it's returned. 512 for both is a fine starting point.
• max_faces - default 1, max 5. Bump it for a group shot where you want every face mapped. Past 5 you're out of luck; the node caps there.
• min_confidence - default 0.5. If a face keeps getting missed, drop it toward 0.3; it gets more aggressive, and slightly more prone to false positives.

The single IMAGE output plugs straight into the "control image" (or conditioning image) input of your ControlNet node. Load a mediapipe-face checkpoint, apply it before the KSampler, and that's the whole loop.

Install

In ComfyUI Manager, search "ControlNet Auxiliar" and install - the pack is registered. Or by hand:

cd ComfyUI/custom_nodes
git clone https://github.com/madtunebk/ComfyUI-ControlnetAux.git
cd ComfyUI-ControlnetAux
pip install -r requirements.txt   # timm, controlnet-aux==0.0.7, mediapipe

Then restart ComfyUI.

Where people get burned

mediapipe is unpinned in the requirements, and on some Python versions it won't install cleanly - the classic fix is a fresh venv and pip install mediapipe on its own before installing the pack. Two honest caveats on top of that: this pack is effectively dormant (last commit mid-2024) and pins the old controlnet-aux==0.0.7, so if a dependency moves, you may be pinning things yourself. And before you commit a workflow to it, know that the actively-maintained "ControlNet Auxiliary Preprocessors" pack by Fannovel16 ships the same MediaPipe face functionality with more options. This node is the lightweight version - perfect when you just need one face map, not the last word on the subject.