📦 Subject Unpack

Subject Manager is the library; Subject Unpack is where the library gets handed to the model. You feed it the SUBJECT_DATA JSON from SubjectManagerNode, and it tears it apart into actual media tensors and a finished prompt - up to 8 images, 2 audio tracks, 2 videos (each as frames plus audio), and one combined text prompt. Everything the manager lets you organize, this node lets you wire in.

If you've used reference-conditioned image models, the shape will feel familiar - but this is built for MiniMax H3, the omni-modal video model that consumes images, audio, video, and text as one unified context. The prompt side is where this gets interesting: each subject card carries prompt templates with tags like <Picture 1> and <Subject 1>, and this node renumbers them into global slots and stitches them together.

How it works

The unpack() pass walks the sections in your library, then every card marked selected or always-on (⭐), and for each one:

• loads its active images into tensors, proportionally resized to image_max_megapixel - no cropping, just a scale-down;
• loads up to 2 audio files, applying your trim handles and capping at max_duration;
• loads up to 2 videos, extracting frames at your fps target and downscaling frames to video_max_megapixel, plus the synchronized audio;
• runs the card's prompt through adapt_prompt_references, which rewrites <Picture N>, <Audio N>, <Video N> to the correct global slot numbers, renumbers subjects, and drops any line that references media this card doesn't actually have active.

That last bit is the genuinely smart part. If a card's picture references image 3 but only one image is enabled, the whole line gets dropped instead of producing a dangling tag the model misreads.

The inputs that matter

• subject_data (optional) - the JSON from the Manager node. Leave it disconnected and you get an empty default library.
• fps - video frame sampling rate, default 24.
• image_max_megapixel - cap for still images (default 1.0 MP). Proportional, so no aspect-ratio surprise.
• video_max_megapixel - cap for video frames (default 0.5 MP). This is the memory control knob; drop it if your H3 pass is VRAM-thirsty.
• max_duration - max seconds extracted from audio/video, default 15.
• prefix - a multiline string prepended to the final prompt. The default subject_definitions: \n matches H3's expected structure - leave it unless you know what you're changing.

The outputs and where they go

image_1 through image_8 (IMAGE), audio_1/audio_2 (AUDIO), video_1_images + video_1_audio and video_2_images + video_2_audio, and prompt (STRING). Route the images/audio/video into your H3 multimodal conditioning and the prompt into your text encode, then queue.

Gotchas

• Unfilled slots output None. Many downstream nodes hard-error on a None IMAGE input, so only wire the outputs you actually populated. This is the most common "it broke" report.
• The media decoders are best-effort. Audio tries torchaudio, then PyAV, then soundfile; video tries PyAV, then OpenCV. All are optional imports - if none are installed, you silently get empty outputs. On a default ComfyUI install PyAV and torchaudio are usually present because the video ecosystem needs them; if your video outputs come back empty, that's the first thing to check.
• The H3 license caveat. This pack is built for a model whose community license geofences out the US, EU, UK, and Korea. The node works fine, but if you're in one of those regions, running local H3 weights is a licensing question you should have settled before building the library, not after.