This project is derived from the MIT-licensed ComfyUI-H3-Multishot work by RiftCast / jlucasmcrell. This repository contains ComfyUI custom-node code. Model files are not bundled. The Advance fork keeps the H3 long-form workflow focused: a small node surface, a unified loader, centralized controls, and a target-clip cache (shot_cache) designed for fast iteration on multi-scene prompts.

A key Advance feature is the Multishot Advance Project. It gives long multi-shot renders a reusable project/session layer: render a sequence, close ComfyUI, reopen the same named project later, edit a target clip, and continue from the first changed target clip while safe earlier cached state is reused. This is meant for iterative video work, not for storing final video outputs.

Example Workflows

Full-Ref: Direct single-reference workflow. It can reuse compatible cached work and resume from the first changed clip, but only during the current ComfyUI session.
Full-Ref With Project: Persistent single-reference workflow. It can be reopened after restarting ComfyUI to continue or modify the sequence from the first changed clip.
Two-Ref: Direct two-reference workflow with 1,1 subject mapping. Compatible cached work can be reused from the first changed clip during the current ComfyUI session.
Two-Ref With Project: Persistent two-reference workflow. It can be loaded after restarting ComfyUI and then continued or modified from the first changed clip.
Video Edit Without Audio: Uses an existing video as the visual structure for changing appearance or action while preserving its camera, timing, environment, and scene continuity; it does not use the source audio as a voice reference.
Video Edit With Voice Timbre: Extends the video-editing workflow with source-audio conditioning so the performer can deliver newly written dialogue while retaining the recognizable vocal character of the voice in the original video (speech may extend due to the source audio).

For complete setup instructions, Prompt Builder field guidance, reference-role examples, dialogue rules, video-editing workflows, and troubleshooting, see the User Guide.

What this node pack is for

According to the official MiniMax-H3 specifications, H3 generates 4–15-second clips at 24 FPS. This pack chains those clips into a longer sequence while keeping the workflow practical for prompt iteration:

write one script with independent target clips separated by ---, using [Shot N] for camera shots/cuts inside each clip;
change a later target clip without re-rendering every earlier compatible clip;
save a named project, close ComfyUI, reopen it later and continue editing from the first changed target clip;
keep model loading, resolution, seed, frames per target clip, sampler, scheduler and target-clip count in one clean workflow lane;
reuse raw cached target-clip state instead of rebuilding unchanged clips from final MP4/video output.

The main goal is iteration speed without changing the generation path for uncached target clips.

Nodes

Core nodes:

| Node | Purpose | | --- | --- | | MultishotAdvanceMultiModelLoader / Multishot Advance Multi Model Loader | Selects one of three H3 diffusion-model slots and exposes one video VAE, one audio VAE, and CLIP. Every resource is lazy-loaded independently only when its corresponding output is connected; inactive model slots and disconnected outputs are not loaded. clip_type defaults to minimax. | | MultishotAdvanceControls / Multishot Advance Controls | Central render controls: aspect ratio, megapixels on H3's fixed 32-pixel grid, frames per target clip (frames_per_shot), seed, steps, sampler, scheduler and target-clip count (shot_count). | | MultishotAdvancePromptBuilder / Multishot Advance Prompt Builder | Builds a reusable target-clip script that can connect directly to the Sampler or pass through the optional Project node. | | MultishotAdvanceAIScenarioDirector / Multishot Advance AI Scenario Director | Experimental and optional local-LLM authoring node. Converts a user scenario, with optional reference analysis, into structured English fields for Prompt Builder. It is not yet feature-complete; see the AI Scenario Director Guide. | | MultishotAdvanceSampler / Multishot Advance Sampler | Main multi-shot sampler with continuity options, prompt splitting and target-clip cache (shot_cache) support. | | MultishotAdvanceVideoSavePlayer / Multishot Advance Video Save/Player | Saves and previews H3 video output with codec/audio controls and embedded workflow metadata. | | MultishotAdvanceProject / Multishot Advance Project | Optional project/session node that lets users save a named multi-clip project, close ComfyUI, reopen it later, edit target clips, and resume rendering from the first changed target clip. |

