MiniMax H3 R2V 桥接器

Here's the annoying shape of reference-to-video work in ComfyUI. One node owns your prompt and reference media - the Universal prompt optimizer, which rewrites a half-formed idea into H3's structured prompt and holds nine image slots plus video and audio. Another owns the generation: AIMixer's MiniMaxH3Director. Neither will accept the other's objects.

UniversalR2VBridge (on canvas: MiniMax H3 R2V 桥接器) is the twenty-line adapter between them. It takes the optimizer's prompt and media bundle and emits a single MMX_DIR_GROUP dict in exactly the shape the Director's r2v_groups input expects.

What it actually builds

The source is about as honest as a node gets. execute pulls images, videos, audios and video_audios out of the bundle and returns one dict:

• version: 1, family: "r2v", kind: "r2v"
• prompt - your text, stripped
• duration_sec
• first_frame and last_frame, hardcoded to None
• ref_images, ref_videos, ref_video_audios, ref_audios

That's it. The code comments say it mirrors the Director's own external_groups.pack_r2v_group, and the Director's normalize_groups_list wraps a single dict into [dict] - which is why one bridge equals one r2v group, and why you stack them for several.

It needs to exist because H3's prompt format isn't tag soup you can improvise - it expects structure, and the optimizer's job is producing that from plain language, with a local GGUF model or an online API set in the pack's ⚙ panel. Once the text is right, something still has to carry it across the pack boundary.

Inputs and output

Three inputs, only two of which matter in practice.

prompt is multiline and flagged as a dynamic-prompts input, so you can convert the widget to a socket and wire the optimizer's prompt output straight in. duration_sec runs 0.1 to 30 in 0.1 steps - the per-group length, and 30 is a hard ceiling here even before H3's own clip limit gets a say. media_bundle is optional; unconnected, you get a prompt-only group with zero references.

Output is one r2v_group of type MMX_DIR_GROUP, straight into the Director's r2v_groups socket. That's the whole graph.

Install (and the part nobody mentions)

cd ComfyUI/custom_nodes
git clone https://github.com/aihaipan/ComfyUI-Universal_Prompt_Optimizer.git

Then restart. No requirements.txt, no model downloads, no compiled anything - pyproject.toml lists aiohttp and nothing else, which ComfyUI already ships. The pack uses the newer backend authoring API (from comfy_api.latest import ComfyExtension, io), so it wants a reasonably current ComfyUI; on an older build you get an empty category instead of an error.

The part nobody mentions: this node is useless on its own. The consumer is AIMixer's ComfyUI_MiniMaxH3_Director, a separate repo that this pack does not install and does not depend on in its metadata. Install both. And then set the Director's task_type to r2v - the README says it, the node's own description says it, and it's the single most common reason someone wires this up and gets silent single-image behaviour instead of reference-driven video.

Where people get burned

You wired images and the Director sees an empty group. The bridge copies bundle["images"] and bundle["audios"] - the loaded values, not the paths. If the optimizer couldn't decode a file, the slot just doesn't exist in the bundle and the bridge has nothing to forward. Check the console after a run: the node logs MiniMax H3 R2V bridge: N image(s), M audio(s), prompt=X chars. If N is 0, the problem is upstream.

Reference audio that doesn't come along. The optimizer packs videos as path-plus-metadata dicts and never populates video_audios, so your reference video's audio track doesn't ride into the group. If the Director needs it, that's a Director-side input.

Audio decode failures are quiet. The optimizer's loader falls back to nothing when a file trips the audio loader, which means a FLAC or an awkward container can leave you with a prompt and images but an empty ref_audios - and if you were counting on 参考音色-style voice cloning from that reference, there's nothing to clone. Re-encode to WAV if you suspect it.

First and last frame look broken because they are. Both are None by construction. This bridge is references-only; frame locking lives on the Director.

A duration_sec of 30 won't give you 30 seconds. H3 emits short clips; 30 is this schema's limit, not the model's. The finite-segment path exists because you can't get there in one group.

Old workflows load red. The bundled 01-director-full-r2v example still references MiniMaxH3R2VBridgeGH, a node id that no longer exists after the rename - and its links use the legacy GH_MEDIA_BUNDLE types. Load it as a reference, then place the current bridge by hand.

If you're building the three-node flow the README pushes (loader → Director Max → save video), you probably don't need this node - the pack's own Director nodes take the prompt and bundle directly. This bridge is for the older AIMixer pipeline, where two packs genuinely have to talk.