基于 comfyui-vrgamedevgirl 的 VRGDG MiniMax H3 Audio Drive（作者 VRGameDevGirl），感谢原作者。/ Based on VRGDG MiniMax H3 Audio Drive from comfyui-vrgamedevgirl by VRGameDevGirl. Thanks to the original author.

输入 / Inputs: av_latent (LATENT), source_audio (AUDIO), audio_vae (VAE)
输出 / Outputs: audio_driven_av_latent (LATENT), original_audio (AUDIO)

Swan Audio Info

读取官方 Load Audio 节点输出，返回音频相关信息。/ Reads the official Load Audio node output and reports audio details.

输入 / Inputs: audio (AUDIO), fps (INT, 默认 24 / default 24)
输出 / Outputs: info (STRING), duration_s (FLOAT, 秒 / seconds), sample_rate (INT, 单位 Hz), num_frames (INT, 由 duration × fps 得出 / derived from duration × fps)

Swan Load H3 Latent Upscaler Model

加载 MiniMax H3 学习式 latent 上采样权重（models/latent_upscale_models/），输出 H3_LATENT_UPSCALER Provider 句柄。该句柄既可接本包的 Transition Lift 节点，也兼容 MiniMax-H3-Flow-Aligned-Regenerate 的 learned_upscaler 输入。/ Loads a learned H3 latent-upscaler checkpoint and outputs an H3_LATENT_UPSCALER provider handle, compatible with both the Swan transition lift and the learned_upscaler input of MiniMax-H3-Flow-Aligned-Regenerate.

输入 / Inputs: model_name (COMBO), device (cuda/cpu), precision (fp16/fp32/bf16), offload_after_upscale (BOOLEAN)
输出 / Outputs: learned_upscaler (H3_LATENT_UPSCALER)

Swan Sigmas Split: Low Runs to Zero

把一条 sigma 日程拆成两段，用于"低清采样 → 提升 → 高清采样"的两段式渐进工作流：低清段以补零收尾（完全去噪，得到干净 x0），高清尾段从拆分点 sigma 继续。总评估次数 N+1。/ Splits one sigma schedule for a two-stage progressive workflow: the low-res stage ends at zero (fully denoised, handing a clean x0 to the lift), and the high tail resumes from the split sigma. Total NFE becomes N + 1.

输入 / Inputs: sigmas (SIGMAS), low_steps (INT)
输出 / Outputs: low_sigmas (SIGMAS), high_sigmas (SIGMAS)

Swan SelfLift Transition Lift (H3)

两段式采样之间的 SelfLift-zero 过渡修复节点：对低清干净端点做双路提升——直接 latent 提升（可接学习式上采样，否则 nearest/bilinear 插值）+ VAE 像素重编码锚——以两者残差为伪影风险图，把 top-rho 高风险位置向像素锚修正（arXiv:2609.02036）。rho=0 时跳过像素路线，仅做直接提升。只提升视频流，音频流原样直通。输出干净的目标尺寸 latent，重加噪由下游 SamplerCustom 的 add_noise 完成。/ SelfLift-zero transition between two samplers: paired direct lift (learned upscaler or interpolation) plus a VAE decode→upscale→re-encode pixel anchor; the residual becomes an artifact-risk map and the top-rho risky locations are corrected toward the anchor. rho=0 keeps the direct lift only. Video stream is lifted, audio passes through untouched. Re-noising happens in the next SamplerCustom via add_noise.

输入 / Inputs: lowres_latent (LATENT), target_scale (FLOAT), direct_lift (learned/nearest/bilinear), rho (FLOAT), w_min / w_max (FLOAT), keep_audio (BOOLEAN), 可选 / optional: highres_latent (LATENT), vae (VAE), upscaler (H3_LATENT_UPSCALER)
输出 / Outputs: highres_latent (LATENT)

keep_audio：开启后自动注入遮罩（视频=生成、音频=保留），让高清段原样沿用低清段的音频，避免音频被二次去噪重生（数字人 / 音频驱动工作流建议开启）。/ Injects a mask (video = generate, audio = preserve) so the high-res stage keeps the low-res audio instead of regenerating it — recommended for digital-human / audio-driven workflows.

noise_mask 透传：低清段 latent 上的遮罩会带到输出——视频遮罩自动缩放到高清网格，音频遮罩原样直通；支持嵌套双流、核心打包 [B,1,N] 与普通视频形遮罩。/ Inpaint masks are carried across: the video mask is rescaled to the target grid and audio masks pass through untouched.

参考接法 / Reference wiring:

SamplerCustom (低清 / low-res, low_sigmas, add_noise=True)
  → Swan SelfLift Transition Lift → SamplerCustom (高清 / high-res, high_sigmas, add_noise=True)

Swan Resize H3 Keyframes (Conditioning)

把 CONDITIONING 里 H3 的关键帧 / 参考 latent 缩放到低清段的 latent 网格。上游 SelfLift 在节点内部自动做这件事，拆成两个采样器后需要显式处理，否则低清段会拿到目标分辨率的参考图。/ Rescales H3 keyframe / reference latents inside CONDITIONING to the low-res stage grid. Upstream SelfLift does this internally; with two separate samplers it must be done explicitly.