Support nodes:

| Node | Purpose | | --- | --- | | MultishotAdvanceCartridgeLoader / Multishot Advance Cartridge Loader (.riftcast) | Loads .riftcast character/project cartridges when that format is used. | | MultishotAdvanceMarkdownPreview / Multishot Advance Markdown Preview | Trims leading/trailing whitespace, displays the normalized STRING/TEXT or markdown in the node UI, and passes that normalized value through text_out. Empty input is displayed and returned as _No text received._. | | MultishotAdvanceProjectCachePreview / Multishot Advance Project Cache Preview | Plays compatible cached project clips without sampling, model loading, or VAE decoding. | | MultishotAdvanceSpeedBoosters / Multishot Advance Speed Boosters (optional packs) | Applies optional H3 speed/VRAM helper patches when the matching external packs are installed. |

Multi Model Loader interface

The Multishot Advance Multi Model Loader widgets appear in this order:

model_1_name
model_2_name
model_3_name
video_vae_name
audio_vae_name
clip_name
clip_type
mmproj_name
active_model
activation_reserve_gb

Its outputs appear in this fixed order:

model
video_vae
audio_vae
clip

Loading is controlled by the real output links in the workflow graph:

If model is connected, only the model selected by active_model is loaded. The other two model slots are not loaded.
If model is not connected, no diffusion model is loaded, even though active_model still displays a selected slot.
video_vae, audio_vae, and clip are each loaded only when that exact output is connected.

Loader activation memory reserve

activation_reserve_gb on Multishot Advance Multi Model Loader controls how activation memory is managed for the selected H3 model:

-1 is the default; any negative value keeps ComfyUI's stock memory estimator and disables every H3 reserve wrapper/VBAR override.
0 enables H3 AUTO mode, which sizes the reserve for the actual render shape and payload. Under DynamicVRAM it applies that reserve as a real AIMDO ModelVBAR watermark after model preparation, so excess DiT weights stream instead of consuming the activation pool. It starts conservatively, measures the first normal denoise step, then corrects the VBAR cap for the remaining steps of that same sampling call. This adds no render, sampler step, or second workflow execution. This first implementation does not read or write an AUTO cache.
A positive value pins that many GiB as a manual reserve. A manual value is also enforced through AIMDO VBAR under DynamicVRAM. It is resolution-specific and may perform poorly when reused for another render shape.

Prompt format

The sampler treats --- and [Shot N] as different levels:

--- starts the next independent target video clip and therefore the next sampler execution.
[Shot 1], [Shot 2], [Shot 3] describe camera shots/cuts inside one target clip. Every independent --- clip restarts at [Shot 1].

Throughout this README, target clip means one independently sampled --- block, while in-clip shot means a [Shot N] camera shot/cut inside that block. Public widget/API names such as shot_count, shot_cache and apply_shot_override are kept verbatim even though they operate on target clips.

Plain text is accepted, but each block is normalized into an official H3 contract before conditioning:

[Shot 1] First target clip...
---
[Shot 1] Second target clip...
[Shot 2] At 00:03.000, Cut to a closer view...
---
[Shot 1] Third target clip...

JSON is also accepted:

{"prompts": ["Shot 1 prompt...", "Shot 2 prompt..."]}

When shot_count is higher than the number of prompt blocks, the sampler keeps the existing fallback behavior and reuses the previous prompt for missing target clips.

Base task modes: T2VA, I2VA, FL2VA and L2VA

Base prompts use exactly these three sections:

integrated_multimodal_description:
[Shot 1] ...

overall_soundscape:
...

non_diegetic_music:
N/A

The sampler resolves the task mode from actual keyframe tensors, not from the checkpoint filename, continuity selector or prompt wording:

