MiniMax H3 Scheduled Ref2VA

The scheduler that compiles your @tags into the right native labels

By ethanfel·Created 17 days ago·Updated about 19 hours ago· 315

clip
vae
audio_vae
reference_schedule
state

positive
latent
compiled_prompt
active_references
schedule_fingerprint

◄clip_index1►

◄clip_count1►

◄prompt►

◄width960►

◄height544►

◄length124►

◄ref_image_sizematch►

◄prompt_compliancestrict►

◄cache_for_upscaletrue►

Scheduled Ref2VA is the payoff node for the whole scheduled-reference family: it takes your chained Picture/Video/Audio schedule, figures out which references are actually active in the current scene, removes the inactive ones, renumbers each media type compactly from 1, and compiles your @tags into the native <Picture N> / <Video N> / <Audio N> labels H3 understands - then runs stock MiniMax H3 Ref2VA. It's the wrapper that makes scene-local references work without you hand-maintaining native numbers.

What it does

The inputs mirror stock Ref2VA plus the schedule machinery. You'll wire:

clip, vae, audio_vae - the H3 text encoder and both VAEs, same as stock Ref2VA.
reference_schedule - the final chain from your scheduled Picture/Video/Audio nodes.
clip_index / clip_count - the current scene and total scenes, both normally from Current Shot.
prompt - the scene prompt, where @hero_face-style aliases get compiled.
width / height / length - generation size, forwarded unchanged to stock Ref2VA; length is the H3-valid raw frame count from Current Shot.
ref_image_size - match limits each picture to generation pixel area; max uses the high-fidelity 2048px-short-edge path.

Then three behavioral switches:

prompt_compliance - strict blocks on unresolved/inactive tags, soft warns and preserves them, disabled passes everything through and caps to stock H3's reference capacity. Start strict; go soft when you're debugging.
cache_for_upscale - saves the active scene's native reference latents and Qwen previews so a deferred upscale can restore them from the checkpoint fingerprint without rewiring the original media. Leave it on unless you're sure you'll never upscale this run.
state - required only when an active Scheduled Video Ref uses sequential timeline mode, which needs exact scene starts.

Outputs: positive conditioning and latent from stock Ref2VA, plus compiled_prompt (exact text sent to H3), active_references (the human-readable mapping like @picture_2 -> <Picture 1> - check it when renumbering surprises you), and schedule_fingerprint.

Install and gotchas

cd ComfyUI/custom_nodes
git clone https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop.git

Restart, or install via ComfyUI Manager under "MiniMax H3 Contex Loop". No pip dependencies; a current ComfyUI with native Add Guide (PR #15439) is expected. Models aren't bundled - mind the MiniMax H3 Community License territory restriction.

The workflow tip: connect the schedule fingerprint into the Plan's generation_fingerprint when all scheduled sources are static, so checkpoints verify cleanly. And remember the scheduler compiles aliases but never inserts meaning - if @voice compiles fine but the scene sounds wrong, the definition belongs in your prompt, not the schedule.

Categoryconditioning/minimax/contex_loop/references/legacy_schedule

Inputs (14)

Name	Type	Default	Description
clip	CLIP		MiniMax H3 text encoder used by stock Ref2VA.
vae	VAE		MiniMax H3 video VAE used to encode active pictures and videos.
audio_vae	VAE		MiniMax H3 audio VAE used to encode active standalone or video-paired audio references.
reference_schedule	H3_REFERENCE_SCHEDULE		Final chain from the scheduled Picture, Video, and Audio reference nodes. For each scene it removes inactive entries, compactly assigns native labels by type, then resolves stable @tags used in the Plan prompt.
clip_index	INT	11–128	Current one-based scene. Connect Current Shot clip_index so the active refs change on each recursive iteration.
clip_count	INT	11–128	Total scenes. Connect Current Shot clip_count to validate schedule bounds.
prompt	STRING		Scene prompt may use optional stable aliases such as @hero_face and @performance. The wrapper replaces them with native H3 labels for the current scene. Example: @picture_2 becomes <Picture 1> if it is the only active picture. Aliases are a scheduler convenience, not required H3 syntax. Native labels remain user-managed. All reference definitions remain visible and editable in the Plan or Prompt Editor.
width	INT	96032–4096	Generation width forwarded unchanged to stock MiniMax H3 Reference to Video.
height	INT	54432–4096	Generation height forwarded unchanged to stock MiniMax H3 Reference to Video.
length	INT	1245–3600	H3-valid raw frame count from Current Shot.
ref_image_size	COMBO	match	Stock Ref2VA picture sizing: match limits each picture to generation pixel area; max uses its high-fidelity 2048px-short-edge path.
stateopt	H3_CHAIN_STATE		Current Shot state. Required only when an active Scheduled Video Ref uses sequential timeline mode; it supplies exact scene starts and Motion Context overlap timing.
prompt_complianceopt	COMBO	strict	strict: compile active @tags and block unknown or inactive tags. soft: compile active tags but warn and preserve unresolved tags. disabled: make every scheduler-authored check non-blocking, pass the prompt unchanged, omit missing/invalid scheduled media (including an empty generated-audio source slice), and keep only stock H3's supported reference capacity. Failures in CLIP, VAE, sampling, or checkpoint execution remain real execution errors.
cache_for_upscaleopt	BOOLEAN	true	Automatically save the active scene's native H3 reference latents, compact Qwen preview frames, and original picture masters needed for target-resolution pass-2 conditioning. Deferred upscale discovers them from the checkpoint fingerprint without reconnecting the original reference media.

Outputs (5)

Name	Type	Description
positive	CONDITIONING	Positive conditioning produced by stock MiniMax H3 Ref2VA.
latent	LATENT	Empty MiniMax H3 AV latent produced by stock Ref2VA.
compiled_prompt	STRING	Exact prompt sent to H3 after stable aliases compile to native labels.
active_references	STRING	Human-readable mapping for this scene, for example @picture_2 -> <Picture 1>. Use it to verify renumbering.
schedule_fingerprint	STRING	Full schedule fingerprint. Connect the schedule node's matching fingerprint to Plan generation_fingerprint when all scheduled sources are static.