AcademiaSD H3 RefMod Encode

This replaces the official MiniMax H3 Reference to Video encode, and it isn't a new API to learn. Same native inputs, same outputs, same ordering - plus one thing: the RefMod characters from AcademiaSD H3 RefMod Character get presented to the text encoder with proper labels, and each label becomes a name you can write in your prompt.

That's the trick. A classic RefMod is appended to the conditioning after text encoding, so Qwen never sees the subject and the prompt has no way to refer to them - <Video 1> is a label the DiT understands, not one the text encoder was given. One RefMod limps along; three characters and the model averages faces and swaps voices. Here the references go into the text side and the DiT side in the same order, so the labels line up. With no characters attached, the conditioning is the official node's.

What it does with your graph

It already carries the references: positive goes to the sampler's positive input and latent straight into the sampler, with no RefMod Apply in between. If you left one in from a classic RefMod workflow, you've paid twice.

The ordering is deliberate. Native ref_image and ref_video come first, so a prompt that hand-writes <Picture 1> keeps working as it did in the official node; then the characters; then native ref_audio last, so an audio reference never sits right before a character's face. It also covers MiniMax H3 Image to Video (FL2VA): first_frame / last_frame become <Picture 1> / <Picture 2> for the text encoder plus keyframes at the first and last frame, and they combine with RefMods - one Encode can serve a Ref2VA branch and another a FL2VA branch fed by the same characters.

The inputs a beginner actually sets

• prompt - write @Anna to cite a character: @Anna becomes <Subject n> Anna, @Anna.voice her <Audio n>, @Anna.video her <Video n>, @Anna.S her Sn. Never hand-write <Audio 1>, <Video 1> or (S1) for a character - those numbers follow character order, so reorder the characters and your prompt is telling the model to swap voices, and it obeys. Native refs are the exception.
• width / height / length - defaults 1344×768 and 124 frames, with a step of 17 on length (H3's frame grid), so those are the shapes you're allowed to ask for, not free integers.
• stack_pictures + stack_pictures_n - how many stills of each RefMod Qwen actually sees. up_to_n (default, N=8) and all give every picture its own block; every_4th_pairs is the old cheap behaviour. More pictures, less bleed, slower encode.
• te_max_side (768 default) - the long side of what Qwen sees. 768 is H3's native resolution; going higher costs time.
• auto_subject_block - writes subject_definitions and retention_analysis into your prompt if they aren't there, already numbered correctly. Leave it unless you write those blocks yourself.
• ref_image_size - match scales each native reference image to the generation's area as the official node does; max takes the short side to 2048, more faithful and slower.

Optional: characters, vae for ref_image/ref_video and for old RefMods with no stored pictures, audio_vae only for ref_audio and ref_video soundtracks - RefMods arrive with their audio encoded - plus first_frame, last_frame, the native ref_image_0…8 / ref_video_0…2 / ref_audio_0…2 slots and h3_mods from ComfyUI-MiniMaxH3Mod.

Outputs: positive (CONDITIONING → sampler), latent (LATENT → sampler), and two strings that exist so you stop guessing. final_prompt is the text actually sent, after alias substitution and the auto-written subject block. reference_map says which label belongs to whom, and it's where the warnings land - a hand-written label contradicting the mapping, or a clause about one subject that cites another character's voice. When voices come out swapped, read reference_map before re-rendering: it usually told you.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/AcademiaSD/comfyui_AcademiaSD
# restart ComfyUI

Or install comfyui_AcademiaSD through ComfyUI Manager; no pip dependencies. You do need a ComfyUI build with native MiniMax H3 (comfy_extras/nodes_minimax_h3) - the pack imports it lazily inside the node functions, so an older install loads the node and only falls over when you queue. RefMod files live in ComfyUI/models/refmods; the H3 weights and the two VAEs are separate downloads this pack doesn't fetch. One note on H3 itself: the weights are under MiniMax's community licence, whose territory excludes the US, EU, UK and South Korea.

Troubleshooting

• "first_frame/last_frame need the video VAE." Literal. Connect the video VAE and re-queue.
• Length too short. Reference videos need at least 5 frames (~0.2 s at 24 fps).
• Native refs only affect the text. Without vae, ref_image/ref_video condition the text encoder but nothing else, exactly as in the official node; reference_map records it with a (!) line rather than failing.
• Voices swapped with two characters. A known experimental limit, not your wiring: two characters with two audio RefMods swapped voices in most configurations in the author's tests - consistently per configuration, not per seed. Several faces work; two speakers in one shot don't yet.