0.4.5: the hop cache stops shelling out to ffmpeg

store.py ran an ffmpeg binary through subprocess.Popen to write and read
its lossless FFV1 cache. That cost two things, and the registry flag was
the smaller one.

_ffmpeg() raised if no ffmpeg was on PATH, and ComfyUI never requires
one -- so the feature that makes a tone A/B cost 14 s instead of 164 s
hard-failed for a large share of users, on the pack's fastest path.

The Comfy registry's YARA scan also flagged all three published versions
for it: rule python_command_injection_risk, "detects ALL os.system and
subprocess usage", severity info, recommendation null. It does no taint
analysis, so a static argument list built from shutil.which and run with
shell=False matches as hard as a shell injection. The reason is not in
the web UI -- it is behind
api.comfy.org/versions?nodeId=<id>&include_status_reason=true.

Now encoded in process with PyAV, a hard dependency of ComfyUI itself
(SaveVideo and CreateVideo are built on it). The format is deliberately
unchanged: ffv1 / rgb48le / level 3 / coder 1 / context 1, in matroska.

Verified before writing any of it, and again through the real HopStore:

- PyAV encode -> PyAV decode is bit exact, including 0 and 65535
- ffmpeg encode -> PyAV decode is bit exact, so caches already on disk
still read and a resumed chain still matches an uninterrupted one
- output sizes within 44 bytes (145,780 vs 145,824)
- a frame-count mismatch still raises instead of returning a short clip

The decode path also stopped building a list of frames to stack, and
decodes into one preallocated array instead -- the geometry is already
in the meta file, so there is no second full-size copy.

