trim windows on every media input, and a per-reference pixel budget

Using the soundtrack for the first time exposed the gap: a 173 s track under a
9.4 s chain, and `loop` silently takes the first 9.4 s -- which for a mastered
track is the intro. There was no way to say WHICH 9.4 seconds.

The same hole was on the other two inputs, and on one of them it is not a
convenience issue. MiniMaxH3ReferenceToVideo hands the whole voice file to
`_encode_ref_audio` with no cap, and every latent frame that produces is a
token the DiT attends over on every step of every hop. An untrimmed
three-minute voice reference is a large, silent, permanent tax on the render.
The reference clip is truncated to the hop length, but only from frame 0, so
you could not point at the motion you wanted.

Six FLOAT widgets, appended last: voice / reference_video / music, start+end.
An end of 0.0 means "to the end of the file", so the default pair is untrimmed
and a longer replacement file still plays out. `media.clip_window` is the ONE
definition of what a window means -- four readers need to agree, and four
copies of that arithmetic would eventually disagree by a rounding rule. It can
never return an empty span: reversed, negative, past-the-end and
shorter-than-50 ms all fall back to the whole file, because a trim that did not
take is a puzzle while an empty tensor is a crash deep inside the model.

waveform.py computes peaks HERE, not in the browser. The first design decoded
in the tab, which is ~66 MB of Float32 for this track, per control, to draw a
picture 240 pixels wide. PromptMasterLD has four trim controls and not one
decodeAudioData between them; it is right. Buckets are max, not mean -- a mean
flattens transients into a sausage, and transients are the only landmarks you
can trim against. `seconds` comes from the decoded sample count because MP3
Xing/LAME headers routinely report double, and a duration that lies makes every
position on the bar lie with it. Measured: 173.49 s, matching the decode.

The route runs the decode in an executor. These handlers share ComfyUI's event
loop and this file takes 1.68 s to decode -- on the loop that is the canvas,
the queue and the progress bar all stopping together. Cached on (name, mtime,
n); mtime for the same reason media.stamp has it.

Per-reference `mp` lands as a ref_plan field, floor 0.3, absent/0 = no cap.
Down only, edges on H3's 16 px grid, and it says so in the console. Framed as
what it is: a token dial, so a location plate need not cost what a face costs.
Deliberately NOT offered on the first frame -- AddGuide does
`_resize(image, width, height, "center")`, so whatever you feed it becomes
exactly the canvas and the control would be wired to nothing.

The hop cache needed no change. chain_salt digests the loaded tensors, not the
filenames, so a trimmed voice is already a different key.

check_waveform.py: 38 assertions, green first run. Workflows 39 -> 45.
Still to come: the trim bar UI itself, and the rail control for mp. Until then
both are reachable through the ref_plan JSON and the raw widgets.

h3_ref_chain.py

@@ -1335,6 +1335,65 @@ class HandTieClips:
                         "are set."
                     ),
                 }),
