Upsampler: chunk_join=stepped replaces continue; fix pin-strength shadowing

chunk_join=stepped: the chunks are re-drawn together, as spatial tiles
always were. The film starts as the upscaled chunks crossfaded into one
latent; each sigma step runs every chunk on its slice of that one state
(step 1 with its slice of one film-wide noise field) and merges the
results, each chunk weighted down linearly across the steps it shares, so
neighbours converge on one face and a chunk's off-tone last step counts
least. Every chunk is still drawn from the source: nothing accumulates.
Whole-frame chunks only; tiled or out-of-VRAM runs fall back to crossfade.

Removed chunk_join=continue: on a GPU it made a visible seam at the
hand-over (traced to a tone step at the held/free boundary) and did not
keep the face closer.

Fix: with the original (non-Regen2K) recipe and structure_lock > 0, chunk
2+ crashed -- the per-chunk lock anchor shadowed upsample()'s pin-strength
argument. Introduced on this branch; regression test added.

CHANGELOG.md

@@ -15,12 +15,13 @@ pack — the published package excludes them.
 - **New node: HTC Video Frames (lean)** (`HTCVideoFrames`). A drop-in for Get Video Components after Load Video, with the same images / audio / fps plus `frame_count` and the VIDEO. `start_seconds`, `max_frames`, `frame_rate` (24 fps nearest-frame re-time) and `resize` (megapixels or long edge, never enlarging) are applied while decoding, and the IMAGE is filled once from 8-bit frames: peak RAM was 1.08x the output against 2.01x for core-style decoding. It replaces Get Video Components in `workflows/HandTieClips_Upsample_Video.json`.
 - **New node: HTC Load Video (path)** (`HTCLoadVideoPath`). It reads a video where it is, so there's no upload, no copy into `input/` and no 100 MB upload limit (no `--max-upload-size` needed). Paste a path (Copy as path quotes are fine) or a name relative to `input/`. Outputs VIDEO, fps, frame_count and an info line (resolution, fps with variable-rate warning, length, codec, bit depth, audio), and the node re-runs only when the file changes.
 - **Fix (file to file, Video Frames):** an audio track FFmpeg can't decode (e.g. an iPhone's spatial-audio APAC track) is now skipped, as core does. Decoding one crashes the process.