| Runtime keyframes | Resolved task | Required text behavior | | --- | --- | --- | | no first/last frame | T2VA | no image-alignment preamble | | first_frame only | I2VA | canonical 0.00-second first-frame alignment | | first_frame + last_frame | FL2VA | canonical first/final alignment using the real duration | | last_frame only | L2VA | canonical final-frame alignment using the real duration |

start_image is an identity/reference seed retained for compatibility. It is not a concrete I2VA first frame. Use first_frame and last_frame when the opening or ending composition must be fixed.

Full-reference contract

When real reference items are present, the final prompt uses exactly six sections in this order:

subject_definitions:
...
summary:
[reference generation] ...
retention_analysis:
...
detailed_description:
[Shot 1] ...
overall_soundscape:
...
non_diegetic_music:
N/A

Picture, Video and Audio labels are assigned from the actual runtime reference registry. A manually written label without a matching runtime item is rejected. Identity-only pictures belong to their Subject definition; concrete keyframes, storyboards and video/audio roles receive their own role-appropriate definition and retention marker. Base images= alignment and full-reference minimax_ref_items are never mixed in the same target clip.

global_context: is accepted only as a legacy importer header. Its content is migrated into the official description section and the header is not emitted in a final prompt.

The contracts follow the official MiniMax guides:

Task mode is not continuity

continuity controls how separate generated clips hand state to the next clip: cut, first_frame, flf_chain, context_pin, latent_handoff and related modes affect inter-clip memory, pins or joins. It does not declare T2VA/I2VA/ FL2VA/L2VA. For example, continuity=first_frame can create a generated handoff frame for later clips, while the first target clip remains T2VA unless a real user first_frame tensor is connected.

Structured dialogue and silent clips

Use stable speaker events and exact dialogue tags:

[Shot 1] (S1) turns toward the control panel.
(S1) <d>[English] The signal is stable.</d>

Every complete statement, question, or exclamation inside <d>...</d> must end with ., ?, or ! immediately before </d>.

Do not use quotation marks alone to indicate speech. Text such as a neon sign reading "OPEN ALL NIGHT" remains on-screen text and does not activate voice references. speech_policy=force_silent adds positive observable behavior to the description and soundscape: relaxed closed mouths, visible performance, environmental ambience and physical action sounds. It does not append negative CFG-style prose outside the official sections.

Multishot Advance Prompt Builder

Multishot Advance Prompt Builder is an optional authoring node that can connect directly to the Sampler for session-only work or pass through the Project node for persistent projects. Put the reusable character/subject description, retention rules, global scene notes and visual style in the builder once, then write only the per-clip action beats in shot_script.

Direct wiring without a Project:

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

Persistent wiring through a Project:

Multishot Advance Prompt Builder.project_name_out -> Multishot Advance Project.project_name_override
Multishot Advance Prompt Builder.script_out     -> Multishot Advance Project.script
Multishot Advance Prompt Builder.shot_count_out -> Multishot Advance Project.shot_count
Multishot Advance Prompt Builder.prompt_builder_state -> Multishot Advance Project.prompt_builder_state
Multishot Advance Project.project        -> Multishot Advance Sampler.project
Multishot Advance Project.script_out     -> Multishot Advance Sampler.script
Multishot Advance Project.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

The Builder creates an editable preview, while the Sampler automatically adapts the final prompt to the references and keyframes actually connected at render time.

When a project is rendered with prompt_builder_state connected, project.json also stores the builder's editable fields. After reopening ComfyUI, select the saved project in the Prompt Builder's project_picker; its prompts and settings are restored automatically. The Builder and Project node populate their pickers from existing folders in ComfyUI/user/multishot_advance_projects.

New Prompt Builder authoring helpers are optional and default-safe:

