Multishot Advance Prompt Builder

MiniMax H3's full-reference prompt contract is a beast: six official sections in a fixed order - subject_definitions, summary, retention_analysis, detailed_description, overall_soundscape, non_diegetic_music - with labels that must match the actual runtime references or the sampler rejects the whole prompt. Hand-writing that for every shot of a long sequence is a recipe for undefined_subject_reference errors at 11pm. This node exists so you don't.

The idea: define the character once (identity, retention rules, global scene notes, visual style), then write only the per-clip action beats in shot_script. The builder assembles the official contract, lints it, and hands you a compiled_preview to eyeball before anything renders.

How it works

Think of it as the authoring half of the pipeline. It can connect directly to the sampler for session-only work, or pass through the Project node so its editable fields persist across restarts:

Multishot Advance Prompt Builder.script_out       -> Multishot Advance Sampler.script
Multishot Advance Prompt Builder.shot_count_out   -> Multishot Advance Sampler.shot_count
Multishot Advance Prompt Builder.reference_subjects_out -> Multishot Advance Sampler.reference_subjects
Multishot Advance Prompt Builder.compiled_preview -> Multishot Advance Markdown Preview.text

Two intent settings matter up top. prompt_contract (auto/base/full_reference) records authoring intent - auto picks full-reference only when you've declared reference items, but the sampler always validates the result against what's actually connected at render time, so the builder's intent is never trusted blindly. task_mode (auto/T2VA/I2VA/FL2VA/L2VA) likewise records intent; the sampler resolves the real task from actual first_frame/last_frame tensors, not from what you clicked.

The inputs a beginner actually sets

There are a lot of fields, but the ones you'll touch every session:

• subject_name - short name/role for <Subject 1> ("the woman in Picture 1" by default). Keep it short; the detail goes in subject_description.
• subject_description - the actual identity: face, hair, skin, wardrobe, distinctive details. The builder adds the "is" and wraps it - don't write <Subject 1> is yourself.
• retention_focus - what the retention_analysis block tells H3 to preserve across clips. Defaults to identity/face/hair/lighting, which is right for most runs.
• shot_script - the per-clip action beats. One target clip per --- block; real camera cuts inside a clip go as [Shot 1], [Shot 2], with official cut timestamps.
• reference_images + reference_image_groups - how many <Picture N> items the prompt names, and how they group into people. "3,3" means pictures 1-3 are Subject 1 and 4-6 are Subject 2. This must match what you actually wire to the sampler, or you'll get the warning below.
• global_prompt, style_prompt, soundscape_prompt, music_prompt - shared world/continuity notes, cinematography, and the soundscape/music section bodies.

The presets (style_preset, camera_preset, shot_template, speech_policy) are all default-off and genuinely optional. force_silent, for instance, adds positive closed-mouth performance and environmental soundscape wording when you want a deliberately silent clip - it does not append "no dialogue" negative prose, which H3 doesn't want.

Outputs: script_out, shot_count_out, prompt_builder_state (wire to the Project node to persist the builder's fields), project_name_out, reference_subjects_out, report (lint warnings), and compiled_preview - the exact final prompt as markdown.

Installing it

Ships in the pack:

cd ComfyUI/custom_nodes
git clone https://github.com/KursatAs/ComfyUI-H3-Multishot-Advance

Restart ComfyUI. No extra downloads.

Common issues

The classic error is undefined_subject_reference ... <Subject 2>: the script uses Subject 2 but subject_definitions only established Subject 1. Fix by checking reference_images counts, the runtime image batch, reference_image_groups, and that secondary_subjects has one non-empty description line per extra person. A close cousin is a nested section header - if a body field contains something like detailed_description: as text, remove it; the builder generates the wrappers. And the recurring theme across all of it: the builder's declared counts are editable intent, the sampler reads the actual tensors, and when they disagree it falls back to the runtime contract with a warning - recoverable, but align them anyway to avoid surprise label assignments.