-- **Upsampler: `attention`, `chunk_join`, `chunking`, `tiling`, `lock_anchor`** (standalone nodes and `HTC Upsample Settings`). `attention=sparse` applies ComfyUI's Model Sparse Attention (sol-attn) to every re-draw step, and runs dense on a ComfyUI without it. `chunk_join=continue` holds each chunk's shared frames to what the previous chunk drew (a per-frame sampler mask) and draws on from there, instead of crossfading two independent re-draws; whole-frame chunks only. `chunking` / `tiling` (both on, as before) each *allow* a split when the clip doesn't fit `tile_tokens`. Time is cut before space, chunks are never under 68 frames (Regen2K), and both off re-draws the clip in one whole-frame pass. Chunking off on a clip over 4x `tile_tokens` (about 18 s at 2 MP; in `HandTieClips` that is usually the whole film) chunks anyway. Tiling off never tiles, and running out of VRAM is an error that says what to change. `lock_anchor=source` (new default; it only matters with `structure_lock` > 0) holds the large shapes to the clip's own latent, enlarged by plain interpolation, instead of the 3D upscaler's output, so the upscaler's own errors are pulled back too. Defaults are otherwise unchanged.
+- **Upsampler: `attention`, `chunk_join`, `chunking`, `tiling`, `lock_anchor`** (standalone nodes and `HTC Upsample Settings`). `attention=sparse` applies ComfyUI's Model Sparse Attention (sol-attn) to every re-draw step, and runs dense on a ComfyUI without it. `chunk_join=stepped` re-draws the chunks together, as spatial tiles always were: after each step, the frames two chunks share are merged into one state, starting from one film-wide noise field, so neighbouring chunks converge on one face and a chunk's off-tone last step counts least. Whole-frame chunks only, and it falls back to crossfade otherwise. (A `continue` mode, which held the shared frames to the previous chunk, was tried and removed: in a side-by-side test it made a visible seam at the hand-over and did not keep the face any closer.) `chunking` / `tiling` (both on, as before) each *allow* a split when the clip doesn't fit `tile_tokens`. Time is cut before space, chunks are never under 68 frames (Regen2K), and both off re-draws the clip in one whole-frame pass. Chunking off on a clip over 4x `tile_tokens` (about 18 s at 2 MP; in `HandTieClips` that is usually the whole film) chunks anyway. Tiling off never tiles, and running out of VRAM is an error that says what to change. `lock_anchor=source` (new default; it only matters with `structure_lock` > 0) holds the large shapes to the clip's own latent, enlarged by plain interpolation, instead of the 3D upscaler's output, so the upscaler's own errors are pulled back too. Defaults are otherwise unchanged.
 - **Fix: the 3D latent upscale's CPU fallback no longer sticks.** One out-of-memory error used to run every remaining chunk on the CPU in float32. Now only that chunk does, and the next one goes back to the GPU.
 - Conditioning rows (references) now count against `tile_tokens` when tiles are cut (`_cond_extra_tokens` was unused).
 - **Upsampler: `tile_tokens = 0` learns the machine** (new default on the standalone nodes; `upsample_tile_tokens` 0 in `HandTieClips`, whose stock value stays 70000). It starts from the budget this GPU learned last time (70000 the first time) and measures each chunk's activation memory (peak minus what stays resident, since ComfyUI's dynamic loading fills spare VRAM with weights). It then stores the next run's starting budget in `ComfyUI/user/htc_upsampler_memory.json`: grown toward 85% of the card when there was room (at most 2x a run), or the budget that worked after an out-of-memory error, never returning near the failing value. It's keyed by GPU, VRAM, attention mode and the low-VRAM chunking. A fixed number behaves exactly as before and teaches nothing.
 - **Draft: `tile_context = global pass`** (standalone nodes and `HTC Upsample Settings`; default `none`). For chunks that must be tiled, the chunk is first re-drawn whole-frame at the largest size that fits the budget, with the same steps. The tiles then hold their large shapes to that result (`structure_lock` at full strength, at `lock_sigma`). A tile only sees its own window, and that is where invention comes from; this way the layout comes from a pass that saw everything, and the tiles add detail. Untiled chunks are unaffected. Not yet measured on a GPU.
 - **H3 Video Upsampler: `redraw_start`** (default 0.8 = the recipe). It rebuilds Regen2K's 3-step shift-6 grid from another starting noise. A side-by-side test showed the face drift comes from the re-draw itself, not from the 3D upscaler (denoise 0 matched the source), nor the seed, the LoRA strength or a text prompt. Starting from less noise keeps faces closer to the source at some cost in sharpening. It is the last widget on both nodes, so existing graphs keep their values.
+- **Fix:** with the original (non-Regen2K) recipe and `structure_lock` > 0, chunk 2 onward crashed, because the lock's anchor latent shadowed the first-frame pin strength. This was introduced on this branch, and it is now fixed and covered by a test.
 
 ## 3.2.0 — 2026-10-30
 

tiled_upsampler.py

@@ -102,15 +102,15 @@ LOCK_SIGMA = 2.0
 #   tile_tokens; neither forces one. chunking cuts time into 102-frame chunks
 #   (no shorter than 68 -- Regen2K's 3 steps from 0.8 invent on short pieces);
 #   tiling cuts space. Time is cut before space: a tile sees part of the frame,
-#   which is where invention comes from, while a join in time is held together
-#   by chunk_join=continue and structure_lock. Both off = the whole clip in one
-#   whole-frame pass.
+#   which is where invention comes from, while a join in time can be stepped
+#   together (chunk_join=stepped). Both off = the whole clip in one whole-frame
+#   pass.
 # lock_anchor: what structure_lock holds the large shapes to. source = the
 #   clip's own latent, enlarged by plain interpolation (nothing invented, so
 #   errors the 3D upscaler adds -- a blown patch, a colour shift -- are pulled
 #   back too); upscaler = the 3D upscaler's output.
 ATTENTION_MODES = ("dense", "sparse")
-JOIN_MODES = ("crossfade", "continue")
+JOIN_MODES = ("crossfade", "stepped")
 LOCK_ANCHORS = ("source", "upscaler")
 # tile_context (draft): what a tile knows about the rest of its frame. none =
 #   only its own window (and structure_lock's anchor). global pass = before the
@@ -1143,15 +1143,12 @@ def _apply_low_vram_patches(model, attn_chunks=4, ffn_chunks=2):
     return model
 
 
