ComfyUI-VideoUpscaleHandFix

一个 ComfyUI 自定义节点，针对真人舞蹈视频手部不清晰的问题：先用 Real-ESRGAN 对每帧整体放大，再用 MediaPipe 检测手部、对手部区域做额外锐化与去噪，最后羽化融合回去。

确定性算法 + 单帧推理，不引入生成模型，保证视频时序连贯，不会出现帧间手指数量/朝向跳变的问题。

功能

• 5 个可选 SR 模型（含视频专用的轻量 SRVGGNetCompact，0.6M / 1.2M 参数）
• MediaPipe HandLandmarker 检测手部 bbox
• 手部区域 unsharp mask 锐化 + bilateralFilter 去噪
• 高斯羽化 alpha 融合，避免接缝
• 模型自动下载（带超时和进度日志）
• MPS / CUDA / CPU 自动选择，MPS 推理失败自动 fallback CPU
• 模型与 detector 模块级缓存，多帧复用

安装

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

依赖：opencv-python、mediapipe>=0.10、realesrgan、basicsr、gfpgan、facexlib、scipy。

torchvision 兼容性：节点会自动给 torchvision.transforms.functional_tensor 打 shim，无需手动处理新版 torchvision 移除该模块的问题。

首次运行会自动下载：

• ESRGAN 模型 → ComfyUI/models/upscale_models/
• MediaPipe 手部模型 → ComfyUI/models/mediapipe/

使用

工作流示例见 workflow_upscale_hand_fix.json。基本接线：

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

节点位于 ComfyUI 的 video 分类下。

参数说明

输入

| 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | images | IMAGE | — | 视频帧序列 (N, H, W, 3)，float32 [0,1] |

模型与放大

| 参数 | 类型 | 默认 | 范围 | 说明 | |---|---|---|---|---| | model | 下拉 | RealESRGAN_x2plus | 见下表 | 选择 SR 模型 | | scale_factor | INT | 2 | 1-4 | 输出放大倍数；1 直接 passthrough，跳过模型 | | tile_size | INT | 256 | 0-512（步进 64） | 分块大小；0 不分块（最快、最吃显存） |

5 个可选模型

| 名称 | 架构 | 参数量 | 适合 | |---|---|---|---| | RealESRGAN_x2plus | RRDB-23 | 16.7M | 通用 2x，质量稳定 | | RealESRGAN_x4plus | RRDB-23 | 16.7M | 通用 4x | | RealESRGAN_x4plus_anime_6B | RRDB-6 | 4.5M | 动漫，真人慎用 | | realesr-animevideov3 | SRVGG-16 | 0.62M | 视频专用，速度极快 | | realesr-general-x4v3 | SRVGG-32 | 1.21M | 真人视频首选 |

真人舞蹈推荐顺序：realesr-general-x4v3 > realesr-animevideov3 > RealESRGAN_x2plus

手部增强

| 参数 | 类型 | 默认 | 范围 | 说明 | |---|---|---|---|---| | hand_enhance | BOOL | True | — | 是否增强手部；不露手的视频建议关闭 | | hand_boost_strength | FLOAT | 0.5 | 0.0-2.0 | unsharp mask 锐化强度；超过 1.2 易出光晕 | | denoise_strength | FLOAT | 0.3 | 0.0-1.0 | bilateralFilter 去噪强度；与锐化对抗 | | hand_padding_ratio | FLOAT | 0.35 | 0.0-1.0 | 手部 bbox 外扩比例；切到指尖时调大 | | feather_ratio | FLOAT | 0.12 | 0.0-0.5 | 羽化融合宽度；看到接缝时调大 |

输出

| 参数 | 类型 | 说明 | |---|---|---| | images | IMAGE | 放大后的帧序列 |

调参速查

| 你想要 | 配置 | |---|---| | 最快预览 | model=realesr-animevideov3, scale=2, hand_enhance=False, tile=0 | | 质量优先（真人） | model=realesr-general-x4v3, scale=2, hand_enhance=True, boost=0.6, denoise=0.3, tile=256 | | 手部细节最大化 | model=realesr-general-x4v3, scale=2, hand_enhance=True, boost=0.8, denoise=0.2, tile=128 | | 运动模糊场景 | model=realesr-general-x4v3, scale=2, hand_enhance=True, boost=0.3, denoise=0.5 |

| 现象 | 调整 | |---|---| | 手指被裁掉 | hand_padding_ratio ↑ 到 0.5+ | | 增强溢出到衣服/脸 | hand_padding_ratio ↓ 到 0.2 | | 手部边缘有接缝 | feather_ratio ↑ 到 0.2 | | 增强效果太弱 | feather_ratio ↓ 到 0.05 | | 手部"塑料感" | hand_boost_strength ↓，denoise_strength ↑ | | 出现暗边光晕 | hand_boost_strength ↓ 到 0.5 以下 |

设计取舍

为什么不用生成式模型修手？

真人舞蹈手部运动幅度大、速度快，diffusion / inpainting 类模型难以保证帧间一致性 — 同一只手在前后帧可能生成不同的指节数量或朝向，整段视频会出现明显抖动。本节点选择确定性增强路线（SR 模型 + 算法后处理），输出可重现，时序天然稳定。

手部检测在原帧而非放大帧上做：MediaPipe 对小图也能检，省下放大帧的检测成本，bbox 再按比例 scale 到放大帧。

Real-ESRGAN 模型权重源自 xinntao/Real-ESRGAN 官方 release。

技术架构

原帧 (H,W,3, RGB) ─┬─> Real-ESRGAN ─> 放大帧 (sH,sW,3, BGR)
                   │
                   └─> MediaPipe ────> 手部 bbox 列表
                                              │
                                              ▼
                            crop -> unsharp -> bilateral
                                              │
                                              ▼
                                    高斯羽化 alpha blend
                                              │
                                              ▼
                                          最终帧

性能参考（Apple M4 / MPS）

| 配置 | 处理速度（576×320 输入 → 1152×640） | |---|---| | realesr-animevideov3 + tile=0 + hand_enhance=False | ~0.3s/帧 | | realesr-general-x4v3 + tile=256 + hand_enhance=True | ~1.5s/帧 | | RealESRGAN_x2plus + tile=256 + hand_enhance=True | ~3s/帧 |

License

代码使用 MIT。模型权重遵循 Real-ESRGAN 与 MediaPipe 各自的 license。