style_preset adds a reusable visual style bank such as cinematic, documentary, anime, product commercial, music video, horror or fashion editorial. Off adds nothing.
camera_preset adds a camera-language bank such as static, slow push-in, handheld follow, tracking, close-up, wide establishing, aerial or arc/orbit. Off leaves camera wording fully manual.
Write each Picture's purpose directly in the existing Prompt Builder fields. Picture and Subject numbers are independent; one Picture may provide explicitly named properties for multiple subjects, objects, animals, the scene, or any body part/anatomical feature. Only the declared properties transfer.
With multiple Pictures and a blank reference_image_groups, unassigned Pictures remain AUTO instead of becoming Subject 1. The groups field remains available as the legacy identity-only shorthand.
reference_image_role sets the general identity, boundary-frame, or storyboard use for the declared Pictures.
prompt_contract records auto, base or full_reference authoring intent. auto selects full-reference only when declared reference items are present; the sampler still validates the result against runtime payloads.
task_mode records T2VA/I2VA/FL2VA/L2VA intent for authoring and project persistence. Actual first_frame/last_frame tensors determine the final base task mode at sampling time.
reference_video_role describes the visual use of a declared video. reference_video_audio_role independently describes its audio use, so an ambience/rhythm/copy source is not accidentally treated as a voice reference.
shot_template does not enable or disable canonical prompt compilation; prompt_contract remains the primary contract selector. With prompt_contract=auto, H3 base sections and H3 reference sections act as legacy compatibility hints for choosing the contract. Director card prefixes an active camera preset with Camera:, while Off makes no template-specific camera change. Every mode still compiles the appropriate canonical base or full-reference sections.
soundscape_prompt and music_prompt always feed the canonical soundscape and non_diegetic_music section bodies for both base and full-reference prompts. Their behavior is independent of shot_template.
report now includes lint warnings/suggestions, and the extra compiled_preview output shows the exact final prompt text as markdown.
Multishot Advance Markdown Preview trims leading/trailing whitespace, displays the normalized STRING/TEXT value, and passes that value through text_out. Empty input becomes _No text received._.

Cartridge wiring

Multishot Advance Cartridge Loader (.riftcast) exposes a typed cartridge_metadata output. Connect it to the Prompt Builder input with the same name. The metadata supplies label-free identity prose and speaker intent; it never hard-codes <Picture N>, <Audio N> or (S1). Connect the cartridge image and voice outputs to the normal sampler reference sockets and set the matching reference counts/roles in the Builder. The sampler's central registry then assigns the real labels from those wired payloads. A voice reference is used only by clips with structured or otherwise explicit foreground speech.

Multishot Advance Video Save/Player

Use this as the final output node for H3 renders:

Multishot Advance Sampler.master_frames -> Multishot Advance Video Save/Player.images
Multishot Advance Sampler.master_audio  -> Multishot Advance Video Save/Player.audio
Multishot Advance Sampler.master_path   -> Multishot Advance Video Save/Player.video_path

source_mode=auto previews master_path when low_ram_master already wrote a file; otherwise it encodes images plus optional audio. Saved videos can embed the ComfyUI prompt/workflow metadata when save_metadata is on.

Multishot Advance Project

Multishot Advance Project is an optional project/session node for long multi-shot H3 workflows. It lets a user save a named project, close ComfyUI, reopen the same project later, edit one target clip, and continue rendering from the first changed target clip instead of starting the whole chain again.

It is not a completed-video archive. Final MP4/video outputs stay in ComfyUI's normal output folders. The project stores editable render state:

the effective target-clip script;
per-target-clip prompt hashes;
sampler/cache compatibility metadata;
reusable per-target-clip cache-v2 artifacts and their verified manifest.

Project folders are created under:

ComfyUI/user/multishot_advance_projects/<readable_name>--<identity_hash>/

The short identity suffix keeps project names that differ only by case, unsupported filename characters or a long shared prefix in separate folders. Use the original project_name in the node; folder naming is automatic. Legacy project folders are no longer supported.

Basic wiring

Add Multishot Advance Project before Multishot Advance Sampler:

Multishot Advance Project.project        -> Multishot Advance Sampler.project
Multishot Advance Project.script_out     -> Multishot Advance Sampler.script
Multishot Advance Project.shot_count_out -> Multishot Advance Sampler.shot_count

Keep the sampler's shot_cache set to use_cache for normal project reuse.