-def sample_tile(model, cond, sampler, sigmas, video, audio, noise, seed, lock=None,
-                known_steps=0):
+def sample_tile(model, cond, sampler, sigmas, video, audio, noise, seed, lock=None):
     """One tile through `sigmas`, audio frozen. -> the tile's video latent.
 
     `noise` is a (video, audio) pair to use as is. SamplerCustomAdvanced's
     path, with a positive-only guider at cfg 1 and the x0 preview. `lock` is
-    a `structure_lock_fn` for this tile, or None. The first `known_steps`
-    latent steps of `video` are held as given (the sampler keeps them at
-    every sigma) and the rest is drawn after them.
+    a `structure_lock_fn` for this tile, or None.
     """
     import comfy.model_management as mm
     import comfy.nested_tensor as nt
@@ -1162,13 +1159,9 @@ def sample_tile(model, cond, sampler, sigmas, video, audio, noise, seed, lock=No
 
     samples = comfy.sample.fix_empty_latent_channels(
         model, nt.NestedTensor((video, audio)), None, None)
-    vmask = torch.ones((1, 1, int(video.shape[2]) if known_steps else 1,
-                        video.shape[3], video.shape[4]),
-                       device=video.device, dtype=torch.float32)
-    if known_steps:
-        vmask[:, :, :int(known_steps)] = 0.0
     mask = nt.NestedTensor((
-        vmask,
+        torch.ones((1, 1, 1, video.shape[3], video.shape[4]),
+                   device=video.device, dtype=torch.float32),
         torch.zeros((1, 32, 2, audio.shape[-1]),
                     device=audio.device, dtype=audio.dtype)))
     guider = comfy.samplers.CFGGuider(model)
@@ -1348,7 +1341,7 @@ def global_pass(model, cond, sampler, sigmas, video, audio, seed, budget,
 def redraw_chunk(model, cond, sampler, sigmas, video, audio, seed, factor=1,
                  budget=TOKEN_BUDGET, overlap_px=TILE_OVERLAP_PX,
                  detail_sigma=0.0, noise_video=None, structure_lock=STRUCTURE_LOCK,
-                 lock_sigma=LOCK_SIGMA, known=None, anchor=None, allow_tiles=True,
+                 lock_sigma=LOCK_SIGMA, anchor=None, allow_tiles=True,
                  tile_context="none"):
     """Every tile stepped together, merged under the feather after each step.
 
@@ -1359,10 +1352,7 @@ def redraw_chunk(model, cond, sampler, sigmas, video, audio, seed, factor=1,
     so low-frequency tile-grid shifts are stripped while fine detail is kept.
     `structure_lock` > 0 holds every tile's large shapes to its slice of
     `video` (the upscaled source) at every step; see `structure_lock_fn`.
-    `known` = (steps, latent) continues the chunk from frames already drawn:
-    its first `steps` latent steps are held to `latent` and the rest is drawn
-    after them. Whole-frame chunks only; a tiled chunk ignores it (the
-    caller's crossfade then joins it as before). `anchor` replaces `video`
+    `anchor` replaces `video`
     as what structure_lock holds the large shapes to. `allow_tiles` False
     keeps the chunk whole-frame whatever the budget, and an OOM is an error
     instead of a retry in tiles. `tile_context` "global pass" re-draws the
@@ -1432,22 +1422,13 @@ def redraw_chunk(model, cond, sampler, sigmas, video, audio, seed, factor=1,
                 # DynamicVRAM DiT on every step.
                 r0, c0, rows, cols, tcond, _m = prepared[0]
                 xt = x[:, :, :, r0:r0 + rows, c0:c0 + cols].contiguous()
-                ks = 0
-                if known is not None and int(known[0]) > 0:
-                    ks = min(int(known[0]), t - 1)
-                    xt = xt.clone()     # a whole-frame slice may be `video` itself
-                    xt[:, :, :ks] = known[1][:, :, :ks].to(xt.device, xt.dtype)
                 noise = (nv[:, :, :, r0:r0 + rows, c0:c0 + cols].contiguous(), na)
                 ot = sample_tile(model, tcond, sampler, sigmas, xt, audio, noise, seed,
-                                 lock=locks[0], known_steps=ks)
+                                 lock=locks[0])
                 _calls += 1
                 x = ot.to(device=dev, dtype=dt)
                 del ot, xt
             else:
-                if known is not None and int(known[0]) > 0:
-                    print(f"[{TAG}] chunk_join=continue needs a whole-frame chunk; this one is "
-                          f"{grid[0]}x{grid[1]} tiles, so it is crossfaded", flush=True)
-                    known = None
                 if str(tile_context) == "global pass":
                     g, g_note = global_pass(
                         model, cond, sampler, sigmas, video, audio, seed,
@@ -1514,13 +1495,78 @@ def redraw_chunk(model, cond, sampler, sigmas, video, audio, seed, factor=1,
 
     if float(detail_sigma or 0.0) > 0.0:
         x = _highpass_detail_merge(video, x, sigma=float(detail_sigma))
-    if known is not None and int(known[0]) > 0:
-        ks = min(int(known[0]), t - 1)
-        x[:, :, :ks] = known[1][:, :, :ks].to(x.device, x.dtype)
     _LAST_BUDGET[0] = cur_budget
     return x, cur_budget
 
 
+def _step_weights(plan, i, device):
+    """Chunk i's weight per latent step in a stepped merge: 1 inside, ramping
+    linearly to near 0 across the steps it shares with each neighbour, so the
+    end of a chunk -- where it is weakest -- counts least."""
+    k0, _f0, k1, _f1 = plan[i]
+    w = torch.ones(k1 - k0, dtype=torch.float32, device=device)
+    if i > 0:
+        ov = max(0, plan[i - 1][2] - k0)
+        if ov:
+            w[:ov] = torch.arange(1, ov + 1, dtype=torch.float32, device=device) / (ov + 1)
+    if i + 1 < len(plan):
+        ov = max(0, k1 - plan[i + 1][0])
+        if ov:
+            w[-ov:] = torch.minimum(w[-ov:], torch.arange(ov, 0, -1, dtype=torch.float32,
+                                                          device=device) / (ov + 1))
+    return w.view(1, 1, -1, 1, 1)
+
+
+def redraw_stepped(model, plan, videos, audios, conds, sampler, sigmas, seed,
+                   locks=None, mem_samples=None):
+    """Every chunk stepped TOGETHER (chunk_join=stepped). -> the film's video latent.
+
+    `videos` are the chunks' upscaled latents (plan order), `audios` their
+    audio slices, `conds` their conditioning, `locks` their structure locks.
+    The film starts as the chunks crossfaded into one latent; each sigma step
+    runs every chunk from its slice of that one state (the first step with its
+    slice of one film-wide noise field) and merges the results under
+    `_step_weights` before the next step -- what spatial tiles have always
+    done, along time. Whole-frame chunks only (the caller checks)."""
+    c, h, w = int(videos[0].shape[1]), int(videos[0].shape[3]), int(videos[0].shape[4])
+    tv = int(plan[-1][2])
+    dev, dt = videos[0].device, videos[0].dtype
+    film = torch.zeros((1, c, tv, h, w), dtype=dt, device=dev)
+    dummy = torch.zeros((1, 32, 2, 1), dtype=dt, device=dev)
+    end = 0
+    for (k0, f0, k1, _f1), v in zip(plan, videos):
+        end, _ = _join_into(film, dummy, end, 0, v.to(dev, dt), dummy[..., :0], k0, f0)
+    nv = torch.randn((1, c, tv, h, w), generator=torch.Generator().manual_seed(int(seed)),
+                     dtype=torch.float32, device="cpu").to(dev, dt)
+    weights = [_step_weights(plan, i, dev) for i in range(len(plan))]
+    x = film
+    for step in range(len(sigmas) - 1):
+        two = sigmas[step:step + 2]
+        acc = torch.zeros_like(x, dtype=torch.float32)
+        wsum = torch.zeros((1, 1, tv, 1, 1), dtype=torch.float32, device=dev)
+        for i, (k0, _f0, k1, _f1) in enumerate(plan):
+            import comfy.model_management as mm
+            mm.throw_exception_if_processing_interrupted()
+            xt = x[:, :, k0:k1].contiguous()
+            noise = ((nv[:, :, k0:k1].contiguous() if step == 0 else torch.zeros_like(xt)),
+                     torch.zeros_like(audios[i]))
+            if torch.cuda.is_available():
+                torch.cuda.reset_peak_memory_stats()
+            ot = sample_tile(model, conds[i], sampler, two, xt, audios[i], noise, seed,
+                             lock=(locks[i] if locks else None))
+            if mem_samples is not None and torch.cuda.is_available():
+                mem_samples.append((seq_len(w * SPATIAL, h * SPATIAL, k1 - k0),
+                                    int(torch.cuda.max_memory_allocated()
+                                        - torch.cuda.memory_allocated()),
+                                    int(torch.cuda.memory_allocated())))
+            acc[:, :, k0:k1] += ot.to(device=dev, dtype=torch.float32) * weights[i]
+            wsum[:, :, k0:k1] += weights[i]
+            del ot, xt
+        x = (acc / wsum.clamp(min=1e-8)).to(dtype=dt)
+        del acc
+    return x
+
+
 def _crossfade(a, b, dim):
     n = a.shape[dim]
     wgt = torch.linspace(0.0, 1.0, n, device=a.device, dtype=a.dtype)
@@ -1781,7 +1827,49 @@ def upsample(model, conditioning, latent, sampler, upscaler, megapixels,
     _oom_total = 0
     init_budget = cur_budget = int(budget)
     mem_samples, _peak_all = [], 0
-    for i, (k0, f0, k1, f1) in enumerate(plan):
+    stepped = False
+    if str(chunk_join) == "stepped" and sigmas is not None and len(plan) > 1:
+        shape = upscaled_cvs[0].shape
+        fits = all(tile_grid(int(shape[3]), int(shape[4]), int(k1 - k0), factor,
+                             max(4096, int(budget)), overlap_px)[1][:2] == (1, 1)
+                   for (k0, _f0, k1, _f1) in plan) if tiling else True
+        if factor > 1 or not fits:
+            print(f"[{TAG}] chunk_join=stepped needs whole-frame chunks"
+                  + (" (and no h3upscale guide)" if factor > 1 else "")
+                  + "; crossfading instead", flush=True)
+        else:
+            conds, auds, locks = [], [], []
+            for i, (k0, f0, k1, f1) in enumerate(plan):
+                a0, a1 = audio_span(f0, f1)
+                auds.append(audio[:, :, :, a0:min(a1, ta)].contiguous())
+                cv = upscaled_cvs[i]
+                conds.append(cond_for_chunk(clean_refs(conditioning(f0, f1)) if per_chunk
+                                            else cond, f0, f1, cv.shape[3], cv.shape[4]))
+                locks.append(structure_lock_fn(anchors[i] if anchors[i] is not None else cv,
+                                               structure_lock, lock_sigma)
+                             if float(structure_lock) > 0.0 else None)
+            _tr = time.perf_counter()
+            try:
+                out_v = redraw_stepped(model, plan, upscaled_cvs, auds, conds, sampler,
+                                       sigmas, seed, locks, mem_samples)
+                stepped = True
+            except Exception as exc:
+                if not _is_oom(exc):
+                    raise
+                print(f"[{TAG}] chunk_join=stepped ran out of VRAM ({exc}); crossfading "
+                      "chunk by chunk instead", flush=True)
+                _free_all_gpu()
+                mem_samples.clear()
+            _redraw_s += time.perf_counter() - _tr
+            if stepped:
+                print(f"[{TAG}] chunk_join=stepped: {len(plan)} chunks x {len(sigmas) - 1} "
+                      f"steps in {len(plan) * (len(sigmas) - 1)} sampler calls, "
+                      f"{_redraw_s:.1f} s", flush=True)
+                if torch.cuda.is_available() and mem_samples:
+                    _peak_all = max(a + r for _t, a, r in mem_samples)
+                out_a[...] = audio[..., :int(total_a)]
+                end_v, end_a = int(tv), int(total_a)
+    for i, (k0, f0, k1, f1) in enumerate(plan if not stepped else []):
         a0, a1 = audio_span(f0, f1)
         cv = upscaled_cvs[i]
         upscaled_cvs[i] = None
@@ -1816,13 +1904,8 @@ def upsample(model, conditioning, latent, sampler, upscaler, megapixels,
                 print(f"[{TAG}] chunk {i + 1}/{len(plan)}: keeping lowered budget "
                       f"{cur_budget} ({_gc[0]}x{_gc[1]} tiles; would fit "
                       f"{_gi[0]}x{_gi[1]} at {init_budget})", flush=True)
-        anchor = anchors[i]
+        lock_anchor_t = anchors[i]      # not `anchor`: that is the pin strength above
         anchors[i] = None
-        known = None
-        if str(chunk_join) == "continue" and i > 0 and end_v > k0:
-            _ks = min(end_v - k0, int(cv.shape[2]) - 1)
-            if _ks > 0:
-                known = (_ks, out_v[:, :, k0:k0 + _ks])
         _tr = time.perf_counter()
         if torch.cuda.is_available():
             torch.cuda.reset_peak_memory_stats()
@@ -1831,7 +1914,7 @@ def upsample(model, conditioning, latent, sampler, upscaler, megapixels,
                            noise_video=(None if film_nv is None
                                         else film_nv[:, :, k0:k1]),
                            structure_lock=structure_lock, lock_sigma=lock_sigma,
-                           known=known, anchor=anchor, allow_tiles=tiling,
+                           anchor=lock_anchor_t, allow_tiles=tiling,
                            tile_context=tile_context)
         rv, cur_budget = (_rc if isinstance(_rc, tuple) else (_rc, cur_budget))
         _redraw_s += time.perf_counter() - _tr
@@ -2169,11 +2252,13 @@ SETTINGS_TYPE = "HTC_UPSAMPLE"
 ATTENTION_TIP = ("dense = exact attention. sparse = ComfyUI's Model Sparse Attention (sol-attn) "
                  "on every step: much faster on long sequences (rdh measured ~4x on a 2K "
                  "refine), close to dense but approximate -- compare faces before relying on it.")
-JOIN_TIP = ("crossfade = neighbouring chunks are re-drawn independently and blended over "
-            "the frames they share. continue = the shared frames are held to what the "
-            "previous chunk drew and the next chunk carries on from them, so faces do not "
-            "settle into a slightly different face at a join. Whole-frame chunks only "
-            "(a tiled chunk falls back to crossfade).")
+JOIN_TIP = ("crossfade = every chunk is re-drawn on its own and the 17 frames neighbours share "
+            "are blended. stepped = the chunks are stepped TOGETHER, the way spatial tiles "
+            "are: after each of the re-draw's steps, the frames two chunks share are merged "
+            "into one state before either takes the next step, from one film-wide noise "
+            "field. Two chunks then converge on one face instead of meeting as two, and a "
+            "chunk's last step (which tends to come out off-tone) weighs least. Same compute, "
+            "one sampler call per chunk per step. Whole-frame chunks only.")
 CHUNKING_TIP = ("On = the clip may be cut into 102-frame chunks (never under 68) when it does "
                 "not fit tile_tokens. Off = the whole clip in one pass: no joins, VRAM grows with "
                 "its length. Clips over 4x tile_tokens (~18 s at 2 MP and 70000; in HandTieClips "

workflows/HandTieClips_Upsample_Video.json

@@ -24,7 +24,7 @@
     "Node name for S&R": "MarkdownNote"
    },
    "widgets_values": [
-    "## H3 Video Upsampler: upscale a finished clip\n\n1. **Load Video**: pick the clip (put it in `ComfyUI/input`). Any size; 24 fps is what H3\n   assumes, other rates work but the soundtrack conditions the re-draw loosely.\n2. **Queue.** HTC Save Video writes it to `video/HANDTIECLIPS/upsampled` at the clip's own fps,\n   with its own soundtrack untouched (NVENC when there is a GPU). Set its `frame_gen` to x2 for\n   double the frame rate (RTX GPU + `nvidia-vfx`).\n\n### The node\n- **megapixels**: output size, aspect kept (2 = about 1920x1080).\n- **denoise**: Regen2K LoRA strength for the 3-step Euler re-draw on `[0.8, 24/35, 0.48, 0]` (0.8 is the default; 0 skips the re-draw and only enlarges).\n- **lora**: the Open-H3-Regenerate-2K LoRA (`open_h3_regenerate_2k_r256pp_bf16.safetensors` by default).\n- **tile_tokens**: 0 = auto (default): learned on this GPU run by run, starting at 70000, grown when there is room, lowered for good after running out of VRAM. A number fixes it (lower = shorter chunks, then tiles).\n- **redraw_seed**: noise seed for the Regen2K re-draw (42 by default).\n- **structure_lock**: 0 = off. Holds the re-draw to the clip's large shapes (faces, hands, line work) at every step so chunks and tiles stop inventing; try 0.5-1, higher for animation.\n- **lock_sigma**: what structure_lock counts as large, in latent cells (2 = 32 px). 1-1.5 also holds eyes and mouths on medium shots.\n- **fps** is wired from Get Video Components: H3 runs on a 24 fps clock, so for other rates **off_24_audio** retimes what the re-draw hears (retime) or conditions on silence. The output soundtrack is always the original. A 48 fps clip interpolated from a 24 fps render: upscale the 24 fps frames and use frame_gen x2 instead (half the work, exact sync).\n- **conditioning** (optional): a CLIPTextEncode of what the clip shows, typed or written by a VLM. Unwired = zeroed-out conditioning.\n- **audio_vae** wired = the re-draw pins the real soundtrack; unwired = it pins silence.\n\nMouths and motion come from the clip; only fine detail is re-drawn.\n\n**Video Frames (lean)** replaces Get Video Components: same images / audio / fps, about half the RAM, and `start_seconds`, `max_frames`, `frame_rate` and `resize` applied while decoding. For long clips use the file-to-file workflow instead.\n\n**Speed and joins:** `attention` sparse = ComfyUI's sparse attention (much faster on long sequences, approximate: compare faces). `chunk_join` continue = each chunk carries on from the frames the previous one drew instead of blending two re-draws. `chunking` / `tiling` allow a split when the clip doesn't fit `tile_tokens` (chunks are shortened first, never under 68 frames); both off = the whole clip in one whole-frame pass, for short clips on big cards. `lock_anchor` source holds `structure_lock` to the clip itself, so the 3D upscaler's own errors are pulled back too."
+    "## H3 Video Upsampler: upscale a finished clip\n\n1. **Load Video**: pick the clip (put it in `ComfyUI/input`). Any size; 24 fps is what H3\n   assumes, other rates work but the soundtrack conditions the re-draw loosely.\n2. **Queue.** HTC Save Video writes it to `video/HANDTIECLIPS/upsampled` at the clip's own fps,\n   with its own soundtrack untouched (NVENC when there is a GPU). Set its `frame_gen` to x2 for\n   double the frame rate (RTX GPU + `nvidia-vfx`).\n\n### The node\n- **megapixels**: output size, aspect kept (2 = about 1920x1080).\n- **denoise**: Regen2K LoRA strength for the 3-step Euler re-draw on `[0.8, 24/35, 0.48, 0]` (0.8 is the default; 0 skips the re-draw and only enlarges).\n- **lora**: the Open-H3-Regenerate-2K LoRA (`open_h3_regenerate_2k_r256pp_bf16.safetensors` by default).\n- **tile_tokens**: 0 = auto (default): learned on this GPU run by run, starting at 70000, grown when there is room, lowered for good after running out of VRAM. A number fixes it (lower = shorter chunks, then tiles).\n- **redraw_seed**: noise seed for the Regen2K re-draw (42 by default).\n- **structure_lock**: 0 = off. Holds the re-draw to the clip's large shapes (faces, hands, line work) at every step so chunks and tiles stop inventing; try 0.5-1, higher for animation.\n- **lock_sigma**: what structure_lock counts as large, in latent cells (2 = 32 px). 1-1.5 also holds eyes and mouths on medium shots.\n- **fps** is wired from Get Video Components: H3 runs on a 24 fps clock, so for other rates **off_24_audio** retimes what the re-draw hears (retime) or conditions on silence. The output soundtrack is always the original. A 48 fps clip interpolated from a 24 fps render: upscale the 24 fps frames and use frame_gen x2 instead (half the work, exact sync).\n- **conditioning** (optional): a CLIPTextEncode of what the clip shows, typed or written by a VLM. Unwired = zeroed-out conditioning.\n- **audio_vae** wired = the re-draw pins the real soundtrack; unwired = it pins silence.\n\nMouths and motion come from the clip; only fine detail is re-drawn.\n\n**Video Frames (lean)** replaces Get Video Components: same images / audio / fps, about half the RAM, and `start_seconds`, `max_frames`, `frame_rate` and `resize` applied while decoding. For long clips use the file-to-file workflow instead.\n\n**Speed and joins:** `attention` sparse = ComfyUI's sparse attention (much faster on long sequences, approximate: compare faces). `chunk_join` stepped = neighbouring chunks are re-drawn together and merged after every step, so they converge on one face instead of meeting as two. `chunking` / `tiling` allow a split when the clip doesn't fit `tile_tokens` (chunks are shortened first, never under 68 frames); both off = the whole clip in one whole-frame pass, for short clips on big cards. `lock_anchor` source holds `structure_lock` to the clip itself, so the 3D upscaler's own errors are pulled back too."
    ]
   },
   {

workflows/HandTieClips_Upsample_Video_File.json

@@ -24,7 +24,7 @@
     "Node name for S&R": "MarkdownNote"
    },
    "widgets_values": [
-    "## H3 Video Upsampler (file to file)\n\nThe same re-draw as the IMAGE workflow, for clips of any length on any machine: the video is read, encoded, re-drawn, decoded and saved **a chunk at a time**, so RAM stays flat however long the film is (the IMAGE path holds the whole clip twice; a minute at 48 fps is over 100 GB).\n\n1. **Load Video**: pick the clip. Frame rate and soundtrack come from the file.\n2. **Queue.** The MP4 lands in `video/H3_upsampled` with the original soundtrack.\n\n### The node\n- **megapixels / denoise / lora / redraw_seed**: as in the IMAGE workflow. **tile_tokens** 0 = auto: learned on this GPU run by run.\n- **structure_lock** (0 = off) holds faces, hands and line work to the clip; try 0.5-1. **lock_sigma** 1-1.5 also holds eyes and mouths on medium shots.\n- **off_24_audio**: H3 runs on a 24 fps clock; for other rates `retime` keeps the re-draw's lip sync.\n- **frame_gen / codec / quality**: as in H3 Save Video. x2 doubles the frame rate (RTX + `nvidia-vfx`).\n- **conditioning** (optional): a CLIPTextEncode of the clip's look. Unwired = zeroed out.\n- **frame_rate**: `24 (H3 native)` re-times the clip to 24 fps while reading (nearest frame), so the soundtrack lines up exactly and a 48 fps clip costs half the re-draw; add `frame_gen` x2 to save 48 again.\n- **reuse_encoded**: the next run on the same clip skips reading and encoding (kept in ComfyUI's temp folder until restart). Handy for A/B runs of structure_lock or seeds.\n\n**Speed and joins:** `attention` sparse = ComfyUI's sparse attention (much faster on long sequences, approximate: compare faces). `chunk_join` continue = each chunk carries on from the frames the previous one drew instead of blending two re-draws. `chunking` / `tiling` allow a split when the clip doesn't fit `tile_tokens` (chunks are shortened first, never under 68 frames); both off = the whole clip in one whole-frame pass, for short clips on big cards. `lock_anchor` source holds `structure_lock` to the clip itself, so the 3D upscaler's own errors are pulled back too."
+    "## H3 Video Upsampler (file to file)\n\nThe same re-draw as the IMAGE workflow, for clips of any length on any machine: the video is read, encoded, re-drawn, decoded and saved **a chunk at a time**, so RAM stays flat however long the film is (the IMAGE path holds the whole clip twice; a minute at 48 fps is over 100 GB).\n\n1. **Load Video**: pick the clip. Frame rate and soundtrack come from the file.\n2. **Queue.** The MP4 lands in `video/H3_upsampled` with the original soundtrack.\n\n### The node\n- **megapixels / denoise / lora / redraw_seed**: as in the IMAGE workflow. **tile_tokens** 0 = auto: learned on this GPU run by run.\n- **structure_lock** (0 = off) holds faces, hands and line work to the clip; try 0.5-1. **lock_sigma** 1-1.5 also holds eyes and mouths on medium shots.\n- **off_24_audio**: H3 runs on a 24 fps clock; for other rates `retime` keeps the re-draw's lip sync.\n- **frame_gen / codec / quality**: as in H3 Save Video. x2 doubles the frame rate (RTX + `nvidia-vfx`).\n- **conditioning** (optional): a CLIPTextEncode of the clip's look. Unwired = zeroed out.\n- **frame_rate**: `24 (H3 native)` re-times the clip to 24 fps while reading (nearest frame), so the soundtrack lines up exactly and a 48 fps clip costs half the re-draw; add `frame_gen` x2 to save 48 again.\n- **reuse_encoded**: the next run on the same clip skips reading and encoding (kept in ComfyUI's temp folder until restart). Handy for A/B runs of structure_lock or seeds.\n\n**Speed and joins:** `attention` sparse = ComfyUI's sparse attention (much faster on long sequences, approximate: compare faces). `chunk_join` stepped = neighbouring chunks are re-drawn together and merged after every step, so they converge on one face instead of meeting as two. `chunking` / `tiling` allow a split when the clip doesn't fit `tile_tokens` (chunks are shortened first, never under 68 frames); both off = the whole clip in one whole-frame pass, for short clips on big cards. `lock_anchor` source holds `structure_lock` to the clip itself, so the 3D upscaler's own errors are pulled back too."
    ]
   },
   {