"""UI-backed sequence prompt construction for H3 Continuum.""" from __future__ import annotations import json import re from typing import Any, Mapping import sys REFERENCE_IMAGES_V39_TYPE = "H3_CONTINUUM_REFERENCE_IMAGES_V39" def _continuum_reference_bundle_type(): """Find the upstream H3 bundle class without copying its implementation.""" candidates = [ module for name, module in list(sys.modules.items()) if module is not None and name.endswith(".v3.reference_images_v39") ] try: import importlib candidates.append(importlib.import_module("v3.reference_images_v39")) except Exception: pass for module in candidates: bundle = getattr(module, "ReferenceImagesV39Bundle", None) if bundle is not None: return bundle raise RuntimeError( "DUMAS H3 Sequence Prompt Builder requires the original " "ComfyUI-H3-Continuum reference_images_v39 module to be installed." ) def _visual_refmods(mods): """Return positive-weight visual RefMods in stable picker order.""" result = [] seen = set() for mod, strength in (mods or []): if getattr(mod, "kind", None) == "audio" or float(strength) <= 0: continue key = str(getattr(mod, "path", "") or "") or (getattr(mod, "name", "refmod"), id(mod)) if key in seen: continue seen.add(key) result.append((mod, float(strength))) return result def _refmod_directive(refmods, start_slot, slots=None): """Build conservative default definitions for RefMods in the prompt.""" lines = [] for offset, (mod, _strength) in enumerate(refmods): slot = slots[offset] if slots is not None else start_slot + offset name = str(getattr(mod, "name", "visual reference") or "visual reference").strip() lines.append( f"@R{slot} is the {name} visual reference; preserve its identity, " "appearance, and important physical details when it is used." ) return "\n".join(lines) MAX_CLIPS = 16 DEFAULT_CLIP_SECONDS = 4.0 def _number(value: Any, name: str, *, minimum: float = 0.0) -> float: if isinstance(value, bool): raise ValueError(f"{name} must be a number") try: result = float(value) except (TypeError, ValueError) as exc: raise ValueError(f"{name} must be a number") from exc if result < minimum: raise ValueError(f"{name} must be >= {minimum}") return result def default_sequence(clip_count: int = 2, clip_seconds: float = DEFAULT_CLIP_SECONDS) -> dict[str, Any]: """Return a portable editor state with one slot per clip.""" count = int(clip_count) if count < 1 or count > MAX_CLIPS: raise ValueError(f"clip_count must be between 1 and {MAX_CLIPS}") duration = _number(clip_seconds, "clip_seconds", minimum=0.1) return { "version": 1, "clips": [ { "duration": duration, "slots": [{"start": 0.0, "end": duration, "text": ""}], } for _ in range(count) ], } def normalize_sequence(value: Any, *, clip_count: int, default_seconds: float) -> dict[str, Any]: """Validate and normalize editor JSON without changing user-authored text.""" if isinstance(value, str): try: value = json.loads(value or "{}") except json.JSONDecodeError as exc: raise ValueError(f"timeline_json is not valid JSON: {exc.msg}") from exc if not isinstance(value, Mapping): raise ValueError("timeline_json must be a JSON object") raw_clips = value.get("clips", []) if not isinstance(raw_clips, list): raise ValueError("timeline_json.clips must be a list") count = int(clip_count) if count < 1 or count > MAX_CLIPS: raise ValueError(f"clip_count must be between 1 and {MAX_CLIPS}") fallback_duration = _number(default_seconds, "default_chunk_seconds", minimum=0.1) clips: list[dict[str, Any]] = [] for clip_index in range(count): raw_clip = raw_clips[clip_index] if clip_index < len(raw_clips) else {} if not isinstance(raw_clip, Mapping): raise ValueError(f"clip {clip_index + 1} must be an object") # Continuum projects use one chunk duration for every clip. Older # editor state may still contain per-clip durations; ignore them so # the single node control remains authoritative. duration = fallback_duration raw_slots = raw_clip.get("slots", []) if not isinstance(raw_slots, list): raise ValueError(f"clip {clip_index + 1} slots must be a list") slots: list[dict[str, Any]] = [] for slot_index, raw_slot in enumerate(raw_slots): if not isinstance(raw_slot, Mapping): raise ValueError(f"clip {clip_index + 1} slot {slot_index + 1} must be an object") start = _number(raw_slot.get("start", 0), f"clip {clip_index + 1} slot {slot_index + 1} start") end = _number(raw_slot.get("end", duration), f"clip {clip_index + 1} slot {slot_index + 1} end") if end <= start: raise ValueError(f"clip {clip_index + 1} slot {slot_index + 1} end must be after start") if end > duration + 1e-6: raise ValueError(f"clip {clip_index + 1} slot {slot_index + 1} ends after the clip duration") text = str(raw_slot.get("text", "")).strip() if text: slots.append({"start": start, "end": end, "text": text}) slots.sort(key=lambda slot: (slot["start"], slot["end"])) if slots: # The final shot owns the end of every uniform-duration chunk; # there must be no unassigned tail on the editor track. slots[-1]["end"] = duration clips.append({"duration": duration, "slots": slots}) clips[-1]["enabled"] = bool(raw_clip.get("enabled", True)) return {"version": 1, "clips": clips} def format_sequence_prompt( *, shared_directive: str, sequence: Mapping[str, Any], soundscape: str = "", music: str = "", ) -> str: """Format uniform clips as chunk blocks with relative shot timings. Continuum treats square-bracket ranges as physical/logical chunk markers. Shot timings belong inside each chunk and must therefore use plain ``start-end s:`` lines rather than creating additional Timeline sections. """ directive = str(shared_directive or "").strip() sound = str(soundscape or "").strip() or "N/A" music_text = str(music or "").strip() or "N/A" sections: list[str] = [] cursor = 0.0 for clip in (item for item in sequence["clips"] if item.get("enabled", True)): duration = float(clip["duration"]) chunk_lines = [f"[{cursor:g}-{cursor + duration:g}s]"] if directive: chunk_lines.append(directive) for slot in clip["slots"]: start = float(slot["start"]) end = float(slot["end"]) chunk_lines.append(f"{start:g}-{end:g}s: {slot['text']}") chunk_lines.append(f"overall_soundscape: {sound}") chunk_lines.append(f"non_diegetic_music: {music_text}") sections.append("\n".join(chunk_lines)) cursor += duration return "\n\n".join(sections).strip() class DumasH3SequencePromptBuilder: """Build one Timeline prompt from clip tabs and clip-local time slots.""" DESCRIPTION = ( "DUMAS H3 prompt editor. Define clips and local time slots in the UI; " "the node emits one absolute Timeline prompt for Sequence Prompt." ) CATEGORY = "Dumas/MiniMax H3/Prompt" RETURN_TYPES = ("STRING", "INT", "FLOAT", REFERENCE_IMAGES_V39_TYPE, "H3_REF_MODS", "INT") RETURN_NAMES = ("sequence_prompt", "chunk_count", "chunk_duration", "reference_images", "ref_mods", "refmod_offset") FUNCTION = "build" @classmethod def INPUT_TYPES(cls): state = json.dumps(default_sequence(), separators=(",", ":")) return { "required": { "clip_count": ("INT", {"default": 2, "min": 1, "max": MAX_CLIPS, "step": 1}), "default_chunk_seconds": ("FLOAT", {"default": DEFAULT_CLIP_SECONDS, "min": 0.1, "max": 30.0, "step": 0.1}), "shared_directive": ("STRING", {"default": "", "multiline": True}), "timeline_json": ("STRING", {"default": state, "multiline": True}), "soundscape": ("STRING", {"default": "", "multiline": True}), "music": ("STRING", {"default": "", "multiline": True}), }, "optional": { **{ f"ref_mod_{index}": ("H3_REF_MODS", { "display_name": f"RefMod {index} (@R{index})", "tooltip": f"RefMod socket {index}; use @R{index} in a clip prompt.", }) for index in range(1, 10) }, }, } def build( self, clip_count, default_chunk_seconds, shared_directive, timeline_json, soundscape, music, **kwargs, ): sequence = normalize_sequence( timeline_json, clip_count=int(clip_count), default_seconds=float(default_chunk_seconds), ) # Disabled tabs are deliberately removed before formatting and # routing. The remaining enabled clips become a compact output # sequence, so downstream nodes never receive gaps in chunk indices. active_sequence = { "version": sequence.get("version", 1), "clips": [clip for clip in sequence["clips"] if clip.get("enabled", True)], } selectors = [] routing_directive = str(shared_directive or "").strip() directive = routing_directive sound = str(soundscape or "").strip() or "N/A" music_text = str(music or "").strip() or "N/A" # Each socket is one deterministic @R slot. This avoids trying to # inspect the contents of a chained bundle in the browser and makes # the socket order match the prompt chips exactly. refmods = [] for index in range(1, 10): refmods.extend(_visual_refmods(kwargs.get(f"ref_mod_{index}"))) if len(refmods) > 9: raise ValueError("The prompt builder supports at most nine RefMod slots.") authored_text_by_chunk = [] for clip in active_sequence["clips"]: authored_text_by_chunk.append("\n".join([ routing_directive, *(str(slot.get("text", "")) for slot in clip["slots"]), f"overall_soundscape: {sound}", f"non_diegetic_music: {music_text}", ])) # RefMod slots are defined by socket order, but only referenced slots # should be passed to the sampler. Keep the original @R number in the # generated definition so a sparse use such as @R2 remains accurate. referenced_slots = { index for index in range(1, len(refmods) + 1) if any(re.search(rf"@R{index}(?![A-Za-z0-9_])", text, re.IGNORECASE) for text in authored_text_by_chunk) } selected_refmods = [ refmod for index, refmod in enumerate(refmods, start=1) if index in referenced_slots ] selected_slots = [index for index in range(1, len(refmods) + 1) if index in referenced_slots] generated = _refmod_directive(selected_refmods, 1, selected_slots) if generated: directive = "\n\n".join(part for part in (directive, generated) if part) for reference_index in range(1, 10): chunks = [] for chunk_index, clip in enumerate(active_sequence["clips"], start=1): # Match against the same per-chunk content emitted by # format_sequence_prompt, not only the editable shot lines. text = "\n".join([ routing_directive, *(str(slot.get("text", "")) for slot in clip["slots"]), f"overall_soundscape: {sound}", f"non_diegetic_music: {music_text}", ]) available = reference_index <= len(refmods) if available and re.search( rf"@(R{reference_index}|image{reference_index})(?![A-Za-z0-9_])", text, re.IGNORECASE, ): chunks.append(chunk_index) selectors.append(",".join(map(str, chunks)) or "off") # Keep the typed reference-images output for compatibility with the # Continuum bridge, but it is intentionally empty: this builder now # owns RefMod sockets rather than image sockets. images = (None,) * 9 reference_bundle = _continuum_reference_bundle_type()( images=images, reference_use="Per chunk", selectors=tuple(selectors), ) return ( format_sequence_prompt( shared_directive=directive, sequence=active_sequence, soundscape=soundscape, music=music, ), len(active_sequence["clips"]), float(default_chunk_seconds), reference_bundle, selected_refmods, 0, ) NODE_CLASS_MAPPINGS = {"DumasH3SequencePromptBuilder": DumasH3SequencePromptBuilder} NODE_DISPLAY_NAME_MAPPINGS = { "DumasH3SequencePromptBuilder": "DUMAS H3 Sequence Prompt Builder", }