Three reference videos and three voices, and the clips keep their sound

H3 takes 9 reference images, 3 reference videos and 3 standalone reference
audios (comfy_extras/nodes_minimax_h3.py:265-280). The pack matched the 9 and
hardcoded exactly one of each of the others, two lines apart:

base_videos = {"ref_video_1": reference_video}
ref_audios = {"ref_audio_1": voice}

So two whole channels ran at a third of capacity. This adds slots 2 and 3 for
both -- twelve widgets, APPENDED, because widgets_values is positional.

Numbering is DENSE. Core numbers reference blocks by iteration order and the
prompt cites those ordinals, so filling slots 1 and 3 must produce <Video 1>
and <Video 2>, never a gap -- otherwise a beat naming "the second clip" cites
something else and nothing reports it. _dense_media() does that and is tested.

ref_video_audios was never passed at all, so a reference clip reached the model
SILENT even when the file had a soundtrack. Each clip's own audio is now
decoded and paired to the same ordinal, trimmed to the same window as its
picture. load_audio() grew a `kinds` parameter so it can be pointed at a video;
the default is unchanged. A clip with no usable audio track logs and passes
silent rather than failing the run.

Cache: chain_salt digested only slot 1 of each. It now digests all three plus
which clips carried sound, or a chain rendered with a second voice could be
served to a run that dropped it. IS_CHANGED covers the new filenames too, so
overwriting clip2.mp4 in place re-runs.

Slots 2 and 3 share slot 1's reference_video_size -- it is a decode area
budget, not a per-clip creative choice, and three clips is already three times
the RAM.

Adds tools/check_media_slots.py: dense numbering including the gap case, that
every file widget has its trim widgets, and -- the guard that did not exist --
that every `*_file` widget is claimed by media_strip.js. A Python file widget
with no slot in the strip falls through to a native dial, which is the 0.4.0
failure recorded at run_panel.js:53 and has recurred since.

Not rendered. The plumbing is checked; whether three voices behave needs a GPU.

13/13 checks pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013orqT1xNDezvdwv4f51MdW

h3_ref_chain.py

@@ -902,6 +902,22 @@ def _condition_pin_latent(lat, anchor, mode="off", noise=0.0, seed=0):
     return new, anchor
 
 
