ComfyUI-H3-Cast

ComfyUI-H3-Cast

Persistent character assets for MiniMax H3 in ComfyUI: save a character once (view images + a voice clip + a description), then compose up to three of them — plus scene reference images — straight into H3's native multi-reference pathway, prompting by name instead of hand-numbering <Picture i> / <Audio j> tags.

Two nodes, no new conditioning mechanisms — everything runs through the stock MiniMaxH3ReferenceToVideo node under the hood, so every native knob and fix keeps working.

Nodes

H3 Cast Member (Save/Load)

Create / load / update one character as an on-disk asset.

• Create: connect 1–4 view images, optionally a voice clip (trimmed non-destructively to H3's 2–15 s audio-reference budget), a name and a description → saved permanently.
• Load: pick any saved character from the dropdown. Outputs the cast-member bundle, a preview batch of all saved views, and a report.
• Update: append more views / a voice to an existing member — gated behind a confirm_update toggle so nothing is written by accident.

Storage is a plain folder per character (<comfy user dir>/default/minimax_h3/reference_sheets/<name>--<id>/ — override the root with MINIMAX_H3_REFERENCE_SHEETS_DIR) containing manifest.json + images/*.png + audio/*.wav. Nothing is hidden in the workflow file; assets survive restarts, reinstalls, and graph changes.

MiniMax H3 Cast to Video

Compose the cast into one generation:

• Up to 3 cast members (cast_1..3) + an optional scene_images batch (e.g. renders of a location — one reference slot per frame).
• Fans all views into H3's 9 ref_image slots and voices into its 3 ref_audio slots, writing the intro lines for you with correct tag numbering: <Picture 1>, <Picture 2>: Maya — description. <Audio 1> is Maya's voice.
• Your prompt just refers to characters by name.
• Passes through the native reference knobs (ref_spacing, ref_strength, ref_decay, ref_ramp, ref_image_size, and temporal_stretch where the installed H3 nodes support it — silently skipped otherwise).
• Outputs: positive conditioning + latent (wire to your sampler exactly like the native node), plus final_prompt (the exact text that was sent, so nothing is a black box) and a slot-usage report.

Slot budgeting: 9 image slots are shared by all members and scene images (max_views_per_member controls the split); anything dropped is listed in the report rather than silently ignored.

MiniMax H3 Cast to Video (Extend)

Same idea as Cast to Video above, but for continuing a prior clip instead of a fresh generation: wraps MiniMaxH3VideoExtend instead of MiniMaxH3ReferenceToVideo, since VideoExtend takes a context_latent + raw ref_images directly rather than doing a fresh generation, so MiniMaxH3ReferenceToVideo-based H3CastToVideo doesn't apply to continuations at all.

• Same cast-member / scene_images / scene_description composition as above, plus the continuation-specific inputs (context_latent, context_frames, pin_last_frame, first_frame, etc.) mirroring MiniMaxH3VideoExtend's own.
• Dependent pack: MiniMaxH3VideoExtend isn't part of stock/public MiniMax H3 support -- only kat3ri/ComfyUI's feat/minimax-h3-video-extend branch has it natively. On any other ComfyUI, install ComfyUI-MiniMax-H3-Extend alongside this pack -- it backports the continuation mechanism (see its own README for exactly what's ported vs. what's fork-only, and its verification status). Without either the fork or that pack, this node fails with a clear error naming what's missing, rather than a bare AttributeError. That pack also provides MiniMax H3 Encode AV, which vae-encodes an externally-loaded prior clip (e.g. VHS_LoadVideo) into the context_latent this node needs -- it used to be vendored here, but moved there since it's an extend/continuation concern, not a cast/character one.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/kat3ri/ComfyUI-H3-Cast
# restart ComfyUI -- nodes appear under "MiniMax H3/cast"

Requires a ComfyUI build with the native MiniMax H3 nodes (comfy_extras/nodes_minimax_h3.py). No additional Python dependencies — audio I/O is stdlib WAV. Cast to Video (Extend) additionally needs either kat3ri/ComfyUI's feat/minimax-h3-video-extend branch, or ComfyUI-MiniMax-H3-Extend installed alongside this pack — see that node's section above for both what it needs and where the AV-encode node moved to.

Minimal wiring

H3 Cast Member (Load: "Maya")  ─┐
H3 Cast Member (Load: "Room")  ─┤→ MiniMax H3 Cast to Video ─→ (positive, latent) → BasicGuider / SamplerCustomAdvanced
CLIPLoader / VAELoader(s)      ─┘         ↑ prompt: "Maya sits by the window reading..."

Credits

• The persistent reference-sheet asset library concept — and the on-disk manifest format this pack is deliberately compatible with — come from ethanfel's ComfyUI-MiniMax-H3-Guide (its MiniMaxH3ReferenceSheet node). Assets saved by either pack load in both. The implementation here is written from scratch; if you want the full structured shot/dialogue planning system on top of the same assets, use ethanfel's pack.
• MiniMax H3 support in ComfyUI is the work of the ComfyUI project; this pack is a thin composition layer over its native H3 nodes.