Files
ComfyUI-H3-Continuum-Tiled/v3/nodes.py
T
chris.dumas 92135c0db0
tests / test (push) Canceled after 0s
tests / windows-storage (push) Canceled after 0s
Support per-chunk timeline durations
2026-11-10 11:46:19 +00:00

1352 lines
51 KiB
Python

"""Public latent-first facade nodes for H3 Continuum V3."""
from __future__ import annotations
import time
from ..constants import (
CHUNK_SECONDS_DEFAULT,
CHUNK_SECONDS_MAX,
CHUNK_SECONDS_MIN,
CHUNK_SECONDS_STEP,
CHUNK_SECONDS_TOOLTIP,
DIAGNOSTICS_FULL,
)
from ..v2.nodes import (
CATEGORY,
DIAGNOSTICS_OPTIONS,
H3ContinuumSamplerV2,
PROMPT_FORMAT_OPTIONS,
SEAM_CORRECTION_OFF,
SPARSE_OVERRIDE_SCHEMA_VERSION,
V2_CONTINUITY_OPTIONS,
validate_sparse_prompt_overrides,
)
from .assembly import H3ContinuumAssembleSeamExperimental, H3ContinuumAssembleV3
from .plan import make_assembly_plan, make_review_audio_projection, REVIEW_AUDIO_PROJECTION_KEY
from .execution_planner import (
PROJECTION_CURRENT_REVIEW_UNIT,
PROJECTION_FULL_ACCEPTED_PREFIX,
resolve_projection_decision as _resolve_projection_decision,
)
from .planning_types import ProjectionDecision
from .review_control import REVISION_STATUS_REVIEW_READY
from ..timeline_video import TIMELINE_VIDEO_SIZE_OPTIONS
REGENERATE_AUTO = "Auto"
REGENERATE_OPTIONS = (REGENERATE_AUTO,) + tuple(
f"Chunk {index}" for index in range(1, 17)
)
def _regenerate_from_value(value, *, chunks: int) -> int:
if isinstance(value, str):
text = value.strip()
if text == REGENERATE_AUTO:
resolved = 0
elif text.startswith("Chunk ") and text[6:].isdigit():
resolved = int(text[6:])
elif text.isdigit():
resolved = int(text)
else:
raise ValueError(f"unknown Regenerate From value: {value!r}")
else:
resolved = int(value)
if resolved < 0 or resolved > int(chunks):
raise ValueError(
f"Regenerate From Chunk {resolved} is outside the configured "
f"1-{int(chunks)} chunk range"
)
return resolved
def _validate_regenerate_storage(run_storage: str, regenerate_from: int) -> None:
if str(run_storage) == "Off" and int(regenerate_from) > 0:
raise ValueError(
"Regenerate From requires Run Storage = Save + Auto Resume"
)
_PARTIAL_REVIEW_SECOND_PASS_WARNING = (
"Warning: Review is incomplete. Second Pass refinement of a partial review "
"sequence is not yet supported."
)
def resolve_projection_decision(
*,
review_execution,
effective_result_status: str,
session,
physical_group_facts: tuple[tuple[int, ...], ...],
) -> ProjectionDecision:
"""Compatibility adapter for the R1 pure resolver API."""
entries = session.get("chunks") if isinstance(session, dict) else None
return _resolve_projection_decision(
review_execution=review_execution,
effective_result_status=effective_result_status,
accepted_chunks=(len(entries) if isinstance(entries, list) else 0),
physical_group_facts=physical_group_facts,
)
def _physical_group_facts(assembly_plan) -> tuple[tuple[int, ...], ...]:
"""Extract immutable logical membership facts from an existing assembly plan."""
if not isinstance(assembly_plan, dict):
return ()
groups = assembly_plan.get("decode_groups") or assembly_plan.get("chunks")
if not isinstance(groups, list):
return ()
facts = []
for group in groups:
if not isinstance(group, dict):
return ()
indices = group.get("logical_chunk_indices")
if indices is None:
indices = [group.get("chunk_index")]
if not isinstance(indices, list) or not indices:
return ()
try:
normalized = tuple(int(index) for index in indices)
except (TypeError, ValueError):
return ()
if any(index < 1 for index in normalized):
return ()
facts.append(normalized)
return tuple(facts)
def _partial_review_warning(storage, *, capture_refine_context: bool) -> str:
execution = getattr(storage, "review_execution", None)
if (
bool(capture_refine_context)
and execution is not None
and bool(getattr(execution, "partial_review", False))
):
return _PARTIAL_REVIEW_SECOND_PASS_WARNING
return ""
def _review_decode_chunk_range(storage, *, capture_refine_context: bool):
# Refine context is a separate, preserved output; capturing it does not
# require external VAE nodes to decode the entire accepted prefix.
if getattr(storage, "review_generation_mode", None) != "Review Each Chunk":
return None
execution = getattr(storage, "review_execution", None)
if execution is None or bool(getattr(execution, "finish_remaining", False)):
return None
start = getattr(execution, "next_review_unit_start", None)
end = getattr(execution, "next_review_unit_end", None)
if start is None or end is None:
return None
if not (
bool(getattr(execution, "partial_review", False))
or bool(getattr(execution, "smart_regenerate", False))
):
return None
return int(start), int(end)
def _apply_review_decode_scope(
outputs,
*,
storage,
capture_refine_context: bool,
configured_chunks: int,
chunk_seconds: float,
first_frame,
last_frame,
timeline_video_source,
):
_, _, assembly_plan, result, *tail = outputs
session = result.get("session") if isinstance(result, dict) else None
entries = session.get("chunks") if isinstance(session, dict) else None
if not isinstance(entries, list):
return outputs
execution_plan = getattr(storage, "execution_plan", None)
decision = getattr(execution_plan, "projection", None)
if not isinstance(decision, ProjectionDecision):
# Compatibility for isolated callers that replace the sequence runtime
# and therefore cannot carry its Queue-local plan. The same pure
# resolver remains the only Projection owner.
effective_status = (
REVISION_STATUS_REVIEW_READY
if getattr(storage, "review_generation_mode", None)
== "Review Each Chunk"
else "complete"
)
decision = resolve_projection_decision(
review_execution=getattr(storage, "review_execution", None),
effective_result_status=effective_status,
session=session,
physical_group_facts=_physical_group_facts(assembly_plan),
)
if decision.kind != PROJECTION_CURRENT_REVIEW_UNIT:
return outputs
start = int(decision.start_chunk)
end = int(decision.end_chunk)
audio_projection = make_review_audio_projection(
assembly_plan, start_chunk=start, end_chunk=end,
)
selected_entries = entries[start - 1 : end]
sequence_complete = len(entries) == int(configured_chunks)
from ..v2.sequence import _terminal_flf_merge_enabled
from .plan import prepare_physical_decode_entries
terminal_merged = sequence_complete and len(set(assembly_plan.get("chunk_durations") or [float(chunk_seconds)] * int(configured_chunks))) == 1 and _terminal_flf_merge_enabled(
multi_chunk_flf=(
first_frame is not None
and last_frame is not None
and int(configured_chunks) > 1
),
chunks=int(configured_chunks),
chunk_seconds=float(chunk_seconds),
prompt_hashes=[str(entry["prompt_hash"]) for entry in entries],
timeline_video_source=timeline_video_source,
)
selected_terminal_merged = terminal_merged and (
end == int(configured_chunks)
and start <= int(configured_chunks) - 1
)
decode_entries, scoped_plan = prepare_physical_decode_entries(
selected_entries,
chunk_seconds=float(chunk_seconds),
preserve_final_frame=(
sequence_complete
and end == int(configured_chunks)
and last_frame is not None
),
terminal_merged=selected_terminal_merged,
terminal_initial_pair=(start == 1),
)
scoped_plan[REVIEW_AUDIO_PROJECTION_KEY] = audio_projection
# Projection narrows the AV decode view, not the already-verified routing
# decision. Keep that Queue-local plan available to the public Inspector.
route_plan = assembly_plan.get("reference_routing_v1")
if isinstance(route_plan, dict):
scoped_plan = dict(scoped_plan)
scoped_plan["reference_routing_v1"] = route_plan
scoped_video = [{"samples": entry["video"]} for entry in decode_entries]
scoped_audio = [{"samples": entry["audio"]} for entry in decode_entries]
scoped_result = dict(result)
scoped_result["report"] = str(scoped_result.get("report", "")).rstrip() + (
f"\nDecode preview: Chunk {start}"
if start == end
else f"\nDecode preview: Chunks {start}-{end}"
)
return (scoped_video, scoped_audio, scoped_plan, scoped_result, *tail)
def _format_review_status(storage, *, detailed: bool = False) -> str:
"""Format Phase D facts after finalize without reading storage in frontend."""
execution = getattr(storage, "review_execution", None)
if execution is None:
return ""
if getattr(storage, "review_generation_mode", None) != "Review Each Chunk":
return str(getattr(execution, "status_hint", "")).strip()
manifest = getattr(storage, "manifest", None)
contract = getattr(storage, "contract", None)
if not isinstance(manifest, dict) or not isinstance(contract, dict):
return str(getattr(execution, "status_hint", "")).strip()
total = int(contract.get("chunk_count", 0))
completed = len(list(manifest.get("chunks") or []))
unit = manifest.get("review_unit")
if not isinstance(unit, dict):
unit = None
if bool(getattr(execution, "finish_remaining", False)):
return "\n".join(
(
"Review completed",
(
f"{int(getattr(storage, 'reused_count', 0))} reused; "
f"{int(getattr(storage, 'generated_count', 0))} generated; "
f"{total} total"
),
"Sequence complete",
)
)
if unit is None:
if completed >= total > 0:
return "Review Mode\nSequence complete"
return str(getattr(execution, "status_hint", "")).strip()
start = int(unit.get("start", 0))
end = int(unit.get("end", 0))
terminal = start != end
if bool(getattr(execution, "smart_regenerate", False)):
regenerated = (
f"Chunk {start} regenerated"
if not terminal
else f"Chunks {start}-{end} regenerated"
)
lines = ["Smart Regenerate", regenerated]
if start > 1:
lines.append(f"Preserved: Chunks 1-{start - 1}")
if terminal:
lines.append("Terminal Merge: 1 physical review unit")
if detailed:
variation = getattr(execution, "requested_effective_nonce", None)
if variation is not None:
lines.append(f"Variation: {int(variation)}")
lines.append("Ready for review")
if completed >= total > 0:
lines.append("Sequence complete")
return "\n".join(lines)
ready = (
f"Chunk {start} / {total} ready"
if not terminal
else f"Chunks {start}-{end} / {total} ready"
)
lines = ["Review Mode", ready]
if terminal:
lines.append("Terminal Merge: 1 physical review unit")
if completed > 0:
lines.append(f"Completed: Chunks 1-{completed}")
if completed >= total > 0:
lines.append("Sequence complete")
else:
lines.extend(
(
"Next: Queue again = Accept + Continue",
"Options: Regenerate Current / Finish Remaining",
)
)
return "\n".join(lines)
class H3ContinuumAdvancedV3:
DESCRIPTION = (
"Optional continuation, session, reroll, and diagnostics settings for V3."
)
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"audio_continuity": ("BOOLEAN", {"default": True}),
"diagnostics": (
DIAGNOSTICS_OPTIONS,
{
"default": DIAGNOSTICS_OPTIONS[0],
"display_name": "Report Detail",
},
),
"reroll_from_chunk": (
"INT",
{"default": 0, "min": 0, "max": 16, "step": 1},
),
"reroll_nonce": (
"INT",
{
"default": 0,
"min": 0,
"max": 0xFFFFFFFF,
"step": 1,
},
),
"strict_compatibility": ("BOOLEAN", {"default": False}),
"debug": ("BOOLEAN", {"default": False}),
"show_preview": ("BOOLEAN", {"default": True}),
},
"optional": {
"last_frame": ("IMAGE",),
"session": ("H3_CONTINUUM_SESSION",),
"initial_state": ("H3_CONTINUUM_STATE",),
"prompt_plan": ("H3_CONTINUUM_PROMPT_PLAN",),
},
}
RETURN_TYPES = ("H3_CONTINUUM_ADVANCED_V3",)
RETURN_NAMES = ("advanced",)
FUNCTION = "pack"
CATEGORY = CATEGORY
def pack(
self,
audio_continuity,
diagnostics,
reroll_from_chunk,
reroll_nonce,
strict_compatibility,
debug,
show_preview,
last_frame=None,
session=None,
initial_state=None,
prompt_plan=None,
):
return (
{
"audio_continuity": bool(audio_continuity),
"diagnostics": diagnostics,
"reroll_from_chunk": int(reroll_from_chunk),
"reroll_nonce": int(reroll_nonce),
"strict_compatibility": False,
"debug": bool(debug),
"show_preview": bool(show_preview),
"last_frame": last_frame,
"session": session,
"initial_state": initial_state,
"prompt_plan": prompt_plan,
},
)
class H3ContinuumSamplerV3:
DESCRIPTION = (
"Latent-first N-chunk MiniMax H3 sampler. Sampling, native continuation, "
"State/Session, and Spectrum interop stay inside Continuum; ComfyUI Core "
"performs video and audio VAE decoding."
)
SEARCH_ALIASES = [
"H3 Continuum V3",
"H3 latent first",
"MiniMax H3 external VAE decode",
]
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"model": ("MODEL",),
"clip": ("CLIP",),
"video_vae": (
"VAE",
{
"tooltip": (
"Used only to encode image conditioning. T2VA does "
"not use it; V3 never decodes with it."
),
},
),
"sampler": ("SAMPLER",),
"sigmas": ("SIGMAS",),
"sequence_prompt": (
"STRING",
{
"forceInput": True,
"display_name": "Sequence Prompt",
"tooltip": (
"Connect one Text (Multiline) for the complete sequence."
),
},
),
"prompt_mode": (
PROMPT_FORMAT_OPTIONS,
{
"default": PROMPT_FORMAT_OPTIONS[0],
"display_name": "Prompt Format",
},
),
"chunks": ("INT", {"default": 3, "min": 1, "max": 16, "step": 1}),
"chunk_seconds": (
"FLOAT",
{
"default": CHUNK_SECONDS_DEFAULT,
"min": CHUNK_SECONDS_MIN,
"max": CHUNK_SECONDS_MAX,
"step": CHUNK_SECONDS_STEP,
"tooltip": CHUNK_SECONDS_TOOLTIP,
},
),
"width": (
"INT",
{"default": 1344, "min": 32, "max": 16384, "step": 32},
),
"height": (
"INT",
{"default": 768, "min": 32, "max": 16384, "step": 32},
),
"continuity": (
V2_CONTINUITY_OPTIONS,
{"default": V2_CONTINUITY_OPTIONS[1]},
),
"base_seed": (
"INT",
{
"default": 0,
"min": 0,
"max": 0xFFFFFFFFFFFFFFFF,
"control_after_generate": True,
},
),
},
"optional": {
"first_frame": (
"IMAGE",
{"tooltip": "Optional. Leave image inputs disconnected for T2VA."},
),
"prompt_overrides": ("H3_CONTINUUM_CLIP_OVERRIDES",),
"advanced": ("H3_CONTINUUM_ADVANCED_V3",),
},
}
RETURN_TYPES = (
"LATENT",
"LATENT",
"H3_CONTINUUM_ASSEMBLY_PLAN",
"H3_CONTINUUM_RESULT",
)
RETURN_NAMES = (
"video_latents",
"audio_latents",
"assembly_plan",
"result",
)
OUTPUT_IS_LIST = (True, True, False, False)
FUNCTION = "run"
CATEGORY = CATEGORY
def run(
self,
model,
clip,
video_vae,
sampler,
sigmas,
sequence_prompt,
prompt_mode,
chunks,
chunk_seconds,
width,
height,
continuity,
base_seed,
first_frame=None,
prompt_overrides=None,
advanced=None,
reference_assets=None,
reference_audio_source=None,
reference_audio_vae=None,
driving_audio_source=None,
driving_audio_vae=None,
reference_video_source=None,
timeline_video_source=None,
guide_source=None,
capture_refine_context=False,
memory_attribution=False,
prompt_conditioning_cache=False,
reference_encode_cache=False,
continuation_transport="reference_context_v1",
max_new_physical_groups=None,
reference_routing_request=None,
):
if prompt_overrides is not None and not isinstance(prompt_overrides, dict):
prompt_overrides = None
if advanced is not None and not isinstance(advanced, dict):
advanced = None
advanced_values = {
"audio_continuity": True,
"diagnostics": DIAGNOSTICS_OPTIONS[0],
"reroll_from_chunk": 0,
"reroll_nonce": 0,
"strict_compatibility": False,
"debug": False,
"show_preview": True,
"last_frame": None,
"session": None,
"initial_state": None,
"prompt_plan": None,
"_diagnostic_continuation_policy": None,
}
if advanced:
advanced_values.update(advanced)
advanced_values["strict_compatibility"] = False
clip_prompt_inputs = {}
if prompt_overrides:
if (
type(prompt_overrides.get("schema_version")) is not int
or prompt_overrides.get("schema_version")
!= SPARSE_OVERRIDE_SCHEMA_VERSION
):
prompt_overrides = None
if prompt_overrides is not None:
try:
sparse_overrides = validate_sparse_prompt_overrides(
prompt_overrides.get("overrides"), chunks=int(chunks)
)
except (TypeError, ValueError):
sparse_overrides = {}
for index, prompt in sparse_overrides.items():
clip_prompt_inputs[f"clip_{index}_prompt"] = prompt
sequence_outputs = H3ContinuumSamplerV2().run(
model=model,
clip=clip,
video_vae=video_vae,
audio_vae=None,
sampler=sampler,
sigmas=sigmas,
prompt_mode=prompt_mode,
prompt_script=sequence_prompt,
chunks=chunks,
chunk_seconds=chunk_seconds,
width=width,
height=height,
continuity=continuity,
base_seed=base_seed,
audio_continuity=advanced_values["audio_continuity"],
exact_total_duration=False,
diagnostics=advanced_values["diagnostics"],
reroll_from_chunk=advanced_values["reroll_from_chunk"],
reroll_nonce=advanced_values["reroll_nonce"],
strict_compatibility=False,
debug=advanced_values["debug"],
seam_correction=SEAM_CORRECTION_OFF,
first_frame=first_frame,
last_frame=advanced_values["last_frame"],
session=advanced_values["session"],
initial_state=advanced_values["initial_state"],
prompt_plan=advanced_values["prompt_plan"],
sequence_prompt=sequence_prompt,
show_preview=advanced_values["show_preview"],
latent_only=True,
reference_assets=reference_assets,
reference_audio_source=reference_audio_source,
reference_audio_vae=reference_audio_vae,
driving_audio_source=driving_audio_source,
driving_audio_vae=driving_audio_vae,
reference_video_source=reference_video_source,
timeline_video_source=timeline_video_source,
guide_source=guide_source,
capture_refine_context=bool(capture_refine_context),
memory_attribution=bool(memory_attribution),
prompt_conditioning_cache=bool(prompt_conditioning_cache),
reference_encode_cache=bool(reference_encode_cache),
continuation_transport=str(continuation_transport),
max_new_physical_groups=max_new_physical_groups,
reference_routing_request=reference_routing_request,
_diagnostic_continuation_policy=advanced_values[
"_diagnostic_continuation_policy"
],
**clip_prompt_inputs,
)
if bool(capture_refine_context):
entries, last_state, session, report, refine_context = sequence_outputs
else:
entries, last_state, session, report = sequence_outputs
from ..v2.sequence import _terminal_flf_merge_enabled
from .plan import prepare_physical_decode_entries
configured_chunks = int(chunks)
completed_chunks = len(entries)
sequence_complete = completed_chunks == configured_chunks
prompt_durations = [float(entry.get("plan", {}).get("requested_extend_seconds", chunk_seconds)) for entry in entries]
terminal_merged = sequence_complete and len(set(prompt_durations)) == 1 and _terminal_flf_merge_enabled(
multi_chunk_flf=(
first_frame is not None
and advanced_values["last_frame"] is not None
and configured_chunks > 1
),
chunks=configured_chunks,
chunk_seconds=float(chunk_seconds),
prompt_hashes=[str(entry["prompt_hash"]) for entry in entries],
timeline_video_source=timeline_video_source,
)
decode_entries, assembly_plan = prepare_physical_decode_entries(
entries,
chunk_seconds=float(chunk_seconds),
preserve_final_frame=(
sequence_complete and advanced_values["last_frame"] is not None
),
terminal_merged=terminal_merged,
)
if reference_routing_request is not None:
from .reference_plan_inspector import project_reference_plan
runtime = reference_routing_request.runtime
if runtime is None:
raise RuntimeError("Reference Routing completed without its runtime Plan")
assembly_plan = dict(assembly_plan)
assembly_plan["reference_routing_v1"] = project_reference_plan(runtime)
video_latents = [{"samples": entry["video"]} for entry in decode_entries]
audio_latents = [{"samples": entry["audio"]} for entry in decode_entries]
if terminal_merged:
report = str(report).rstrip() + (
"\nDecode: terminal merged latent retained as one physical external "
"Core VAE decode group; logical Run Storage entries are unchanged."
)
result = {
"last_state": last_state,
"session": session,
"report": report,
}
outputs = (video_latents, audio_latents, assembly_plan, result)
if bool(capture_refine_context):
return (*outputs, refine_context)
return outputs
class H3ContinuumSamplerProduction(H3ContinuumSamplerV3):
"""Stable single-entry sampler UI for V3.3 and later releases."""
DEPRECATED = False
CATEGORY = CATEGORY
DESCRIPTION = (
"Production H3 Continuum sampler with first/last-frame or image-reference conditioning and "
"ComfyUI-native advanced widgets. Video/audio VAE decoding remains in "
"ComfyUI Core."
)
SEARCH_ALIASES = [
"H3 Continuum Sampler V3.3",
"H3 Continuum Sampler V3.2",
"H3 Continuum Production",
"MiniMax H3 long video",
]
RETURN_TYPES = (
"LATENT",
"LATENT",
"H3_CONTINUUM_ASSEMBLY_PLAN",
"STRING",
)
RETURN_NAMES = (
"video_latents",
"audio_latents",
"assembly_plan",
"status",
)
@classmethod
def INPUT_TYPES(cls):
advanced = {"advanced": True}
return {
"required": {
"model": (
"MODEL",
{
"tooltip": (
"MiniMax H3 diffusion model used for every Continuum chunk."
)
},
),
"clip": (
"CLIP",
{
"tooltip": (
"MiniMax H3 text encoder used to encode the complete Sequence Prompt."
)
},
),
"video_vae": (
"VAE",
{
"tooltip": (
"Used only to encode image conditioning. T2VA does "
"not use it; Continuum never decodes with it."
),
},
),
"sampler": (
"SAMPLER",
{
"tooltip": (
"ComfyUI sampler algorithm used unchanged for every generated chunk."
)
},
),
"sigmas": (
"SIGMAS",
{
"tooltip": (
"ComfyUI noise schedule used unchanged for every generated chunk."
)
},
),
"sequence_prompt": (
"STRING",
{
"forceInput": True,
"display_name": "Sequence Prompt",
"tooltip": (
"Connect one Text (Multiline) for the complete sequence."
),
},
),
"prompt_mode": (
PROMPT_FORMAT_OPTIONS,
{
"default": PROMPT_FORMAT_OPTIONS[0],
"display_name": "Prompt Format",
"tooltip": "Auto accepts Fixed, list-separated, and timeline prompt styles.",
**advanced,
},
),
"chunks": (
"INT",
{
"default": 3,
"min": 1,
"max": 16,
"step": 1,
"tooltip": "Number of sequential Continuum chunks to generate.",
},
),
"chunk_seconds": (
"FLOAT",
{
"default": CHUNK_SECONDS_DEFAULT,
"min": CHUNK_SECONDS_MIN,
"max": CHUNK_SECONDS_MAX,
"step": CHUNK_SECONDS_STEP,
"tooltip": CHUNK_SECONDS_TOOLTIP,
},
),
"width": (
"INT",
{
"default": 1344,
"min": 32,
"max": 16384,
"step": 32,
"tooltip": "Output width. Use a multiple of 32.",
},
),
"height": (
"INT",
{
"default": 768,
"min": 32,
"max": 16384,
"step": 32,
"tooltip": "Output height. Use a multiple of 32.",
},
),
"continuity": (
V2_CONTINUITY_OPTIONS,
{
"default": V2_CONTINUITY_OPTIONS[1],
"tooltip": "Amount of prior video context retained at each chunk boundary.",
},
),
"base_seed": (
"INT",
{
"default": 0,
"min": 0,
"max": 0xFFFFFFFFFFFFFFFF,
"control_after_generate": True,
"tooltip": "Base seed used to derive deterministic per-chunk seeds.",
},
),
"audio_continuity": (
"BOOLEAN",
{
"default": True,
"advanced": True,
"tooltip": (
"On passes prior audio context into continuation chunks. "
"Turn it off only to isolate or replace generated audio."
),
},
),
"diagnostics": (
DIAGNOSTICS_OPTIONS,
{
"default": DIAGNOSTICS_OPTIONS[0],
"display_name": "Report Detail",
"advanced": True,
"tooltip": "Controls the detail level of the read-only Status report. It does not change generated tensors.",
},
),
"reroll_from_chunk": (
REGENERATE_OPTIONS,
{
"default": REGENERATE_AUTO,
"display_name": "Regenerate From",
"advanced": True,
"tooltip": (
"Auto resumes the longest compatible saved prefix. "
"Choosing a chunk reuses earlier chunks and regenerates "
"that chunk and everything after it."
),
},
),
"reroll_nonce": (
"INT",
{
"default": 0,
"min": 0,
"max": 0xFFFFFFFF,
"step": 1,
"advanced": True,
"display_name": "Variation Nonce",
"tooltip": (
"Change only when regenerating an explicit chunk and you want "
"a new variation with otherwise identical settings."
),
},
),
"strict_compatibility": (
"BOOLEAN",
{
"default": True,
"advanced": True,
"tooltip": "Legacy saved-workflow input. V3.8 keeps it loadable but ignores its value.",
},
),
"debug": (
"BOOLEAN",
{
"default": False,
"advanced": True,
"tooltip": "Developer diagnostics controlled by the H3 Continuum settings panel.",
},
),
"show_preview": (
"BOOLEAN",
{
"default": True,
"advanced": True,
"tooltip": "Show live sampling previews. Disable only to reduce preview overhead.",
},
),
"run_storage": (
("Off", "Save + Auto Resume"),
{
"default": "Off",
"display_name": "Run Storage",
"advanced": True,
"tooltip": "Atomically save raw AV chunks and resume a compatible saved run.",
},
),
"run_name": (
"STRING",
{
"default": "",
"display_name": "Run Name (Optional Override)",
"advanced": True,
"tooltip": "Enter a stable name for this saved run. Compatible chunks are selected automatically.",
},
),
"reference_size": (
("Match Output", "Max Identity"),
{
"default": "Match Output",
"display_name": "Reference Size",
"advanced": True,
"tooltip": "Match Output is the practical default; Max Identity preserves more reference detail.",
},
),
"project_id": (
"STRING",
{
"default": "",
"display_name": "Auto Resume ID Override",
"advanced": True,
"tooltip": "Optional. Leave blank to derive a stable ID from this sampler node. Run Name remains the explicit override.",
},
),
},
"optional": {
"first_frame": (
"IMAGE",
{
"tooltip": (
"First Image conditioning for I2VA or FL2VA. With Output Size = "
"First Image, its aspect ratio also defines the output canvas. Leave "
"it disconnected and use Manual Width/Height for T2VA."
)
},
),
"last_frame": (
"IMAGE",
{"tooltip": "Optional last-frame anchor for FL2VA. Leave disconnected for T2VA and normal I2VA."},
),
"reference_image_1": (
"IMAGE",
{"tooltip": "Optional Reference Image 1 for appearance, identity, subject, or scene guidance."},
),
"reference_image_2": (
"IMAGE",
{"tooltip": "Optional Reference Image 2. Prompt references follow the connected image order."},
),
"reference_image_3": (
"IMAGE",
{"tooltip": "Optional Reference Image 3. Prompt references follow the connected image order."},
),
"reference_audio_1": (
"AUDIO",
{"tooltip": "Legacy optional single Reference Audio. Do not connect it together with Audio References."},
),
"reference_audio_vae": (
"VAE",
{"tooltip": "Audio VAE used only by the legacy single Reference Audio input."},
),
},
"hidden": {
"prompt": "PROMPT",
"unique_id": "UNIQUE_ID",
},
}
def run(
self,
model,
clip,
video_vae,
sampler,
sigmas,
sequence_prompt,
prompt_mode,
chunks,
chunk_seconds,
width,
height,
continuity,
base_seed,
audio_continuity,
diagnostics,
reroll_from_chunk,
reroll_nonce,
strict_compatibility,
debug,
show_preview,
run_storage="Off",
run_name="",
reference_size="Match Output",
project_id="",
first_frame=None,
last_frame=None,
reference_image_1=None,
reference_image_2=None,
prompt_overrides=None,
prompt=None,
unique_id=None,
reference_image_3=None,
reference_audio_1=None,
reference_audio_vae=None,
driving_audio_source=None,
driving_audio_vae=None,
reference_video_source=None,
timeline_video_source=None,
guide_source=None,
capture_refine_context=False,
memory_attribution=False,
prompt_conditioning_cache=False,
reference_encode_cache=False,
continuation_transport="reference_context_v1",
max_new_physical_groups=None,
generation_mode=None,
review_action=None,
take_group=0,
take_revision_id="",
take_action="Automatic",
_diagnostic_continuation_policy=None,
audio_references=None,
reference_image_4=None,
reference_image_5=None,
image_references=None,
_reference_routing_settings=None,
):
runtime_started_at = time.perf_counter()
from ..reference import prepare_reference_assets
from ..reference_audio import resolve_reference_audio_input
regenerate_from = _regenerate_from_value(
reroll_from_chunk,
chunks=int(chunks),
)
review_requested = generation_mode is not None or review_action is not None
take_requested = str(take_action) != "Automatic"
if review_requested and (generation_mode is None or review_action is None):
raise ValueError(
"internal review execution requires both generation_mode and review_action"
)
if review_requested and max_new_physical_groups is not None:
raise ValueError(
"internal review execution owns max_new_physical_groups"
)
if take_requested and generation_mode != "Review Each Chunk":
raise ValueError("Take selection requires Review Each Chunk")
reference_routing_request = None
if _reference_routing_settings is None:
reference_assets = prepare_reference_assets(
reference_image_1=reference_image_1,
reference_image_2=reference_image_2,
output_width=int(width),
output_height=int(height),
size_mode=reference_size,
reference_image_3=reference_image_3,
reference_image_4=reference_image_4,
reference_image_5=reference_image_5,
image_references=image_references,
)
else:
from .reference_runtime import ReferenceInputSet, ReferenceRoutingRequest
reference_assets = None
reference_routing_request = ReferenceRoutingRequest(
selectors_by_slot=dict(_reference_routing_settings),
inputs=ReferenceInputSet.from_inputs(
reference_image_1=reference_image_1,
reference_image_2=reference_image_2,
reference_image_3=reference_image_3,
reference_image_4=reference_image_4,
reference_image_5=reference_image_5,
image_references=image_references,
output_width=int(width),
output_height=int(height),
size_mode=reference_size,
),
)
reference_audio_source, resolved_reference_audio_vae = resolve_reference_audio_input(
reference_audio_1,
reference_audio_vae,
audio_references,
)
def mark_runtime_start(assembly_plan):
marked = dict(assembly_plan)
marked["_runtime_started_at"] = runtime_started_at
return marked
def append_reference_plan(report, assembly_plan):
if reference_routing_request is None:
return str(report)
from .reference_plan_inspector import format_reference_plan
plan_view = assembly_plan.get("reference_routing_v1")
if not isinstance(plan_view, dict):
raise RuntimeError("Reference Routing output has no verified Plan")
return str(report).rstrip() + "\n" + format_reference_plan(plan_view)
def execute():
return super(H3ContinuumSamplerProduction, self).run(
model=model,
clip=clip,
video_vae=video_vae,
sampler=sampler,
sigmas=sigmas,
sequence_prompt=sequence_prompt,
prompt_mode=prompt_mode,
chunks=chunks,
chunk_seconds=chunk_seconds,
width=width,
height=height,
continuity=continuity,
base_seed=base_seed,
first_frame=first_frame,
prompt_overrides=prompt_overrides,
reference_assets=reference_assets,
reference_audio_source=reference_audio_source,
reference_audio_vae=resolved_reference_audio_vae,
driving_audio_source=driving_audio_source,
driving_audio_vae=driving_audio_vae,
reference_video_source=reference_video_source,
timeline_video_source=timeline_video_source,
guide_source=guide_source,
capture_refine_context=bool(capture_refine_context),
memory_attribution=bool(memory_attribution),
prompt_conditioning_cache=bool(prompt_conditioning_cache),
reference_encode_cache=bool(reference_encode_cache),
reference_routing_request=reference_routing_request,
continuation_transport=str(continuation_transport),
max_new_physical_groups=max_new_physical_groups,
advanced={
"audio_continuity": bool(audio_continuity),
"diagnostics": diagnostics,
"reroll_from_chunk": regenerate_from,
"reroll_nonce": int(reroll_nonce),
"strict_compatibility": False,
"debug": bool(debug),
"show_preview": bool(show_preview),
"last_frame": last_frame,
"_diagnostic_continuation_policy": _diagnostic_continuation_policy,
},
)
if run_storage == "Off":
if take_requested:
raise ValueError(
"Use This Take / Continue From Here requires Run Storage = Save + Auto Resume."
)
if review_requested:
from .review_control import GENERATION_MODE_REVIEW
if generation_mode == GENERATION_MODE_REVIEW:
raise ValueError(
"Review Each Chunk requires Run Storage = Save + Auto Resume."
)
_validate_regenerate_storage(run_storage, regenerate_from)
execute_outputs = execute()
if bool(capture_refine_context):
video_latents, audio_latents, assembly_plan, result, refine_context = execute_outputs
else:
video_latents, audio_latents, assembly_plan, result = execute_outputs
outputs = (
video_latents,
audio_latents,
mark_runtime_start(assembly_plan),
append_reference_plan(result["report"], assembly_plan),
)
if bool(capture_refine_context):
return (*outputs, refine_context)
return outputs
if run_storage != "Save + Auto Resume":
raise ValueError(f"unknown Run Storage mode: {run_storage!r}")
from ..run_storage import (
automatic_project_key,
resolve_run_storage_name,
run_storage_scope,
)
storage_name = resolve_run_storage_name(
project_id=project_id,
legacy_run_name=run_name,
automatic_key=automatic_project_key(prompt, unique_id),
)
with run_storage_scope(
storage_name, prompt=prompt, unique_id=unique_id
) as storage:
if review_requested:
storage.configure_review(
generation_mode=str(generation_mode),
review_action=str(review_action),
manual_regenerate_from=regenerate_from,
take_group=int(take_group),
take_revision_id=str(take_revision_id),
take_action=str(take_action),
)
execute_outputs = execute()
execute_outputs = _apply_review_decode_scope(
execute_outputs,
storage=storage,
capture_refine_context=bool(capture_refine_context),
configured_chunks=int(chunks),
chunk_seconds=float(chunk_seconds),
first_frame=first_frame,
last_frame=last_frame,
timeline_video_source=timeline_video_source,
)
if bool(capture_refine_context):
video_latents, audio_latents, assembly_plan, result, refine_context = execute_outputs
else:
video_latents, audio_latents, assembly_plan, result = execute_outputs
result = dict(result)
report = append_reference_plan(result["report"], assembly_plan) + "\n" + storage.summary(
detailed=diagnostics == DIAGNOSTICS_FULL
)
warning = _partial_review_warning(
storage,
capture_refine_context=bool(capture_refine_context),
)
if warning:
report += "\n" + warning
result["report"] = report
storage.finalize(
session=result["session"],
report=report,
review_pause_metadata=storage.review_pause_metadata(),
)
review_status = _format_review_status(
storage,
detailed=diagnostics == DIAGNOSTICS_FULL,
)
if review_status:
report += "\n" + review_status
result["report"] = report
outputs = (
video_latents,
audio_latents,
mark_runtime_start(assembly_plan),
report,
)
if bool(capture_refine_context):
return (*outputs, refine_context)
return outputs
class H3ContinuumSamplerTimelineVideo(H3ContinuumSamplerProduction):
"""V3.3 sampler with optional chunk-local Timeline Video conditioning."""
DEPRECATED = False
CATEGORY = CATEGORY
DESCRIPTION = (
"Timeline Video sampler. It slices one Core VIDEO per chunk, "
"resizes only that slice, and reuses the stable Continuum sampling engine."
)
SEARCH_ALIASES = [
"H3 Continuum Timeline Video",
"MiniMax H3 video reference timeline",
]
@classmethod
def INPUT_TYPES(cls):
schema = super().INPUT_TYPES()
required = {}
for name, definition in schema["required"].items():
required[name] = definition
if name == "reference_size":
required["timeline_video_size"] = (
TIMELINE_VIDEO_SIZE_OPTIONS,
{
"default": TIMELINE_VIDEO_SIZE_OPTIONS[0],
"display_name": "Timeline Video Size",
"advanced": True,
"tooltip": (
"Efficient limits each chunk-local reference slice to about 0.4 MP. "
"Match Output uses the output pixel area and may be substantially heavier."
),
},
)
schema["required"] = required
optional = dict(schema.get("optional", {}))
optional["timeline_video"] = (
"VIDEO",
{
"tooltip": (
"Optional. One continuous Core VIDEO covering every configured chunk. "
"When omitted or bypassed, the node uses the standard conditioning path. "
"Its audio is ignored; use the normal audio inputs for generated audio."
)
},
)
schema["optional"] = optional
return schema
def run(
self,
timeline_video=None,
timeline_video_size=TIMELINE_VIDEO_SIZE_OPTIONS[0],
**kwargs,
):
if timeline_video is None:
return super().run(**kwargs)
from ..timeline_video import prepare_timeline_video_source
source = prepare_timeline_video_source(
timeline_video,
chunks=int(kwargs["chunks"]),
chunk_seconds=float(kwargs["chunk_seconds"]),
output_width=int(kwargs["width"]),
output_height=int(kwargs["height"]),
size_mode=str(timeline_video_size),
)
return super().run(timeline_video_source=source, **kwargs)
NODE_CLASS_MAPPINGS = {
"H3ContinuumSamplerProduction": H3ContinuumSamplerProduction,
"H3ContinuumSamplerTimelineVideo": H3ContinuumSamplerTimelineVideo,
"H3ContinuumSamplerV3": H3ContinuumSamplerV3,
"H3ContinuumAdvancedV3": H3ContinuumAdvancedV3,
"H3ContinuumAssembleV3": H3ContinuumAssembleV3,
"H3ContinuumAssembleSeamExperimental": H3ContinuumAssembleSeamExperimental,
}
NODE_DISPLAY_NAME_MAPPINGS = {
"H3ContinuumSamplerProduction": "H3 Continuum Sampler V3.2.4",
"H3ContinuumSamplerTimelineVideo": "H3 Continuum Sampler V3.3",
"H3ContinuumSamplerV3": "H3 Continuum Sampler V3",
"H3ContinuumAdvancedV3": "H3 Continuum Advanced V3",
"H3ContinuumAssembleV3": "H3 Continuum Assemble V3.2.4",
"H3ContinuumAssembleSeamExperimental": "H3 Continuum Assemble + Seam",
}