+def _dense_media(prefix, items):
+    """Number the filled slots 1..N with no gaps. -> dict or None.
+
+    `<Video N>` and `<Audio N>` are POSITIONAL: core numbers reference blocks
+    by the order it iterates them, and the prompt cites those ordinals. A gap
+    would hand core `ref_video_1` and `ref_video_3`, and a beat written about
+    "the second clip" would then name something else. So slot 3 becomes
+    <Video 2> when slot 2 is empty, and the tooltips say so.
+    """
+    out = {}
+    for x in items:
+        if x is not None:
+            out[f"{prefix}{len(out) + 1}"] = x
+    return out or None
+
+
 def _pin_mech_for(hop_index, overlap_n, prev_sampled):
     """Which mechanism `_pin_continue` will pick, without doing the work.
 
@@ -1639,6 +1655,84 @@ class HandTieClips:
                         "rather than by edge."
                     ),
                 }),
+                # APPENDED, never inserted -- see the note at the top of this
+                # block. H3 natively takes 9 reference images, 3 reference
+                # videos and 3 standalone reference audios; the pack matched
+                # the 9 and passed exactly one of each of the others.
+                "reference_video_2_file": ("STRING", {
+                    "default": "",
+                    "tooltip": (
+                        "Reference clip 2 of 3. H3 takes three; this pack "
+                        "passed one until now. Cited as <Video 2> when every "
+                        "earlier slot is filled -- the numbering is dense, so "
+                        "clearing slot 2 renumbers slot 3. Decoded at the same "
+                        "reference video size as slot 1. Set in the panel."
+                    ),
+                }),
+                "reference_video_2_start_s": ("FLOAT", {
+                    "default": 0.0, "min": 0.0, "max": 3600.0, "step": 0.1,
+                    "tooltip": "Trim in, seconds, for reference clip 2.",
+                }),
+                "reference_video_2_end_s": ("FLOAT", {
+                    "default": 0.0, "min": 0.0, "max": 3600.0, "step": 0.1,
+                    "tooltip": "Trim out, seconds, for reference clip 2. 0 = to the end.",
+                }),
+                "reference_video_3_file": ("STRING", {
+                    "default": "",
+                    "tooltip": (
+                        "Reference clip 3 of 3. H3 takes three; this pack "
+                        "passed one until now. Cited as <Video 3> when every "
+                        "earlier slot is filled -- the numbering is dense, so "
+                        "clearing slot 2 renumbers slot 3. Decoded at the same "
+                        "reference video size as slot 1. Set in the panel."
+                    ),
+                }),
+                "reference_video_3_start_s": ("FLOAT", {
+                    "default": 0.0, "min": 0.0, "max": 3600.0, "step": 0.1,
+                    "tooltip": "Trim in, seconds, for reference clip 3.",
+                }),
+                "reference_video_3_end_s": ("FLOAT", {
+                    "default": 0.0, "min": 0.0, "max": 3600.0, "step": 0.1,
+                    "tooltip": "Trim out, seconds, for reference clip 3. 0 = to the end.",
+                }),
+                "voice_2_file": ("STRING", {
+                    "default": "",
+                    "tooltip": (
+                        "Voice reference 2 of 3, cited as <Audio 2>. H3 takes "
+                        "three standalone reference audios; this pack passed one "
+                        "until now. Dense numbering, so clearing slot 2 renumbers "
+                        "slot 3 -- and a beat that names an ordinal would then "
+                        "cite the wrong voice. Every reference audio is attended "
+                        "on every step of every hop, so trim them. Set in the panel."
+                    ),
+                }),
+                "voice_2_start_s": ("FLOAT", {
+                    "default": 0.0, "min": 0.0, "max": 3600.0, "step": 0.1,
+                    "tooltip": "Trim in, seconds, for voice 2.",
+                }),
+                "voice_2_end_s": ("FLOAT", {
+                    "default": 0.0, "min": 0.0, "max": 3600.0, "step": 0.1,
+                    "tooltip": "Trim out, seconds, for voice 2. 0 = to the end.",
+                }),
+                "voice_3_file": ("STRING", {
+                    "default": "",
+                    "tooltip": (
+                        "Voice reference 3 of 3, cited as <Audio 3>. H3 takes "
+                        "three standalone reference audios; this pack passed one "
+                        "until now. Dense numbering, so clearing slot 2 renumbers "
+                        "slot 3 -- and a beat that names an ordinal would then "
+                        "cite the wrong voice. Every reference audio is attended "
+                        "on every step of every hop, so trim them. Set in the panel."
+                    ),
+                }),
+                "voice_3_start_s": ("FLOAT", {
+                    "default": 0.0, "min": 0.0, "max": 3600.0, "step": 0.1,
+                    "tooltip": "Trim in, seconds, for voice 3.",
+                }),
+                "voice_3_end_s": ("FLOAT", {
+                    "default": 0.0, "min": 0.0, "max": 3600.0, "step": 0.1,
+                    "tooltip": "Trim out, seconds, for voice 3. 0 = to the end.",
+                }),
             },
             "hidden": {
                 "unique_id": "UNIQUE_ID",
@@ -1665,7 +1759,9 @@ class HandTieClips:
     @classmethod
     def IS_CHANGED(cls, ref_plan="", start_image_file="",
                    reference_video_file="", voice_file="",
-                   soundtrack_file="", **_):
+                   soundtrack_file="",
+                   reference_video_2_file="", reference_video_3_file="",
+                   voice_2_file="", voice_3_file="", **_):
         """Re-run when a reference file changes underneath its name.
 
         Every picture now arrives as a basename, and a basename is a stable
