ComfyUI-H3-Multishot-Advance

ComfyUI-H3-Multishot-Advance

Focused MiniMax-H3 multi-shot video nodes for ComfyUI.

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 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 shot, and continue from the first changed shot 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 shot without re-rendering every earlier compatible shot;
• save a named project, close ComfyUI, reopen it later and continue editing from the first changed shot;
• keep model loading, resolution, seed, frame count, sampler and scheduler in one clean workflow lane;
• reuse raw cached shot state instead of rebuilding unchanged clips from final MP4/video output.

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

Nodes

Core nodes:

| Node | Purpose | | --- | --- | | MultishotAdvanceMultiModelLoader / Multishot Advance Multi Model Loader | Loads the H3 diffusion model, CLIP/text encoder, video VAE and audio VAE from one node. clip_type defaults to minimax. | | MultishotAdvanceControls / Multishot Advance Controls | Central render controls: aspect ratio, megapixels, snap multiple, frames per shot, seed, steps, sampler, scheduler and shot count. | | MultishotAdvancePromptBuilder / Multishot Advance Prompt Builder | Builds a reusable multi-shot script that can connect directly to the Sampler or pass through the optional Project node. | | MultishotAdvanceSampler / Multishot Advance Sampler | Main multi-shot sampler with continuity options, prompt splitting and 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-shot project, close ComfyUI, reopen it later, edit shots, and resume rendering from the first changed shot. |

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 | Displays connected STRING/TEXT or markdown in the node UI and passes the same text through from text_out. | | 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. |

Loader activation memory reserve

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

• -1 is the default; any negative value keeps ComfyUI's stock memory estimator and disables the H3 reserve override.
• 0 enables H3 AUTO mode, which sizes the reserve for the actual render shape and refines its estimate from measured peak usage.
• A positive value pins that many GiB as a manual reserve. A manual value 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].

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 shots.

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:

• MiniMax-H3 base prompt writing guide
• MiniMax-H3 full-reference prompt writing guide

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.
• reference_image_role controls how <Picture 1> is used: off adds no extra role, identity_reference supplies identity, first_frame_anchor or last_frame_anchor fixes the corresponding boundary, storyboard_reference supplies composition guidance, and identity + first_frame_anchor combines identity with the opening-frame anchor.
• 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 displays any connected STRING/TEXT value in its node UI and passes the same text through from text_out.

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 shot, and continue rendering from the first changed shot 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 shot script;
• per-shot prompt hashes;
• sampler/cache compatibility metadata;
• reusable per-shot 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

1. Set a stable project_name.
2. Put the shot script into the Project node's script input.
3. Use mode=load_or_create.
4. Render normally.
5. 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 shot.

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

Project node options

• shot_count=0 means use the number of shots found in the script. If the script already has the exact number of shots, this is the cleanest setting.
• shot_count>0 makes the Project node produce an effective script with exactly that many shots, 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 shot 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.

Shot cache

shot_cache defaults to use_cache.

The cache is meant for lossless iteration. It stores raw shot state and checks a stable technical key before reuse. A shot 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 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-shot workflow is already rendered and only shot 5's prompt changes, compatible earlier shots can be loaded from cache and the run continues from the first changed shot. The cache does not improve or degrade quality by itself; it avoids recomputing matching work.

Cache-v2 stores one .safetensors artifact per completed shot plus an atomically published cache_manifest.json. Each artifact contains that shot's timeline data and its end-of-shot 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 Prompt Builder
• Multishot Advance Sampler
• Multishot Advance Project
• Multishot Advance Project Cache Preview
• Multishot Advance Video Save/Player

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 shot's raw latent tail into the next shot.

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 shot 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.

The original upstream distribution also referenced ComfyUI_JoyAI_Echo_GGUF_Nodes by RealRebelAI for LLM prompt writing. This Advance repository does not bundle or depend on that package.

License

MIT. See LICENSE.

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