Video Upscale Hand Fix

You know the shot: the generated dancer looks great, then you upscale the video to 1080p and her hands turn into blurry gloves. Hands were already the weakest part of AI video, and upscaling makes it worse - the model just invents mush where it has no real detail. This node is a narrow, honest fix for exactly that: upscale the whole frame with Real-ESRGAN, then use MediaPipe to find the hands and sharpen only them before blending back.

What makes it interesting is what it refuses to do. It's deterministic - no diffusion, no inpainting, no generation at any step. Per-frame generative fixes are the trap here, because a diffusion pass on frame 40 doesn't know what it did to frame 39, and you get fingers that change count or orientation between frames. This node's whole pitch is that the output is reproducible and temporally stable, because nothing in the pipeline is allowed to invent anything. For a dancing subject with fast, overlapping hands, that's the right trade: sharper, not rewritten.

The per-frame mechanism, from the source, is straightforward:

• Real-ESRGAN upscales the frame to scale_factor×, split into tile_size tiles to keep VRAM sane.
• MediaPipe HandLandmarker runs on the original frame, not the upscaled one - hands are cheap to find small, and the bounding box gets scaled up to match. Saves you a full upscale's worth of detection.
• Each hand crop gets a 2× supersample, unsharp-style sharpen, and a bilateral filter for denoise.
• A Gaussian-feathered alpha blend pastes the enhanced crop back so there's no visible seam.

Models get cached at module level and auto-download on first run, and there's a torchvision shim baked in so newer torchvision versions (which removed functional_tensor) don't crash the realesrgan import. Nice touch for a one-node pack.

The inputs you'll actually touch:

• model - the default RealESRGAN_x2plus is the safe generalist, but for real-person video the author recommends realesr-general-x4v3, a 1.2M-param video model that's fast and sharp. realesr-animevideov3 is the speed king for previews; steer clear of RealESRGAN_x4plus_anime_6B for real faces.
• scale_factor - 1 to 4. Set it to 1 and the node skips ESRGAN entirely and just runs the hand pass, which is handy for testing the enhancement alone.
• hand_boost_strength - the sharpen amount, default 0.5. Past about 1.2 you start getting halos.
• tile_size - 0 means no tiling: fastest, hungriest. 256 is a sensible default.

The one output, images, is an IMAGE tensor that plugs straight into VHS_VideoCombine. Basic wiring, straight from the pack's workflow:

VHS_LoadVideo ──IMAGE──> VideoUpscaleHandFix ──IMAGE──> VHS_VideoCombine

Install

Via ComfyUI Manager (search "ComfyUI-VideoUpscaleHandFix") or:

cd ComfyUI/custom_nodes
git clone https://github.com/liaowu-boos/ComfyUI-VideoUpscaleHandFix.git
cd ComfyUI-VideoUpscaleHandFix
pip install -r requirements.txt

The dependency list is the heavy part: realesrgan, basicsr, gfpgan, facexlib, plus mediapipe>=0.10 and opencv-python. That's a realesrgan stack that pulls its own torchvision expectations - which is exactly why the shim exists. First run downloads the SR weights into ComfyUI/models/upscale_models/ and the MediaPipe hand_landmarker.task into ComfyUI/models/mediapipe/, with progress logs, so don't panic if the first queue looks like it's stalling.

Troubleshooting

• First run is slow and chatty - it's downloading two models. Watch the console for the progress lines.
• On Apple Silicon it picks MPS, and falls back to CPU automatically if MPS chokes - slower but it won't crash. The README quotes ~0.3s/frame for the light config on an M4.
• Fingers getting clipped → bump hand_padding_ratio toward 0.5. Enhancement bleeding onto clothes/face → drop it to ~0.2.
• A visible seam around the hand → raise feather_ratio to 0.2. Hands looking plastic → lower hand_boost_strength, raise denoise_strength.
• No hands in frame → just turn hand_enhance off and it becomes a plain deterministic ESRGAN video upscaler.

It's a one-trick node, and the trick is genuinely useful for the people it targets. If you're restoring an actual damaged video you'd reach for something generative instead - but for "my good dance render got mushy hands on upscale," this is the closest thing to a set-and-forget answer. Keep realesr-general-x4v3, scale 2, boost 0.6, and it just works.