Release V3.8 source, illustrated manual and Spectrum workflow
This commit is contained in:
@@ -0,0 +1,320 @@
|
||||
"""Read-only Adaptive Continuity observation and decision trace for A8a.
|
||||
|
||||
The observer records the continuation contract that Production already chose.
|
||||
It never changes context depth, transport, masks, tensors, conditioning, MODEL,
|
||||
Seed, SIGMAS, physical grouping, or execution policy.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
import math
|
||||
from typing import Any
|
||||
|
||||
|
||||
ADAPTIVE_CONTINUITY_OBSERVER_VERSION = 1
|
||||
EXECUTION_APPLIED = False
|
||||
|
||||
INITIAL_TRANSPORT = "initial"
|
||||
REFERENCE_CONTEXT_V1 = "reference_context_v1"
|
||||
MASKED_VIDEO_PREFIX_V1 = "masked_video_prefix_v1"
|
||||
MASKED_AV_PREFIX_22_V1 = "masked_av_prefix_22_v1"
|
||||
MASKED_AV_PREFIX_39_V1 = "masked_av_prefix_39_v1"
|
||||
|
||||
_KNOWN_TRANSPORTS = frozenset(
|
||||
(
|
||||
INITIAL_TRANSPORT,
|
||||
REFERENCE_CONTEXT_V1,
|
||||
MASKED_VIDEO_PREFIX_V1,
|
||||
MASKED_AV_PREFIX_22_V1,
|
||||
MASKED_AV_PREFIX_39_V1,
|
||||
)
|
||||
)
|
||||
_VALID_CONTEXT_FRAMES = frozenset((0, 5, 22, 39))
|
||||
_PLANNER_CONTRACT = {
|
||||
"planner_version": ADAPTIVE_CONTINUITY_OBSERVER_VERSION,
|
||||
"mode": "read_only_observer",
|
||||
"execution_applied": EXECUTION_APPLIED,
|
||||
"confidence_scope": "observation_completeness_not_mitigation_efficacy",
|
||||
"issue_13_mitigation_claim": False,
|
||||
"mutations": [],
|
||||
"observed_fields": [
|
||||
"motion_score",
|
||||
"current_context_frames",
|
||||
"resolved_transport",
|
||||
"terminal_atomic",
|
||||
"boundary_index",
|
||||
"boundary_count",
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
def _canonical_hash(value: Any) -> str:
|
||||
payload = json.dumps(
|
||||
value,
|
||||
sort_keys=True,
|
||||
separators=(",", ":"),
|
||||
ensure_ascii=True,
|
||||
).encode("utf-8")
|
||||
return hashlib.sha256(payload).hexdigest()
|
||||
|
||||
|
||||
ADAPTIVE_CONTINUITY_PLANNER_HASH = _canonical_hash(_PLANNER_CONTRACT)
|
||||
|
||||
|
||||
class AdaptiveContinuityObservationError(ValueError):
|
||||
"""One diagnostic observation is malformed or internally inconsistent."""
|
||||
|
||||
|
||||
def _recommendation(
|
||||
*,
|
||||
current_context_frames: int,
|
||||
resolved_transport: str,
|
||||
terminal_atomic: bool,
|
||||
) -> str:
|
||||
if int(current_context_frames) == 0:
|
||||
return "no_continuation_action_initial_group"
|
||||
if bool(terminal_atomic):
|
||||
return "keep_fixed_terminal_merge_contract"
|
||||
if str(resolved_transport) == REFERENCE_CONTEXT_V1:
|
||||
return "keep_current_reference_context_contract"
|
||||
return "keep_current_masked_prefix_contract"
|
||||
|
||||
|
||||
def make_adaptive_continuity_decision(
|
||||
*,
|
||||
physical_group: int,
|
||||
logical_chunks: tuple[int, ...],
|
||||
observed_motion_score: float,
|
||||
current_context_frames: int,
|
||||
resolved_transport: str,
|
||||
terminal_atomic: bool,
|
||||
boundary_index: int,
|
||||
boundary_count: int,
|
||||
reason: str,
|
||||
fallback_reason: str | None = None,
|
||||
reused: bool = False,
|
||||
) -> dict[str, Any]:
|
||||
"""Build one immutable, JSON-safe observation without retaining tensors."""
|
||||
|
||||
group = int(physical_group)
|
||||
logical = tuple(int(value) for value in logical_chunks)
|
||||
context = int(current_context_frames)
|
||||
boundary = int(boundary_index)
|
||||
boundaries = int(boundary_count)
|
||||
transport = str(resolved_transport)
|
||||
motion = float(observed_motion_score)
|
||||
reason_text = str(reason).strip()
|
||||
|
||||
if group < 1 or not logical or any(value < 1 for value in logical):
|
||||
raise AdaptiveContinuityObservationError(
|
||||
"physical group and logical chunks must be positive"
|
||||
)
|
||||
if tuple(sorted(set(logical))) != logical:
|
||||
raise AdaptiveContinuityObservationError(
|
||||
"logical chunks must be ordered and unique"
|
||||
)
|
||||
if context not in _VALID_CONTEXT_FRAMES:
|
||||
raise AdaptiveContinuityObservationError(
|
||||
f"unsupported observed context frame count: {context}"
|
||||
)
|
||||
if transport not in _KNOWN_TRANSPORTS:
|
||||
raise AdaptiveContinuityObservationError(
|
||||
f"unknown resolved continuation transport: {transport!r}"
|
||||
)
|
||||
if context == 0 and transport != INITIAL_TRANSPORT:
|
||||
raise AdaptiveContinuityObservationError(
|
||||
"zero-context observations must use the initial transport marker"
|
||||
)
|
||||
if context > 0 and transport == INITIAL_TRANSPORT:
|
||||
raise AdaptiveContinuityObservationError(
|
||||
"continuation observations require a resolved transport"
|
||||
)
|
||||
if boundary < 0 or boundaries < 0 or boundary > boundaries:
|
||||
raise AdaptiveContinuityObservationError(
|
||||
"boundary index/count are inconsistent"
|
||||
)
|
||||
if not math.isfinite(motion) or motion < 0.0:
|
||||
raise AdaptiveContinuityObservationError(
|
||||
"observed motion score must be finite and non-negative"
|
||||
)
|
||||
|
||||
confidence = 1.0 if reason_text else 0.5
|
||||
payload: dict[str, Any] = {
|
||||
"planner_version": ADAPTIVE_CONTINUITY_OBSERVER_VERSION,
|
||||
"planner_hash": ADAPTIVE_CONTINUITY_PLANNER_HASH,
|
||||
"physical_group": group,
|
||||
"logical_chunks": list(logical),
|
||||
"observed_motion_score": motion,
|
||||
"current_context_frames": context,
|
||||
"resolved_transport": transport,
|
||||
"terminal_atomic": bool(terminal_atomic),
|
||||
"boundary_index": boundary,
|
||||
"boundary_count": boundaries,
|
||||
"recommendation": _recommendation(
|
||||
current_context_frames=context,
|
||||
resolved_transport=transport,
|
||||
terminal_atomic=bool(terminal_atomic),
|
||||
),
|
||||
"confidence": confidence,
|
||||
"confidence_scope": "observation completeness only; not mitigation efficacy",
|
||||
"reason": reason_text or "selection reason unavailable",
|
||||
"fallback_reason": (
|
||||
str(fallback_reason).strip() if fallback_reason is not None else None
|
||||
),
|
||||
"reused": bool(reused),
|
||||
"execution_applied": EXECUTION_APPLIED,
|
||||
"issue_13_mitigation_claim": False,
|
||||
}
|
||||
payload["decision_hash"] = _canonical_hash(payload)
|
||||
return payload
|
||||
|
||||
|
||||
class AdaptiveContinuityObserver:
|
||||
"""Collect fail-soft A8a observations in deterministic physical-group order."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self._records: list[dict[str, Any]] = []
|
||||
self._advisories: list[str] = []
|
||||
|
||||
@property
|
||||
def records(self) -> tuple[dict[str, Any], ...]:
|
||||
return tuple(dict(record) for record in self._records)
|
||||
|
||||
def observe(self, **kwargs: Any) -> dict[str, Any]:
|
||||
record = make_adaptive_continuity_decision(**kwargs)
|
||||
self._records.append(record)
|
||||
return record
|
||||
|
||||
def note_observation_failure(self, exc: Exception) -> None:
|
||||
self._advisories.append(f"{type(exc).__name__}: {exc}")
|
||||
|
||||
def replay_prefix(
|
||||
self,
|
||||
*,
|
||||
entries: list[dict[str, Any]],
|
||||
total_chunks: int,
|
||||
terminal_merge_enabled: bool,
|
||||
resolved_transport: str,
|
||||
) -> None:
|
||||
"""Reconstruct trace-only records from accepted CPU chunk metadata."""
|
||||
|
||||
chunk_count = int(total_chunks)
|
||||
completed = len(entries)
|
||||
if chunk_count < 1 or completed > chunk_count:
|
||||
raise AdaptiveContinuityObservationError(
|
||||
"replayed prefix length is outside the configured sequence"
|
||||
)
|
||||
boundary_count = max(0, chunk_count - 1)
|
||||
normal_count = completed
|
||||
terminal_complete = False
|
||||
pair_start = max(0, chunk_count - 2)
|
||||
if bool(terminal_merge_enabled):
|
||||
if pair_start < completed < chunk_count:
|
||||
raise AdaptiveContinuityObservationError(
|
||||
"terminal merged prefix contains only one logical half"
|
||||
)
|
||||
terminal_complete = completed == chunk_count
|
||||
normal_count = pair_start if terminal_complete else completed
|
||||
|
||||
for index in range(normal_count):
|
||||
entry = entries[index]
|
||||
context = int(entry.get("context_frames", 0))
|
||||
self.observe(
|
||||
physical_group=index + 1,
|
||||
logical_chunks=(index + 1,),
|
||||
observed_motion_score=float(entry.get("motion_score", 0.0)),
|
||||
current_context_frames=context,
|
||||
resolved_transport=(
|
||||
INITIAL_TRANSPORT if context == 0 else str(resolved_transport)
|
||||
),
|
||||
terminal_atomic=False,
|
||||
boundary_index=index,
|
||||
boundary_count=boundary_count,
|
||||
reason="replayed from accepted chunk metadata",
|
||||
fallback_reason=None,
|
||||
reused=True,
|
||||
)
|
||||
|
||||
if terminal_complete:
|
||||
entry = entries[pair_start]
|
||||
context = int(entry.get("context_frames", 0))
|
||||
self.observe(
|
||||
physical_group=pair_start + 1,
|
||||
logical_chunks=(pair_start + 1, chunk_count),
|
||||
observed_motion_score=float(entry.get("motion_score", 0.0)),
|
||||
current_context_frames=context,
|
||||
resolved_transport=(
|
||||
INITIAL_TRANSPORT if context == 0 else str(resolved_transport)
|
||||
),
|
||||
terminal_atomic=True,
|
||||
boundary_index=pair_start,
|
||||
boundary_count=boundary_count,
|
||||
reason="replayed from accepted Terminal Merge metadata",
|
||||
fallback_reason=None,
|
||||
reused=True,
|
||||
)
|
||||
|
||||
def report_lines(self) -> list[str]:
|
||||
lines = [
|
||||
"Adaptive Continuity observer [A8a v1]: "
|
||||
f"planner_hash={ADAPTIVE_CONTINUITY_PLANNER_HASH}, "
|
||||
f"observed_groups={len(self._records)}, "
|
||||
"execution_applied=false; recommendation trace only, "
|
||||
"Issue #13 mitigation claim=none, Production continuity unchanged."
|
||||
]
|
||||
for record in self._records:
|
||||
lines.append(
|
||||
"Adaptive Continuity decision [A8a v1]: "
|
||||
f"physical_group={record['physical_group']}, "
|
||||
f"logical_chunks={record['logical_chunks']}, "
|
||||
f"boundary={record['boundary_index']}/{record['boundary_count']}, "
|
||||
f"motion={record['observed_motion_score']:.6f}, "
|
||||
f"context={record['current_context_frames']}, "
|
||||
f"transport={record['resolved_transport']}, "
|
||||
f"terminal_atomic={str(record['terminal_atomic']).lower()}, "
|
||||
f"reused={str(record['reused']).lower()}, "
|
||||
f"recommendation={record['recommendation']}, "
|
||||
f"confidence={record['confidence']:.2f}, "
|
||||
f"reason={record['reason']}, "
|
||||
f"fallback_reason={record['fallback_reason'] or 'none'}, "
|
||||
f"decision_hash={record['decision_hash']}, "
|
||||
"execution_applied=false."
|
||||
)
|
||||
lines.extend(
|
||||
f"Adaptive Continuity advisory [A8a v1]: {item}; execution_applied=false."
|
||||
for item in self._advisories
|
||||
)
|
||||
return lines
|
||||
|
||||
|
||||
def adaptive_observer_event_fail_soft(
|
||||
observer: Any,
|
||||
method: str,
|
||||
**kwargs: Any,
|
||||
) -> Any:
|
||||
"""Invoke one observer event without allowing diagnostics to stop Sampling."""
|
||||
|
||||
if observer is None:
|
||||
return None
|
||||
try:
|
||||
return getattr(observer, str(method))(**kwargs)
|
||||
except Exception as exc:
|
||||
try:
|
||||
observer.note_observation_failure(exc)
|
||||
except Exception:
|
||||
pass
|
||||
return None
|
||||
|
||||
|
||||
__all__ = [
|
||||
"ADAPTIVE_CONTINUITY_OBSERVER_VERSION",
|
||||
"ADAPTIVE_CONTINUITY_PLANNER_HASH",
|
||||
"AdaptiveContinuityObservationError",
|
||||
"AdaptiveContinuityObserver",
|
||||
"EXECUTION_APPLIED",
|
||||
"INITIAL_TRANSPORT",
|
||||
"adaptive_observer_event_fail_soft",
|
||||
"make_adaptive_continuity_decision",
|
||||
]
|
||||
+431
-431
@@ -1,431 +1,431 @@
|
||||
"""Decoded chunk assembly for latent-first H3 Continuum V3."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import math
|
||||
import time
|
||||
from typing import Any
|
||||
|
||||
import torch
|
||||
|
||||
from ..media import validate_audio
|
||||
from ..v2.decoder import _slice_audio_for_timeline, enforce_total_frames
|
||||
from ..constants import (
|
||||
DIAGNOSTICS_FULL,
|
||||
DIAGNOSTICS_OFF,
|
||||
DIAGNOSTICS_OPTIONS,
|
||||
normalize_diagnostics_mode,
|
||||
)
|
||||
from ..v2.seam_guard import correct_audio_seam
|
||||
from .plan import FPS, validate_assembly_plan
|
||||
|
||||
AUDIO_SEAM_OFF = "Off"
|
||||
AUDIO_SEAM_AUTO = "Auto"
|
||||
AUDIO_SEAM_OPTIONS = (AUDIO_SEAM_OFF, AUDIO_SEAM_AUTO)
|
||||
VIDEO_SEAM_OFF = "Off"
|
||||
VIDEO_SEAM_ANALYZE = "Analyze Only"
|
||||
VIDEO_SEAM_AUTO = "Auto"
|
||||
VIDEO_SEAM_AUTO_2 = "Auto 2"
|
||||
VIDEO_SEAM_ANALYSIS_OPTIONS = (
|
||||
VIDEO_SEAM_AUTO,
|
||||
VIDEO_SEAM_AUTO_2,
|
||||
VIDEO_SEAM_ANALYZE,
|
||||
VIDEO_SEAM_OFF,
|
||||
)
|
||||
|
||||
|
||||
def _singleton(value: Any, name: str) -> Any:
|
||||
while isinstance(value, list):
|
||||
if len(value) != 1:
|
||||
raise ValueError(f"{name} must contain exactly one value")
|
||||
value = value[0]
|
||||
return value
|
||||
|
||||
|
||||
def _chunk_list(value: Any) -> list[Any]:
|
||||
if isinstance(value, list):
|
||||
if len(value) == 1 and isinstance(value[0], list):
|
||||
return list(value[0])
|
||||
return list(value)
|
||||
return [value]
|
||||
|
||||
|
||||
def _format_elapsed(seconds: float) -> str:
|
||||
total = max(0.0, float(seconds))
|
||||
hours, remainder = divmod(total, 3600.0)
|
||||
minutes, seconds = divmod(remainder, 60.0)
|
||||
return f"{int(hours):02d}:{int(minutes):02d}:{seconds:05.2f}"
|
||||
|
||||
|
||||
def assemble_decoded_chunks(
|
||||
*,
|
||||
images: list[Any],
|
||||
audio: list[Any],
|
||||
assembly_plan: dict[str, Any],
|
||||
exact_total_duration: bool,
|
||||
audio_seam: str,
|
||||
diagnostics: str,
|
||||
):
|
||||
plan = validate_assembly_plan(assembly_plan)
|
||||
diagnostics_mode = normalize_diagnostics_mode(diagnostics)
|
||||
if audio_seam not in AUDIO_SEAM_OPTIONS:
|
||||
raise ValueError(f"unknown Audio Seam mode: {audio_seam!r}")
|
||||
|
||||
chunk_plans = list(
|
||||
plan["decode_groups"] if "decode_groups" in plan else plan["chunks"]
|
||||
)
|
||||
if len(images) != len(chunk_plans) or len(audio) != len(chunk_plans):
|
||||
raise ValueError(
|
||||
"decoded chunk count does not match the V3 assembly plan: "
|
||||
f"images={len(images)}, audio={len(audio)}, plan={len(chunk_plans)}"
|
||||
)
|
||||
|
||||
total_retained_frames = sum(int(item["net_frames"]) for item in chunk_plans)
|
||||
image_buffer = None
|
||||
audio_buffer = None
|
||||
audio_rate = None
|
||||
frame_cursor = 0
|
||||
reports = [
|
||||
"H3 Continuum Assemble V3",
|
||||
f"Audio Seam: {audio_seam}. Video seam correction is disabled.",
|
||||
]
|
||||
|
||||
for index, (raw_images, raw_audio, chunk) in enumerate(
|
||||
zip(images, audio, chunk_plans), start=1
|
||||
):
|
||||
if not torch.is_tensor(raw_images) or raw_images.ndim != 4:
|
||||
raise ValueError(f"decoded image chunk {index} must be [frames,H,W,C]")
|
||||
raw_images = raw_images.detach().to("cpu")
|
||||
total_frames = int(chunk["total_frames"])
|
||||
trim_frames = int(chunk["trim_frames"])
|
||||
net_frames = int(chunk["net_frames"])
|
||||
if int(raw_images.shape[0]) < total_frames:
|
||||
raise ValueError(
|
||||
f"decoded image chunk {index} has {raw_images.shape[0]} frames; "
|
||||
f"expected at least {total_frames}"
|
||||
)
|
||||
segment_images = raw_images[:total_frames][trim_frames:].contiguous()
|
||||
if int(segment_images.shape[0]) != net_frames:
|
||||
raise ValueError(
|
||||
f"decoded image chunk {index} retained {segment_images.shape[0]} frames; "
|
||||
f"plan expects {net_frames}"
|
||||
)
|
||||
|
||||
waveform, sample_rate = validate_audio(raw_audio)
|
||||
waveform = waveform.detach().to("cpu")
|
||||
sample_rate = int(sample_rate)
|
||||
raw_audio_cpu = {"waveform": waveform, "sample_rate": sample_rate}
|
||||
if audio_rate is None:
|
||||
audio_rate = sample_rate
|
||||
elif sample_rate != audio_rate:
|
||||
raise ValueError(
|
||||
f"audio sample rate changed between chunks: {audio_rate} -> {sample_rate}"
|
||||
)
|
||||
|
||||
frame_stop = frame_cursor + net_frames
|
||||
segment_waveform = _slice_audio_for_timeline(
|
||||
raw_audio_cpu,
|
||||
trim_frames=trim_frames,
|
||||
frame_start=frame_cursor,
|
||||
frame_stop=frame_stop,
|
||||
)
|
||||
|
||||
if image_buffer is None:
|
||||
image_buffer = torch.empty(
|
||||
(total_retained_frames, *segment_images.shape[1:]),
|
||||
dtype=segment_images.dtype,
|
||||
device="cpu",
|
||||
)
|
||||
elif tuple(segment_images.shape[1:]) != tuple(image_buffer.shape[1:]):
|
||||
raise ValueError(f"decoded image geometry changed at chunk {index}")
|
||||
image_buffer[frame_cursor:frame_stop].copy_(segment_images)
|
||||
|
||||
if audio_buffer is None:
|
||||
audio_buffer = torch.empty(
|
||||
(
|
||||
*waveform.shape[:-1],
|
||||
int(round(total_retained_frames / FPS * sample_rate)),
|
||||
),
|
||||
dtype=waveform.dtype,
|
||||
device="cpu",
|
||||
)
|
||||
elif tuple(segment_waveform.shape[:-1]) != tuple(audio_buffer.shape[:-1]):
|
||||
raise ValueError(
|
||||
"decoded audio batch/channel structure changed between chunks"
|
||||
)
|
||||
|
||||
sample_start = int(round(frame_cursor / FPS * sample_rate))
|
||||
sample_stop = int(round(frame_stop / FPS * sample_rate))
|
||||
seam_report = None
|
||||
if index > 1 and audio_seam == AUDIO_SEAM_AUTO:
|
||||
try:
|
||||
cut_sample = int(round(trim_frames / FPS * sample_rate))
|
||||
patch, metrics, fade_samples, level_gain, dc_bias = correct_audio_seam(
|
||||
audio_buffer[..., :sample_start],
|
||||
waveform,
|
||||
sample_rate=sample_rate,
|
||||
cut_sample=cut_sample,
|
||||
)
|
||||
if patch is not None and int(patch.shape[-1]) > 0:
|
||||
patch_start = sample_start - int(patch.shape[-1])
|
||||
if patch_start < 0:
|
||||
raise ValueError("audio seam patch starts before the output")
|
||||
audio_buffer[..., patch_start:sample_start].copy_(patch)
|
||||
seam_report = (
|
||||
f"audio seam {index-1}->{index}: "
|
||||
f"corr={metrics.correlation_before:.4f}->{metrics.correlation_after:.4f}, "
|
||||
f"jump={metrics.boundary_jump_before:.6f}->{metrics.boundary_jump_after:.6f}, "
|
||||
f"fade={fade_samples} samples"
|
||||
)
|
||||
if diagnostics_mode == DIAGNOSTICS_FULL:
|
||||
seam_report += (
|
||||
f", offset={metrics.offset_samples:+d}, "
|
||||
f"gain={level_gain:.4f}, dc={dc_bias:+.6f}"
|
||||
)
|
||||
except Exception as exc:
|
||||
seam_report = (
|
||||
f"audio seam {index-1}->{index}: fallback to native boundary "
|
||||
f"({type(exc).__name__}: {exc})"
|
||||
)
|
||||
|
||||
audio_buffer[..., sample_start:sample_stop].copy_(segment_waveform)
|
||||
if diagnostics_mode != DIAGNOSTICS_OFF:
|
||||
reports.append(
|
||||
f"assembled decoded chunk {index}: {net_frames} retained frames, "
|
||||
f"cumulative {frame_stop}/{total_retained_frames}"
|
||||
)
|
||||
if seam_report:
|
||||
reports.append(seam_report)
|
||||
frame_cursor = frame_stop
|
||||
|
||||
if image_buffer is None or audio_buffer is None or audio_rate is None:
|
||||
raise RuntimeError("V3 assembler failed to allocate output buffers")
|
||||
if frame_cursor != total_retained_frames:
|
||||
raise RuntimeError(
|
||||
f"V3 assembly cursor mismatch: {frame_cursor} != {total_retained_frames}"
|
||||
)
|
||||
|
||||
result_audio = {
|
||||
"waveform": audio_buffer.contiguous(),
|
||||
"sample_rate": audio_rate,
|
||||
}
|
||||
duration_report = ""
|
||||
if exact_total_duration:
|
||||
image_buffer, result_audio, duration_report = enforce_total_frames(
|
||||
image_buffer.contiguous(),
|
||||
result_audio,
|
||||
target_frames=int(plan["target_frames"]),
|
||||
preserve_final_frame=bool(plan.get("preserve_final_frame")),
|
||||
)
|
||||
|
||||
reports.append(
|
||||
f"Assembled {len(chunk_plans)} externally decoded chunks into "
|
||||
f"{image_buffer.shape[0]} frames with cumulative sample-boundary alignment."
|
||||
)
|
||||
if duration_report:
|
||||
reports.append(duration_report)
|
||||
runtime_started_at = plan.get("_runtime_started_at")
|
||||
if isinstance(runtime_started_at, (int, float)):
|
||||
elapsed = time.perf_counter() - float(runtime_started_at)
|
||||
if math.isfinite(elapsed) and elapsed >= 0.0:
|
||||
reports.append(f"Total workflow elapsed: {_format_elapsed(elapsed)}")
|
||||
return image_buffer.contiguous(), result_audio, "\n".join(reports)
|
||||
|
||||
|
||||
class H3ContinuumAssembleV3:
|
||||
DESCRIPTION = (
|
||||
"Assemble full AV chunks decoded by ComfyUI Core. Trims decoded context, "
|
||||
"aligns audio on cumulative frame boundaries, and optionally applies Audio Seam Auto."
|
||||
)
|
||||
SEARCH_ALIASES = ["H3 latent assemble", "H3 external VAE decode"]
|
||||
|
||||
@classmethod
|
||||
def INPUT_TYPES(cls):
|
||||
return {
|
||||
"required": {
|
||||
"images": ("IMAGE",),
|
||||
"audio": ("AUDIO",),
|
||||
"assembly_plan": ("H3_CONTINUUM_ASSEMBLY_PLAN",),
|
||||
"exact_total_duration": (
|
||||
"BOOLEAN",
|
||||
{
|
||||
"default": True,
|
||||
"tooltip": "Adjust the final output to the exact requested total duration.",
|
||||
},
|
||||
),
|
||||
"audio_seam": (
|
||||
AUDIO_SEAM_OPTIONS,
|
||||
{
|
||||
"default": AUDIO_SEAM_AUTO,
|
||||
"display_name": "Audio Seam",
|
||||
"tooltip": (
|
||||
"Auto corrects only decoded audio boundaries; "
|
||||
"video frames are never altered."
|
||||
),
|
||||
},
|
||||
),
|
||||
"diagnostics": (
|
||||
DIAGNOSTICS_OPTIONS,
|
||||
{
|
||||
"default": DIAGNOSTICS_OPTIONS[0],
|
||||
"display_name": "Report Detail",
|
||||
},
|
||||
),
|
||||
}
|
||||
}
|
||||
|
||||
INPUT_IS_LIST = True
|
||||
RETURN_TYPES = ("IMAGE", "AUDIO", "STRING")
|
||||
RETURN_NAMES = ("images", "audio", "report")
|
||||
FUNCTION = "assemble"
|
||||
CATEGORY = "MiniMax H3/Continuum"
|
||||
|
||||
def assemble(
|
||||
self,
|
||||
images,
|
||||
audio,
|
||||
assembly_plan,
|
||||
exact_total_duration,
|
||||
audio_seam,
|
||||
diagnostics,
|
||||
):
|
||||
return assemble_decoded_chunks(
|
||||
images=_chunk_list(images),
|
||||
audio=_chunk_list(audio),
|
||||
assembly_plan=_singleton(assembly_plan, "assembly_plan"),
|
||||
exact_total_duration=bool(
|
||||
_singleton(exact_total_duration, "exact_total_duration")
|
||||
),
|
||||
audio_seam=str(_singleton(audio_seam, "audio_seam")),
|
||||
diagnostics=str(_singleton(diagnostics, "diagnostics")),
|
||||
)
|
||||
# V3.0.1 hardening integration: preflight before allocation; Detailed Report only.
|
||||
from ..hardening import assemble_with_hardening as _assemble_with_hardening
|
||||
|
||||
_assemble_decoded_chunks_v300 = assemble_decoded_chunks
|
||||
|
||||
|
||||
def assemble_decoded_chunks(*args, **kwargs):
|
||||
return _assemble_with_hardening(_assemble_decoded_chunks_v300, args, kwargs)
|
||||
|
||||
|
||||
class H3ContinuumAssembleSeamExperimental(H3ContinuumAssembleV3):
|
||||
DEPRECATED = False
|
||||
CATEGORY = "MiniMax H3/Continuum"
|
||||
DESCRIPTION = (
|
||||
"Analyze decoded chunk boundaries and apply guarded video seam correction."
|
||||
)
|
||||
SEARCH_ALIASES = ["H3 seam analysis", "H3 boundary flicker analysis"]
|
||||
|
||||
@classmethod
|
||||
def INPUT_TYPES(cls):
|
||||
schema = super().INPUT_TYPES()
|
||||
required = dict(schema["required"])
|
||||
diagnostics = required.pop("diagnostics")
|
||||
required["video_seam"] = (
|
||||
VIDEO_SEAM_ANALYSIS_OPTIONS,
|
||||
{
|
||||
"default": VIDEO_SEAM_AUTO,
|
||||
"display_name": "Video Seam",
|
||||
"tooltip": (
|
||||
"Analyze Only reports decoded video boundaries without changing them. "
|
||||
"Auto applies the validated transient and micro-flash correction. "
|
||||
"Auto 2 experimentally adds qualified exposure-ramp smoothing."
|
||||
),
|
||||
},
|
||||
)
|
||||
required["diagnostics"] = diagnostics
|
||||
schema["required"] = required
|
||||
return schema
|
||||
|
||||
def assemble(
|
||||
self,
|
||||
images,
|
||||
audio,
|
||||
assembly_plan,
|
||||
exact_total_duration,
|
||||
audio_seam,
|
||||
video_seam,
|
||||
diagnostics,
|
||||
):
|
||||
mode = str(_singleton(video_seam, "video_seam"))
|
||||
if mode not in VIDEO_SEAM_ANALYSIS_OPTIONS:
|
||||
raise ValueError(f"unknown Video Seam mode: {mode!r}")
|
||||
if mode == VIDEO_SEAM_OFF:
|
||||
return super().assemble(
|
||||
images,
|
||||
audio,
|
||||
assembly_plan,
|
||||
exact_total_duration,
|
||||
audio_seam,
|
||||
diagnostics,
|
||||
)
|
||||
|
||||
image_chunks = _chunk_list(images)
|
||||
plan = _singleton(assembly_plan, "assembly_plan")
|
||||
analyses = []
|
||||
analysis_error = None
|
||||
actions = {}
|
||||
try:
|
||||
from .video_seam import (
|
||||
analyze_decoded_boundaries,
|
||||
correct_decoded_boundaries,
|
||||
format_video_boundary_analysis,
|
||||
)
|
||||
|
||||
analyses = analyze_decoded_boundaries(
|
||||
images=image_chunks,
|
||||
assembly_plan=plan,
|
||||
)
|
||||
if mode in (VIDEO_SEAM_AUTO, VIDEO_SEAM_AUTO_2):
|
||||
image_chunks, actions = correct_decoded_boundaries(
|
||||
images=image_chunks,
|
||||
assembly_plan=plan,
|
||||
analyses=analyses,
|
||||
enable_exposure_ramp=mode == VIDEO_SEAM_AUTO_2,
|
||||
)
|
||||
except Exception as exc:
|
||||
analysis_error = exc
|
||||
|
||||
result_images, result_audio, report = assemble_decoded_chunks(
|
||||
images=image_chunks,
|
||||
audio=_chunk_list(audio),
|
||||
assembly_plan=plan,
|
||||
exact_total_duration=bool(
|
||||
_singleton(exact_total_duration, "exact_total_duration")
|
||||
),
|
||||
audio_seam=str(_singleton(audio_seam, "audio_seam")),
|
||||
diagnostics=str(_singleton(diagnostics, "diagnostics")),
|
||||
)
|
||||
if mode == VIDEO_SEAM_ANALYZE:
|
||||
status = "Video Seam: Analyze Only; decoded frames and audio are unchanged."
|
||||
elif mode == VIDEO_SEAM_AUTO:
|
||||
status = (
|
||||
"Video Seam: Auto; guarded transient and micro-flash correction enabled."
|
||||
)
|
||||
else:
|
||||
status = (
|
||||
"Video Seam: Auto 2 (Experimental); guarded transient, micro-flash, "
|
||||
"and exposure-ramp correction enabled."
|
||||
)
|
||||
report = report.replace("Video seam correction is disabled.", status, 1)
|
||||
if analysis_error is None:
|
||||
lines = [
|
||||
format_video_boundary_analysis(
|
||||
item,
|
||||
action=(
|
||||
"analysis only"
|
||||
if mode == VIDEO_SEAM_ANALYZE
|
||||
else actions.get(item.boundary_index, "kept native boundary")
|
||||
),
|
||||
)
|
||||
for item in analyses
|
||||
]
|
||||
if not lines:
|
||||
lines = [f"Video Seam {mode}: no decoded chunk boundary to analyze."]
|
||||
else:
|
||||
lines = [
|
||||
f"Video Seam {mode}: native output preserved; analysis unavailable "
|
||||
f"({type(analysis_error).__name__}: {analysis_error})"
|
||||
]
|
||||
return result_images, result_audio, report.rstrip() + "\n" + "\n".join(lines)
|
||||
"""Decoded chunk assembly for latent-first H3 Continuum V3."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import math
|
||||
import time
|
||||
from typing import Any
|
||||
|
||||
import torch
|
||||
|
||||
from ..media import validate_audio
|
||||
from ..v2.decoder import _slice_audio_for_timeline, enforce_total_frames
|
||||
from ..constants import (
|
||||
DIAGNOSTICS_FULL,
|
||||
DIAGNOSTICS_OFF,
|
||||
DIAGNOSTICS_OPTIONS,
|
||||
normalize_diagnostics_mode,
|
||||
)
|
||||
from ..v2.seam_guard import correct_audio_seam
|
||||
from .plan import FPS, validate_assembly_plan
|
||||
|
||||
AUDIO_SEAM_OFF = "Off"
|
||||
AUDIO_SEAM_AUTO = "Auto"
|
||||
AUDIO_SEAM_OPTIONS = (AUDIO_SEAM_OFF, AUDIO_SEAM_AUTO)
|
||||
VIDEO_SEAM_OFF = "Off"
|
||||
VIDEO_SEAM_ANALYZE = "Analyze Only"
|
||||
VIDEO_SEAM_AUTO = "Auto"
|
||||
VIDEO_SEAM_AUTO_2 = "Auto 2"
|
||||
VIDEO_SEAM_ANALYSIS_OPTIONS = (
|
||||
VIDEO_SEAM_AUTO,
|
||||
VIDEO_SEAM_AUTO_2,
|
||||
VIDEO_SEAM_ANALYZE,
|
||||
VIDEO_SEAM_OFF,
|
||||
)
|
||||
|
||||
|
||||
def _singleton(value: Any, name: str) -> Any:
|
||||
while isinstance(value, list):
|
||||
if len(value) != 1:
|
||||
raise ValueError(f"{name} must contain exactly one value")
|
||||
value = value[0]
|
||||
return value
|
||||
|
||||
|
||||
def _chunk_list(value: Any) -> list[Any]:
|
||||
if isinstance(value, list):
|
||||
if len(value) == 1 and isinstance(value[0], list):
|
||||
return list(value[0])
|
||||
return list(value)
|
||||
return [value]
|
||||
|
||||
|
||||
def _format_elapsed(seconds: float) -> str:
|
||||
total = max(0.0, float(seconds))
|
||||
hours, remainder = divmod(total, 3600.0)
|
||||
minutes, seconds = divmod(remainder, 60.0)
|
||||
return f"{int(hours):02d}:{int(minutes):02d}:{seconds:05.2f}"
|
||||
|
||||
|
||||
def assemble_decoded_chunks(
|
||||
*,
|
||||
images: list[Any],
|
||||
audio: list[Any],
|
||||
assembly_plan: dict[str, Any],
|
||||
exact_total_duration: bool,
|
||||
audio_seam: str,
|
||||
diagnostics: str,
|
||||
):
|
||||
plan = validate_assembly_plan(assembly_plan)
|
||||
diagnostics_mode = normalize_diagnostics_mode(diagnostics)
|
||||
if audio_seam not in AUDIO_SEAM_OPTIONS:
|
||||
raise ValueError(f"unknown Audio Seam mode: {audio_seam!r}")
|
||||
|
||||
chunk_plans = list(
|
||||
plan["decode_groups"] if "decode_groups" in plan else plan["chunks"]
|
||||
)
|
||||
if len(images) != len(chunk_plans) or len(audio) != len(chunk_plans):
|
||||
raise ValueError(
|
||||
"decoded chunk count does not match the V3 assembly plan: "
|
||||
f"images={len(images)}, audio={len(audio)}, plan={len(chunk_plans)}"
|
||||
)
|
||||
|
||||
total_retained_frames = sum(int(item["net_frames"]) for item in chunk_plans)
|
||||
image_buffer = None
|
||||
audio_buffer = None
|
||||
audio_rate = None
|
||||
frame_cursor = 0
|
||||
reports = [
|
||||
"H3 Continuum Assemble V3",
|
||||
f"Audio Seam: {audio_seam}. Video seam correction is disabled.",
|
||||
]
|
||||
|
||||
for index, (raw_images, raw_audio, chunk) in enumerate(
|
||||
zip(images, audio, chunk_plans), start=1
|
||||
):
|
||||
if not torch.is_tensor(raw_images) or raw_images.ndim != 4:
|
||||
raise ValueError(f"decoded image chunk {index} must be [frames,H,W,C]")
|
||||
raw_images = raw_images.detach().to("cpu")
|
||||
total_frames = int(chunk["total_frames"])
|
||||
trim_frames = int(chunk["trim_frames"])
|
||||
net_frames = int(chunk["net_frames"])
|
||||
if int(raw_images.shape[0]) < total_frames:
|
||||
raise ValueError(
|
||||
f"decoded image chunk {index} has {raw_images.shape[0]} frames; "
|
||||
f"expected at least {total_frames}"
|
||||
)
|
||||
segment_images = raw_images[:total_frames][trim_frames:].contiguous()
|
||||
if int(segment_images.shape[0]) != net_frames:
|
||||
raise ValueError(
|
||||
f"decoded image chunk {index} retained {segment_images.shape[0]} frames; "
|
||||
f"plan expects {net_frames}"
|
||||
)
|
||||
|
||||
waveform, sample_rate = validate_audio(raw_audio)
|
||||
waveform = waveform.detach().to("cpu")
|
||||
sample_rate = int(sample_rate)
|
||||
raw_audio_cpu = {"waveform": waveform, "sample_rate": sample_rate}
|
||||
if audio_rate is None:
|
||||
audio_rate = sample_rate
|
||||
elif sample_rate != audio_rate:
|
||||
raise ValueError(
|
||||
f"audio sample rate changed between chunks: {audio_rate} -> {sample_rate}"
|
||||
)
|
||||
|
||||
frame_stop = frame_cursor + net_frames
|
||||
segment_waveform = _slice_audio_for_timeline(
|
||||
raw_audio_cpu,
|
||||
trim_frames=trim_frames,
|
||||
frame_start=frame_cursor,
|
||||
frame_stop=frame_stop,
|
||||
)
|
||||
|
||||
if image_buffer is None:
|
||||
image_buffer = torch.empty(
|
||||
(total_retained_frames, *segment_images.shape[1:]),
|
||||
dtype=segment_images.dtype,
|
||||
device="cpu",
|
||||
)
|
||||
elif tuple(segment_images.shape[1:]) != tuple(image_buffer.shape[1:]):
|
||||
raise ValueError(f"decoded image geometry changed at chunk {index}")
|
||||
image_buffer[frame_cursor:frame_stop].copy_(segment_images)
|
||||
|
||||
if audio_buffer is None:
|
||||
audio_buffer = torch.empty(
|
||||
(
|
||||
*waveform.shape[:-1],
|
||||
int(round(total_retained_frames / FPS * sample_rate)),
|
||||
),
|
||||
dtype=waveform.dtype,
|
||||
device="cpu",
|
||||
)
|
||||
elif tuple(segment_waveform.shape[:-1]) != tuple(audio_buffer.shape[:-1]):
|
||||
raise ValueError(
|
||||
"decoded audio batch/channel structure changed between chunks"
|
||||
)
|
||||
|
||||
sample_start = int(round(frame_cursor / FPS * sample_rate))
|
||||
sample_stop = int(round(frame_stop / FPS * sample_rate))
|
||||
seam_report = None
|
||||
if index > 1 and audio_seam == AUDIO_SEAM_AUTO:
|
||||
try:
|
||||
cut_sample = int(round(trim_frames / FPS * sample_rate))
|
||||
patch, metrics, fade_samples, level_gain, dc_bias = correct_audio_seam(
|
||||
audio_buffer[..., :sample_start],
|
||||
waveform,
|
||||
sample_rate=sample_rate,
|
||||
cut_sample=cut_sample,
|
||||
)
|
||||
if patch is not None and int(patch.shape[-1]) > 0:
|
||||
patch_start = sample_start - int(patch.shape[-1])
|
||||
if patch_start < 0:
|
||||
raise ValueError("audio seam patch starts before the output")
|
||||
audio_buffer[..., patch_start:sample_start].copy_(patch)
|
||||
seam_report = (
|
||||
f"audio seam {index-1}->{index}: "
|
||||
f"corr={metrics.correlation_before:.4f}->{metrics.correlation_after:.4f}, "
|
||||
f"jump={metrics.boundary_jump_before:.6f}->{metrics.boundary_jump_after:.6f}, "
|
||||
f"fade={fade_samples} samples"
|
||||
)
|
||||
if diagnostics_mode == DIAGNOSTICS_FULL:
|
||||
seam_report += (
|
||||
f", offset={metrics.offset_samples:+d}, "
|
||||
f"gain={level_gain:.4f}, dc={dc_bias:+.6f}"
|
||||
)
|
||||
except Exception as exc:
|
||||
seam_report = (
|
||||
f"audio seam {index-1}->{index}: fallback to native boundary "
|
||||
f"({type(exc).__name__}: {exc})"
|
||||
)
|
||||
|
||||
audio_buffer[..., sample_start:sample_stop].copy_(segment_waveform)
|
||||
if diagnostics_mode != DIAGNOSTICS_OFF:
|
||||
reports.append(
|
||||
f"assembled decoded chunk {index}: {net_frames} retained frames, "
|
||||
f"cumulative {frame_stop}/{total_retained_frames}"
|
||||
)
|
||||
if seam_report:
|
||||
reports.append(seam_report)
|
||||
frame_cursor = frame_stop
|
||||
|
||||
if image_buffer is None or audio_buffer is None or audio_rate is None:
|
||||
raise RuntimeError("V3 assembler failed to allocate output buffers")
|
||||
if frame_cursor != total_retained_frames:
|
||||
raise RuntimeError(
|
||||
f"V3 assembly cursor mismatch: {frame_cursor} != {total_retained_frames}"
|
||||
)
|
||||
|
||||
result_audio = {
|
||||
"waveform": audio_buffer.contiguous(),
|
||||
"sample_rate": audio_rate,
|
||||
}
|
||||
duration_report = ""
|
||||
if exact_total_duration:
|
||||
image_buffer, result_audio, duration_report = enforce_total_frames(
|
||||
image_buffer.contiguous(),
|
||||
result_audio,
|
||||
target_frames=int(plan["target_frames"]),
|
||||
preserve_final_frame=bool(plan.get("preserve_final_frame")),
|
||||
)
|
||||
|
||||
reports.append(
|
||||
f"Assembled {len(chunk_plans)} externally decoded chunks into "
|
||||
f"{image_buffer.shape[0]} frames with cumulative sample-boundary alignment."
|
||||
)
|
||||
if duration_report:
|
||||
reports.append(duration_report)
|
||||
runtime_started_at = plan.get("_runtime_started_at")
|
||||
if isinstance(runtime_started_at, (int, float)):
|
||||
elapsed = time.perf_counter() - float(runtime_started_at)
|
||||
if math.isfinite(elapsed) and elapsed >= 0.0:
|
||||
reports.append(f"Total workflow elapsed: {_format_elapsed(elapsed)}")
|
||||
return image_buffer.contiguous(), result_audio, "\n".join(reports)
|
||||
|
||||
|
||||
class H3ContinuumAssembleV3:
|
||||
DESCRIPTION = (
|
||||
"Assemble full AV chunks decoded by ComfyUI Core. Trims decoded context, "
|
||||
"aligns audio on cumulative frame boundaries, and optionally applies Audio Seam Auto."
|
||||
)
|
||||
SEARCH_ALIASES = ["H3 latent assemble", "H3 external VAE decode"]
|
||||
|
||||
@classmethod
|
||||
def INPUT_TYPES(cls):
|
||||
return {
|
||||
"required": {
|
||||
"images": ("IMAGE",),
|
||||
"audio": ("AUDIO",),
|
||||
"assembly_plan": ("H3_CONTINUUM_ASSEMBLY_PLAN",),
|
||||
"exact_total_duration": (
|
||||
"BOOLEAN",
|
||||
{
|
||||
"default": True,
|
||||
"tooltip": "Adjust the final output to the exact requested total duration.",
|
||||
},
|
||||
),
|
||||
"audio_seam": (
|
||||
AUDIO_SEAM_OPTIONS,
|
||||
{
|
||||
"default": AUDIO_SEAM_AUTO,
|
||||
"display_name": "Audio Seam",
|
||||
"tooltip": (
|
||||
"Auto corrects only decoded audio boundaries; "
|
||||
"video frames are never altered."
|
||||
),
|
||||
},
|
||||
),
|
||||
"diagnostics": (
|
||||
DIAGNOSTICS_OPTIONS,
|
||||
{
|
||||
"default": DIAGNOSTICS_OPTIONS[0],
|
||||
"display_name": "Report Detail",
|
||||
},
|
||||
),
|
||||
}
|
||||
}
|
||||
|
||||
INPUT_IS_LIST = True
|
||||
RETURN_TYPES = ("IMAGE", "AUDIO", "STRING")
|
||||
RETURN_NAMES = ("images", "audio", "report")
|
||||
FUNCTION = "assemble"
|
||||
CATEGORY = "MiniMax H3/Continuum"
|
||||
|
||||
def assemble(
|
||||
self,
|
||||
images,
|
||||
audio,
|
||||
assembly_plan,
|
||||
exact_total_duration,
|
||||
audio_seam,
|
||||
diagnostics,
|
||||
):
|
||||
return assemble_decoded_chunks(
|
||||
images=_chunk_list(images),
|
||||
audio=_chunk_list(audio),
|
||||
assembly_plan=_singleton(assembly_plan, "assembly_plan"),
|
||||
exact_total_duration=bool(
|
||||
_singleton(exact_total_duration, "exact_total_duration")
|
||||
),
|
||||
audio_seam=str(_singleton(audio_seam, "audio_seam")),
|
||||
diagnostics=str(_singleton(diagnostics, "diagnostics")),
|
||||
)
|
||||
# V3.0.1 hardening integration: preflight before allocation; Detailed Report only.
|
||||
from ..hardening import assemble_with_hardening as _assemble_with_hardening
|
||||
|
||||
_assemble_decoded_chunks_v300 = assemble_decoded_chunks
|
||||
|
||||
|
||||
def assemble_decoded_chunks(*args, **kwargs):
|
||||
return _assemble_with_hardening(_assemble_decoded_chunks_v300, args, kwargs)
|
||||
|
||||
|
||||
class H3ContinuumAssembleSeamExperimental(H3ContinuumAssembleV3):
|
||||
DEPRECATED = False
|
||||
CATEGORY = "MiniMax H3/Continuum"
|
||||
DESCRIPTION = (
|
||||
"Analyze decoded chunk boundaries and apply guarded video seam correction."
|
||||
)
|
||||
SEARCH_ALIASES = ["H3 seam analysis", "H3 boundary flicker analysis"]
|
||||
|
||||
@classmethod
|
||||
def INPUT_TYPES(cls):
|
||||
schema = super().INPUT_TYPES()
|
||||
required = dict(schema["required"])
|
||||
diagnostics = required.pop("diagnostics")
|
||||
required["video_seam"] = (
|
||||
VIDEO_SEAM_ANALYSIS_OPTIONS,
|
||||
{
|
||||
"default": VIDEO_SEAM_AUTO,
|
||||
"display_name": "Video Seam",
|
||||
"tooltip": (
|
||||
"Analyze Only reports decoded video boundaries without changing them. "
|
||||
"Auto applies the validated transient and micro-flash correction. "
|
||||
"Auto 2 experimentally adds qualified exposure-ramp smoothing."
|
||||
),
|
||||
},
|
||||
)
|
||||
required["diagnostics"] = diagnostics
|
||||
schema["required"] = required
|
||||
return schema
|
||||
|
||||
def assemble(
|
||||
self,
|
||||
images,
|
||||
audio,
|
||||
assembly_plan,
|
||||
exact_total_duration,
|
||||
audio_seam,
|
||||
video_seam,
|
||||
diagnostics,
|
||||
):
|
||||
mode = str(_singleton(video_seam, "video_seam"))
|
||||
if mode not in VIDEO_SEAM_ANALYSIS_OPTIONS:
|
||||
raise ValueError(f"unknown Video Seam mode: {mode!r}")
|
||||
if mode == VIDEO_SEAM_OFF:
|
||||
return super().assemble(
|
||||
images,
|
||||
audio,
|
||||
assembly_plan,
|
||||
exact_total_duration,
|
||||
audio_seam,
|
||||
diagnostics,
|
||||
)
|
||||
|
||||
image_chunks = _chunk_list(images)
|
||||
plan = _singleton(assembly_plan, "assembly_plan")
|
||||
analyses = []
|
||||
analysis_error = None
|
||||
actions = {}
|
||||
try:
|
||||
from .video_seam import (
|
||||
analyze_decoded_boundaries,
|
||||
correct_decoded_boundaries,
|
||||
format_video_boundary_analysis,
|
||||
)
|
||||
|
||||
analyses = analyze_decoded_boundaries(
|
||||
images=image_chunks,
|
||||
assembly_plan=plan,
|
||||
)
|
||||
if mode in (VIDEO_SEAM_AUTO, VIDEO_SEAM_AUTO_2):
|
||||
image_chunks, actions = correct_decoded_boundaries(
|
||||
images=image_chunks,
|
||||
assembly_plan=plan,
|
||||
analyses=analyses,
|
||||
enable_exposure_ramp=mode == VIDEO_SEAM_AUTO_2,
|
||||
)
|
||||
except Exception as exc:
|
||||
analysis_error = exc
|
||||
|
||||
result_images, result_audio, report = assemble_decoded_chunks(
|
||||
images=image_chunks,
|
||||
audio=_chunk_list(audio),
|
||||
assembly_plan=plan,
|
||||
exact_total_duration=bool(
|
||||
_singleton(exact_total_duration, "exact_total_duration")
|
||||
),
|
||||
audio_seam=str(_singleton(audio_seam, "audio_seam")),
|
||||
diagnostics=str(_singleton(diagnostics, "diagnostics")),
|
||||
)
|
||||
if mode == VIDEO_SEAM_ANALYZE:
|
||||
status = "Video Seam: Analyze Only; decoded frames and audio are unchanged."
|
||||
elif mode == VIDEO_SEAM_AUTO:
|
||||
status = (
|
||||
"Video Seam: Auto; guarded transient and micro-flash correction enabled."
|
||||
)
|
||||
else:
|
||||
status = (
|
||||
"Video Seam: Auto 2 (Experimental); guarded transient, micro-flash, "
|
||||
"and exposure-ramp correction enabled."
|
||||
)
|
||||
report = report.replace("Video seam correction is disabled.", status, 1)
|
||||
if analysis_error is None:
|
||||
lines = [
|
||||
format_video_boundary_analysis(
|
||||
item,
|
||||
action=(
|
||||
"analysis only"
|
||||
if mode == VIDEO_SEAM_ANALYZE
|
||||
else actions.get(item.boundary_index, "kept native boundary")
|
||||
),
|
||||
)
|
||||
for item in analyses
|
||||
]
|
||||
if not lines:
|
||||
lines = [f"Video Seam {mode}: no decoded chunk boundary to analyze."]
|
||||
else:
|
||||
lines = [
|
||||
f"Video Seam {mode}: native output preserved; analysis unavailable "
|
||||
f"({type(analysis_error).__name__}: {analysis_error})"
|
||||
]
|
||||
return result_images, result_audio, report.rstrip() + "\n" + "\n".join(lines)
|
||||
|
||||
+861
-398
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,66 @@
|
||||
"""Generic Easy workflow audio loader backed by ComfyUI Core LoadAudio."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from types import SimpleNamespace
|
||||
|
||||
|
||||
try:
|
||||
from comfy_extras.nodes_audio import LoadAudio as CoreLoadAudio
|
||||
except (ImportError, AttributeError): # pragma: no cover - standalone unit tests
|
||||
class CoreLoadAudio:
|
||||
"""Non-runtime shim; real ComfyUI always supplies Core LoadAudio."""
|
||||
|
||||
@classmethod
|
||||
def define_schema(cls):
|
||||
return SimpleNamespace(
|
||||
node_id="LoadAudio",
|
||||
display_name="Load Audio",
|
||||
category="audio",
|
||||
essentials_category="Audio",
|
||||
description="",
|
||||
search_aliases=["import audio", "open audio", "audio file"],
|
||||
is_deprecated=False,
|
||||
)
|
||||
|
||||
@classmethod
|
||||
def execute(cls, audio):
|
||||
return audio
|
||||
|
||||
load = execute
|
||||
|
||||
|
||||
class H3EasyLoadAudio(CoreLoadAudio):
|
||||
"""Core LoadAudio with an Easy frontend control for native node bypass."""
|
||||
|
||||
@classmethod
|
||||
def define_schema(cls):
|
||||
schema = super().define_schema()
|
||||
schema.node_id = "H3EasyLoadAudio"
|
||||
schema.display_name = "H3 Continuum Load Audio"
|
||||
schema.category = "MiniMax H3/Continuum"
|
||||
schema.description = (
|
||||
"Loads audio through ComfyUI Core. Enable Audio controls the node's "
|
||||
"native Bypass mode without changing the AUDIO contract."
|
||||
)
|
||||
schema.search_aliases = list(
|
||||
dict.fromkeys(
|
||||
[
|
||||
*getattr(schema, "search_aliases", []),
|
||||
"H3 Continuum Load Audio",
|
||||
"H3 Easy Load Audio",
|
||||
"H3 Easy Audio Loader",
|
||||
"Load Audio with Bypass",
|
||||
]
|
||||
)
|
||||
)
|
||||
return schema
|
||||
|
||||
|
||||
NODE_CLASS_MAPPINGS = {
|
||||
"H3EasyLoadAudio": H3EasyLoadAudio,
|
||||
}
|
||||
|
||||
NODE_DISPLAY_NAME_MAPPINGS = {
|
||||
"H3EasyLoadAudio": "H3 Continuum Load Audio",
|
||||
}
|
||||
@@ -0,0 +1,48 @@
|
||||
"""Generic Easy workflow image loader backed by ComfyUI Core LoadImage."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
|
||||
try:
|
||||
from nodes import LoadImage as CoreLoadImage
|
||||
except (ImportError, AttributeError): # pragma: no cover - standalone unit tests
|
||||
class CoreLoadImage:
|
||||
"""Non-runtime shim; real ComfyUI always supplies Core LoadImage."""
|
||||
|
||||
@classmethod
|
||||
def INPUT_TYPES(cls):
|
||||
return {
|
||||
"required": {
|
||||
"image": (("",), {"image_upload": True}),
|
||||
}
|
||||
}
|
||||
|
||||
RETURN_TYPES = ("IMAGE", "MASK")
|
||||
FUNCTION = "load_image"
|
||||
|
||||
|
||||
class H3EasyLoadImage(CoreLoadImage):
|
||||
"""Core LoadImage with an Easy frontend control for native node bypass."""
|
||||
|
||||
DEPRECATED = False
|
||||
CATEGORY = "MiniMax H3/Continuum"
|
||||
DESCRIPTION = (
|
||||
"Loads an image through ComfyUI Core. Enable Image controls the node's "
|
||||
"native Bypass mode, so the same node can serve First, Last, or Reference "
|
||||
"image inputs without changing the IMAGE/MASK contract."
|
||||
)
|
||||
SEARCH_ALIASES = [
|
||||
"H3 Continuum Load Image",
|
||||
"H3 Easy Load Image",
|
||||
"H3 Easy Image Loader",
|
||||
"Load Image with Bypass",
|
||||
]
|
||||
|
||||
|
||||
NODE_CLASS_MAPPINGS = {
|
||||
"H3EasyLoadImage": H3EasyLoadImage,
|
||||
}
|
||||
|
||||
NODE_DISPLAY_NAME_MAPPINGS = {
|
||||
"H3EasyLoadImage": "H3 Continuum Load Image",
|
||||
}
|
||||
@@ -0,0 +1,482 @@
|
||||
"""V3.8 Easy Mode facade and deterministic UI resolvers."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
import math
|
||||
from typing import Any
|
||||
|
||||
from ..conditioning import conditioning_display_label
|
||||
from ..constants import (
|
||||
CONTINUITY_OPTIONS,
|
||||
DIAGNOSTICS_BASIC,
|
||||
PROMPT_FORMAT_AUTO,
|
||||
)
|
||||
from ..reference import REFERENCE_SIZE_MATCH_OUTPUT
|
||||
from ..reference_video import REFERENCE_VIDEO_SIZE_EFFICIENT
|
||||
from .driving_nodes import (
|
||||
CONTINUATION_BACKEND_STANDARD,
|
||||
H3ContinuumSamplerV37,
|
||||
)
|
||||
from .nodes import CATEGORY as CONTINUUM_CATEGORY, REGENERATE_AUTO
|
||||
from .resolution import (
|
||||
H3_ASPECT_AUTO,
|
||||
H3_ASPECT_LANDSCAPE,
|
||||
H3_ASPECT_OPTIONS,
|
||||
H3_ASPECT_PORTRAIT,
|
||||
H3_ASPECT_SQUARE,
|
||||
H3_BALANCED_MP,
|
||||
H3_CANVAS_MULTIPLE,
|
||||
H3_CUSTOM_MP_DEFAULT,
|
||||
H3_CUSTOM_MP_MAX,
|
||||
H3_CUSTOM_MP_MIN,
|
||||
H3_CUSTOM_MP_STRONG_WARNING,
|
||||
H3_DRAFT_MP,
|
||||
H3_MP_PIXELS,
|
||||
H3_NATIVE_LONG_EDGE_CAP,
|
||||
H3_NATIVE_SHORT_EDGE,
|
||||
H3_PRESET_BALANCED,
|
||||
H3_PRESET_CUSTOM,
|
||||
H3_PRESET_DRAFT,
|
||||
H3_PRESET_NATIVE,
|
||||
H3_PRESET_OPTIONS,
|
||||
H3ResolutionPlan,
|
||||
resolve_h3_aspect,
|
||||
resolve_h3_resolution,
|
||||
)
|
||||
|
||||
|
||||
EASY_DURATION_DEFAULT = 10
|
||||
EASY_DURATION_MIN = 4
|
||||
EASY_DURATION_MAX = 480
|
||||
EASY_TARGET_CHUNK_SECONDS = 10.0
|
||||
EASY_MAX_CHUNKS = 16
|
||||
|
||||
EASY_SEED_MODE_RANDOMIZE = "Randomize"
|
||||
EASY_SEED_MODE_FIXED = "Fixed"
|
||||
EASY_SEED_MODE_OPTIONS = (
|
||||
EASY_SEED_MODE_RANDOMIZE,
|
||||
EASY_SEED_MODE_FIXED,
|
||||
)
|
||||
|
||||
EASY_ASPECT_AUTO = H3_ASPECT_AUTO
|
||||
EASY_ASPECT_LANDSCAPE = H3_ASPECT_LANDSCAPE
|
||||
EASY_ASPECT_PORTRAIT = H3_ASPECT_PORTRAIT
|
||||
EASY_ASPECT_SQUARE = H3_ASPECT_SQUARE
|
||||
EASY_ASPECT_OPTIONS = H3_ASPECT_OPTIONS
|
||||
|
||||
EASY_PRESET_DRAFT = H3_PRESET_DRAFT
|
||||
EASY_PRESET_BALANCED = H3_PRESET_BALANCED
|
||||
EASY_PRESET_NATIVE = H3_PRESET_NATIVE
|
||||
EASY_PRESET_CUSTOM = H3_PRESET_CUSTOM
|
||||
EASY_PRESET_OPTIONS = H3_PRESET_OPTIONS
|
||||
|
||||
EASY_DRAFT_MP = H3_DRAFT_MP
|
||||
EASY_BALANCED_MP = H3_BALANCED_MP
|
||||
EASY_CUSTOM_MP_DEFAULT = H3_CUSTOM_MP_DEFAULT
|
||||
EASY_CUSTOM_MP_MIN = H3_CUSTOM_MP_MIN
|
||||
EASY_CUSTOM_MP_MAX = H3_CUSTOM_MP_MAX
|
||||
EASY_CUSTOM_MP_STRONG_WARNING = H3_CUSTOM_MP_STRONG_WARNING
|
||||
EASY_MP_PIXELS = H3_MP_PIXELS
|
||||
EASY_CANVAS_MULTIPLE = H3_CANVAS_MULTIPLE
|
||||
EASY_NATIVE_SHORT_EDGE = H3_NATIVE_SHORT_EDGE
|
||||
EASY_NATIVE_LONG_EDGE_CAP = H3_NATIVE_LONG_EDGE_CAP
|
||||
EasyResolutionPlan = H3ResolutionPlan
|
||||
resolve_easy_aspect = resolve_h3_aspect
|
||||
resolve_easy_resolution = resolve_h3_resolution
|
||||
EASY_REFERENCES_TYPE = "H3_CONTINUUM_EASY_REFERENCES"
|
||||
EASY_REFERENCES_SCHEMA_VERSION = 1
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class EasyDurationPlan:
|
||||
duration_seconds: int
|
||||
chunks: int
|
||||
chunk_seconds: float
|
||||
|
||||
|
||||
def make_easy_references(
|
||||
reference_image_1: Any = None,
|
||||
reference_image_2: Any = None,
|
||||
reference_image_3: Any = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Pack fixed Easy reference sockets without preprocessing their images."""
|
||||
|
||||
return {
|
||||
"schema_version": EASY_REFERENCES_SCHEMA_VERSION,
|
||||
"reference_image_1": reference_image_1,
|
||||
"reference_image_2": reference_image_2,
|
||||
"reference_image_3": reference_image_3,
|
||||
}
|
||||
|
||||
|
||||
def resolve_easy_references(references: Any = None) -> tuple[Any, Any, Any]:
|
||||
"""Expand the private Easy bundle back into the mature V3.7 input contract."""
|
||||
|
||||
if references is None:
|
||||
return None, None, None
|
||||
if not isinstance(references, dict):
|
||||
raise TypeError("Easy References must come from H3 Continuum Easy References")
|
||||
if references.get("schema_version") != EASY_REFERENCES_SCHEMA_VERSION:
|
||||
raise ValueError("Unsupported H3 Continuum Easy References schema version")
|
||||
return tuple(
|
||||
references.get(f"reference_image_{index}") for index in range(1, 4)
|
||||
)
|
||||
|
||||
|
||||
def resolve_easy_duration(duration_seconds: int) -> EasyDurationPlan:
|
||||
"""Resolve one total duration around ten-second logical chunks."""
|
||||
|
||||
if isinstance(duration_seconds, bool):
|
||||
raise TypeError("Duration must be an integer number of seconds")
|
||||
duration = int(duration_seconds)
|
||||
if duration != duration_seconds:
|
||||
raise ValueError("Duration must be an integer number of seconds")
|
||||
if not EASY_DURATION_MIN <= duration <= EASY_DURATION_MAX:
|
||||
raise ValueError(
|
||||
f"Duration must be between {EASY_DURATION_MIN} and {EASY_DURATION_MAX} seconds"
|
||||
)
|
||||
chunks = min(
|
||||
EASY_MAX_CHUNKS,
|
||||
max(1, int(math.ceil(float(duration) / EASY_TARGET_CHUNK_SECONDS))),
|
||||
)
|
||||
chunk_seconds = float(duration) / float(chunks)
|
||||
if not 4.0 <= chunk_seconds <= 30.0:
|
||||
raise ValueError("Duration cannot be represented by the Production chunk contract")
|
||||
return EasyDurationPlan(
|
||||
duration_seconds=duration,
|
||||
chunks=chunks,
|
||||
chunk_seconds=chunk_seconds,
|
||||
)
|
||||
|
||||
|
||||
class H3ContinuumEasyReferences:
|
||||
"""Fixed three-image facade for the existing V3.7 reference contract."""
|
||||
|
||||
DEPRECATED = False
|
||||
CATEGORY = CONTINUUM_CATEGORY
|
||||
DESCRIPTION = (
|
||||
"Collects up to three optional still-image references for H3 Continuum "
|
||||
"Easy V3.8. Images are passed unchanged to the existing V3.7 reference "
|
||||
"preprocessing and conditioning path."
|
||||
)
|
||||
SEARCH_ALIASES = [
|
||||
"H3 Continuum Easy References",
|
||||
"MiniMax H3 Easy Reference Images",
|
||||
]
|
||||
RETURN_TYPES = (EASY_REFERENCES_TYPE,)
|
||||
RETURN_NAMES = ("references",)
|
||||
FUNCTION = "pack"
|
||||
|
||||
@classmethod
|
||||
def INPUT_TYPES(cls):
|
||||
return {
|
||||
"optional": {
|
||||
"reference_image_1": (
|
||||
"IMAGE",
|
||||
{"display_name": "Reference Image 1 (Optional)"},
|
||||
),
|
||||
"reference_image_2": (
|
||||
"IMAGE",
|
||||
{"display_name": "Reference Image 2 (Optional)"},
|
||||
),
|
||||
"reference_image_3": (
|
||||
"IMAGE",
|
||||
{"display_name": "Reference Image 3 (Optional)"},
|
||||
),
|
||||
}
|
||||
}
|
||||
|
||||
def pack(
|
||||
self,
|
||||
reference_image_1=None,
|
||||
reference_image_2=None,
|
||||
reference_image_3=None,
|
||||
):
|
||||
return (
|
||||
make_easy_references(
|
||||
reference_image_1=reference_image_1,
|
||||
reference_image_2=reference_image_2,
|
||||
reference_image_3=reference_image_3,
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
class H3ContinuumEasyV38(H3ContinuumSamplerV37):
|
||||
"""Beginner-facing resolver over the unchanged V3.7 Production engine."""
|
||||
|
||||
DEPRECATED = False
|
||||
CATEGORY = CONTINUUM_CATEGORY
|
||||
DESCRIPTION = (
|
||||
"Easy Mode facade over H3 Continuum V3.7 Production. It resolves total "
|
||||
"duration, decimal-MP resolution, seed UI, and image mode without copying "
|
||||
"the sampler or scheduler implementation."
|
||||
)
|
||||
SEARCH_ALIASES = [
|
||||
"H3 Continuum Easy V3.8",
|
||||
"MiniMax H3 Easy Mode",
|
||||
]
|
||||
RETURN_TYPES = (
|
||||
"LATENT",
|
||||
"LATENT",
|
||||
"H3_CONTINUUM_ASSEMBLY_PLAN",
|
||||
"STRING",
|
||||
"AUDIO",
|
||||
)
|
||||
RETURN_NAMES = (
|
||||
"video_latents",
|
||||
"audio_latents",
|
||||
"assembly_plan",
|
||||
"status",
|
||||
"driving_audio",
|
||||
)
|
||||
OUTPUT_IS_LIST = (True, True, False, False, False)
|
||||
FUNCTION = "run"
|
||||
|
||||
@classmethod
|
||||
def INPUT_TYPES(cls):
|
||||
return {
|
||||
"required": {
|
||||
"model": ("MODEL",),
|
||||
"clip": ("CLIP",),
|
||||
"video_vae": (
|
||||
"VAE",
|
||||
{
|
||||
"display_name": "Video VAE",
|
||||
"tooltip": "Used only for connected image conditioning.",
|
||||
},
|
||||
),
|
||||
"sampler": ("SAMPLER",),
|
||||
"sigmas": ("SIGMAS",),
|
||||
"prompt_text": (
|
||||
"STRING",
|
||||
{
|
||||
"default": "",
|
||||
"multiline": True,
|
||||
"dynamicPrompts": True,
|
||||
"display_name": "Prompt",
|
||||
},
|
||||
),
|
||||
"duration": (
|
||||
"INT",
|
||||
{
|
||||
"default": EASY_DURATION_DEFAULT,
|
||||
"min": EASY_DURATION_MIN,
|
||||
"max": EASY_DURATION_MAX,
|
||||
"step": 1,
|
||||
"display_name": "Duration (sec)",
|
||||
},
|
||||
),
|
||||
"seed": (
|
||||
"INT",
|
||||
{
|
||||
"default": 0,
|
||||
"min": 0,
|
||||
"max": 0xFFFFFFFFFFFFFFFF,
|
||||
"control_after_generate": True,
|
||||
"display_name": "Seed",
|
||||
},
|
||||
),
|
||||
"seed_mode": (
|
||||
EASY_SEED_MODE_OPTIONS,
|
||||
{
|
||||
"default": EASY_SEED_MODE_RANDOMIZE,
|
||||
"display_name": "Seed Mode",
|
||||
},
|
||||
),
|
||||
"aspect": (
|
||||
EASY_ASPECT_OPTIONS,
|
||||
{
|
||||
"default": EASY_ASPECT_AUTO,
|
||||
"display_name": "Aspect",
|
||||
},
|
||||
),
|
||||
"preset": (
|
||||
EASY_PRESET_OPTIONS,
|
||||
{
|
||||
"default": EASY_PRESET_DRAFT,
|
||||
"display_name": "Resolution Preset",
|
||||
},
|
||||
),
|
||||
"custom_mp": (
|
||||
"FLOAT",
|
||||
{
|
||||
"default": EASY_CUSTOM_MP_DEFAULT,
|
||||
"min": EASY_CUSTOM_MP_MIN,
|
||||
"max": EASY_CUSTOM_MP_MAX,
|
||||
"step": 0.01,
|
||||
"display_name": "Custom MP",
|
||||
},
|
||||
),
|
||||
"run_storage": (
|
||||
("Off", "Save + Auto Resume"),
|
||||
{
|
||||
"default": "Off",
|
||||
"display_name": "Run Storage",
|
||||
"advanced": True,
|
||||
},
|
||||
),
|
||||
"run_name": (
|
||||
"STRING",
|
||||
{
|
||||
"default": "",
|
||||
"display_name": "Run Name (Optional Override)",
|
||||
"advanced": True,
|
||||
},
|
||||
),
|
||||
"project_id": (
|
||||
"STRING",
|
||||
{
|
||||
"default": "",
|
||||
"display_name": "Auto Resume ID Override",
|
||||
"advanced": True,
|
||||
},
|
||||
),
|
||||
},
|
||||
"optional": {
|
||||
"first_frame": (
|
||||
"IMAGE",
|
||||
{"display_name": "First Image (Optional)"},
|
||||
),
|
||||
"last_frame": (
|
||||
"IMAGE",
|
||||
{"display_name": "Last Image (Optional)"},
|
||||
),
|
||||
"references": (
|
||||
EASY_REFERENCES_TYPE,
|
||||
{"display_name": "Easy References (Optional)"},
|
||||
),
|
||||
"driving_audio": (
|
||||
"AUDIO",
|
||||
{
|
||||
"display_name": "Driving Audio",
|
||||
"tooltip": (
|
||||
"Optional original audio timeline. Uses the unchanged "
|
||||
"V3.7 Driving Audio conditioning and final-output contract."
|
||||
),
|
||||
},
|
||||
),
|
||||
"audio_vae": (
|
||||
"VAE",
|
||||
{
|
||||
"display_name": "Driving Audio VAE",
|
||||
"tooltip": (
|
||||
"Required only when Driving Audio is connected. It may be "
|
||||
"shared with the external Core audio decode path."
|
||||
),
|
||||
},
|
||||
),
|
||||
},
|
||||
"hidden": {
|
||||
"prompt": "PROMPT",
|
||||
"unique_id": "UNIQUE_ID",
|
||||
},
|
||||
}
|
||||
|
||||
def run(
|
||||
self,
|
||||
model,
|
||||
clip,
|
||||
video_vae,
|
||||
sampler,
|
||||
sigmas,
|
||||
prompt_text,
|
||||
duration,
|
||||
seed,
|
||||
seed_mode=EASY_SEED_MODE_RANDOMIZE,
|
||||
aspect=EASY_ASPECT_AUTO,
|
||||
preset=EASY_PRESET_DRAFT,
|
||||
custom_mp=EASY_CUSTOM_MP_DEFAULT,
|
||||
run_storage="Off",
|
||||
run_name="",
|
||||
project_id="",
|
||||
first_frame=None,
|
||||
last_frame=None,
|
||||
references=None,
|
||||
driving_audio=None,
|
||||
audio_vae=None,
|
||||
prompt=None,
|
||||
unique_id=None,
|
||||
):
|
||||
del seed_mode # Queue-time seed mutation remains owned by ComfyUI's frontend.
|
||||
duration_plan = resolve_easy_duration(duration)
|
||||
resolution = resolve_easy_resolution(
|
||||
aspect=aspect,
|
||||
preset=preset,
|
||||
custom_mp=custom_mp,
|
||||
first_frame=first_frame,
|
||||
)
|
||||
reference_image_1, reference_image_2, reference_image_3 = (
|
||||
resolve_easy_references(references)
|
||||
)
|
||||
outputs = super().run(
|
||||
model=model,
|
||||
clip=clip,
|
||||
video_vae=video_vae,
|
||||
sampler=sampler,
|
||||
sigmas=sigmas,
|
||||
sequence_prompt=prompt_text,
|
||||
prompt_mode=PROMPT_FORMAT_AUTO,
|
||||
chunks=duration_plan.chunks,
|
||||
chunk_seconds=duration_plan.chunk_seconds,
|
||||
width=resolution.width,
|
||||
height=resolution.height,
|
||||
continuity=CONTINUITY_OPTIONS[0],
|
||||
base_seed=int(seed),
|
||||
audio_continuity=True,
|
||||
diagnostics=DIAGNOSTICS_BASIC,
|
||||
reroll_from_chunk=REGENERATE_AUTO,
|
||||
reroll_nonce=0,
|
||||
strict_compatibility=False,
|
||||
debug=False,
|
||||
show_preview=True,
|
||||
run_storage=run_storage,
|
||||
run_name=run_name,
|
||||
reference_size=REFERENCE_SIZE_MATCH_OUTPUT,
|
||||
reference_image_1=reference_image_1,
|
||||
reference_image_2=reference_image_2,
|
||||
reference_image_3=reference_image_3,
|
||||
driving_audio=driving_audio,
|
||||
audio_vae=audio_vae,
|
||||
project_id=project_id,
|
||||
first_frame=first_frame,
|
||||
last_frame=last_frame,
|
||||
prompt=prompt,
|
||||
unique_id=unique_id,
|
||||
video_reference_size=REFERENCE_VIDEO_SIZE_EFFICIENT,
|
||||
continuation_backend=CONTINUATION_BACKEND_STANDARD,
|
||||
)
|
||||
video, audio, assembly_plan, status, driving_audio = outputs[:5]
|
||||
mode = conditioning_display_label(
|
||||
has_first=first_frame is not None,
|
||||
has_last=last_frame is not None,
|
||||
has_reference=any(
|
||||
image is not None
|
||||
for image in (
|
||||
reference_image_1,
|
||||
reference_image_2,
|
||||
reference_image_3,
|
||||
)
|
||||
),
|
||||
)
|
||||
warning_lines = "\n".join(resolution.warnings)
|
||||
summary = (
|
||||
f"H3 Continuum Easy V3.8\n"
|
||||
f"{mode} / {duration_plan.duration_seconds} sec\n"
|
||||
f"{resolution.preset}: {resolution.width} x {resolution.height} "
|
||||
f"({resolution.actual_mp:.2f} MP)"
|
||||
)
|
||||
if warning_lines:
|
||||
summary += f"\n{warning_lines}"
|
||||
return video, audio, assembly_plan, f"{summary}\n\n{status}", driving_audio
|
||||
|
||||
|
||||
NODE_CLASS_MAPPINGS = {
|
||||
"H3ContinuumEasyReferences": H3ContinuumEasyReferences,
|
||||
"H3ContinuumEasyV38": H3ContinuumEasyV38,
|
||||
}
|
||||
|
||||
NODE_DISPLAY_NAME_MAPPINGS = {
|
||||
"H3ContinuumEasyReferences": "H3 Continuum Easy References",
|
||||
"H3ContinuumEasyV38": "H3 Continuum Easy V3.8",
|
||||
}
|
||||
@@ -0,0 +1,272 @@
|
||||
"""Simple H3 video loader backed by the current ComfyUI Core video API."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from fractions import Fraction
|
||||
import os
|
||||
|
||||
import torch
|
||||
|
||||
|
||||
try:
|
||||
import folder_paths
|
||||
except ImportError: # pragma: no cover - standalone unit tests
|
||||
class _FolderPathsShim:
|
||||
@staticmethod
|
||||
def get_input_directory():
|
||||
return "."
|
||||
|
||||
@staticmethod
|
||||
def filter_files_content_types(files, content_types):
|
||||
del files, content_types
|
||||
return []
|
||||
|
||||
@staticmethod
|
||||
def get_annotated_filepath(file):
|
||||
raise RuntimeError(f"ComfyUI folder_paths is unavailable for {file}")
|
||||
|
||||
@staticmethod
|
||||
def exists_annotated_filepath(file):
|
||||
del file
|
||||
return False
|
||||
|
||||
folder_paths = _FolderPathsShim()
|
||||
|
||||
try:
|
||||
from comfy_api.latest import InputImpl, io
|
||||
except ImportError: # pragma: no cover - standalone unit tests
|
||||
class _SchemaItem:
|
||||
def __init__(self, item_id=None, **kwargs):
|
||||
self.id = item_id
|
||||
for key, value in kwargs.items():
|
||||
setattr(self, key, value)
|
||||
|
||||
class _InputFactory:
|
||||
Input = _SchemaItem
|
||||
|
||||
class _OutputFactory:
|
||||
@staticmethod
|
||||
def Output(**kwargs):
|
||||
return _SchemaItem(**kwargs)
|
||||
|
||||
class _UploadVideo:
|
||||
value = "video_upload"
|
||||
|
||||
class _UploadType:
|
||||
video = _UploadVideo()
|
||||
|
||||
class _Schema:
|
||||
def __init__(self, **kwargs):
|
||||
for key, value in kwargs.items():
|
||||
setattr(self, key, value)
|
||||
|
||||
class _NodeOutput:
|
||||
def __init__(self, *args):
|
||||
self.args = args
|
||||
|
||||
class _ComfyNode:
|
||||
pass
|
||||
|
||||
class _IOShim:
|
||||
ComfyNode = _ComfyNode
|
||||
Schema = _Schema
|
||||
NodeOutput = _NodeOutput
|
||||
Boolean = _InputFactory
|
||||
Combo = _InputFactory
|
||||
Float = _InputFactory
|
||||
Image = _OutputFactory
|
||||
Audio = _OutputFactory
|
||||
UploadType = _UploadType
|
||||
|
||||
class _InputImplShim:
|
||||
@staticmethod
|
||||
def VideoFromFile(path):
|
||||
raise RuntimeError(f"ComfyUI VideoFromFile is unavailable for {path}")
|
||||
|
||||
InputImpl = _InputImplShim
|
||||
io = _IOShim()
|
||||
|
||||
try:
|
||||
from comfy_execution.graph_utils import ExecutionBlocker
|
||||
except ImportError: # pragma: no cover - standalone unit tests
|
||||
class ExecutionBlocker:
|
||||
def __init__(self, message):
|
||||
self.message = message
|
||||
|
||||
|
||||
CATEGORY = "MiniMax H3/Continuum"
|
||||
|
||||
|
||||
def _fraction_from_rate(value: float) -> Fraction:
|
||||
"""Convert a UI frame-rate value without introducing binary-float drift."""
|
||||
|
||||
return Fraction(str(float(value))).limit_denominator(1_000_000)
|
||||
|
||||
|
||||
def _resample_video_frames(
|
||||
images: torch.Tensor,
|
||||
source_rate: Fraction,
|
||||
target_rate: float,
|
||||
) -> torch.Tensor:
|
||||
"""Drop or duplicate IMAGE frames while preserving nominal duration."""
|
||||
|
||||
if images.ndim != 4:
|
||||
raise ValueError(
|
||||
f"Expected IMAGE batch [B,H,W,C], got shape {tuple(images.shape)}"
|
||||
)
|
||||
|
||||
frame_count = int(images.shape[0])
|
||||
if frame_count <= 0:
|
||||
raise ValueError("Video contains no decodable frames")
|
||||
|
||||
source = Fraction(source_rate)
|
||||
if source <= 0:
|
||||
raise ValueError(f"Invalid source frame rate: {source_rate}")
|
||||
|
||||
requested_rate = float(target_rate)
|
||||
if requested_rate <= 0:
|
||||
return images
|
||||
|
||||
target = _fraction_from_rate(requested_rate)
|
||||
if target == source:
|
||||
return images
|
||||
|
||||
target_count = max(1, round(Fraction(frame_count, 1) * target / source))
|
||||
source_numerator = source.numerator
|
||||
source_denominator = source.denominator
|
||||
target_numerator = target.numerator
|
||||
target_denominator = target.denominator
|
||||
indices = [
|
||||
min(
|
||||
frame_count - 1,
|
||||
(
|
||||
index
|
||||
* source_numerator
|
||||
* target_denominator
|
||||
// (source_denominator * target_numerator)
|
||||
),
|
||||
)
|
||||
for index in range(target_count)
|
||||
]
|
||||
index_tensor = torch.tensor(indices, dtype=torch.long, device=images.device)
|
||||
return images.index_select(0, index_tensor)
|
||||
|
||||
|
||||
def load_video_components(
|
||||
*,
|
||||
file: str,
|
||||
enable_video: bool,
|
||||
force_rate: float,
|
||||
):
|
||||
"""Decode through Core and return standard IMAGE/AUDIO outputs."""
|
||||
|
||||
if not enable_video:
|
||||
blocker = ExecutionBlocker(None)
|
||||
return blocker, blocker
|
||||
|
||||
video_path = folder_paths.get_annotated_filepath(file)
|
||||
components = InputImpl.VideoFromFile(video_path).get_components()
|
||||
images = _resample_video_frames(
|
||||
components.images,
|
||||
Fraction(components.frame_rate),
|
||||
float(force_rate),
|
||||
)
|
||||
audio = components.audio
|
||||
if audio is None:
|
||||
audio = ExecutionBlocker(None)
|
||||
return images, audio
|
||||
|
||||
|
||||
class H3ContinuumLoadVideo(io.ComfyNode):
|
||||
"""Minimal Core-backed video loader for H3 Continuum workflows."""
|
||||
|
||||
@classmethod
|
||||
def define_schema(cls):
|
||||
input_dir = folder_paths.get_input_directory()
|
||||
files = [
|
||||
name
|
||||
for name in os.listdir(input_dir)
|
||||
if os.path.isfile(os.path.join(input_dir, name))
|
||||
]
|
||||
files = folder_paths.filter_files_content_types(files, ["video"])
|
||||
return io.Schema(
|
||||
node_id="H3ContinuumLoadVideo",
|
||||
display_name="H3 Continuum Load Video",
|
||||
category=CATEGORY,
|
||||
description=(
|
||||
"Loads IMAGE and AUDIO through ComfyUI Core VideoFromFile. "
|
||||
"Force Rate drops or duplicates frames without changing duration or audio."
|
||||
),
|
||||
search_aliases=[
|
||||
"H3 Continuum Load Video",
|
||||
"H3 Easy Load Video",
|
||||
"MiniMax H3 Video Loader",
|
||||
],
|
||||
inputs=[
|
||||
io.Boolean.Input(
|
||||
"enable_video",
|
||||
default=True,
|
||||
display_name="Enable Video",
|
||||
),
|
||||
io.Combo.Input(
|
||||
"file",
|
||||
options=sorted(files),
|
||||
upload=io.UploadType.video,
|
||||
display_name="Video",
|
||||
),
|
||||
io.Float.Input(
|
||||
"force_rate",
|
||||
default=24.0,
|
||||
min=0.0,
|
||||
max=120.0,
|
||||
step=0.01,
|
||||
display_name="Force Rate",
|
||||
tooltip=(
|
||||
"0 uses the source FPS. A positive value resamples frames "
|
||||
"while preserving nominal duration."
|
||||
),
|
||||
),
|
||||
],
|
||||
outputs=[
|
||||
io.Image.Output(display_name="images"),
|
||||
io.Audio.Output(display_name="audio"),
|
||||
],
|
||||
)
|
||||
|
||||
@classmethod
|
||||
def execute(cls, enable_video: bool, file: str, force_rate: float):
|
||||
return io.NodeOutput(
|
||||
*load_video_components(
|
||||
file=file,
|
||||
enable_video=bool(enable_video),
|
||||
force_rate=float(force_rate),
|
||||
)
|
||||
)
|
||||
|
||||
@classmethod
|
||||
def fingerprint_inputs(cls, enable_video: bool, file: str, force_rate: float):
|
||||
enabled = bool(enable_video)
|
||||
file_name = str(file)
|
||||
modification_time = None
|
||||
if enabled and folder_paths.exists_annotated_filepath(file_name):
|
||||
video_path = folder_paths.get_annotated_filepath(file_name)
|
||||
modification_time = os.path.getmtime(video_path)
|
||||
return enabled, file_name, float(force_rate), modification_time
|
||||
|
||||
@classmethod
|
||||
def validate_inputs(cls, enable_video: bool, file: str, force_rate: float):
|
||||
del force_rate
|
||||
if not bool(enable_video):
|
||||
return True
|
||||
if not folder_paths.exists_annotated_filepath(file):
|
||||
return f"Invalid video file: {file}"
|
||||
return True
|
||||
|
||||
|
||||
NODE_CLASS_MAPPINGS = {
|
||||
"H3ContinuumLoadVideo": H3ContinuumLoadVideo,
|
||||
}
|
||||
|
||||
NODE_DISPLAY_NAME_MAPPINGS = {
|
||||
"H3ContinuumLoadVideo": "H3 Continuum Load Video",
|
||||
}
|
||||
@@ -0,0 +1,221 @@
|
||||
"""Explicit opt-in A7b memory actions that preserve Production ownership.
|
||||
|
||||
This module resolves only Reference sizing policy. Model unloading and
|
||||
attention/backend selection remain advisory because ComfyUI Core and external
|
||||
MODEL wrappers own those lifecycles.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
import hashlib
|
||||
import json
|
||||
from typing import Any
|
||||
|
||||
from ..reference import REFERENCE_SIZE_MATCH_OUTPUT, REFERENCE_SIZE_MAX_IDENTITY
|
||||
from ..reference_video import (
|
||||
REFERENCE_VIDEO_SIZE_BALANCED,
|
||||
REFERENCE_VIDEO_SIZE_EFFICIENT,
|
||||
REFERENCE_VIDEO_SIZE_MATCH_OUTPUT,
|
||||
)
|
||||
|
||||
|
||||
MEMORY_ACTION_POLICY_TYPE = "H3_CONTINUUM_MEMORY_ACTION_POLICY"
|
||||
MEMORY_ACTION_POLICY_VERSION = 1
|
||||
|
||||
ACTION_DISABLED = "Disabled"
|
||||
ACTION_REDUCE_REFERENCES_ONE_STEP = "Reduce References One Step"
|
||||
ACTION_OPTIONS = (
|
||||
ACTION_DISABLED,
|
||||
ACTION_REDUCE_REFERENCES_ONE_STEP,
|
||||
)
|
||||
|
||||
_IMAGE_DOWNGRADE = {
|
||||
REFERENCE_SIZE_MAX_IDENTITY: REFERENCE_SIZE_MATCH_OUTPUT,
|
||||
REFERENCE_SIZE_MATCH_OUTPUT: REFERENCE_SIZE_MATCH_OUTPUT,
|
||||
}
|
||||
_VIDEO_DOWNGRADE = {
|
||||
REFERENCE_VIDEO_SIZE_MATCH_OUTPUT: REFERENCE_VIDEO_SIZE_BALANCED,
|
||||
REFERENCE_VIDEO_SIZE_BALANCED: REFERENCE_VIDEO_SIZE_EFFICIENT,
|
||||
REFERENCE_VIDEO_SIZE_EFFICIENT: REFERENCE_VIDEO_SIZE_EFFICIENT,
|
||||
}
|
||||
|
||||
|
||||
def _canonical_hash(value: Any) -> str:
|
||||
payload = json.dumps(
|
||||
value,
|
||||
sort_keys=True,
|
||||
separators=(",", ":"),
|
||||
ensure_ascii=True,
|
||||
).encode("utf-8")
|
||||
return hashlib.sha256(payload).hexdigest()
|
||||
|
||||
|
||||
def _contract_base(action: str) -> dict[str, Any]:
|
||||
return {
|
||||
"memory_action_policy_version": MEMORY_ACTION_POLICY_VERSION,
|
||||
"action": action,
|
||||
"reference_downgrade": (
|
||||
"one_step"
|
||||
if action == ACTION_REDUCE_REFERENCES_ONE_STEP
|
||||
else "disabled"
|
||||
),
|
||||
"auto_unload": "advisory_only",
|
||||
"backend_switch": "advisory_only",
|
||||
"same_run_actual_row_trigger": False,
|
||||
}
|
||||
|
||||
|
||||
def make_memory_action_policy(action: str = ACTION_DISABLED) -> dict[str, Any]:
|
||||
"""Build the versioned policy object emitted by the public helper node."""
|
||||
|
||||
normalized = str(action)
|
||||
if normalized not in ACTION_OPTIONS:
|
||||
raise ValueError(f"unsupported memory action {action!r}")
|
||||
contract = _contract_base(normalized)
|
||||
return {**contract, "contract_hash": _canonical_hash(contract)}
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class MemoryActionDecision:
|
||||
action: str
|
||||
enabled: bool
|
||||
requested_image_mode: str
|
||||
effective_image_mode: str
|
||||
requested_video_mode: str
|
||||
effective_video_mode: str
|
||||
image_applied: bool
|
||||
video_applied: bool
|
||||
contract_hash: str | None
|
||||
warning: str | None = None
|
||||
|
||||
@property
|
||||
def applied(self) -> bool:
|
||||
return bool(self.image_applied or self.video_applied)
|
||||
|
||||
|
||||
def _disabled_decision(
|
||||
*,
|
||||
image_mode: str,
|
||||
video_mode: str,
|
||||
contract_hash: str | None = None,
|
||||
warning: str | None = None,
|
||||
) -> MemoryActionDecision:
|
||||
return MemoryActionDecision(
|
||||
action=ACTION_DISABLED,
|
||||
enabled=False,
|
||||
requested_image_mode=image_mode,
|
||||
effective_image_mode=image_mode,
|
||||
requested_video_mode=video_mode,
|
||||
effective_video_mode=video_mode,
|
||||
image_applied=False,
|
||||
video_applied=False,
|
||||
contract_hash=contract_hash,
|
||||
warning=warning,
|
||||
)
|
||||
|
||||
|
||||
def resolve_memory_action_policy(
|
||||
policy: Any,
|
||||
*,
|
||||
image_mode: str,
|
||||
video_mode: str,
|
||||
has_reference_images: bool,
|
||||
has_video_guide: bool,
|
||||
) -> MemoryActionDecision:
|
||||
"""Resolve an optional policy without changing tensors or runtime state.
|
||||
|
||||
Malformed or unsupported objects fail soft to Disabled. The caller may
|
||||
surface ``warning`` after generation, but Sampling inputs remain unchanged.
|
||||
"""
|
||||
|
||||
requested_image = str(image_mode)
|
||||
requested_video = str(video_mode)
|
||||
if policy is None:
|
||||
return _disabled_decision(
|
||||
image_mode=requested_image,
|
||||
video_mode=requested_video,
|
||||
)
|
||||
if not isinstance(policy, dict):
|
||||
return _disabled_decision(
|
||||
image_mode=requested_image,
|
||||
video_mode=requested_video,
|
||||
warning="invalid policy object; no memory action was applied",
|
||||
)
|
||||
|
||||
action = str(policy.get("action", ""))
|
||||
try:
|
||||
version = int(policy.get("memory_action_policy_version"))
|
||||
except (TypeError, ValueError):
|
||||
version = -1
|
||||
supplied_hash = policy.get("contract_hash")
|
||||
expected_contract = _contract_base(action) if action in ACTION_OPTIONS else None
|
||||
expected_hash = (
|
||||
_canonical_hash(expected_contract) if expected_contract is not None else None
|
||||
)
|
||||
if (
|
||||
version != MEMORY_ACTION_POLICY_VERSION
|
||||
or action not in ACTION_OPTIONS
|
||||
or not isinstance(supplied_hash, str)
|
||||
or supplied_hash != expected_hash
|
||||
):
|
||||
return _disabled_decision(
|
||||
image_mode=requested_image,
|
||||
video_mode=requested_video,
|
||||
warning="unsupported or modified policy contract; no memory action was applied",
|
||||
)
|
||||
if action == ACTION_DISABLED:
|
||||
return _disabled_decision(
|
||||
image_mode=requested_image,
|
||||
video_mode=requested_video,
|
||||
contract_hash=supplied_hash,
|
||||
)
|
||||
|
||||
effective_image = requested_image
|
||||
effective_video = requested_video
|
||||
if bool(has_reference_images):
|
||||
effective_image = _IMAGE_DOWNGRADE.get(requested_image, requested_image)
|
||||
if bool(has_video_guide):
|
||||
effective_video = _VIDEO_DOWNGRADE.get(requested_video, requested_video)
|
||||
return MemoryActionDecision(
|
||||
action=action,
|
||||
enabled=True,
|
||||
requested_image_mode=requested_image,
|
||||
effective_image_mode=effective_image,
|
||||
requested_video_mode=requested_video,
|
||||
effective_video_mode=effective_video,
|
||||
image_applied=(
|
||||
bool(has_reference_images) and effective_image != requested_image
|
||||
),
|
||||
video_applied=(bool(has_video_guide) and effective_video != requested_video),
|
||||
contract_hash=supplied_hash,
|
||||
)
|
||||
|
||||
|
||||
def format_memory_action_status(decision: MemoryActionDecision) -> str | None:
|
||||
"""Format post-generation status without claiming VRAM prediction."""
|
||||
|
||||
if decision.warning is not None:
|
||||
return "Memory Action Policy [Experimental A7b v1]: " + decision.warning + "."
|
||||
if not decision.enabled:
|
||||
return None
|
||||
changes: list[str] = []
|
||||
if decision.image_applied:
|
||||
changes.append(
|
||||
"Reference Image "
|
||||
f"{decision.requested_image_mode} -> {decision.effective_image_mode}"
|
||||
)
|
||||
if decision.video_applied:
|
||||
changes.append(
|
||||
"Video Guide "
|
||||
f"{decision.requested_video_mode} -> {decision.effective_video_mode}"
|
||||
)
|
||||
action = "; ".join(changes) if changes else "no applicable Reference downgrade"
|
||||
return (
|
||||
"Memory Action Policy [Experimental A7b v1]: explicit opt-in; "
|
||||
f"{action}.\n"
|
||||
"Memory advisory: automatic MODEL unload was not executed; Core retains "
|
||||
"lifecycle ownership.\n"
|
||||
"Memory advisory: automatic attention/backend switching was not executed; "
|
||||
"the external MODEL wrapper was preserved."
|
||||
)
|
||||
+949
-710
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,349 @@
|
||||
"""Read-only A7a planning from actual ComfyUI H3 PackedLayout rows.
|
||||
|
||||
The planner observes layouts that ComfyUI Core already built for Sampling. It
|
||||
does not estimate VRAM, change execution policy, mutate a layout, or influence
|
||||
the physical-group order. Memory counters are point-in-time observations only.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
from typing import Any, Callable
|
||||
|
||||
|
||||
PACKED_ROW_PLAN_VERSION = 1
|
||||
MAX_CONCURRENT_PHYSICAL_GROUPS = 1
|
||||
|
||||
_VIDEO_CONDITION_KINDS = frozenset(("cond", "ref_img"))
|
||||
_AUDIO_CONDITION_KINDS = frozenset(("cond_audio", "ref_audio"))
|
||||
|
||||
|
||||
class PackedRowPlanningError(ValueError):
|
||||
"""An observed object is not an internally consistent H3 PackedLayout."""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class PackedRowBreakdown:
|
||||
seq_len: int
|
||||
text_rows: int
|
||||
condition_video_rows: int
|
||||
condition_audio_rows: int
|
||||
target_video_rows: int
|
||||
target_audio_rows: int
|
||||
unknown_rows: int
|
||||
segment_count: int
|
||||
segment_signature: tuple[tuple[int, int, str], ...]
|
||||
|
||||
@property
|
||||
def condition_rows(self) -> int:
|
||||
return int(self.condition_video_rows + self.condition_audio_rows)
|
||||
|
||||
@property
|
||||
def target_rows(self) -> int:
|
||||
return int(self.target_video_rows + self.target_audio_rows)
|
||||
|
||||
@property
|
||||
def condition_to_target_ratio(self) -> float | None:
|
||||
if self.target_rows <= 0:
|
||||
return None
|
||||
return float(self.condition_rows / self.target_rows)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class MemoryObservation:
|
||||
system_available_bytes: int | None = None
|
||||
cuda_allocated_bytes: int | None = None
|
||||
cuda_reserved_bytes: int | None = None
|
||||
core_visible_free_bytes: int | None = None
|
||||
|
||||
|
||||
def analyze_packed_layout(layout: Any) -> PackedRowBreakdown:
|
||||
"""Account actual rows without importing or recreating Core PackedLayout."""
|
||||
|
||||
if layout is None:
|
||||
raise PackedRowPlanningError("Core PackedLayout is unavailable")
|
||||
try:
|
||||
seq_len = int(layout.seq_len)
|
||||
raw_segments = tuple(layout.segments)
|
||||
except Exception as exc:
|
||||
raise PackedRowPlanningError(
|
||||
"Core PackedLayout does not expose seq_len/segments"
|
||||
) from exc
|
||||
if seq_len <= 0 or not raw_segments:
|
||||
raise PackedRowPlanningError("Core PackedLayout is empty")
|
||||
|
||||
signature: list[tuple[int, int, str]] = []
|
||||
previous_stop = 0
|
||||
counts = {
|
||||
"text": 0,
|
||||
"condition_video": 0,
|
||||
"condition_audio": 0,
|
||||
"target_video": 0,
|
||||
"target_audio": 0,
|
||||
"unknown": 0,
|
||||
}
|
||||
target_video_segments = 0
|
||||
target_audio_segments = 0
|
||||
for item in raw_segments:
|
||||
if not isinstance(item, (tuple, list)) or len(item) != 3:
|
||||
raise PackedRowPlanningError("PackedLayout segment is not (start, stop, kind)")
|
||||
start, stop, kind = int(item[0]), int(item[1]), str(item[2])
|
||||
if start != previous_stop or stop <= start or stop > seq_len:
|
||||
raise PackedRowPlanningError(
|
||||
"PackedLayout segments are not a contiguous in-range partition"
|
||||
)
|
||||
rows = stop - start
|
||||
signature.append((start, stop, kind))
|
||||
if kind == "text":
|
||||
counts["text"] += rows
|
||||
elif kind in _VIDEO_CONDITION_KINDS:
|
||||
counts["condition_video"] += rows
|
||||
elif kind in _AUDIO_CONDITION_KINDS:
|
||||
counts["condition_audio"] += rows
|
||||
elif kind == "video":
|
||||
counts["target_video"] += rows
|
||||
target_video_segments += 1
|
||||
elif kind == "audio":
|
||||
counts["target_audio"] += rows
|
||||
target_audio_segments += 1
|
||||
else:
|
||||
counts["unknown"] += rows
|
||||
previous_stop = stop
|
||||
if previous_stop != seq_len:
|
||||
raise PackedRowPlanningError("PackedLayout segment rows do not sum to seq_len")
|
||||
if target_video_segments != 1 or target_audio_segments != 1:
|
||||
raise PackedRowPlanningError(
|
||||
"H3 PackedLayout must contain exactly one target Video and Audio segment"
|
||||
)
|
||||
return PackedRowBreakdown(
|
||||
seq_len=seq_len,
|
||||
text_rows=int(counts["text"]),
|
||||
condition_video_rows=int(counts["condition_video"]),
|
||||
condition_audio_rows=int(counts["condition_audio"]),
|
||||
target_video_rows=int(counts["target_video"]),
|
||||
target_audio_rows=int(counts["target_audio"]),
|
||||
unknown_rows=int(counts["unknown"]),
|
||||
segment_count=len(signature),
|
||||
segment_signature=tuple(signature),
|
||||
)
|
||||
|
||||
|
||||
def read_memory_observation() -> MemoryObservation:
|
||||
"""Read counters without CUDA synchronization, cache clearing, or peak reset."""
|
||||
|
||||
system_available = None
|
||||
cuda_allocated = None
|
||||
cuda_reserved = None
|
||||
core_free = None
|
||||
try:
|
||||
import psutil
|
||||
|
||||
system_available = int(psutil.virtual_memory().available)
|
||||
except Exception:
|
||||
pass
|
||||
try:
|
||||
import torch
|
||||
|
||||
if torch.cuda.is_available():
|
||||
cuda_allocated = int(torch.cuda.memory_allocated())
|
||||
cuda_reserved = int(torch.cuda.memory_reserved())
|
||||
except Exception:
|
||||
pass
|
||||
try:
|
||||
import comfy.model_management as model_management
|
||||
|
||||
device = model_management.get_torch_device()
|
||||
core_free = int(model_management.get_free_memory(device))
|
||||
except Exception:
|
||||
pass
|
||||
return MemoryObservation(
|
||||
system_available_bytes=system_available,
|
||||
cuda_allocated_bytes=cuda_allocated,
|
||||
cuda_reserved_bytes=cuda_reserved,
|
||||
core_visible_free_bytes=core_free,
|
||||
)
|
||||
|
||||
|
||||
def _safe_memory_read(reader: Callable[[], MemoryObservation]) -> MemoryObservation:
|
||||
try:
|
||||
value = reader()
|
||||
return value if isinstance(value, MemoryObservation) else MemoryObservation()
|
||||
except Exception:
|
||||
return MemoryObservation()
|
||||
|
||||
|
||||
class PackedRowPlanner:
|
||||
"""Collect one immutable actual-layout plan record per sampled group."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
*,
|
||||
memory_reader: Callable[[], MemoryObservation] = read_memory_observation,
|
||||
) -> None:
|
||||
self._memory_reader = memory_reader
|
||||
self._active: dict[str, Any] | None = None
|
||||
self._records: list[dict[str, Any]] = []
|
||||
self._advisories: list[str] = []
|
||||
|
||||
@property
|
||||
def records(self) -> tuple[dict[str, Any], ...]:
|
||||
return tuple(self._records)
|
||||
|
||||
def begin_group(
|
||||
self,
|
||||
*,
|
||||
physical_group: int,
|
||||
logical_chunks: tuple[int, ...],
|
||||
terminal_atomic: bool,
|
||||
) -> None:
|
||||
if self._active is not None:
|
||||
self._advisories.append(
|
||||
"a group began before the prior observation was finalized"
|
||||
)
|
||||
self.finish_group()
|
||||
self._active = {
|
||||
"physical_group": int(physical_group),
|
||||
"logical_chunks": tuple(int(value) for value in logical_chunks),
|
||||
"terminal_atomic": bool(terminal_atomic),
|
||||
"pre_memory": _safe_memory_read(self._memory_reader),
|
||||
"breakdown": None,
|
||||
"unavailable": None,
|
||||
}
|
||||
|
||||
def observe_layout(self, layout: Any) -> None:
|
||||
if self._active is None:
|
||||
return
|
||||
try:
|
||||
observed = analyze_packed_layout(layout)
|
||||
except Exception as exc:
|
||||
if self._active["breakdown"] is None:
|
||||
self._active["unavailable"] = f"{type(exc).__name__}: {exc}"
|
||||
return
|
||||
current = self._active["breakdown"]
|
||||
if current is not None and current != observed:
|
||||
self._active["unavailable"] = (
|
||||
"PackedLayout topology changed within one physical group"
|
||||
)
|
||||
self._active["breakdown"] = None
|
||||
return
|
||||
if self._active["unavailable"] is None:
|
||||
self._active["breakdown"] = observed
|
||||
|
||||
def note_observation_failure(self, exc: Exception) -> None:
|
||||
if self._active is not None and self._active["breakdown"] is None:
|
||||
self._active["unavailable"] = f"{type(exc).__name__}: {exc}"
|
||||
|
||||
def finish_group(self) -> None:
|
||||
if self._active is None:
|
||||
return
|
||||
record = dict(self._active)
|
||||
record["post_memory"] = _safe_memory_read(self._memory_reader)
|
||||
if record["breakdown"] is None and record["unavailable"] is None:
|
||||
record["unavailable"] = "Core PackedLayout was not observed"
|
||||
self._records.append(record)
|
||||
self._active = None
|
||||
|
||||
@staticmethod
|
||||
def _mib(value: int | None) -> str:
|
||||
return "n/a" if value is None else f"{int(value) / 1024**2:.1f} MiB"
|
||||
|
||||
def report_lines(self) -> list[str]:
|
||||
if self._active is not None:
|
||||
self.finish_group()
|
||||
valid = [record for record in self._records if record["breakdown"] is not None]
|
||||
peak = None
|
||||
if valid:
|
||||
peak = max(valid, key=lambda record: record["breakdown"].seq_len)
|
||||
order = [int(record["physical_group"]) for record in self._records]
|
||||
lines = [
|
||||
"Packed-row plan [A7a v1]: "
|
||||
f"execution_order={order}, "
|
||||
f"max_concurrent_physical_groups={MAX_CONCURRENT_PHYSICAL_GROUPS}, "
|
||||
f"observed_groups={len(valid)}/{len(self._records)}, "
|
||||
f"peak_candidate={int(peak['physical_group']) if peak else 'unavailable'}, "
|
||||
f"peak_total_rows={peak['breakdown'].seq_len if peak else 'unavailable'}; "
|
||||
"actual Core rows only, VRAM/time prediction=not provided, "
|
||||
"execution policy=unchanged."
|
||||
]
|
||||
for record in self._records:
|
||||
group = int(record["physical_group"])
|
||||
logical = list(record["logical_chunks"])
|
||||
breakdown = record["breakdown"]
|
||||
if breakdown is None:
|
||||
lines.append(
|
||||
"Packed-row group [A7a v1]: "
|
||||
f"physical_group={group}, logical_chunks={logical}, "
|
||||
f"terminal_atomic={str(bool(record['terminal_atomic'])).lower()}, "
|
||||
f"unavailable/advisory={record['unavailable']}."
|
||||
)
|
||||
continue
|
||||
pre = record["pre_memory"]
|
||||
post = record["post_memory"]
|
||||
ratio = breakdown.condition_to_target_ratio
|
||||
ratio_text = "n/a" if ratio is None else f"{ratio:.6f}"
|
||||
lines.append(
|
||||
"Packed-row group [A7a v1]: "
|
||||
f"physical_group={group}, logical_chunks={logical}, "
|
||||
f"terminal_atomic={str(bool(record['terminal_atomic'])).lower()}, "
|
||||
f"total={breakdown.seq_len}, text={breakdown.text_rows}, "
|
||||
f"condition_video={breakdown.condition_video_rows}, "
|
||||
f"condition_audio={breakdown.condition_audio_rows}, "
|
||||
f"target_video={breakdown.target_video_rows}, "
|
||||
f"target_audio={breakdown.target_audio_rows}, "
|
||||
f"unknown={breakdown.unknown_rows}, "
|
||||
f"condition_to_target_ratio={ratio_text}, "
|
||||
f"pre_system_available={self._mib(pre.system_available_bytes)}, "
|
||||
f"pre_CUDA_allocated={self._mib(pre.cuda_allocated_bytes)}, "
|
||||
f"pre_CUDA_reserved={self._mib(pre.cuda_reserved_bytes)}, "
|
||||
f"pre_Core_free={self._mib(pre.core_visible_free_bytes)}, "
|
||||
f"post_system_available={self._mib(post.system_available_bytes)}, "
|
||||
f"post_CUDA_allocated={self._mib(post.cuda_allocated_bytes)}, "
|
||||
f"post_CUDA_reserved={self._mib(post.cuda_reserved_bytes)}, "
|
||||
f"post_Core_free={self._mib(post.core_visible_free_bytes)}."
|
||||
)
|
||||
lines.extend(f"Packed-row advisory [A7a v1]: {item}." for item in self._advisories)
|
||||
return lines
|
||||
|
||||
|
||||
def observe_layout_fail_soft(planner: Any, payload: Any) -> None:
|
||||
"""Diagnostics must never replace a Sampling result."""
|
||||
|
||||
if planner is None:
|
||||
return
|
||||
try:
|
||||
layout = payload.get("layout") if isinstance(payload, dict) else None
|
||||
planner.observe_layout(layout)
|
||||
except Exception as exc:
|
||||
try:
|
||||
planner.note_observation_failure(exc)
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
|
||||
def planner_event_fail_soft(planner: Any, method: str, **kwargs: Any) -> Any:
|
||||
"""Invoke one lifecycle event without allowing diagnostics to stop Sampling."""
|
||||
|
||||
if planner is None:
|
||||
return None
|
||||
try:
|
||||
return getattr(planner, str(method))(**kwargs)
|
||||
except Exception as exc:
|
||||
try:
|
||||
planner.note_observation_failure(exc)
|
||||
except Exception:
|
||||
pass
|
||||
return None
|
||||
|
||||
|
||||
__all__ = [
|
||||
"MAX_CONCURRENT_PHYSICAL_GROUPS",
|
||||
"MemoryObservation",
|
||||
"PACKED_ROW_PLAN_VERSION",
|
||||
"PackedRowBreakdown",
|
||||
"PackedRowPlanner",
|
||||
"PackedRowPlanningError",
|
||||
"analyze_packed_layout",
|
||||
"observe_layout_fail_soft",
|
||||
"planner_event_fail_soft",
|
||||
"read_memory_observation",
|
||||
]
|
||||
+281
-281
@@ -1,205 +1,205 @@
|
||||
"""Assembly-plan contract for latent-first H3 Continuum V3."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
import torch
|
||||
|
||||
from ..state import validate_plan
|
||||
|
||||
"""Assembly-plan contract for latent-first H3 Continuum V3."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
import torch
|
||||
|
||||
from ..state import validate_plan
|
||||
|
||||
ASSEMBLY_PLAN_MAGIC = "H3_CONTINUUM_ASSEMBLY_PLAN"
|
||||
ASSEMBLY_PLAN_SCHEMA_VERSION = 1
|
||||
FPS = 24
|
||||
SECOND_PASS_CONTRACT_VERSION = 1
|
||||
|
||||
|
||||
class AssemblyPlanError(ValueError):
|
||||
pass
|
||||
|
||||
|
||||
def make_assembly_plan(
|
||||
entries: list[dict[str, Any]],
|
||||
*,
|
||||
chunk_seconds: float,
|
||||
preserve_final_frame: bool,
|
||||
) -> dict[str, Any]:
|
||||
if not entries:
|
||||
raise AssemblyPlanError("cannot create an assembly plan for an empty sequence")
|
||||
|
||||
chunks: list[dict[str, Any]] = []
|
||||
width = height = None
|
||||
for sequence_index, entry in enumerate(entries, start=1):
|
||||
if not isinstance(entry, dict):
|
||||
raise AssemblyPlanError(f"chunk {sequence_index} entry is not a dictionary")
|
||||
plan = validate_plan(entry.get("plan"))
|
||||
video = entry.get("video")
|
||||
audio = entry.get("audio")
|
||||
if not torch.is_tensor(video) or video.ndim < 3:
|
||||
raise AssemblyPlanError(f"chunk {sequence_index} video latent is invalid")
|
||||
if not torch.is_tensor(audio) or audio.ndim < 3:
|
||||
raise AssemblyPlanError(f"chunk {sequence_index} audio latent is invalid")
|
||||
|
||||
plan_width = int(plan["width"])
|
||||
plan_height = int(plan["height"])
|
||||
if width is None:
|
||||
width, height = plan_width, plan_height
|
||||
elif (plan_width, plan_height) != (width, height):
|
||||
raise AssemblyPlanError("chunk dimensions changed within the sequence")
|
||||
|
||||
chunks.append(
|
||||
{
|
||||
"sequence_index": sequence_index,
|
||||
"chunk_index": int(plan["clip_index"]),
|
||||
"total_frames": int(plan["total_frames"]),
|
||||
"trim_frames": int(plan["trim_frames"]),
|
||||
"net_frames": int(plan["net_frames"]),
|
||||
"context_frames": int(plan["context_frames"]),
|
||||
"expected_video_latent_t": int(video.shape[2]),
|
||||
"expected_audio_latent_t": int(audio.shape[-1]),
|
||||
}
|
||||
)
|
||||
|
||||
result = {
|
||||
"magic": ASSEMBLY_PLAN_MAGIC,
|
||||
"schema_version": ASSEMBLY_PLAN_SCHEMA_VERSION,
|
||||
"fps": FPS,
|
||||
"width": int(width),
|
||||
"height": int(height),
|
||||
"chunk_seconds": float(chunk_seconds),
|
||||
"target_frames": int(round(len(chunks) * float(chunk_seconds) * FPS)),
|
||||
"preserve_final_frame": bool(preserve_final_frame),
|
||||
"chunks": chunks,
|
||||
}
|
||||
return validate_assembly_plan(result)
|
||||
|
||||
|
||||
def validate_assembly_plan(plan: Any) -> dict[str, Any]:
|
||||
if not isinstance(plan, dict) or plan.get("magic") != ASSEMBLY_PLAN_MAGIC:
|
||||
raise AssemblyPlanError("invalid H3 Continuum V3 assembly plan")
|
||||
if (
|
||||
type(plan.get("schema_version")) is not int
|
||||
or plan["schema_version"] != ASSEMBLY_PLAN_SCHEMA_VERSION
|
||||
):
|
||||
raise AssemblyPlanError(
|
||||
f"unsupported assembly plan schema {plan.get('schema_version')!r}"
|
||||
)
|
||||
if int(plan.get("fps", 0)) != FPS:
|
||||
raise AssemblyPlanError("assembly plan FPS must be 24")
|
||||
if int(plan.get("width", 0)) <= 0 or int(plan.get("height", 0)) <= 0:
|
||||
raise AssemblyPlanError("assembly plan dimensions are invalid")
|
||||
if float(plan.get("chunk_seconds", 0.0)) <= 0:
|
||||
raise AssemblyPlanError("assembly plan chunk duration is invalid")
|
||||
if int(plan.get("target_frames", 0)) <= 0:
|
||||
raise AssemblyPlanError("assembly plan target frame count is invalid")
|
||||
|
||||
chunks = plan.get("chunks")
|
||||
if not isinstance(chunks, list) or not chunks:
|
||||
raise AssemblyPlanError("assembly plan contains no chunks")
|
||||
for expected_index, chunk in enumerate(chunks, start=1):
|
||||
if not isinstance(chunk, dict):
|
||||
raise AssemblyPlanError(f"assembly chunk {expected_index} is invalid")
|
||||
if int(chunk.get("sequence_index", 0)) != expected_index:
|
||||
raise AssemblyPlanError("assembly chunk order is not contiguous")
|
||||
total = int(chunk.get("total_frames", 0))
|
||||
trim = int(chunk.get("trim_frames", -1))
|
||||
net = int(chunk.get("net_frames", 0))
|
||||
if total <= 0 or trim < 0 or net <= 0 or total - trim != net:
|
||||
raise AssemblyPlanError(
|
||||
f"assembly chunk {expected_index} frame plan is invalid"
|
||||
)
|
||||
if int(chunk.get("context_frames", -1)) < 0:
|
||||
raise AssemblyPlanError(
|
||||
f"assembly chunk {expected_index} context is invalid"
|
||||
)
|
||||
if int(chunk.get("expected_video_latent_t", 0)) <= 0:
|
||||
raise AssemblyPlanError(
|
||||
f"assembly chunk {expected_index} video latent length is invalid"
|
||||
)
|
||||
if int(chunk.get("expected_audio_latent_t", 0)) <= 0:
|
||||
raise AssemblyPlanError(
|
||||
f"assembly chunk {expected_index} audio latent length is invalid"
|
||||
)
|
||||
return plan
|
||||
# V3.0.1 hardening integration: redundant metadata plus fail-closed validation.
|
||||
from ..hardening import (
|
||||
enrich_assembly_plan as _enrich_assembly_plan,
|
||||
validate_assembly_plan_contract as _validate_assembly_plan_contract,
|
||||
)
|
||||
|
||||
_make_assembly_plan_v300 = make_assembly_plan
|
||||
_validate_assembly_plan_v300 = validate_assembly_plan
|
||||
|
||||
|
||||
def validate_assembly_plan(plan):
|
||||
result = _validate_assembly_plan_v300(plan)
|
||||
_validate_assembly_plan_contract(plan)
|
||||
return result
|
||||
|
||||
|
||||
def make_assembly_plan(*args, **kwargs):
|
||||
plan = _make_assembly_plan_v300(*args, **kwargs)
|
||||
_enrich_assembly_plan(plan)
|
||||
validate_assembly_plan(plan)
|
||||
return plan
|
||||
|
||||
|
||||
def _recombine_terminal_tensor(
|
||||
first,
|
||||
second,
|
||||
*,
|
||||
slices,
|
||||
time_dim: int,
|
||||
name: str,
|
||||
):
|
||||
"""Invert the terminal logical split without changing any tensor value."""
|
||||
|
||||
import torch
|
||||
|
||||
if not torch.is_tensor(first) or not torch.is_tensor(second):
|
||||
raise ValueError(f"terminal {name} entries must be tensors")
|
||||
if first.ndim != second.ndim:
|
||||
raise ValueError(f"terminal {name} tensor ranks differ")
|
||||
dim = int(time_dim)
|
||||
if dim < 0:
|
||||
dim += first.ndim
|
||||
if dim < 0 or dim >= first.ndim:
|
||||
raise ValueError(f"terminal {name} time dimension is invalid")
|
||||
for axis, (left, right) in enumerate(zip(first.shape, second.shape)):
|
||||
if axis != dim and int(left) != int(right):
|
||||
raise ValueError(f"terminal {name} tensor geometry differs")
|
||||
|
||||
(first_start, first_stop), (second_start, second_stop) = slices
|
||||
first_start = int(first_start)
|
||||
first_stop = int(first_stop)
|
||||
second_start = int(second_start)
|
||||
second_stop = int(second_stop)
|
||||
if first_start != 0 or second_start > first_stop or second_stop <= first_stop:
|
||||
raise ValueError(f"terminal {name} split ranges do not form one physical unit")
|
||||
if int(first.shape[dim]) != first_stop - first_start:
|
||||
raise ValueError(f"terminal {name} first slice length is inconsistent")
|
||||
if int(second.shape[dim]) != second_stop - second_start:
|
||||
raise ValueError(f"terminal {name} second slice length is inconsistent")
|
||||
|
||||
overlap_start = max(first_start, second_start)
|
||||
overlap_stop = min(first_stop, second_stop)
|
||||
overlap_length = max(0, overlap_stop - overlap_start)
|
||||
if overlap_length:
|
||||
first_overlap = first.narrow(dim, overlap_start - first_start, overlap_length)
|
||||
second_overlap = second.narrow(dim, overlap_start - second_start, overlap_length)
|
||||
if not torch.equal(first_overlap, second_overlap):
|
||||
raise ValueError(
|
||||
f"terminal {name} overlap differs; refusing lossy physical reconstruction"
|
||||
)
|
||||
|
||||
output_shape = list(first.shape)
|
||||
output_shape[dim] = second_stop
|
||||
output = first.new_empty(output_shape)
|
||||
output.narrow(dim, first_start, first_stop - first_start).copy_(first)
|
||||
output.narrow(dim, second_start, second_stop - second_start).copy_(second)
|
||||
return output.contiguous()
|
||||
|
||||
|
||||
|
||||
|
||||
class AssemblyPlanError(ValueError):
|
||||
pass
|
||||
|
||||
|
||||
def make_assembly_plan(
|
||||
entries: list[dict[str, Any]],
|
||||
*,
|
||||
chunk_seconds: float,
|
||||
preserve_final_frame: bool,
|
||||
) -> dict[str, Any]:
|
||||
if not entries:
|
||||
raise AssemblyPlanError("cannot create an assembly plan for an empty sequence")
|
||||
|
||||
chunks: list[dict[str, Any]] = []
|
||||
width = height = None
|
||||
for sequence_index, entry in enumerate(entries, start=1):
|
||||
if not isinstance(entry, dict):
|
||||
raise AssemblyPlanError(f"chunk {sequence_index} entry is not a dictionary")
|
||||
plan = validate_plan(entry.get("plan"))
|
||||
video = entry.get("video")
|
||||
audio = entry.get("audio")
|
||||
if not torch.is_tensor(video) or video.ndim < 3:
|
||||
raise AssemblyPlanError(f"chunk {sequence_index} video latent is invalid")
|
||||
if not torch.is_tensor(audio) or audio.ndim < 3:
|
||||
raise AssemblyPlanError(f"chunk {sequence_index} audio latent is invalid")
|
||||
|
||||
plan_width = int(plan["width"])
|
||||
plan_height = int(plan["height"])
|
||||
if width is None:
|
||||
width, height = plan_width, plan_height
|
||||
elif (plan_width, plan_height) != (width, height):
|
||||
raise AssemblyPlanError("chunk dimensions changed within the sequence")
|
||||
|
||||
chunks.append(
|
||||
{
|
||||
"sequence_index": sequence_index,
|
||||
"chunk_index": int(plan["clip_index"]),
|
||||
"total_frames": int(plan["total_frames"]),
|
||||
"trim_frames": int(plan["trim_frames"]),
|
||||
"net_frames": int(plan["net_frames"]),
|
||||
"context_frames": int(plan["context_frames"]),
|
||||
"expected_video_latent_t": int(video.shape[2]),
|
||||
"expected_audio_latent_t": int(audio.shape[-1]),
|
||||
}
|
||||
)
|
||||
|
||||
result = {
|
||||
"magic": ASSEMBLY_PLAN_MAGIC,
|
||||
"schema_version": ASSEMBLY_PLAN_SCHEMA_VERSION,
|
||||
"fps": FPS,
|
||||
"width": int(width),
|
||||
"height": int(height),
|
||||
"chunk_seconds": float(chunk_seconds),
|
||||
"target_frames": int(round(len(chunks) * float(chunk_seconds) * FPS)),
|
||||
"preserve_final_frame": bool(preserve_final_frame),
|
||||
"chunks": chunks,
|
||||
}
|
||||
return validate_assembly_plan(result)
|
||||
|
||||
|
||||
def validate_assembly_plan(plan: Any) -> dict[str, Any]:
|
||||
if not isinstance(plan, dict) or plan.get("magic") != ASSEMBLY_PLAN_MAGIC:
|
||||
raise AssemblyPlanError("invalid H3 Continuum V3 assembly plan")
|
||||
if (
|
||||
type(plan.get("schema_version")) is not int
|
||||
or plan["schema_version"] != ASSEMBLY_PLAN_SCHEMA_VERSION
|
||||
):
|
||||
raise AssemblyPlanError(
|
||||
f"unsupported assembly plan schema {plan.get('schema_version')!r}"
|
||||
)
|
||||
if int(plan.get("fps", 0)) != FPS:
|
||||
raise AssemblyPlanError("assembly plan FPS must be 24")
|
||||
if int(plan.get("width", 0)) <= 0 or int(plan.get("height", 0)) <= 0:
|
||||
raise AssemblyPlanError("assembly plan dimensions are invalid")
|
||||
if float(plan.get("chunk_seconds", 0.0)) <= 0:
|
||||
raise AssemblyPlanError("assembly plan chunk duration is invalid")
|
||||
if int(plan.get("target_frames", 0)) <= 0:
|
||||
raise AssemblyPlanError("assembly plan target frame count is invalid")
|
||||
|
||||
chunks = plan.get("chunks")
|
||||
if not isinstance(chunks, list) or not chunks:
|
||||
raise AssemblyPlanError("assembly plan contains no chunks")
|
||||
for expected_index, chunk in enumerate(chunks, start=1):
|
||||
if not isinstance(chunk, dict):
|
||||
raise AssemblyPlanError(f"assembly chunk {expected_index} is invalid")
|
||||
if int(chunk.get("sequence_index", 0)) != expected_index:
|
||||
raise AssemblyPlanError("assembly chunk order is not contiguous")
|
||||
total = int(chunk.get("total_frames", 0))
|
||||
trim = int(chunk.get("trim_frames", -1))
|
||||
net = int(chunk.get("net_frames", 0))
|
||||
if total <= 0 or trim < 0 or net <= 0 or total - trim != net:
|
||||
raise AssemblyPlanError(
|
||||
f"assembly chunk {expected_index} frame plan is invalid"
|
||||
)
|
||||
if int(chunk.get("context_frames", -1)) < 0:
|
||||
raise AssemblyPlanError(
|
||||
f"assembly chunk {expected_index} context is invalid"
|
||||
)
|
||||
if int(chunk.get("expected_video_latent_t", 0)) <= 0:
|
||||
raise AssemblyPlanError(
|
||||
f"assembly chunk {expected_index} video latent length is invalid"
|
||||
)
|
||||
if int(chunk.get("expected_audio_latent_t", 0)) <= 0:
|
||||
raise AssemblyPlanError(
|
||||
f"assembly chunk {expected_index} audio latent length is invalid"
|
||||
)
|
||||
return plan
|
||||
# V3.0.1 hardening integration: redundant metadata plus fail-closed validation.
|
||||
from ..hardening import (
|
||||
enrich_assembly_plan as _enrich_assembly_plan,
|
||||
validate_assembly_plan_contract as _validate_assembly_plan_contract,
|
||||
)
|
||||
|
||||
_make_assembly_plan_v300 = make_assembly_plan
|
||||
_validate_assembly_plan_v300 = validate_assembly_plan
|
||||
|
||||
|
||||
def validate_assembly_plan(plan):
|
||||
result = _validate_assembly_plan_v300(plan)
|
||||
_validate_assembly_plan_contract(plan)
|
||||
return result
|
||||
|
||||
|
||||
def make_assembly_plan(*args, **kwargs):
|
||||
plan = _make_assembly_plan_v300(*args, **kwargs)
|
||||
_enrich_assembly_plan(plan)
|
||||
validate_assembly_plan(plan)
|
||||
return plan
|
||||
|
||||
|
||||
def _recombine_terminal_tensor(
|
||||
first,
|
||||
second,
|
||||
*,
|
||||
slices,
|
||||
time_dim: int,
|
||||
name: str,
|
||||
):
|
||||
"""Invert the terminal logical split without changing any tensor value."""
|
||||
|
||||
import torch
|
||||
|
||||
if not torch.is_tensor(first) or not torch.is_tensor(second):
|
||||
raise ValueError(f"terminal {name} entries must be tensors")
|
||||
if first.ndim != second.ndim:
|
||||
raise ValueError(f"terminal {name} tensor ranks differ")
|
||||
dim = int(time_dim)
|
||||
if dim < 0:
|
||||
dim += first.ndim
|
||||
if dim < 0 or dim >= first.ndim:
|
||||
raise ValueError(f"terminal {name} time dimension is invalid")
|
||||
for axis, (left, right) in enumerate(zip(first.shape, second.shape)):
|
||||
if axis != dim and int(left) != int(right):
|
||||
raise ValueError(f"terminal {name} tensor geometry differs")
|
||||
|
||||
(first_start, first_stop), (second_start, second_stop) = slices
|
||||
first_start = int(first_start)
|
||||
first_stop = int(first_stop)
|
||||
second_start = int(second_start)
|
||||
second_stop = int(second_stop)
|
||||
if first_start != 0 or second_start > first_stop or second_stop <= first_stop:
|
||||
raise ValueError(f"terminal {name} split ranges do not form one physical unit")
|
||||
if int(first.shape[dim]) != first_stop - first_start:
|
||||
raise ValueError(f"terminal {name} first slice length is inconsistent")
|
||||
if int(second.shape[dim]) != second_stop - second_start:
|
||||
raise ValueError(f"terminal {name} second slice length is inconsistent")
|
||||
|
||||
overlap_start = max(first_start, second_start)
|
||||
overlap_stop = min(first_stop, second_stop)
|
||||
overlap_length = max(0, overlap_stop - overlap_start)
|
||||
if overlap_length:
|
||||
first_overlap = first.narrow(dim, overlap_start - first_start, overlap_length)
|
||||
second_overlap = second.narrow(dim, overlap_start - second_start, overlap_length)
|
||||
if not torch.equal(first_overlap, second_overlap):
|
||||
raise ValueError(
|
||||
f"terminal {name} overlap differs; refusing lossy physical reconstruction"
|
||||
)
|
||||
|
||||
output_shape = list(first.shape)
|
||||
output_shape[dim] = second_stop
|
||||
output = first.new_empty(output_shape)
|
||||
output.narrow(dim, first_start, first_stop - first_start).copy_(first)
|
||||
output.narrow(dim, second_start, second_stop - second_start).copy_(second)
|
||||
return output.contiguous()
|
||||
|
||||
|
||||
def _terminal_physical_prompt(
|
||||
prompts: list[str],
|
||||
*,
|
||||
@@ -284,20 +284,20 @@ def _attach_second_pass_contract(
|
||||
|
||||
|
||||
def prepare_physical_decode_entries(
|
||||
entries,
|
||||
*,
|
||||
chunk_seconds: float,
|
||||
preserve_final_frame: bool,
|
||||
terminal_merged: bool,
|
||||
):
|
||||
"""Return external-VAE decode units while preserving logical plan metadata."""
|
||||
|
||||
logical_entries = list(entries)
|
||||
plan = make_assembly_plan(
|
||||
logical_entries,
|
||||
chunk_seconds=float(chunk_seconds),
|
||||
preserve_final_frame=bool(preserve_final_frame),
|
||||
)
|
||||
entries,
|
||||
*,
|
||||
chunk_seconds: float,
|
||||
preserve_final_frame: bool,
|
||||
terminal_merged: bool,
|
||||
):
|
||||
"""Return external-VAE decode units while preserving logical plan metadata."""
|
||||
|
||||
logical_entries = list(entries)
|
||||
plan = make_assembly_plan(
|
||||
logical_entries,
|
||||
chunk_seconds=float(chunk_seconds),
|
||||
preserve_final_frame=bool(preserve_final_frame),
|
||||
)
|
||||
if not terminal_merged:
|
||||
_attach_second_pass_contract(
|
||||
plan,
|
||||
@@ -306,75 +306,75 @@ def prepare_physical_decode_entries(
|
||||
chunk_seconds=float(chunk_seconds),
|
||||
)
|
||||
return logical_entries, plan
|
||||
if len(logical_entries) < 2:
|
||||
raise ValueError("terminal physical decode requires two logical entries")
|
||||
|
||||
from ..v2.sequence import _terminal_pair_contract
|
||||
|
||||
initial_pair = len(logical_entries) == 2
|
||||
contract = _terminal_pair_contract(
|
||||
initial_pair=initial_pair,
|
||||
chunk_seconds=float(chunk_seconds),
|
||||
)
|
||||
first_entry = logical_entries[-2]
|
||||
second_entry = logical_entries[-1]
|
||||
physical_video = _recombine_terminal_tensor(
|
||||
first_entry["video"],
|
||||
second_entry["video"],
|
||||
slices=contract["video_slices"],
|
||||
time_dim=2,
|
||||
name="video",
|
||||
)
|
||||
physical_audio = _recombine_terminal_tensor(
|
||||
first_entry["audio"],
|
||||
second_entry["audio"],
|
||||
slices=contract["audio_slices"],
|
||||
time_dim=-1,
|
||||
name="audio",
|
||||
)
|
||||
|
||||
physical_entry = dict(first_entry)
|
||||
physical_entry["video"] = physical_video
|
||||
physical_entry["audio"] = physical_audio
|
||||
decode_entries = [*logical_entries[:-2], physical_entry]
|
||||
|
||||
logical_chunks = list(plan["chunks"])
|
||||
decode_groups = []
|
||||
for chunk in logical_chunks[:-2]:
|
||||
group = dict(chunk)
|
||||
group["logical_chunk_indices"] = [int(chunk["chunk_index"])]
|
||||
group["terminal_merged"] = False
|
||||
decode_groups.append(group)
|
||||
|
||||
first_chunk = logical_chunks[-2]
|
||||
second_chunk = logical_chunks[-1]
|
||||
frame_start = int(first_chunk.get("frame_start", 0))
|
||||
net_frames = int(contract["physical_frames"]) - int(
|
||||
contract["physical_context_frames"]
|
||||
)
|
||||
terminal_group = dict(first_chunk)
|
||||
terminal_group.update(
|
||||
{
|
||||
"total_frames": int(contract["physical_frames"]),
|
||||
"trim_frames": int(contract["physical_context_frames"]),
|
||||
"net_frames": net_frames,
|
||||
"context_frames": int(contract["physical_context_frames"]),
|
||||
"expected_video_latent_t": int(physical_video.shape[2]),
|
||||
"expected_audio_latent_t": int(physical_audio.shape[-1]),
|
||||
"frame_start": frame_start,
|
||||
"frame_stop": frame_start + net_frames,
|
||||
"logical_chunk_indices": [
|
||||
int(first_chunk["chunk_index"]),
|
||||
int(second_chunk["chunk_index"]),
|
||||
],
|
||||
"terminal_merged": True,
|
||||
}
|
||||
)
|
||||
decode_groups.append(terminal_group)
|
||||
|
||||
plan = dict(plan)
|
||||
plan["decode_group_version"] = 1
|
||||
plan["logical_chunk_count"] = len(logical_chunks)
|
||||
if len(logical_entries) < 2:
|
||||
raise ValueError("terminal physical decode requires two logical entries")
|
||||
|
||||
from ..v2.sequence import _terminal_pair_contract
|
||||
|
||||
initial_pair = len(logical_entries) == 2
|
||||
contract = _terminal_pair_contract(
|
||||
initial_pair=initial_pair,
|
||||
chunk_seconds=float(chunk_seconds),
|
||||
)
|
||||
first_entry = logical_entries[-2]
|
||||
second_entry = logical_entries[-1]
|
||||
physical_video = _recombine_terminal_tensor(
|
||||
first_entry["video"],
|
||||
second_entry["video"],
|
||||
slices=contract["video_slices"],
|
||||
time_dim=2,
|
||||
name="video",
|
||||
)
|
||||
physical_audio = _recombine_terminal_tensor(
|
||||
first_entry["audio"],
|
||||
second_entry["audio"],
|
||||
slices=contract["audio_slices"],
|
||||
time_dim=-1,
|
||||
name="audio",
|
||||
)
|
||||
|
||||
physical_entry = dict(first_entry)
|
||||
physical_entry["video"] = physical_video
|
||||
physical_entry["audio"] = physical_audio
|
||||
decode_entries = [*logical_entries[:-2], physical_entry]
|
||||
|
||||
logical_chunks = list(plan["chunks"])
|
||||
decode_groups = []
|
||||
for chunk in logical_chunks[:-2]:
|
||||
group = dict(chunk)
|
||||
group["logical_chunk_indices"] = [int(chunk["chunk_index"])]
|
||||
group["terminal_merged"] = False
|
||||
decode_groups.append(group)
|
||||
|
||||
first_chunk = logical_chunks[-2]
|
||||
second_chunk = logical_chunks[-1]
|
||||
frame_start = int(first_chunk.get("frame_start", 0))
|
||||
net_frames = int(contract["physical_frames"]) - int(
|
||||
contract["physical_context_frames"]
|
||||
)
|
||||
terminal_group = dict(first_chunk)
|
||||
terminal_group.update(
|
||||
{
|
||||
"total_frames": int(contract["physical_frames"]),
|
||||
"trim_frames": int(contract["physical_context_frames"]),
|
||||
"net_frames": net_frames,
|
||||
"context_frames": int(contract["physical_context_frames"]),
|
||||
"expected_video_latent_t": int(physical_video.shape[2]),
|
||||
"expected_audio_latent_t": int(physical_audio.shape[-1]),
|
||||
"frame_start": frame_start,
|
||||
"frame_stop": frame_start + net_frames,
|
||||
"logical_chunk_indices": [
|
||||
int(first_chunk["chunk_index"]),
|
||||
int(second_chunk["chunk_index"]),
|
||||
],
|
||||
"terminal_merged": True,
|
||||
}
|
||||
)
|
||||
decode_groups.append(terminal_group)
|
||||
|
||||
plan = dict(plan)
|
||||
plan["decode_group_version"] = 1
|
||||
plan["logical_chunk_count"] = len(logical_chunks)
|
||||
plan["physical_decode_group_count"] = len(decode_groups)
|
||||
plan["decode_groups"] = decode_groups
|
||||
_attach_second_pass_contract(
|
||||
|
||||
@@ -0,0 +1,340 @@
|
||||
"""Process-local, VAE-scoped cache for V3.8 reference encode tensors.
|
||||
|
||||
Only detached, contiguous CPU tensor copies are retained. The cache never
|
||||
owns source images, video frames, audio waveforms, conditioning objects, or
|
||||
sampling outputs.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections import Counter, OrderedDict
|
||||
from dataclasses import dataclass
|
||||
import threading
|
||||
from typing import Any, Callable
|
||||
import weakref
|
||||
|
||||
import torch
|
||||
|
||||
|
||||
REF_ENCODE_CACHE_VERSION = 1
|
||||
DEFAULT_MAX_ENTRIES = 16
|
||||
DEFAULT_MAX_BYTES = 512 * 1024 * 1024
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class RefEncodeCacheKey:
|
||||
kind: str
|
||||
preprocess_version: int
|
||||
identity: str
|
||||
cache_version: int = REF_ENCODE_CACHE_VERSION
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class RefEncodeCacheEvent:
|
||||
kind: str
|
||||
action: str
|
||||
reason: str = ""
|
||||
payload_bytes: int = 0
|
||||
|
||||
|
||||
@dataclass(slots=True)
|
||||
class _CacheEntry:
|
||||
tensor: torch.Tensor
|
||||
payload_bytes: int
|
||||
last_used: int
|
||||
|
||||
|
||||
CacheEventSink = Callable[[RefEncodeCacheEvent], None]
|
||||
|
||||
|
||||
def make_ref_encode_cache_key(
|
||||
kind: str,
|
||||
preprocess_version: int,
|
||||
identity: str,
|
||||
) -> RefEncodeCacheKey:
|
||||
return RefEncodeCacheKey(
|
||||
kind=str(kind),
|
||||
preprocess_version=int(preprocess_version),
|
||||
identity=str(identity),
|
||||
)
|
||||
|
||||
|
||||
class RefEncodeCache:
|
||||
"""Small process-local LRU split into weak VAE object namespaces."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
*,
|
||||
max_entries: int = DEFAULT_MAX_ENTRIES,
|
||||
max_bytes: int = DEFAULT_MAX_BYTES,
|
||||
) -> None:
|
||||
if int(max_entries) < 1:
|
||||
raise ValueError("max_entries must be positive")
|
||||
if int(max_bytes) < 1:
|
||||
raise ValueError("max_bytes must be positive")
|
||||
self.max_entries = int(max_entries)
|
||||
self.max_bytes = int(max_bytes)
|
||||
self._lock = threading.RLock()
|
||||
self._namespaces: weakref.WeakKeyDictionary[
|
||||
Any, OrderedDict[RefEncodeCacheKey, _CacheEntry]
|
||||
] = weakref.WeakKeyDictionary()
|
||||
self._clock = 0
|
||||
self._stats: Counter[str] = Counter()
|
||||
self._kind_stats: dict[str, Counter[str]] = {}
|
||||
|
||||
@staticmethod
|
||||
def _vae_cacheable(vae: Any) -> bool:
|
||||
try:
|
||||
weakref.ref(vae)
|
||||
hash(vae)
|
||||
except TypeError:
|
||||
return False
|
||||
return True
|
||||
|
||||
def supports_vae(self, vae: Any) -> bool:
|
||||
return self._vae_cacheable(vae)
|
||||
|
||||
def _next_clock_locked(self) -> int:
|
||||
self._clock += 1
|
||||
return self._clock
|
||||
|
||||
def _record_locked(
|
||||
self,
|
||||
*,
|
||||
key: RefEncodeCacheKey,
|
||||
action: str,
|
||||
reason: str = "",
|
||||
payload_bytes: int = 0,
|
||||
) -> RefEncodeCacheEvent:
|
||||
self._stats[str(action)] += 1
|
||||
self._kind_stats.setdefault(key.kind, Counter())[str(action)] += 1
|
||||
return RefEncodeCacheEvent(
|
||||
kind=key.kind,
|
||||
action=str(action),
|
||||
reason=str(reason),
|
||||
payload_bytes=int(payload_bytes),
|
||||
)
|
||||
|
||||
@staticmethod
|
||||
def _emit(event: RefEncodeCacheEvent, sink: CacheEventSink | None) -> None:
|
||||
if sink is not None:
|
||||
sink(event)
|
||||
|
||||
def _resident_locked(self) -> tuple[int, int]:
|
||||
entries = 0
|
||||
payload_bytes = 0
|
||||
for namespace in list(self._namespaces.values()):
|
||||
entries += len(namespace)
|
||||
payload_bytes += sum(entry.payload_bytes for entry in namespace.values())
|
||||
return entries, payload_bytes
|
||||
|
||||
def _evict_locked(self) -> None:
|
||||
while True:
|
||||
entries, payload_bytes = self._resident_locked()
|
||||
if entries <= self.max_entries and payload_bytes <= self.max_bytes:
|
||||
return
|
||||
oldest_namespace = None
|
||||
oldest_key = None
|
||||
oldest_clock = None
|
||||
for namespace in list(self._namespaces.values()):
|
||||
for key, entry in namespace.items():
|
||||
if oldest_clock is None or entry.last_used < oldest_clock:
|
||||
oldest_namespace = namespace
|
||||
oldest_key = key
|
||||
oldest_clock = entry.last_used
|
||||
if oldest_namespace is None or oldest_key is None:
|
||||
return
|
||||
oldest_namespace.pop(oldest_key, None)
|
||||
self._stats["evictions"] += 1
|
||||
|
||||
def lookup(
|
||||
self,
|
||||
vae: Any,
|
||||
key: RefEncodeCacheKey,
|
||||
*,
|
||||
event_sink: CacheEventSink | None = None,
|
||||
) -> torch.Tensor | None:
|
||||
if not self._vae_cacheable(vae):
|
||||
with self._lock:
|
||||
event = self._record_locked(
|
||||
key=key,
|
||||
action="bypass",
|
||||
reason="vae_not_weakrefable_or_hashable",
|
||||
)
|
||||
self._emit(event, event_sink)
|
||||
return None
|
||||
|
||||
master = None
|
||||
with self._lock:
|
||||
namespace = self._namespaces.get(vae)
|
||||
entry = namespace.get(key) if namespace is not None else None
|
||||
if entry is None:
|
||||
event = self._record_locked(key=key, action="miss")
|
||||
else:
|
||||
entry.last_used = self._next_clock_locked()
|
||||
namespace.move_to_end(key)
|
||||
master = entry.tensor
|
||||
event = self._record_locked(
|
||||
key=key,
|
||||
action="hit",
|
||||
payload_bytes=entry.payload_bytes,
|
||||
)
|
||||
self._emit(event, event_sink)
|
||||
return None if master is None else master.clone()
|
||||
|
||||
def store(
|
||||
self,
|
||||
vae: Any,
|
||||
key: RefEncodeCacheKey,
|
||||
tensor: Any,
|
||||
*,
|
||||
event_sink: CacheEventSink | None = None,
|
||||
) -> bool:
|
||||
if not self._vae_cacheable(vae):
|
||||
with self._lock:
|
||||
event = self._record_locked(
|
||||
key=key,
|
||||
action="bypass",
|
||||
reason="vae_not_weakrefable_or_hashable",
|
||||
)
|
||||
self._emit(event, event_sink)
|
||||
return False
|
||||
if not torch.is_tensor(tensor):
|
||||
with self._lock:
|
||||
event = self._record_locked(
|
||||
key=key,
|
||||
action="bypass",
|
||||
reason="payload_not_tensor",
|
||||
)
|
||||
self._emit(event, event_sink)
|
||||
return False
|
||||
if tensor.device.type != "cpu":
|
||||
with self._lock:
|
||||
event = self._record_locked(
|
||||
key=key,
|
||||
action="bypass",
|
||||
reason="payload_not_cpu",
|
||||
)
|
||||
self._emit(event, event_sink)
|
||||
return False
|
||||
payload_bytes = int(tensor.numel()) * int(tensor.element_size())
|
||||
if payload_bytes > self.max_bytes:
|
||||
with self._lock:
|
||||
event = self._record_locked(
|
||||
key=key,
|
||||
action="bypass",
|
||||
reason="entry_exceeds_byte_limit",
|
||||
payload_bytes=payload_bytes,
|
||||
)
|
||||
self._emit(event, event_sink)
|
||||
return False
|
||||
try:
|
||||
master = tensor.detach().contiguous().clone()
|
||||
except Exception:
|
||||
with self._lock:
|
||||
event = self._record_locked(
|
||||
key=key,
|
||||
action="bypass",
|
||||
reason="payload_copy_failed",
|
||||
payload_bytes=payload_bytes,
|
||||
)
|
||||
self._emit(event, event_sink)
|
||||
return False
|
||||
|
||||
with self._lock:
|
||||
namespace = self._namespaces.get(vae)
|
||||
if namespace is None:
|
||||
namespace = OrderedDict()
|
||||
self._namespaces[vae] = namespace
|
||||
namespace[key] = _CacheEntry(
|
||||
tensor=master,
|
||||
payload_bytes=payload_bytes,
|
||||
last_used=self._next_clock_locked(),
|
||||
)
|
||||
namespace.move_to_end(key)
|
||||
self._evict_locked()
|
||||
event = self._record_locked(
|
||||
key=key,
|
||||
action="store",
|
||||
payload_bytes=payload_bytes,
|
||||
)
|
||||
self._emit(event, event_sink)
|
||||
return True
|
||||
|
||||
def clear(self) -> None:
|
||||
with self._lock:
|
||||
self._namespaces = weakref.WeakKeyDictionary()
|
||||
self._clock = 0
|
||||
self._stats.clear()
|
||||
self._kind_stats.clear()
|
||||
|
||||
def inspect(self) -> dict[str, Any]:
|
||||
with self._lock:
|
||||
entries, payload_bytes = self._resident_locked()
|
||||
return {
|
||||
"cache_version": REF_ENCODE_CACHE_VERSION,
|
||||
"resident_entries": entries,
|
||||
"resident_bytes": payload_bytes,
|
||||
"max_entries": self.max_entries,
|
||||
"max_bytes": self.max_bytes,
|
||||
"stats": dict(self._stats),
|
||||
"kind_stats": {
|
||||
kind: dict(values)
|
||||
for kind, values in sorted(self._kind_stats.items())
|
||||
},
|
||||
"vae_namespaces": len(self._namespaces),
|
||||
}
|
||||
|
||||
|
||||
_REF_ENCODE_CACHE = RefEncodeCache()
|
||||
|
||||
|
||||
def get_ref_encode_cache() -> RefEncodeCache:
|
||||
return _REF_ENCODE_CACHE
|
||||
|
||||
|
||||
def clear_ref_encode_cache() -> None:
|
||||
_REF_ENCODE_CACHE.clear()
|
||||
|
||||
|
||||
def inspect_ref_encode_cache() -> dict[str, Any]:
|
||||
return _REF_ENCODE_CACHE.inspect()
|
||||
|
||||
|
||||
def format_ref_encode_cache_diagnostics(
|
||||
events: list[RefEncodeCacheEvent] | tuple[RefEncodeCacheEvent, ...],
|
||||
) -> str:
|
||||
if not events:
|
||||
return ""
|
||||
labels = {
|
||||
"reference_image": "image",
|
||||
"video_guide": "video",
|
||||
"reference_audio": "audio",
|
||||
}
|
||||
by_kind: dict[str, Counter[str]] = {}
|
||||
totals: Counter[str] = Counter()
|
||||
for event in events:
|
||||
by_kind.setdefault(event.kind, Counter())[event.action] += 1
|
||||
totals[event.action] += 1
|
||||
components = []
|
||||
for kind in ("reference_image", "video_guide", "reference_audio"):
|
||||
values = by_kind.get(kind)
|
||||
if not values:
|
||||
continue
|
||||
components.append(
|
||||
f"{labels[kind]} hit={values['hit']}/miss={values['miss']}"
|
||||
f"/store={values['store']}/bypass={values['bypass']}"
|
||||
)
|
||||
state = inspect_ref_encode_cache()
|
||||
resident_mib = int(state["resident_bytes"]) / float(1024**2)
|
||||
limit_mib = int(state["max_bytes"]) / float(1024**2)
|
||||
components.append(
|
||||
"total "
|
||||
f"hits={totals['hit']}, misses={totals['miss']}, "
|
||||
f"stores={totals['store']}, bypasses={totals['bypass']}"
|
||||
)
|
||||
components.append(
|
||||
f"resident={resident_mib:.1f} MiB/{limit_mib:.1f} MiB "
|
||||
f"({int(state['resident_entries'])}/{int(state['max_entries'])} entries)"
|
||||
)
|
||||
return "Reference encode cache: " + "; ".join(components) + "."
|
||||
@@ -0,0 +1,282 @@
|
||||
"""Persistent MiniMax H3 video-reference conditioning for the V3.4 sampler."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
import hashlib
|
||||
import json
|
||||
import math
|
||||
from typing import Any
|
||||
|
||||
import torch
|
||||
|
||||
from .temporal import align_frame_count_up
|
||||
|
||||
|
||||
REFERENCE_VIDEO_CONTRACT_VERSION = 1
|
||||
REFERENCE_VIDEO_PREPROCESS_VERSION = 3
|
||||
REFERENCE_VIDEO_SIZE_EFFICIENT = "Efficient - 0.4 MP"
|
||||
REFERENCE_VIDEO_SIZE_BALANCED = "Balanced - 0.6 MP"
|
||||
REFERENCE_VIDEO_SIZE_MATCH_OUTPUT = "Match Output"
|
||||
REFERENCE_VIDEO_SIZE_OPTIONS = (
|
||||
REFERENCE_VIDEO_SIZE_EFFICIENT,
|
||||
REFERENCE_VIDEO_SIZE_BALANCED,
|
||||
REFERENCE_VIDEO_SIZE_MATCH_OUTPUT,
|
||||
)
|
||||
_CANVAS_MULTIPLE = 32
|
||||
_EFFICIENT_AREA = 400_000
|
||||
_BALANCED_AREA = 600_000
|
||||
_SOURCE_FPS = 24
|
||||
|
||||
|
||||
class ReferenceVideoError(ValueError):
|
||||
pass
|
||||
|
||||
|
||||
def _canonical_hash(value: Any) -> str:
|
||||
payload = json.dumps(
|
||||
value, sort_keys=True, separators=(",", ":"), ensure_ascii=True
|
||||
).encode("utf-8")
|
||||
return hashlib.sha256(payload).hexdigest()
|
||||
|
||||
|
||||
def _tensor_hash(value: torch.Tensor) -> str:
|
||||
tensor = value.detach().to(device="cpu").contiguous()
|
||||
digest = hashlib.sha256()
|
||||
digest.update(str(tuple(int(v) for v in tensor.shape)).encode("ascii"))
|
||||
digest.update(str(tensor.dtype).encode("ascii"))
|
||||
digest.update(tensor.numpy().tobytes(order="C"))
|
||||
return digest.hexdigest()
|
||||
|
||||
|
||||
def _round_canvas(value: float) -> int:
|
||||
return max(
|
||||
_CANVAS_MULTIPLE,
|
||||
int(round(float(value) / _CANVAS_MULTIPLE)) * _CANVAS_MULTIPLE,
|
||||
)
|
||||
|
||||
|
||||
def _resolved_size(
|
||||
source_width: int,
|
||||
source_height: int,
|
||||
*,
|
||||
output_width: int,
|
||||
output_height: int,
|
||||
size_mode: str,
|
||||
) -> tuple[int, int]:
|
||||
if size_mode == REFERENCE_VIDEO_SIZE_MATCH_OUTPUT:
|
||||
target_area = int(output_width) * int(output_height)
|
||||
elif size_mode == REFERENCE_VIDEO_SIZE_BALANCED:
|
||||
target_area = _BALANCED_AREA
|
||||
else:
|
||||
target_area = _EFFICIENT_AREA
|
||||
source_area = int(source_width) * int(source_height)
|
||||
scale = min(1.0, math.sqrt(float(target_area) / float(source_area)))
|
||||
target_width = _round_canvas(int(source_width) * scale)
|
||||
target_height = _round_canvas(int(source_height) * scale)
|
||||
if source_width >= _CANVAS_MULTIPLE:
|
||||
target_width = min(
|
||||
target_width,
|
||||
max(_CANVAS_MULTIPLE, (int(source_width) // _CANVAS_MULTIPLE) * _CANVAS_MULTIPLE),
|
||||
)
|
||||
if source_height >= _CANVAS_MULTIPLE:
|
||||
target_height = min(
|
||||
target_height,
|
||||
max(_CANVAS_MULTIPLE, (int(source_height) // _CANVAS_MULTIPLE) * _CANVAS_MULTIPLE),
|
||||
)
|
||||
return target_width, target_height
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ReferenceVideoSource:
|
||||
frames: torch.Tensor
|
||||
source_shape: tuple[int, ...]
|
||||
source_dtype: str
|
||||
source_sha256: str
|
||||
size_mode: str
|
||||
target_width: int
|
||||
target_height: int
|
||||
frame_count: int
|
||||
combined_hash: str
|
||||
|
||||
@property
|
||||
def contract(self) -> dict[str, Any]:
|
||||
return {
|
||||
"reference_video_contract_version": REFERENCE_VIDEO_CONTRACT_VERSION,
|
||||
"source_shape": list(self.source_shape),
|
||||
"source_dtype": self.source_dtype,
|
||||
"source_sha256": self.source_sha256,
|
||||
"source_fps": _SOURCE_FPS,
|
||||
"size_mode": self.size_mode,
|
||||
"target_width": self.target_width,
|
||||
"target_height": self.target_height,
|
||||
"frame_count": self.frame_count,
|
||||
"preprocess_version": REFERENCE_VIDEO_PREPROCESS_VERSION,
|
||||
"combined_hash": self.combined_hash,
|
||||
}
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ReferenceVideoAssets:
|
||||
source: ReferenceVideoSource
|
||||
item: dict[str, Any]
|
||||
block: dict[str, Any]
|
||||
|
||||
|
||||
def _resolve_reference_frame_count(source_frames: int, target_frames: int) -> int:
|
||||
source_count = int(source_frames)
|
||||
target_count = int(target_frames)
|
||||
if source_count < 5 or target_count < 5:
|
||||
raise ReferenceVideoError("Video Reference requires at least 5 frames")
|
||||
target_cap = align_frame_count_up(target_count)
|
||||
available_count = min(source_count, target_cap)
|
||||
return min(align_frame_count_up(available_count), target_cap)
|
||||
|
||||
|
||||
def _fit_reference_frames(frames: torch.Tensor, frame_count: int) -> torch.Tensor:
|
||||
requested_count = int(frame_count)
|
||||
current_count = int(frames.shape[0])
|
||||
if current_count >= requested_count:
|
||||
return frames[:requested_count].contiguous()
|
||||
if current_count < 1:
|
||||
raise ReferenceVideoError("Video Reference contains no frames")
|
||||
padding = frames[-1:].expand(requested_count - current_count, -1, -1, -1)
|
||||
return torch.cat((frames, padding), dim=0).contiguous()
|
||||
|
||||
|
||||
def prepare_reference_video_source(
|
||||
reference_video_1: Any,
|
||||
*,
|
||||
target_frames: int,
|
||||
output_width: int,
|
||||
output_height: int,
|
||||
size_mode: str = REFERENCE_VIDEO_SIZE_EFFICIENT,
|
||||
) -> ReferenceVideoSource | None:
|
||||
if reference_video_1 is None:
|
||||
return None
|
||||
if not torch.is_tensor(reference_video_1) or reference_video_1.ndim != 4:
|
||||
raise ReferenceVideoError(
|
||||
"Video Reference must be a ComfyUI IMAGE batch with shape [T, H, W, C]"
|
||||
)
|
||||
if int(reference_video_1.shape[-1]) < 3:
|
||||
raise ReferenceVideoError("Video Reference must contain RGB channels")
|
||||
frames = reference_video_1[:, :, :, :3].detach().to(
|
||||
device="cpu", dtype=torch.float32
|
||||
).contiguous()
|
||||
if not bool(torch.isfinite(frames).all().item()):
|
||||
raise ReferenceVideoError("Video Reference contains NaN or infinity")
|
||||
source_shape = tuple(int(value) for value in frames.shape)
|
||||
source_sha256 = _tensor_hash(frames)
|
||||
frame_count = _resolve_reference_frame_count(
|
||||
int(frames.shape[0]),
|
||||
int(target_frames),
|
||||
)
|
||||
normalized_size_mode = (
|
||||
str(size_mode)
|
||||
if str(size_mode) in REFERENCE_VIDEO_SIZE_OPTIONS
|
||||
else REFERENCE_VIDEO_SIZE_EFFICIENT
|
||||
)
|
||||
target_width, target_height = _resolved_size(
|
||||
int(frames.shape[2]),
|
||||
int(frames.shape[1]),
|
||||
output_width=int(output_width),
|
||||
output_height=int(output_height),
|
||||
size_mode=normalized_size_mode,
|
||||
)
|
||||
contract_base = {
|
||||
"reference_video_contract_version": REFERENCE_VIDEO_CONTRACT_VERSION,
|
||||
"source_shape": list(source_shape),
|
||||
"source_dtype": str(frames.dtype),
|
||||
"source_sha256": source_sha256,
|
||||
"source_fps": _SOURCE_FPS,
|
||||
"size_mode": normalized_size_mode,
|
||||
"target_width": target_width,
|
||||
"target_height": target_height,
|
||||
"frame_count": frame_count,
|
||||
"preprocess_version": REFERENCE_VIDEO_PREPROCESS_VERSION,
|
||||
}
|
||||
return ReferenceVideoSource(
|
||||
frames=frames,
|
||||
source_shape=source_shape,
|
||||
source_dtype=str(frames.dtype),
|
||||
source_sha256=source_sha256,
|
||||
size_mode=normalized_size_mode,
|
||||
target_width=target_width,
|
||||
target_height=target_height,
|
||||
frame_count=frame_count,
|
||||
combined_hash=_canonical_hash(contract_base),
|
||||
)
|
||||
|
||||
|
||||
def encode_reference_video(
|
||||
video_vae: Any,
|
||||
source: ReferenceVideoSource,
|
||||
) -> ReferenceVideoAssets:
|
||||
available_count = min(int(source.frames.shape[0]), int(source.frame_count))
|
||||
frames = source.frames[:available_count]
|
||||
if (
|
||||
int(frames.shape[2]) != source.target_width
|
||||
or int(frames.shape[1]) != source.target_height
|
||||
):
|
||||
try:
|
||||
import comfy.utils
|
||||
except Exception as exc:
|
||||
raise ReferenceVideoError(
|
||||
"ComfyUI Core image resize support is unavailable"
|
||||
) from exc
|
||||
frames = comfy.utils.common_upscale(
|
||||
frames.movedim(-1, 1),
|
||||
source.target_width,
|
||||
source.target_height,
|
||||
"lanczos",
|
||||
"disabled",
|
||||
).movedim(1, -1).contiguous()
|
||||
frames = _fit_reference_frames(frames, source.frame_count)
|
||||
try:
|
||||
latent = video_vae.encode(frames).detach().to("cpu").contiguous()
|
||||
except Exception as exc:
|
||||
raise ReferenceVideoError("Video Reference VAE Encode failed") from exc
|
||||
qwen_frames = frames[::_SOURCE_FPS // 2].contiguous()
|
||||
item = {
|
||||
"type": "video",
|
||||
"data": qwen_frames,
|
||||
"timestamps": [index / 2.0 for index in range(int(qwen_frames.shape[0]))],
|
||||
}
|
||||
block = {
|
||||
"kind": "video",
|
||||
"latent_t": int(latent.shape[2]),
|
||||
"latent_h": source.target_height // 16,
|
||||
"latent_w": source.target_width // 16,
|
||||
"ref_audio_t": 0,
|
||||
"latent": latent,
|
||||
"audio_latent": None,
|
||||
}
|
||||
return ReferenceVideoAssets(source=source, item=item, block=block)
|
||||
|
||||
|
||||
def combine_reference_video_identity(
|
||||
visual_identity_hash: str,
|
||||
source: ReferenceVideoSource | None,
|
||||
) -> str:
|
||||
if source is None:
|
||||
return str(visual_identity_hash)
|
||||
return _canonical_hash(
|
||||
{
|
||||
"reference_video_identity_version": 1,
|
||||
"visual_identity_hash": str(visual_identity_hash),
|
||||
"reference_video_hash": source.combined_hash,
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
def validate_reference_video_prompts(
|
||||
prompts: list[str], source: ReferenceVideoSource | None
|
||||
) -> str:
|
||||
if source is None or any("<Video 1>" in str(prompt) for prompt in prompts):
|
||||
return ""
|
||||
return (
|
||||
"H3C-P103 Warning: Video Reference is connected but the prompt contains no "
|
||||
"<Video 1> tag; video still conditions generation, but an explicit tag is "
|
||||
"recommended."
|
||||
)
|
||||
|
||||
@@ -0,0 +1,179 @@
|
||||
"""Versioned physical-group selection for Experimental selective refinement."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
from collections.abc import Mapping, Sequence
|
||||
from dataclasses import dataclass
|
||||
from types import MappingProxyType
|
||||
from typing import Any
|
||||
|
||||
|
||||
MAGIC = "H3_CONTINUUM_REFINE_SCOPE"
|
||||
SCHEMA_VERSION = 1
|
||||
|
||||
MODE_ALL = "all"
|
||||
MODE_PHYSICAL_GROUP = "physical_group"
|
||||
MODE_LOGICAL_CHUNK = "logical_chunk"
|
||||
MODES = (MODE_ALL, MODE_PHYSICAL_GROUP, MODE_LOGICAL_CHUNK)
|
||||
|
||||
|
||||
class RefineScopeError(ValueError):
|
||||
"""Raised before preparation when a requested scope cannot be resolved."""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class RefineScope:
|
||||
"""One immutable scope resolution containing no Tensor or runtime object."""
|
||||
|
||||
mode: str
|
||||
selected_group_indices: tuple[int, ...]
|
||||
contract: Mapping[str, Any]
|
||||
|
||||
@property
|
||||
def is_all(self) -> bool:
|
||||
return self.mode == MODE_ALL
|
||||
|
||||
|
||||
def _identity(payload: Mapping[str, Any]) -> str:
|
||||
encoded = json.dumps(
|
||||
dict(payload),
|
||||
sort_keys=True,
|
||||
separators=(",", ":"),
|
||||
).encode("utf-8")
|
||||
return hashlib.sha256(encoded).hexdigest()
|
||||
|
||||
|
||||
def _physical_groups(assembly_plan: Mapping[str, Any]) -> list[Mapping[str, Any]]:
|
||||
if not isinstance(assembly_plan, Mapping):
|
||||
raise RefineScopeError("assembly_plan must be a mapping")
|
||||
second_pass = assembly_plan.get("second_pass_contract")
|
||||
if not isinstance(second_pass, Mapping) or second_pass.get("version") != 1:
|
||||
raise RefineScopeError("assembly_plan has no Second Pass contract version 1")
|
||||
groups = second_pass.get("physical_groups")
|
||||
if (
|
||||
not isinstance(groups, Sequence)
|
||||
or isinstance(groups, (str, bytes))
|
||||
or not groups
|
||||
or not all(isinstance(group, Mapping) for group in groups)
|
||||
):
|
||||
raise RefineScopeError("assembly_plan has no physical groups")
|
||||
return list(groups)
|
||||
|
||||
|
||||
def _logical_chunks(group: Mapping[str, Any], group_index: int) -> tuple[int, ...]:
|
||||
values = group.get("logical_chunks")
|
||||
if (
|
||||
not isinstance(values, Sequence)
|
||||
or isinstance(values, (str, bytes))
|
||||
or not values
|
||||
or any(type(value) is not int or value <= 0 for value in values)
|
||||
):
|
||||
raise RefineScopeError(
|
||||
f"physical group {group_index + 1} has invalid logical chunk identity"
|
||||
)
|
||||
chunks = tuple(int(value) for value in values)
|
||||
if len(set(chunks)) != len(chunks):
|
||||
raise RefineScopeError(
|
||||
f"physical group {group_index + 1} repeats a logical chunk"
|
||||
)
|
||||
return chunks
|
||||
|
||||
|
||||
def resolve_refine_scope(
|
||||
mode: str | None,
|
||||
scope_index: int,
|
||||
assembly_plan: Mapping[str, Any],
|
||||
) -> RefineScope:
|
||||
"""Resolve one public 1-based selection to complete physical groups.
|
||||
|
||||
Logical chunks never split a physical group. Selecting either logical half of
|
||||
a Terminal Merge group therefore selects the complete terminal pair.
|
||||
"""
|
||||
|
||||
if mode is None:
|
||||
canonical_mode = MODE_ALL
|
||||
elif not isinstance(mode, str):
|
||||
raise RefineScopeError(f"unsupported refine scope mode {mode!r}")
|
||||
else:
|
||||
canonical_mode = mode.strip().lower()
|
||||
if canonical_mode not in MODES:
|
||||
raise RefineScopeError(f"unsupported refine scope mode {mode!r}")
|
||||
if type(scope_index) is not int or scope_index <= 0:
|
||||
raise RefineScopeError("refine scope index must be a positive integer")
|
||||
|
||||
groups = _physical_groups(assembly_plan)
|
||||
group_chunks = [
|
||||
_logical_chunks(group, group_index)
|
||||
for group_index, group in enumerate(groups)
|
||||
]
|
||||
terminal_expanded = False
|
||||
requested_index: int | None = None
|
||||
|
||||
if canonical_mode == MODE_ALL:
|
||||
selected = tuple(range(len(groups)))
|
||||
elif canonical_mode == MODE_PHYSICAL_GROUP:
|
||||
requested_index = int(scope_index)
|
||||
selected_index = requested_index - 1
|
||||
if selected_index >= len(groups):
|
||||
raise RefineScopeError(
|
||||
f"physical group {requested_index} is outside 1..{len(groups)}"
|
||||
)
|
||||
selected = (selected_index,)
|
||||
else:
|
||||
requested_index = int(scope_index)
|
||||
matches = [
|
||||
group_index
|
||||
for group_index, chunks in enumerate(group_chunks)
|
||||
if requested_index in chunks
|
||||
]
|
||||
if len(matches) != 1:
|
||||
if matches:
|
||||
raise RefineScopeError(
|
||||
f"logical chunk {requested_index} belongs to multiple physical groups"
|
||||
)
|
||||
raise RefineScopeError(
|
||||
f"logical chunk {requested_index} is not present in the assembly plan"
|
||||
)
|
||||
selected = (matches[0],)
|
||||
selected_group = groups[selected[0]]
|
||||
selected_chunks = group_chunks[selected[0]]
|
||||
terminal_expanded = bool(
|
||||
selected_group.get("terminal_merged") and len(selected_chunks) > 1
|
||||
)
|
||||
|
||||
selected_chunks = tuple(
|
||||
chunk
|
||||
for group_index in selected
|
||||
for chunk in group_chunks[group_index]
|
||||
)
|
||||
contract: dict[str, Any] = {
|
||||
"magic": MAGIC,
|
||||
"schema_version": SCHEMA_VERSION,
|
||||
"mode": canonical_mode,
|
||||
"requested_index": requested_index,
|
||||
"selected_physical_group_indices": tuple(selected),
|
||||
"selected_physical_groups": tuple(index + 1 for index in selected),
|
||||
"selected_logical_chunks": tuple(selected_chunks),
|
||||
"terminal_expanded": terminal_expanded,
|
||||
}
|
||||
contract["scope_hash"] = _identity(contract)
|
||||
return RefineScope(
|
||||
mode=canonical_mode,
|
||||
selected_group_indices=selected,
|
||||
contract=MappingProxyType(contract),
|
||||
)
|
||||
|
||||
|
||||
def serializable_scope_contract(scope: RefineScope) -> dict[str, Any]:
|
||||
if not isinstance(scope, RefineScope):
|
||||
raise RefineScopeError("refine_scope must be a RefineScope")
|
||||
return {
|
||||
**dict(scope.contract),
|
||||
"selected_physical_group_indices": list(
|
||||
scope.contract["selected_physical_group_indices"]
|
||||
),
|
||||
"selected_physical_groups": list(scope.contract["selected_physical_groups"]),
|
||||
"selected_logical_chunks": list(scope.contract["selected_logical_chunks"]),
|
||||
}
|
||||
@@ -0,0 +1,206 @@
|
||||
"""Versioned stream-target policies for future Continuum refinement modes."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
from dataclasses import dataclass
|
||||
from types import MappingProxyType
|
||||
from typing import Any, Mapping
|
||||
|
||||
|
||||
MAGIC = "H3_CONTINUUM_REFINE_TARGET"
|
||||
SCHEMA_VERSION = 1
|
||||
EXECUTION_MAGIC = "H3_CONTINUUM_TARGETED_REFINE_EXECUTION"
|
||||
EXECUTION_SCHEMA_VERSION = 1
|
||||
|
||||
MODE_VIDEO_ONLY = "video_only"
|
||||
MODE_AUDIO_ONLY = "audio_only"
|
||||
MODE_VIDEO_AUDIO = "video_audio"
|
||||
MODES = (MODE_VIDEO_ONLY, MODE_AUDIO_ONLY, MODE_VIDEO_AUDIO)
|
||||
|
||||
NOISE_SEEDED_RANDOM = "seeded_random"
|
||||
NOISE_ZERO = "zero"
|
||||
OUTPUT_SAMPLED = "sampled"
|
||||
OUTPUT_INPUT_PASSTHROUGH = "input_passthrough_bit_exact"
|
||||
|
||||
VIDEO_ONLY_SEED_NAMESPACE = "h3-continuum-refine-v1"
|
||||
AUDIO_ONLY_SEED_NAMESPACE = "h3-continuum-refine-audio-v1"
|
||||
VIDEO_AUDIO_SEED_NAMESPACE = "h3-continuum-refine-av-v1"
|
||||
|
||||
|
||||
class RefineTargetError(ValueError):
|
||||
"""Raised when a target policy or target execution contract is invalid."""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class RefineTarget:
|
||||
"""One immutable target policy; it contains no Tensor or runtime object."""
|
||||
|
||||
mode: str
|
||||
contract: Mapping[str, Any]
|
||||
|
||||
|
||||
def _identity(payload: Mapping[str, Any]) -> str:
|
||||
encoded = json.dumps(
|
||||
dict(payload),
|
||||
sort_keys=True,
|
||||
separators=(",", ":"),
|
||||
).encode("utf-8")
|
||||
return hashlib.sha256(encoded).hexdigest()
|
||||
|
||||
|
||||
def _stream_policy(*, noise: str, mask: int, output: str) -> dict[str, Any]:
|
||||
return {
|
||||
"noise": str(noise),
|
||||
"mask": int(mask),
|
||||
"output": str(output),
|
||||
}
|
||||
|
||||
|
||||
_POLICIES: dict[str, dict[str, Any]] = {
|
||||
MODE_VIDEO_ONLY: {
|
||||
"video": _stream_policy(
|
||||
noise=NOISE_SEEDED_RANDOM,
|
||||
mask=1,
|
||||
output=OUTPUT_SAMPLED,
|
||||
),
|
||||
"audio": _stream_policy(
|
||||
noise=NOISE_ZERO,
|
||||
mask=0,
|
||||
output=OUTPUT_INPUT_PASSTHROUGH,
|
||||
),
|
||||
"seed_namespace": VIDEO_ONLY_SEED_NAMESPACE,
|
||||
},
|
||||
MODE_AUDIO_ONLY: {
|
||||
"video": _stream_policy(
|
||||
noise=NOISE_ZERO,
|
||||
mask=0,
|
||||
output=OUTPUT_INPUT_PASSTHROUGH,
|
||||
),
|
||||
"audio": _stream_policy(
|
||||
noise=NOISE_SEEDED_RANDOM,
|
||||
mask=1,
|
||||
output=OUTPUT_SAMPLED,
|
||||
),
|
||||
"seed_namespace": AUDIO_ONLY_SEED_NAMESPACE,
|
||||
},
|
||||
MODE_VIDEO_AUDIO: {
|
||||
"video": _stream_policy(
|
||||
noise=NOISE_SEEDED_RANDOM,
|
||||
mask=1,
|
||||
output=OUTPUT_SAMPLED,
|
||||
),
|
||||
"audio": _stream_policy(
|
||||
noise=NOISE_SEEDED_RANDOM,
|
||||
mask=1,
|
||||
output=OUTPUT_SAMPLED,
|
||||
),
|
||||
"seed_namespace": VIDEO_AUDIO_SEED_NAMESPACE,
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def make_refine_target(mode: str) -> RefineTarget:
|
||||
canonical_mode = str(mode).strip().lower()
|
||||
if canonical_mode not in MODES:
|
||||
raise RefineTargetError(f"unsupported refine target mode {mode!r}")
|
||||
policy = _POLICIES[canonical_mode]
|
||||
contract: dict[str, Any] = {
|
||||
"magic": MAGIC,
|
||||
"schema_version": SCHEMA_VERSION,
|
||||
"mode": canonical_mode,
|
||||
"video": dict(policy["video"]),
|
||||
"audio": dict(policy["audio"]),
|
||||
"seed_namespace": str(policy["seed_namespace"]),
|
||||
}
|
||||
contract["target_hash"] = _identity(contract)
|
||||
return RefineTarget(
|
||||
mode=canonical_mode,
|
||||
contract=MappingProxyType(contract),
|
||||
)
|
||||
|
||||
|
||||
def resolve_refine_target(value: RefineTarget | str | None) -> RefineTarget:
|
||||
if value is None:
|
||||
return make_refine_target(MODE_VIDEO_ONLY)
|
||||
if isinstance(value, str):
|
||||
return make_refine_target(value)
|
||||
if not isinstance(value, RefineTarget):
|
||||
raise RefineTargetError("refine_target must be a RefineTarget or mode string")
|
||||
rebuilt = make_refine_target(value.mode)
|
||||
if dict(rebuilt.contract) != dict(value.contract):
|
||||
raise RefineTargetError("refine_target contract identity is inconsistent")
|
||||
return value
|
||||
|
||||
|
||||
def serializable_target_contract(target: RefineTarget) -> dict[str, Any]:
|
||||
resolved = resolve_refine_target(target)
|
||||
return {
|
||||
**dict(resolved.contract),
|
||||
"video": dict(resolved.contract["video"]),
|
||||
"audio": dict(resolved.contract["audio"]),
|
||||
}
|
||||
|
||||
|
||||
def derive_target_refine_seed(
|
||||
refine_seed: int,
|
||||
physical_group_index: int,
|
||||
target: RefineTarget | str,
|
||||
) -> int:
|
||||
if type(refine_seed) is not int or refine_seed < 0:
|
||||
raise RefineTargetError("refine_seed must be a non-negative integer")
|
||||
if type(physical_group_index) is not int or physical_group_index < 0:
|
||||
raise RefineTargetError("physical_group_index must be a non-negative integer")
|
||||
resolved = resolve_refine_target(target)
|
||||
namespace = str(resolved.contract["seed_namespace"])
|
||||
payload = f"{namespace}:{refine_seed}:{physical_group_index}".encode("ascii")
|
||||
return int.from_bytes(hashlib.blake2b(payload, digest_size=8).digest(), "big")
|
||||
|
||||
|
||||
_SIGMA_RANGE_FIELDS = (
|
||||
"schema_version",
|
||||
"mode",
|
||||
"source_sigma_hash",
|
||||
"sigma_hash",
|
||||
"start_sigma",
|
||||
"end_sigma",
|
||||
"evaluation_count",
|
||||
"source_evaluation_count",
|
||||
"start_index",
|
||||
"end_index",
|
||||
)
|
||||
|
||||
|
||||
def build_target_execution_contract(
|
||||
target: RefineTarget,
|
||||
refine_schedule_contract: Mapping[str, Any],
|
||||
) -> dict[str, Any]:
|
||||
"""Combine target policy with sigma-range identity without mutating V1."""
|
||||
|
||||
resolved = resolve_refine_target(target)
|
||||
if not isinstance(refine_schedule_contract, Mapping):
|
||||
raise RefineTargetError("refine_schedule_contract must be a mapping")
|
||||
missing = [
|
||||
name for name in _SIGMA_RANGE_FIELDS if name not in refine_schedule_contract
|
||||
]
|
||||
if missing or not refine_schedule_contract.get("schedule_hash"):
|
||||
details = ", ".join([*missing, "schedule_hash"] if not refine_schedule_contract.get("schedule_hash") else missing)
|
||||
raise RefineTargetError(f"refine schedule range identity is incomplete: {details}")
|
||||
|
||||
sigma_range = {
|
||||
name: refine_schedule_contract[name] for name in _SIGMA_RANGE_FIELDS
|
||||
}
|
||||
sigma_range["source_schedule_hash"] = str(
|
||||
refine_schedule_contract["schedule_hash"]
|
||||
)
|
||||
contract: dict[str, Any] = {
|
||||
"magic": EXECUTION_MAGIC,
|
||||
"schema_version": EXECUTION_SCHEMA_VERSION,
|
||||
"policy_authority": "refine_target_contract_v1",
|
||||
"target": serializable_target_contract(resolved),
|
||||
"sigma_range": sigma_range,
|
||||
}
|
||||
contract["execution_hash"] = _identity(contract)
|
||||
return contract
|
||||
|
||||
@@ -0,0 +1,421 @@
|
||||
"""Pure visible-timeline resolution for Experimental temporal refinement."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
import math
|
||||
from collections.abc import Mapping, Sequence
|
||||
from dataclasses import dataclass
|
||||
from types import MappingProxyType
|
||||
from typing import Any
|
||||
|
||||
from ..temporal import audio_latent_t, latent_slot_offsets, pixel_frames_for_latent_t
|
||||
|
||||
|
||||
MAGIC = "H3_CONTINUUM_REFINE_WINDOW"
|
||||
SCHEMA_VERSION = 1
|
||||
MODE_TIME_WINDOW = "time_window"
|
||||
|
||||
|
||||
class RefineWindowError(ValueError):
|
||||
"""Raised before preparation when a visible time window is invalid."""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class GroupTemporalWindow:
|
||||
"""One physical group's immutable temporal mask ranges."""
|
||||
|
||||
group_index: int
|
||||
logical_chunks: tuple[int, ...]
|
||||
terminal_merged: bool
|
||||
visible_frame_ranges: tuple[tuple[int, int], ...]
|
||||
physical_frame_ranges: tuple[tuple[int, int], ...]
|
||||
video_slot_ranges: tuple[tuple[int, int], ...]
|
||||
audio_tick_ranges: tuple[tuple[int, int], ...]
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class RefineWindow:
|
||||
"""One versioned visible-output window with no Tensor or runtime object."""
|
||||
|
||||
selected_group_indices: tuple[int, ...]
|
||||
groups: tuple[GroupTemporalWindow, ...]
|
||||
contract: Mapping[str, Any]
|
||||
|
||||
def group(self, group_index: int) -> GroupTemporalWindow | None:
|
||||
for group in self.groups:
|
||||
if group.group_index == int(group_index):
|
||||
return group
|
||||
return None
|
||||
|
||||
|
||||
def _identity(payload: Mapping[str, Any]) -> str:
|
||||
encoded = json.dumps(
|
||||
dict(payload),
|
||||
sort_keys=True,
|
||||
separators=(",", ":"),
|
||||
).encode("utf-8")
|
||||
return hashlib.sha256(encoded).hexdigest()
|
||||
|
||||
|
||||
def _merge_ranges(values: Sequence[tuple[int, int]]) -> tuple[tuple[int, int], ...]:
|
||||
ordered = sorted(
|
||||
(int(start), int(stop))
|
||||
for start, stop in values
|
||||
if int(stop) > int(start)
|
||||
)
|
||||
merged: list[list[int]] = []
|
||||
for start, stop in ordered:
|
||||
if merged and start <= merged[-1][1]:
|
||||
merged[-1][1] = max(merged[-1][1], stop)
|
||||
else:
|
||||
merged.append([start, stop])
|
||||
return tuple((start, stop) for start, stop in merged)
|
||||
|
||||
|
||||
def _indices_to_ranges(indices: Sequence[int]) -> tuple[tuple[int, int], ...]:
|
||||
ordered = sorted(set(int(value) for value in indices))
|
||||
if not ordered:
|
||||
return ()
|
||||
ranges: list[tuple[int, int]] = []
|
||||
start = previous = ordered[0]
|
||||
for value in ordered[1:]:
|
||||
if value == previous + 1:
|
||||
previous = value
|
||||
continue
|
||||
ranges.append((start, previous + 1))
|
||||
start = previous = value
|
||||
ranges.append((start, previous + 1))
|
||||
return tuple(ranges)
|
||||
|
||||
|
||||
def _overlaps(
|
||||
start: int,
|
||||
stop: int,
|
||||
ranges: Sequence[tuple[int, int]],
|
||||
) -> bool:
|
||||
return any(start < range_stop and stop > range_start for range_start, range_stop in ranges)
|
||||
|
||||
|
||||
def _contract_groups(assembly_plan: Mapping[str, Any]) -> list[Mapping[str, Any]]:
|
||||
if not isinstance(assembly_plan, Mapping):
|
||||
raise RefineWindowError("assembly_plan must be a mapping")
|
||||
contract = assembly_plan.get("second_pass_contract")
|
||||
if not isinstance(contract, Mapping) or contract.get("version") != 1:
|
||||
raise RefineWindowError("assembly_plan has no Second Pass contract version 1")
|
||||
groups = contract.get("physical_groups")
|
||||
if (
|
||||
not isinstance(groups, Sequence)
|
||||
or isinstance(groups, (str, bytes))
|
||||
or not groups
|
||||
or not all(isinstance(group, Mapping) for group in groups)
|
||||
):
|
||||
raise RefineWindowError("assembly_plan has no physical groups")
|
||||
return list(groups)
|
||||
|
||||
|
||||
def _logical_chunks(group: Mapping[str, Any], group_index: int) -> tuple[int, ...]:
|
||||
values = group.get("logical_chunks")
|
||||
if (
|
||||
not isinstance(values, Sequence)
|
||||
or isinstance(values, (str, bytes))
|
||||
or not values
|
||||
or any(type(value) is not int or value <= 0 for value in values)
|
||||
):
|
||||
raise RefineWindowError(
|
||||
f"physical group {group_index + 1} has invalid logical chunk identity"
|
||||
)
|
||||
chunks = tuple(int(value) for value in values)
|
||||
if tuple(sorted(chunks)) != chunks or len(set(chunks)) != len(chunks):
|
||||
raise RefineWindowError(
|
||||
f"physical group {group_index + 1} logical chunks are not ordered and unique"
|
||||
)
|
||||
return chunks
|
||||
|
||||
|
||||
def _visible_units(
|
||||
assembly_plan: Mapping[str, Any],
|
||||
groups: Sequence[Mapping[str, Any]],
|
||||
) -> tuple[list[dict[str, int]], int]:
|
||||
decode_groups = assembly_plan.get("decode_groups")
|
||||
if isinstance(decode_groups, Sequence) and not isinstance(
|
||||
decode_groups, (str, bytes)
|
||||
):
|
||||
if len(decode_groups) != len(groups) or not all(
|
||||
isinstance(group, Mapping) for group in decode_groups
|
||||
):
|
||||
raise RefineWindowError(
|
||||
"assembly_plan decode groups differ from Second Pass physical groups"
|
||||
)
|
||||
source_units: Sequence[Mapping[str, Any]] = decode_groups
|
||||
else:
|
||||
source_units = groups
|
||||
|
||||
cursor = 0
|
||||
units: list[dict[str, int]] = []
|
||||
for group_index, (group, source) in enumerate(zip(groups, source_units, strict=True)):
|
||||
physical_frames = int(group.get("physical_frames", 0))
|
||||
trim_frames = int(group.get("trim_prefix_frames", -1))
|
||||
source_latent_t = int(group.get("source_latent_t", 0))
|
||||
audio_shape = group.get("source_audio_shape")
|
||||
if physical_frames <= 0 or trim_frames < 0 or trim_frames >= physical_frames:
|
||||
raise RefineWindowError(
|
||||
f"physical group {group_index + 1} frame geometry is invalid"
|
||||
)
|
||||
if source_latent_t <= 0 or pixel_frames_for_latent_t(source_latent_t) != physical_frames:
|
||||
raise RefineWindowError(
|
||||
f"physical group {group_index + 1} Video latent T differs from its frame grid"
|
||||
)
|
||||
if (
|
||||
not isinstance(audio_shape, Sequence)
|
||||
or isinstance(audio_shape, (str, bytes))
|
||||
or len(audio_shape) != 4
|
||||
or int(audio_shape[-1]) != audio_latent_t(physical_frames)
|
||||
):
|
||||
raise RefineWindowError(
|
||||
f"physical group {group_index + 1} Audio latent T differs from its frame grid"
|
||||
)
|
||||
net_frames = physical_frames - trim_frames
|
||||
source_total = int(source.get("total_frames", physical_frames))
|
||||
source_trim = int(source.get("trim_frames", trim_frames))
|
||||
source_net = int(source.get("net_frames", source_total - source_trim))
|
||||
source_start = int(source.get("frame_start", cursor))
|
||||
source_stop = int(source.get("frame_stop", source_start + source_net))
|
||||
if (
|
||||
source_total != physical_frames
|
||||
or source_trim != trim_frames
|
||||
or source_net != net_frames
|
||||
or source_start != cursor
|
||||
or source_stop != cursor + net_frames
|
||||
):
|
||||
raise RefineWindowError(
|
||||
f"physical group {group_index + 1} visible range is inconsistent"
|
||||
)
|
||||
units.append(
|
||||
{
|
||||
"group_index": group_index,
|
||||
"visible_start": source_start,
|
||||
"visible_stop": source_stop,
|
||||
"physical_frames": physical_frames,
|
||||
"trim_frames": trim_frames,
|
||||
"video_t": source_latent_t,
|
||||
"audio_t": int(audio_shape[-1]),
|
||||
}
|
||||
)
|
||||
cursor = source_stop
|
||||
return units, cursor
|
||||
|
||||
|
||||
def _output_to_natural_ranges(
|
||||
output_start: int,
|
||||
output_stop: int,
|
||||
*,
|
||||
natural_frames: int,
|
||||
target_frames: int,
|
||||
preserve_final_frame: bool,
|
||||
) -> tuple[tuple[int, int], ...]:
|
||||
mappings: list[tuple[int, int, int, bool]] = []
|
||||
if target_frames >= natural_frames:
|
||||
mappings.append((0, natural_frames, 0, False))
|
||||
if target_frames > natural_frames:
|
||||
mappings.append((natural_frames, target_frames, natural_frames - 1, True))
|
||||
elif preserve_final_frame and target_frames >= 2:
|
||||
mappings.extend(
|
||||
(
|
||||
(0, target_frames - 1, 0, False),
|
||||
(target_frames - 1, target_frames, natural_frames - 1, True),
|
||||
)
|
||||
)
|
||||
else:
|
||||
mappings.append((0, target_frames, 0, False))
|
||||
|
||||
natural_ranges: list[tuple[int, int]] = []
|
||||
for destination_start, destination_stop, source_start, repeated in mappings:
|
||||
overlap_start = max(output_start, destination_start)
|
||||
overlap_stop = min(output_stop, destination_stop)
|
||||
if overlap_stop <= overlap_start:
|
||||
continue
|
||||
if repeated:
|
||||
natural_ranges.append((source_start, source_start + 1))
|
||||
else:
|
||||
mapped_start = source_start + overlap_start - destination_start
|
||||
mapped_stop = source_start + overlap_stop - destination_start
|
||||
natural_ranges.append((mapped_start, mapped_stop))
|
||||
return _merge_ranges(natural_ranges)
|
||||
|
||||
|
||||
def _group_window(
|
||||
group: Mapping[str, Any],
|
||||
unit: Mapping[str, int],
|
||||
natural_ranges: Sequence[tuple[int, int]],
|
||||
) -> GroupTemporalWindow | None:
|
||||
visible_start = int(unit["visible_start"])
|
||||
visible_stop = int(unit["visible_stop"])
|
||||
visible_ranges = _merge_ranges(
|
||||
(
|
||||
max(start, visible_start),
|
||||
min(stop, visible_stop),
|
||||
)
|
||||
for start, stop in natural_ranges
|
||||
if start < visible_stop and stop > visible_start
|
||||
)
|
||||
if not visible_ranges:
|
||||
return None
|
||||
|
||||
trim_frames = int(unit["trim_frames"])
|
||||
physical_ranges = _merge_ranges(
|
||||
(
|
||||
trim_frames + start - visible_start,
|
||||
trim_frames + stop - visible_start,
|
||||
)
|
||||
for start, stop in visible_ranges
|
||||
)
|
||||
video_t = int(unit["video_t"])
|
||||
offsets = latent_slot_offsets(video_t)
|
||||
selected_slots = []
|
||||
for slot, slot_start in enumerate(offsets):
|
||||
slot_stop = offsets[slot + 1] if slot + 1 < video_t else int(unit["physical_frames"])
|
||||
if _overlaps(slot_start, slot_stop, physical_ranges):
|
||||
selected_slots.append(slot)
|
||||
video_ranges = _indices_to_ranges(selected_slots)
|
||||
if video_ranges and offsets[video_ranges[0][0]] < trim_frames:
|
||||
raise RefineWindowError(
|
||||
f"physical group {int(unit['group_index']) + 1} Video grid would expose "
|
||||
"the protected continuation prefix"
|
||||
)
|
||||
|
||||
audio_ranges = _merge_ranges(
|
||||
(
|
||||
max(0, min(int(unit["audio_t"]), audio_latent_t(start))),
|
||||
max(0, min(int(unit["audio_t"]), audio_latent_t(stop))),
|
||||
)
|
||||
for start, stop in physical_ranges
|
||||
)
|
||||
protected_audio_stop = audio_latent_t(trim_frames)
|
||||
if audio_ranges and audio_ranges[0][0] < protected_audio_stop:
|
||||
raise RefineWindowError(
|
||||
f"physical group {int(unit['group_index']) + 1} Audio grid would expose "
|
||||
"the protected continuation prefix"
|
||||
)
|
||||
if not video_ranges or not audio_ranges:
|
||||
raise RefineWindowError(
|
||||
f"physical group {int(unit['group_index']) + 1} window resolves to an empty AV grid"
|
||||
)
|
||||
return GroupTemporalWindow(
|
||||
group_index=int(unit["group_index"]),
|
||||
logical_chunks=_logical_chunks(group, int(unit["group_index"])),
|
||||
terminal_merged=bool(group.get("terminal_merged", False)),
|
||||
visible_frame_ranges=visible_ranges,
|
||||
physical_frame_ranges=physical_ranges,
|
||||
video_slot_ranges=video_ranges,
|
||||
audio_tick_ranges=audio_ranges,
|
||||
)
|
||||
|
||||
|
||||
def resolve_refine_window(
|
||||
start_sec: float,
|
||||
end_sec: float,
|
||||
assembly_plan: Mapping[str, Any],
|
||||
) -> RefineWindow:
|
||||
"""Resolve final visible output time to protected physical AV ranges.
|
||||
|
||||
The requested interval is half-open. Fractions select every output frame
|
||||
interval they overlap. Continuation trim prefixes are never selected.
|
||||
"""
|
||||
|
||||
try:
|
||||
requested_start = float(start_sec)
|
||||
requested_end = float(end_sec)
|
||||
except (TypeError, ValueError) as exc:
|
||||
raise RefineWindowError("refine window seconds must be numeric") from exc
|
||||
if not math.isfinite(requested_start) or not math.isfinite(requested_end):
|
||||
raise RefineWindowError("refine window seconds must be finite")
|
||||
if requested_start >= requested_end:
|
||||
raise RefineWindowError("refine window start must be less than end")
|
||||
|
||||
groups = _contract_groups(assembly_plan)
|
||||
units, natural_frames = _visible_units(assembly_plan, groups)
|
||||
fps = int(assembly_plan.get("fps", 0))
|
||||
target_frames = int(assembly_plan.get("target_frames", 0))
|
||||
if fps <= 0 or target_frames <= 0 or natural_frames <= 0:
|
||||
raise RefineWindowError("assembly_plan visible timeline is invalid")
|
||||
|
||||
clamped_start = min(max(requested_start, 0.0), target_frames / fps)
|
||||
clamped_end = min(max(requested_end, 0.0), target_frames / fps)
|
||||
output_start = max(0, min(target_frames, math.floor(clamped_start * fps + 1e-9)))
|
||||
output_stop = max(0, min(target_frames, math.ceil(clamped_end * fps - 1e-9)))
|
||||
if output_stop <= output_start:
|
||||
raise RefineWindowError("refine window does not overlap the visible output")
|
||||
|
||||
natural_ranges = _output_to_natural_ranges(
|
||||
output_start,
|
||||
output_stop,
|
||||
natural_frames=natural_frames,
|
||||
target_frames=target_frames,
|
||||
preserve_final_frame=bool(assembly_plan.get("preserve_final_frame", False)),
|
||||
)
|
||||
if not natural_ranges:
|
||||
raise RefineWindowError("refine window has no natural timeline source")
|
||||
|
||||
resolved_groups = tuple(
|
||||
group_window
|
||||
for group, unit in zip(groups, units, strict=True)
|
||||
if (
|
||||
group_window := _group_window(
|
||||
group,
|
||||
unit,
|
||||
natural_ranges,
|
||||
)
|
||||
)
|
||||
is not None
|
||||
)
|
||||
if not resolved_groups:
|
||||
raise RefineWindowError("refine window selects no physical group")
|
||||
selected = tuple(group.group_index for group in resolved_groups)
|
||||
group_contracts = [
|
||||
{
|
||||
"group_index": group.group_index,
|
||||
"physical_group": group.group_index + 1,
|
||||
"logical_chunks": list(group.logical_chunks),
|
||||
"terminal_merged": group.terminal_merged,
|
||||
"visible_frame_ranges": [list(value) for value in group.visible_frame_ranges],
|
||||
"physical_frame_ranges": [list(value) for value in group.physical_frame_ranges],
|
||||
"video_slot_ranges": [list(value) for value in group.video_slot_ranges],
|
||||
"audio_tick_ranges": [list(value) for value in group.audio_tick_ranges],
|
||||
}
|
||||
for group in resolved_groups
|
||||
]
|
||||
contract: dict[str, Any] = {
|
||||
"magic": MAGIC,
|
||||
"schema_version": SCHEMA_VERSION,
|
||||
"mode": MODE_TIME_WINDOW,
|
||||
"timeline": "final_visible_output",
|
||||
"interval": "half_open",
|
||||
"requested_start_sec": requested_start,
|
||||
"requested_end_sec": requested_end,
|
||||
"effective_start_sec": output_start / fps,
|
||||
"effective_end_sec": output_stop / fps,
|
||||
"output_frame_range": [output_start, output_stop],
|
||||
"target_frames": target_frames,
|
||||
"natural_frames": natural_frames,
|
||||
"natural_frame_ranges": [list(value) for value in natural_ranges],
|
||||
"selected_physical_groups": [index + 1 for index in selected],
|
||||
"groups": group_contracts,
|
||||
"continuation_prefix_policy": "always_protected",
|
||||
"outside_window_policy": "mask_zero_then_bit_exact_restore",
|
||||
"physical_group_atomicity": "preserved",
|
||||
"temporal_quantization": "intersecting_video_slots_and_audio_ticks",
|
||||
}
|
||||
contract["window_hash"] = _identity(contract)
|
||||
return RefineWindow(
|
||||
selected_group_indices=selected,
|
||||
groups=resolved_groups,
|
||||
contract=MappingProxyType(contract),
|
||||
)
|
||||
|
||||
|
||||
def serializable_window_contract(window: RefineWindow) -> dict[str, Any]:
|
||||
if not isinstance(window, RefineWindow):
|
||||
raise RefineWindowError("refine_window must be a RefineWindow")
|
||||
return json.loads(json.dumps(dict(window.contract)))
|
||||
@@ -0,0 +1,920 @@
|
||||
"""Read-only V3.8 reliability diagnostics.
|
||||
|
||||
The helpers in this module inspect shapes and existing metadata only. They do
|
||||
not resize, encode, hash, copy, or otherwise modify user tensors.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Callable, Mapping, Sequence
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
|
||||
import torch
|
||||
|
||||
from ..compatibility import check_comfy_h3_runtime
|
||||
from ..constants import (
|
||||
DIAGNOSTICS_BASIC,
|
||||
DIAGNOSTICS_FULL,
|
||||
DIAGNOSTICS_OFF,
|
||||
FPS,
|
||||
normalize_diagnostics_mode,
|
||||
)
|
||||
from ..reference import resolve_reference_image_size
|
||||
from ..reference_video import (
|
||||
REFERENCE_VIDEO_SIZE_EFFICIENT,
|
||||
resolve_reference_video_frame_count,
|
||||
resolve_reference_video_size,
|
||||
)
|
||||
from ..temporal import (
|
||||
align_frame_count_up,
|
||||
audio_grid_offset,
|
||||
audio_latent_t,
|
||||
context_slots,
|
||||
is_valid_frame_count,
|
||||
video_latent_t,
|
||||
)
|
||||
|
||||
|
||||
VISUAL_LOAD_LOW_MAX = 0.75
|
||||
VISUAL_LOAD_MEDIUM_MAX = 1.75
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class DiagnosticSection:
|
||||
basic: tuple[str, ...] = ()
|
||||
detailed: tuple[str, ...] = ()
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class V38Diagnostics:
|
||||
basic: tuple[str, ...]
|
||||
detailed: tuple[str, ...]
|
||||
|
||||
|
||||
def _combine_sections(*sections: DiagnosticSection) -> V38Diagnostics:
|
||||
return V38Diagnostics(
|
||||
basic=tuple(line for section in sections for line in section.basic),
|
||||
detailed=tuple(line for section in sections for line in section.detailed),
|
||||
)
|
||||
|
||||
|
||||
def _physical_groups(assembly_plan: Any) -> list[Any]:
|
||||
if not isinstance(assembly_plan, Mapping):
|
||||
return []
|
||||
decode_groups = assembly_plan.get("decode_groups")
|
||||
if isinstance(decode_groups, list) and decode_groups:
|
||||
return list(decode_groups)
|
||||
chunks = assembly_plan.get("chunks")
|
||||
return list(chunks) if isinstance(chunks, list) else []
|
||||
|
||||
|
||||
def _latent_outputs(value: Any) -> list[Any]:
|
||||
return list(value) if isinstance(value, (list, tuple)) else []
|
||||
|
||||
|
||||
def _latent_samples(value: Any) -> Any:
|
||||
return value.get("samples") if isinstance(value, Mapping) else None
|
||||
|
||||
|
||||
def _image_geometry(value: Any) -> tuple[int, int]:
|
||||
shape = getattr(value, "shape", None)
|
||||
if shape is None or len(shape) != 4:
|
||||
raise ValueError("IMAGE must have shape [B,H,W,C]")
|
||||
height = int(shape[1])
|
||||
width = int(shape[2])
|
||||
if height < 1 or width < 1:
|
||||
raise ValueError("IMAGE geometry must be positive")
|
||||
return width, height
|
||||
|
||||
|
||||
def _video_guide_geometry(value: Any) -> tuple[int, int, int]:
|
||||
shape = getattr(value, "shape", None)
|
||||
if shape is None or len(shape) != 4:
|
||||
raise ValueError("Video Guide must have shape [T,H,W,C]")
|
||||
frames = int(shape[0])
|
||||
height = int(shape[1])
|
||||
width = int(shape[2])
|
||||
if frames < 1 or height < 1 or width < 1:
|
||||
raise ValueError("Video Guide geometry must be positive")
|
||||
return frames, width, height
|
||||
|
||||
|
||||
def _native_chunk_frames(chunk_seconds: float) -> int:
|
||||
return align_frame_count_up(int(round(float(chunk_seconds) * FPS)))
|
||||
|
||||
|
||||
def build_frame_alignment_diagnostics(
|
||||
*,
|
||||
video_latents: Any,
|
||||
assembly_plan: Any,
|
||||
video_guide: Any = None,
|
||||
chunk_seconds: float,
|
||||
) -> DiagnosticSection:
|
||||
"""Inspect Video Guide alignment and physical video latent lengths."""
|
||||
|
||||
basic: list[str] = []
|
||||
detailed: list[str] = []
|
||||
if video_guide is not None:
|
||||
try:
|
||||
source_frames, _source_width, _source_height = _video_guide_geometry(
|
||||
video_guide
|
||||
)
|
||||
aligned_frames = resolve_reference_video_frame_count(
|
||||
source_frames,
|
||||
_native_chunk_frames(chunk_seconds),
|
||||
)
|
||||
if source_frames < aligned_frames:
|
||||
action = "final-frame pad"
|
||||
elif source_frames > aligned_frames:
|
||||
action = "trimmed to one-chunk H3 limit"
|
||||
else:
|
||||
action = "unchanged"
|
||||
line = (
|
||||
f"Frame alignment: Video Guide {source_frames} -> {aligned_frames} "
|
||||
f"({action}, H3 17k+5)."
|
||||
)
|
||||
if action != "unchanged":
|
||||
basic.append(line)
|
||||
detailed.append(line)
|
||||
except Exception as exc:
|
||||
line = (
|
||||
"Frame alignment advisory: Video Guide alignment could not be "
|
||||
f"inspected ({type(exc).__name__}: {exc})."
|
||||
)
|
||||
basic.append(line)
|
||||
detailed.append(line)
|
||||
|
||||
groups = _physical_groups(assembly_plan)
|
||||
outputs = _latent_outputs(video_latents)
|
||||
if not groups:
|
||||
line = "Frame alignment advisory: physical group metadata is unavailable."
|
||||
basic.append(line)
|
||||
detailed.append(line)
|
||||
return DiagnosticSection(tuple(basic), tuple(detailed))
|
||||
if len(outputs) != len(groups):
|
||||
line = (
|
||||
"Frame alignment advisory: physical video output count "
|
||||
f"{len(outputs)} does not match group count {len(groups)}."
|
||||
)
|
||||
basic.append(line)
|
||||
detailed.append(line)
|
||||
|
||||
for index, group in enumerate(groups, start=1):
|
||||
problems: list[str] = []
|
||||
try:
|
||||
if not isinstance(group, Mapping):
|
||||
raise ValueError("group metadata is not a mapping")
|
||||
frames = int(group["total_frames"])
|
||||
trim = int(group["trim_frames"])
|
||||
net = int(group["net_frames"])
|
||||
metadata_t = int(group["expected_video_latent_t"])
|
||||
if not is_valid_frame_count(frames):
|
||||
problems.append("frames are not on H3 17k+5")
|
||||
expected_t = None
|
||||
else:
|
||||
expected_t = video_latent_t(frames)
|
||||
if metadata_t != expected_t:
|
||||
problems.append("metadata T differs from native grid")
|
||||
if frames - trim != net:
|
||||
problems.append("total-trim differs from net")
|
||||
samples = (
|
||||
_latent_samples(outputs[index - 1])
|
||||
if index <= len(outputs)
|
||||
else None
|
||||
)
|
||||
if not torch.is_tensor(samples) or samples.ndim < 3:
|
||||
actual_t = None
|
||||
problems.append("video LATENT samples are missing or invalid")
|
||||
else:
|
||||
actual_t = int(samples.shape[2])
|
||||
if actual_t != metadata_t:
|
||||
problems.append("actual T differs from metadata")
|
||||
if expected_t is not None and actual_t != expected_t:
|
||||
problems.append("actual T differs from native grid")
|
||||
result = "PASS" if not problems else "ADVISORY"
|
||||
expected_text = "n/a" if expected_t is None else str(expected_t)
|
||||
actual_text = "n/a" if actual_t is None else str(actual_t)
|
||||
detailed.append(
|
||||
f"Frame grid: group={index} frames={frames} trim={trim} net={net} "
|
||||
f"video_t={actual_text} metadata={metadata_t} "
|
||||
f"expected={expected_text} {result}."
|
||||
)
|
||||
except Exception as exc:
|
||||
problems.append(f"{type(exc).__name__}: {exc}")
|
||||
detailed.append(
|
||||
f"Frame grid: group={index} unavailable ADVISORY "
|
||||
f"({problems[-1]})."
|
||||
)
|
||||
if problems:
|
||||
basic.append(
|
||||
f"Frame alignment advisory: group {index}: "
|
||||
+ "; ".join(problems)
|
||||
+ "."
|
||||
)
|
||||
return DiagnosticSection(tuple(basic), tuple(detailed))
|
||||
|
||||
|
||||
def validate_audio_latent_lengths(
|
||||
*,
|
||||
audio_latents: Any,
|
||||
assembly_plan: Any,
|
||||
) -> DiagnosticSection:
|
||||
"""Validate physical audio latent shapes without reading tensor values."""
|
||||
|
||||
basic: list[str] = []
|
||||
detailed: list[str] = []
|
||||
groups = _physical_groups(assembly_plan)
|
||||
outputs = _latent_outputs(audio_latents)
|
||||
if not groups:
|
||||
line = "Audio latent advisory: physical group metadata is unavailable."
|
||||
return DiagnosticSection((line,), (line,))
|
||||
if len(outputs) != len(groups):
|
||||
line = (
|
||||
f"Audio latent advisory: physical output count {len(outputs)} "
|
||||
f"does not match group count {len(groups)}."
|
||||
)
|
||||
basic.append(line)
|
||||
detailed.append(line)
|
||||
|
||||
for index, group in enumerate(groups, start=1):
|
||||
problems: list[str] = []
|
||||
frames = metadata_t = nominal_t = actual_t = None
|
||||
phase = None
|
||||
try:
|
||||
if not isinstance(group, Mapping):
|
||||
raise ValueError("group metadata is not a mapping")
|
||||
frames = int(group["total_frames"])
|
||||
metadata_t = int(group["expected_audio_latent_t"])
|
||||
nominal_t = audio_latent_t(frames)
|
||||
samples = (
|
||||
_latent_samples(outputs[index - 1])
|
||||
if index <= len(outputs)
|
||||
else None
|
||||
)
|
||||
if not torch.is_tensor(samples):
|
||||
problems.append("LATENT samples are missing or not a Tensor")
|
||||
elif samples.ndim != 4:
|
||||
problems.append(f"rank is {samples.ndim}, expected 4")
|
||||
else:
|
||||
if int(samples.shape[0]) < 1:
|
||||
problems.append("batch dimension is empty")
|
||||
if int(samples.shape[1]) != 32:
|
||||
problems.append(f"channels={int(samples.shape[1])}, expected 32")
|
||||
if int(samples.shape[2]) != 2:
|
||||
problems.append(f"stereo={int(samples.shape[2])}, expected 2")
|
||||
actual_t = int(samples.shape[-1])
|
||||
if actual_t <= 0:
|
||||
problems.append("T must be positive")
|
||||
else:
|
||||
phase = audio_grid_offset(frames, actual_t)
|
||||
if actual_t != metadata_t:
|
||||
problems.append(
|
||||
f"metadata={metadata_t} actual={actual_t} "
|
||||
f"delta={actual_t - metadata_t}"
|
||||
)
|
||||
if not -0.500001 <= phase <= 0.500001:
|
||||
problems.append(f"phase={phase:.6f} is outside [-0.5,0.5]")
|
||||
result = "PASS" if not problems else "ADVISORY"
|
||||
detailed.append(
|
||||
f"Audio latent check: group={index} frames={frames} "
|
||||
f"metadata={metadata_t} actual="
|
||||
f"{'n/a' if actual_t is None else actual_t} nominal={nominal_t} "
|
||||
f"phase={'n/a' if phase is None else f'{phase:.6f}'} {result}."
|
||||
)
|
||||
except Exception as exc:
|
||||
problems.append(f"{type(exc).__name__}: {exc}")
|
||||
detailed.append(
|
||||
f"Audio latent check: group={index} unavailable ADVISORY "
|
||||
f"({problems[-1]})."
|
||||
)
|
||||
if problems:
|
||||
basic.append(
|
||||
f"Audio latent advisory: group {index}: "
|
||||
+ "; ".join(problems)
|
||||
+ "."
|
||||
)
|
||||
return DiagnosticSection(tuple(basic), tuple(detailed))
|
||||
|
||||
|
||||
def collect_core_compatibility_advisory(
|
||||
checker: Callable[[], list[str]] | None = None,
|
||||
) -> DiagnosticSection:
|
||||
"""Collect the existing feature-based Core advisory after successful generation."""
|
||||
|
||||
active_checker = checker or check_comfy_h3_runtime
|
||||
try:
|
||||
issues = tuple(dict.fromkeys(str(issue) for issue in active_checker() if issue))
|
||||
except Exception as exc:
|
||||
basic = (
|
||||
"Core compatibility advisory unavailable; generation result was preserved.",
|
||||
)
|
||||
detailed = (
|
||||
basic[0][:-1] + f" ({type(exc).__name__}: {exc}).",
|
||||
)
|
||||
return DiagnosticSection(basic, detailed)
|
||||
if not issues:
|
||||
return DiagnosticSection(
|
||||
(),
|
||||
("Core compatibility: native MiniMax H3 contracts detected.",),
|
||||
)
|
||||
return DiagnosticSection(
|
||||
(
|
||||
"Core compatibility advisory: "
|
||||
f"{len(issues)} native H3 contract difference(s) detected; "
|
||||
"generation completed; enable Detailed Report for details.",
|
||||
),
|
||||
tuple(f"Core compatibility advisory: {issue}." for issue in issues),
|
||||
)
|
||||
|
||||
|
||||
def _visual_load_class(total: float) -> str:
|
||||
if total < VISUAL_LOAD_LOW_MAX:
|
||||
return "Low"
|
||||
if total < VISUAL_LOAD_MEDIUM_MAX:
|
||||
return "Medium"
|
||||
return "High"
|
||||
|
||||
|
||||
def estimate_visual_conditioning_load(
|
||||
*,
|
||||
output_width: int,
|
||||
output_height: int,
|
||||
reference_images: Sequence[Any],
|
||||
reference_size: str,
|
||||
video_guide: Any,
|
||||
video_guide_size: str = REFERENCE_VIDEO_SIZE_EFFICIENT,
|
||||
chunk_seconds: float,
|
||||
still_guide_active: bool,
|
||||
) -> DiagnosticSection:
|
||||
"""Estimate peak per-group relative visual conditioning from geometry only."""
|
||||
|
||||
output_area = int(output_width) * int(output_height)
|
||||
if output_area <= 0:
|
||||
line = "Visual conditioning load advisory: output geometry is invalid."
|
||||
return DiagnosticSection((line,), (line,))
|
||||
|
||||
components: list[tuple[str, float]] = []
|
||||
problems: list[str] = []
|
||||
for socket_index, image in enumerate(reference_images, start=1):
|
||||
if image is None:
|
||||
continue
|
||||
try:
|
||||
source_width, source_height = _image_geometry(image)
|
||||
target_width, target_height = resolve_reference_image_size(
|
||||
source_width,
|
||||
source_height,
|
||||
output_width=int(output_width),
|
||||
output_height=int(output_height),
|
||||
size_mode=str(reference_size),
|
||||
)
|
||||
load = (target_width * target_height) / float(output_area)
|
||||
components.append(
|
||||
(f"Ref{socket_index}={target_width}x{target_height}", load)
|
||||
)
|
||||
except Exception as exc:
|
||||
problems.append(
|
||||
f"Reference Image {socket_index} unavailable "
|
||||
f"({type(exc).__name__}: {exc})"
|
||||
)
|
||||
|
||||
if video_guide is not None:
|
||||
try:
|
||||
source_frames, source_width, source_height = _video_guide_geometry(
|
||||
video_guide
|
||||
)
|
||||
native_frames = _native_chunk_frames(chunk_seconds)
|
||||
aligned_frames = resolve_reference_video_frame_count(
|
||||
source_frames,
|
||||
native_frames,
|
||||
)
|
||||
target_width, target_height = resolve_reference_video_size(
|
||||
source_width,
|
||||
source_height,
|
||||
output_width=int(output_width),
|
||||
output_height=int(output_height),
|
||||
size_mode=str(video_guide_size),
|
||||
)
|
||||
spatial_ratio = (target_width * target_height) / float(output_area)
|
||||
temporal_ratio = video_latent_t(aligned_frames) / float(
|
||||
video_latent_t(native_frames)
|
||||
)
|
||||
components.append(
|
||||
(
|
||||
f"Video Guide={target_width}x{target_height}/{aligned_frames}f",
|
||||
spatial_ratio * temporal_ratio,
|
||||
)
|
||||
)
|
||||
except Exception as exc:
|
||||
problems.append(
|
||||
f"Video Guide unavailable ({type(exc).__name__}: {exc})"
|
||||
)
|
||||
|
||||
basic: list[str] = []
|
||||
detailed: list[str] = []
|
||||
if components:
|
||||
total = sum(load for _name, load in components)
|
||||
classification = _visual_load_class(total)
|
||||
basic_line = (
|
||||
f"Visual conditioning load: {classification} "
|
||||
"(peak per physical group)."
|
||||
)
|
||||
if still_guide_active:
|
||||
basic_line = basic_line[:-1] + "; Still Guide active."
|
||||
basic.append(basic_line)
|
||||
details = "; ".join(
|
||||
f"{name}={load:.3f}" for name, load in components
|
||||
)
|
||||
detailed_line = (
|
||||
f"Visual conditioning load: total={total:.3f} "
|
||||
f"class={classification}; {details}"
|
||||
)
|
||||
if still_guide_active:
|
||||
detailed_line += "; Still Guide=active"
|
||||
detailed.append(detailed_line + ".")
|
||||
elif still_guide_active:
|
||||
basic.append("Still Guide: active.")
|
||||
detailed.append("Still Guide: active (excluded from numeric visual load).")
|
||||
|
||||
for problem in problems:
|
||||
line = f"Visual conditioning load advisory: {problem}."
|
||||
basic.append(line)
|
||||
detailed.append(line)
|
||||
return DiagnosticSection(tuple(basic), tuple(detailed))
|
||||
|
||||
|
||||
@dataclass(frozen=True, slots=True)
|
||||
class _LogicalChunkGeometry:
|
||||
index: int
|
||||
total_frames: int | None
|
||||
trim_frames: int | None
|
||||
net_frames: int | None
|
||||
derived_start: int
|
||||
derived_stop: int
|
||||
visible_start: int | None
|
||||
visible_stop: int | None
|
||||
problems: tuple[str, ...]
|
||||
|
||||
|
||||
def _chunk_boundary_advisory(message: str) -> str:
|
||||
return f"Chunk boundary advisory: {str(message).rstrip('.')}."
|
||||
|
||||
|
||||
def _logical_chunk_geometries(
|
||||
assembly_plan: Any,
|
||||
) -> tuple[list[_LogicalChunkGeometry], list[str]]:
|
||||
problems: list[str] = []
|
||||
if not isinstance(assembly_plan, Mapping):
|
||||
return [], ["Assembly Plan metadata is unavailable"]
|
||||
raw_chunks = assembly_plan.get("chunks")
|
||||
if not isinstance(raw_chunks, list) or not raw_chunks:
|
||||
return [], ["logical chunk metadata is unavailable"]
|
||||
|
||||
geometries: list[_LogicalChunkGeometry] = []
|
||||
cursor = 0
|
||||
for position, chunk in enumerate(raw_chunks, start=1):
|
||||
local: list[str] = []
|
||||
total = trim = net = None
|
||||
visible_start = visible_stop = None
|
||||
index = position
|
||||
if not isinstance(chunk, Mapping):
|
||||
local.append("metadata is not a mapping")
|
||||
else:
|
||||
try:
|
||||
index = int(chunk.get("chunk_index", chunk.get("sequence_index", position)))
|
||||
if index != position:
|
||||
local.append(
|
||||
f"logical order has Chunk {index} at position {position}"
|
||||
)
|
||||
except Exception:
|
||||
index = position
|
||||
local.append("logical chunk index is invalid")
|
||||
try:
|
||||
total = int(chunk["total_frames"])
|
||||
trim = int(chunk["trim_frames"])
|
||||
net = int(chunk["net_frames"])
|
||||
if total < 0:
|
||||
local.append("total_frames is negative")
|
||||
if trim < 0:
|
||||
local.append("trim_frames is negative")
|
||||
if trim > total:
|
||||
local.append("trim_frames exceeds total_frames")
|
||||
if net < 0:
|
||||
local.append("net_frames is negative")
|
||||
if total - trim != net:
|
||||
local.append("total_frames - trim_frames differs from net_frames")
|
||||
except Exception as exc:
|
||||
local.append(
|
||||
"required geometry is unavailable "
|
||||
f"({type(exc).__name__}: {exc})"
|
||||
)
|
||||
|
||||
derived_start = cursor
|
||||
derived_stop = cursor + (net if net is not None and net >= 0 else 0)
|
||||
if isinstance(chunk, Mapping) and "frame_start" in chunk:
|
||||
try:
|
||||
visible_start = int(chunk["frame_start"])
|
||||
if visible_start != derived_start:
|
||||
local.append(
|
||||
f"frame_start={visible_start} differs from derived {derived_start}"
|
||||
)
|
||||
except Exception:
|
||||
local.append("frame_start is invalid")
|
||||
else:
|
||||
visible_start = derived_start if net is not None else None
|
||||
if isinstance(chunk, Mapping) and "frame_stop" in chunk:
|
||||
try:
|
||||
visible_stop = int(chunk["frame_stop"])
|
||||
if visible_stop != derived_stop:
|
||||
local.append(
|
||||
f"frame_stop={visible_stop} differs from derived {derived_stop}"
|
||||
)
|
||||
except Exception:
|
||||
local.append("frame_stop is invalid")
|
||||
else:
|
||||
visible_stop = derived_stop if net is not None else None
|
||||
|
||||
geometries.append(
|
||||
_LogicalChunkGeometry(
|
||||
index=index,
|
||||
total_frames=total,
|
||||
trim_frames=trim,
|
||||
net_frames=net,
|
||||
derived_start=derived_start,
|
||||
derived_stop=derived_stop,
|
||||
visible_start=visible_start,
|
||||
visible_stop=visible_stop,
|
||||
problems=tuple(local),
|
||||
)
|
||||
)
|
||||
problems.extend(f"Chunk {position}: {problem}" for problem in local)
|
||||
cursor = derived_stop
|
||||
return geometries, problems
|
||||
|
||||
|
||||
def _physical_boundary_mapping(
|
||||
*,
|
||||
assembly_plan: Any,
|
||||
logical_count: int,
|
||||
video_latents: Any,
|
||||
audio_latents: Any,
|
||||
) -> tuple[list[Mapping[str, Any]], list[tuple[int, ...]], dict[int, int], list[str]]:
|
||||
problems: list[str] = []
|
||||
if not isinstance(assembly_plan, Mapping):
|
||||
return [], [], {}, ["physical group metadata is unavailable"]
|
||||
|
||||
if "decode_groups" in assembly_plan:
|
||||
raw_groups = assembly_plan.get("decode_groups")
|
||||
if not isinstance(raw_groups, list) or not raw_groups:
|
||||
return [], [], {}, ["physical groups are not a non-empty list"]
|
||||
groups = list(raw_groups)
|
||||
fallback = False
|
||||
else:
|
||||
raw_chunks = assembly_plan.get("chunks")
|
||||
if not isinstance(raw_chunks, list) or not raw_chunks:
|
||||
return [], [], {}, ["physical group metadata is unavailable"]
|
||||
groups = list(raw_chunks)
|
||||
fallback = True
|
||||
|
||||
normalized_groups: list[Mapping[str, Any]] = []
|
||||
logical_groups: list[tuple[int, ...]] = []
|
||||
logical_to_group: dict[int, int] = {}
|
||||
flattened: list[int] = []
|
||||
for group_index, group in enumerate(groups, start=1):
|
||||
if not isinstance(group, Mapping):
|
||||
problems.append(f"physical group {group_index} metadata is not a mapping")
|
||||
normalized_groups.append({})
|
||||
logical_groups.append(())
|
||||
continue
|
||||
normalized_groups.append(group)
|
||||
raw_logical = (
|
||||
[group.get("chunk_index", group.get("sequence_index", group_index))]
|
||||
if fallback
|
||||
else group.get("logical_chunk_indices")
|
||||
)
|
||||
if not isinstance(raw_logical, (list, tuple)) or not raw_logical:
|
||||
problems.append(f"physical group {group_index} has no logical chunks")
|
||||
logical_groups.append(())
|
||||
continue
|
||||
try:
|
||||
logical = tuple(int(value) for value in raw_logical)
|
||||
except Exception:
|
||||
problems.append(f"physical group {group_index} logical chunks are invalid")
|
||||
logical_groups.append(())
|
||||
continue
|
||||
logical_groups.append(logical)
|
||||
flattened.extend(logical)
|
||||
if tuple(sorted(logical)) != logical:
|
||||
problems.append(f"physical group {group_index} logical order is reversed")
|
||||
terminal = bool(group.get("terminal_merged", False))
|
||||
if terminal:
|
||||
expected_terminal = (logical_count - 1, logical_count)
|
||||
if len(logical) != 2 or logical != expected_terminal:
|
||||
problems.append(
|
||||
f"physical group {group_index} Terminal Merge mapping is invalid"
|
||||
)
|
||||
elif len(logical) != 1:
|
||||
problems.append(
|
||||
f"physical group {group_index} has multiple logical chunks without Terminal Merge"
|
||||
)
|
||||
for chunk_index in logical:
|
||||
if chunk_index < 1 or chunk_index > logical_count:
|
||||
problems.append(
|
||||
f"physical group {group_index} references invalid Chunk {chunk_index}"
|
||||
)
|
||||
elif chunk_index in logical_to_group:
|
||||
problems.append(f"logical Chunk {chunk_index} is mapped more than once")
|
||||
else:
|
||||
logical_to_group[chunk_index] = group_index
|
||||
|
||||
expected = list(range(1, logical_count + 1))
|
||||
if flattened != expected:
|
||||
missing = [value for value in expected if value not in flattened]
|
||||
if missing:
|
||||
problems.append(
|
||||
"physical group mapping does not cover all logical chunks "
|
||||
f"(missing={missing})"
|
||||
)
|
||||
if not missing and flattened != sorted(flattened):
|
||||
problems.append("physical group logical chunk order is not contiguous")
|
||||
|
||||
video_count = len(_latent_outputs(video_latents))
|
||||
audio_count = len(_latent_outputs(audio_latents))
|
||||
if video_count != len(groups) or audio_count != len(groups):
|
||||
problems.append(
|
||||
"physical output/group counts differ "
|
||||
f"(groups={len(groups)}, video={video_count}, audio={audio_count})"
|
||||
)
|
||||
return normalized_groups, logical_groups, logical_to_group, problems
|
||||
|
||||
|
||||
def _second_pass_boundary_contract_problems(
|
||||
*,
|
||||
assembly_plan: Any,
|
||||
groups: Sequence[Mapping[str, Any]],
|
||||
logical_groups: Sequence[tuple[int, ...]],
|
||||
) -> tuple[list[str], str | None]:
|
||||
if not isinstance(assembly_plan, Mapping) or "second_pass_contract" not in assembly_plan:
|
||||
return [], None
|
||||
contract = assembly_plan.get("second_pass_contract")
|
||||
if not isinstance(contract, Mapping):
|
||||
return ["Second Pass contract is not a mapping"], "Second Pass contract: UNAVAILABLE."
|
||||
contract_groups = contract.get("physical_groups")
|
||||
if not isinstance(contract_groups, list):
|
||||
return ["Second Pass physical_groups is not a list"], "Second Pass contract: UNAVAILABLE."
|
||||
|
||||
problems: list[str] = []
|
||||
if len(contract_groups) != len(groups):
|
||||
problems.append(
|
||||
"Second Pass physical group count differs from decode groups "
|
||||
f"({len(contract_groups)} != {len(groups)})"
|
||||
)
|
||||
for index, (decode_group, logical) in enumerate(
|
||||
zip(groups, logical_groups, strict=False)
|
||||
):
|
||||
if index >= len(contract_groups):
|
||||
break
|
||||
contract_group = contract_groups[index]
|
||||
if not isinstance(contract_group, Mapping):
|
||||
problems.append(f"Second Pass group {index} is not a mapping")
|
||||
continue
|
||||
raw_contract_logical = contract_group.get("logical_chunks")
|
||||
contract_logical = (
|
||||
tuple(raw_contract_logical)
|
||||
if isinstance(raw_contract_logical, (list, tuple))
|
||||
else ()
|
||||
)
|
||||
checks = (
|
||||
("group_id", contract_group.get("group_id"), index),
|
||||
("logical_chunks", contract_logical, logical),
|
||||
(
|
||||
"physical_frames",
|
||||
contract_group.get("physical_frames"),
|
||||
decode_group.get("total_frames"),
|
||||
),
|
||||
(
|
||||
"trim_prefix_frames",
|
||||
contract_group.get("trim_prefix_frames"),
|
||||
decode_group.get("trim_frames"),
|
||||
),
|
||||
(
|
||||
"terminal_merged",
|
||||
bool(contract_group.get("terminal_merged", False)),
|
||||
bool(decode_group.get("terminal_merged", False)),
|
||||
),
|
||||
)
|
||||
for name, actual, expected in checks:
|
||||
if actual != expected:
|
||||
problems.append(
|
||||
f"Second Pass group {index} {name} differs "
|
||||
f"({actual!r} != {expected!r})"
|
||||
)
|
||||
result = "PASS" if not problems else "ADVISORY"
|
||||
return problems, f"Second Pass contract: groups={len(contract_groups)} {result}."
|
||||
|
||||
|
||||
def build_chunk_boundary_diagnostics(
|
||||
*,
|
||||
video_latents: Any,
|
||||
audio_latents: Any,
|
||||
assembly_plan: Any,
|
||||
) -> DiagnosticSection:
|
||||
"""Inspect logical/physical chunk boundaries using metadata and shapes only."""
|
||||
|
||||
detailed = [
|
||||
"Chunk boundary contract: structural diagnostic only; "
|
||||
"no image/audio similarity measurement."
|
||||
]
|
||||
basic: list[str] = []
|
||||
geometries, logical_problems = _logical_chunk_geometries(assembly_plan)
|
||||
groups, logical_groups, logical_to_group, mapping_problems = (
|
||||
_physical_boundary_mapping(
|
||||
assembly_plan=assembly_plan,
|
||||
logical_count=len(geometries),
|
||||
video_latents=video_latents,
|
||||
audio_latents=audio_latents,
|
||||
)
|
||||
)
|
||||
second_pass_problems, second_pass_line = _second_pass_boundary_contract_problems(
|
||||
assembly_plan=assembly_plan,
|
||||
groups=groups,
|
||||
logical_groups=logical_groups,
|
||||
)
|
||||
global_problems = logical_problems + mapping_problems + second_pass_problems
|
||||
for problem in dict.fromkeys(global_problems):
|
||||
basic.append(_chunk_boundary_advisory(problem))
|
||||
if second_pass_line is not None:
|
||||
detailed.append(second_pass_line)
|
||||
|
||||
for boundary_index in range(1, len(geometries)):
|
||||
left = geometries[boundary_index - 1]
|
||||
right = geometries[boundary_index]
|
||||
local = list(left.problems) + list(right.problems)
|
||||
if left.visible_stop is None or right.visible_start is None:
|
||||
gap = None
|
||||
local.append("visible range is unavailable")
|
||||
else:
|
||||
gap = int(right.visible_start) - int(left.visible_stop)
|
||||
if gap != 0:
|
||||
local.append("non-contiguous visible range")
|
||||
|
||||
context_frames = right.trim_frames
|
||||
context_video_t = context_audio_t = None
|
||||
if context_frames is None:
|
||||
local.append("incoming context is unavailable")
|
||||
else:
|
||||
try:
|
||||
context_video_t = context_slots(context_frames)
|
||||
context_audio_t = audio_latent_t(context_frames)
|
||||
except Exception as exc:
|
||||
local.append(
|
||||
f"incoming context {context_frames}f is invalid "
|
||||
f"({type(exc).__name__}: {exc})"
|
||||
)
|
||||
|
||||
left_group = logical_to_group.get(left.index)
|
||||
right_group = logical_to_group.get(right.index)
|
||||
if left_group is None or right_group is None:
|
||||
local.append("physical group mapping is unavailable")
|
||||
classification = "UNAVAILABLE"
|
||||
detailed.append(
|
||||
f"Boundary {left.index}→{right.index}: physical mapping unavailable; "
|
||||
f"UNAVAILABLE ({'; '.join(dict.fromkeys(local))})."
|
||||
)
|
||||
elif left_group == right_group:
|
||||
group = groups[right_group - 1] if right_group <= len(groups) else {}
|
||||
terminal = bool(group.get("terminal_merged", False))
|
||||
expected_pair = (left.index, right.index)
|
||||
actual_pair = (
|
||||
logical_groups[right_group - 1]
|
||||
if right_group <= len(logical_groups)
|
||||
else ()
|
||||
)
|
||||
if not terminal:
|
||||
local.append("shared physical group lacks terminal_merged=yes")
|
||||
if actual_pair != expected_pair:
|
||||
local.append("shared physical group does not match this boundary")
|
||||
classification = "PASS" if not local else "ADVISORY"
|
||||
detailed.append(
|
||||
f"Boundary {left.index}→{right.index}: shared physical group={right_group}; "
|
||||
f"terminal_merged={'yes' if terminal else 'no'}; "
|
||||
"no external decode boundary; "
|
||||
f"{classification}"
|
||||
+ (f" ({'; '.join(dict.fromkeys(local))})" if local else "")
|
||||
+ "."
|
||||
)
|
||||
else:
|
||||
classification = "PASS" if not local else "ADVISORY"
|
||||
visible_left = "n/a" if left.visible_stop is None else str(left.visible_stop)
|
||||
visible_right = "n/a" if right.visible_start is None else str(right.visible_start)
|
||||
gap_text = "n/a" if gap is None else str(gap)
|
||||
context_text = "n/a" if context_frames is None else f"{context_frames}f"
|
||||
video_text = "n/a" if context_video_t is None else f"{context_video_t}T"
|
||||
audio_text = "n/a" if context_audio_t is None else f"{context_audio_t}T"
|
||||
right_text = (
|
||||
"right=unavailable"
|
||||
if right.total_frames is None
|
||||
or right.trim_frames is None
|
||||
or right.net_frames is None
|
||||
else (
|
||||
f"right={right.total_frames}f trim={right.trim_frames} "
|
||||
f"net={right.net_frames}"
|
||||
)
|
||||
)
|
||||
detailed.append(
|
||||
f"Boundary {left.index}→{right.index}: physical; "
|
||||
f"visible={visible_left}→{visible_right} gap={gap_text}; "
|
||||
f"context={context_text} video={video_text} audio={audio_text}; "
|
||||
f"{right_text}; {classification}"
|
||||
+ (f" ({'; '.join(dict.fromkeys(local))})" if local else "")
|
||||
+ "."
|
||||
)
|
||||
|
||||
if local:
|
||||
if gap not in (None, 0):
|
||||
message = (
|
||||
f"boundary {left.index}→{right.index} has a non-contiguous "
|
||||
"visible range"
|
||||
)
|
||||
elif classification == "UNAVAILABLE":
|
||||
message = f"boundary {left.index}→{right.index} is unavailable"
|
||||
else:
|
||||
message = (
|
||||
f"boundary {left.index}→{right.index}: "
|
||||
+ "; ".join(dict.fromkeys(local))
|
||||
)
|
||||
advisory = _chunk_boundary_advisory(message)
|
||||
if advisory not in basic:
|
||||
basic.append(advisory)
|
||||
|
||||
return DiagnosticSection(tuple(basic), tuple(detailed))
|
||||
|
||||
|
||||
def build_v38_diagnostics(
|
||||
*,
|
||||
video_latents: Any,
|
||||
audio_latents: Any,
|
||||
assembly_plan: Any,
|
||||
output_width: int,
|
||||
output_height: int,
|
||||
chunk_seconds: float,
|
||||
reference_images: Sequence[Any] = (),
|
||||
reference_size: str = "Match Output",
|
||||
video_guide: Any = None,
|
||||
video_guide_size: str = REFERENCE_VIDEO_SIZE_EFFICIENT,
|
||||
still_guide_active: bool = False,
|
||||
core_checker: Callable[[], list[str]] | None = None,
|
||||
) -> V38Diagnostics:
|
||||
return _combine_sections(
|
||||
build_frame_alignment_diagnostics(
|
||||
video_latents=video_latents,
|
||||
assembly_plan=assembly_plan,
|
||||
video_guide=video_guide,
|
||||
chunk_seconds=float(chunk_seconds),
|
||||
),
|
||||
validate_audio_latent_lengths(
|
||||
audio_latents=audio_latents,
|
||||
assembly_plan=assembly_plan,
|
||||
),
|
||||
build_chunk_boundary_diagnostics(
|
||||
video_latents=video_latents,
|
||||
audio_latents=audio_latents,
|
||||
assembly_plan=assembly_plan,
|
||||
),
|
||||
collect_core_compatibility_advisory(core_checker),
|
||||
estimate_visual_conditioning_load(
|
||||
output_width=int(output_width),
|
||||
output_height=int(output_height),
|
||||
reference_images=tuple(reference_images),
|
||||
reference_size=str(reference_size),
|
||||
video_guide=video_guide,
|
||||
video_guide_size=str(video_guide_size),
|
||||
chunk_seconds=float(chunk_seconds),
|
||||
still_guide_active=bool(still_guide_active),
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
def format_v38_diagnostics(
|
||||
diagnostics: V38Diagnostics,
|
||||
*,
|
||||
mode: str = DIAGNOSTICS_BASIC,
|
||||
) -> str:
|
||||
normalized = normalize_diagnostics_mode(str(mode))
|
||||
if normalized == DIAGNOSTICS_OFF:
|
||||
return ""
|
||||
lines = diagnostics.detailed if normalized == DIAGNOSTICS_FULL else diagnostics.basic
|
||||
if not lines:
|
||||
return ""
|
||||
return "V3.8 Reliability\n" + "\n".join(lines)
|
||||
|
||||
|
||||
def append_v38_status(
|
||||
status: Any,
|
||||
diagnostics: V38Diagnostics,
|
||||
*,
|
||||
mode: str = DIAGNOSTICS_BASIC,
|
||||
) -> str:
|
||||
suffix = format_v38_diagnostics(diagnostics, mode=mode)
|
||||
original = str(status)
|
||||
return original if not suffix else original.rstrip() + "\n" + suffix
|
||||
@@ -0,0 +1,248 @@
|
||||
"""Shared H3 resolution presets for Easy and V3.8 sampler facades."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
import math
|
||||
from typing import Any
|
||||
|
||||
|
||||
H3_ASPECT_AUTO = "Auto from First Image"
|
||||
H3_ASPECT_LANDSCAPE = "Landscape 16:9"
|
||||
H3_ASPECT_PORTRAIT = "Portrait 9:16"
|
||||
H3_ASPECT_SQUARE = "Square 1:1"
|
||||
H3_ASPECT_OPTIONS = (
|
||||
H3_ASPECT_AUTO,
|
||||
H3_ASPECT_LANDSCAPE,
|
||||
H3_ASPECT_PORTRAIT,
|
||||
H3_ASPECT_SQUARE,
|
||||
)
|
||||
|
||||
H3_SIZE_SOURCE_FIRST_IMAGE = "First Image"
|
||||
H3_SIZE_SOURCE_MANUAL = "Manual"
|
||||
H3_SIZE_SOURCE_LEGACY = "Legacy Aspect"
|
||||
H3_SIZE_SOURCE_OPTIONS = (
|
||||
H3_SIZE_SOURCE_FIRST_IMAGE,
|
||||
H3_SIZE_SOURCE_MANUAL,
|
||||
H3_SIZE_SOURCE_LEGACY,
|
||||
)
|
||||
|
||||
H3_PRESET_DRAFT = "Draft — 0.30 MP"
|
||||
H3_PRESET_BALANCED = "Balanced — 0.60 MP"
|
||||
H3_PRESET_NATIVE = "Native 768"
|
||||
H3_PRESET_CUSTOM = "Custom"
|
||||
H3_PRESET_OPTIONS = (
|
||||
H3_PRESET_DRAFT,
|
||||
H3_PRESET_BALANCED,
|
||||
H3_PRESET_NATIVE,
|
||||
H3_PRESET_CUSTOM,
|
||||
)
|
||||
|
||||
H3_DRAFT_MP = 0.30
|
||||
H3_BALANCED_MP = 0.60
|
||||
H3_CUSTOM_MP_DEFAULT = 0.30
|
||||
H3_CUSTOM_MP_MIN = 0.10
|
||||
H3_CUSTOM_MP_MAX = 16.0
|
||||
H3_CUSTOM_MP_STRONG_WARNING = 2.50
|
||||
H3_MP_PIXELS = 1_000_000.0
|
||||
H3_CANVAS_MULTIPLE = 32
|
||||
H3_NATIVE_SHORT_EDGE = 768
|
||||
H3_NATIVE_LONG_EDGE_CAP = 1344
|
||||
H3_MANUAL_WIDTH_DEFAULT = 736
|
||||
H3_MANUAL_HEIGHT_DEFAULT = 416
|
||||
H3_CANVAS_MIN = 32
|
||||
H3_CANVAS_MAX = 16384
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class H3ResolutionPlan:
|
||||
width: int
|
||||
height: int
|
||||
aspect_ratio: float
|
||||
aspect_source: str
|
||||
preset: str
|
||||
target_mp: float | None
|
||||
warnings: tuple[str, ...]
|
||||
|
||||
@property
|
||||
def actual_mp(self) -> float:
|
||||
return float(self.width * self.height) / H3_MP_PIXELS
|
||||
|
||||
|
||||
def _round_canvas(value: float) -> int:
|
||||
units = math.floor(float(value) / H3_CANVAS_MULTIPLE + 0.5)
|
||||
return max(H3_CANVAS_MULTIPLE, int(units) * H3_CANVAS_MULTIPLE)
|
||||
|
||||
|
||||
def _first_image_aspect(first_frame: Any) -> float | None:
|
||||
shape = getattr(first_frame, "shape", None)
|
||||
if shape is None or len(shape) != 4:
|
||||
return None
|
||||
height = int(shape[1])
|
||||
width = int(shape[2])
|
||||
if width < 1 or height < 1:
|
||||
return None
|
||||
return float(width) / float(height)
|
||||
|
||||
|
||||
def _manual_dimension(value: Any, name: str) -> int:
|
||||
if isinstance(value, bool):
|
||||
raise TypeError(f"Manual {name} must be an integer")
|
||||
resolved = int(value)
|
||||
if float(value) != float(resolved):
|
||||
raise ValueError(f"Manual {name} must be an integer")
|
||||
if not H3_CANVAS_MIN <= resolved <= H3_CANVAS_MAX:
|
||||
raise ValueError(
|
||||
f"Manual {name} must be between {H3_CANVAS_MIN} and {H3_CANVAS_MAX}"
|
||||
)
|
||||
if resolved % H3_CANVAS_MULTIPLE:
|
||||
raise ValueError(
|
||||
f"Manual {name} must be aligned to {H3_CANVAS_MULTIPLE} pixels"
|
||||
)
|
||||
return resolved
|
||||
|
||||
|
||||
def _manual_resolution(width: Any, height: Any, *, warning: str | None = None) -> H3ResolutionPlan:
|
||||
resolved_width = _manual_dimension(width, "Width")
|
||||
resolved_height = _manual_dimension(height, "Height")
|
||||
return H3ResolutionPlan(
|
||||
width=resolved_width,
|
||||
height=resolved_height,
|
||||
aspect_ratio=float(resolved_width) / float(resolved_height),
|
||||
aspect_source="Manual Width / Height",
|
||||
preset="Manual",
|
||||
target_mp=None,
|
||||
warnings=(warning,) if warning else (),
|
||||
)
|
||||
|
||||
|
||||
def resolve_h3_aspect(aspect: str, first_frame: Any = None) -> tuple[float, str]:
|
||||
"""Resolve the existing Easy aspect policy without creating a second fallback."""
|
||||
|
||||
if aspect == H3_ASPECT_AUTO:
|
||||
image_aspect = _first_image_aspect(first_frame)
|
||||
if image_aspect is not None:
|
||||
return image_aspect, "First Image"
|
||||
return 16.0 / 9.0, "Landscape 16:9 fallback"
|
||||
if aspect == H3_ASPECT_LANDSCAPE:
|
||||
return 16.0 / 9.0, H3_ASPECT_LANDSCAPE
|
||||
if aspect == H3_ASPECT_PORTRAIT:
|
||||
return 9.0 / 16.0, H3_ASPECT_PORTRAIT
|
||||
if aspect == H3_ASPECT_SQUARE:
|
||||
return 1.0, H3_ASPECT_SQUARE
|
||||
return 16.0 / 9.0, "Landscape 16:9 fallback"
|
||||
|
||||
|
||||
def _area_resolution(aspect_ratio: float, megapixels: float) -> tuple[int, int]:
|
||||
target_pixels = float(megapixels) * H3_MP_PIXELS
|
||||
raw_width = math.sqrt(target_pixels * float(aspect_ratio))
|
||||
raw_height = math.sqrt(target_pixels / float(aspect_ratio))
|
||||
return _round_canvas(raw_width), _round_canvas(raw_height)
|
||||
|
||||
|
||||
def _native_resolution(aspect_ratio: float) -> tuple[int, int]:
|
||||
landscape = float(aspect_ratio) >= 1.0
|
||||
major_ratio = float(aspect_ratio) if landscape else 1.0 / float(aspect_ratio)
|
||||
short_edge = float(H3_NATIVE_SHORT_EDGE)
|
||||
long_edge = short_edge * major_ratio
|
||||
if long_edge > H3_NATIVE_LONG_EDGE_CAP:
|
||||
long_edge = float(H3_NATIVE_LONG_EDGE_CAP)
|
||||
short_edge = long_edge / major_ratio
|
||||
long_px = min(H3_NATIVE_LONG_EDGE_CAP, _round_canvas(long_edge))
|
||||
short_px = min(H3_NATIVE_SHORT_EDGE, _round_canvas(short_edge))
|
||||
if landscape:
|
||||
return long_px, short_px
|
||||
return short_px, long_px
|
||||
|
||||
|
||||
def resolve_h3_resolution(
|
||||
*,
|
||||
aspect: str,
|
||||
preset: str,
|
||||
custom_mp: float = H3_CUSTOM_MP_DEFAULT,
|
||||
first_frame: Any = None,
|
||||
) -> H3ResolutionPlan:
|
||||
"""Resolve decimal-MP or Native 768 dimensions on the H3 32-pixel grid."""
|
||||
|
||||
aspect_ratio, aspect_source = resolve_h3_aspect(aspect, first_frame)
|
||||
warnings: list[str] = []
|
||||
target_mp: float | None
|
||||
if preset == H3_PRESET_DRAFT:
|
||||
target_mp = H3_DRAFT_MP
|
||||
width, height = _area_resolution(aspect_ratio, target_mp)
|
||||
elif preset == H3_PRESET_BALANCED:
|
||||
target_mp = H3_BALANCED_MP
|
||||
width, height = _area_resolution(aspect_ratio, target_mp)
|
||||
elif preset == H3_PRESET_NATIVE:
|
||||
target_mp = None
|
||||
width, height = _native_resolution(aspect_ratio)
|
||||
else:
|
||||
preset = H3_PRESET_CUSTOM
|
||||
if isinstance(custom_mp, bool):
|
||||
raise TypeError("Custom MP must be numeric")
|
||||
target_mp = float(custom_mp)
|
||||
if not H3_CUSTOM_MP_MIN <= target_mp <= H3_CUSTOM_MP_MAX:
|
||||
raise ValueError(
|
||||
f"Custom MP must be between {H3_CUSTOM_MP_MIN:.2f} and "
|
||||
f"{H3_CUSTOM_MP_MAX:.2f}"
|
||||
)
|
||||
width, height = _area_resolution(aspect_ratio, target_mp)
|
||||
native_width, native_height = _native_resolution(aspect_ratio)
|
||||
native_pixels = native_width * native_height
|
||||
if width * height > native_pixels:
|
||||
warnings.append(
|
||||
"Above Native 768: processing time and memory usage may increase."
|
||||
)
|
||||
if target_mp > H3_CUSTOM_MP_STRONG_WARNING:
|
||||
warnings.append(
|
||||
"High Custom MP: substantial VRAM use and generation time are possible."
|
||||
)
|
||||
return H3ResolutionPlan(
|
||||
width=width,
|
||||
height=height,
|
||||
aspect_ratio=aspect_ratio,
|
||||
aspect_source=aspect_source,
|
||||
preset=preset,
|
||||
target_mp=target_mp,
|
||||
warnings=tuple(warnings),
|
||||
)
|
||||
|
||||
|
||||
def resolve_h3_size_source(
|
||||
*,
|
||||
size_source: str,
|
||||
width: Any = H3_MANUAL_WIDTH_DEFAULT,
|
||||
height: Any = H3_MANUAL_HEIGHT_DEFAULT,
|
||||
aspect: str = H3_ASPECT_AUTO,
|
||||
preset: str = H3_PRESET_DRAFT,
|
||||
custom_mp: float = H3_CUSTOM_MP_DEFAULT,
|
||||
first_frame: Any = None,
|
||||
) -> H3ResolutionPlan:
|
||||
"""Resolve the V3.8 two-choice Size Source while retaining legacy API input."""
|
||||
|
||||
if size_source == H3_SIZE_SOURCE_MANUAL:
|
||||
return _manual_resolution(width, height)
|
||||
if size_source == H3_SIZE_SOURCE_FIRST_IMAGE:
|
||||
if _first_image_aspect(first_frame) is None:
|
||||
return _manual_resolution(
|
||||
width,
|
||||
height,
|
||||
warning=(
|
||||
"First Image is unavailable for Size Source = First Image; "
|
||||
"the displayed Manual Width / Height were used."
|
||||
),
|
||||
)
|
||||
return resolve_h3_resolution(
|
||||
aspect=H3_ASPECT_AUTO,
|
||||
preset=preset,
|
||||
custom_mp=custom_mp,
|
||||
first_frame=first_frame,
|
||||
)
|
||||
# Existing API prompts and saved workflows omit size_source. Preserve their
|
||||
# exact V3.8 aspect resolver until the frontend migrates the visible widgets.
|
||||
return resolve_h3_resolution(
|
||||
aspect=aspect,
|
||||
preset=preset,
|
||||
custom_mp=custom_mp,
|
||||
first_frame=first_frame,
|
||||
)
|
||||
@@ -0,0 +1,767 @@
|
||||
"""Pure execution-policy resolvers for V3.8 chunk review.
|
||||
|
||||
This module deliberately owns no ComfyUI, torch, filesystem, Run Storage, or
|
||||
sampling behavior. It turns already-validated storage facts into an execution
|
||||
decision that later phases can apply to the existing Production engine.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
|
||||
from ..branch_provenance import TAKE_ACTION_CONTINUE, TAKE_ACTION_USE
|
||||
|
||||
|
||||
GENERATION_MODE_FULL_RUN = "Full Run"
|
||||
GENERATION_MODE_REVIEW = "Review Each Chunk"
|
||||
GENERATION_MODE_OPTIONS = (
|
||||
GENERATION_MODE_FULL_RUN,
|
||||
GENERATION_MODE_REVIEW,
|
||||
)
|
||||
|
||||
REVIEW_ACTION_CONTINUE = "Continue / Next"
|
||||
REVIEW_ACTION_REGENERATE_CURRENT = "Regenerate Current"
|
||||
REVIEW_ACTION_FINISH_REMAINING = "Finish Remaining"
|
||||
REVIEW_ACTION_OPTIONS = (
|
||||
REVIEW_ACTION_CONTINUE,
|
||||
REVIEW_ACTION_REGENERATE_CURRENT,
|
||||
REVIEW_ACTION_FINISH_REMAINING,
|
||||
)
|
||||
|
||||
RUN_STORAGE_OFF = "Off"
|
||||
RUN_STORAGE_SAVE_AUTO_RESUME = "Save + Auto Resume"
|
||||
|
||||
REVISION_STATUS_IN_PROGRESS = "in_progress"
|
||||
REVISION_STATUS_INTERRUPTED = "interrupted"
|
||||
REVISION_STATUS_REVIEW_READY = "review_ready"
|
||||
REVISION_STATUS_COMPLETE = "complete"
|
||||
REVISION_STATUSES = (
|
||||
REVISION_STATUS_IN_PROGRESS,
|
||||
REVISION_STATUS_INTERRUPTED,
|
||||
REVISION_STATUS_REVIEW_READY,
|
||||
REVISION_STATUS_COMPLETE,
|
||||
)
|
||||
|
||||
EXECUTION_MODE_FULL_RUN = "full_run"
|
||||
EXECUTION_MODE_REVIEW_CONTINUE = "review_continue"
|
||||
EXECUTION_MODE_REVIEW_REGENERATE = "review_regenerate_current"
|
||||
EXECUTION_MODE_REVIEW_FINISH = "review_finish_remaining"
|
||||
EXECUTION_MODE_REVIEW_USE_TAKE = "review_use_take"
|
||||
EXECUTION_MODE_REVIEW_CONTINUE_FROM_TAKE = "review_continue_from_take"
|
||||
|
||||
NONCE_POLICY_INACTIVE = "inactive"
|
||||
NONCE_POLICY_INHERIT = "inherit_branch"
|
||||
NONCE_POLICY_ADVANCE = "advance_variation"
|
||||
NONCE_POLICY_MANUAL = "manual"
|
||||
|
||||
REVIEW_PAUSE_REASON = "review_each_chunk"
|
||||
|
||||
|
||||
class ReviewControlError(ValueError):
|
||||
"""Raised when a requested review policy is structurally ambiguous."""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ReviewUnit:
|
||||
"""One atomic physical sampling group expressed in logical chunk numbers."""
|
||||
|
||||
start: int
|
||||
end: int
|
||||
physical_group: int
|
||||
|
||||
def as_metadata(self) -> dict[str, int]:
|
||||
return {
|
||||
"start": self.start,
|
||||
"end": self.end,
|
||||
"physical_group": self.physical_group,
|
||||
}
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ReviewExecution:
|
||||
"""Side-effect-free decision consumed by later execution phases."""
|
||||
|
||||
execution_mode: str
|
||||
requires_run_storage: bool
|
||||
effective_regenerate_from: int
|
||||
max_new_physical_groups: int | None
|
||||
next_review_unit_start: int | None
|
||||
next_review_unit_end: int | None
|
||||
next_review_physical_group: int | None
|
||||
finish_remaining: bool
|
||||
smart_regenerate: bool
|
||||
one_shot_reset_required: bool
|
||||
partial_review: bool
|
||||
projected_prefix_count: int
|
||||
nonce_policy: str
|
||||
branch_regenerate_from: int
|
||||
base_effective_nonce: int
|
||||
requested_effective_nonce: int | None
|
||||
status_hint: str
|
||||
|
||||
|
||||
def _integer(value: Any, *, name: str, minimum: int, maximum: int) -> int:
|
||||
if isinstance(value, bool) or not isinstance(value, int):
|
||||
raise ReviewControlError(f"{name} must be an integer")
|
||||
if not minimum <= value <= maximum:
|
||||
raise ReviewControlError(
|
||||
f"{name} must be between {minimum} and {maximum}"
|
||||
)
|
||||
return value
|
||||
|
||||
|
||||
def _manual_regenerate_from(value: Any, *, configured_chunks: int) -> int:
|
||||
if value is None or value == "Auto" or value == 0:
|
||||
return 0
|
||||
if isinstance(value, str) and value.startswith("Chunk "):
|
||||
try:
|
||||
value = int(value[6:])
|
||||
except ValueError as exc:
|
||||
raise ReviewControlError(
|
||||
"manual_regenerate_from must be Auto or a valid chunk"
|
||||
) from exc
|
||||
return _integer(
|
||||
value,
|
||||
name="manual_regenerate_from",
|
||||
minimum=1,
|
||||
maximum=configured_chunks,
|
||||
)
|
||||
|
||||
|
||||
def _terminal_pair_start(
|
||||
*,
|
||||
configured_chunks: int,
|
||||
terminal_merge_enabled: bool,
|
||||
terminal_pair_start: Any,
|
||||
) -> int | None:
|
||||
if type(terminal_merge_enabled) is not bool:
|
||||
raise ReviewControlError("terminal_merge_enabled must be a boolean")
|
||||
if not terminal_merge_enabled:
|
||||
return None
|
||||
if configured_chunks < 2:
|
||||
raise ReviewControlError(
|
||||
"Terminal Merge requires at least two configured chunks"
|
||||
)
|
||||
start = _integer(
|
||||
terminal_pair_start,
|
||||
name="terminal_pair_start",
|
||||
minimum=1,
|
||||
maximum=configured_chunks - 1,
|
||||
)
|
||||
if start != configured_chunks - 1:
|
||||
raise ReviewControlError(
|
||||
"Terminal Merge must cover the final two configured chunks"
|
||||
)
|
||||
return start
|
||||
|
||||
|
||||
def _review_geometry(
|
||||
*,
|
||||
configured_chunks: Any,
|
||||
validated_prefix_count: Any,
|
||||
terminal_merge_enabled: bool,
|
||||
terminal_pair_start: Any,
|
||||
) -> tuple[int, int, int | None]:
|
||||
chunks = _integer(
|
||||
configured_chunks,
|
||||
name="configured_chunks",
|
||||
minimum=1,
|
||||
maximum=0x7FFFFFFF,
|
||||
)
|
||||
prefix = _integer(
|
||||
validated_prefix_count,
|
||||
name="validated_prefix_count",
|
||||
minimum=0,
|
||||
maximum=chunks,
|
||||
)
|
||||
pair_start = _terminal_pair_start(
|
||||
configured_chunks=chunks,
|
||||
terminal_merge_enabled=terminal_merge_enabled,
|
||||
terminal_pair_start=terminal_pair_start,
|
||||
)
|
||||
if pair_start is not None and pair_start <= prefix < chunks:
|
||||
raise ReviewControlError(
|
||||
"validated prefix ends inside the atomic Terminal Merge pair"
|
||||
)
|
||||
return chunks, prefix, pair_start
|
||||
|
||||
|
||||
def resolve_next_review_unit(
|
||||
*,
|
||||
configured_chunks: int,
|
||||
validated_prefix_count: int,
|
||||
terminal_merge_enabled: bool,
|
||||
terminal_pair_start: int | None,
|
||||
) -> ReviewUnit | None:
|
||||
"""Return the next atomic physical group after a validated logical prefix."""
|
||||
|
||||
chunks, prefix, pair_start = _review_geometry(
|
||||
configured_chunks=configured_chunks,
|
||||
validated_prefix_count=validated_prefix_count,
|
||||
terminal_merge_enabled=terminal_merge_enabled,
|
||||
terminal_pair_start=terminal_pair_start,
|
||||
)
|
||||
if prefix == chunks:
|
||||
return None
|
||||
start = prefix + 1
|
||||
if pair_start is not None and start == pair_start:
|
||||
return ReviewUnit(
|
||||
start=pair_start,
|
||||
end=chunks,
|
||||
physical_group=pair_start,
|
||||
)
|
||||
return ReviewUnit(start=start, end=start, physical_group=start)
|
||||
|
||||
|
||||
def _review_unit_for_chunk(
|
||||
chunk: int,
|
||||
*,
|
||||
configured_chunks: int,
|
||||
terminal_pair_start: int | None,
|
||||
) -> ReviewUnit:
|
||||
if terminal_pair_start is not None and chunk >= terminal_pair_start:
|
||||
return ReviewUnit(
|
||||
start=terminal_pair_start,
|
||||
end=configured_chunks,
|
||||
physical_group=terminal_pair_start,
|
||||
)
|
||||
return ReviewUnit(start=chunk, end=chunk, physical_group=chunk)
|
||||
|
||||
|
||||
def _validated_review_unit(
|
||||
value: Any,
|
||||
*,
|
||||
configured_chunks: int,
|
||||
validated_prefix_count: int,
|
||||
terminal_pair_start: int | None,
|
||||
) -> ReviewUnit | None:
|
||||
if value is None:
|
||||
return None
|
||||
if isinstance(value, ReviewUnit):
|
||||
unit = value
|
||||
elif isinstance(value, Mapping):
|
||||
try:
|
||||
unit = ReviewUnit(
|
||||
start=value["start"],
|
||||
end=value["end"],
|
||||
physical_group=value["physical_group"],
|
||||
)
|
||||
except KeyError as exc:
|
||||
raise ReviewControlError(
|
||||
"latest_review_unit is missing required metadata"
|
||||
) from exc
|
||||
else:
|
||||
raise ReviewControlError(
|
||||
"latest_review_unit must be review metadata or None"
|
||||
)
|
||||
start = _integer(
|
||||
unit.start,
|
||||
name="latest_review_unit.start",
|
||||
minimum=1,
|
||||
maximum=configured_chunks,
|
||||
)
|
||||
end = _integer(
|
||||
unit.end,
|
||||
name="latest_review_unit.end",
|
||||
minimum=start,
|
||||
maximum=configured_chunks,
|
||||
)
|
||||
physical_group = _integer(
|
||||
unit.physical_group,
|
||||
name="latest_review_unit.physical_group",
|
||||
minimum=1,
|
||||
maximum=configured_chunks,
|
||||
)
|
||||
if physical_group != start:
|
||||
raise ReviewControlError(
|
||||
"latest_review_unit physical group must equal its first logical chunk"
|
||||
)
|
||||
if terminal_pair_start is not None and start == terminal_pair_start:
|
||||
if end != configured_chunks:
|
||||
raise ReviewControlError(
|
||||
"latest_review_unit splits the atomic Terminal Merge pair"
|
||||
)
|
||||
elif end != start:
|
||||
raise ReviewControlError(
|
||||
"a non-terminal review unit must contain exactly one logical chunk"
|
||||
)
|
||||
if terminal_pair_start is not None and start > terminal_pair_start:
|
||||
raise ReviewControlError(
|
||||
"latest_review_unit starts inside the atomic Terminal Merge pair"
|
||||
)
|
||||
if end != validated_prefix_count:
|
||||
raise ReviewControlError(
|
||||
"latest_review_unit is not the head of the validated prefix"
|
||||
)
|
||||
return ReviewUnit(start=start, end=end, physical_group=physical_group)
|
||||
|
||||
|
||||
def make_review_pause_metadata(review_unit: ReviewUnit) -> dict[str, Any]:
|
||||
"""Build non-identity manifest metadata for a successful review pause."""
|
||||
|
||||
if not isinstance(review_unit, ReviewUnit):
|
||||
raise ReviewControlError("review_unit must be a ReviewUnit")
|
||||
start = _integer(
|
||||
review_unit.start,
|
||||
name="review_unit.start",
|
||||
minimum=1,
|
||||
maximum=0x7FFFFFFF,
|
||||
)
|
||||
end = _integer(
|
||||
review_unit.end,
|
||||
name="review_unit.end",
|
||||
minimum=start,
|
||||
maximum=0x7FFFFFFF,
|
||||
)
|
||||
physical_group = _integer(
|
||||
review_unit.physical_group,
|
||||
name="review_unit.physical_group",
|
||||
minimum=1,
|
||||
maximum=0x7FFFFFFF,
|
||||
)
|
||||
if physical_group != start:
|
||||
raise ReviewControlError(
|
||||
"review_unit physical group must equal its first logical chunk"
|
||||
)
|
||||
return {
|
||||
"review_unit": {
|
||||
"start": start,
|
||||
"end": end,
|
||||
"physical_group": physical_group,
|
||||
},
|
||||
"review_pause_reason": REVIEW_PAUSE_REASON,
|
||||
}
|
||||
|
||||
|
||||
def _revision_status(value: Any, *, prefix: int, chunks: int) -> str | None:
|
||||
if value is None or value == "":
|
||||
if prefix:
|
||||
raise ReviewControlError(
|
||||
"a non-empty validated prefix requires a revision status"
|
||||
)
|
||||
return None
|
||||
status = str(value)
|
||||
if status not in REVISION_STATUSES:
|
||||
raise ReviewControlError(f"unknown latest revision status: {status!r}")
|
||||
if status == REVISION_STATUS_COMPLETE and prefix != chunks:
|
||||
raise ReviewControlError(
|
||||
"a complete revision must contain every configured chunk"
|
||||
)
|
||||
if status == REVISION_STATUS_REVIEW_READY and not 0 < prefix < chunks:
|
||||
raise ReviewControlError(
|
||||
"review_ready requires a non-empty incomplete prefix"
|
||||
)
|
||||
return status
|
||||
|
||||
|
||||
def _branch_contract(
|
||||
*,
|
||||
latest_effective_nonce: Any,
|
||||
latest_branch_regenerate_from: Any,
|
||||
validated_prefix_count: int,
|
||||
configured_chunks: int,
|
||||
latest_revision_status: str | None,
|
||||
) -> tuple[int, int]:
|
||||
nonce = _integer(
|
||||
latest_effective_nonce,
|
||||
name="latest_effective_nonce",
|
||||
minimum=0,
|
||||
maximum=0xFFFFFFFF,
|
||||
)
|
||||
branch_start = _manual_regenerate_from(
|
||||
latest_branch_regenerate_from,
|
||||
configured_chunks=configured_chunks,
|
||||
)
|
||||
if nonce == 0 and branch_start != 0:
|
||||
raise ReviewControlError(
|
||||
"a regenerate branch requires a positive effective nonce"
|
||||
)
|
||||
if nonce > 0 and branch_start == 0:
|
||||
raise ReviewControlError(
|
||||
"a positive effective nonce requires its regenerate branch boundary"
|
||||
)
|
||||
if branch_start > validated_prefix_count + 1:
|
||||
raise ReviewControlError(
|
||||
"regenerate branch boundary skips the validated prefix head"
|
||||
)
|
||||
if (
|
||||
latest_revision_status
|
||||
in (REVISION_STATUS_REVIEW_READY, REVISION_STATUS_COMPLETE)
|
||||
and branch_start > validated_prefix_count
|
||||
):
|
||||
raise ReviewControlError(
|
||||
"a ready regenerate branch has not committed its boundary chunk"
|
||||
)
|
||||
return nonce, branch_start
|
||||
|
||||
|
||||
def _nonce_decision(
|
||||
*,
|
||||
manual_regenerate_from: int,
|
||||
smart_regenerate: bool,
|
||||
latest_effective_nonce: int,
|
||||
latest_branch_regenerate_from: int,
|
||||
smart_target: int = 0,
|
||||
) -> tuple[str, int, int | None]:
|
||||
if smart_regenerate:
|
||||
if latest_effective_nonce >= 0xFFFFFFFF:
|
||||
raise ReviewControlError(
|
||||
"effective reroll nonce variation space is exhausted"
|
||||
)
|
||||
return (
|
||||
NONCE_POLICY_ADVANCE,
|
||||
smart_target,
|
||||
latest_effective_nonce + 1,
|
||||
)
|
||||
if manual_regenerate_from:
|
||||
return NONCE_POLICY_MANUAL, manual_regenerate_from, None
|
||||
if latest_effective_nonce:
|
||||
return (
|
||||
NONCE_POLICY_INHERIT,
|
||||
latest_branch_regenerate_from,
|
||||
latest_effective_nonce,
|
||||
)
|
||||
return NONCE_POLICY_INACTIVE, 0, 0
|
||||
|
||||
|
||||
def _unit_status(unit: ReviewUnit, *, chunks: int, verb: str) -> str:
|
||||
if unit.start == unit.end:
|
||||
return f"{verb}: Chunk {unit.start} / {chunks}."
|
||||
return (
|
||||
f"{verb}: Chunks {unit.start}-{unit.end} / {chunks}; "
|
||||
"Terminal Merge atomic group."
|
||||
)
|
||||
|
||||
|
||||
def resolve_review_execution(
|
||||
*,
|
||||
generation_mode: str,
|
||||
review_action: str,
|
||||
configured_chunks: int,
|
||||
validated_prefix_count: int,
|
||||
terminal_merge_enabled: bool,
|
||||
terminal_pair_start: int | None,
|
||||
manual_regenerate_from: Any,
|
||||
run_storage_mode: str,
|
||||
latest_review_unit: ReviewUnit | Mapping[str, Any] | None,
|
||||
latest_revision_status: str | None,
|
||||
latest_effective_nonce: int,
|
||||
latest_branch_regenerate_from: Any = 0,
|
||||
) -> ReviewExecution:
|
||||
"""Resolve V3.8 review intent without touching Production or storage state."""
|
||||
|
||||
if generation_mode not in GENERATION_MODE_OPTIONS:
|
||||
raise ReviewControlError(f"unknown Generation Mode: {generation_mode!r}")
|
||||
if review_action not in REVIEW_ACTION_OPTIONS:
|
||||
raise ReviewControlError(f"unknown Review Action: {review_action!r}")
|
||||
chunks, prefix, pair_start = _review_geometry(
|
||||
configured_chunks=configured_chunks,
|
||||
validated_prefix_count=validated_prefix_count,
|
||||
terminal_merge_enabled=terminal_merge_enabled,
|
||||
terminal_pair_start=terminal_pair_start,
|
||||
)
|
||||
status = _revision_status(
|
||||
latest_revision_status,
|
||||
prefix=prefix,
|
||||
chunks=chunks,
|
||||
)
|
||||
manual_from = _manual_regenerate_from(
|
||||
manual_regenerate_from,
|
||||
configured_chunks=chunks,
|
||||
)
|
||||
nonce, existing_branch_start = _branch_contract(
|
||||
latest_effective_nonce=latest_effective_nonce,
|
||||
latest_branch_regenerate_from=latest_branch_regenerate_from,
|
||||
validated_prefix_count=prefix,
|
||||
configured_chunks=chunks,
|
||||
latest_revision_status=status,
|
||||
)
|
||||
|
||||
if generation_mode == GENERATION_MODE_FULL_RUN:
|
||||
nonce_policy, branch_start, requested_nonce = _nonce_decision(
|
||||
manual_regenerate_from=manual_from,
|
||||
smart_regenerate=False,
|
||||
latest_effective_nonce=nonce,
|
||||
latest_branch_regenerate_from=existing_branch_start,
|
||||
)
|
||||
return ReviewExecution(
|
||||
execution_mode=EXECUTION_MODE_FULL_RUN,
|
||||
requires_run_storage=False,
|
||||
effective_regenerate_from=(manual_from or branch_start),
|
||||
max_new_physical_groups=None,
|
||||
next_review_unit_start=None,
|
||||
next_review_unit_end=None,
|
||||
next_review_physical_group=None,
|
||||
finish_remaining=False,
|
||||
smart_regenerate=False,
|
||||
one_shot_reset_required=False,
|
||||
partial_review=False,
|
||||
projected_prefix_count=chunks,
|
||||
nonce_policy=nonce_policy,
|
||||
branch_regenerate_from=branch_start,
|
||||
base_effective_nonce=nonce,
|
||||
requested_effective_nonce=requested_nonce,
|
||||
status_hint="Full Run: Review execution limit disabled.",
|
||||
)
|
||||
|
||||
if run_storage_mode != RUN_STORAGE_SAVE_AUTO_RESUME:
|
||||
raise ReviewControlError(
|
||||
"Review Each Chunk requires Run Storage = Save + Auto Resume."
|
||||
)
|
||||
|
||||
latest_unit = _validated_review_unit(
|
||||
latest_review_unit,
|
||||
configured_chunks=chunks,
|
||||
validated_prefix_count=prefix,
|
||||
terminal_pair_start=pair_start,
|
||||
)
|
||||
|
||||
if review_action == REVIEW_ACTION_REGENERATE_CURRENT:
|
||||
if manual_from:
|
||||
raise ReviewControlError(
|
||||
"Regenerate Current cannot be combined with manual Regenerate From. "
|
||||
"Set Regenerate From to Auto."
|
||||
)
|
||||
if prefix == 0:
|
||||
raise ReviewControlError(
|
||||
"Regenerate Current requires an existing reviewed unit"
|
||||
)
|
||||
if latest_unit is None:
|
||||
raise ReviewControlError(
|
||||
"Regenerate Current requires latest review_unit metadata"
|
||||
)
|
||||
if status not in (
|
||||
REVISION_STATUS_REVIEW_READY,
|
||||
REVISION_STATUS_COMPLETE,
|
||||
):
|
||||
raise ReviewControlError(
|
||||
"Regenerate Current requires a review_ready revision or a complete "
|
||||
"revision with review_unit metadata"
|
||||
)
|
||||
nonce_policy, branch_start, requested_nonce = _nonce_decision(
|
||||
manual_regenerate_from=0,
|
||||
smart_regenerate=True,
|
||||
latest_effective_nonce=nonce,
|
||||
latest_branch_regenerate_from=existing_branch_start,
|
||||
smart_target=latest_unit.start,
|
||||
)
|
||||
projected = latest_unit.end
|
||||
return ReviewExecution(
|
||||
execution_mode=EXECUTION_MODE_REVIEW_REGENERATE,
|
||||
requires_run_storage=True,
|
||||
effective_regenerate_from=latest_unit.start,
|
||||
max_new_physical_groups=1,
|
||||
next_review_unit_start=latest_unit.start,
|
||||
next_review_unit_end=latest_unit.end,
|
||||
next_review_physical_group=latest_unit.physical_group,
|
||||
finish_remaining=False,
|
||||
smart_regenerate=True,
|
||||
one_shot_reset_required=True,
|
||||
partial_review=projected < chunks,
|
||||
projected_prefix_count=projected,
|
||||
nonce_policy=nonce_policy,
|
||||
branch_regenerate_from=branch_start,
|
||||
base_effective_nonce=nonce,
|
||||
requested_effective_nonce=requested_nonce,
|
||||
status_hint=_unit_status(
|
||||
latest_unit,
|
||||
chunks=chunks,
|
||||
verb="Smart Regenerate",
|
||||
),
|
||||
)
|
||||
|
||||
nonce_policy, branch_start, requested_nonce = _nonce_decision(
|
||||
manual_regenerate_from=manual_from,
|
||||
smart_regenerate=False,
|
||||
latest_effective_nonce=nonce,
|
||||
latest_branch_regenerate_from=existing_branch_start,
|
||||
)
|
||||
if review_action == REVIEW_ACTION_FINISH_REMAINING:
|
||||
return ReviewExecution(
|
||||
execution_mode=EXECUTION_MODE_REVIEW_FINISH,
|
||||
requires_run_storage=True,
|
||||
effective_regenerate_from=(manual_from or branch_start),
|
||||
max_new_physical_groups=None,
|
||||
next_review_unit_start=None,
|
||||
next_review_unit_end=None,
|
||||
next_review_physical_group=None,
|
||||
finish_remaining=True,
|
||||
smart_regenerate=False,
|
||||
one_shot_reset_required=True,
|
||||
partial_review=False,
|
||||
projected_prefix_count=chunks,
|
||||
nonce_policy=nonce_policy,
|
||||
branch_regenerate_from=branch_start,
|
||||
base_effective_nonce=nonce,
|
||||
requested_effective_nonce=requested_nonce,
|
||||
status_hint=(
|
||||
f"Review Mode: finish remaining after accepted prefix "
|
||||
f"{prefix} / {chunks}."
|
||||
),
|
||||
)
|
||||
|
||||
if manual_from:
|
||||
next_unit = _review_unit_for_chunk(
|
||||
manual_from,
|
||||
configured_chunks=chunks,
|
||||
terminal_pair_start=pair_start,
|
||||
)
|
||||
else:
|
||||
next_unit = resolve_next_review_unit(
|
||||
configured_chunks=chunks,
|
||||
validated_prefix_count=prefix,
|
||||
terminal_merge_enabled=terminal_merge_enabled,
|
||||
terminal_pair_start=pair_start,
|
||||
)
|
||||
if next_unit is None:
|
||||
projected = chunks
|
||||
status_hint = "Review Mode: Sequence complete."
|
||||
unit_start = unit_end = physical_group = None
|
||||
else:
|
||||
projected = next_unit.end
|
||||
status_hint = _unit_status(
|
||||
next_unit,
|
||||
chunks=chunks,
|
||||
verb="Review next unit",
|
||||
)
|
||||
unit_start = next_unit.start
|
||||
unit_end = next_unit.end
|
||||
physical_group = next_unit.physical_group
|
||||
return ReviewExecution(
|
||||
execution_mode=EXECUTION_MODE_REVIEW_CONTINUE,
|
||||
requires_run_storage=True,
|
||||
effective_regenerate_from=(manual_from or branch_start),
|
||||
max_new_physical_groups=1,
|
||||
next_review_unit_start=unit_start,
|
||||
next_review_unit_end=unit_end,
|
||||
next_review_physical_group=physical_group,
|
||||
finish_remaining=False,
|
||||
smart_regenerate=False,
|
||||
one_shot_reset_required=False,
|
||||
partial_review=projected < chunks,
|
||||
projected_prefix_count=projected,
|
||||
nonce_policy=nonce_policy,
|
||||
branch_regenerate_from=branch_start,
|
||||
base_effective_nonce=nonce,
|
||||
requested_effective_nonce=requested_nonce,
|
||||
status_hint=status_hint,
|
||||
)
|
||||
|
||||
|
||||
def resolve_take_execution(
|
||||
*,
|
||||
take_action: str,
|
||||
configured_chunks: int,
|
||||
selected_prefix_count: int,
|
||||
terminal_merge_enabled: bool,
|
||||
terminal_pair_start: int | None,
|
||||
selected_review_unit: ReviewUnit | Mapping[str, Any],
|
||||
selected_effective_nonce: int,
|
||||
selected_branch_regenerate_from: int,
|
||||
next_effective_nonce: int,
|
||||
) -> ReviewExecution:
|
||||
"""Resolve an already-validated immutable Take selection.
|
||||
|
||||
The selected prefix is a Run Storage fact. Continuing from it starts a
|
||||
fresh downstream nonce boundary without changing the Sampling Contract.
|
||||
"""
|
||||
|
||||
if take_action not in (TAKE_ACTION_USE, TAKE_ACTION_CONTINUE):
|
||||
raise ReviewControlError(f"unknown Take action: {take_action!r}")
|
||||
chunks, prefix, pair_start = _review_geometry(
|
||||
configured_chunks=configured_chunks,
|
||||
validated_prefix_count=selected_prefix_count,
|
||||
terminal_merge_enabled=terminal_merge_enabled,
|
||||
terminal_pair_start=terminal_pair_start,
|
||||
)
|
||||
unit = _validated_review_unit(
|
||||
selected_review_unit,
|
||||
configured_chunks=chunks,
|
||||
validated_prefix_count=prefix,
|
||||
terminal_pair_start=pair_start,
|
||||
)
|
||||
if unit is None:
|
||||
raise ReviewControlError("selected Take is missing its physical review unit")
|
||||
selected_nonce, selected_branch = _branch_contract(
|
||||
latest_effective_nonce=selected_effective_nonce,
|
||||
latest_branch_regenerate_from=selected_branch_regenerate_from,
|
||||
validated_prefix_count=prefix,
|
||||
configured_chunks=chunks,
|
||||
latest_revision_status=(
|
||||
REVISION_STATUS_COMPLETE if prefix == chunks else REVISION_STATUS_REVIEW_READY
|
||||
),
|
||||
)
|
||||
if take_action == TAKE_ACTION_USE:
|
||||
return ReviewExecution(
|
||||
execution_mode=EXECUTION_MODE_REVIEW_USE_TAKE,
|
||||
requires_run_storage=True,
|
||||
effective_regenerate_from=selected_branch,
|
||||
max_new_physical_groups=0,
|
||||
next_review_unit_start=None,
|
||||
next_review_unit_end=None,
|
||||
next_review_physical_group=None,
|
||||
finish_remaining=False,
|
||||
smart_regenerate=False,
|
||||
one_shot_reset_required=True,
|
||||
partial_review=prefix < chunks,
|
||||
projected_prefix_count=prefix,
|
||||
nonce_policy=NONCE_POLICY_INHERIT if selected_nonce else NONCE_POLICY_INACTIVE,
|
||||
branch_regenerate_from=selected_branch,
|
||||
base_effective_nonce=selected_nonce,
|
||||
requested_effective_nonce=selected_nonce,
|
||||
status_hint=_unit_status(unit, chunks=chunks, verb="Use This Take"),
|
||||
)
|
||||
|
||||
next_unit = resolve_next_review_unit(
|
||||
configured_chunks=chunks,
|
||||
validated_prefix_count=prefix,
|
||||
terminal_merge_enabled=terminal_merge_enabled,
|
||||
terminal_pair_start=pair_start,
|
||||
)
|
||||
if next_unit is None:
|
||||
return ReviewExecution(
|
||||
execution_mode=EXECUTION_MODE_REVIEW_USE_TAKE,
|
||||
requires_run_storage=True,
|
||||
effective_regenerate_from=selected_branch,
|
||||
max_new_physical_groups=0,
|
||||
next_review_unit_start=None,
|
||||
next_review_unit_end=None,
|
||||
next_review_physical_group=None,
|
||||
finish_remaining=False,
|
||||
smart_regenerate=False,
|
||||
one_shot_reset_required=True,
|
||||
partial_review=False,
|
||||
projected_prefix_count=chunks,
|
||||
nonce_policy=NONCE_POLICY_INHERIT if selected_nonce else NONCE_POLICY_INACTIVE,
|
||||
branch_regenerate_from=selected_branch,
|
||||
base_effective_nonce=selected_nonce,
|
||||
requested_effective_nonce=selected_nonce,
|
||||
status_hint="Continue From Here: selected Take is already complete.",
|
||||
)
|
||||
nonce = _integer(
|
||||
next_effective_nonce,
|
||||
name="next_effective_nonce",
|
||||
minimum=1,
|
||||
maximum=0xFFFFFFFF,
|
||||
)
|
||||
return ReviewExecution(
|
||||
execution_mode=EXECUTION_MODE_REVIEW_CONTINUE_FROM_TAKE,
|
||||
requires_run_storage=True,
|
||||
effective_regenerate_from=next_unit.start,
|
||||
max_new_physical_groups=1,
|
||||
next_review_unit_start=next_unit.start,
|
||||
next_review_unit_end=next_unit.end,
|
||||
next_review_physical_group=next_unit.physical_group,
|
||||
finish_remaining=False,
|
||||
smart_regenerate=False,
|
||||
one_shot_reset_required=True,
|
||||
partial_review=next_unit.end < chunks,
|
||||
projected_prefix_count=next_unit.end,
|
||||
nonce_policy=NONCE_POLICY_ADVANCE,
|
||||
branch_regenerate_from=next_unit.start,
|
||||
base_effective_nonce=selected_nonce,
|
||||
requested_effective_nonce=nonce,
|
||||
status_hint=_unit_status(next_unit, chunks=chunks, verb="Continue From Here"),
|
||||
)
|
||||
+89
-4
@@ -53,6 +53,13 @@ def _latent_samples(value: Any, *, name: str) -> torch.Tensor:
|
||||
return samples
|
||||
|
||||
|
||||
def _require_finite_samples(samples: torch.Tensor, *, name: str) -> None:
|
||||
"""Reject unusable processor output before it reaches Second Pass Sampling."""
|
||||
|
||||
if not bool(torch.isfinite(samples).all().item()):
|
||||
raise SecondPassContractError(f"{name}.samples contains NaN or Inf")
|
||||
|
||||
|
||||
def _contract_groups(assembly_plan: Mapping[str, Any]) -> list[Mapping[str, Any]]:
|
||||
if not isinstance(assembly_plan, Mapping):
|
||||
raise SecondPassContractError("assembly_plan must be a mapping")
|
||||
@@ -95,6 +102,7 @@ def _validate_video_groups(
|
||||
source_w = int(group.get("source_latent_w", -1))
|
||||
if source_h < 1 or source_w < 1 or height < source_h or width < source_w:
|
||||
raise SecondPassContractError("video latent spatial size must be preserved or enlarged")
|
||||
_require_finite_samples(samples, name=f"video_latents[{position}]")
|
||||
if target_geometry is None:
|
||||
target_geometry = (height, width)
|
||||
elif target_geometry != (height, width):
|
||||
@@ -121,6 +129,7 @@ def validate_second_pass_inputs(
|
||||
expected_shape = group.get("source_audio_shape")
|
||||
if not isinstance(expected_shape, list) or tuple(expected_shape) != tuple(samples.shape):
|
||||
raise SecondPassContractError("audio latent shape or physical group order changed")
|
||||
_require_finite_samples(samples, name=f"audio_latents[{position}]")
|
||||
|
||||
return {
|
||||
"physical_group_count": len(groups),
|
||||
@@ -135,6 +144,38 @@ def passthrough_audio_latents(audio_latents: Sequence[Any]) -> list[Any]:
|
||||
return list(audio_latents)
|
||||
|
||||
|
||||
def _normalize_selected_group_indices(
|
||||
selected_group_indices: Sequence[int] | None,
|
||||
physical_group_count: int,
|
||||
) -> tuple[tuple[int, ...], bool]:
|
||||
"""Validate an optional internal physical-group selection."""
|
||||
|
||||
if selected_group_indices is None:
|
||||
return tuple(range(physical_group_count)), False
|
||||
if (
|
||||
not isinstance(selected_group_indices, Sequence)
|
||||
or isinstance(selected_group_indices, (str, bytes))
|
||||
or not selected_group_indices
|
||||
):
|
||||
raise SecondPassContractError(
|
||||
"selected physical groups must be a non-empty integer sequence"
|
||||
)
|
||||
selected = tuple(selected_group_indices)
|
||||
if any(type(index) is not int for index in selected):
|
||||
raise SecondPassContractError(
|
||||
"selected physical group indices must be integers"
|
||||
)
|
||||
if len(set(selected)) != len(selected):
|
||||
raise SecondPassContractError("selected physical groups contain duplicates")
|
||||
if tuple(sorted(selected)) != selected:
|
||||
raise SecondPassContractError(
|
||||
"selected physical groups must follow physical execution order"
|
||||
)
|
||||
if selected[0] < 0 or selected[-1] >= physical_group_count:
|
||||
raise SecondPassContractError("selected physical group index is out of range")
|
||||
return selected, True
|
||||
|
||||
|
||||
def update_second_pass_geometry(
|
||||
assembly_plan: Mapping[str, Any],
|
||||
video_latents: Sequence[Any],
|
||||
@@ -189,6 +230,7 @@ def prepare_physical_refine_groups(
|
||||
adapt_group_conditioning_fn=None,
|
||||
group_consumer_fn=None,
|
||||
retain_group_outputs: bool = True,
|
||||
selected_group_indices: Sequence[int] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Prepare one MODEL and one complete CONDITIONING per physical group.
|
||||
|
||||
@@ -202,6 +244,11 @@ def prepare_physical_refine_groups(
|
||||
video_latents,
|
||||
assembly_plan,
|
||||
)
|
||||
selected_indices, selection_active = _normalize_selected_group_indices(
|
||||
selected_group_indices,
|
||||
len(groups),
|
||||
)
|
||||
selected_index_set = set(selected_indices)
|
||||
encode_prompt_fn = encode_prompt_fn or encode_prompt_conditioning
|
||||
clone_model_fn = clone_model_fn or clone_model_for_chunk
|
||||
validate_refine_context_fn = validate_refine_context_fn or validate_refine_context
|
||||
@@ -248,6 +295,8 @@ def prepare_physical_refine_groups(
|
||||
group_conditioning: list[list[Any]] = []
|
||||
details: list[dict[str, Any]] = []
|
||||
for group_index, group in enumerate(groups):
|
||||
if group_index not in selected_index_set:
|
||||
continue
|
||||
captured_group = (
|
||||
captured_groups[group_index] if captured_groups is not None else None
|
||||
)
|
||||
@@ -344,11 +393,12 @@ def prepare_physical_refine_groups(
|
||||
details.append(detail)
|
||||
|
||||
physical_group_count = len(groups)
|
||||
selected_group_count = len(selected_indices)
|
||||
if retain_group_outputs and not (
|
||||
len(group_models)
|
||||
== len(group_conditioning)
|
||||
== len(details)
|
||||
== physical_group_count
|
||||
== selected_group_count
|
||||
):
|
||||
raise SecondPassContractError(
|
||||
"prepared MODEL/CONDITIONING physical group counts differ"
|
||||
@@ -367,6 +417,9 @@ def prepare_physical_refine_groups(
|
||||
"details": details,
|
||||
"warnings": warnings,
|
||||
"physical_group_count": physical_group_count,
|
||||
"selected_group_count": selected_group_count,
|
||||
"selected_group_indices": list(selected_indices),
|
||||
"selection_active": selection_active,
|
||||
"target_latent_h": target_h,
|
||||
"target_latent_w": target_w,
|
||||
}
|
||||
@@ -394,6 +447,8 @@ def run_second_pass_groups(
|
||||
validate_refine_context_fn=None,
|
||||
adapt_group_conditioning_fn=None,
|
||||
refine_schedule: RefineSchedule | None = None,
|
||||
selected_group_indices: Sequence[int] | None = None,
|
||||
temporal_windows_by_group: Mapping[int, Any] | None = None,
|
||||
) -> tuple[list[dict[str, Any]], list[Any], dict[str, Any], str]:
|
||||
"""Refine complete physical groups while preserving first-pass audio exactly."""
|
||||
|
||||
@@ -405,10 +460,16 @@ def run_second_pass_groups(
|
||||
effective_sigmas = resolved_schedule.sigmas
|
||||
schedule_contract = serializable_schedule_contract(resolved_schedule)
|
||||
groups = _contract_groups(assembly_plan)
|
||||
selected_indices, selection_active = _normalize_selected_group_indices(
|
||||
selected_group_indices,
|
||||
len(groups),
|
||||
)
|
||||
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]] = []
|
||||
refined_videos: list[dict[str, Any]] = (
|
||||
list(video_latents) if selection_active else []
|
||||
)
|
||||
group_seeds: list[int] = []
|
||||
conditioning_sources: list[str] = []
|
||||
group_report_lines: list[str] = []
|
||||
@@ -432,7 +493,7 @@ def run_second_pass_groups(
|
||||
group_seeds.append(physical_seed)
|
||||
conditioning_sources.append(conditioning_source)
|
||||
nested_latent = latent_builder(video_samples, audio_samples)
|
||||
sampled = sample_fn(
|
||||
sample_arguments = dict(
|
||||
model=chunk_model,
|
||||
conditioning=conditioning,
|
||||
latent=nested_latent,
|
||||
@@ -441,6 +502,14 @@ def run_second_pass_groups(
|
||||
seed=physical_seed,
|
||||
enable_preview=bool(enable_preview),
|
||||
)
|
||||
if temporal_windows_by_group is not None:
|
||||
temporal_window = temporal_windows_by_group.get(group_index)
|
||||
if temporal_window is None:
|
||||
raise SecondPassContractError(
|
||||
f"selected physical group {group_index + 1} has no temporal window"
|
||||
)
|
||||
sample_arguments["temporal_window"] = temporal_window
|
||||
sampled = sample_fn(**sample_arguments)
|
||||
refined_video, _temporary_audio = stream_extractor(sampled)
|
||||
if tuple(refined_video.shape) != tuple(video_samples.shape):
|
||||
raise SecondPassContractError(
|
||||
@@ -452,7 +521,10 @@ def run_second_pass_groups(
|
||||
)
|
||||
output_latent = dict(video_latent)
|
||||
output_latent["samples"] = refined_video
|
||||
refined_videos.append(output_latent)
|
||||
if selection_active:
|
||||
refined_videos[group_index] = output_latent
|
||||
else:
|
||||
refined_videos.append(output_latent)
|
||||
group_report_lines.append(
|
||||
"group "
|
||||
f"{group_index + 1}: logical_chunks={group.get('logical_chunks')}, "
|
||||
@@ -491,7 +563,12 @@ def run_second_pass_groups(
|
||||
adapt_group_conditioning_fn=adapt_group_conditioning_fn,
|
||||
group_consumer_fn=sample_prepared_group,
|
||||
retain_group_outputs=False,
|
||||
selected_group_indices=(selected_indices if selection_active else None),
|
||||
)
|
||||
if len(group_seeds) != len(selected_indices):
|
||||
raise SecondPassContractError(
|
||||
"Video refine Sampling count differs from selected physical group count"
|
||||
)
|
||||
report_lines = [
|
||||
"H3 Continuum Second Pass V3.5",
|
||||
"Mode: context-aware physical-group refine when a complete First Pass "
|
||||
@@ -509,6 +586,14 @@ def run_second_pass_groups(
|
||||
*prepared["warnings"],
|
||||
*group_report_lines,
|
||||
]
|
||||
if selection_active:
|
||||
report_lines.insert(
|
||||
3,
|
||||
"Selected physical groups: "
|
||||
+ ", ".join(str(index + 1) for index in selected_indices)
|
||||
+ "; non-selected groups were exact object passthrough with no "
|
||||
"conditioning, MODEL clone, Sampling, or seed derivation.",
|
||||
)
|
||||
|
||||
passthrough_audio = passthrough_audio_latents(audio_latents)
|
||||
updated_plan = prepared["updated_assembly_plan"]
|
||||
|
||||
+274
-1
@@ -4,7 +4,43 @@ from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from .refine_target import MODE_AUDIO_ONLY, MODE_VIDEO_AUDIO, MODE_VIDEO_ONLY
|
||||
from .refine_scope import MODE_ALL, MODE_LOGICAL_CHUNK, MODE_PHYSICAL_GROUP
|
||||
from .refine_window import MODE_TIME_WINDOW
|
||||
from .second_pass import run_second_pass_groups
|
||||
from .targeted_second_pass import run_targeted_second_pass_groups
|
||||
|
||||
|
||||
REFINE_TARGET_VIDEO_ONLY = "Video Only"
|
||||
REFINE_TARGET_AUDIO_ONLY = "Audio Only"
|
||||
REFINE_TARGET_VIDEO_AUDIO = "Video + Audio"
|
||||
REFINE_TARGET_OPTIONS = (
|
||||
REFINE_TARGET_VIDEO_ONLY,
|
||||
REFINE_TARGET_AUDIO_ONLY,
|
||||
REFINE_TARGET_VIDEO_AUDIO,
|
||||
)
|
||||
_REFINE_TARGET_MODES = {
|
||||
REFINE_TARGET_VIDEO_ONLY: MODE_VIDEO_ONLY,
|
||||
REFINE_TARGET_AUDIO_ONLY: MODE_AUDIO_ONLY,
|
||||
REFINE_TARGET_VIDEO_AUDIO: MODE_VIDEO_AUDIO,
|
||||
}
|
||||
|
||||
REFINE_SCOPE_ALL = "All"
|
||||
REFINE_SCOPE_PHYSICAL_GROUP = "Physical Group"
|
||||
REFINE_SCOPE_LOGICAL_CHUNK = "Logical Chunk"
|
||||
REFINE_SCOPE_TIME_WINDOW = "Time Window"
|
||||
REFINE_SCOPE_OPTIONS = (
|
||||
REFINE_SCOPE_ALL,
|
||||
REFINE_SCOPE_PHYSICAL_GROUP,
|
||||
REFINE_SCOPE_LOGICAL_CHUNK,
|
||||
REFINE_SCOPE_TIME_WINDOW,
|
||||
)
|
||||
_REFINE_SCOPE_MODES = {
|
||||
REFINE_SCOPE_ALL: MODE_ALL,
|
||||
REFINE_SCOPE_PHYSICAL_GROUP: MODE_PHYSICAL_GROUP,
|
||||
REFINE_SCOPE_LOGICAL_CHUNK: MODE_LOGICAL_CHUNK,
|
||||
REFINE_SCOPE_TIME_WINDOW: MODE_TIME_WINDOW,
|
||||
}
|
||||
|
||||
|
||||
def _single_list_input(name: str, value: Any) -> Any:
|
||||
@@ -103,10 +139,247 @@ class H3ContinuumSecondPassV35:
|
||||
)
|
||||
|
||||
|
||||
def resolve_selective_refine_target(value: str) -> str:
|
||||
"""Resolve one public UI label to the versioned internal target mode."""
|
||||
|
||||
try:
|
||||
return _REFINE_TARGET_MODES[value]
|
||||
except (KeyError, TypeError) as exc:
|
||||
raise ValueError(f"unsupported selective refine target {value!r}") from exc
|
||||
|
||||
|
||||
def resolve_selective_refine_scope(value: str) -> str:
|
||||
"""Resolve one public UI label to the versioned internal scope mode."""
|
||||
|
||||
try:
|
||||
return _REFINE_SCOPE_MODES[value]
|
||||
except (KeyError, TypeError) as exc:
|
||||
raise ValueError(f"unsupported selective refine scope {value!r}") from exc
|
||||
|
||||
|
||||
def _selective_status_prefix(
|
||||
label: str,
|
||||
physical_group_count: int,
|
||||
scope_label: str,
|
||||
scope_index: int,
|
||||
window_start_sec: float,
|
||||
window_end_sec: float,
|
||||
) -> str:
|
||||
if label == REFINE_TARGET_VIDEO_ONLY:
|
||||
detail = "Video=refined; Audio=bit-exact passthrough"
|
||||
elif label == REFINE_TARGET_AUDIO_ONLY:
|
||||
detail = "Experimental / Production HOLD; Video=locked; Audio=refined"
|
||||
elif label == REFINE_TARGET_VIDEO_AUDIO:
|
||||
detail = (
|
||||
"GPU Experimental PASS / Production HOLD; "
|
||||
"Video=refined; Audio=refined"
|
||||
)
|
||||
else:
|
||||
raise ValueError(f"unsupported selective refine target {label!r}")
|
||||
if scope_label == REFINE_SCOPE_ALL:
|
||||
scope_detail = "."
|
||||
elif scope_label == REFINE_SCOPE_TIME_WINDOW:
|
||||
scope_detail = f" [{window_start_sec:g}, {window_end_sec:g}) sec."
|
||||
else:
|
||||
scope_detail = f" {scope_index}."
|
||||
return (
|
||||
f"Selective Refine: {label}; {detail}; "
|
||||
f"physical groups={physical_group_count}; scope={scope_label}"
|
||||
+ scope_detail
|
||||
)
|
||||
|
||||
|
||||
class H3ContinuumSelectiveSecondPassExperimental:
|
||||
"""Experimental public adapter for versioned selective-refine targets."""
|
||||
|
||||
DEPRECATED = False
|
||||
DESCRIPTION = (
|
||||
"Experimental Selective Second Pass for MiniMax H3. Video Only preserves "
|
||||
"compatibility with the existing Continuum Second Pass. Audio Only keeps "
|
||||
"the input video locked and refines audio. Video + Audio refines both AV "
|
||||
"streams. Audio-targeted modes remain Experimental while upstream H3 "
|
||||
"denoise-mask correctness is under review. Chunk scope skips complete "
|
||||
"physical groups without conditioning, model clone, Sampling, or seed use; "
|
||||
"a logical chunk inside Terminal Merge expands to the complete pair. Time "
|
||||
"Window uses the final visible output timeline, protects continuation "
|
||||
"prefixes, and restores every out-of-window latent position bit-exactly."
|
||||
)
|
||||
|
||||
@classmethod
|
||||
def INPUT_TYPES(cls):
|
||||
return {
|
||||
"required": {
|
||||
"model": ("MODEL",),
|
||||
"clip": ("CLIP",),
|
||||
"sampler": ("SAMPLER",),
|
||||
"sigmas": ("SIGMAS",),
|
||||
"video_latents": ("LATENT",),
|
||||
"audio_latents": ("LATENT",),
|
||||
"assembly_plan": ("H3_CONTINUUM_ASSEMBLY_PLAN",),
|
||||
"refine_seed": (
|
||||
"INT",
|
||||
{
|
||||
"default": 0,
|
||||
"min": 0,
|
||||
"max": 0xFFFFFFFFFFFFFFFF,
|
||||
"control_after_generate": True,
|
||||
"tooltip": "Base seed independently derived once per physical group.",
|
||||
},
|
||||
),
|
||||
"refine_target": (
|
||||
REFINE_TARGET_OPTIONS,
|
||||
{"default": REFINE_TARGET_VIDEO_ONLY},
|
||||
),
|
||||
"refine_scope": (
|
||||
REFINE_SCOPE_OPTIONS,
|
||||
{"default": REFINE_SCOPE_ALL},
|
||||
),
|
||||
"refine_scope_index": (
|
||||
"INT",
|
||||
{
|
||||
"default": 1,
|
||||
"min": 1,
|
||||
"max": 0x7FFFFFFF,
|
||||
"tooltip": (
|
||||
"1-based physical-group or logical-chunk number. "
|
||||
"Ignored when Refine Scope is All or Time Window."
|
||||
),
|
||||
},
|
||||
),
|
||||
"window_start_sec": (
|
||||
"FLOAT",
|
||||
{
|
||||
"default": 0.0,
|
||||
"min": 0.0,
|
||||
"max": 86400.0,
|
||||
"step": 0.01,
|
||||
"tooltip": (
|
||||
"Time Window start on the final visible output timeline. "
|
||||
"Ignored by other Refine Scope modes."
|
||||
),
|
||||
},
|
||||
),
|
||||
"window_end_sec": (
|
||||
"FLOAT",
|
||||
{
|
||||
"default": 5.0,
|
||||
"min": 0.01,
|
||||
"max": 86400.0,
|
||||
"step": 0.01,
|
||||
"tooltip": (
|
||||
"Exclusive Time Window end on the final visible output "
|
||||
"timeline. Ignored by other Refine Scope modes."
|
||||
),
|
||||
},
|
||||
),
|
||||
},
|
||||
"optional": {
|
||||
"refine_context": ("H3_CONTINUUM_REFINE_CONTEXT",),
|
||||
"video_vae": ("VAE",),
|
||||
},
|
||||
}
|
||||
|
||||
INPUT_IS_LIST = True
|
||||
RETURN_TYPES = ("LATENT", "LATENT", "H3_CONTINUUM_ASSEMBLY_PLAN", "STRING")
|
||||
RETURN_NAMES = (
|
||||
"refined_video_latents",
|
||||
"audio_latents",
|
||||
"updated_assembly_plan",
|
||||
"status",
|
||||
)
|
||||
OUTPUT_IS_LIST = (True, True, False, False)
|
||||
FUNCTION = "refine"
|
||||
CATEGORY = "MiniMax H3/Continuum/Advanced"
|
||||
|
||||
def refine(
|
||||
self,
|
||||
model,
|
||||
clip,
|
||||
sampler,
|
||||
sigmas,
|
||||
video_latents,
|
||||
audio_latents,
|
||||
assembly_plan,
|
||||
refine_seed,
|
||||
refine_target,
|
||||
refine_scope=None,
|
||||
refine_scope_index=None,
|
||||
window_start_sec=None,
|
||||
window_end_sec=None,
|
||||
refine_context=None,
|
||||
video_vae=None,
|
||||
refine_schedule=None,
|
||||
):
|
||||
label = _single_list_input("refine_target", refine_target)
|
||||
target_mode = resolve_selective_refine_target(label)
|
||||
scope_label = (
|
||||
REFINE_SCOPE_ALL
|
||||
if refine_scope is None
|
||||
else _single_list_input("refine_scope", refine_scope)
|
||||
)
|
||||
scope_mode = resolve_selective_refine_scope(scope_label)
|
||||
resolved_scope_index = (
|
||||
1
|
||||
if refine_scope_index is None
|
||||
else int(_single_list_input("refine_scope_index", refine_scope_index))
|
||||
)
|
||||
resolved_window_start = (
|
||||
0.0
|
||||
if window_start_sec is None
|
||||
else float(_single_list_input("window_start_sec", window_start_sec))
|
||||
)
|
||||
resolved_window_end = (
|
||||
5.0
|
||||
if window_end_sec is None
|
||||
else float(_single_list_input("window_end_sec", window_end_sec))
|
||||
)
|
||||
videos, audios, updated_plan, status = run_targeted_second_pass_groups(
|
||||
model=_single_list_input("model", model),
|
||||
clip=_single_list_input("clip", clip),
|
||||
sampler=_single_list_input("sampler", sampler),
|
||||
sigmas=_single_list_input("sigmas", sigmas),
|
||||
video_latents=video_latents,
|
||||
audio_latents=audio_latents,
|
||||
assembly_plan=_single_list_input("assembly_plan", assembly_plan),
|
||||
refine_seed=int(_single_list_input("refine_seed", refine_seed)),
|
||||
refine_target=target_mode,
|
||||
refine_scope=scope_mode,
|
||||
refine_scope_index=resolved_scope_index,
|
||||
window_start_sec=resolved_window_start,
|
||||
window_end_sec=resolved_window_end,
|
||||
refine_context=(
|
||||
None
|
||||
if refine_context is None
|
||||
else _single_list_input("refine_context", refine_context)
|
||||
),
|
||||
video_vae=(
|
||||
None
|
||||
if video_vae is None
|
||||
else _single_list_input("video_vae", video_vae)
|
||||
),
|
||||
refine_schedule=refine_schedule,
|
||||
)
|
||||
prefix = _selective_status_prefix(
|
||||
label,
|
||||
len(video_latents),
|
||||
scope_label,
|
||||
resolved_scope_index,
|
||||
resolved_window_start,
|
||||
resolved_window_end,
|
||||
)
|
||||
return videos, audios, updated_plan, f"{prefix}\n{status}"
|
||||
|
||||
|
||||
NODE_CLASS_MAPPINGS = {
|
||||
"H3ContinuumSecondPassV35": H3ContinuumSecondPassV35,
|
||||
"H3ContinuumSelectiveSecondPassExperimental": (
|
||||
H3ContinuumSelectiveSecondPassExperimental
|
||||
),
|
||||
}
|
||||
|
||||
NODE_DISPLAY_NAME_MAPPINGS = {
|
||||
"H3ContinuumSecondPassV35": "H3 Continuum Second Pass V3.5",
|
||||
"H3ContinuumSecondPassV35": "H3 Continuum Second Pass",
|
||||
"H3ContinuumSelectiveSecondPassExperimental": (
|
||||
"H3 Continuum Selective Second Pass (Experimental)"
|
||||
),
|
||||
}
|
||||
|
||||
@@ -0,0 +1,496 @@
|
||||
"""Target-aware refinement sampling for frozen Video and Audio policies."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any, Callable
|
||||
|
||||
import torch
|
||||
|
||||
from ..state import extract_av_streams
|
||||
from .refine_sampling import (
|
||||
RefineSamplingRuntimeError,
|
||||
_load_runtime_modules,
|
||||
_make_basic_guider,
|
||||
sample_refine_chunk,
|
||||
)
|
||||
from .refine_target import (
|
||||
MODE_AUDIO_ONLY,
|
||||
MODE_VIDEO_AUDIO,
|
||||
MODE_VIDEO_ONLY,
|
||||
RefineTarget,
|
||||
RefineTargetError,
|
||||
resolve_refine_target,
|
||||
)
|
||||
from .refine_window import GroupTemporalWindow
|
||||
|
||||
|
||||
class TargetedRefineExecutionUnavailable(RefineTargetError):
|
||||
"""Raised before Sampling when a future target mode is not implemented."""
|
||||
|
||||
|
||||
def _validate_ranges(
|
||||
ranges: tuple[tuple[int, int], ...],
|
||||
length: int,
|
||||
*,
|
||||
name: str,
|
||||
) -> tuple[tuple[int, int], ...]:
|
||||
if not ranges:
|
||||
raise RefineSamplingRuntimeError(f"{name} temporal window is empty")
|
||||
previous_stop = 0
|
||||
for start, stop in ranges:
|
||||
if start < previous_stop or stop <= start or stop > int(length):
|
||||
raise RefineSamplingRuntimeError(
|
||||
f"{name} temporal window is outside its latent length"
|
||||
)
|
||||
previous_stop = stop
|
||||
return ranges
|
||||
|
||||
|
||||
def _window_masks(
|
||||
video: torch.Tensor,
|
||||
audio: torch.Tensor,
|
||||
temporal_window: GroupTemporalWindow,
|
||||
) -> tuple[torch.Tensor, torch.Tensor]:
|
||||
if not isinstance(temporal_window, GroupTemporalWindow):
|
||||
raise RefineSamplingRuntimeError(
|
||||
"temporal window must be a resolved GroupTemporalWindow"
|
||||
)
|
||||
video_ranges = _validate_ranges(
|
||||
temporal_window.video_slot_ranges,
|
||||
int(video.shape[2]),
|
||||
name="Video",
|
||||
)
|
||||
audio_ranges = _validate_ranges(
|
||||
temporal_window.audio_tick_ranges,
|
||||
int(audio.shape[-1]),
|
||||
name="Audio",
|
||||
)
|
||||
video_mask = torch.zeros(
|
||||
(
|
||||
int(video.shape[0]),
|
||||
1,
|
||||
int(video.shape[2]),
|
||||
int(video.shape[3]),
|
||||
int(video.shape[4]),
|
||||
),
|
||||
dtype=torch.float32,
|
||||
device="cpu",
|
||||
)
|
||||
audio_mask = torch.zeros(
|
||||
(
|
||||
int(audio.shape[0]),
|
||||
1,
|
||||
int(audio.shape[2]),
|
||||
int(audio.shape[3]),
|
||||
),
|
||||
dtype=torch.float32,
|
||||
device="cpu",
|
||||
)
|
||||
for start, stop in video_ranges:
|
||||
video_mask[:, :, start:stop] = 1.0
|
||||
for start, stop in audio_ranges:
|
||||
audio_mask[..., start:stop] = 1.0
|
||||
return video_mask, audio_mask
|
||||
|
||||
|
||||
def _prepare_video_only_noise_and_mask(
|
||||
video: torch.Tensor,
|
||||
audio: torch.Tensor,
|
||||
*,
|
||||
seed: int,
|
||||
batch_inds: Any = None,
|
||||
prepare_noise_fn: Callable[[torch.Tensor, int, Any], torch.Tensor],
|
||||
nested_builder: Callable[[tuple[torch.Tensor, torch.Tensor]], Any],
|
||||
temporal_window: GroupTemporalWindow,
|
||||
) -> tuple[Any, Any]:
|
||||
"""Build windowed Video noise/mask while locking Audio completely."""
|
||||
|
||||
video_noise = prepare_noise_fn(video, int(seed), batch_inds)
|
||||
if not torch.is_tensor(video_noise) or tuple(video_noise.shape) != tuple(video.shape):
|
||||
raise RefineSamplingRuntimeError(
|
||||
"ComfyUI returned invalid Video Only noise geometry"
|
||||
)
|
||||
video_mask, _audio_window_mask = _window_masks(video, audio, temporal_window)
|
||||
audio_noise = torch.zeros_like(audio, device="cpu")
|
||||
audio_mask = torch.zeros(
|
||||
(int(audio.shape[0]), 1, 1, 1),
|
||||
dtype=torch.float32,
|
||||
device="cpu",
|
||||
)
|
||||
return (
|
||||
nested_builder((video_noise, audio_noise)),
|
||||
nested_builder((video_mask, audio_mask)),
|
||||
)
|
||||
|
||||
|
||||
def require_video_only_execution(
|
||||
refine_target: RefineTarget | str | None,
|
||||
) -> RefineTarget:
|
||||
target = resolve_refine_target(refine_target)
|
||||
if target.mode != MODE_VIDEO_ONLY:
|
||||
raise TargetedRefineExecutionUnavailable(
|
||||
f"refine target {target.mode!r} is contract-only in Phase A1"
|
||||
)
|
||||
return target
|
||||
|
||||
|
||||
def _prepare_audio_only_noise_and_mask(
|
||||
video: torch.Tensor,
|
||||
audio: torch.Tensor,
|
||||
*,
|
||||
seed: int,
|
||||
batch_inds: Any = None,
|
||||
prepare_noise_fn: Callable[[torch.Tensor, int, Any], torch.Tensor],
|
||||
nested_builder: Callable[[tuple[torch.Tensor, torch.Tensor]], Any],
|
||||
temporal_window: GroupTemporalWindow | None = None,
|
||||
) -> tuple[Any, Any]:
|
||||
"""Build zero/locked Video and seeded-random/sampled Audio streams."""
|
||||
|
||||
if video.ndim != 5 or audio.ndim != 4:
|
||||
raise RefineSamplingRuntimeError(
|
||||
"targeted latent must contain video [B,C,T,H,W] and audio [B,C,2,T]"
|
||||
)
|
||||
if int(video.shape[0]) != int(audio.shape[0]):
|
||||
raise RefineSamplingRuntimeError("targeted video/audio batch sizes differ")
|
||||
|
||||
audio_noise = prepare_noise_fn(audio, int(seed), batch_inds)
|
||||
if not torch.is_tensor(audio_noise) or tuple(audio_noise.shape) != tuple(audio.shape):
|
||||
raise RefineSamplingRuntimeError(
|
||||
"ComfyUI returned invalid Audio Only noise geometry"
|
||||
)
|
||||
video_noise = torch.zeros_like(video, device="cpu")
|
||||
if temporal_window is None:
|
||||
video_mask = torch.zeros(
|
||||
(int(video.shape[0]), 1, 1, 1, 1),
|
||||
dtype=torch.float32,
|
||||
device="cpu",
|
||||
)
|
||||
audio_mask = torch.ones(
|
||||
(int(audio.shape[0]), 1, 1, 1),
|
||||
dtype=torch.float32,
|
||||
device="cpu",
|
||||
)
|
||||
else:
|
||||
_video_window_mask, audio_mask = _window_masks(
|
||||
video,
|
||||
audio,
|
||||
temporal_window,
|
||||
)
|
||||
video_mask = torch.zeros(
|
||||
(int(video.shape[0]), 1, 1, 1, 1),
|
||||
dtype=torch.float32,
|
||||
device="cpu",
|
||||
)
|
||||
noise = nested_builder((video_noise, audio_noise))
|
||||
noise_mask = nested_builder((video_mask, audio_mask))
|
||||
return noise, noise_mask
|
||||
|
||||
|
||||
def _prepare_video_audio_noise_and_mask(
|
||||
video: torch.Tensor,
|
||||
audio: torch.Tensor,
|
||||
*,
|
||||
seed: int,
|
||||
batch_inds: Any = None,
|
||||
prepare_noise_fn: Callable[[torch.Tensor, int, Any], torch.Tensor],
|
||||
nested_builder: Callable[[tuple[torch.Tensor, torch.Tensor]], Any],
|
||||
temporal_window: GroupTemporalWindow | None = None,
|
||||
) -> tuple[Any, Any]:
|
||||
"""Build seeded-random noise and sampled masks for both AV streams."""
|
||||
|
||||
if video.ndim != 5 or audio.ndim != 4:
|
||||
raise RefineSamplingRuntimeError(
|
||||
"targeted latent must contain video [B,C,T,H,W] and audio [B,C,2,T]"
|
||||
)
|
||||
if int(video.shape[0]) != int(audio.shape[0]):
|
||||
raise RefineSamplingRuntimeError("targeted video/audio batch sizes differ")
|
||||
|
||||
video_noise = prepare_noise_fn(video, int(seed), batch_inds)
|
||||
audio_noise = prepare_noise_fn(audio, int(seed), batch_inds)
|
||||
if not torch.is_tensor(video_noise) or tuple(video_noise.shape) != tuple(video.shape):
|
||||
raise RefineSamplingRuntimeError(
|
||||
"ComfyUI returned invalid Video + Audio video noise geometry"
|
||||
)
|
||||
if not torch.is_tensor(audio_noise) or tuple(audio_noise.shape) != tuple(audio.shape):
|
||||
raise RefineSamplingRuntimeError(
|
||||
"ComfyUI returned invalid Video + Audio audio noise geometry"
|
||||
)
|
||||
if temporal_window is None:
|
||||
video_mask = torch.ones(
|
||||
(int(video.shape[0]), 1, 1, 1, 1),
|
||||
dtype=torch.float32,
|
||||
device="cpu",
|
||||
)
|
||||
audio_mask = torch.ones(
|
||||
(int(audio.shape[0]), 1, 1, 1),
|
||||
dtype=torch.float32,
|
||||
device="cpu",
|
||||
)
|
||||
else:
|
||||
video_mask, audio_mask = _window_masks(video, audio, temporal_window)
|
||||
noise = nested_builder((video_noise, audio_noise))
|
||||
noise_mask = nested_builder((video_mask, audio_mask))
|
||||
return noise, noise_mask
|
||||
|
||||
|
||||
def _sample_with_target_noise_and_mask(
|
||||
*,
|
||||
model: Any,
|
||||
conditioning: list,
|
||||
latent: dict[str, Any],
|
||||
sampler: Any,
|
||||
sigmas: torch.Tensor,
|
||||
seed: int,
|
||||
enable_preview: bool,
|
||||
noise_mask_builder: Callable[..., tuple[Any, Any]],
|
||||
temporal_window: GroupTemporalWindow | None = None,
|
||||
restore_video_outside_window: bool = False,
|
||||
restore_audio_outside_window: bool = False,
|
||||
) -> dict[str, Any]:
|
||||
"""Run Core once after constructing one explicit AV target policy."""
|
||||
|
||||
if not isinstance(latent, dict) or "samples" not in latent:
|
||||
raise RefineSamplingRuntimeError("latent must be a ComfyUI LATENT dictionary")
|
||||
if not torch.is_tensor(sigmas) or sigmas.ndim != 1 or sigmas.numel() < 2:
|
||||
raise RefineSamplingRuntimeError("sigmas must contain at least two values")
|
||||
|
||||
model_management, nested_tensor, comfy_sample, comfy_utils, preview = (
|
||||
_load_runtime_modules()
|
||||
)
|
||||
working = latent.copy()
|
||||
latent_image = comfy_sample.fix_empty_latent_channels(
|
||||
model,
|
||||
working["samples"],
|
||||
working.get("downscale_ratio_spacial"),
|
||||
working.get("downscale_ratio_temporal"),
|
||||
)
|
||||
working["samples"] = latent_image
|
||||
video, audio = extract_av_streams(working)
|
||||
noise, noise_mask = noise_mask_builder(
|
||||
video,
|
||||
audio,
|
||||
seed=int(seed),
|
||||
batch_inds=working.get("batch_index"),
|
||||
prepare_noise_fn=comfy_sample.prepare_noise,
|
||||
nested_builder=nested_tensor.NestedTensor,
|
||||
temporal_window=temporal_window,
|
||||
)
|
||||
guider = _make_basic_guider(model, conditioning)
|
||||
|
||||
x0_output: dict[str, Any] = {}
|
||||
callback = None
|
||||
if enable_preview:
|
||||
callback = preview.prepare_callback(
|
||||
model,
|
||||
int(sigmas.shape[-1]) - 1,
|
||||
x0_output,
|
||||
)
|
||||
samples = guider.sample(
|
||||
noise,
|
||||
latent_image,
|
||||
sampler,
|
||||
sigmas,
|
||||
denoise_mask=noise_mask,
|
||||
callback=callback,
|
||||
disable_pbar=not comfy_utils.PROGRESS_BAR_ENABLED,
|
||||
seed=int(seed),
|
||||
)
|
||||
samples = samples.to(model_management.intermediate_device())
|
||||
if temporal_window is not None:
|
||||
sampled_output = {"samples": samples}
|
||||
sampled_video, sampled_audio = extract_av_streams(sampled_output)
|
||||
if restore_video_outside_window:
|
||||
sampled_video = _restore_outside_temporal_ranges(
|
||||
sampled_video,
|
||||
video,
|
||||
temporal_window.video_slot_ranges,
|
||||
time_dim=2,
|
||||
name="Video",
|
||||
)
|
||||
if restore_audio_outside_window:
|
||||
sampled_audio = _restore_outside_temporal_ranges(
|
||||
sampled_audio,
|
||||
audio,
|
||||
temporal_window.audio_tick_ranges,
|
||||
time_dim=-1,
|
||||
name="Audio",
|
||||
)
|
||||
samples = nested_tensor.NestedTensor((sampled_video, sampled_audio))
|
||||
|
||||
output = working.copy()
|
||||
output.pop("downscale_ratio_spacial", None)
|
||||
output.pop("downscale_ratio_temporal", None)
|
||||
output["samples"] = samples
|
||||
extract_av_streams(output)
|
||||
return output
|
||||
|
||||
|
||||
def _restore_outside_temporal_ranges(
|
||||
sampled: torch.Tensor,
|
||||
source: torch.Tensor,
|
||||
ranges: tuple[tuple[int, int], ...],
|
||||
*,
|
||||
time_dim: int,
|
||||
name: str,
|
||||
) -> torch.Tensor:
|
||||
"""Restore every inactive temporal position from the input bit-exactly."""
|
||||
|
||||
if not torch.is_tensor(sampled) or not torch.is_tensor(source):
|
||||
raise RefineSamplingRuntimeError(f"{name} temporal restore requires Tensors")
|
||||
if tuple(sampled.shape) != tuple(source.shape):
|
||||
raise RefineSamplingRuntimeError(
|
||||
f"{name} temporal restore input/output shapes differ"
|
||||
)
|
||||
if sampled.dtype != source.dtype:
|
||||
raise RefineSamplingRuntimeError(
|
||||
f"{name} temporal restore input/output dtypes differ"
|
||||
)
|
||||
dim = int(time_dim)
|
||||
if dim < 0:
|
||||
dim += sampled.ndim
|
||||
if dim < 0 or dim >= sampled.ndim:
|
||||
raise RefineSamplingRuntimeError(f"{name} temporal restore dimension is invalid")
|
||||
validated = _validate_ranges(ranges, int(sampled.shape[dim]), name=name)
|
||||
restored = sampled.clone()
|
||||
original = source.to(device=restored.device)
|
||||
cursor = 0
|
||||
for start, stop in validated:
|
||||
if start > cursor:
|
||||
restored.narrow(dim, cursor, start - cursor).copy_(
|
||||
original.narrow(dim, cursor, start - cursor)
|
||||
)
|
||||
cursor = stop
|
||||
if cursor < int(restored.shape[dim]):
|
||||
restored.narrow(dim, cursor, int(restored.shape[dim]) - cursor).copy_(
|
||||
original.narrow(dim, cursor, int(restored.shape[dim]) - cursor)
|
||||
)
|
||||
return restored
|
||||
|
||||
|
||||
def sample_video_only_window_refine_chunk(
|
||||
*,
|
||||
model: Any,
|
||||
conditioning: list,
|
||||
latent: dict[str, Any],
|
||||
sampler: Any,
|
||||
sigmas: torch.Tensor,
|
||||
seed: int,
|
||||
temporal_window: GroupTemporalWindow,
|
||||
enable_preview: bool = True,
|
||||
) -> dict[str, Any]:
|
||||
"""Refine only selected Video slots and restore all other AV positions."""
|
||||
|
||||
return _sample_with_target_noise_and_mask(
|
||||
model=model,
|
||||
conditioning=conditioning,
|
||||
latent=latent,
|
||||
sampler=sampler,
|
||||
sigmas=sigmas,
|
||||
seed=int(seed),
|
||||
enable_preview=bool(enable_preview),
|
||||
noise_mask_builder=_prepare_video_only_noise_and_mask,
|
||||
temporal_window=temporal_window,
|
||||
restore_video_outside_window=True,
|
||||
restore_audio_outside_window=True,
|
||||
)
|
||||
|
||||
|
||||
def sample_audio_only_refine_chunk(
|
||||
*,
|
||||
model: Any,
|
||||
conditioning: list,
|
||||
latent: dict[str, Any],
|
||||
sampler: Any,
|
||||
sigmas: torch.Tensor,
|
||||
seed: int,
|
||||
temporal_window: GroupTemporalWindow | None = None,
|
||||
enable_preview: bool = True,
|
||||
) -> dict[str, Any]:
|
||||
"""Sample Audio while Core carries Video with zero noise and mask zero."""
|
||||
|
||||
return _sample_with_target_noise_and_mask(
|
||||
model=model,
|
||||
conditioning=conditioning,
|
||||
latent=latent,
|
||||
sampler=sampler,
|
||||
sigmas=sigmas,
|
||||
seed=int(seed),
|
||||
enable_preview=bool(enable_preview),
|
||||
noise_mask_builder=_prepare_audio_only_noise_and_mask,
|
||||
temporal_window=temporal_window,
|
||||
restore_video_outside_window=temporal_window is not None,
|
||||
restore_audio_outside_window=temporal_window is not None,
|
||||
)
|
||||
|
||||
|
||||
def sample_video_audio_refine_chunk(
|
||||
*,
|
||||
model: Any,
|
||||
conditioning: list,
|
||||
latent: dict[str, Any],
|
||||
sampler: Any,
|
||||
sigmas: torch.Tensor,
|
||||
seed: int,
|
||||
temporal_window: GroupTemporalWindow | None = None,
|
||||
enable_preview: bool = True,
|
||||
) -> dict[str, Any]:
|
||||
"""Sample and adopt both Video and Audio using mask one for each stream."""
|
||||
|
||||
return _sample_with_target_noise_and_mask(
|
||||
model=model,
|
||||
conditioning=conditioning,
|
||||
latent=latent,
|
||||
sampler=sampler,
|
||||
sigmas=sigmas,
|
||||
seed=int(seed),
|
||||
enable_preview=bool(enable_preview),
|
||||
noise_mask_builder=_prepare_video_audio_noise_and_mask,
|
||||
temporal_window=temporal_window,
|
||||
restore_video_outside_window=temporal_window is not None,
|
||||
restore_audio_outside_window=temporal_window is not None,
|
||||
)
|
||||
|
||||
|
||||
def sample_targeted_refine_chunk(
|
||||
*,
|
||||
model: Any,
|
||||
conditioning: list,
|
||||
latent: dict[str, Any],
|
||||
sampler: Any,
|
||||
sigmas: torch.Tensor,
|
||||
seed: int,
|
||||
refine_target: RefineTarget | str | None = MODE_VIDEO_ONLY,
|
||||
temporal_window: GroupTemporalWindow | None = None,
|
||||
enable_preview: bool = True,
|
||||
legacy_sample_fn: Callable[..., dict[str, Any]] | None = None,
|
||||
video_only_window_sample_fn: Callable[..., dict[str, Any]] | None = None,
|
||||
audio_only_sample_fn: Callable[..., dict[str, Any]] | None = None,
|
||||
video_audio_sample_fn: Callable[..., dict[str, Any]] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Dispatch an implemented target without changing its stream policy."""
|
||||
|
||||
target = resolve_refine_target(refine_target)
|
||||
if target.mode == MODE_VIDEO_ONLY and temporal_window is not None:
|
||||
sample_fn = video_only_window_sample_fn or sample_video_only_window_refine_chunk
|
||||
elif target.mode == MODE_VIDEO_ONLY:
|
||||
sample_fn = legacy_sample_fn or sample_refine_chunk
|
||||
elif target.mode == MODE_AUDIO_ONLY:
|
||||
sample_fn = audio_only_sample_fn or sample_audio_only_refine_chunk
|
||||
elif target.mode == MODE_VIDEO_AUDIO:
|
||||
sample_fn = video_audio_sample_fn or sample_video_audio_refine_chunk
|
||||
else: # pragma: no cover - resolve_refine_target validates the mode.
|
||||
raise TargetedRefineExecutionUnavailable(
|
||||
f"refine target {target.mode!r} is unavailable"
|
||||
)
|
||||
arguments = dict(
|
||||
model=model,
|
||||
conditioning=conditioning,
|
||||
latent=latent,
|
||||
sampler=sampler,
|
||||
sigmas=sigmas,
|
||||
seed=int(seed),
|
||||
enable_preview=bool(enable_preview),
|
||||
)
|
||||
if temporal_window is not None:
|
||||
arguments["temporal_window"] = temporal_window
|
||||
return sample_fn(**arguments)
|
||||
@@ -0,0 +1,491 @@
|
||||
"""Target-aware Second Pass orchestration over complete physical groups."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
import torch
|
||||
|
||||
from ..state import extract_av_streams
|
||||
from ..v2.sampling import latent_from_cpu
|
||||
from .refine_schedule import (
|
||||
RefineScheduleError,
|
||||
resolve_refine_schedule,
|
||||
serializable_schedule_contract,
|
||||
)
|
||||
from .refine_scope import (
|
||||
MODE_ALL as SCOPE_ALL,
|
||||
resolve_refine_scope,
|
||||
)
|
||||
from .refine_target import (
|
||||
MODE_AUDIO_ONLY,
|
||||
MODE_VIDEO_AUDIO,
|
||||
MODE_VIDEO_ONLY,
|
||||
RefineTarget,
|
||||
build_target_execution_contract,
|
||||
derive_target_refine_seed,
|
||||
resolve_refine_target,
|
||||
serializable_target_contract,
|
||||
)
|
||||
from .refine_window import (
|
||||
MODE_TIME_WINDOW,
|
||||
GroupTemporalWindow,
|
||||
RefineWindow,
|
||||
resolve_refine_window,
|
||||
)
|
||||
from .second_pass import (
|
||||
SecondPassContractError,
|
||||
_normalize_selected_group_indices,
|
||||
_latent_samples,
|
||||
prepare_physical_refine_groups,
|
||||
run_second_pass_groups,
|
||||
validate_second_pass_inputs,
|
||||
)
|
||||
from .targeted_refine_sampling import (
|
||||
TargetedRefineExecutionUnavailable,
|
||||
sample_targeted_refine_chunk,
|
||||
)
|
||||
|
||||
|
||||
def _attach_target_contract(
|
||||
updated_plan: dict[str, Any],
|
||||
target: RefineTarget,
|
||||
) -> None:
|
||||
contract = updated_plan.get("second_pass_contract")
|
||||
if not isinstance(contract, dict):
|
||||
raise SecondPassContractError(
|
||||
"targeted Second Pass output has no mutable contract"
|
||||
)
|
||||
if contract.get("version") != 1:
|
||||
raise SecondPassContractError(
|
||||
"targeted Second Pass must preserve contract version 1"
|
||||
)
|
||||
schedule_contract = contract.get("refine_schedule")
|
||||
contract["refine_target_contract"] = serializable_target_contract(target)
|
||||
contract["refine_execution_contract"] = build_target_execution_contract(
|
||||
target,
|
||||
schedule_contract,
|
||||
)
|
||||
|
||||
|
||||
def _run_video_only_groups(
|
||||
*,
|
||||
target: RefineTarget,
|
||||
sample_fn,
|
||||
arguments: dict[str, Any],
|
||||
selected_group_indices: Sequence[int] | None = None,
|
||||
temporal_windows_by_group: Mapping[int, GroupTemporalWindow] | None = None,
|
||||
) -> tuple[list[dict[str, Any]], list[Any], dict[str, Any], str]:
|
||||
def targeted_sample(**kwargs):
|
||||
return sample_targeted_refine_chunk(
|
||||
refine_target=target,
|
||||
legacy_sample_fn=sample_fn,
|
||||
video_only_window_sample_fn=sample_fn,
|
||||
**kwargs,
|
||||
)
|
||||
|
||||
videos, audios, updated_plan, status = run_second_pass_groups(
|
||||
**arguments,
|
||||
sample_fn=targeted_sample,
|
||||
selected_group_indices=selected_group_indices,
|
||||
temporal_windows_by_group=temporal_windows_by_group,
|
||||
)
|
||||
_attach_target_contract(updated_plan, target)
|
||||
return videos, audios, updated_plan, status
|
||||
|
||||
|
||||
def _run_sampled_target_groups(
|
||||
*,
|
||||
target: RefineTarget,
|
||||
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,
|
||||
video_vae: Any,
|
||||
conditioning_upscale_method: str,
|
||||
enable_preview: bool,
|
||||
encode_prompt_fn,
|
||||
latent_builder,
|
||||
sample_fn,
|
||||
stream_extractor,
|
||||
clone_model_fn,
|
||||
validate_refine_context_fn,
|
||||
adapt_group_conditioning_fn,
|
||||
refine_schedule,
|
||||
selected_group_indices: Sequence[int] | None = None,
|
||||
temporal_windows_by_group: Mapping[int, GroupTemporalWindow] | None = None,
|
||||
) -> tuple[list[Any], list[dict[str, Any]], dict[str, Any], str]:
|
||||
"""Sample one non-legacy target and adopt only its configured outputs."""
|
||||
|
||||
if target.mode not in (MODE_AUDIO_ONLY, MODE_VIDEO_AUDIO):
|
||||
raise TargetedRefineExecutionUnavailable(
|
||||
f"refine target {target.mode!r} is not a sampled-stream target"
|
||||
)
|
||||
adopt_sampled_video = target.mode == MODE_VIDEO_AUDIO
|
||||
|
||||
validation = validate_second_pass_inputs(
|
||||
video_latents,
|
||||
audio_latents,
|
||||
assembly_plan,
|
||||
)
|
||||
selected_indices, selection_active = _normalize_selected_group_indices(
|
||||
selected_group_indices,
|
||||
int(validation["physical_group_count"]),
|
||||
)
|
||||
try:
|
||||
resolved_schedule = resolve_refine_schedule(sigmas, refine_schedule)
|
||||
except RefineScheduleError as exc:
|
||||
raise SecondPassContractError(
|
||||
f"refine schedule is invalid: {exc}"
|
||||
) from exc
|
||||
effective_sigmas = resolved_schedule.sigmas
|
||||
schedule_contract = serializable_schedule_contract(resolved_schedule)
|
||||
latent_builder = latent_builder or latent_from_cpu
|
||||
stream_extractor = stream_extractor or extract_av_streams
|
||||
refined_videos: list[dict[str, Any]] = (
|
||||
list(video_latents) if selection_active else []
|
||||
)
|
||||
refined_audios: list[dict[str, Any]] = (
|
||||
list(audio_latents) if selection_active else []
|
||||
)
|
||||
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}]",
|
||||
)
|
||||
physical_seed = derive_target_refine_seed(
|
||||
int(refine_seed),
|
||||
group_index,
|
||||
target,
|
||||
)
|
||||
group_seeds.append(physical_seed)
|
||||
conditioning_source = str(detail["conditioning_source"])
|
||||
conditioning_sources.append(conditioning_source)
|
||||
nested_latent = latent_builder(video_samples, audio_samples)
|
||||
sample_arguments = dict(
|
||||
model=chunk_model,
|
||||
conditioning=conditioning,
|
||||
latent=nested_latent,
|
||||
sampler=sampler,
|
||||
sigmas=effective_sigmas,
|
||||
seed=physical_seed,
|
||||
refine_target=target,
|
||||
enable_preview=bool(enable_preview),
|
||||
audio_only_sample_fn=sample_fn,
|
||||
video_audio_sample_fn=sample_fn,
|
||||
)
|
||||
if temporal_windows_by_group is not None:
|
||||
temporal_window = temporal_windows_by_group.get(group_index)
|
||||
if temporal_window is None:
|
||||
raise SecondPassContractError(
|
||||
f"selected physical group {group_index + 1} has no temporal window"
|
||||
)
|
||||
sample_arguments["temporal_window"] = temporal_window
|
||||
sampled = sample_targeted_refine_chunk(**sample_arguments)
|
||||
sampled_video, sampled_audio = stream_extractor(sampled)
|
||||
if tuple(sampled_video.shape) != tuple(video_samples.shape):
|
||||
raise SecondPassContractError(
|
||||
f"sampled video group {group_index} changed B/C/T/H/W geometry"
|
||||
)
|
||||
if tuple(sampled_audio.shape) != tuple(audio_samples.shape):
|
||||
raise SecondPassContractError(
|
||||
f"refined audio group {group_index} changed B/C/stereo/T geometry"
|
||||
)
|
||||
if not bool(torch.isfinite(sampled_audio.float()).all().item()):
|
||||
raise SecondPassContractError(
|
||||
f"refined audio group {group_index} contains NaN or Inf"
|
||||
)
|
||||
if adopt_sampled_video:
|
||||
if not bool(torch.isfinite(sampled_video.float()).all().item()):
|
||||
raise SecondPassContractError(
|
||||
f"refined video group {group_index} contains NaN or Inf"
|
||||
)
|
||||
output_video = dict(video_latent)
|
||||
output_video["samples"] = sampled_video
|
||||
if selection_active:
|
||||
refined_videos[group_index] = output_video
|
||||
else:
|
||||
refined_videos.append(output_video)
|
||||
output_audio = dict(audio_latent)
|
||||
output_audio["samples"] = sampled_audio
|
||||
if selection_active:
|
||||
refined_audios[group_index] = output_audio
|
||||
else:
|
||||
refined_audios.append(output_audio)
|
||||
adoption = (
|
||||
f"video_shape={tuple(sampled_video.shape)}, "
|
||||
"sampled_video_adopted=true, sampled_audio_adopted=true"
|
||||
if adopt_sampled_video
|
||||
else "temporary_video_discarded=true"
|
||||
)
|
||||
group_report_lines.append(
|
||||
"group "
|
||||
f"{group_index + 1}: logical_chunks={group.get('logical_chunks')}, "
|
||||
f"prompt_policy={group.get('prompt_policy', 'unknown')}, "
|
||||
f"conditioning_source={conditioning_source}, "
|
||||
f"refine_seed={physical_seed}, "
|
||||
f"audio_shape={tuple(sampled_audio.shape)}, sampling_passes=1, "
|
||||
f"{adoption}"
|
||||
)
|
||||
|
||||
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,
|
||||
selected_group_indices=(selected_indices if selection_active else None),
|
||||
)
|
||||
expected_groups = int(validation["physical_group_count"])
|
||||
expected_sampled_groups = len(selected_indices)
|
||||
if len(group_seeds) != expected_sampled_groups:
|
||||
raise SecondPassContractError(
|
||||
"targeted Sampling count differs from selected physical group count"
|
||||
)
|
||||
if len(refined_audios) != expected_groups:
|
||||
raise SecondPassContractError(
|
||||
"targeted Audio output count differs from physical group count"
|
||||
)
|
||||
if adopt_sampled_video and len(refined_videos) != expected_groups:
|
||||
raise SecondPassContractError(
|
||||
"targeted Video output count differs from physical group count"
|
||||
)
|
||||
|
||||
output_videos = refined_videos if adopt_sampled_video else list(video_latents)
|
||||
updated_plan = prepared["updated_assembly_plan"]
|
||||
contract = updated_plan["second_pass_contract"]
|
||||
execution_target = "both_sampled" if adopt_sampled_video else "video_locked_audio"
|
||||
if conditioning_sources and all(
|
||||
source == "refine_context" for source in conditioning_sources
|
||||
):
|
||||
contract["execution"] = (
|
||||
f"context_aware_physical_groups_{execution_target}_v1"
|
||||
)
|
||||
elif any(source == "refine_context" for source in conditioning_sources):
|
||||
contract["execution"] = f"mixed_context_physical_groups_{execution_target}_v1"
|
||||
else:
|
||||
contract["execution"] = f"t2va_physical_groups_{execution_target}_v1"
|
||||
contract["conditioning_sources"] = conditioning_sources
|
||||
contract["refine_seed_base"] = int(refine_seed)
|
||||
contract["refine_group_seeds"] = group_seeds
|
||||
contract["video_output"] = (
|
||||
"sampled" if adopt_sampled_video else "bit_exact_first_pass_passthrough"
|
||||
)
|
||||
contract["video_sampling"] = (
|
||||
"seeded_random_mask_1" if adopt_sampled_video else "zero_noise_mask_locked"
|
||||
)
|
||||
contract["audio_output"] = "sampled"
|
||||
contract["audio_sampling"] = "seeded_random_mask_1"
|
||||
contract["refine_schedule"] = schedule_contract
|
||||
contract["refine_schedule_identity"] = schedule_contract["schedule_hash"]
|
||||
_attach_target_contract(updated_plan, target)
|
||||
|
||||
if adopt_sampled_video:
|
||||
target_line = (
|
||||
"Target: Video + Audio "
|
||||
"(GPU Experimental PASS / Production HOLD)."
|
||||
)
|
||||
sampling_line = (
|
||||
"Sampling contract: video seeded random noise/mask=1 and adopted "
|
||||
"sampled output; audio seeded random noise/mask=1 and adopted "
|
||||
"sampled output."
|
||||
)
|
||||
output_line = (
|
||||
"Outputs: sampled Video and sampled Audio adopted for every complete "
|
||||
"physical group."
|
||||
)
|
||||
else:
|
||||
target_line = "Target: Audio Only (Experimental / Production HOLD)."
|
||||
sampling_line = (
|
||||
"Sampling contract: video zero noise/mask=0 and discarded sampled "
|
||||
"output; audio seeded random noise/mask=1 and adopted sampled output."
|
||||
)
|
||||
output_line = (
|
||||
"Video output: original first-pass physical Video LATENT objects "
|
||||
"returned bit-exact; temporary sampled Video discarded."
|
||||
)
|
||||
report_lines = [
|
||||
"H3 Continuum Targeted Second Pass",
|
||||
target_line,
|
||||
f"Physical groups: {validation['physical_group_count']}.",
|
||||
sampling_line,
|
||||
"RefineSchedule: "
|
||||
f"schema={schedule_contract['schema_version']}, "
|
||||
f"mode={schedule_contract['mode']}, "
|
||||
f"evaluations={schedule_contract['evaluation_count']}, "
|
||||
f"sigma_hash={schedule_contract['sigma_hash']}.",
|
||||
*prepared["warnings"],
|
||||
*group_report_lines,
|
||||
output_line,
|
||||
]
|
||||
if selection_active:
|
||||
report_lines.insert(
|
||||
3,
|
||||
"Selected physical groups: "
|
||||
+ ", ".join(str(index + 1) for index in selected_indices)
|
||||
+ "; non-selected groups were exact object passthrough with no "
|
||||
"conditioning, MODEL clone, Sampling, or seed derivation.",
|
||||
)
|
||||
return output_videos, refined_audios, updated_plan, "\n".join(report_lines)
|
||||
|
||||
|
||||
def run_targeted_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_target: RefineTarget | str | None = MODE_VIDEO_ONLY,
|
||||
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,
|
||||
refine_schedule=None,
|
||||
refine_scope: str | None = SCOPE_ALL,
|
||||
refine_scope_index: int = 1,
|
||||
window_start_sec: float = 0.0,
|
||||
window_end_sec: float = 5.0,
|
||||
) -> tuple[list[dict[str, Any]], list[Any], dict[str, Any], str]:
|
||||
"""Run an implemented target without changing the V3.5 public node."""
|
||||
|
||||
target = resolve_refine_target(refine_target)
|
||||
window: RefineWindow | None = None
|
||||
if isinstance(refine_scope, str) and refine_scope.strip().lower() == MODE_TIME_WINDOW:
|
||||
scope = None
|
||||
window = resolve_refine_window(
|
||||
window_start_sec,
|
||||
window_end_sec,
|
||||
assembly_plan,
|
||||
)
|
||||
selected_group_indices = window.selected_group_indices
|
||||
temporal_windows_by_group = {
|
||||
group.group_index: group for group in window.groups
|
||||
}
|
||||
else:
|
||||
scope = resolve_refine_scope(
|
||||
refine_scope,
|
||||
refine_scope_index,
|
||||
assembly_plan,
|
||||
)
|
||||
selected_group_indices = (
|
||||
None if scope.is_all else scope.selected_group_indices
|
||||
)
|
||||
temporal_windows_by_group = None
|
||||
arguments = dict(
|
||||
model=model,
|
||||
clip=clip,
|
||||
sampler=sampler,
|
||||
sigmas=sigmas,
|
||||
video_latents=video_latents,
|
||||
audio_latents=audio_latents,
|
||||
assembly_plan=assembly_plan,
|
||||
refine_seed=int(refine_seed),
|
||||
refine_context=refine_context,
|
||||
video_vae=video_vae,
|
||||
conditioning_upscale_method=str(conditioning_upscale_method),
|
||||
enable_preview=bool(enable_preview),
|
||||
encode_prompt_fn=encode_prompt_fn,
|
||||
latent_builder=latent_builder,
|
||||
stream_extractor=stream_extractor,
|
||||
clone_model_fn=clone_model_fn,
|
||||
validate_refine_context_fn=validate_refine_context_fn,
|
||||
adapt_group_conditioning_fn=adapt_group_conditioning_fn,
|
||||
refine_schedule=refine_schedule,
|
||||
)
|
||||
if target.mode == MODE_VIDEO_ONLY:
|
||||
result = _run_video_only_groups(
|
||||
target=target,
|
||||
sample_fn=sample_fn,
|
||||
arguments=arguments,
|
||||
selected_group_indices=selected_group_indices,
|
||||
temporal_windows_by_group=temporal_windows_by_group,
|
||||
)
|
||||
elif target.mode == MODE_AUDIO_ONLY:
|
||||
result = _run_sampled_target_groups(
|
||||
target=target,
|
||||
sample_fn=sample_fn,
|
||||
selected_group_indices=selected_group_indices,
|
||||
temporal_windows_by_group=temporal_windows_by_group,
|
||||
**arguments,
|
||||
)
|
||||
elif target.mode == MODE_VIDEO_AUDIO:
|
||||
result = _run_sampled_target_groups(
|
||||
target=target,
|
||||
sample_fn=sample_fn,
|
||||
selected_group_indices=selected_group_indices,
|
||||
temporal_windows_by_group=temporal_windows_by_group,
|
||||
**arguments,
|
||||
)
|
||||
else:
|
||||
raise TargetedRefineExecutionUnavailable(
|
||||
f"refine target {target.mode!r} is unavailable"
|
||||
)
|
||||
|
||||
videos, audios, updated_plan, status = result
|
||||
if window is not None:
|
||||
contract = window.contract
|
||||
window_line = (
|
||||
"Refine Window: timeline=final_visible_output, interval=["
|
||||
f"{contract['effective_start_sec']:.6f}, "
|
||||
f"{contract['effective_end_sec']:.6f}) sec, output_frames="
|
||||
f"{contract['output_frame_range']}, selected_physical_groups="
|
||||
f"{contract['selected_physical_groups']}, continuation_prefix=protected, "
|
||||
"outside_window=mask_zero_then_bit_exact_restore, "
|
||||
"physical_group_atomicity=preserved."
|
||||
)
|
||||
return videos, audios, updated_plan, f"{status}\n{window_line}"
|
||||
assert scope is not None
|
||||
if scope.is_all:
|
||||
return videos, audios, updated_plan, status
|
||||
scope_contract = scope.contract
|
||||
scope_line = (
|
||||
"Refine Scope: "
|
||||
f"mode={scope.mode}, requested_index={scope_contract['requested_index']}, "
|
||||
"selected_physical_groups="
|
||||
f"{list(scope_contract['selected_physical_groups'])}, "
|
||||
"selected_logical_chunks="
|
||||
f"{list(scope_contract['selected_logical_chunks'])}, "
|
||||
f"terminal_expanded={str(scope_contract['terminal_expanded']).lower()}."
|
||||
)
|
||||
return videos, audios, updated_plan, f"{status}\n{scope_line}"
|
||||
+532
-532
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user