Create H3 RefMod Master
One node to extract a character's look and voice
- refs_image
- refs_video
- refs_bundle
- mask
- av_encoder
- vae
- audio
- audio_vae
- mods
- details
Extract H3 RefMod Master is the pack's "one character extractor": appearance and/or audio in a single node, one bundle out, one run to save a whole character reference. It's basically the regular Extract H3 RefMod with the audio extractor folded in and orchestrated, and the reason it exists is workflow ergonomics - when you're building a reference library for a recurring character you don't want to chase two separate save paths and stitch the results together yourself.
A caveat up front, because the naming invites the wrong hope: this is not joint identity-and-voice training. It extracts appearance and audio references and hands them back as one bundle; the README is explicit that it doesn't guarantee audiovisual synchronization or a matched voice. And given the pack's own known limitation on speaker-identity transfer, treat the audio half as a music/ambience reference today and keep your expectations there.
How it works
The node merges the visual extractor's full control set with audio inputs, then runs sequentially: visual references first (using the H3 video VAE on vae), then audio (using the H3 audio VAE - the 32 kHz codec - on audio_vae). Either modality can be omitted, so it works as a fancier visual extractor or a pure audio one. Saves land as two independent files under the same name: with name=hero and subfolder=characters you get characters/hero_visual.safetensors and characters/hero_audio.safetensors, which you then pick up together in Load H3 RefMods to rebuild the bundle after a restart.
Saving is all-or-nothing by design. The visual extractor's internal save is deferred; Master holds both extractions in memory, checks the combined budget, and only then writes files (atomically) - a failed extraction or budget overflow saves neither. The final Created/Replaced messages show the real paths. Flip save=False and Master returns the bundle without writing anything.
Inputs that matter
Everything from the plain extractor is here - mode (training vs encode), ref_resolution, pool dials, identity, merge, motion_only, max_tokens, mask - plus the audio half:
- audio - connect an AUDIO source directly. Video-frame inputs don't implicitly carry a track; wire the source loader's AUDIO output separately if the clip has one.
- audio_vae - the H3 audio VAE, separate socket from the visual one. Forgetting it on an audio extraction is the classic error; Master raises if audio is connected without it.
- audio_max_seconds - initial duration of the clip (default 30s).
- audio_budget_policy -
error(default) raises on token overflow;truncatekeeps a contiguous prefix instead of resampling speech/music in latent time. - max_total_tokens - combined visual + audio budget; 0 disables this extra limit.
Outputs are mods (feed to Apply H3 RefMod, or Inspect) and details - a string with actual paths and token totals.
Install
ComfyUI Manager (search "ComfyUI-MiniMaxH3Mod") or:
cd ComfyUI/custom_nodes
git clone https://github.com/Luisacaotica/ComfyUI-MiniMaxH3Mod
Restart. Deps are light. You need the H3 weights plus both VAEs working in a current ComfyUI - video VAE for the visual half, the 32 kHz audio VAE for audio - and remember H3's community licence excludes the US, EU, UK and Korea.
Common issues
Beyond the voice-transfer limitation (documented in the README as not working reliably), the practical traps are: connecting the wrong VAE to audio_vae, expecting a video's frames to bring their soundtrack along, and double-saving - Master already saves, so if you also run it into Save H3 RefMods, set save=False on Master. And keep voices in separate files: mixing two voices in one audio mod muddies both, since you can't fade one without the other.
Inputs (31)
| Name | Type | Default | Description |
|---|---|---|---|
| name | STRING | my_concept | Saved mod name (appears in the Load H3 RefMods dropdown after a reload). |
| mode | COMBO | Compressed Reference | Compressed Reference pools the latent and optionally refines its reconstruction. Full Reference stores the VAE encode, subject to resolution/frame/token limits. Neither mode trains H3 weights. Legacy mode values remain accepted. |
| concept_type | COMBO | generic | Metadata only; does not select a learning algorithm. What this mod represents — 'identity' (a specific person/character), 'pose_motion' (a pose/dance/gesture/camera move), 'clothing', 'background', 'style', or 'generic'. Stored in the mod and used by the loaders' prompt_hint output (merges concept_type + description into a string you can concat onto your CLIP prompt). 'identity' in training mode with a small grid also triggers a warning nudging you toward 'encode' mode or a bigger grid — pooling is lossy in exactly the way that destroys facial identity. |
| background_retention | FLOAT | 0.000–1 | Only used when 'mask' is connected. Floor weight for the region outside the mask: 0 = that region collapses to a heavily blurred copy of itself (kills specific structure like a skyline/treeline while staying smooth and in-distribution), 1 = mask has no effect. Middle values (0.3-0.6) partially blur instead of fully. |
| ref_resolution | INT | 1024256–2048 | Target short edge in px (downscale only, never upscale), applied to BOTH modes: 'encode' stores at that res, 'training' encodes smaller too (it pools to a grid anyway, so native-res encoding is wasted compute — this is the main speed dial for training mode). 1024 is a good default; 512 halves encode cost; 2048 = official max fidelity, 4x the tokens of 1024. |
| pool_h | INT | 162–64 | Pooled mode: spatial latent grid after pooling. The grid is auto-fit to the source's aspect ratio (long edge = max of the two dials, other edge derived), so a portrait person isn't squished into a square grid (the 'fat/chubby' distortion). Square sources keep the exact dial value. 16x16 = 64 tokens/frame (concept sweet spot); 32x32 = 256; 64x64 = 1024, full-mode parity for identity. |
| pool_w | INT | 162–64 | Pooled mode: grid width (long edge if the source is wider than tall). |
| latent_frames | INT | 161–2147483647 | Per-video temporal limit. Encode mode samples up to this many source frames before VAE encoding and causal 4k+1 trimming; training mode pools to up to this many latent frames after encoding. Set at least the source frame count to avoid encode-mode sampling. Images use 1. Higher values increase memory and token cost; max_tokens can still reduce the result. |
| identity | INT | 5000–2000 | Compressed Reference only: optimization steps to reduce latent reconstruction error. 0 uses pooling alone. This is not identity strength or model training. |
| merge | BOOLEAN | false | Merge mode (training only): instead of stacking each ref's own pooled latent, optimize ONE shared grid against every full encode jointly — the result lands on what's COMMON across all the views (structure, motion, identity) rather than any single shot's framing/background. Ideal for a collection: many angles of a subject, a folder of similar clips -> one tiny consensus mod, one ref block's worth of tokens. Keeps every full encode in VRAM during refinement. Off = stack (each ref keeps its own frames). Ignored when mode='encode'. |
| motion_only | BOOLEAN | false | EXPERIMENTAL — extract only what MOVES. Video refs are converted to per-frame temporal differences (|f[t+1] - f[t]|, normalized) before encoding, so the mod carries where/how things move and the static appearance (background, the lineart look, an outfit) never enters the latent. For a lineart animation this keeps the moving lines and drops the static drawing. Needs video refs — a still has no motion, so image refs keep their appearance (warned). Training mode only; the ref channel is content-based, so treat the result as a soft motion guide, not a ControlNet. Combines with 'merge'. |
| multiplier | INT | 11–10 | Data multiplier: repeat the extracted ref N times along time so a short video/GIF (few tokens) isn't drowned out by the main video's tokens. Each repeat duplicates the same latent frames, so attention weight on the ref scales roughly with N. 1 = no repeat; file size grows with N. |
| max_tokens | INT | 51200–2147483647 | Hard cap on the total tokens the mod injects (0 = no cap; 5120 is a good performance default). If the stacked refs exceed it, near-duplicate latent frames are dropped first (video refs are full of frames that differ only by noise — each one still costs a token per spatial patch in every block), then frames are resampled to fit. The cap is honored after the multiplier. Lower latent_frames/ref_resolution instead to avoid wasting encode work: ~23K tokens = one 1024px encode-mode video ref at 16 frames. |
| description | STRING | Optional text describing the concept (e.g. 'a ginger woman with messy hair', 'an animation style', 'handheld camera movement'). Stored in the mod and printed in the info block — documentation only, no wiring. | |
| save | BOOLEAN | true | Save the mod to mods/ so Load H3 RefMods can pick it up later. |
| audio_max_seconds | FLOAT | 30.000.025–600 | — |
| audio_max_tokens | INT | 51200–2147483647 | — |
| audio_budget_policy | COMBO | error | 2 options: error, truncate |
| audio_concept_type | COMBO | voice | 5 options: voice, singing, music_style, sound_fx, ambience |
| max_total_tokens | INT | 00–1048576 | Combined visual and audio budget. 0 disables this extra limit. |
| refs_imageopt | COMFY_AUTOGROW_V3 | — | |
| refs_videoopt | COMFY_AUTOGROW_V3 | — | |
| refs_bundleopt | H3_REF_LIST | All images/videos from a Load H3 RefMod Folder node, appended after the autogrow refs (bulk extraction). | |
| maskopt | MASK | Subject mask (or a batch, one per reference in order: images then videos) marking what to keep at full weight. Everything outside the mask collapses toward a heavily blurred copy of itself per spatial cell (stays in-distribution — a flat noise-mix here decodes as a woven/static texture instead of 'nothing'), controlled by background_retention. Fixes 'encode' mode pulling in a background/style that doesn't belong to the subject. A single mask broadcasts to every reference; a batch must match the reference count. | |
| av_encoderopt | MINIMAX_H3_AV_ENCODER | Legacy MiniMax-H3 VAERef. Loads its video checkpoint using the native ComfyUI VAE; prefer vae to share an already loaded VAE. | |
| vaeopt | VAE | Standard VAE, used when av_encoder is not connected. | |
| extraction_presetopt | COMBO | manual | manual preserves controls. identity_encode: Full Reference, resolution=1024, steps=0, merge/motion_only off. style_experimental: Compressed Reference, pool=8x8, steps=150, merge/motion_only off. motion_sequence: Compressed Reference, pool=16x16, merge/motion_only off; preserves frame limit and Refinement Steps. It keeps appearance, not frame differences. |
| subfolderopt | STRING | Optional folder inside models/refmods, for example celebs or voices. | |
| audioopt | AUDIO | — | |
| audio_vaeopt | VAE | MiniMax H3 audio VAE. The visual vae socket remains separate. | |
| budget_policyopt | COMBO | truncate | On max_tokens overflow: truncate uses the existing frame reduction; error stops without saving. 0 max_tokens disables the cap. |
Outputs (2)
| Name | Type | Description |
|---|---|---|
| mods | H3_REF_MODS | — |
| details | STRING | — |