@@ -1676,7 +1772,9 @@ class HandTieClips:
         would force a full re-render of an expensive node on every queue.
         """
         names = [start_image_file, reference_video_file, voice_file,
-                 soundtrack_file]
+                 soundtrack_file,
+                 reference_video_2_file, reference_video_3_file,
+                 voice_2_file, voice_3_file]
         try:
             for r in (_refs.parse_ref_plan(ref_plan).get("refs") or []):
                 if r.get("file"):
@@ -1705,6 +1803,12 @@ class HandTieClips:
             music_start_s=0.0, music_end_s=0.0, render_from=0,
             reference_video_desc="",
             reference_video_size=None,
+            reference_video_2_file="", reference_video_2_start_s=0.0,
+            reference_video_2_end_s=0.0,
+            reference_video_3_file="", reference_video_3_start_s=0.0,
+            reference_video_3_end_s=0.0,
+            voice_2_file="", voice_2_start_s=0.0, voice_2_end_s=0.0,
+            voice_3_file="", voice_3_start_s=0.0, voice_3_end_s=0.0,
             unique_id=None):
         # First thing, before a single model is touched: hand the writer's VRAM
         # back. The plan writer stays resident between plans now, which is the
@@ -1893,7 +1997,56 @@ class HandTieClips:
         voice = (_media.load_audio(voice_file,
                                    start=float(voice_start_s), end=float(voice_end_s))
                  if voice_file else None)
-        for _name, _got in (("start_image", start_image_file and start_image is None),
+
+        # Slots 2 and 3. All three decode at the same reference_video_size --
+        # it is an area budget for the decode, not a per-clip creative choice,
+        # and three of them is already three times the RAM.
+        def _more_video(fname, t0, t1):
+            return (_media.load_video(
+                fname, max_frames=max(lengths) if lengths else length,
+                start=float(t0), end=float(t1),
+                size=reference_video_size or _media.DEFAULT_VIDEO_SIZE)
+                if fname else None)
+
+        def _more_voice(fname, t0, t1):
+            return (_media.load_audio(fname, start=float(t0), end=float(t1))
+                    if fname else None)
+
+        reference_video_2 = _more_video(reference_video_2_file,
+                                        reference_video_2_start_s, reference_video_2_end_s)
+        reference_video_3 = _more_video(reference_video_3_file,
+                                        reference_video_3_start_s, reference_video_3_end_s)
+        voice_2 = _more_voice(voice_2_file, voice_2_start_s, voice_2_end_s)
+        voice_3 = _more_voice(voice_3_file, voice_3_start_s, voice_3_end_s)
+
+        # Each clip's own soundtrack, paired to the same ordinal. Core takes
+        # ref_video_audios beside ref_videos and this pack never passed them,
+        # so a reference clip reached the model silent even when the file had
+        # sound. Trimmed to the same window as its picture.
+        def _clip_audio(fname, t0, t1):
+            if not fname:
+                return None
+            try:
+                return _media.load_audio(fname, start=float(t0), end=float(t1),
+                                         kinds=("audio", "video"))
+            except Exception as e:  # noqa: BLE001 -- a silent clip is not a failure
+                print(f"[{TAG}] reference clip {fname}: no usable audio track "
+                      f"({e!r}); passing it silent", flush=True)
+                return None
+
+        _vid_slots = [
+            (reference_video, _clip_audio(reference_video_file,
+                                          reference_video_start_s, reference_video_end_s)),
+            (reference_video_2, _clip_audio(reference_video_2_file,
+                                            reference_video_2_start_s, reference_video_2_end_s)),
+            (reference_video_3, _clip_audio(reference_video_3_file,
+                                            reference_video_3_start_s, reference_video_3_end_s)),
+        ]
+        for _name, _got in (("reference_video_2", reference_video_2_file and reference_video_2 is None),
+                            ("reference_video_3", reference_video_3_file and reference_video_3 is None),
+                            ("voice_2", voice_2_file and voice_2 is None),
+                            ("voice_3", voice_3_file and voice_3 is None),
+                            ("start_image", start_image_file and start_image is None),
                             ("reference_video", reference_video_file and reference_video is None),
                             ("voice", voice_file and voice is None),
                             ("soundtrack", soundtrack_file and soundtrack is None
@@ -1949,7 +2102,20 @@ class HandTieClips:
                       f"character(s) {_chars}. Both inject identity text -- drop "
                       f"the characters block and keep setting only.", flush=True)
         ref_images = _collect_ref_images(slot_images)
-        base_videos = None if reference_video is None else {"ref_video_1": reference_video}
+        base_videos, base_video_audios = {}, {}
+        for _v, _a in _vid_slots:
+            if _v is None:
+                continue
+            _n = len(base_videos) + 1
+            base_videos[f"ref_video_{_n}"] = _v
+            if _a is not None:
+                base_video_audios[f"ref_video_audio_{_n}"] = _a
+        base_videos = base_videos or None
+        base_video_audios = base_video_audios or None
+        if base_videos and len(base_videos) > 1:
+            print(f"[{TAG}] {len(base_videos)} reference clips"
+                  + (f", {len(base_video_audios)} with sound" if base_video_audios else "")
+                  , flush=True)
         # The author's clip is always <Video 1>: _attach_pin_to_qwen APPENDS the
         # pinned tail (`live_v = len(videos) + 1`), so unlike the stills nothing
         # shifts it. One line, built once, and empty unless the field is filled.
@@ -1962,7 +2128,9 @@ class HandTieClips:
                   "description, so it goes to the encoder as <Video 1> with "
                   "nothing saying why. Fill reference_video_desc if the render "
                   "keeps drifting toward the clip.", flush=True)
-        ref_audios = None if voice is None else {"ref_audio_1": voice}
+        ref_audios = _dense_media("ref_audio_", [voice, voice_2, voice_3])
+        if ref_audios and len(ref_audios) > 1:
+            print(f"[{TAG}] {len(ref_audios)} voice references", flush=True)
 
         # Fingerprint the model as it arrives -- after whatever LoRA and
         # attention nodes are drawn upstream, before this node touches it.
@@ -2063,8 +2231,14 @@ class HandTieClips:
             # chain. Changing one late reference cost a full run. A reference
             # can only change the pixels of a hop it is actually handed to, so
             # that is where it belongs.
-            "voice": _store.audio_digest(voice),
-            "refvid": _store.tensor_digest(reference_video),
+            # All three slots, not just the first. Digesting only slot 1 would
+            # let a chain rendered with a second voice be served to a run that
+            # dropped it -- the silently-wrong-frames class this key exists to
+            # prevent.
+            "voice": [_store.audio_digest(v) for v in (voice, voice_2, voice_3)],
+            "refvid": [_store.tensor_digest(v) for v in
+                       (reference_video, reference_video_2, reference_video_3)],
+            "refvid_audio": sorted(base_video_audios or {}),
             # tensor_digest already covers the pixels, and the pixels change
             # with the size -- but only once the clip is decoded. Naming the
             # setting keeps the key readable when a cache miss has to be
@@ -2419,6 +2593,11 @@ class HandTieClips:
                     ref_image_size=ref_image_size,
                     ref_images=hop_images,
                     ref_videos=hop_videos,
+                    # Paired by ordinal with ref_videos. The pin clip, when
+                    # pin_to_qwen appends one, takes the next number and simply
+                    # has no entry here -- it is the previous hop's picture and
+                    # has no soundtrack of its own.
+                    ref_video_audios=base_video_audios,
                     ref_audios=(ref_audios if hop_voice else None),
                 )
                 cond, latent = _result(packed)[0], _result(packed)[1]

js/editor/media_strip.js

@@ -35,6 +35,24 @@ const SLOTS = [
     ["voice_file", "audio", "voice",
      "Voice or timbre reference for hop 1 as <Audio 1>. Later hops use the pin.",
      "voice", null, null],
+    // Slots 2 and 3. H3 takes three reference videos and three standalone
+    // reference audios; the pack passed one of each until now. Numbering is
+    // DENSE -- clearing slot 2 renumbers slot 3, so a beat that cites an
+    // ordinal would then name a different clip. Slots 2 and 3 share slot 1's
+    // reference video size, which is a decode budget rather than a creative
+    // choice.
+    ["reference_video_2_file", "video", "reference clip 2",
+     "Second motion/look plate, cited as <Video 2>. Shares slot 1's decode size.",
+     "reference_video_2", null, null],
+    ["reference_video_3_file", "video", "reference clip 3",
+     "Third motion/look plate, cited as <Video 3>. Shares slot 1's decode size.",
+     "reference_video_3", null, null],
+    ["voice_2_file", "audio", "voice 2",
+     "Second voice reference, cited as <Audio 2>. Every reference audio is attended on every step of every hop -- trim it.",
+     "voice_2", null, null],
+    ["voice_3_file", "audio", "voice 3",
+     "Third voice reference, cited as <Audio 3>. Trim it.",
+     "voice_3", null, null],
     // Not a reference at all: this one is never shown to the model. It is mixed
     // under the finished chain after the last hop is joined, so it sits here
     // because this is where you look for audio -- not because it behaves like

media.py

@@ -446,7 +446,7 @@ def load_video(name, max_frames=None, start=0.0, end=0.0,
         return None
 
 
-def load_audio(name, start=0.0, end=0.0):
+def load_audio(name, start=0.0, end=0.0, kinds=("audio",)):
     """A take as ComfyUI's AUDIO dict, or None.
 
     Shape is `[batch, channels, samples]`, which is what every AUDIO consumer