+                # Trim windows, appended 2026-09-01 -- LAST, per the note at
+                # the top of this block. Six floats rather than one JSON blob
+                # because these three slots are fixed and named, the same
+                # reason `voice_file` is its own widget. The rail's references
+                # are a LIST, which is why their per-item settings live in
+                # `ref_plan` instead.
+                #
+                # An end of 0.0 is the sentinel for "to the end of the file",
+                # so the default pair (0, 0) is untrimmed and costs nothing.
+                # media.clip_window is the single definition of what they mean.
+                "voice_start_s": ("FLOAT", {
+                    "default": 0.0, "min": 0.0, "max": 3600.0, "step": 0.1,
+                    "tooltip": (
+                        "Trim window into the voice reference, in seconds. Leave both at 0 for "
+                        "the whole file; an end of 0 always means "
+                        "'to the end', so a longer replacement file "
+                        "still plays out. "
+                        "Worth setting: H3 encodes the WHOLE voice file into the "
+                        "conditioning with no cap, and every latent frame of it "
+                        "is attended over on every step of every hop. A "
+                        "three-minute take is a large invisible tax."
+                    ),
+                }),
+                "voice_end_s": ("FLOAT", {
+                    "default": 0.0, "min": 0.0, "max": 3600.0, "step": 0.1,
+                    "tooltip": "End of the voice window. 0 = to the end of the file.",
+                }),
+                "reference_video_start_s": ("FLOAT", {
+                    "default": 0.0, "min": 0.0, "max": 3600.0, "step": 0.1,
+                    "tooltip": (
+                        "Trim window into the reference clip, in seconds. Leave both at 0 for "
+                        "the whole file; an end of 0 always means "
+                        "'to the end', so a longer replacement file "
+                        "still plays out. "
+                        "H3 already truncates the clip to the hop length, but "
+                        "only from frame 0 -- so without this there is no way to "
+                        "point at the motion you actually want."
+                    ),
+                }),
+                "reference_video_end_s": ("FLOAT", {
+                    "default": 0.0, "min": 0.0, "max": 3600.0, "step": 0.1,
+                    "tooltip": "End of the reference clip window. 0 = to the end.",
+                }),
+                "music_start_s": ("FLOAT", {
+                    "default": 0.0, "min": 0.0, "max": 3600.0, "step": 0.1,
+                    "tooltip": (
+                        "Trim window into the soundtrack, in seconds. Leave both at 0 for "
+                        "the whole file; an end of 0 always means "
+                        "'to the end', so a longer replacement file "
+                        "still plays out. "
+                        "The window is cut from the TRACK first; music_fit then "
+                        "loops or trims that to the chain. Without it a mastered "
+                        "track always starts the chain on its intro."
+                    ),
+                }),
+                "music_end_s": ("FLOAT", {
+                    "default": 0.0, "min": 0.0, "max": 3600.0, "step": 0.1,
+                    "tooltip": "End of the soundtrack window. 0 = to the end.",
+                }),
             },
             "hidden": {
                 "unique_id": "UNIQUE_ID",
@@ -1396,6 +1455,9 @@ class HandTieClips:
             contact_sheet="off", tone_anchor=_tone.ANCHOR_STRENGTH,
             soundtrack=None, music_gain_db=-14.0, music_duck=0.6,
             music_fit="loop", music_fade_s=1.0, soundtrack_file="",
+            voice_start_s=0.0, voice_end_s=0.0,
+            reference_video_start_s=0.0, reference_video_end_s=0.0,
+            music_start_s=0.0, music_end_s=0.0,
             unique_id=None):
         dry = str(dry_run) == "on"
         draft = str(quality) == "draft"
@@ -1496,9 +1558,13 @@ class HandTieClips:
         # before anything expensive starts. Each returns exactly what the socket
         # it replaced delivered, so everything downstream is unchanged.
         start_image = _media.load_image(start_image_file) if start_image_file else None
-        reference_video = (_media.load_video(reference_video_file)
-                           if reference_video_file else None)
-        voice = _media.load_audio(voice_file) if voice_file else None
+        reference_video = (_media.load_video(
+            reference_video_file,
+            start=float(reference_video_start_s), end=float(reference_video_end_s))
+            if reference_video_file else None)
+        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),
                             ("reference_video", reference_video_file and reference_video is None),
                             ("voice", voice_file and voice is None),
@@ -1519,7 +1585,7 @@ class HandTieClips:
         for _r in ref_plan_refs:
             if not _r["file"]:
                 continue
-            _im = _media.load_image(_r["file"])
+            _im = _media.load_image(_r["file"], cap_mp=_r.get("mp") or 0.0)
             if _im is not None and _im.shape[0] > 0:
                 slot_images[_r["slot"]] = _im[:1]
         if ref_plan_refs:
@@ -2152,7 +2218,9 @@ class HandTieClips:
         # not, and silently preferring the stale one would be the worse guess.
         _bed = soundtrack
         if _bed is None and soundtrack_file:
-            _bed = _media.load_audio(soundtrack_file)
+            _bed = _media.load_audio(soundtrack_file,
+                                     start=float(music_start_s),
+                                     end=float(music_end_s))
         elif _bed is not None and soundtrack_file:
             print(f"[{TAG}] soundtrack: using the wired socket, not "
                   f"{soundtrack_file!r}", flush=True)

media.py

@@ -157,11 +157,80 @@ def _to_tensor(pil):
     return torch.from_numpy(arr).unsqueeze(0)
 
 
