From 4661648cf5e73d146719e4a883fbad288ab071e3 Mon Sep 17 00:00:00 2001 From: Chris Dumas Date: Thu, 15 Oct 2026 10:18:39 +0000 Subject: [PATCH] Add prompt-driven reference image routing --- README.md | 11 +++++++ prompt_builder.py | 45 +++++++++++++++++++++++++-- tests/test_sequence_prompt_builder.py | 39 ++++++++++++++++++++--- web/sequence_prompt_builder.js | 31 ++++++++++++++++++ 4 files changed, 119 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index f75e137..e403e6c 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,17 @@ outside the clip tabs. The editor state is stored in a serializable JSON widget, making saved workflows portable even when the optional browser panel is unavailable. +The node can also accept up to nine optional reference-image inputs. Each +input has a fixed identity (`Reference Image 1` is always `@R1`, through +`@R9`); when an image is connected, the editor shows a button for inserting +that tag at the current caret position. The fourth output is the same typed +`H3_CONTINUUM_REFERENCE_IMAGES_V39` bundle used by the V3.9 sampler. It is +automatically set to `Per chunk`, and only references explicitly mentioned in +each chunk's prompt are assigned to that chunk. References that are connected +but not mentioned remain off for that chunk. Connect this output directly to +the sampler's `Reference Images (Optional)` input instead of adding a separate +Reference Images helper node. + Example output: ```text diff --git a/prompt_builder.py b/prompt_builder.py index 967be71..e19e2a1 100644 --- a/prompt_builder.py +++ b/prompt_builder.py @@ -3,8 +3,14 @@ from __future__ import annotations import json +import re from typing import Any, Mapping +from .v3.reference_images_v39 import ( + REFERENCE_IMAGES_V39_TYPE, + ReferenceImagesV39Bundle, +) + MAX_CLIPS = 16 DEFAULT_CLIP_SECONDS = 4.0 @@ -135,8 +141,8 @@ class DumasH3SequencePromptBuilder: "the node emits one absolute Timeline prompt for Sequence Prompt." ) CATEGORY = "DUMAS H3/Prompt" - RETURN_TYPES = ("STRING", "INT", "FLOAT") - RETURN_NAMES = ("sequence_prompt", "chunk_count", "chunk_duration") + RETURN_TYPES = ("STRING", "INT", "FLOAT", REFERENCE_IMAGES_V39_TYPE) + RETURN_NAMES = ("sequence_prompt", "chunk_count", "chunk_duration", "reference_images") FUNCTION = "build" @classmethod @@ -150,15 +156,47 @@ class DumasH3SequencePromptBuilder: "timeline_json": ("STRING", {"default": state, "multiline": True}), "soundscape": ("STRING", {"default": "", "multiline": True}), "music": ("STRING", {"default": "", "multiline": True}), + }, + "optional": { + f"reference_image_{index}": ("IMAGE", { + "display_name": f"Reference Image {index} (@R{index})", + "tooltip": f"Fixed Reference Image {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): + 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), ) + selectors = [] + for reference_index in range(1, 10): + tag = f"R{reference_index}" + chunks = [] + for chunk_index, clip in enumerate(sequence["clips"], start=1): + text = "\n".join(str(slot.get("text", "")) for slot in clip["slots"]) + if kwargs.get(f"reference_image_{reference_index}") is not None and re.search( + rf"@{tag}(?![A-Za-z0-9_])", text, re.IGNORECASE + ): + chunks.append(chunk_index) + selectors.append(",".join(map(str, chunks)) or "off") + images = tuple(kwargs.get(f"reference_image_{index}") for index in range(1, 10)) + reference_bundle = ReferenceImagesV39Bundle( + images=images, + reference_use="Per chunk", + selectors=tuple(selectors), + ) return ( format_sequence_prompt( shared_directive=shared_directive, @@ -168,6 +206,7 @@ class DumasH3SequencePromptBuilder: ), len(sequence["clips"]), float(default_chunk_seconds), + reference_bundle, ) diff --git a/tests/test_sequence_prompt_builder.py b/tests/test_sequence_prompt_builder.py index e68e647..49b1181 100644 --- a/tests/test_sequence_prompt_builder.py +++ b/tests/test_sequence_prompt_builder.py @@ -61,11 +61,42 @@ def test_normalizer_rejects_invalid_slot_ranges(bad): normalize_sequence(bad, clip_count=1, default_seconds=4) -def test_node_schema_has_single_string_output_and_serialized_editor_state(): - schema = DumasH3SequencePromptBuilder.INPUT_TYPES()["required"] - assert DumasH3SequencePromptBuilder.RETURN_TYPES == ("STRING", "INT", "FLOAT") +def test_node_schema_has_prompt_outputs_reference_bundle_and_serialized_editor_state(): + inputs = DumasH3SequencePromptBuilder.INPUT_TYPES() + schema = inputs["required"] + assert DumasH3SequencePromptBuilder.RETURN_TYPES == ( + "STRING", "INT", "FLOAT", "H3_CONTINUUM_REFERENCE_IMAGES_V39" + ) + assert "reference_image_1" in inputs["optional"] assert schema["timeline_json"][1]["multiline"] is True result = DumasH3SequencePromptBuilder().build(1, 4, "Directive", json.dumps(default_sequence(1, 4)), "N/A", "N/A") assert result[0].startswith("[0-4s]\nDirective") assert result[0].count("overall_soundscape:") == 1 - assert result[1:] == (1, 4.0) + assert result[1] == 1 + assert result[2] == 4.0 + assert result[3].reference_use == "Per chunk" + assert result[3].selectors == ("off",) * 9 + + +def test_builder_routes_connected_references_only_to_mentioning_chunks(): + value = { + "clips": [ + {"slots": [{"start": 0, "end": 4, "text": "@R1 walks toward @R2."}]}, + {"slots": [{"start": 0, "end": 4, "text": "The camera follows @r2."}]}, + {"slots": [{"start": 0, "end": 4, "text": "A wide shot with no reference."}]}, + ] + } + result = DumasH3SequencePromptBuilder().build( + 3, + 4, + "", + json.dumps(value), + "", + "", + reference_image_1=object(), + reference_image_2=object(), + ) + bundle = result[3] + assert bundle.reference_use == "Per chunk" + assert bundle.selectors == ("1", "1,2", "off", "off", "off", "off", "off", "off", "off") + assert bundle.images[0] is not None and bundle.images[1] is not None diff --git a/web/sequence_prompt_builder.js b/web/sequence_prompt_builder.js index c25d134..c002cbe 100644 --- a/web/sequence_prompt_builder.js +++ b/web/sequence_prompt_builder.js @@ -241,6 +241,31 @@ function configure(node) { shotChips.append(chip); }); panel.append(shotChips); + const referenceRow = el("div"); referenceRow.style.cssText = "display:flex;gap:4px;overflow:hidden;margin:4px 0 7px;align-items:center"; + const connectedReferences = Array.from({ length: 9 }, (_, offset) => offset + 1) + .filter((index) => node.inputs?.some((input) => input.name === `reference_image_${index}` && input.link != null)); + if (connectedReferences.length) { + const referenceLabel = el("span", "Refs:"); referenceLabel.style.cssText = "color:#8fa898;font:10px monospace;margin-right:2px"; referenceRow.append(referenceLabel); + connectedReferences.forEach((index) => { + const button = el("button", `@R${index}`); button.type = "button"; + button.title = `Insert reference image ${index} as @R${index}`; + button.style.cssText = "padding:3px 8px;border:1px solid #4f9bb0;border-radius:4px;background:#172d33;color:#8bd5e7;font:11px monospace;cursor:pointer"; + button.onclick = (event) => { + event.preventDefault(); event.stopPropagation(); + if (!prompt) return; + const start = prompt.selectionStart ?? prompt.value.length; + const end = prompt.selectionEnd ?? start; + const token = `@R${index} `; + prompt.value = prompt.value.slice(0, start) + token + prompt.value.slice(end); + const caret = start + token.length; + prompt.focus(); prompt.setSelectionRange(caret, caret); + promptText = prompt.value; clip.prompt = prompt.value; + syncPrompt(clip, clip.prompt); persistState(); + }; + referenceRow.append(button); + }); + } + panel.append(referenceRow); const promptLabel = el("div", "PROMPT SCRIPT"); promptLabel.style.cssText = "color:#8fa898;font-size:10px;letter-spacing:.08em;margin:4px 0 3px"; panel.append(promptLabel); prompt = el("textarea"); prompt.rows = 10; prompt.value = promptText; prompt.placeholder = "[Shot 1] At 00:00.000, describe the opening action...\n\nType @ at the start of a new line to add the next shot."; prompt.style.cssText = "width:100%;box-sizing:border-box;color:#e8e8e8;background:#171717;border:1px solid #4e4e4e;border-radius:4px;padding:8px;font:12px/1.45 monospace;margin-top:2px;resize:vertical;outline:none"; prompt.oninput = () => { promptText = prompt.value; clip.prompt = prompt.value; }; @@ -303,6 +328,12 @@ function configure(node) { setState(); render(); return result; })(secondsWidget.callback); stateWidget.callback = ((previous) => function(...args) { const result = previous?.apply(this, args); render(); return result; })(stateWidget.callback); + const previousConnections = node.onConnectionsChange; + node.onConnectionsChange = function(...args) { + const result = previousConnections?.apply(this, args); + render(); + return result; + }; node.__dumasSequencePromptBuilder = refresh; refresh(); }