Release V3.5.1 conditioning bridge and reference audio

This commit is contained in:
ukr8b3g-cmyk
2026-08-25 00:04:59 +09:00
parent ee7b9937dc
commit b555579a17
36 changed files with 5024 additions and 138 deletions
+135
View File
@@ -0,0 +1,135 @@
"""V3.5 Advanced bridge from Continuum refine context to Core conditioning."""
from __future__ import annotations
from typing import Any
from .second_pass import prepare_physical_refine_groups
from .second_pass_nodes import _single_list_input
class H3ContinuumConditioningBridgeV35:
"""Publish paired physical-group MODEL and CONDITIONING values."""
DEPRECATED = False
DESCRIPTION = (
"Advanced interoperability bridge for Basic Guider and external samplers. "
"It adapts the captured Continuum refine context to externally processed "
"physical-group video latents, then returns one paired MODEL and complete "
"CONDITIONING per physical group plus the target-geometry Assembly Plan. "
"Nested AV LATENT construction, Audio LATENT, Noise, Audio Lock, and external "
"sampling behavior remain the workflow's responsibility."
)
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"model": ("MODEL",),
"clip": ("CLIP",),
"video_latents": ("LATENT",),
"assembly_plan": ("H3_CONTINUUM_ASSEMBLY_PLAN",),
"refine_context": ("H3_CONTINUUM_REFINE_CONTEXT",),
},
"optional": {
"video_vae": (
"VAE",
{
"tooltip": (
"When available, First/Last keyframes are re-encoded at "
"the target geometry. Otherwise the existing conditioning "
"adapter uses its documented latent-resize fallback."
)
},
),
},
}
INPUT_IS_LIST = True
RETURN_TYPES = (
"MODEL",
"CONDITIONING",
"H3_CONTINUUM_ASSEMBLY_PLAN",
"STRING",
)
RETURN_NAMES = (
"group_models",
"conditioning",
"updated_assembly_plan",
"status",
)
OUTPUT_IS_LIST = (True, True, False, False)
FUNCTION = "prepare"
CATEGORY = "MiniMax H3/Continuum/Advanced"
def prepare(
self,
model,
clip,
video_latents,
assembly_plan,
refine_context,
video_vae=None,
):
prepared = prepare_physical_refine_groups(
model=_single_list_input("model", model),
clip=_single_list_input("clip", clip),
video_latents=video_latents,
assembly_plan=_single_list_input("assembly_plan", assembly_plan),
refine_context=_single_list_input("refine_context", refine_context),
video_vae=(
None
if video_vae is None
else _single_list_input("video_vae", video_vae)
),
)
group_models = prepared["group_models"]
conditioning = prepared["conditioning"]
physical_group_count = int(prepared["physical_group_count"])
if not len(group_models) == len(conditioning) == physical_group_count:
raise ValueError(
"Conditioning Bridge MODEL/CONDITIONING physical group counts differ"
)
status_lines = [
"H3 Continuum Conditioning Bridge V3.5",
f"Physical groups: {physical_group_count}.",
"Output contract: one paired MODEL and one complete CONDITIONING per "
"physical group; CONDITIONING entries remain grouped.",
"Scope: Advanced MODEL + CONDITIONING interoperability only; AV LATENT, "
"Noise, and Audio Lock are controlled by the external workflow.",
*prepared["warnings"],
]
for detail in prepared["details"]:
group = detail["group"]
status_lines.append(
"group "
f"{int(detail['group_index']) + 1}: "
f"logical_chunks={group.get('logical_chunks')}, "
f"prompt_policy={group.get('prompt_policy', 'unknown')}, "
f"conditioning_source={detail['conditioning_source']}, "
f"physical_clip_index={detail['physical_clip_index']}, "
f"context_frames={detail['context_frames']}"
)
status_lines.append(
"Target geometry: "
f"{prepared['updated_assembly_plan']['width']}x"
f"{prepared['updated_assembly_plan']['height']}."
)
return (
group_models,
conditioning,
prepared["updated_assembly_plan"],
"\n".join(status_lines),
)
NODE_CLASS_MAPPINGS = {
"H3ContinuumConditioningBridgeV35": H3ContinuumConditioningBridgeV35,
}
NODE_DISPLAY_NAME_MAPPINGS = {
"H3ContinuumConditioningBridgeV35": (
"H3 Continuum Conditioning Bridge V3.5"
),
}
+42 -7
View File
@@ -101,9 +101,9 @@ class H3ContinuumSamplerV34(H3ContinuumSamplerProduction):
REFERENCE_VIDEO_SIZE_OPTIONS,
{
"default": REFERENCE_VIDEO_SIZE_EFFICIENT,
"display_name": "Video Reference Size",
"display_name": "Video Guide Size",
"tooltip": (
"Efficient limits Video Reference to about 0.4 MP; Balanced uses "
"Efficient limits Video Guide Frames to about 0.4 MP; Balanced uses "
"about 0.6 MP; Match Output uses the output pixel area. Source "
"aspect ratio is preserved and smaller sources are not enlarged."
),
@@ -115,16 +115,20 @@ class H3ContinuumSamplerV34(H3ContinuumSamplerProduction):
optional["reference_video_1"] = (
"IMAGE",
{
"display_name": "Video Reference",
"display_name": "Video Guide Frames",
"tooltip": (
"Optional persistent video reference. Connect an IMAGE frame batch; "
"frames are interpreted at 24 fps and applied to every chunk."
"Optional video guide. Connect the IMAGE frame batch from a video loader; "
"source-video audio is not included. Frames are interpreted at 24 fps "
"and applied to every chunk. Non-native frame counts are padded by "
"repeating the final frame to the next H3 17k+5 count, up to the "
"one-chunk limit."
),
},
)
optional["driving_audio"] = (
"AUDIO",
{
"display_name": "Driving Audio",
"tooltip": (
"Optional original audio timeline. It is used as native H3 guide "
"conditioning and selected unchanged for final output."
@@ -134,6 +138,7 @@ class H3ContinuumSamplerV34(H3ContinuumSamplerProduction):
optional["audio_vae"] = (
"VAE",
{
"display_name": "Driving Audio VAE",
"tooltip": (
"Required only when Driving Audio is connected. Uses the same "
"Audio VAE encode path as ComfyUI Core MiniMax H3 Add Guide."
@@ -151,6 +156,8 @@ class H3ContinuumSamplerV34(H3ContinuumSamplerProduction):
reference_video_1=None,
video_reference_size=REFERENCE_VIDEO_SIZE_EFFICIENT,
capture_refine_context=False,
reference_audio_1=None,
reference_audio_vae=None,
**kwargs,
):
from ..reference_video import prepare_reference_video_source
@@ -175,8 +182,8 @@ class H3ContinuumSamplerV34(H3ContinuumSamplerProduction):
size_mode=str(video_reference_size),
)
outputs = super().run(
reference_audio_1=None,
reference_audio_vae=None,
reference_audio_1=reference_audio_1,
reference_audio_vae=reference_audio_vae,
driving_audio_source=source,
driving_audio_vae=audio_vae,
reference_video_source=reference_video_source,
@@ -217,6 +224,34 @@ class H3ContinuumSamplerV35(H3ContinuumSamplerV34):
)
OUTPUT_IS_LIST = (*H3ContinuumSamplerV34.OUTPUT_IS_LIST, False)
@classmethod
def INPUT_TYPES(cls):
schema = super().INPUT_TYPES()
optional = dict(schema.get("optional", {}))
optional["reference_audio_1"] = (
"AUDIO",
{
"display_name": "Reference Audio (Optional)",
"tooltip": (
"Optional standalone audio reference for H3 conditioning. "
"It is not the audio track of Video Guide Frames. Unlike Driving "
"Audio, it does not replace the generated final audio."
),
},
)
optional["reference_audio_vae"] = (
"VAE",
{
"display_name": "Reference Audio VAE (Optional)",
"tooltip": (
"Required only when Reference Audio is connected. It encodes the "
"reference for H3 conditioning; generated audio remains the output."
),
},
)
schema["optional"] = optional
return schema
def run(self, *args, **kwargs):
kwargs.pop("capture_refine_context", None)
kwargs.pop("memory_attribution", None)
+70 -8
View File
@@ -67,6 +67,65 @@ def h3_core_native_canvas(
return target_width, target_height
def align_h3_manual_canvas(
current_latent_width: int,
current_latent_height: int,
scale_by: float,
*,
pixel_scale_width: int,
pixel_scale_height: int,
canvas_multiple: int | None = None,
) -> dict[str, int]:
"""Scale and align a manual target to ComfyUI Core's H3 canvas grid."""
if canvas_multiple is None:
from comfy_extras.nodes_minimax_h3 import CANVAS_MULTIPLE
canvas_multiple = int(CANVAS_MULTIPLE)
current_latent_width = int(current_latent_width)
current_latent_height = int(current_latent_height)
pixel_scale_width = int(pixel_scale_width)
pixel_scale_height = int(pixel_scale_height)
canvas_multiple = int(canvas_multiple)
scale_by = float(scale_by)
if min(
current_latent_width,
current_latent_height,
pixel_scale_width,
pixel_scale_height,
canvas_multiple,
) < 1:
raise SecondPassContractError("manual H3 canvas geometry is invalid")
if (
canvas_multiple % pixel_scale_width
or canvas_multiple % pixel_scale_height
):
raise SecondPassContractError(
"ComfyUI Core H3 canvas multiple is not aligned to the latent scale"
)
def aligned_target(current_latent: int, pixel_scale: int) -> int:
current_pixels = current_latent * pixel_scale
scaled_pixels = current_pixels * scale_by
nearest_core_canvas = max(
canvas_multiple,
round(scaled_pixels / canvas_multiple) * canvas_multiple,
)
preserved_core_canvas = (
(current_pixels + canvas_multiple - 1) // canvas_multiple
) * canvas_multiple
return max(nearest_core_canvas, preserved_core_canvas)
target_width = aligned_target(current_latent_width, pixel_scale_width)
target_height = aligned_target(current_latent_height, pixel_scale_height)
return {
"target_width": target_width,
"target_height": target_height,
"target_latent_width": target_width // pixel_scale_width,
"target_latent_height": target_height // pixel_scale_height,
}
def resolve_h3_native_latent_target(
video_latents: Sequence[Mapping[str, Any]],
assembly_plan: Mapping[str, Any],
@@ -393,14 +452,17 @@ class H3ContinuumHiResFixV35:
resize_mode = "h3_native_canvas_auto"
else:
pixel_scale_width, pixel_scale_height = resolve_pixel_latent_scale(plan)
target_latent_width = round(current_geometry[1] * scale)
target_latent_height = round(current_geometry[0] * scale)
if target_latent_width < 1 or target_latent_height < 1:
raise SecondPassContractError(
"scale_by produced a non-positive target geometry"
)
target_width = target_latent_width * pixel_scale_width
target_height = target_latent_height * pixel_scale_height
manual_target = align_h3_manual_canvas(
current_geometry[1],
current_geometry[0],
scale,
pixel_scale_width=pixel_scale_width,
pixel_scale_height=pixel_scale_height,
)
target_latent_width = int(manual_target["target_latent_width"])
target_latent_height = int(manual_target["target_latent_height"])
target_width = int(manual_target["target_width"])
target_height = int(manual_target["target_height"])
resize_mode = "manual_scale_by"
if current_geometry == (target_latent_height, target_latent_width):
+162 -45
View File
@@ -168,36 +168,35 @@ def update_second_pass_geometry(
return updated
def run_second_pass_groups(
def prepare_physical_refine_groups(
*,
model: Any,
clip: Any,
sampler: Any,
sigmas: torch.Tensor,
video_latents: Sequence[Any],
audio_latents: Sequence[Any],
assembly_plan: Mapping[str, Any],
refine_seed: int,
refine_context: Any = None,
video_vae: Any = None,
conditioning_upscale_method: str = "bilinear",
enable_preview: bool = True,
encode_prompt_fn=None,
latent_builder=None,
sample_fn=None,
stream_extractor=None,
clone_model_fn=None,
validate_refine_context_fn=None,
adapt_group_conditioning_fn=None,
) -> tuple[list[dict[str, Any]], list[Any], dict[str, Any], str]:
"""Refine complete physical groups while preserving first-pass audio exactly."""
group_consumer_fn=None,
retain_group_outputs: bool = True,
) -> dict[str, Any]:
"""Prepare one MODEL and one complete CONDITIONING per physical group.
validation = validate_second_pass_inputs(video_latents, audio_latents, assembly_plan)
groups = _contract_groups(assembly_plan)
This is the shared, sampling-independent contract used by the built-in
Second Pass and the public Advanced Conditioning Bridge. The returned
``conditioning`` value is an outer physical-group list; every item inside
it remains one complete ComfyUI CONDITIONING object.
"""
groups, (target_h, target_w) = _validate_video_groups(
video_latents,
assembly_plan,
)
encode_prompt_fn = encode_prompt_fn or encode_prompt_conditioning
latent_builder = latent_builder or latent_from_cpu
sample_fn = sample_fn or sample_refine_chunk
stream_extractor = stream_extractor or extract_av_streams
clone_model_fn = clone_model_fn or clone_model_for_chunk
validate_refine_context_fn = validate_refine_context_fn or validate_refine_context
adapt_group_conditioning_fn = (
@@ -205,9 +204,9 @@ def run_second_pass_groups(
)
captured_groups: Sequence[Mapping[str, Any]] | None = None
context_warnings: list[str] = []
warnings: list[str] = []
if refine_context is None:
context_warnings.append(
warnings.append(
"WARNING: refine_context is not connected; using legacy prompt-only "
"conditioning."
)
@@ -226,7 +225,7 @@ def run_second_pass_groups(
raise SecondPassContractError(
f"refine_context contract is invalid: {exc}"
) from exc
context_warnings.append(
warnings.append(
"WARNING: optional refine_context was not a typed Continuum context; "
f"using legacy prompt-only conditioning ({exc})."
)
@@ -234,29 +233,15 @@ def run_second_pass_groups(
if bool(validated_context.get("complete")):
captured_groups = validated_context["groups"]
else:
context_warnings.append(
warnings.append(
"WARNING: refine_context capture is incomplete; using legacy "
"prompt-only conditioning."
)
refined_videos: list[dict[str, Any]] = []
group_seeds: list[int] = []
conditioning_sources: list[str] = []
report_lines = [
"H3 Continuum Second Pass V3.5",
"Mode: context-aware physical-group refine when a complete First Pass "
"refine_context is available.",
f"Physical groups: {validation['physical_group_count']}.",
"Sampling contract: video random noise/mask=1; audio zero noise/mask=0; "
"workflow SIGMAS are applied directly by Core.",
*context_warnings,
]
for group_index, (video_latent, audio_latent, group) in enumerate(
zip(video_latents, audio_latents, groups, strict=True)
):
video_samples = _latent_samples(video_latent, name=f"video_latents[{group_index}]")
audio_samples = _latent_samples(audio_latent, name=f"audio_latents[{group_index}]")
group_models: list[Any] = []
group_conditioning: list[list[Any]] = []
details: list[dict[str, Any]] = []
for group_index, group in enumerate(groups):
captured_group = (
captured_groups[group_index] if captured_groups is not None else None
)
@@ -267,15 +252,15 @@ def run_second_pass_groups(
try:
conditioning, adaptation_stats = adapt_group_conditioning_fn(
captured_group,
target_latent_h=validation["target_latent_h"],
target_latent_w=validation["target_latent_w"],
target_latent_h=target_h,
target_latent_w=target_w,
video_vae=video_vae,
upscale_method=str(conditioning_upscale_method),
)
conditioning_source = "refine_context"
context_conditioning_available = True
except RefineConditioningAdaptationError as exc:
report_lines.append(
warnings.append(
f"WARNING: group {group_index + 1} refine_context target "
f"adaptation was unavailable; using legacy prompt-only "
f"conditioning ({exc})."
@@ -296,6 +281,11 @@ def run_second_pass_groups(
timeline_video_assets=None,
)
conditioning_source = "prompt_only_fallback"
if not isinstance(conditioning, list):
raise SecondPassContractError(
f"physical group {group_index} conditioning is not a complete "
"ComfyUI CONDITIONING object"
)
logical_chunks = model_group.get("logical_chunks")
if not isinstance(logical_chunks, Sequence) or not logical_chunks:
@@ -324,6 +314,107 @@ def run_second_pass_groups(
chunk_index=physical_clip_index,
context_frames=context_frames if context_frames > 0 else None,
)
detail = {
"group_index": group_index,
"group": group,
"conditioning_source": conditioning_source,
"adaptation_stats": adaptation_stats,
"physical_clip_index": physical_clip_index,
"context_frames": context_frames,
}
if group_consumer_fn is not None:
group_consumer_fn(
group_index,
video_latents[group_index],
group,
chunk_model,
conditioning,
detail,
)
if retain_group_outputs:
group_models.append(chunk_model)
# Append, never extend: CONDITIONING's internal entries belong together.
group_conditioning.append(conditioning)
details.append(detail)
physical_group_count = len(groups)
if retain_group_outputs and not (
len(group_models)
== len(group_conditioning)
== len(details)
== physical_group_count
):
raise SecondPassContractError(
"prepared MODEL/CONDITIONING physical group counts differ"
)
if not retain_group_outputs and group_consumer_fn is None:
raise SecondPassContractError(
"non-retained physical group preparation requires a consumer"
)
return {
"group_models": group_models,
"conditioning": group_conditioning,
"updated_assembly_plan": update_second_pass_geometry(
assembly_plan,
video_latents,
),
"details": details,
"warnings": warnings,
"physical_group_count": physical_group_count,
"target_latent_h": target_h,
"target_latent_w": target_w,
}
def run_second_pass_groups(
*,
model: Any,
clip: Any,
sampler: Any,
sigmas: torch.Tensor,
video_latents: Sequence[Any],
audio_latents: Sequence[Any],
assembly_plan: Mapping[str, Any],
refine_seed: int,
refine_context: Any = None,
video_vae: Any = None,
conditioning_upscale_method: str = "bilinear",
enable_preview: bool = True,
encode_prompt_fn=None,
latent_builder=None,
sample_fn=None,
stream_extractor=None,
clone_model_fn=None,
validate_refine_context_fn=None,
adapt_group_conditioning_fn=None,
) -> tuple[list[dict[str, Any]], list[Any], dict[str, Any], str]:
"""Refine complete physical groups while preserving first-pass audio exactly."""
validation = validate_second_pass_inputs(video_latents, audio_latents, assembly_plan)
groups = _contract_groups(assembly_plan)
latent_builder = latent_builder or latent_from_cpu
sample_fn = sample_fn or sample_refine_chunk
stream_extractor = stream_extractor or extract_av_streams
refined_videos: list[dict[str, Any]] = []
group_seeds: list[int] = []
conditioning_sources: list[str] = []
group_report_lines: list[str] = []
def sample_prepared_group(
group_index,
video_latent,
group,
chunk_model,
conditioning,
detail,
):
audio_latent = audio_latents[group_index]
video_samples = _latent_samples(video_latent, name=f"video_latents[{group_index}]")
audio_samples = _latent_samples(audio_latent, name=f"audio_latents[{group_index}]")
conditioning_source = str(detail["conditioning_source"])
adaptation_stats = detail["adaptation_stats"]
physical_clip_index = int(detail["physical_clip_index"])
context_frames = int(detail["context_frames"])
physical_seed = derive_refine_seed(int(refine_seed), group_index)
group_seeds.append(physical_seed)
conditioning_sources.append(conditioning_source)
@@ -349,7 +440,7 @@ def run_second_pass_groups(
output_latent = dict(video_latent)
output_latent["samples"] = refined_video
refined_videos.append(output_latent)
report_lines.append(
group_report_lines.append(
"group "
f"{group_index + 1}: logical_chunks={group.get('logical_chunks')}, "
f"prompt_policy={group.get('prompt_policy', 'unknown')}, "
@@ -360,20 +451,46 @@ def run_second_pass_groups(
"sampling_passes=1, temporary_audio_discarded=true"
)
if adaptation_stats is not None:
report_lines.append(
group_report_lines.append(
"group "
f"{group_index + 1} target conditioning: "
f"keyframes_resized={int(adaptation_stats.get('keyframes_resized', 0))}, "
f"keyframes_reencoded={int(adaptation_stats.get('keyframes_reencoded', 0))}, "
f"context_refs_resized={int(adaptation_stats.get('context_refs_resized', 0))}"
)
report_lines.extend(
group_report_lines.extend(
f"WARNING: {warning}"
for warning in adaptation_stats.get("warnings", ())
)
prepared = prepare_physical_refine_groups(
model=model,
clip=clip,
video_latents=video_latents,
assembly_plan=assembly_plan,
refine_context=refine_context,
video_vae=video_vae,
conditioning_upscale_method=conditioning_upscale_method,
encode_prompt_fn=encode_prompt_fn,
clone_model_fn=clone_model_fn,
validate_refine_context_fn=validate_refine_context_fn,
adapt_group_conditioning_fn=adapt_group_conditioning_fn,
group_consumer_fn=sample_prepared_group,
retain_group_outputs=False,
)
report_lines = [
"H3 Continuum Second Pass V3.5",
"Mode: context-aware physical-group refine when a complete First Pass "
"refine_context is available.",
f"Physical groups: {validation['physical_group_count']}.",
"Sampling contract: video random noise/mask=1; audio zero noise/mask=0; "
"workflow SIGMAS are applied directly by Core.",
*prepared["warnings"],
*group_report_lines,
]
passthrough_audio = passthrough_audio_latents(audio_latents)
updated_plan = update_second_pass_geometry(assembly_plan, refined_videos)
updated_plan = prepared["updated_assembly_plan"]
contract = updated_plan["second_pass_contract"]
if conditioning_sources and all(
source == "refine_context" for source in conditioning_sources