H3 Visual Perception Producer

Every captioning node in ComfyUI has the same temptation: if the model isn't there, make something up. H3 Visual Perception Producer refuses. Left on its defaults it declares the fact unavailable and produces a typed non-observation, so a downstream prompt never gets a fabricated detail about a frame nobody looked at.

That's a deliberate posture, and it's the most interesting thing about the node. It is also why beginners think it's broken.

What it's for

H3 reference sets (ref2va) are the case. You hand the model reference images or a video with declared roles, and you write a prompt describing what should carry over. If you're guessing what's in those references, your prompt is describing a different video. Perception is the pack's answer: decode the media on the host, ask a local vision model about selected frames, and let those observations become evidence instead of your memory of the image.

Note the division of labour in the pack. H3 Media Admission Producer admits one host-owned media value and wraps it in a locator-free envelope; that envelope is this node's media input. Perception then describes it. Nothing here generates, samples or writes pixels - it's an evidence producer.

The inputs, and the ones that trip you up

Required:

• media (H3_MEDIA_PRODUCER_RESULT) - from Media Admission Producer. A raw LoadImage output won't do.
• route - a combo, default comfyui_native.
• profile_id - a string, default unqualified.
• device - a combo, default auto.
• cancel_requested - boolean, default false.

Optional: local_service_consent (boolean, false by default) and request (H3_CONTEXT_REQUEST). The node's own description tells you why the second one is there: attach it to sample only the frames kept by reference conditioning, rather than everything in the clip.

Now the part that catches people. The node advertises a specific qualified profile - qwen38_27b_q4_visual_v2 - and that profile has a fixed runtime route: ollama, on auto device, with local_service_consent: true, because frames leave the ComfyUI process for a loopback Ollama service. Leave route on its default comfyui_native while picking that profile and validation stops you with unsupported_route_or_device. That's not an install problem. It's the node telling you the profile and the route disagree.

Whereas leaving profile_id at unqualified is perfectly legal and does nothing: you get a declared-unavailable result. Which brings us to setup.

The one-time host registration

Visual perception needs an operator to register it once, on the host - this is in the pack's host-integration doc, not in a widget. You point it at a trusted absolute Python executable and a private, writable temporary folder:

from pathlib import Path
from comfyui_h3_context.adapters.perception_host import (
    PerceptionHostSettings, configure_perception_host, clear_perception_host,
)

binding = configure_perception_host(PerceptionHostSettings(
    python_executable=Path("C:/operator/perception/.venv/Scripts/python.exe"),
    temporary_root=Path("C:/operator/perception/private-temp"),
    cancelled=lambda: False,  # replace with the host's own cancellation check
))
# teardown: clear_perception_host(binding)

Those paths are deliberately not workflow inputs and never show up in results. If perception isn't configured for that profile, the node reports perception_unconfigured - the README's advice is not to fight it: describe the fact yourself, or put it in as a hard constraint via H3 Hard Constraint Producer. A stated fact you own beats a guessed one.

Setting cancel_requested to true is a third, valid path: you get a typed cancellation result before anything executes, with no error. Useful for testing an orchestration that needs to prove it stops.

Output, and a limitation worth knowing

One output: result (H3_VISUAL_PRODUCER_RESULT). Its consumer in the pack is the optional visual_result input on H3 Full Reference Timeline Producer - and per the README, that node can't be queued in this release; it reports perception_profile_unavailable regardless. So today this is an evidence producer you can wire, run and inspect, on a road that isn't fully open yet. If you were hoping visual perception would magically fill in your ref2va prompt, no: write the description, or state it as a constraint.

Install it

The pack isn't in the Comfy Registry yet, per its README:

cd ComfyUI/custom_nodes
git clone https://github.com/rookiestar28/ComfyUI-MiniMaxH3-Studio.git

Restart ComfyUI, then find it under Add Node → h3_context → perception. The pack installs no Python packages and no models; the vision work happens in your separately managed Ollama/perception environment, which is why the setup contract exists at all. Media features elsewhere in this pack (the clip editor, assembly, rendering) want Windows x64 - but this node's registration step is host configuration, and the pack documents it for operators rather than pretending it's a widget.

Building and validating prompts needs no H3 weights at all, so if you're evaluating the pack before committing 40-odd gigabytes of model, this is one of the nodes you can exercise immediately.