Normal use

Set a stable project_name.
Put the target-clip script into the Project node's script input.
Use mode=load_or_create.
Render normally.
Later, even after closing and reopening ComfyUI, use the same project_name to load the saved project, edit the script, and continue from the first changed target clip.

If target clip 2 changes in a three-clip project, the project marks target clip 2 as dirty. The sampler can restore the safe prefix for target clip 1, then re-render target clips 2 and 3. This is intentional: later target clips depend on earlier memory/context state, so changing target clip 2 must invalidate everything after it.

Project node options

shot_count=0 means use the number of target clips found in the script. If the script already has the exact number of target clips, this is the cleanest setting.
shot_count>0 makes the Project node produce an effective script with exactly that many target clips, using the same repeat/truncate behavior as the sampler.
mode=load_or_create is the normal write/update mode.
mode=read_only loads and reports project state without updating project.json or project cache metadata.
mode=rebuild_project treats the current project as dirty from shot 1, so the next project-aware render starts fresh.
project_picker lists existing project folders. Leave it on (manual / new project_name) when creating a new project; select an existing project to load it without typing the name.
apply_shot_override replaces one effective target-clip prompt before cache invalidation is calculated. In write mode, that edited effective script becomes the saved project script.

If the Project node's script input is empty and a project with the same project_name already exists, the node loads the saved script from project.json. This is the reopen-next-day path.

Project Cache Preview

Connect the Project output to Multishot Advance Project Cache Preview to inspect completed cached clips without sampling, model loading, or VAE decoding:

Multishot Advance Project.project -> Multishot Advance Project Cache Preview.project

prefix_index=0 selects the latest cache prefix compatible with the project's current prompts and sampler identity. The node can play the complete cached prefix or only its final clip. It verifies cache-v2 artifact sizes, SHA-256 checksums, sampler identity, and schema before creating a temporary player copy. Preview is strictly read-only: it does not prune, rewrite, invalidate, or resume the project cache.

Known issues / current workaround

Make speech intent explicit

MiniMax-H3 can invent spoken audio when intent is ambiguous, especially after a clip with a voice reference or when self_anchor_voice is enabled. The sampler keeps voice/timbre references out of conditioning unless the target clip contains structured or otherwise explicit foreground speech.

Write speaking events with stable speaker ids and structured dialogue:

[Shot 1] (S1) examines the receiver.
(S1) <d>[English] I finally found it.</d>

For a deliberately silent clip, choose speech_policy=force_silent. The compiler adds positive visual and soundscape behavior inside the official sections; negative prose such as No dialogue is neither required nor added.

fl2va/ref2va checkpoint warnings are informational

Some continuity/reference modes can print warnings when a workflow uses an fl2va checkpoint where ref2va reference rows would normally be used. These warnings do not stop the workflow. They tell the user that certain reference-bank or identity-reference slots may be ignored by that model variant.

This is not always a bad result in practice. Some user testing in this project has produced unexpectedly good fl2va results in scenes that also print reference-row warnings. This is an experimental observation, not an official guarantee. ref2va remains the recommended choice when the workflow depends on reference-row identity behavior, while fl2va may still be tested when its rendered result is preferable for a particular scene.

Target-clip cache (`shot_cache`)

shot_cache defaults to use_cache.

The cache is meant for lossless iteration. It stores raw target-clip state and checks a stable technical key before reuse. A target clip can be reused only when the settings that affect it still match, including:

model/checkpoint identity;
seed and seed_per_shot behavior;
resolution and frames per target clip (frames_per_shot);
sampler, scheduler and steps;
reference image/audio/video fingerprints;
continuity, pin and bank settings;
prompt prefix and all previous prompts needed for chain state.

Practical result: if a five-clip workflow is already rendered and only target clip 5's prompt changes, compatible earlier clips can be loaded from cache and the run continues from the first changed target clip. The cache does not improve or degrade quality by itself; it avoids recomputing matching work.