输入 / Inputs: conditioning (CONDITIONING), scale (FLOAT), 可选 / optional: reference_latent (LATENT)
输出 / Outputs: conditioning (CONDITIONING)

接 reference_latent（低清段的 Empty H3 AV Latent）时按它的网格精确对齐；不接则用 scale 缩放。无关键帧的 conditioning 原样直通。/ Connect the low-res Empty H3 AV Latent as reference_latent for an exact grid match, otherwise use scale. Conditioning without keyframes passes through unchanged.

Swan H3 Tiled Model (High Stage)

高段分块采样：把每次模型评估沿较长的 2×2-patch 轴切开，逐块前向（每块都带上完整音频流与音频条件），再用归一化重叠窗把各块融合回完整网格。只接高清段的采样器，低清段继续用未包装的 MODEL。分块本身是 MODEL 补丁（DIFFUSION_MODEL + PREPARE_SAMPLING 两个钩子），因此不限制采样器。/ Spatial tiling for the high-res stage: each model evaluation is split along the longer 2x2-patch axis, every tile is evaluated with the complete audio stream and audio conditioning, and the tiles are fused back with a normalized overlap window. Wire it in front of the high-res sampler only. It works through two ModelPatcher hooks, so any sampler can be used.

输入 / Inputs: model (MODEL), stage_latent (LATENT，高清段采样用的那个 latent), tiles (INT，0=自动 / auto，1=关闭 / off，2-8=强制), enable_tiling (BOOLEAN)
输出 / Outputs: model (MODEL)

参考接法 / Reference wiring:

Empty H3 AV Latent (低清) → SamplerCustom (低清, low_sigmas, 用原始 MODEL)
  → Swan SelfLift Transition Lift → 干净的目标尺寸 latent
      ├─→ Swan H3 Tiled Model (High Stage).stage_latent
      │     └─→ SamplerCustom (高清, high_sigmas).model
      └─→ SamplerCustom (高清, high_sigmas).latent_image     ← 同一个 latent 分两路

遮罩限制：分块只支持「视频遮罩全 1、音频遮罩全 0」这一种组合（即上面 keep_audio 产出的形态）；局部/软视频遮罩、局部音频遮罩、ControlNet 会被明确拒绝。所以数字人场景要「分块 + 保音频」时请打开 keep_audio。/ Tiling accepts only the video=1-everywhere / audio=0-everywhere combination (what keep_audio produces). Partial or soft video masks, partial audio masks and ControlNet are rejected with a clear error.

显存预算：tiles=0 时按可用工作区自动挑 1–8 块；但本机 ComfyUI 的 MIN_WEIGHT_MEMORY_RATIO 为 0，估计偏乐观，显存吃紧时建议直接指定 tiles。日志里会打印 [Swan_Bits tiling plan] / [Swan_Bits tiling memory] 供核对。/ With tiles=0 the tile count is picked automatically from the estimated workspace, but this ComfyUI reports MIN_WEIGHT_MEMORY_RATIO = 0.0, which makes that estimate optimistic — set tiles explicitly when VRAM is tight.

鸣谢 / Acknowledgements

SelfLift: Accelerating Few-Step Diffusion via Self-Recovering Resolution Transition —— SelfLift-zero 过渡算法来源；ComfyUI 实现参考 facok/comfyui-SelfLift，感谢原作者。/ Source of the SelfLift-zero transition algorithm; ComfyUI implementation reference.
LBH-123-AI/Comfyui_Minimax_h3_latent_Upscaler —— H3 学习式上采样权重与网络架构来源，本包内的模型加载代码移植自该项目（自包含、无运行时依赖），感谢原作者。/ Source of the H3 learned upscaler weights and network architecture; the model-loading code in this package is a self-contained port of that project (no runtime dependency). Thanks to the original author.

来源与许可 / Source and licensing

本包的 h3_tiling.py（高段分块采样）移植自 slmonker/selflift-Avatar v0.1.2-experimental 的 h3_tiling.py；而该文件本身是 facok/comfyui-SelfLift 同名文件的快照，外加一段遮罩兼容判定。上游文档保存在 docs/upstream/，源文件哈希与本地改动记录在 PROVENANCE.json。/ The h3_tiling.py in this package (high-res tiling) is ported from h3_tiling.py in slmonker/selflift-Avatar v0.1.2-experimental, which is itself a snapshot of the same file in facok/comfyui-SelfLift plus a mask-compatibility guard. Upstream documentation is preserved under docs/upstream/, and source hashes and local changes are recorded in PROVENANCE.json.

准备本包时，上游仓库未声明许可证。本仓库不代表上游作者附加任何许可证，也不意味着获得超出适用权利之外再分发上游代码或模型权重的许可。研究论文、第三方代码与模型权重由各自的作者负责。/ The upstream repositories did not declare a license at the time this package was prepared. This repository does not add a license on behalf of the upstream authors and does not imply permission to redistribute upstream code or model weights beyond the applicable rights. Research papers, third-party code, and model checkpoints remain the responsibility of their respective authors.

安装 / Install

把本文件夹复制到 ComfyUI/custom_nodes/ 并重启 ComfyUI。/ Copy this folder into ComfyUI/custom_nodes/ and restart ComfyUI.