-def load_image(name):
+# The shortest window worth honouring. Below this a trim is indistinguishable
+# from a mis-drag, and a zero-length slice would hand the encoder an empty
+# tensor -- which fails deep inside the model with an error naming neither the
+# file nor the widget that caused it.
+MIN_WINDOW_S = 0.05
+
+
+def clip_window(start, end, secs):
+    """`(start, end)` in seconds -> a sane `(lo, hi)` inside `0..secs`.
+
+    THE one definition. Four readers need to agree on what a trim means -- the
+    voice, the reference clip, the soundtrack and the peaks route -- and four
+    copies of this arithmetic would eventually disagree by a rounding rule.
+
+    `end <= 0` is the sentinel for "to the end of the file", so the widget
+    default of 0.0 means untrimmed and a file that is later replaced by a longer
+    one still plays to its new end. Anything incoherent -- reversed, negative,
+    past the end, or shorter than MIN_WINDOW_S -- returns the WHOLE file rather
+    than an empty one. A trim that did not take is a puzzle; a render that dies
+    with an empty tensor is a bug report.
+    """
+    try:
+        secs = float(secs)
+    except (TypeError, ValueError):
+        return 0.0, 0.0
+    if secs <= 0:
+        return 0.0, 0.0
+    try:
+        lo = float(start or 0.0)
+    except (TypeError, ValueError):
+        lo = 0.0
+    try:
+        hi = float(end or 0.0)
+    except (TypeError, ValueError):
+        hi = 0.0
+
+    if hi <= 0.0 or hi > secs:
+        hi = secs
+    lo = max(0.0, min(lo, secs))
+    if hi - lo < MIN_WINDOW_S:
+        return 0.0, secs
+    return lo, hi
+
+
+def _mp_cap_size(w, h, cap_mp, multiple=16):
+    """Target size for a still under a megapixel cap. Down only.
+
+    `cap_mp <= 0` is off. Never upscales: H3 itself only ever scales references
+    down (`min(1.0, ...)` in nodes_minimax_h3.py), so a cap above the image's
+    own size would be a dial wired to nothing, and one that pretended to
+    upscale would just cost VRAM for interpolated pixels.
+
+    Edges land on a multiple of 16 because that is H3's canvas grid -- it
+    rounds to it anyway, and doing it here means the size in the log is the
+    size the encoder sees.
+    """
+    cap = float(cap_mp or 0.0) * 1_000_000.0
+    if cap <= 0 or w * h <= cap:
+        return int(w), int(h)
+    scale = (cap / float(w * h)) ** 0.5
+    m = max(1, int(multiple))
+    return (max(m, int(w * scale) // m * m), max(m, int(h * scale) // m * m))
+
+
+def load_image(name, cap_mp=0.0):
     """One still as an IMAGE tensor `[1,H,W,3]`, or None.
 
     Returns what a `Load Image` returns, so `_ref_frames` resizes it and
     `tensor_digest` keys it exactly as before.
+
+    `cap_mp` is the per-reference megapixel budget from the rail. It is a TOKEN
+    dial, not a quality one: every reference becomes `latent_h * latent_w`
+    entries in the DiT payload and is attended over on every step of every hop,
+    so a location plate costing as much as a face is waste. 0 means no cap.
     """
     path = resolve(name, kinds={"image"})
     if path is None:
@@ -171,14 +240,30 @@ def load_image(name):
         with Image.open(path) as im:
             # EXIF orientation: a phone portrait otherwise loads on its side,
             # and the model would be handed a rotated face.
-            return _to_tensor(ImageOps.exif_transpose(im))
+            im = ImageOps.exif_transpose(im)
+            tw, th = _mp_cap_size(im.width, im.height, cap_mp)
+            if (tw, th) != (im.width, im.height):
+                print(f"[{TAG}] {name}: {im.width}x{im.height} -> {tw}x{th} "
+                      f"({float(cap_mp):.2f} MP cap)", flush=True)
+                im = im.resize((tw, th), Image.Resampling.LANCZOS)
+            return _to_tensor(im)
     except Exception as exc:
         print(f"[{TAG}] could not read reference {name!r}: {exc!r}", flush=True)
         return None
 
 
-def load_video(name, max_frames=None):
-    """A clip as an IMAGE batch `[N,H,W,3]`, or None."""
+def load_video(name, max_frames=None, start=0.0, end=0.0):
+    """A clip as an IMAGE batch `[N,H,W,3]`, or None.
+
+    `start`/`end` are the trim window in seconds; see `clip_window`. H3 already
+    truncates a reference video to the hop length, but only from frame 0
+    (`frames[:frame_count]` in nodes_minimax_h3.py), so without this there is no
+    way to point at the segment whose motion you actually want.
+
+    Frames are counted rather than sought. A keyframe seek lands on the nearest
+    I-frame, which can be a second off -- and a bar that says 3.10 s while the
+    clip starts at 4.00 s is worse than no bar.
+    """
     path = resolve(name, kinds={"video"})
     if path is None:
         return None
@@ -189,7 +274,19 @@ def load_video(name, max_frames=None):
 
         frames = []
         with av.open(path) as container:
-            for frame in container.decode(video=0):
+            vs = container.streams.video[0]
+            fps = float(vs.average_rate or 0) or 24.0
+            n_total = int(vs.frames or 0)
+            secs = (n_total / fps) if n_total else float(
+                (vs.duration or 0) * float(vs.time_base or 0) or 0.0)
+            lo, hi = clip_window(start, end, secs) if secs > 0 else (0.0, 0.0)
+            first = int(round(lo * fps))
+            last = int(round(hi * fps)) if hi > 0 else 0
+            for i, frame in enumerate(container.decode(video=0)):
+                if i < first:
+                    continue
+                if last and i >= last:
+                    break
                 frames.append(frame.to_ndarray(format="rgb24"))
                 if max_frames and len(frames) >= int(max_frames):
                     break
@@ -202,7 +299,7 @@ def load_video(name, max_frames=None):
         return None
 
 
-def load_audio(name):
+def load_audio(name, start=0.0, end=0.0):
     """A take as ComfyUI's AUDIO dict, or None.
 
     Shape is `[batch, channels, samples]`, which is what every AUDIO consumer
@@ -218,6 +315,12 @@ def load_audio(name):
 
     `torchaudio` is still used for `functional.resample` in music.py; it is only
     the *decoding* half of that library that is gone.
+
+    `start`/`end` are the trim window in seconds; see `clip_window`. This matters
+    most for the voice: `MiniMaxH3ReferenceToVideo` hands the whole file to
+    `_encode_ref_audio` with no cap, and every latent frame that produces is a
+    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"})
     if path is None:
@@ -245,6 +348,11 @@ def load_audio(name):
             print(f"[{TAG}] {name!r} decoded to no audio frames", flush=True)
             return None
         wav = torch.cat(chunks, dim=1)
+        # Slice before the dtype conversion below so a long take is not first
+        # promoted to float32 in full.
+        lo, hi = clip_window(start, end, wav.shape[-1] / float(sr))
+        if hi > lo and (lo > 0.0 or hi < wav.shape[-1] / float(sr)):
+            wav = wav[..., int(round(lo * sr)):int(round(hi * sr))]
         # Integer PCM is scaled by its own full range, not normalised by peak:
         # a quiet take must stay quiet, and dividing by max would silently
         # apply a wildly different gain per file.

refs.py

@@ -40,7 +40,19 @@ RETENTION = {
 # and it exists only so the ordinal machinery below did not have to change.
 # A plan from before the sockets were removed carries an authored `slot` and no
 # `file`; that is detected, kept as `legacy_slot`, and reported by check().
-REF_FIELDS = ("tag", "file", "slot", "subject", "retention", "desc", "shots")
+REF_FIELDS = ("tag", "file", "slot", "subject", "retention", "desc", "shots",
+              "mp")
+
+# Per-reference pixel budget, in megapixels. 0 (or absent) means no cap.
+#
+# This is a TOKEN dial, not a quality one. H3 turns each reference into
+# `latent_h * latent_w` entries in the DiT payload and attends over all of them
+# on every step of every hop, so a location plate costing what a face costs is
+# waste. The floor is a picture you can still recognise a room in; there is no
+# ceiling, because H3 only ever scales a reference DOWN
+# (`min(1.0, ...)` in nodes_minimax_h3.py) and a cap above the file's own size
+# would be a dial wired to nothing.
+REF_MP_MIN = 0.3
 
 # Per-subject continuity text -- the half `HTCContinuityState` owned, moved here
 # so it is keyed by the same subject number that owns the picture ordinals.
@@ -147,6 +159,20 @@ def _norm_ref(raw, i):
         _fail(f"{where} (@{tag}): retention '{retention}' is not valid. "
               f"Use one of: {', '.join(sorted(RETENTION))}")
 
+    # Absent and 0 are the same thing -- no cap -- so an author who never
+    # opens the rail is never asked to think about this.
+    mp = raw.get("mp")
+    if mp in (None, "", 0, 0.0):
+        mp = 0.0
+    else:
+        try:
+            mp = float(mp)
+        except (TypeError, ValueError):
+            _fail(f"{where} (@{tag}): mp {mp!r} is not a number")
+        if mp < REF_MP_MIN:
+            _fail(f"{where} (@{tag}): mp {mp:g} is below the {REF_MP_MIN:g} MP "
+                  f"floor. Use 0 for no cap.")
+
     shots = raw.get("shots")
     if shots is not None:
         if not isinstance(shots, (list, tuple)):
@@ -172,6 +198,7 @@ def _norm_ref(raw, i):
         "retention": retention,
         "desc": str(raw.get("desc") or "").strip(),
         "shots": shots,
+        "mp": mp,
     }
 
 

routes.py

@@ -24,11 +24,25 @@ import os as _os
 from . import directives as _d
 from . import media as _media
 from . import refs as _refs
+from . import waveform as _waveform
 
 TAG = "HandTieClips"
 ROUTE = "/h3_ref_chain/vocab"
 UPLOAD_ROUTE = "/h3_ref_chain/upload"
 FILES_ROUTE = "/h3_ref_chain/files"
+PEAKS_ROUTE = "/h3_ref_chain/peaks"
+
+# Decoded waveform summaries, keyed (name, mtime, n).
+#
+# mtime is in the key for the same reason `media.stamp` puts it in IS_CHANGED:
+# a filename is a stable input even when the bytes behind it change, and a trim
+# bar drawn from the previous file is a bar that lies about where the beats are.
+#
+# Cleared wholesale rather than evicted one at a time. The entries are ~1.5 KB
+# and the working set is however many references one chain uses, so an LRU would
+# be more machinery than the thing it manages.
+_PEAKS = {}
+_PEAKS_MAX = 48
 
 # A batch of stills is a handful; this is a guard against a runaway multipart
 # body, not a considered product limit.
@@ -98,6 +112,60 @@ def register():
             print(f"[{TAG}] files route failed: {exc!r}", flush=True)
             return web.json_response({"ok": False, "error": str(exc)}, status=500)
 
+    @instance.routes.post(PEAKS_ROUTE)
+    async def _peaks(request):
+        """A waveform summary for the trim bar: `{peaks: [...], seconds}`.
+
+        The decode runs in an executor, NOT on this coroutine. These handlers
+        share ComfyUI's event loop, and decoding a three-minute file on it
+        freezes the canvas, the queue and the progress bar together -- the same
+        constraint `llm.py`'s docstring spells out for the writer.
+        """
+        import asyncio
+
+        try:
+            body = await request.json()
+        except Exception:
+            body = {}
+        name = str((body or {}).get("name") or "").strip()
+        n = (body or {}).get("n") or _waveform.DEFAULT_N
+
+        path = _media.resolve(name, kinds={"audio", "video"})
+        if path is None:
+            # Not an error the panel can act on -- the file is simply gone, and
+            # the picker already says so. A flat line draws an empty bar.
+            return web.json_response({"ok": True, "peaks": [], "seconds": 0.0})
+
+        try:
+            mtime = _os.path.getmtime(path)
+        except OSError:
+            mtime = 0.0
+        key = (name, mtime, int(n))
+        hit = _PEAKS.get(key)
+        if hit is not None:
+            return web.json_response({"ok": True, "peaks": hit[0],
+                                      "seconds": hit[1], "cached": True})
+
+        def work():
+            audio = _media.load_audio(name)
+            if audio is None:
+                # A video with no audio track, or a file PyAV cannot open. The
+                # bar still has to position its grips, so report the duration
+                # even when there is nothing to draw.
+                return [], 0.0
+            return _waveform.peaks(audio, n)
+
+        try:
+            got = await asyncio.get_running_loop().run_in_executor(None, work)
+        except Exception as exc:
+            print(f"[{TAG}] peaks route failed for {name!r}: {exc!r}", flush=True)
+            return web.json_response({"ok": False, "error": str(exc)}, status=500)
+
+        if len(_PEAKS) >= _PEAKS_MAX:
+            _PEAKS.clear()
+        _PEAKS[key] = got
+        return web.json_response({"ok": True, "peaks": got[0], "seconds": got[1]})
+
     @instance.routes.post(UPLOAD_ROUTE)
     async def _upload(request):
         """Stream dropped media into the reference folder.

tools/check_waveform.py

@@ -0,0 +1,122 @@
+"""Peaks and trim windows, on the CPU, with no server and no GPU.
+
+Same shape as check_music.py: `waveform.py` and the window arithmetic in
+`media.py` are importable without ComfyUI, so the parts that are easy to get
+subtly wrong -- an off-by-one bucket, a reversed window, a silent file dividing
+by zero -- are checked here rather than discovered in a render.
+
+The window cases are the ones that matter most. A bad window does not raise; it
+quietly slices the wrong audio, and the only symptom is a render that came out
+different for no visible reason.
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import torch  # noqa: E402
+
+import media  # noqa: E402
+import waveform  # noqa: E402
+
+FAILED = []
+
+
+def ck(what, cond, note=""):
+    print(f"    {'ok ' if cond else 'FAIL'}  {what}{'   ' + note if note else ''}")
+    if not cond:
+        FAILED.append(what)
+
+
+print("peaks")
+
+sr = 16000
+# A quiet bed with one loud tick a quarter of the way in. The tick is the whole
+# point: it is the landmark a person trims against, and a mean-bucketed
+# waveform would smear it into the noise floor.
+sig = torch.full((sr * 8,), 0.05)
+sig[sr * 2:sr * 2 + 200] = 0.9
+p = waveform.reduce_peaks(sig, 240)
+
+ck("returns exactly n buckets", len(p) == 240, f"{len(p)}")
+ck("normalised to 1.0", max(p) == 1.0)
+ck("nothing above 1.0", all(v <= 1.0 for v in p))
+ck("nothing below 0", all(v >= 0.0 for v in p))
+# 2s of 8s = bucket 60. Max-bucketing keeps it at full height; a mean would
+# divide the tick by the bucket width and bury it under the bed.
+peak_at = p.index(1.0)
+ck("the transient survives bucketing", 55 <= peak_at <= 65, f"bucket {peak_at}")
+ck("the quiet bed is not normalised up to the tick",
+   p[10] < 0.2, f"{p[10]:.3f}")
+
+ck("n is clamped low", len(waveform.reduce_peaks(sig, 1)) == waveform.MIN_N)
+ck("n is clamped high", len(waveform.reduce_peaks(sig, 99999)) == waveform.MAX_N)
+ck("n defaults", len(waveform.reduce_peaks(sig, None)) == waveform.DEFAULT_N)
+
+# Silence must not divide by zero. This is the empty-file case and it reaches
+# the route on any brand-new upload that is still being written.
+z = waveform.reduce_peaks(torch.zeros(sr), 240)
+ck("silence is a flat line, not a crash", len(z) == 240 and max(z) == 0.0)
+ck("an empty signal is a flat line", waveform.reduce_peaks(torch.zeros(0), 240) == [0.0] * 240)
+
+# The remainder fold: a transient in the final fraction of a second is audible,
+# so it has to be visible.
+tail = torch.zeros(sr * 8 + 137)
+tail[-50:] = 1.0
+ck("a transient in the ragged tail is kept",
+   waveform.reduce_peaks(tail, 240)[-1] == 1.0)
+
+print("\npeaks() on an AUDIO dict")
+
+aud = {"waveform": sig.reshape(1, 1, -1), "sample_rate": sr}
+pk, secs = waveform.peaks(aud, 240)
+ck("seconds comes from the samples", abs(secs - 8.0) < 1e-6, f"{secs:.3f}")
+ck("n buckets from a dict", len(pk) == 240)
+
+stereo = {"waveform": sig.reshape(1, 1, -1).repeat(1, 2, 1), "sample_rate": sr}
+ck("a stereo copy of a mono file draws identically",
+   waveform.peaks(stereo, 240)[0] == pk)
+
+ck("no audio is a flat line", waveform.peaks(None, 240)[1] == 0.0)
+ck("a dict with no waveform is a flat line",
+   waveform.peaks({"sample_rate": sr}, 240)[1] == 0.0)
+
+print("\nclip_window")
+
+W = media.clip_window
+ck("0/0 is the whole file", W(0, 0, 100.0) == (0.0, 100.0))
+ck("end 0 means to the end", W(3, 0, 100.0) == (3.0, 100.0))
+ck("a real window is kept", W(3, 9, 100.0) == (3.0, 9.0))
+ck("a reversed window falls back to the whole file", W(9, 3, 100.0) == (0.0, 100.0))
+ck("a start past the end falls back", W(200, 0, 100.0) == (0.0, 100.0))
+ck("a window shorter than the minimum falls back",
+   W(5, 5.0 + media.MIN_WINDOW_S / 2, 100.0) == (0.0, 100.0))
+ck("an end past the file is clamped to it", W(3, 500, 100.0) == (3.0, 100.0))
+ck("a negative start is clamped to 0", W(-5, 9, 100.0) == (0.0, 9.0))
+ck("a zero-length file yields nothing", W(0, 0, 0.0) == (0.0, 0.0))
+ck("junk does not raise", W("x", None, 100.0) == (0.0, 100.0))
+# The load-bearing one. A window is only ever a window; it can never hand the
+# encoder an empty tensor, whatever the widgets say.
+ck("no input produces an empty window",
+   all(W(a, b, 100.0)[1] > W(a, b, 100.0)[0]
+       for a in (-1, 0, 3, 99.99, 100, 500) for b in (-1, 0, 0.01, 3, 100, 500)))
+
+print("\nmegapixel cap")
+
+C = media._mp_cap_size
+ck("no cap is a no-op", C(1920, 1080, 0) == (1920, 1080))
+ck("a cap above the image is a no-op", C(1920, 1080, 8.0) == (1920, 1080))
+w, h = C(1920, 1080, 0.5)
+ck("a cap below the image scales it down", w * h <= 0.5e6, f"{w}x{h}")
+ck("the cap keeps the aspect", abs((w / h) - (1920 / 1080)) < 0.05, f"{w / h:.3f}")
+ck("edges land on H3's 16 px grid", w % 16 == 0 and h % 16 == 0, f"{w}x{h}")
+ck("a portrait image stays portrait", C(1080, 1920, 0.3)[0] < C(1080, 1920, 0.3)[1])
+ck("never smaller than one grid cell", min(C(64, 64, 0.3)) >= 16)
+
+print()
+if FAILED:
+    print(f"WAVEFORM CHECK: {len(FAILED)} FAILURE(S)")
+    for f in FAILED:
+        print(f"  - {f}")
+    sys.exit(1)
+print("WAVEFORM CHECK: all clear")

waveform.py

@@ -0,0 +1,106 @@
+"""Peaks for the trim bar, computed here rather than in the browser.
+
+The obvious way to draw a waveform in a panel is to fetch the file and run it
+through `AudioContext.decodeAudioData`. That was the first design and it is
+wrong at this scale: a 173 s stereo file decodes to roughly 66 MB of Float32 in
+the tab, per control, for a picture 240 pixels wide. PromptMasterLD reaches the
+same conclusion from the other direction -- it has four separate trim controls
+and not one `decodeAudioData` call between them.
+
+So the server sends 240 numbers. The browser holds 240 numbers. The decode
+happens once, on a thread, behind an mtime-keyed cache.
+
+Three details are load-bearing:
+
+**Bucket by max, not by mean.** A mean flattens transients into a smooth
+sausage, and transients are the only landmarks you can trim against -- the
+whole point of looking at the picture is to find the downbeat or the start of
+the sentence.
+
+**`seconds` comes from the decoded sample count.** MP3 Xing/LAME headers
+routinely report double the real duration, and a duration that lies makes every
+position on the bar lie with it. We already decode, so the honest number is
+free.
+
+**No ComfyUI import.** Same rule as `music.py`, `plan.py` and `refs.py`: the DSP
+is testable on a CPU with no server, which is what `tools/check_waveform.py`
+does.
+"""
+from __future__ import annotations
+
+TAG = "HandTieClips"
+
+# 240 is PromptMasterLD's default and it is a good one: a trim bar is a few
+# hundred CSS pixels wide, so more buckets than this buys nothing you can see
+# and costs JSON on every panel open.
+DEFAULT_N = 240
+MIN_N = 24
+MAX_N = 600
+
+
+def reduce_peaks(mono, n=DEFAULT_N):
+    """A 1-D waveform -> `n` bucket maxima in 0..1.
+
+    `mono` is any 1-D sequence of floats (a torch tensor, a numpy array, a
+    list). Returns a plain list so the caller can hand it straight to
+    `json_response` without a tensor library in the loop.
+    """
+    n = max(MIN_N, min(MAX_N, int(n or DEFAULT_N)))
+    total = len(mono)
+    if total <= 0:
+        return [0.0] * n
+
+    import torch  # noqa: PLC0415
+
+    x = mono if isinstance(mono, torch.Tensor) else torch.as_tensor(mono)
+    x = x.detach().to(torch.float32).abs().flatten()
+
+    # Pad up to a whole number of buckets rather than looping in Python. A
+    # 173 s file is 8.3M samples and a per-bucket slice in the interpreter is
+    # measurable; one reshape and one max over a dim is not.
+    per = max(1, total // n)
+    keep = per * n
+    if keep < total:
+        # Fold the remainder into the last bucket instead of dropping it, or a
+        # transient in the final fraction of a second would vanish from the
+        # picture while still being audible in the file.
+        head = x[:keep].reshape(n, per).amax(dim=1)
+        head[-1] = torch.maximum(head[-1], x[keep:].amax())
+        buckets = head
+    else:
+        buckets = x[:keep].reshape(n, per).amax(dim=1)
+
+    top = float(buckets.max())
+    if top > 0:
+        buckets = buckets / top
+    # 3 dp is well past what a 240 px canvas can render, and it keeps the JSON
+    # payload around 1.5 KB instead of 5 KB.
+    return [round(float(v), 3) for v in buckets]
+
+
+def peaks(audio, n=DEFAULT_N):
+    """A ComfyUI AUDIO dict -> `(peaks, seconds)`.
+
+    `audio` is what `media.load_audio` returns: `{"waveform": [B,C,S],
+    "sample_rate": int}`. A missing or empty take returns a flat line rather
+    than raising, so a panel drawing a control for a file that has gone missing
+    shows an empty bar instead of an error.
+    """
+    if not audio:
+        return [0.0] * max(MIN_N, min(MAX_N, int(n or DEFAULT_N))), 0.0
+
+    import torch  # noqa: PLC0415
+
+    wav = audio.get("waveform")
+    sr = int(audio.get("sample_rate") or 0)
+    if wav is None or sr <= 0:
+        return [0.0] * max(MIN_N, min(MAX_N, int(n or DEFAULT_N))), 0.0
+
+    x = wav if isinstance(wav, torch.Tensor) else torch.as_tensor(wav)
+    while x.dim() > 1:
+        # Mean across batch and channels, not sum: summing two correlated
+        # channels doubles the amplitude and the normalise below would hide it,
+        # but a mono file and its own stereo copy should draw identically.
+        x = x.mean(dim=0)
+    samples = int(x.shape[-1])
+    return reduce_peaks(x, n), samples / float(sr)

workflows/HandTieClips_Showcase.json

@@ -602,7 +602,13 @@
         0.6,
         "loop",
         1.0,
-        ""
+        "",
+        0,
+        0,
+        0,
+        0,
+        0,
+        0
       ],
       "title": "H3 Ref2VA Chain - showcase 6x7s"
     },

workflows/HandTieClips_Starter.json

@@ -605,7 +605,13 @@
         0.6,
         "loop",
         1.0,
-        ""
+        "",
+        0,
+        0,
+        0,
+        0,
+        0,
+        0
       ],
       "title": "H3 Ref2VA Chain - starter"
     },