Unify V3.3 public node surface

This commit is contained in:
ukr8b3g-cmyk
2026-08-16 21:08:13 +09:00
parent 3fe9ada6af
commit 161e17bddf
9 changed files with 43 additions and 355 deletions
+17 -3
View File
@@ -9,7 +9,7 @@ Native long-form MiniMax H3 video and audio continuation for ComfyUI.
https://github.com/user-attachments/assets/bfa8c683-fc9d-48f1-9cdb-477ca110cdf2 https://github.com/user-attachments/assets/bfa8c683-fc9d-48f1-9cdb-477ca110cdf2
**H3 Continuum Sampler V3.3** generates 1 to 16 linked H3 chunks, carries raw video/audio latent context between chunks, supports T2VA, I2VA, FL2VA and multi-image Reference conditioning, and can resume completed chunks from disk. **H3 Continuum Sampler V3.3** generates 1 to 16 linked H3 chunks, carries raw video/audio latent context between chunks, supports T2VA, I2VA, FL2VA, multi-image Reference conditioning, and optional Timeline Video, and can resume completed chunks from disk.
V3 delegates video and audio decoding to normal **ComfyUI Core VAE Decode nodes**. No model weights or third-party accelerator code are bundled. V3 delegates video and audio decoding to normal **ComfyUI Core VAE Decode nodes**. No model weights or third-party accelerator code are bundled.
@@ -62,6 +62,20 @@ For ZIP installation, extract the repository as `ComfyUI-H3-Continuum` under `Co
Use an up-to-date ComfyUI. ComfyUI v0.32.0 or later is recommended for the current MiniMax H3 Core VAE fixes and memory improvements. Use an up-to-date ComfyUI. ComfyUI v0.32.0 or later is recommended for the current MiniMax H3 Core VAE fixes and memory improvements.
## Current and legacy nodes
V3.3 uses two current workflow nodes:
- **H3 Continuum Sampler V3.3** - unified sampler for normal generation and optional Timeline Video conditioning.
- **H3 Continuum Assemble + Seam** - Core-decoded chunk assembly with Audio Seam and guarded Video Seam correction.
The V3.2.4 nodes remain registered only so existing saved workflows continue to load:
- **[Legacy] H3 Continuum Sampler V3.2.4**
- **[Legacy] H3 Continuum Assemble V3.2.4**
New workflows should use the two V3.3 nodes. The legacy Node IDs are preserved, but they do not receive the integrated Timeline Video and current seam workflow surface.
No additional Python package is required beyond a working ComfyUI MiniMax H3 environment. No additional Python package is required beyond a working ComfyUI MiniMax H3 environment.
## Standard connection ## Standard connection
@@ -131,7 +145,7 @@ Both modes avoid stretching and use crop-free Reference preprocessing.
3. Set `Prompt Format = Auto`. 3. Set `Prompt Format = Auto`.
4. Start with `chunks = 3`, `chunk_seconds = 5.0`, and `Balanced - 22 frames`. 4. Start with `chunks = 3`, `chunk_seconds = 5.0`, and `Balanced - 22 frames`.
5. Connect the raw latent outputs to Core VAE Decode and Core VAE Decode Audio. 5. Connect the raw latent outputs to Core VAE Decode and Core VAE Decode Audio.
6. Connect decoded outputs and `assembly_plan` to **H3 Continuum Assemble V3**. 6. Connect decoded outputs and `assembly_plan` to **H3 Continuum Assemble + Seam**.
7. Connect Assemble images/audio to Create Video. 7. Connect Assemble images/audio to Create Video.
Recommended safe defaults: Recommended safe defaults:
@@ -334,7 +348,7 @@ Turbo LoRA files are available from [LightX2V MiniMax H3 Turbo](https://huggingf
## Timeline Video ## Timeline Video
`H3 Continuum Timeline Video` adds an optional `VIDEO` source to the existing continuation pipeline. The source is sliced per 5-second chunk, resized independently from the output, encoded only for chunks that must be generated, and released after use. `H3 Continuum Sampler V3.3` includes an optional `timeline_video` input. When connected, the source is sliced per 5-second chunk, resized independently from the output, encoded only for chunks that must be generated, and released after use. When it is not connected, the same node operates as the normal Continuum sampler.
- `Efficient - 0.4 MP` is the default and recommended starting point. - `Efficient - 0.4 MP` is the default and recommended starting point.
- `Match Output` preserves more source detail but can be substantially slower and heavier. - `Match Output` preserves more source detail but can be substantially slower and heavier.
-3
View File
@@ -377,11 +377,8 @@ NODE_DISPLAY_NAME_MAPPINGS.update(V3_NODE_DISPLAY_NAME_MAPPINGS)
# every older identifier registered so saved workflows still load, while # every older identifier registered so saved workflows still load, while
# ComfyUI's native deprecated-node filter hides legacy building blocks. # ComfyUI's native deprecated-node filter hides legacy building blocks.
_primary_node_ids = { _primary_node_ids = {
"H3ContinuumSamplerProduction",
"H3ContinuumSamplerTimelineVideo", "H3ContinuumSamplerTimelineVideo",
"H3ContinuumAssembleV3",
"H3ContinuumAssembleSeamExperimental", "H3ContinuumAssembleSeamExperimental",
"H3ContinuumSeamTestSource",
"H3ContinuumClipOverrides", "H3ContinuumClipOverrides",
"H3ContinuumResult", "H3ContinuumResult",
} }
+16 -7
View File
@@ -73,13 +73,22 @@ def _source(size_mode=TIMELINE_VIDEO_SIZE_MATCH_OUTPUT):
return video, source return video, source
def test_timeline_node_is_separate_and_stable_schema_is_unchanged(): def test_v33_unifies_optional_timeline_video_and_keeps_v324_schema():
stable = H3ContinuumSamplerProduction.INPUT_TYPES() legacy = H3ContinuumSamplerProduction.INPUT_TYPES()
experimental = H3ContinuumSamplerTimelineVideo.INPUT_TYPES() unified = H3ContinuumSamplerTimelineVideo.INPUT_TYPES()
assert "timeline_video" not in stable["required"] assert "timeline_video" not in legacy["required"]
assert "timeline_video_size" not in stable["required"] assert "timeline_video_size" not in legacy["required"]
assert "timeline_video" not in experimental["required"] assert "timeline_video" not in unified["required"]
assert experimental["optional"]["timeline_video"][0] == "VIDEO" assert unified["optional"]["timeline_video"][0] == "VIDEO"
from ComfyUI_H3_Continuum_Join import nodes as root_nodes
assert root_nodes.NODE_DISPLAY_NAME_MAPPINGS["H3ContinuumSamplerTimelineVideo"] == (
"H3 Continuum Sampler V3.3"
)
assert root_nodes.NODE_DISPLAY_NAME_MAPPINGS["H3ContinuumSamplerProduction"] == (
"[Legacy] H3 Continuum Sampler V3.2.4"
)
def test_timeline_node_without_video_delegates_to_stable_engine(monkeypatch): def test_timeline_node_without_video_delegates_to_stable_engine(monkeypatch):
-96
View File
@@ -1,96 +0,0 @@
import torch
from ComfyUI_H3_Continuum_Join.constants import DIAGNOSTICS_OPTIONS
from ComfyUI_H3_Continuum_Join.v3.assembly import (
H3ContinuumAssembleSeamExperimental,
VIDEO_SEAM_ANALYZE,
VIDEO_SEAM_AUTO,
VIDEO_SEAM_AUTO_2,
)
from ComfyUI_H3_Continuum_Join.v3.nodes import NODE_CLASS_MAPPINGS
from ComfyUI_H3_Continuum_Join.v3.seam_test_source import (
H3ContinuumSeamTestSource,
TEST_SIZE_256,
)
from ComfyUI_H3_Continuum_Join.v3.video_seam import analyze_decoded_boundaries
def _source_outputs():
image = torch.full((1, 256, 256, 3), 0.5, dtype=torch.float32)
return H3ContinuumSeamTestSource().create(
image,
exposure_change=0.08,
test_resolution=TEST_SIZE_256,
)
def test_seam_test_source_is_registered():
assert NODE_CLASS_MAPPINGS["H3ContinuumSeamTestSource"] is H3ContinuumSeamTestSource
def test_seam_test_source_is_public_in_root_registration():
from ComfyUI_H3_Continuum_Join import nodes as root_nodes
node_class = root_nodes.NODE_CLASS_MAPPINGS["H3ContinuumSeamTestSource"]
assert not getattr(node_class, "DEPRECATED", False)
assert node_class.CATEGORY == "MiniMax H3/Continuum/Testing"
assert root_nodes.NODE_DISPLAY_NAME_MAPPINGS["H3ContinuumSeamTestSource"] == (
"H3 Continuum Seam Test Source (Experimental)"
)
def test_seam_test_source_emits_realistic_three_chunk_contract():
images, audio, plan, instructions = _source_outputs()
assert [tuple(item.shape) for item in images] == [
(124, 256, 256, 3),
(141, 256, 256, 3),
(141, 256, 256, 3),
]
assert len(audio) == 3
assert plan["target_frames"] == 360
assert [item["trim_frames"] for item in plan["chunks"]] == [0, 22, 22]
assert "Analyze Only" in instructions
assert "Auto 2" in instructions
def test_controlled_boundaries_are_classified_as_exposure_ramps():
images, _audio, plan, _instructions = _source_outputs()
analyses = analyze_decoded_boundaries(images=images, assembly_plan=plan)
assert len(analyses) == 2
assert all(item.exposure_ramp_candidate for item in analyses)
assert [item.classification for item in analyses] == [
"exposure_ramp",
"exposure_ramp",
]
def test_auto_two_corrects_only_the_controlled_ramp_frames():
images, audio, plan, _instructions = _source_outputs()
node = H3ContinuumAssembleSeamExperimental()
common = {
"images": images,
"audio": audio,
"assembly_plan": [plan],
"exact_total_duration": [False],
"audio_seam": ["Off"],
"diagnostics": [DIAGNOSTICS_OPTIONS[0]],
}
analyzed_images, _analyzed_audio, analyzed_report = node.assemble(
video_seam=[VIDEO_SEAM_ANALYZE],
**common,
)
auto_images, _auto_audio, auto_report = node.assemble(
video_seam=[VIDEO_SEAM_AUTO],
**common,
)
auto_two_images, _auto_two_audio, auto_two_report = node.assemble(
video_seam=[VIDEO_SEAM_AUTO_2],
**common,
)
assert torch.equal(auto_images, analyzed_images)
assert "class=exposure_ramp" in analyzed_report
assert "action=kept native boundary" in auto_report
assert not torch.equal(auto_two_images, analyzed_images)
assert auto_two_report.count(
"normalized exposure/color on 4 exposure ramp boundary frame(s)"
) == 2
+3
View File
@@ -354,3 +354,6 @@ def test_experimental_seam_analyzer_is_public_in_root_registration():
assert root_nodes.NODE_DISPLAY_NAME_MAPPINGS["H3ContinuumAssembleSeamExperimental"] == ( assert root_nodes.NODE_DISPLAY_NAME_MAPPINGS["H3ContinuumAssembleSeamExperimental"] == (
"H3 Continuum Assemble + Seam" "H3 Continuum Assemble + Seam"
) )
assert root_nodes.NODE_DISPLAY_NAME_MAPPINGS["H3ContinuumAssembleV3"] == (
"[Legacy] H3 Continuum Assemble V3.2.4"
)
-1
View File
@@ -86,7 +86,6 @@ def main() -> int:
"H3ContinuumAdvancedV3", "H3ContinuumAdvancedV3",
"H3ContinuumAssembleV3", "H3ContinuumAssembleV3",
"H3ContinuumAssembleSeamExperimental", "H3ContinuumAssembleSeamExperimental",
"H3ContinuumSeamTestSource",
} }
actual = set(module.NODE_CLASS_MAPPINGS) actual = set(module.NODE_CLASS_MAPPINGS)
if actual != expected: if actual != expected:
+2
View File
@@ -288,6 +288,8 @@ def assemble_decoded_chunks(*args, **kwargs):
class H3ContinuumAssembleSeamExperimental(H3ContinuumAssembleV3): class H3ContinuumAssembleSeamExperimental(H3ContinuumAssembleV3):
DEPRECATED = False
CATEGORY = "MiniMax H3/Continuum"
DESCRIPTION = ( DESCRIPTION = (
"Analyze decoded chunk boundaries and apply guarded video seam correction." "Analyze decoded chunk boundaries and apply guarded video seam correction."
) )
+5 -9
View File
@@ -692,9 +692,10 @@ class H3ContinuumSamplerProduction(H3ContinuumSamplerV3):
class H3ContinuumSamplerTimelineVideo(H3ContinuumSamplerProduction): class H3ContinuumSamplerTimelineVideo(H3ContinuumSamplerProduction):
"""Chunk-local Timeline Video facade over the stable engine.""" """V3.3 sampler with optional chunk-local Timeline Video conditioning."""
DEPRECATED = False DEPRECATED = False
CATEGORY = CATEGORY
DESCRIPTION = ( DESCRIPTION = (
"Timeline Video sampler. It slices one Core VIDEO per chunk, " "Timeline Video sampler. It slices one Core VIDEO per chunk, "
"resizes only that slice, and reuses the stable Continuum sampling engine." "resizes only that slice, and reuses the stable Continuum sampling engine."
@@ -760,9 +761,6 @@ class H3ContinuumSamplerTimelineVideo(H3ContinuumSamplerProduction):
return super().run(timeline_video_source=source, **kwargs) return super().run(timeline_video_source=source, **kwargs)
from .seam_test_source import H3ContinuumSeamTestSource
NODE_CLASS_MAPPINGS = { NODE_CLASS_MAPPINGS = {
"H3ContinuumSamplerProduction": H3ContinuumSamplerProduction, "H3ContinuumSamplerProduction": H3ContinuumSamplerProduction,
"H3ContinuumSamplerTimelineVideo": H3ContinuumSamplerTimelineVideo, "H3ContinuumSamplerTimelineVideo": H3ContinuumSamplerTimelineVideo,
@@ -770,15 +768,13 @@ NODE_CLASS_MAPPINGS = {
"H3ContinuumAdvancedV3": H3ContinuumAdvancedV3, "H3ContinuumAdvancedV3": H3ContinuumAdvancedV3,
"H3ContinuumAssembleV3": H3ContinuumAssembleV3, "H3ContinuumAssembleV3": H3ContinuumAssembleV3,
"H3ContinuumAssembleSeamExperimental": H3ContinuumAssembleSeamExperimental, "H3ContinuumAssembleSeamExperimental": H3ContinuumAssembleSeamExperimental,
"H3ContinuumSeamTestSource": H3ContinuumSeamTestSource,
} }
NODE_DISPLAY_NAME_MAPPINGS = { NODE_DISPLAY_NAME_MAPPINGS = {
"H3ContinuumSamplerProduction": "H3 Continuum Sampler V3.3", "H3ContinuumSamplerProduction": "H3 Continuum Sampler V3.2.4",
"H3ContinuumSamplerTimelineVideo": "H3 Continuum Timeline Video", "H3ContinuumSamplerTimelineVideo": "H3 Continuum Sampler V3.3",
"H3ContinuumSamplerV3": "H3 Continuum Sampler V3", "H3ContinuumSamplerV3": "H3 Continuum Sampler V3",
"H3ContinuumAdvancedV3": "H3 Continuum Advanced V3", "H3ContinuumAdvancedV3": "H3 Continuum Advanced V3",
"H3ContinuumAssembleV3": "H3 Continuum Assemble V3", "H3ContinuumAssembleV3": "H3 Continuum Assemble V3.2.4",
"H3ContinuumAssembleSeamExperimental": "H3 Continuum Assemble + Seam", "H3ContinuumAssembleSeamExperimental": "H3 Continuum Assemble + Seam",
"H3ContinuumSeamTestSource": "H3 Continuum Seam Test Source (Experimental)",
} }
-236
View File
@@ -1,236 +0,0 @@
"""Deterministic decoded-chunk source for video seam validation."""
from __future__ import annotations
import math
from typing import Any
import torch
import torch.nn.functional as F
from ..hardening import enrich_assembly_plan
from .plan import (
ASSEMBLY_PLAN_MAGIC,
ASSEMBLY_PLAN_SCHEMA_VERSION,
FPS,
validate_assembly_plan,
)
TEST_SIZE_256 = "256 px (Fast)"
TEST_SIZE_512 = "512 px"
TEST_SIZE_INPUT = "Input Size"
TEST_SIZE_OPTIONS = (TEST_SIZE_256, TEST_SIZE_512, TEST_SIZE_INPUT)
def _prepare_image(image: Any, size_mode: str) -> torch.Tensor:
if not torch.is_tensor(image) or image.ndim != 4 or int(image.shape[-1]) < 3:
raise ValueError("image must be an IMAGE tensor [B,H,W,C]")
if int(image.shape[0]) != 1:
raise ValueError("Seam Test Source requires exactly one input image")
frame = image[0, ..., :3].detach().to(device="cpu", dtype=torch.float32)
if not bool(torch.isfinite(frame).all().item()):
raise ValueError("input image contains NaN or Inf")
frame = frame.clamp(0.0, 1.0)
if size_mode == TEST_SIZE_INPUT:
return frame.contiguous()
limits = {TEST_SIZE_256: 256, TEST_SIZE_512: 512}
if size_mode not in limits:
raise ValueError(f"unknown Test Resolution: {size_mode!r}")
height, width = int(frame.shape[0]), int(frame.shape[1])
scale = min(1.0, float(limits[size_mode]) / float(max(height, width)))
target_height = max(1, int(round(height * scale)))
target_width = max(1, int(round(width * scale)))
if (target_height, target_width) == (height, width):
return frame.contiguous()
resized = F.interpolate(
frame.permute(2, 0, 1).unsqueeze(0),
size=(target_height, target_width),
mode="bilinear",
align_corners=False,
)
return resized[0].permute(1, 2, 0).contiguous()
def _repeat_frame(frame: torch.Tensor, count: int) -> torch.Tensor:
return frame.unsqueeze(0).expand(int(count), -1, -1, -1).clone()
def _ramp_chunk(
previous_anchor: torch.Tensor,
*,
context_frames: int,
net_frames: int,
exposure_change: float,
) -> tuple[torch.Tensor, torch.Tensor]:
context = _repeat_frame(previous_anchor, context_frames)
ramp_count = 5
ramp_factors = torch.linspace(
1.0 - exposure_change,
1.0 - exposure_change * 2.0,
steps=ramp_count,
dtype=torch.float32,
)
ramp = (
previous_anchor.unsqueeze(0)
* ramp_factors.reshape(-1, 1, 1, 1)
).clamp(0.0, 1.0)
next_anchor = ramp[-1].contiguous()
tail = _repeat_frame(next_anchor, net_frames - ramp_count)
return torch.cat((context, ramp, tail), dim=0).contiguous(), next_anchor
def _silent_audio(total_frames: int, sample_rate: int) -> dict[str, Any]:
samples = int(math.ceil(total_frames / FPS * sample_rate)) + 8
return {
"waveform": torch.zeros((1, 2, samples), dtype=torch.float32),
"sample_rate": int(sample_rate),
}
def _assembly_plan(width: int, height: int) -> dict[str, Any]:
chunks = [
{
"sequence_index": 1,
"chunk_index": 1,
"total_frames": 124,
"trim_frames": 0,
"net_frames": 124,
"context_frames": 0,
"expected_video_latent_t": 32,
"expected_audio_latent_t": 207,
},
{
"sequence_index": 2,
"chunk_index": 2,
"total_frames": 141,
"trim_frames": 22,
"net_frames": 119,
"context_frames": 22,
"expected_video_latent_t": 36,
"expected_audio_latent_t": 235,
},
{
"sequence_index": 3,
"chunk_index": 3,
"total_frames": 141,
"trim_frames": 22,
"net_frames": 119,
"context_frames": 22,
"expected_video_latent_t": 36,
"expected_audio_latent_t": 235,
},
]
plan = {
"magic": ASSEMBLY_PLAN_MAGIC,
"schema_version": ASSEMBLY_PLAN_SCHEMA_VERSION,
"fps": FPS,
"width": int(width),
"height": int(height),
"chunk_seconds": 5.0,
"target_frames": 360,
"preserve_final_frame": True,
"chunks": chunks,
}
enrich_assembly_plan(plan)
return validate_assembly_plan(plan)
class H3ContinuumSeamTestSource:
DESCRIPTION = (
"Create deterministic decoded chunks for testing Video Seam modes. "
"Chunk 2 and Chunk 3 each begin with a controlled exposure ramp. "
"This node performs no H3 sampling."
)
SEARCH_ALIASES = ["H3 seam test", "H3 exposure ramp test"]
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"image": ("IMAGE",),
"exposure_change": (
"FLOAT",
{
"default": 0.08,
"min": 0.01,
"max": 0.20,
"step": 0.01,
"display_name": "Exposure Change",
"tooltip": (
"8% is the controlled default. Each new chunk ramps "
"from one step darker to two steps darker."
),
},
),
"test_resolution": (
TEST_SIZE_OPTIONS,
{
"default": TEST_SIZE_256,
"display_name": "Test Resolution",
"tooltip": (
"256 px is recommended for fast seam testing. "
"Input Size can require several GiB of RAM."
),
},
),
}
}
RETURN_TYPES = (
"IMAGE",
"AUDIO",
"H3_CONTINUUM_ASSEMBLY_PLAN",
"STRING",
)
RETURN_NAMES = ("images", "audio", "assembly_plan", "instructions")
OUTPUT_IS_LIST = (True, True, False, False)
FUNCTION = "create"
CATEGORY = "MiniMax H3/Continuum/Testing"
EXPERIMENTAL = True
def create(
self,
image,
exposure_change=0.08,
test_resolution=TEST_SIZE_256,
):
change = float(exposure_change)
if not math.isfinite(change) or not 0.01 <= change <= 0.20:
raise ValueError("Exposure Change must be between 0.01 and 0.20")
base = _prepare_image(image, str(test_resolution))
chunk_1 = _repeat_frame(base, 124)
chunk_2, anchor_2 = _ramp_chunk(
base,
context_frames=22,
net_frames=119,
exposure_change=change,
)
chunk_3, _anchor_3 = _ramp_chunk(
anchor_2,
context_frames=22,
net_frames=119,
exposure_change=change,
)
images = [chunk_1, chunk_2, chunk_3]
audio = [
_silent_audio(124, 32000),
_silent_audio(141, 32000),
_silent_audio(141, 32000),
]
plan = _assembly_plan(int(base.shape[1]), int(base.shape[0]))
instructions = (
"H3 Continuum Seam Test Source\n"
"1. Connect images, audio, and assembly_plan to the matching inputs "
"of H3 Continuum Assemble + Seam.\n"
"2. Set Audio Seam=Off and exact_total_duration=true.\n"
"3. Run Video Seam=Analyze Only, then Auto, then Auto 2.\n"
"4. Analyze Only should report class=exposure_ramp at both boundaries.\n"
"5. Auto should keep both native boundaries. Auto 2 should report "
"normalized exposure/color on 4 exposure ramp boundary frame(s).\n"
f"Source: 3 x 5 sec, 24 fps, {base.shape[1]}x{base.shape[0]}, "
f"exposure change={change:.0%}."
)
return images, audio, plan, instructions