Cache-v2 stores one .safetensors artifact per completed target clip plus an atomically published cache_manifest.json. Each artifact contains that target clip's timeline data and its end-of-clip resume checkpoint; earlier decoded frames and latents are not copied into every later prefix. Artifact size, SHA-256, prompt prefix, sampler identity, cache version, and state schema are checked before restore. An invalid or unsupported cache is treated as a recoverable cache miss, so rendering starts from the first required clip instead of crashing the workflow.

Legacy pickle-based .pt shot caches are intentionally not restored. They are not needed by cache-v2; a writable cache-v2 initialization removes those legacy cache artifacts from its resolved cache folder and rebuilds state with a new render.

Without Multishot Advance Project, standalone shot cache files are stored under:

ComfyUI/user/multishot_advance_shot_cache/

With Multishot Advance Project, the reusable prefix cache is stored inside the named project folder instead, so the project owns its editable render state.

Installation

Clone or copy this folder into ComfyUI's custom_nodes directory:

ComfyUI/custom_nodes/ComfyUI-H3-Multishot-Advance/

Restart ComfyUI and look for:

Multishot Advance Multi Model Loader
Multishot Advance Controls
Multishot Advance AI Scenario Director (experimental / optional)
Multishot Advance Prompt Builder
Multishot Advance Sampler
Multishot Advance Project
Multishot Advance Project Cache Preview
Multishot Advance Video Save/Player
Multishot Advance Markdown Preview
Multishot Advance Cartridge Loader (.riftcast)
Multishot Advance Speed Boosters (optional packs)

If you use GGUF H3 checkpoints or GGUF text encoders, install ComfyUI-GGUF. This pack includes the H3 GGUF architecture hook and the apply_gguf_arch_patch.py fallback for installs that need an on-disk patch.

Conditional dependency: Motion Context

The sampler's default continuity=context_pin mode needs ComfyUI-H3-Motion-Context. That pack provides the MiniMaxH3MotionContext node used to pin the previous target clip's raw latent tail into the next target clip.

Motion Context 0.4.x is supported with ComfyUI 0.34.0 or newer. For ComfyUI 0.33.4 or older, use Motion Context 0.3.1, which is also supported for continuity=context_pin. The sampler detects capabilities rather than relying only on version numbers: the legacy release preflights its layout/payload hooks, while 0.4.x verifies the native ComfyUI keyframe-audio layout before target clip 1. A failed check stops the run before any target clip is sampled.

If Motion Context is not installed, switch continuity to a mode that does not need it, such as first_frame, cut, flf_chain, or latent_handoff. ComfyUI-MiniMaxH3-Contex-Loop is a separate companion/fork and is not a replacement for the MiniMaxH3MotionContext node id expected by context_pin.

Notes

Model files are not included.
This is not a drop-in replacement for old upstream workflows. Node names and the workflow layout were intentionally cleaned up.
The older upstream prompt-writer bundle is not bundled here. Use the Advance Prompt Builder or supply a contract-valid prompt; the sampler performs final clip splitting, registry assignment and validation.

Caution

Multishot Advance Project folders and target-clip cache files can become large over time. They store raw reusable render state, not just small text metadata. Users should periodically clean old projects/cache folders manually when they no longer need them.

They are stored under:

ComfyUI/user/multishot_advance_projects/<readable_name>--<identity_hash>/
ComfyUI/user/multishot_advance_shot_cache/

Project-owned cache files are kept inside the corresponding hashed project folder. The standalone shot-cache folder is used by workflows that do not use Multishot Advance Project.

Credits

This project builds on work from:

ComfyUI-H3-Multishot by RiftCast / jlucasmcrell.
ComfyUI-H3-Motion-Context by NikoDemon80, for the Motion Context node used by context_pin.
ComfyUI by comfyanonymous and contributors.
ComfyUI-GGUF by city96, for optional GGUF model support.
MiniMax-H3 by MiniMax. Model files and their licenses are not included in this repository.

License

MIT. See LICENSE.

The original MIT copyright notice is preserved, and Advance modifications are copyright KursatAs.