H3 Canonicalize References

The H3 Canonicalize References node is the pack's file clerk. After Qwen analyzes your reference images - one Initial picture, one or more Cast pictures, or both - each analysis comes back as its own JSON blob. This node collects them all, figures out which is which, renumbers every person into a single canonical <Subject 1>, <Subject 2> list, and hands the Authoring Editor one clean draft. You'll almost never wire it manually; in the bundled MiniMax H3 workflows it sits between the Qwen request nodes and the editor.

It exists because reference-driven video prompting has a numbering problem, not a vision problem. Your Initial photo and three Cast photos are analyzed separately, and the pack's H3 prompt protocol needs subjects to be stable global identifiers. "The woman in the red dress" has to become <Subject 2> everywhere, in every shot, or the model loses track of who you mean - the same subject-attribution failure the captioning world keeps bumping into. Canonicalize is where that consistency gets enforced.

How it works

The node has one mode switch and one number:

• mode - i2va (image-to-video, one Initial frame only) or ref2va (reference-to-video, the default). Ref2VA is the full workflow: Initial and/or Cast references author a video where the model retains your subjects.
• initial_picture_number - where your Initial picture sits in the lineup, 1–9, with 0 meaning "no Initial picture". Cast results are counted in Picture order excluding the Initial, which is the tooltip's way of saying the cast numbering shifts if your Initial isn't first. Set it wrong and you'll get a validation error, not a silent mess.

It takes initial_json and cast_json from the Qwen request nodes. The output is a single authoring_draft_json.

Behind the scenes it's strict in the way that makes debugging painless:

• I2VA requires exactly one Initial result and rejects Cast results outright.
• Ref2VA allows at most one Initial result and needs at least one Initial or Cast to do anything.
• If you promised three cast results but only two arrived, it raises "not enough Cast Qwen results for reference layout" instead of guessing.

The renumbering trick

The Initial analyzer returns its people as local subject_0, subject_1 names, because it doesn't know yet where it sits in the lineup. Canonicalize rewrites those into the global <Subject N> labels in Picture order - a subject_0 that turns out to be Picture 3 becomes <Subject 5> if there were two cast people before it. Then it walks every mention in the Initial description and rewrites those references too, so nothing dangles. Cast pictures are simpler: each contributes exactly one subject, per the one-person-per-Cast contract.

Install and gotchas

Install the whole pack through ComfyUI Manager (search "H3 Scribe") or git clone https://github.com/last-git/h3_scribe into ComfyUI/custom_nodes, then restart. You also need ComfyUI_Simple_Qwen3-VL-gguf and the Qwen3-VL GGUF + mmproj files the README lists; the pack itself depends only on pydantic and calls no APIs.

The most common beginner mistake is leaving initial_picture_number at 1 when there's no Initial picture - that tells the pack a nonexistent frame is Picture 1. Set it to 0 for Cast-only Ref2VA. And if you see a reference-count validation error after adding a Cast, it's usually because you cloned the Cast Load Image in the workflow but forgot to wire its Qwen result into this node's cast_json.