ComfyUI-H3-Context-Noise

ComfyUI-H3-Context-Noise

English | 中文

为 MiniMax H3 Motion Context 提供手动上下文加噪节点的 ComfyUI 扩展，用于角色替换（character-swap）续帧链路中消除上一镜的色彩残留。

---

这个扩展是做什么的

H3 续帧时会把上一镜的末尾帧作为上下文带入下一镜。上下文太干净会带来一个问题：模型几乎原样复制上一镜的纹理与颜色，在 trim 边界之后立刻显出明显的色彩残留。

解决办法就是给上下文"加噪"：把被携带的帧做成色彩损毁但运动可读的版本，模型无法照抄上一镜的外观，只能从身份参考重新合成——接缝处的残留自然就消失了。

加噪采用**锥形（taper）**策略：窗口内维持一个平坦的注入强度 alpha，在靠近接缝的最后几帧线性降到 alpha_end。强度太恒定会在接缝处留残影，降得太狠又会丢失锐度收益，这是一个经过实际验证的经验配方。

已校验配方（22 / 0.45 / 0.10 / 3）

| 帧（0=最旧） | 0..18 | 19 | 20 | 21（接缝）| |---|---|---|---|---| | alpha | 0.45 | 0.333 | 0.217 | 0.100 |

---

节点

安装后 conditioning/minimax 分类下会出现两个节点，分别对应 H3 Motion Context 接收上下文的两条路径：

| 节点 | 类型 | 作用 | |---|---|---| | H3 Context Taper Noise (latent)<br>MiniMaxH3ContextLatentTaperNoise | LATENT → LATENT | 在 context_latent 路径上，对上一镜 AV latent 尾部的潜变量步注入高斯噪声，音频流保持原样不动。 | | H3 Context Taper Noise (frames)<br>MiniMaxH3ContextTaperNoise | IMAGE → IMAGE | 在 context_frames 路径上，对上一镜解码帧尾部注入 6 色调色板块状噪声（像素级）。 |

两个节点都带第二个输出 alpha_schedule（STRING），打印实际注入强度序列，方便核对（末尾通常恰好是 alpha_end）。

---

如何连接

下图是一个工作流中的实际接法（以Ref多参考中实际使用的续帧工作流为例）：

核心思路是把加噪节点插在上一镜输出与 H3 Motion Context 之间：

| 链路 | 起点 | 终点 | |---|---|---| | A | #204 GetVideoComponents → images | #314 H3 Context Taper Noise (frames) → images | | B | #314 → images | #206 H3 Motion Context → context_frames | | C | #207 H3 Motion Context Load Latent → LATENT | #312 H3 Context Taper Noise (latent) → context_latent | | D | #312 → context_latent | #206 → context_latent |

接的时候记住一点：

context_latent 一旦接入，H3 Motion Context 会完全忽略 context_frames。

所以当你走 latent 链路（C→D）时，frames 链路（A→B）接不接都不影响结果；只有断开 latent 链路后，frames 节点才会真正接管。两条路径都可以独立使用，按你的工作流走哪条算哪条。

参数建议：加噪节点的 tail_frames 设成与 H3 Motion Context 的 context_length 一致（示例中两者都是 22），保证被钉住的上下文帧全部经过加噪处理。

---

安装

1. 克隆仓库到 ComfyUI 的 custom_nodes 目录：

   cd <ComfyUI>/custom_nodes
   git clone https://github.com/<your-name>/ComfyUI-H3-Context-Noise.git
   

   或者在 ComfyUI Manager 里搜索安装。

2. 重启 ComfyUI，节点即出现在 conditioning/minimax 分类下。

3. 打开你的工作流，把加噪节点插进 context_latent 或 context_frames 链路（见上文"如何连接"）。

无需额外安装任何 Python 依赖——只用 ComfyUI 自带的 torch 与 Pillow。

---

参数

MiniMaxH3ContextTaperNoise（frames 节点）

| 参数 | 默认 | 说明 | |---|---|---| | tail_frames | 22 | 从片段末尾起注入多少帧。需 ≥ H3 Motion Context 的 context_length，否则部分被钉住的帧仍是干净的。 | | alpha | 0.45 | 窗口内平坦注入强度。 | | alpha_end | 0.10 | 最末帧（接缝处）强度，必须 ≤ alpha。 | | ramp_frames | 3 | 末尾多少帧从 alpha 降到 alpha_end。 | | seed | 0 | 噪声种子；整段共享一条随机流，可复现。 | | pattern | poc_chroma_blocks | 噪声图案：poc_chroma_blocks（已校验的 6 色调色板）/ gaussian_rgb / uniform_rgb（实验用）。 | | grid_mode | poc_36x64 | 噪声网格：poc_36x64 在 576×1024 下正好是 16×16 像素块；block_size 让块尺寸在任何分辨率下恒定。 | | block_size | 16 | block_size 模式下的像素块边长。 |

MiniMaxH3ContextLatentTaperNoise（latent 节点）

| 参数 | 默认 | 说明 | |---|---|---| | context_latent | — | 上一镜的 AV latent，直接来自 H3 Motion Context Load Latent。 | | tail_frames | "22" | 注入的像素帧数，会换算成潜变量步。只有 5 / 22 / 39 / 56 是整步数（→ 2 / 7 / 12 / 17 步）。建议与 H3 Motion Context 的 context_length 保持一致。 | | alpha | 0.45 | 窗口内平坦注入强度。 | | alpha_end | 0.10 | 最末帧强度，必须 ≤ alpha。 | | ramp_steps | 2 | 末尾降噪的潜变量步数（一步约等于 4 像素帧，2 步约等于像素配方里的 3 帧斜坡）。 | | seed | 0 | 高斯噪声种子。 | | noise_scale | match_latent_std | match_latent_std 让高斯按被携带窗口自身的标准差缩放，alpha 的含义与 latent 尺度无关；unit 使用原始 N(0,1)。 |

---

测试

"<ComfyUI>\python\python.exe" -m unittest discover -s tests -v

测试覆盖：配方数值与参考脚本一致、锥形单调性、潜变量步换算、噪声场与 PIL 参考实现 bit 级一致、像素/潜变量节点行为（仅尾部被改、接缝处损毁最轻、确定性、音频不动、容器类型保持）。

---

与上游研究的关系

• 加噪配方（22 / 0.45 / 0.10 / 3 锥形、6 色调色板块状噪声）来自 MacroSony 的 minimax-h3-chained-character-swap（scripts/inject_tail_taper.py）， 本扩展是该配方在 ComfyUI 图内的直接实现，免去了离线 mp4 往返。
• 节点对接的是 NikoDemon80/ComfyUI-H3-Motion-Context 的上下文接口（context_latent 的 AV 嵌套约定、context_frames 帧采样约定、H3 VAE 时序）， 也参考了 MacroSony/pi-comfyui-paint 的多 clip 续帧工作流骨架。

---

注意事项

• 一次性：加噪输出是一次性的，不要把加噪后的结果再喂回下一环的上下文。
• 只接受 AV 嵌套 latent：latent 节点只接受 H3 的 video+audio 嵌套对，普通单流 latent 会被明确拒绝——请接 H3 Motion Context Load Latent 的输出。
• 窗口对齐：如果提示「the N step tail starts at cycle position … not 0」，说明片段长度与 tail_frames 不对齐，H3 会拒收窗口——调整片段长度或 tail_frames 即可，不要忽略告警。

---

许可

MIT。加噪配方算法的版权归属 MacroSony（见 inject_tail_taper.py）。