ComfyUI-MiniMaxH3-Timed-References

<p align="center"> <img src="assets/icon.svg" alt="MiniMax H3 Timed References" width="680"> </p>

MiniMax H3 Timed References for ComfyUI

Add lightweight image or video references at specific times in a MiniMax H3 video.

The pack contains two nodes:

Add Timed Image Reference for MiniMax H3

It sits on the H3 CLIP line and presents an image to Qwen at the selected timestamp. The image is used for semantic guidance only: it is not VAE-encoded and does not consume a native H3 reference slot.

Add Timed Video Reference for MiniMax H3 (Experimental)

This node presents selected frames from a short video to Qwen. Connect core Load Video to its source_video input for the lightest path: the source remains file-backed, only selected frames are materialized as tensors, and real presentation timestamps are preserved. A decoded IMAGE batch remains available as a constant-frame-rate compatibility input.

Install

In ComfyUI Manager, search for MiniMax H3 Timed References and click Install.

Or clone the repository into ComfyUI/custom_nodes/:

cd ComfyUI/custom_nodes
git clone https://github.com/ethanfel/ComfyUI-MiniMaxH3-Timed-References.git

Restart ComfyUI.

Use

Place the node between the MiniMax H3 CLIP loader and the core MiniMax H3 Reference to Video node:

H3 CLIP
  -> Add Timed Image Reference
  -> MiniMax H3 Reference to Video

Then:

1. Connect an image.
2. Set its target time in seconds.
3. Give it a short tag such as red_car.
4. Write #red_car in the Ref2VA prompt.

Chain more nodes to add more images:

H3 CLIP
  -> Timed Reference: red_car at 0.0s
  -> Timed Reference: blue_car at 0.0s
  -> Core H3 Ref2VA

Each tag must be unique. Keep every timestamp within the generated video's duration.

Reference sizes range from 64 to 1280, plus source. 64 is Qwen's practical aligned floor in this H3 path, but it carries very little visual detail. Start around 256–512; use the smaller choices only when the subject remains recognizable and saving vision tokens matters.

How it works

At tokenization time the node:

• finds the next available H3 <Video N> reference number;
• replaces your #tag with that label;
• presents the image or sampled video to Qwen at the chosen timestamp;
• preserves timed-reference labels to six decimal places instead of rounding them to tenths of a second.

Native H3 images, videos, and audio can still be connected normally. Timed references do not enter minimax_refs and do not use native reference slots.

The patch activates only through ComfyUI's core MiniMax H3 Reference to Video tokenizer path. Other CLIP workflows pass through unchanged.

Experimental video references

Connect core Load Video directly to source_video, then choose where the clip begins on the generated timeline. This route reads presentation timestamps from the media stream, so variable-frame-rate clips keep their actual timing. The clip must be 15 seconds or shorter; use core Trim Video first when needed.

analysis_fps=2 matches core H3 behavior. Higher rates can be tested up to the source video's average frame rate. Every increase adds vision tokens and memory use, and rates above the source rate provide no new information.

For an older loader that outputs an IMAGE batch, connect video_frames and enter its loaded frame rate in source_fps. That input has no per-frame timing metadata, so the node necessarily treats it as constant-rate. Like the image node, video references are semantic conditioning only: they are not VAE-encoded and do not consume a native H3 video-reference slot.

Example workflow

The repository includes:

example_workflows/MiniMax H3 Timed References - Street Race Comparison.json

It compares the same 10-second street race in two branches:

• both cars described entirely with text;
• both cars supplied through #red_car and #blue_car timed references.

Copy the two JPG files from example_workflows/assets/ into ComfyUI/input/ before loading the workflow. Asset credits are in example_workflows/assets/ATTRIBUTION.md.

License

Copyright (C) 2026 Ethanfel. The code is licensed under the GNU General Public License v3.0 only; see LICENSE. The bundled example images retain their separate CC BY-SA 4.0 license.