@@ -469,7 +469,10 @@ def load_audio(name, start=0.0, end=0.0):
     token the DiT attends over on every step of every hop. An untrimmed
     three-minute take is a large, silent, permanent tax on the render.
     """
-    path = resolve(name, kinds={"audio"})
+    # `kinds` is a parameter so a VIDEO can be asked for its own soundtrack:
+    # core takes ref_video_audios paired with each reference clip, and a clip
+    # handed over silent is a channel left at zero. Default is unchanged.
+    path = resolve(name, kinds=set(kinds))
     if path is None:
         return None
     try:

tools/check_all.py

@@ -39,6 +39,7 @@ CHECKS = [
     ("check_texture.py", []),
     ("check_workflows.py", []),
     ("check_features.py", []),
+    ("check_media_slots.py", []),
     ("check_planner.py", []),
     ("gen_schema.py", ["--check"]),
 ]

tools/check_media_slots.py

@@ -0,0 +1,111 @@
+r"""The media slots: dense numbering, and the JS half exists.
+
+    D:\ComfyUI\venv\Scripts\python.exe tools\check_media_slots.py
+
+H3 takes 9 reference images, 3 reference videos and 3 standalone reference
+audios. The pack matched the 9 and passed exactly one of the others until the
+slots were added, so two whole channels sat at a third of capacity.
+
+Two things about that are easy to get wrong and impossible to see afterwards.
+
+**Numbering is dense.** Core numbers reference blocks by the order it iterates
+them and the prompt cites those ordinals, so a gap must not survive: filling
+slots 1 and 3 has to produce <Video 1> and <Video 2>, not 1 and 3. If it ever
+produced a gap, a beat naming "the second clip" would cite something else and
+nothing would report it.
+
+**A file widget with no slot in the strip falls through to a native dial.**
+That is the 0.4.0 failure recorded at run_panel.js:53 and it has recurred since.
+Nothing checked it, so this does: every `*_file` widget the node declares must
+be claimed by `media_strip.js`, and every widget the strip expects must exist.
+"""
+from __future__ import annotations
+
+import importlib.util
+import io
+import os
+import re
+import sys
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+COMFY = os.path.dirname(os.path.dirname(HERE))
+sys.path.insert(0, COMFY)
+
+FAIL = []
+
+
+def ck(name, cond, detail=""):
+    print("  %-4s %-52s %s" % ("ok" if cond else "FAIL", name, detail))
+    if not cond:
+        FAIL.append(name)
+
+
+def load_pack():
+    spec = importlib.util.spec_from_file_location(
+        "htcpack", os.path.join(HERE, "__init__.py"),
+        submodule_search_locations=[HERE])
+    m = importlib.util.module_from_spec(spec)
+    sys.modules["htcpack"] = m
+    spec.loader.exec_module(m)
+    return m
+
+
+def main():
+    load_pack()
+    H3 = sys.modules["htcpack.h3_ref_chain"]
+    dense = H3._dense_media
+
+    print("dense numbering")
+    ck("all three present number 1..3",
+       list(dense("ref_audio_", ["a", "b", "c"])) == ["ref_audio_1", "ref_audio_2", "ref_audio_3"])
+    ck("a gap in the middle does NOT survive",
+       list(dense("ref_video_", ["a", None, "c"])) == ["ref_video_1", "ref_video_2"],
+       "slot 3 becomes <Video 2>")
+    ck("only the last slot filled still starts at 1",
+       list(dense("ref_audio_", [None, None, "c"])) == ["ref_audio_1"])
+    ck("order is preserved, not sorted",
+       list(dense("x", ["z", "a"]).values()) == ["z", "a"])
+    ck("nothing filled is None, not an empty dict",
+       dense("ref_audio_", [None, None, None]) is None,
+       "core takes None to mean the channel is unused")
+
+    print("the node declares what core accepts")
+    it = H3.HandTieClips.INPUT_TYPES()
+    allw = dict(it.get("required", {})); allw.update(it.get("optional", {}))
+    vids = [w for w in allw if re.fullmatch(r"reference_video(_[23])?_file", w)]
+    auds = [w for w in allw if re.fullmatch(r"voice(_[23])?_file", w)]
+    ck("three reference video slots", len(vids) == 3, str(sorted(vids)))
+    ck("three voice slots", len(auds) == 3, str(sorted(auds)))
+    for w in vids + auds:
+        trim = w[:-len("_file")]
+        ck(f"{w} has both trim widgets",
+           f"{trim}_start_s" in allw and f"{trim}_end_s" in allw)
+
+    print("the JS half exists for every file widget")
+    js = io.open(os.path.join(HERE, "js/editor/media_strip.js"), encoding="utf-8").read()
+    block = js.split("const SLOTS = [", 1)[1].split("\n];", 1)[0]
+    slot_files = re.findall(r'\["([a-z0-9_]+_file)"', block)
+    trims = re.findall(r'"([a-z0-9_]+)",\s*null,\s*null\]', block)
+
+    unclaimed = [w for w in allw
+                 if w.endswith("_file") and w not in slot_files]
+    ck("no file widget falls through to a native dial",
+       not unclaimed, f"unclaimed: {unclaimed}" if unclaimed else f"{len(slot_files)} slots")
+
+    expected = set(slot_files)
+    for t in trims:
+        expected |= {f"{t}_start_s", f"{t}_end_s"}
+    missing = sorted(w for w in expected if w not in allw)
+    ck("every widget the strip expects exists in Python",
+       not missing, f"missing: {missing}" if missing else f"{len(expected)} checked")
+
+    print()
+    if FAIL:
+        print("%d FAILURE(S): %s" % (len(FAIL), ", ".join(FAIL)))
+        return 1
+    print("ALL PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

workflows/HandTieClips_Showcase.json

@@ -611,7 +611,19 @@
         0,
         0,
         "",
-        "MAX"
+        "MAX",
+        "",
+        0,
+        0,
+        "",
+        0,
+        0,
+        "",
+        0,
+        0,
+        "",
+        0,
+        0
       ],
       "title": "H3 Ref2VA Chain - showcase 6x7s"
     },

workflows/HandTieClips_Starter.json

@@ -614,7 +614,19 @@
         0,
         0,
         "",
-        "MAX"
+        "MAX",
+        "",
+        0,
+        0,
+        "",
+        0,
+        0,
+        "",
+        0,
+        0,
+        "",
+        0,
+        0
       ],
       "title": "H3 Ref2VA Chain - starter"
     },