Five documents claimed ffmpeg was required (CLAUDE.md, PROMPTING.md,
README twice, and the Starter's on-canvas card via tools/notes.py). All
corrected; README's existing "No dependencies to install" line, which
already listed av, is now true rather than nearly true.

Devlog section 23.

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

CLAUDE.md

@@ -93,7 +93,7 @@ Fixes two real bugs:
 
 ### 4. Hop store (`store.py`)
 
-Lossless FFV1 (`rgb48le`) video + a float32 `.npy` waveform + a `.latent.pt` sidecar per hop under ComfyUI's temp dir, enabled by `cache_hops`, LRU-evicted above `cache_budget_gb`. **Needs `ffmpeg` on PATH** or it raises.
+Lossless FFV1 (`rgb48le`) video + a float32 `.npy` waveform + a `.latent.pt` sidecar per hop under ComfyUI's temp dir, enabled by `cache_hops`, LRU-evicted above `cache_budget_gb`. Encoded in process with PyAV, which ComfyUI already depends on -- no `ffmpeg` binary on PATH is needed, and nothing here shells out.
 
 **The latent sidecar is what makes the cache useful past hop 1** (added 2026-08-27). It stores this hop's sampler output so a hit can seed the *next* hop's Motion-Context pin. Without it, a hit left `prev_sampled` empty, the next hop predicted the AddGuide fallback, and because the mechanism is in the per-hop key that key no longer matched what was on disk -- so **nothing past hop 1 could ever hit, and the hop after a hit was joined by the weaker mechanism.** `cache_hops=on` was measurably worse than off. Verified in-browser: hop 1 hit, hop 2 logged `previous hop has no sampler latent (cache hit); AddGuide pixel pin`, hops 2-3 re-rendered.
 

PROMPTING.md

@@ -519,8 +519,9 @@ Eight hops in, hop 6 is wrong and the other seven are fine. `cache_hops` is how
 you fix 6 without re-rendering 1 through 5.
 
 Turn it **on before the first run of a plan** -- it is `off` by default, and a
-hop that was never cached cannot be reused. It needs `ffmpeg` on PATH; without
-it the node raises rather than quietly carrying on without a cache.
+hop that was never cached cannot be reused. It needs nothing installed --
+the lossless FFV1 encode runs in process through PyAV, which ComfyUI already
+ships.
 
 ### Editing a hop invalidates that hop and everything after it
 

README.md

@@ -50,6 +50,18 @@ of a second, separate generation. The pack exists so that you cannot tell which.
 > also has its tooltips back — it read them from `widget.options`, where this
 > frontend does not keep them. Section 22 of the devlog has the A/B.
 
+> **0.4.5 — 2026-08-30.** The hop cache no longer needs `ffmpeg` on PATH. It
+> used to shell out to an ffmpeg binary to write its lossless FFV1, so the
+> feature that makes a tone A/B cost 14 seconds instead of 164 raised a
+> `RuntimeError` for anyone who did not happen to have ffmpeg installed —
+> which ComfyUI itself never requires. It now encodes in process through PyAV,
+> which ComfyUI already depends on. **The format is unchanged** (ffv1 /
+> `rgb48le` / level 3), verified bit-exact in both directions, so caches
+> written by the old path still read and a resumed chain still matches an
+> uninterrupted one. This also clears the Comfy registry's security scan,
+> which flags every `subprocess` call in a custom node regardless of how it is
+> invoked. Section 23 of the devlog.
+
 **Writing for it:** [PROMPTING.md](PROMPTING.md) is the authoring guide — the rules that come from what this model actually does, not from taste. [prompt_pack/](prompt_pack/) has a copy-paste prompt that gets a language model to write plans for you.
 
 Each hop is native **MiniMax H3 Reference-to-Video**. Hops after the first are guided by the **previous hop's sampler AV latent** via `ComfyUI-H3-Motion-Context` when that pack is installed (22 picture frames + 24-frame end-aligned audio). Stock `MiniMaxH3AddGuide` is the fallback when Motion-Context is missing or the previous hop was a pixel cache hit. Voice stays as a reference every hop. Identity stills ride hop 1; later hops use the pin for wardrobe and room unless a ref lists those hops in `shots`. A 5 s hop drops the airlock on a continuous join — validate seams at 8 s or 15 s.
@@ -133,7 +145,6 @@ The two example graphs are in `workflows/` inside the pack folder -- open them w
 - ComfyUI new enough to include **Add Guide for MiniMax H3** (`MiniMaxH3AddGuide`)
 - A **ref2va** (or hybrid ref2va) checkpoint — fl2va has no reference rows
 - Video VAE + audio VAE + MiniMax text encoder
-- `ffmpeg` on PATH, if you turn `cache_hops` on
 - **Optional but recommended:** [ComfyUI-H3-Motion-Context](https://github.com/NikoDemon80/ComfyUI-H3-Motion-Context). Hops after the first are guided by the previous hop's sampler AV latent through it. Without it the node falls back to stock `MiniMaxH3AddGuide`, which still works and still chains -- it is a different join, so a seam you are comparing against someone else's render may not be the same code path. The node detects it at runtime and prints which one it took.
 
 The two shipped workflows wire the **turbo stack** this node is actually run with, because an example without it is not the graph anyone uses:
@@ -335,7 +346,7 @@ The key **chains** — each hop's key includes the previous hop's — because ho
 
 That last one is worth knowing about. The node cannot read the settings on your LoRA and attention nodes, so instead it fingerprints what they *did* to the model — which weight keys were patched, at what strengths, and the attention overrides. Change a LoRA strength and the cache correctly invalidates. Two different LoRAs touching exactly the same keys at exactly the same strengths would look identical to it; that is the one gap.
 
-Set `locked: true` on a shot to pin it to its last render regardless. Needs `ffmpeg` on PATH.
+Set `locked: true` on a shot to pin it to its last render regardless.
 
 ## Reading a plan before you render it
 

docs/DEVLOG.md

@@ -969,3 +969,56 @@ trip and says the two spellings are one string; `refs.py` rejects an `@tag` in
 `name`, `locked` or `context`. Not fixed, because it is a brief-writing lesson
 rather than a bug: ending a chain in a location no plate describes earns the
 place-handoff warning, and that was the brief's fault, not either model's.
+
+## 23. The hop cache stops shelling out (2026-08-30)
+
+The Comfy registry flagged all three published versions. The reason is not in
+the web UI and `status_detail` on the node is empty; it is behind
+`https://api.comfy.org/versions?nodeId=<id>&include_status_reason=true`, which
+returns the actual findings:
+
+    scanner      yara_scan
+    issue_type   python_command_injection_risk
+    file_path    store.py   lines 131 and 215
+    description  "Detects all os.system and subprocess usage"
+    severity     info
+    recommendation  null
+    admin_tags   any-code-execute
+
+Two findings, both the `subprocess.Popen` calls that ran `ffmpeg` for the FFV1
+hop cache. The rule does no taint analysis, so a static argument list built from
+`shutil.which` and run with `shell=False` matches exactly as hard as a shell
+injection would. Its 95% confidence is confidence that the call *is* a
+subprocess call, not that it is exploitable.
+
+Appealing looked like the wrong move. `plaguekind-nodes` -- 22.5k downloads --
+has 1.3.8 through 1.4.0 flagged with the same two findings and 1.4.1 onward
+`Active` with `status_reason` = **"Passed automated checks"**, the string the
+scanner writes when it finds nothing. That is a code change, not an admin
+override.
+
+**But the registry is the weakest reason to have done this.** `_ffmpeg()` raised
+if no ffmpeg binary was on PATH, and ComfyUI never requires one -- so the
+feature that makes a tone A/B cost 14 s instead of 164 s hard-failed for a large
+share of users, on the pack's fastest path, at the exact moment a CivitAI post
+would send new people at it.
+
+PyAV is a hard dependency of ComfyUI itself (SaveVideo and CreateVideo are built
+on it) and its ffv1 encoder lists `rgb48le` among 61 pixel formats, so the
+format did not have to change: ffv1 / rgb48le / level 3 / coder 1 / context 1,
+in matroska. Verified before writing any of it, and again through the real
+`HopStore`:
+
+- PyAV encode -> PyAV decode: **bit exact**, including 0, 65535 and midpoints
+- **ffmpeg encode -> PyAV decode: bit exact** -- existing caches on disk still
+  read, which is the part that protects users
+- file sizes within 44 bytes of each other (145,780 vs 145,824)
+- a frame-count mismatch still raises rather than returning a short clip
+
+The decode path also got slightly better on the way: it decodes into one
+preallocated `(n, h, w, 3)` array instead of building a list of frames and
+stacking, so there is no second full-size copy. Five documents claimed ffmpeg
+was required -- CLAUDE.md, PROMPTING.md, README twice, and the on-canvas card in
+the Starter workflow via `tools/notes.py`. All corrected. README's existing
+"No dependencies to install" line, which already listed `av`, is now true rather
+than nearly true.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "comfyui-hand-tie-clips"
-version = "0.4.4"
+version = "0.4.5"
 description = "Native MiniMax H3 Ref2VA chain: persistent references, previous-segment clip+audio pin, one queue."
 readme = "README.md"
 # SPDX string, not `{ file = "LICENSE" }`. The registry does not resolve the file

store.py

@@ -24,10 +24,9 @@ and concatenates once at the end.
 import hashlib
 import json
 import os
-import shutil
-import subprocess
 import time
 
+import av
 import numpy as np
 import torch
 
@@ -38,15 +37,28 @@ AUDIO_EXT = ".npy"
 META_EXT = ".json"
 LATENT_EXT = ".latent.pt"
 
-
-def _ffmpeg():
-    exe = shutil.which("ffmpeg")
-    if not exe:
-        raise RuntimeError(
-            f"{TAG}: ffmpeg is not on PATH. The hop store needs it to write "
-            f"lossless FFV1. Install ffmpeg or set cache to off."
-        )
-    return exe
+# FFV1 through PyAV, in process. This used to shell out to an `ffmpeg` binary
+# on PATH, which cost two things:
+#
+#   1. The cache -- the feature that makes a tone A/B 14 seconds instead of
+#      164 -- hard-failed with a RuntimeError for anyone who did not happen to
+#      have ffmpeg installed. ComfyUI itself never needs it on PATH, so that is
+#      most users, and the failure landed on the pack's fastest path.
+#   2. The Comfy registry's YARA scan flags every `subprocess` call in a custom
+#      node (`python_command_injection_risk`, "detects ALL os.system and
+#      subprocess usage") with no taint analysis, so a static argument list with
+#      shell=False still flagged all three published versions.
+#
+# `av` is a hard dependency of ComfyUI itself -- SaveVideo and CreateVideo are
+# built on it -- so this trades an optional external binary for a library that
+# is already guaranteed present.
+#
+# The format is deliberately UNCHANGED: ffv1 / rgb48le / level 3 / coder 1 /
+# context 1, in matroska. Verified bit-exact in both directions, so caches
+# written by the old path stay readable and a resumed chain still matches an
+# uninterrupted one.
+FFV1_OPTIONS = {"level": "3", "coder": "1", "context": "1"}
+PIX_FMT = "rgb48le"
 
 
 def tensor_digest(t):
@@ -115,32 +127,35 @@ class HopStore:
         past hop 1.
         """
         n, hgt, wid = int(imgs.shape[0]), int(imgs.shape[1]), int(imgs.shape[2])
+        # The .part suffix defeats extension-based format detection, so the
+        # muxer is named explicitly. Writing to .part and renaming on success
+        # keeps a killed render from leaving a half-file that `has()` trusts.
         vid_tmp = self._p(key, VIDEO_EXT + ".part")
-        cmd = [
-            _ffmpeg(), "-y", "-v", "error",
-            "-f", "rawvideo", "-pix_fmt", "rgb48le",
-            "-s", f"{wid}x{hgt}", "-r", str(self.fps),
-            "-i", "-",
-            "-c:v", "ffv1", "-level", "3", "-coder", "1", "-context", "1",
-            "-pix_fmt", "rgb48le",
-            # The .part suffix defeats extension-based format detection, so the
-            # muxer is named explicitly. Writing to .part and renaming on success
-            # keeps a killed render from leaving a half-file that `has()` trusts.
-            "-f", "matroska", vid_tmp,
-        ]
-        proc = subprocess.Popen(cmd, stdin=subprocess.PIPE,
-                                stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
         try:
-            # Frame at a time: never materialise a second full-size copy.
-            for i in range(n):
-                f = (imgs[i].clamp(0, 1) * 65535.0).round().to(torch.int32)
-                proc.stdin.write(f.numpy().astype("<u2").tobytes())
-            proc.stdin.close()
-        except BrokenPipeError:
-            pass
-        err = proc.stderr.read().decode(errors="replace")
-        if proc.wait() != 0:
-            raise RuntimeError(f"{TAG}: FFV1 encode failed for hop {key}: {err.strip()}")
+            container = av.open(vid_tmp, mode="w", format="matroska")
+            try:
+                stream = container.add_stream("ffv1", rate=self.fps)
+                stream.width, stream.height = wid, hgt
+                stream.pix_fmt = PIX_FMT
+                stream.options = dict(FFV1_OPTIONS)
+                # Frame at a time: never materialise a second full-size copy.
+                for i in range(n):
+                    f = (imgs[i].clamp(0, 1) * 65535.0).round().to(torch.int32)
+                    frame = av.VideoFrame.from_ndarray(
+                        f.numpy().astype("<u2"), format=PIX_FMT)
+                    for packet in stream.encode(frame):
+                        container.mux(packet)
+                for packet in stream.encode():          # flush the encoder
+                    container.mux(packet)
+            finally:
+                container.close()
+        except Exception as e:                          # noqa: BLE001
+            # Leave no .part behind for the next run to trip over.
+            try:
+                os.remove(vid_tmp)
+            except OSError:
+                pass
+            raise RuntimeError(f"{TAG}: FFV1 encode failed for hop {key}: {e}") from e
         os.replace(vid_tmp, self._p(key, VIDEO_EXT))
 
         np.save(self._p(key, AUDIO_EXT),
@@ -203,25 +218,31 @@ class HopStore:
         with open(self._p(key, META_EXT), encoding="utf-8") as fh:
             info = json.load(fh)
         n, hgt, wid = int(info["frames"]), int(info["height"]), int(info["width"])
-        cmd = [
-            _ffmpeg(), "-v", "error", "-i", self._p(key, VIDEO_EXT),
-            "-f", "rawvideo", "-pix_fmt", "rgb48le", "-",
-        ]
-        want = n * hgt * wid * 3 * 2
-        # communicate(), not sequential reads: draining stdout to EOF while
-        # stderr is an unread pipe deadlocks the moment ffmpeg emits more than
-        # the pipe buffer on stderr -- which is exactly what a corrupt FFV1
-        # does, i.e. the one case where the error actually matters.
-        proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
-        raw, err_raw = proc.communicate()
-        err = err_raw.decode(errors="replace")
-        if proc.returncode != 0:
-            raise RuntimeError(f"{TAG}: FFV1 decode failed for hop {key}: {err.strip()}")
-        if len(raw) != want:
+        # Decoded straight into one preallocated array rather than a list of
+        # frames: the meta file already states the geometry, so the destination
+        # is known up front and there is never a second full-size copy to stack.
+        arr = np.empty((n, hgt, wid, 3), dtype=np.uint16)
+        seen = 0
+        try:
+            container = av.open(self._p(key, VIDEO_EXT))
+            try:
+                for frame in container.decode(container.streams.video[0]):
+                    if seen >= n:                      # more frames than meta
+                        seen += 1
+                        break
+                    arr[seen] = frame.to_ndarray(format=PIX_FMT)
+                    seen += 1
+            finally:
+                container.close()
+        except Exception as e:                         # noqa: BLE001
+            raise RuntimeError(f"{TAG}: FFV1 decode failed for hop {key}: {e}") from e
+        if seen != n:
+            # Same contract as the old byte-count check: a truncated or
+            # over-long cache entry is a hard error, not a short clip, because
+            # a hop silently missing its tail would poison every hop after it.
             raise RuntimeError(
-                f"{TAG}: cached hop {key} is {len(raw)} bytes, expected {want}. "
+                f"{TAG}: cached hop {key} decoded {seen} frame(s), expected {n}. "
                 f"Delete the cache entry and re-render.")
-        arr = np.frombuffer(raw, dtype="<u2").reshape(n, hgt, wid, 3)
         imgs = torch.from_numpy(arr.astype(np.float32) / 65535.0)
         wav = torch.from_numpy(np.load(self._p(key, AUDIO_EXT)))
         os.utime(self._p(key, VIDEO_EXT), None)  # LRU touch

tools/notes.py

@@ -350,7 +350,7 @@ write negations. Skim the beats before queueing.
 ## Fixing one hop without re-rendering the rest
 
 Set **`cache_hops` to `on` before your first run.** It is off by default, and a
-hop that was never cached cannot be reused. Needs `ffmpeg` on PATH.
+hop that was never cached cannot be reused. Nothing to install.
 
 The cache key **chains**, so editing shot 5 of 8 re-renders 5 to 8 and reuses 1
 to 4 off disk. Hop 6 was rendered *from* hop 5, so it has to. **Edit the

workflows/HandTieClips_Starter.json

@@ -1378,7 +1378,7 @@
         "htc_card": "author"
       },
       "widgets_values": [
-        "## Let a model write your plan\n\n`prompt_pack/` in the pack folder turns any chat model into a plan writer. In\nLM Studio, or anything with a system-prompt box:\n\n1. Load a model with **context 16384 or more**. The prompt is ~4,700 tokens and\n   the reply another 1,000-2,000; a small window truncates the rules and you get\n   invented directive names.\n2. Paste **`prompt_pack/SYSTEM_PROMPT.md`** into the **System Prompt** box.\n   Nothing else goes in that box.\n3. **Temperature 0.3-0.5.** Higher and the JSON grows trailing commas and smart\n   quotes.\n4. Describe the scene, and say how many hops and what pictures you have:\n\n   > Six hops. A cook in a kitchen; she says one line, walks out into a hallway,\n   > waits by a window, then comes back. I have a face photo, a photo of her\n   > apron, and a photo of the kitchen.\n\n5. Each panel section has its own **JSON** disclosure at the bottom. The first\n   ```json``` block goes in the one under **SCRIPT** (`shot_plan`), the second\n   in the one under **REFERENCES** (`ref_plan`). Bad JSON keeps the last good\n   version on screen and says so, rather than discarding your paste.\n6. **If the node rejects it, paste the error straight back into the chat.** One\n   round trip usually fixes it.\n\nWant it to match a shape? Paste `prompt_pack/EXAMPLE_6_HOP.md` first.\n\nSmall models (7B-8B) hold the JSON schema but drift on the prose rules -- they\nwrite negations. Skim the beats before queueing.\n\n## Fixing one hop without re-rendering the rest\n\nSet **`cache_hops` to `on` before your first run.** It is off by default, and a\nhop that was never cached cannot be reused. Needs `ffmpeg` on PATH.\n\nThe cache key **chains**, so editing shot 5 of 8 re-renders 5 to 8 and reuses 1\nto 4 off disk. Hop 6 was rendered *from* hop 5, so it has to. **Edit the\nearliest hop you dislike and work forward** -- that way each hop is paid for\nonce.\n\nAnything chain-wide re-renders everything: resolution, aspect, overlap, sampler,\nscheduler, either shift, `ref_image_size`, `pin_to_qwen`, the LoRA stack, or\n**any reference picture** (keyed on pixels, so a re-crop counts even under the\nsame filename). That is the usual reason the cache looks broken.\n\nLoved a hop? Put `\"locked\": true` and a stable `\"id\"` on that shot and it keeps\nthat exact take even when its inputs move. Unrelated to `subjects.N.locked`,\nwhich is identity text.\n\nFull detail in `PROMPTING.md`, under *Re-rolling one hop*."
+        "## Let a model write your plan\n\n`prompt_pack/` in the pack folder turns any chat model into a plan writer. In\nLM Studio, or anything with a system-prompt box:\n\n1. Load a model with **context 16384 or more**. The prompt is ~4,700 tokens and\n   the reply another 1,000-2,000; a small window truncates the rules and you get\n   invented directive names.\n2. Paste **`prompt_pack/SYSTEM_PROMPT.md`** into the **System Prompt** box.\n   Nothing else goes in that box.\n3. **Temperature 0.3-0.5.** Higher and the JSON grows trailing commas and smart\n   quotes.\n4. Describe the scene, and say how many hops and what pictures you have:\n\n   > Six hops. A cook in a kitchen; she says one line, walks out into a hallway,\n   > waits by a window, then comes back. I have a face photo, a photo of her\n   > apron, and a photo of the kitchen.\n\n5. Each panel section has its own **JSON** disclosure at the bottom. The first\n   ```json``` block goes in the one under **SCRIPT** (`shot_plan`), the second\n   in the one under **REFERENCES** (`ref_plan`). Bad JSON keeps the last good\n   version on screen and says so, rather than discarding your paste.\n6. **If the node rejects it, paste the error straight back into the chat.** One\n   round trip usually fixes it.\n\nWant it to match a shape? Paste `prompt_pack/EXAMPLE_6_HOP.md` first.\n\nSmall models (7B-8B) hold the JSON schema but drift on the prose rules -- they\nwrite negations. Skim the beats before queueing.\n\n## Fixing one hop without re-rendering the rest\n\nSet **`cache_hops` to `on` before your first run.** It is off by default, and a\nhop that was never cached cannot be reused. Nothing to install.\n\nThe cache key **chains**, so editing shot 5 of 8 re-renders 5 to 8 and reuses 1\nto 4 off disk. Hop 6 was rendered *from* hop 5, so it has to. **Edit the\nearliest hop you dislike and work forward** -- that way each hop is paid for\nonce.\n\nAnything chain-wide re-renders everything: resolution, aspect, overlap, sampler,\nscheduler, either shift, `ref_image_size`, `pin_to_qwen`, the LoRA stack, or\n**any reference picture** (keyed on pixels, so a re-crop counts even under the\nsame filename). That is the usual reason the cache looks broken.\n\nLoved a hop? Put `\"locked\": true` and a stable `\"id\"` on that shot and it keeps\nthat exact take even when its inputs move. Unrelated to `subjects.N.locked`,\nwhich is identity text.\n\nFull detail in `PROMPTING.md`, under *Re-rolling one hop*."
       ],
       "color": "#432",
       "bgcolor": "#653"