TBDub Preprocess (face crop preview)

What it's for

TBDub Generate takes a couple of minutes and can refuse your video for a dozen reasons. This node is the free pre-flight check: it runs the runtime's face preprocessing and nothing else.

No audio. No diffusion. No GPU, no DiT, no VAE - it's MediaPipe on the CPU, plus a bit of ffmpeg. What you get back is the actual thing the model will be fed: a video of the 512×512 face crops TBDub intends to dub. If the framing is wrong, if the box is drifting across the shot, if the crop is clipping a chin, you find out here instead of after a full job that also refuses because there are two people in one frame.

It's also the honest answer to "will this even work on my footage": TBDub needs one visible face, a face lost for more than 0.4 seconds is refused, and more than one face in a frame is refused unless you change the policy. Preprocess reports exactly which frames those are.

How it works

It runs the first four stages of the runtime's job pipeline - decode with ffmpeg, MediaPipe face detection and landmarking, interpolation of any missing detections, and the aligned 512×512 crop - then writes those crops out at 25 fps as a preview. Because nothing is cut to a speech length, the preview is the whole source, with no audio attached.

MediaPipe doing the detection is worth knowing about: it's the licence-clean, fast-on-CPU face backend the rest of the ecosystem reaches for when InsightFace's non-commercial models get in the way - Kijai's LivePortrait swap is the canonical example. It gives TBDub a landmark pass on the CPU while the GPU sits idle, with the tradeoff that swap has always had: fine on ordinary angles, and it doesn't chase faces the way ArcFace-based detection does.

Inputs and outputs

Required: runtime (wire a TBDub Runtime node), video, and face_mode - full_frame for MediaPipe detection plus crop, cropped if your input is already an aligned square face clip.

Optional: start_frame, multiple_faces (refuse by default, highest_score for upstream's most-confident-face behaviour) and fps_policy (resample_to_25 or refuse). Deliberately absent: seed and audio. Nothing here generates anything, so there's nothing to seed and nothing to drive.

Outputs: crop_preview, a VIDEO of the 512×512 crops at 25 fps - wire it to Save Video or Video Combine and watch it. report, a JSON string carrying faces (detected frames, interpolated frames, the count of frames with multiple faces and the first ten frame numbers where that happens, and the policy you set), plus source, fps, preview, patches, timings and upstream versions.

Set multiple_faces and fps_policy to the same values you'll use in Generate. Otherwise you're testing a configuration you're not going to run.

Install

ComfyUI Manager, search TBDub (publisher hiroki-abe-58), or:

cd ComfyUI/custom_nodes
git clone https://github.com/hiroki-abe-58/ComfyUI-TBDub

The node needs no packages in ComfyUI's environment. But "no GPU needed" does not mean "no runtime needed": this still launches the separate runtime process, so the venv, the pinned upstream checkout at 19e18e4, ffmpeg/ffprobe and a registered entry in ComfyUI/user/tbdub.runtimes.json all have to exist first. Build that per docs/SETUP.md, copy examples/tbdub.runtimes.example.json to ComfyUI/user/tbdub.runtimes.json, edit the paths, restart.

One thing a green preprocess does not buy you: in preprocess mode the runtime only checks config.json and face_landmarker.task. The Student DiT and the Wan VAE are never touched. So a clean preview means detection is fine, not that your 15 GB of weights are intact - TBDub Doctor with deep is the one that hashes those.

Where people get burned

"more than one face was detected in N frame(s)" - this is the same refusal Generate will give you, just minutes earlier and for free. Crop the shot or set multiple_faces to highest_score.

A drifting or jittery crop is MediaPipe doing its best on a hard shot: profile angles, heavy motion blur, a face half out of frame. The preview is where you see it. Since the crop is what actually gets dubbed, bad tracking here means a bad dub no matter what the sampler does - this node's preview is the honest early warning.

A few interpolated frames is normal, not a failure. MediaPipe misses a frame occasionally and the runtime fills the gap; the report says how many. A large count alongside visible drift means detection isn't locking on at all.

A non-25 fps source gets converted here too, using the same fps_policy you set. If you set refuse, preprocess stops on it - which is the point. Better here than three minutes into a Generate.

"(no runtime configured)" - the config file is missing or in the wrong place: the root of the ComfyUI user directory, or wherever COMFYUI_TBDUB_CONFIG points. Same failure as everywhere else in this pack.