Upload 42 files

custom_nodes/ComfyUI-Nugget/README.md

@@ -0,0 +1,525 @@
+# Nugget
+
+Three nodes for ComfyUI, all under **Nugget** in the node menu.
+
+| node | what it does |
+|---|---|
+| **Video Auto Transcriber** | Describes a short video shot by shot, with cut times read from the file, camera movement measured rather than guessed, and dialogue transcribed into the shot it was spoken in. |
+| **Batch images (no crop)** | Batches up to 9 images into one tensor by padding instead of centre-cropping. Sockets appear as you connect them. |
+| **Pad image to size (no crop)** | Letterboxes one image to an exact size. |
+
+---
+
+## Video Auto Transcriber
+
+One node. Give it a short video, get back what actually happens in it — shot by
+shot, with cut times read from the file rather than guessed, camera movement
+measured rather than described, and any dialogue transcribed and placed in the
+shot it was spoken in.
+
+```
+Load CLIP  ─┐                              ┌─ full description
+Load Video ─┴─> [Video Auto Transcriber] ──┼─ overview
+                                           ├─ characters identified
+                                           ├─ shots
+                                           ├─ audio transcription
+                                           └─ audio language
+```
+
+It uses the text encoder ComfyUI already has loaded. No second server, no API
+key, nothing to start before you queue.
+
+---
+
+## Setup, in order
+
+**1. Install the pack.** Drop the folder into `ComfyUI/custom_nodes` and restart.
+
+**2. Run the installer.** It finds the Python ComfyUI actually uses, so it does
+not matter which one is on your PATH:
+
+```
+python install.py
+```
+
+Windows: double-click `install.bat`.
+
+This is not optional if you want dialogue. faster-whisper does not ship with
+ComfyUI, and the most common reason it still reports as missing after you
+install it is that `pip` went to your system Python while ComfyUI runs its own.
+The installer detects that and re-runs itself in the right interpreter.
+
+It also **builds a real model and transcribes a second of silence** to prove it
+works, because a successful import proves nothing — CTranslate2 loads its CUDA
+libraries only when a model is constructed.
+
+`python install.py --check` reports without changing anything.
+
+**3. Download a text encoder.** The `clip` input needs a **language model**, not
+an image-generation text encoder. Pick one:
+
+| model | file | size | notes |
+|---|---|---|---|
+| Gemma 4 E4B | [`gemma4_e4b_it_fp8_scaled.safetensors`](https://huggingface.co/Comfy-Org/gemma-4/tree/main/text_encoders) | 9.1 GB | ComfyUI's own default. **Start here on a 16 GB card.** |
+| Qwen3-VL 8B | [`qwen3vl_8b_nvfp4.safetensors`](https://huggingface.co/Comfy-Org/Qwen3-VL/tree/main/text_encoders) | 6.3 GB | Most headroom of the 8B builds |
+| Qwen3-VL 8B | [`qwen3vl_8b_fp8_scaled.safetensors`](https://huggingface.co/Comfy-Org/Qwen3-VL/tree/main/text_encoders) | 10.6 GB | Alternative family |
+| Qwen3-VL 4B | [`qwen3vl_4b_fp8_scaled.safetensors`](https://huggingface.co/Comfy-Org/Qwen3-VL/tree/main/text_encoders) | ~5 GB | For 8 GB cards |
+| Gemma 4 12B | [`gemma4_12b_int8_convrot.safetensors`](https://huggingface.co/Comfy-Org/gemma-4/tree/main/text_encoders) | 12.1 GB | Wants 20 GB+ in practice — see below |
+
+All go in `ComfyUI/models/text_encoders/`. Restart, then select the file in
+**Load CLIP**. ComfyUI works out the model type from the file itself, so the
+type dropdown rarely matters; picking the wrong file is what does.
+
+Both model families' chat markers are stripped from the output, so either works
+with no configuration.
+
+**Weights are not the whole cost.** On a 16 GB card a 12.1 GB encoder leaves
+under 4 GB for the vision tower, the activations and the KV cache — and this
+node sends images on *every* call, which is the expensive path. It loads, then
+dies part way through with no Python traceback. Subtract the file size from your
+VRAM and want about 6 GB left, not 4. The node logs free VRAM before the encoder
+loads and warns below 5 GB.
+
+Avoid abliterated or "uncensored" repacks. They damage special-token handling,
+which shows up as pages of `<think></think>` and `<|image>` in the output.
+
+---
+
+## Why not just point the built-in node at a video
+
+ComfyUI's `Generate Text` node has a `video` input. Its own tooltip says:
+
+> Video frames as image batch. Assumed to be 24 FPS; subsampled to 1 FPS internally.
+
+One frame per second cannot tell a cut from a camera move. Feed it a 14-second
+clip and it sees 12 stills, then reports 12 shots — one per still, each
+conveniently a second long. A slow crane from someone's boots to their face
+comes back as five separate shots.
+
+This node finds the cuts first, then shows the model several frames from inside
+each shot, passed as an image batch so the 1 FPS subsampling never applies.
+
+## Settings
+
+| | |
+|---|---|
+| **prompt max length** | Token budget for each shot description. `0` (the default) follows **description detail** — 160 / 300 / 500. Raise it if descriptions stop mid-sentence. The overview and character passes scale with it. |
+| **description detail** | `brief` / `normal` / `detailed`. Sets how much is written per shot and how many frames the model sees. The frame count scales with shot length, so a half-second shot is not padded with near-identical frames and a ten-second one is not left with six-second gaps. |
+| **scene sensitivity** | Cut detection. Raise if shots are being missed, lower if one shot is being split in two. |
+| **min shot** | Shortest shot allowed, in seconds. Two cuts closer than this become one — so a high value *throws cuts away*. Fast-cut music video: `0.5`. Interviews: `5` is fine. |
+| **max frame size** | Maximum width frames are scaled to. A **ceiling, not a target** — a 640-wide source stays 640 even at 1024, because upscaling invents no detail while still costing vision tokens. Drop to 512 for speed, raise to 1024 if fine detail or on-screen text is being missed. |
+| **frame layout** | *(advanced)* `grid` composites each beat's frames into one image — much cheaper, and shows motion at a glance. `separate` sends individual images: more spatial detail per frame, several times slower. |
+| **whisper model** | Speech model. `large-v3` by default. `off` skips audio entirely — useful for clips with no dialogue, and for isolating whether a problem is in the speech half or the vision half. |
+| **audio language** | Named languages, not codes. Leave on `auto` unless detection keeps guessing wrong. |
+| **seed** | *(advanced)* Only used if you raise temperature in `llm.py`. Output is greedy and repeatable by default. |
+
+Temperature, top_k, top_p, min_p, both penalties, thinking mode and the chat
+template are fixed in `llm.py`. For a description task each has one correct
+value, and putting them on the node face would only be nine more ways to get a
+worse answer. The repetition penalty in particular is set to 1.0 on purpose:
+shot descriptions are *supposed* to repeat "the man", "the camera", "green
+jacket", and penalising that makes the model invent variation that reads as real
+change.
+
+## Output
+
+```
+overview: Warm low sunlight, high contrast, steady unhurried pace.
+
+characters identified:
+a man in an olive puffer jacket and black beanie
+
+shots:
+
+[Shot 1] From 00:00.000 to 00:04.800, a wide aerial view of a sunlit snowy
+ridge, a lone figure on the skyline; the camera is locked off.
+
+[Shot 2] From 00:04.800 to 00:08.828, the man stands in profile, breath vapour
+visible against jagged peaks; the camera pans right.
+    speech 00:05.100-00:06.400: "It took us nine hours to get up here."
+
+[Shot 3] From 00:08.828 to 00:13.714, the frame starts on his boots and rises
+to his face as he folds his arms and smiles; the camera tilts up.
+
+audio: speech in English (98% confidence)
+```
+
+**full description** is the block above — the thing you will usually wire onward.
+
+**overview**, **characters identified** and **shots** are the same content as
+separate strings, so a downstream node that wants only one part does not have to
+parse it back out of a formatted block.
+
+**audio transcription** is the dialogue on its own with timings, so it can be
+reformatted without re-running the vision passes.
+
+**audio language** is the detected language name (`English`, `Japanese`,
+`French`) or `none` when nothing was said. It exists so a downstream prompt
+writer can tag dialogue without parsing it back out — MiniMax H3, for instance,
+wants spoken lines as `<d>[English] ...</d>`.
+
+## Switching it off
+
+Bypass the **Load Video** node (Ctrl+B), or delete the link into `video`, and
+this node does nothing: no error, no model load, six empty strings out.
+
+Bypass is the fiddly one. Bypassing a node makes it pass through a reference to
+whatever is on its own inputs — and Load Video has no VIDEO input to pass
+through, so what arrives here is not a VIDEO. ComfyUI's own check then rejects
+the entire prompt with *"Return type mismatch between linked nodes"* **before any
+node runs**, which nothing inside the node can catch. So the node opts out of
+that check for `video` specifically and decides for itself, treating anything
+that cannot name a file on disk as "switched off".
+
+If your ComfyUI is old enough that bypass still fails, **delete the link instead
+of bypassing**. An unconnected optional input has nothing to type-check.
+
+The outputs are empty rather than a placeholder like `no video` on purpose: they
+usually feed a string join on the way into a prompt, and anything non-empty would
+end up inside it.
+
+A missing `clip` still errors, because that is a wiring mistake rather than a
+deliberate switch-off.
+
+## How the cuts are found
+
+Colour histograms of 64×64 thumbnails, twelve per second, compared frame to
+frame. Histograms rather than pixel differences on purpose: a mean pixel
+difference reacts strongly to camera movement, so a crane or a whip pan scores
+like a cut. On the test footage, switching to histograms widened the gap between
+the weakest true cut and the strongest false positive from 1.5× to 2.4×.
+
+The threshold is per-neighbourhood (`median + k·MAD`, with a floor and a ratio
+term), because three equally hard cuts in one clip can score 0.43, 0.17 and 0.12
+— any single cutoff either misses the weak one or floods on noise.
+
+Candidates are then accepted **strongest first**, not earliest first. This is the
+part that matters and the part that is easy to get wrong. Walking the list in
+time order and keeping anything far enough from the last accepted cut looks
+reasonable and quietly isn't: a weak false positive a fraction of a second early
+claims the slot, and the real cut is rejected for being too close to it. On real
+footage the two strongest scores in the entire file were both discarded that way
+in favour of noise scoring a quarter as high. Sorting by score first — ordinary
+non-maximum suppression — recovers both exactly.
+
+Both ends of the clip are held to at least a one-second minimum whatever
+`min shot` says, so neither an opening flicker nor a fade to black produces a
+sliver shot.
+
+## Camera movement is measured, not guessed
+
+A vision model shown a handful of stills cannot tell a pan from a cut, or a
+push-in from a subject walking closer. Ask it in the prompt and you get
+confident wrong answers — "the camera remains stationary" over a crane shot is
+the usual one.
+
+So the movement is measured and handed to the model as fact. Translation comes
+from phase correlation between frames; zoom comes from whether the quadrants
+diverge, since in a push-in the left half drifts left and the right half drifts
+right while the global shift stays near zero.
+
+On the test clip, whose third shot is a crane from a man's boots up to his face:
+
+```
+Shot 1 (0.00-4.80):  the camera is locked off and does not move
+Shot 2 (4.80-8.83):  the camera pans right
+Shot 3 (8.83-13.71): the camera pans right and tilts up
+```
+
+It costs nothing extra — the numbers come out of the same decode pass that finds
+the cuts.
+
+## Characters
+
+One pass lists the characters — people and animals — and that list is handed to
+**every** shot pass. That is the entire reason it is worth generating: it is what
+lets shot 4 say "the man" and mean the same man as shot 2.
+
+There are no `Man A` / `Woman A` labels. On their own the label carries no more
+information than the description next to it. A clip with no characters — a
+landscape, a product shot, an abstract animation — returns nothing and the
+section is omitted.
+
+**Repeats are merged.** The context frames deliberately span every shot, so the
+model sees the same person in several framings and often describes each one:
+
+```
+a man in a green jacket
+a man in an olive puffer jacket and black beanie
+a man wearing a dark beanie and green puffer jacket
+```
+
+Those are one man. Entries whose distinguishing words overlap enough are
+collapsed, keeping the fullest description. The merge repeats until nothing more
+combines, because replacing an entry with a longer description gives it more
+words, which can reveal a match the short version hid. A man and a woman, or a
+man and a dog, stay separate.
+
+## Long shots
+
+A cut is not the only thing worth timing. A twenty-second continuous take has
+just as much happening in it as four five-second shots, and describing it in one
+pass gives it the same handful of frames and the same two sentences a short shot
+gets — everything between the samples is lost.
+
+So a shot longer than its detail level's limit is described in **beats**, each
+with its own times:
+
+```
+[Shot 1] From 00:00.000 to 00:20.000:
+    00:00.000 - 00:06.667  he steps into frame and starts walking left...
+    00:06.667 - 00:13.333  the camera pushes in as he stops and turns...
+    00:13.333 - 00:20.000  he looks off-screen right; the light drops...
+```
+
+A twenty-second take at `normal` becomes 3 beats and 27 frames rather than 1
+description and 9 frames. Beats after the first are told they are continuing the
+same shot and to describe what *changes*, so you get progression rather than the
+same scene restated three times. A shot only slightly over the limit is left
+whole — splitting seven seconds into six plus one gives a one-second beat that
+says nothing.
+
+This is the partition-and-summarise approach from
+[LVD-2M](https://arxiv.org/abs/2410.10816).
+
+## Frame grids
+
+Each beat's frames are composited into a single image, read left to right then
+top to bottom. Six frames cost roughly what one image costs, which is what makes
+the dense sampling above affordable — and the model sees the whole progression
+laid out at once instead of as a sequence it has to hold in mind.
+
+This comes from [IG-VLM](https://arxiv.org/abs/2403.18406), which found
+image-pretrained VLMs read grids zero-shot with no video training, and
+[Video Panels](https://arxiv.org/abs/2509.23724), which confirmed it across five
+benchmarks and several model families. Both frame it as trading spatial detail
+for temporal resolution — the right trade when the thing you are describing is
+motion.
+
+At the default `max frame size` of 768 a six-panel grid gives each frame 256×192,
+which stays legible enough to read on-screen text. If detail is being missed,
+raise `max frame size` before switching to `separate`.
+
+## Length
+
+Nothing caps the assembled description, but every model call has a token budget,
+and generation simply stops when it runs out — mid-sentence if that is where the
+budget lands. Defaults are 160 / 300 / 500 tokens per shot by detail level, 120
+for the overview, 200 for the character list.
+
+Since there is no truncation flag to read, the tell is a description ending
+without terminal punctuation. When that happens the log says so and names the
+budget it hit, so you know to raise **prompt max length**.
+
+Worth remembering that a long shot is split into beats, each with its own full
+budget — a 20-second single take at `normal` is three beats, so 900 tokens, not
+300.
+
+## Re-running without re-transcribing
+
+ComfyUI skips any node whose inputs have not changed, so once a clip is
+transcribed, queueing again costs nothing — change the sampler seed downstream
+and only the sampler re-runs.
+
+That only works if this node's inputs stay put, which is why **the seed here
+does not auto-randomise**. It has no effect on output anyway (generation is
+greedy unless you raise temperature in `llm.py`), so a `randomize` setting would
+change the inputs on every queue, miss the cache, and re-transcribe the whole
+video for nothing. If you set it to `randomize` yourself, that is exactly what
+will happen.
+
+Changing the video, or any setting on this node, does invalidate the cache — as
+it should, because the description genuinely would be different.
+
+To skip transcription entirely, bypass the Load Video node.
+
+## What it does about being slow
+
+Several model calls on a 20-second clip takes a while, so:
+
+- **Frames are decoded once.** Every timestamp the run needs is collected up
+  front and pulled in a single sequential pass. Fetching per shot instead means
+  re-decoding the whole file once per shot.
+- **The transcript is cached** against the audio and the speech settings. Nudging
+  `detail` re-runs the vision passes, which is the point, but it will not re-run
+  a transcription that cannot have changed.
+- **Progress shows on the node**, one step per pass.
+- **Cancel works, including mid-transcription.** ComfyUI cancels by setting a
+  flag, so a node only stops when it next asks. Transcription is by far the
+  longest uninterruptible stretch — `large-v3` on the CPU can spend over a minute
+  on a ten-second clip — so the segment loop polls as faster-whisper yields, and
+  the frame decode polls too. The one thing that cannot be cut short is a single
+  `clip.generate()` call, which is one blocking call into ComfyUI with no hook to
+  poll; those run a few seconds each.
+- **One failed shot does not lose the run.** It is marked in the output and the
+  rest continues.
+
+## Troubleshooting
+
+| symptom | cause |
+|---|---|
+| `'SD1ClipModel' object has no attribute 'generate'` | Load CLIP is loading a Stable Diffusion text encoder, not a language model. An SD1 encoder is ~235 MB; the log line `Model SD1ClipModel prepared ... 235MB Staged` is the giveaway. Download one of the encoders above. |
+| ComfyUI **exits** with a code instead of showing an error | Native crash — almost always VRAM. Check the `GB free before loading the text encoder` line in the log. Use a smaller encoder. |
+| `Library cublas64_12.dll is not found` | Windows only, and the package is probably installed. pip puts the DLL in `site-packages/nvidia/...`, which Python has not searched since 3.8. The node registers those folders itself now. |
+| Transcript says faster-whisper is missing after installing it | It went into the wrong Python. Run `install.py`. |
+| Shot descriptions stop mid-sentence | Raise **prompt max length**. The log warns when this happens. |
+| One shot reported as several | Raise **min shot**, or lower **scene sensitivity**. |
+| Several shots reported as one | Raise **scene sensitivity**. |
+| Dialogue invented over music | Set **whisper model** to `off`. `large-v3` hallucinates on non-speech audio; VAD suppresses most of it but not all. |
+
+### A note on CUDA versions
+
+faster-whisper is built on CTranslate2, which is compiled against **CUDA 12**.
+If your torch is built against a different CUDA, speech runs on the CPU and no
+CUDA libraries are registered at all. Putting two CUDA runtimes in one process
+does not raise an exception — it kills the process. On a 20-second clip the GPU
+saves a few seconds; it is not worth a crash.
+
+## Hardware
+
+Tested on: RTX 5060 Ti 16 GB, CUDA speech.
+
+| | |
+|---|---|
+| **NVIDIA, 12 GB+** | Everything on the GPU. |
+| **NVIDIA, 8 GB** | Use Qwen3-VL 4B or Gemma 4 E2B. Speech falls back to CPU. |
+| **AMD / ROCm** | Vision on the GPU, **speech on CPU always** — CTranslate2 has no ROCm backend. |
+| **Apple Silicon** | Same: vision on MPS, speech on CPU. No Metal backend either. |
+| **CPU only** | Works. Slowly. |
+
+Speech on CPU with `large-v3` at int8 is roughly 25–40 seconds for a 20-second
+clip. Annoying, not broken. Drop to `medium` or `small` if that matters.
+
+**Requires ComfyUI v0.15.0 or newer** — that is when `clip.generate()` arrived.
+Older builds get a clear error rather than an AttributeError.
+
+## Nothing here censors the output
+
+Filtering is assumed to happen outside this node, so nothing inside it filters
+again. There is no word list, no blocklist, no content check, and no prompt
+wording that steers the model toward tamer descriptions. The test suite asserts
+all three and fails if any of them changes.
+
+Exactly three things discard model output, none of them content-based:
+
+- **Control tokens.** `<think>`, `<|im_start|>`, `<|image>`, `<|turn>` and the
+  rest of Gemma's and Qwen's chat markers. Core's own node leaves these in,
+  which is why raw use of it produces pages of `<think></think>`.
+- **A truncated reasoning trace.** If generation opens `<think>` and runs out of
+  budget before closing it, there is no answer — only a half-finished thought —
+  and returning it as the description would be worse than returning nothing.
+- **Duplicate character entries.** The same person described twice in different
+  framings is merged, keeping the fullest description. Content-agnostic: it
+  matches on word overlap, not on what the words are.
+
+What the *model* will do is a separate matter. A safety-tuned encoder may decline
+to describe some footage however the prompt is written, and Whisper has its own
+opinions about what it transcribes. Neither is something this node can undo —
+that is a question of which encoder you load.
+
+## Known limits
+
+- **Under 2 minutes.** Longer clips are refused with a message rather than
+  running for twenty minutes and running out of memory.
+- **No speaker diarisation.** Two people talking gives you the words but not who
+  said them.
+- **Whisper on music.** `large-v3` invents dialogue over music and room tone.
+  Silero VAD is on by default and `condition_on_previous_text` is off, which
+  suppresses most of it, and a language confidence under 50% is reported as
+  uncertain rather than asserted. It is not a complete fix.
+- **Speech crossing a cut** is assigned to whichever shot it spends most of
+  itself in, so it is listed once rather than under both.
+- **Variable frame rate** is detected and logged, not corrected. It does not
+  affect the timings here — every time comes from the frame's own timestamp.
+- **HEVC and AV1** depend on your PyAV build.
+
+## Tests
+
+```
+python tests/run_all.py
+```
+
+Around 270 tests across three suites, no GPU, no model, no network.
+
+`pip install pyflakes` adds an undefined-name gate to the registration suite.
+Two bugs have shipped that Python only raises when the offending line runs — a
+`NODES` list broken by a find-and-replace, and a stale variable in a log call
+that fired only after the first generation finished. Neither is a syntax error.
+That check catches both. The video tests build their own clip
+with PyAV. The detection tests include the non-maximum-suppression case above,
+and the token-stripping tests include the exact runaway output that motivated
+them.
+
+---
+
+# Batch images (no crop)
+
+ComfyUI's IMAGE type is one tensor shaped `(batch, height, width, channels)`, so
+every image in a batch must share a height and a width. KJNodes'
+`ImageBatchMulti` resolves that by scaling images 2..N to match image 1 and
+centre-cropping the overflow — fine for images of the same shape, destructive for
+anything else. A portrait dropped into a landscape slot 1 loses its top and
+bottom, which is where a face usually is.
+
+This pads instead. Every image is scaled to *fit* the canvas and the remainder
+filled, so nothing is cropped and nothing is stretched.
+
+**The canvas is the smallest box that holds every input**, then scaled down to
+your ceiling preserving that box's aspect ratio. Which means a set that needs no
+padding gets none:
+
+| input | canvas | bars |
+|---|---|---|
+| one 1920×1080 | 1024×576 | 0% |
+| three identical portraits | 701×1024 | 0% |
+| one 4000×100 panorama | 1024×26 | 0% |
+| portrait + landscape | 1024×1024 | 32% each |
+
+Only genuinely mixed shapes cost anything, and there padding is the better
+failure — you can raise resolution to offset wasted tokens, you cannot recover a
+cropped face.
+
+Sockets appear one at a time as you fill them, up to nine, and compact
+themselves: disconnect `image_2` of three and `image_3` slides down. That keeps
+the numbers lined up with `<Picture N>` in an H3 prompt.
+
+**Bypassing a Load Image is different from disconnecting it.** Bypass leaves the
+link in place and delivers nothing, so the socket still looks wired while no
+image arrives. Nothing errors — the empty socket is skipped — but everything
+after it shifts up, so `image_4` becomes picture 2. A prompt written against
+`<Picture 4>` then names an image the model never saw. The console says so when
+it happens:
+
+```
+[Nugget] image_2, image_3 are empty (bypassed?), so the remaining references
+were renumbered: image_1 is picture 1, image_4 is picture 2. A prompt naming a
+higher picture number will not match.
+```
+
+Disconnect rather than bypass if the numbering matters — the sockets then
+compact on the canvas and what you see is what the model gets.
+
+Outputs are the batch, a `content_mask` marking the real pixels, the canvas
+width and height, and a `padding_report` naming how much of each image is bars.
+Heavy padding means your references disagree about shape, and the fix is
+upstream — crop them to a common aspect before loading.
+
+`max width` / `max height` are a ceiling, never a target. The canvas also never
+exceeds the largest input, so a 16384 ceiling with 64×64 images still gives a
+64×64 canvas.
+
+# Pad image to size (no crop)
+
+The same letterboxing for a single image, against an exact size rather than a
+ceiling. Useful in front of any node that demands a fixed resolution.
+
+---
+
+## Credits
+
+The workflow these were built for is a modified variant of **mackyb**'s H3
+prompt enhancer. These nodes are independent of it and work in any graph.
+
+## Licence
+
+MIT.

custom_nodes/ComfyUI-Nugget/__init__.py

@@ -0,0 +1,76 @@
+"""
+@author: Nugget
+@title: Nugget
+@nickname: Nugget
+@description: Video auto transcription with measured cuts and camera movement, plus image batching that never crops.
+
+The tags above are how ComfyUI-Manager labels the badge in a node's top-right
+corner. Without a @nickname it truncates @title to 20 characters; without either
+the badge shows nothing recognisable.
+
+Registration is deliberately defensive in two layers. Each node module is
+imported on its own, so a failure in one does not take the others down -- if the
+image nodes cannot load, the transcriber still registers, and vice versa. And if
+everything fails, the pack logs the traceback and exposes no entrypoint, so
+ComfyUI skips it rather than failing to start.
+
+**This module must not define ``NODE_CLASS_MAPPINGS``, not even as an empty
+dict.** ComfyUI's loader reads::
+
+    if hasattr(module, "NODE_CLASS_MAPPINGS") and getattr(...) is not None:
+        ...
+    elif hasattr(module, "comfy_entrypoint"):
+        ...
+
+so the mere presence of the attribute takes the older branch and
+``comfy_entrypoint`` is never reached. Every node here is an ``io.ComfyNode``
+subclass with no ``INPUT_TYPES``, so that branch would register broken nodes.
+This is also why the image nodes were converted from the older style rather than
+being merged in as they were: the two registration mechanisms cannot coexist in
+one package.
+
+To remove the pack, delete this folder.
+"""
+
+import importlib
+import logging
+import traceback
+
+log = logging.getLogger("Nugget")
+
+__version__ = "1.1.0"
+
+# Served to the browser for the auto-expanding image sockets. Read separately
+# from node registration, so it works alongside comfy_entrypoint.
+WEB_DIRECTORY = "./web/js"
+
+_NODES = []
+
+for _module, _label in (("nodes_transcribe", "transcriber"),
+                        ("nodes_motion", "motion transfer"),
+                        ("nodes_prompt", "prompt"),
+                        ("nodes_image", "image")):
+    try:
+        _mod = importlib.import_module(f".{_module}", __name__)
+        _NODES.extend(_mod.NODES)
+    except Exception:
+        log.error("[Nugget] the %s nodes failed to load and were skipped:\n%s",
+                  _label, traceback.format_exc())
+
+if _NODES:
+    log.info("[Nugget] v%s loaded: %s", __version__,
+             ", ".join(sorted(c.__name__ for c in _NODES)))
+
+    from comfy_api.latest import ComfyExtension
+
+    class NuggetExtension(ComfyExtension):
+        async def get_node_list(self):
+            return list(_NODES)
+
+    async def comfy_entrypoint():
+        return NuggetExtension()
+
+    __all__ = ["comfy_entrypoint", "WEB_DIRECTORY"]
+else:
+    log.error("[Nugget] no nodes could be loaded; registering nothing")
+    __all__ = ["WEB_DIRECTORY"]

custom_nodes/ComfyUI-Nugget/camera.py

@@ -0,0 +1,123 @@
+"""Measuring camera movement, instead of asking the model to guess it.
+
+A vision model shown a handful of stills has no reliable way to tell a pan from
+a cut, or a push-in from a subject walking closer. Asking it to describe camera
+movement in the prompt produces confident, frequently wrong answers -- "the
+camera remains stationary" over a crane shot being the usual one.
+
+So the movement is measured instead, and the measurement is handed to the model
+as fact.
+
+**Translation** comes from phase correlation: multiply the two frames' Fourier
+transforms, normalise to unit magnitude, invert, and the brightest point is the
+shift between them. It is robust to brightness changes and cheap, and it locks
+onto the dominant global motion rather than any one moving object.
+
+**Zoom** comes from whether the quadrants diverge. In a push-in the left half
+drifts left and the right half drifts right while the global shift stays near
+zero; in a pan every quadrant moves the same way. Comparing quadrant shifts to
+each other separates the two without any explicit scale search.
+
+Note the sign convention throughout: this reports where the *image content*
+went, and the camera moved the opposite way. Content sliding down means the
+camera tilted up.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+# Frame edge used for correlation. 64 is too coarse to see a slow drift -- a
+# gentle pan over five seconds rounds to zero pixels -- and 256 costs more than
+# the extra precision is worth.
+SIZE = 128
+
+# Fractions of frame width, accumulated across the window.
+PAN_THRESHOLD = 0.18
+ZOOM_THRESHOLD = 0.25
+
+# Above this ratio of path length to net displacement, the camera wandered
+# rather than travelled: handheld, or a move that reverses.
+SHAKE_RATIO = 2.5
+
+
+def _shift(a: np.ndarray, b: np.ndarray) -> tuple[int, int]:
+    """Displacement of image content from ``a`` to ``b``, in pixels."""
+    fa, fb = np.fft.fft2(a), np.fft.fft2(b)
+    cross = fa * np.conj(fb)
+    magnitude = np.abs(cross)
+    magnitude[magnitude < 1e-9] = 1e-9
+    surface = np.fft.ifft2(cross / magnitude).real
+
+    dy, dx = np.unravel_index(int(np.argmax(surface)), surface.shape)
+    height, width = a.shape
+    if dy > height // 2:
+        dy -= height
+    if dx > width // 2:
+        dx -= width
+    return -int(dx), -int(dy)
+
+
+def step(a: np.ndarray, b: np.ndarray) -> tuple[float, float, float]:
+    """(dx, dy, zoom) between two greyscale frames, in pixels."""
+    gx, gy = _shift(a, b)
+
+    height, width = a.shape
+    half_h, half_w = height // 2, width // 2
+    corners = {
+        "tl": (slice(0, half_h), slice(0, half_w)),
+        "tr": (slice(0, half_h), slice(half_w, width)),
+        "bl": (slice(half_h, height), slice(0, half_w)),
+        "br": (slice(half_h, height), slice(half_w, width)),
+    }
+    quadrant = {name: _shift(a[box], b[box]) for name, box in corners.items()}
+
+    # A quadrant shift larger than half its own size means the correlation peak
+    # wrapped and the number is meaningless. Large pans do this, and trusting it
+    # invents a zoom that is not there.
+    limit = min(half_h, half_w) / 2
+    if any(abs(x) > limit or abs(y) > limit for x, y in quadrant.values()):
+        return float(gx), float(gy), 0.0
+
+    spread_x = ((quadrant["tr"][0] + quadrant["br"][0])
+                - (quadrant["tl"][0] + quadrant["bl"][0])) / 2.0
+    spread_y = ((quadrant["bl"][1] + quadrant["br"][1])
+                - (quadrant["tl"][1] + quadrant["tr"][1])) / 2.0
+    return float(gx), float(gy), (spread_x + spread_y) / 2.0
+
+
+def summarise(motion, start: float, end: float) -> str:
+    """A plain phrase for the camera movement between two times.
+
+    ``motion`` is [(time, dx, dy, zoom), ...] as produced during the scan.
+    """
+    window = [m for m in motion if start <= m[0] < end]
+    if len(window) < 2:
+        return ""
+
+    net_x = sum(m[1] for m in window) / SIZE
+    net_y = sum(m[2] for m in window) / SIZE
+    net_z = sum(m[3] for m in window) / SIZE
+    path = sum(abs(m[1]) + abs(m[2]) for m in window) / SIZE
+    net = abs(net_x) + abs(net_y)
+
+    parts: list[str] = []
+    if abs(net_x) >= PAN_THRESHOLD:
+        # Content moving right means the camera swung left.
+        parts.append("pans left" if net_x > 0 else "pans right")
+    if abs(net_y) >= PAN_THRESHOLD:
+        parts.append("tilts up" if net_y > 0 else "tilts down")
+    if abs(net_z) >= ZOOM_THRESHOLD:
+        parts.append("pushes in" if net_z > 0 else "pulls back")
+
+    if not parts:
+        if path > PAN_THRESHOLD * 2:
+            return "the camera is handheld, drifting slightly without going anywhere"
+        return "the camera is locked off and does not move"
+
+    movement = " and ".join(parts) if len(parts) < 3 else \
+        ", ".join(parts[:-1]) + " and " + parts[-1]
+
+    if net > 0 and path / max(net, 1e-6) > SHAKE_RATIO:
+        return f"the camera {movement}, unsteadily"
+    return f"the camera {movement}"

custom_nodes/ComfyUI-Nugget/detect.py

@@ -0,0 +1,167 @@
+"""Hard-cut detection.
+
+Two decisions in here are worth stating, because both are places the obvious
+implementation gets it wrong.
+
+**The threshold is adaptive, not fixed.** Three equally hard cuts in one clip can
+score 0.43, 0.17 and 0.12. Any single cutoff either misses the weak one or floods
+on noise, so the bar for each candidate is set from its own neighbourhood:
+``median + k*MAD`` with a floor and a ratio-over-median term.
+
+**Candidates are accepted strongest-first, not earliest-first.** This is the part
+that matters. Walking the candidate list in time order and keeping anything far
+enough from the last accepted cut looks reasonable and is quietly wrong: a weak
+false positive a fraction of a second early claims the slot, and the real cut
+gets rejected for being too close to it. Measured on a real clip, the two
+strongest scores in the whole file (0.427 and 0.634) were both discarded that way
+in favour of noise scoring 0.120. Sorting by score first -- ordinary non-maximum
+suppression -- recovers both exactly.
+"""
+
+from __future__ import annotations
+
+import statistics
+from dataclasses import dataclass
+
+# sensitivity -> (k for median + k*MAD, required ratio over the local median)
+# Both knobs move together: on busy footage MAD often is not the binding
+# constraint, so scaling k alone would make the setting do nothing.
+#
+# The ratios are calibrated for the histogram metric in video.py. On the test
+# footage true cuts land at 8x and 14x the local median while the strongest
+# false positive reaches 3.4x, so "normal" sits at 5.5 -- comfortably between
+# the two. Recalibrate these together with the metric, never separately.
+SENSITIVITY = {
+    "low": (6.0, 8.0),
+    "normal": (4.0, 5.5),
+    "high": (2.5, 3.5),
+}
+
+# Absolute floor, so static footage never fires on sensor noise. Kept low on
+# purpose -- a real cut can score under 0.06 in absolute terms while still being
+# 40x its local baseline, and a high floor silently misses those.
+SCORE_FLOOR = 0.015
+
+# Rolling window, in frames, for the adaptive threshold.
+WINDOW = 30
+
+# Two spikes closer together than this are one event, not two. A camera flash
+# scores high going into white and high coming back out.
+FLASH_WINDOW = 0.35
+
+# The very start and end of a clip are held to at least this, whatever min_shot
+# says. A fade to black, a logo sting or a first-frame flicker is a real visual
+# change but not a cut, and at a low min_shot it otherwise produces a half-second
+# shot at the end of every video that has one.
+EDGE_MIN = 1.0
+
+
+@dataclass
+class Shot:
+    index: int
+    start: float
+    end: float
+
+    @property
+    def duration(self) -> float:
+        return max(0.0, self.end - self.start)
+
+
+def candidates(scores, k: float, ratio: float) -> list[dict]:
+    """Local maxima that clear their own neighbourhood's adaptive threshold.
+
+    ``scores`` is [(time, score), ...] in playback order.
+    """
+    values = [s for _, s in scores]
+    n = len(values)
+    if n < 3:
+        return []
+
+    half = WINDOW // 2
+    found: list[dict] = []
+    for i in range(1, n - 1):
+        score = values[i]
+        # Local maximum. Without this one cut yields two or three adjacent
+        # candidates and every downstream rule has to cope with duplicates.
+        if not (score > values[i - 1] and score >= values[i + 1]):
+            continue
+
+        window = values[max(0, i - half):min(n, i + half + 1)]
+        median = statistics.median(window)
+        mad = statistics.median([abs(x - median) for x in window])
+        threshold = max(SCORE_FLOOR, median + k * mad, median * ratio)
+
+        if score >= threshold:
+            found.append({"t": scores[i][0], "score": score, "threshold": threshold})
+    return found
+
+
+def suppress_flashes(found: list[dict]) -> list[dict]:
+    """Drop pairs that are one bright event rather than two cuts.
+
+    Only a genuinely flash-like pair is removed: two spikes inside
+    ``FLASH_WINDOW`` whose scores are within 25% of each other. A real cut
+    followed by unrelated activity has a much larger score gap, and non-maximum
+    suppression below handles that case on its own.
+    """
+    if len(found) < 2:
+        return found
+
+    drop: set[int] = set()
+    for i in range(len(found) - 1):
+        a, b = found[i], found[i + 1]
+        if b["t"] - a["t"] > FLASH_WINDOW:
+            continue
+        hi = max(a["score"], b["score"])
+        if hi > 0 and abs(a["score"] - b["score"]) / hi <= 0.25:
+            drop.add(i)
+            drop.add(i + 1)
+    return [c for i, c in enumerate(found) if i not in drop]
+
+
+def suppress_non_maxima(found: list[dict], min_shot: float,
+                        region_start: float = 0.0,
+                        region_end: float | None = None) -> list[float]:
+    """Keep the strongest candidate in every ``min_shot`` neighbourhood.
+
+    Accepting in time order instead would let a weak early candidate shadow a
+    strong one just after it -- see the module docstring.
+    """
+    kept: list[dict] = []
+    for candidate in sorted(found, key=lambda c: -c["score"]):
+        # Both ends of the region count as boundaries, so the first and last
+        # shots are held to the same minimum as every other one. Without the
+        # head guard, noise in the opening frames produces a sliver shot; without
+        # the tail guard, a fade to black at the end does the same. The fade is
+        # the common one -- it is a real visual change, just not a cut.
+        edge = max(min_shot, EDGE_MIN)
+        if candidate["t"] - region_start < edge:
+            continue
+        if region_end is not None and region_end - candidate["t"] < edge:
+            continue
+        if any(abs(candidate["t"] - k["t"]) < min_shot for k in kept):
+            continue
+        kept.append(candidate)
+    return sorted(c["t"] for c in kept)
+
+
+def find_cuts(scores, sensitivity: str = "normal", min_shot: float = 1.0,
+              region_start: float = 0.0,
+              region_end: float | None = None) -> list[float]:
+    """Cut times, in seconds, from a list of [(time, score), ...]."""
+    k, ratio = SENSITIVITY.get(sensitivity, SENSITIVITY["normal"])
+    found = candidates(scores, k, ratio)
+    found = suppress_flashes(found)
+    return suppress_non_maxima(found, min_shot, region_start, region_end)
+
+
+def build_shots(cuts, start: float, end: float) -> list[Shot]:
+    """Turn cut times into contiguous shots tiling [start, end].
+
+    Guaranteed: no gaps, no overlaps, first starts at ``start``, last ends at
+    ``end``, and a clip with no cuts is exactly one shot.
+    """
+    edges = [start]
+    edges += [t for t in sorted(cuts) if start < t < end]
+    edges.append(end)
+    return [Shot(i + 1, edges[i], edges[i + 1]) for i in range(len(edges) - 1)]

custom_nodes/ComfyUI-Nugget/fingerprint.py

@@ -0,0 +1,158 @@
+"""Deciding whether this is the same request as last time.
+
+ComfyUI's default cache key for a node is its input signature *including every
+ancestor node's inputs*. That is stricter than it sounds. It answers "was the
+graph upstream of here identical?", not "is the content arriving here
+identical?", and the two come apart in exactly the cases that matter:
+
+  - bypassing an upstream node rewires the links the frontend sends, so the
+    signature changes even though nothing reaches this node
+  - connecting or disconnecting a socket changes it for the same reason
+  - any ancestor that re-runs for its own reasons drags this node with it
+
+Each of those makes a generation run again and produce text that is either
+identical (wasted minutes) or, with sampling on, gratuitously different.
+
+So the node fingerprints what it actually received instead: the prompt text,
+every setting, the seed, which encoder is loaded, and the pixels on each
+connected image socket. Same content, same fingerprint, no matter what the graph
+around it did.
+
+Images are sampled rather than hashed whole. A 9-image set at 2048px is hundreds
+of megabytes and reading all of it on every queue would cost more than it saves;
+a few thousand evenly spread elements plus the exact shape and dtype separates
+any two images anyone would actually put in a workflow. The sample is taken with
+a fixed stride, so it is the same sample every time for the same tensor.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from collections import OrderedDict
+
+log = logging.getLogger("Nugget")
+
+# Elements read per image. 4096 spread across the whole tensor -- not a corner,
+# which would miss two frames differing only in the middle.
+SAMPLE = 4096
+
+# Text only, a few kilobytes an entry, so this can never be the thing that
+# triggers a memory eviction.
+MAX_ENTRIES = 8
+
+_STORE: "OrderedDict[str, str]" = OrderedDict()
+
+
+def tensor_id(value) -> str:
+    """A content fingerprint for one image tensor.
+
+    Shape and dtype first, because two different images almost always differ
+    there and it costs nothing. The sampled bytes are taken through numpy rather
+    than formatted as text: float repr is lossy and two visibly different frames
+    could round to the same string.
+    """
+    try:
+        shape = tuple(int(n) for n in value.shape)
+        head = f"{shape}|{value.dtype}"
+        flat = value.detach().reshape(-1)
+        count = int(flat.numel())
+        if count == 0:
+            return head + "|empty"
+        stride = max(1, count // SAMPLE)
+        sample = flat[::stride][:SAMPLE].to("cpu").contiguous()
+        raw = sample.numpy().tobytes()
+        return head + "|" + hashlib.blake2b(raw, digest_size=16).hexdigest()
+    except Exception as exc:
+        # Never let fingerprinting be the thing that breaks a run. An unknown
+        # object falls back to "assume it changed", which costs a regeneration
+        # and is the safe direction to be wrong in.
+        log.debug("[Nugget] could not fingerprint an image (%s)", exc)
+        return "unfingerprintable"
+
+
+def is_image(value) -> bool:
+    """Is this an actual image tensor, or bypass debris?
+
+    Bypass hands a node whatever was on the bypassed node's inputs, so an image
+    socket can receive a string, a number, or nothing at all. Anything without a
+    shape is not an image and must not be treated as one.
+    """
+    if value is None:
+        return False
+    shape = getattr(value, "shape", None)
+    if shape is None or len(shape) < 3:
+        return False
+    return hasattr(value, "detach") and hasattr(value, "reshape")
+
+
+def images_id(images: dict, limit: int) -> str:
+    """Every connected image socket, in slot order.
+
+    Slot order is part of the identity, not just the set of images: the prompt
+    can name picture 2, so the same images in a different order is a different
+    request.
+    """
+    parts = []
+    for i in range(1, limit + 1):
+        value = images.get(f"image_{i}")
+        if is_image(value):
+            parts.append(f"{i}:{tensor_id(value)}")
+    return ";".join(parts) if parts else "none"
+
+
+def model_id(clip) -> str:
+    """Enough to tell one loaded encoder from another.
+
+    Same approach as recall.py: a different model writes different text from the
+    same input, so it belongs in the key. Falling back to object identity is
+    over-cautious rather than wrong -- it produces a miss where a hit was
+    possible, never a hit where the model has changed.
+    """
+    for path in (("tokenizer", "clip_name"), ("cond_stage_model", "__class__")):
+        obj = clip
+        for step in path:
+            obj = getattr(obj, step, None)
+            if obj is None:
+                break
+        if isinstance(obj, str):
+            return obj
+        if obj is not None and hasattr(obj, "__name__"):
+            return str(obj.__name__)
+    return str(id(clip))
+
+
+def key(clip, settings: dict, images: dict, limit: int) -> str:
+    """The whole request as one hex string.
+
+    A string on purpose. ComfyUI stores whatever ``fingerprint_inputs`` returns
+    in the workflow it writes into saved images, and serialises that as JSON, so
+    returning a tuple or a custom object either fails to save or silently
+    disables caching.
+    """
+    body = "|".join([
+        model_id(clip),
+        images_id(images, limit),
+        repr(sorted((str(k), str(v)) for k, v in settings.items())),
+    ])
+    return hashlib.blake2b(body.encode("utf-8", "replace"),
+                           digest_size=20).hexdigest()
+
+
+def get(cache_key: str):
+    if not cache_key or cache_key not in _STORE:
+        return None
+    _STORE.move_to_end(cache_key)
+    return _STORE[cache_key]
+
+
+def put(cache_key: str, value: str) -> None:
+    if not cache_key:
+        return
+    _STORE[cache_key] = value
+    while len(_STORE) > MAX_ENTRIES:
+        _STORE.popitem(last=False)
+
+
+def clear() -> None:
+    _STORE.clear()

custom_nodes/ComfyUI-Nugget/install.bat

@@ -0,0 +1,30 @@
+@echo off
+REM  Double-click this to install what Nugget needs.
+REM  It finds the Python that ComfyUI uses on its own, so it does not matter
+REM  which Python is on your PATH.
+
+cd /d "%~dp0"
+
+REM  Prefer ComfyUI's bundled interpreter directly if it is where we expect.
+set "PY="
+if exist "..\..\..\python_embeded\python.exe" set "PY=..\..\..\python_embeded\python.exe"
+if exist "..\..\python_embeded\python.exe"    set "PY=..\..\python_embeded\python.exe"
+
+if not defined PY (
+  where python >nul 2>nul
+  if errorlevel 1 (
+    echo.
+    echo   No Python found on your PATH, and no portable ComfyUI above this folder.
+    echo   Open the folder containing ComfyUI's python.exe and run:
+    echo       python.exe "%~dp0install.py"
+    echo.
+    pause
+    exit /b 1
+  )
+  set "PY=python"
+)
+
+"%PY%" install.py %*
+
+echo.
+pause

custom_nodes/ComfyUI-Nugget/install.py

@@ -0,0 +1,496 @@
+#!/usr/bin/env python3
+"""Install and verify everything this node needs.
+
+    python install.py            # check, then offer to install what is missing
+    python install.py --yes      # install without asking
+    python install.py --check    # report only, change nothing
+
+Run it with whatever Python you have. It finds the one ComfyUI actually uses and
+re-runs itself there, because installing into the wrong interpreter is the single
+most common reason faster-whisper still reports as missing after you installed
+it: ``pip install`` hits your system Python while ComfyUI runs its own bundled or
+virtual-environment one, and the two never see each other's packages.
+
+Two things this deliberately does not do.
+
+It does not capture pip's output. pip has a perfectly good progress bar, and
+hiding it makes a 700 MB cuDNN download look like a hang.
+
+It does not assume an NVIDIA card. ``torch.cuda.is_available()`` returns True on
+ROCm builds too, so checking it alone would cheerfully install CUDA wheels onto a
+Radeon. The backend is worked out from ``torch.version.hip`` and
+``torch.version.cuda``, and the CUDA major version chooses between the cu11 and
+cu12 wheels rather than cu12 being hardcoded.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import platform
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+
+# Where ComfyUI's interpreter lives, relative to a root containing main.py.
+CANDIDATES = [
+    Path("python_embeded") / "python.exe",              # Windows portable
+    Path("..") / "python_embeded" / "python.exe",       # portable, node inside ComfyUI/
+    Path("venv") / "Scripts" / "python.exe",
+    Path(".venv") / "Scripts" / "python.exe",
+    Path("venv") / "bin" / "python",
+    Path(".venv") / "bin" / "python",
+    Path("venv") / "bin" / "python3",
+    Path(".venv") / "bin" / "python3",
+]
+
+GIB = 1024 ** 3
+
+RESET, BOLD, RED, GREEN, YELLOW = "\033[0m", "\033[1m", "\033[31m", "\033[32m", "\033[33m"
+if os.name == "nt":
+    try:                                # Windows 10+ understands ANSI if asked
+        import ctypes
+        ctypes.windll.kernel32.SetConsoleMode(
+            ctypes.windll.kernel32.GetStdHandle(-11), 7)
+    except Exception:
+        RESET = BOLD = RED = GREEN = YELLOW = ""
+
+
+def say(text: str = "") -> None:
+    print(text, flush=True)
+
+
+def state(label: str, ok, detail: str = "") -> None:
+    mark = (f"{GREEN}ok{RESET}" if ok is True
+            else f"{YELLOW}--{RESET}" if ok is None
+            else f"{RED}MISSING{RESET}")
+    plain = "ok" if ok is True else "--" if ok is None else "MISSING"
+    say(f"  {label:<26} {mark}{' ' * max(1, 10 - len(plain))} {detail}")
+
+
+def installed(module: str) -> bool:
+    try:
+        __import__(module)
+        return True
+    except ImportError:
+        return False
+
+
+class Machine:
+    """What this computer can actually do, worked out once."""
+
+    def __init__(self):
+        self.os = platform.system()
+        self.arch = platform.machine()
+        self.python = "%d.%d.%d" % sys.version_info[:3]
+        self.backend = "cpu"            # cuda | rocm | mps | cpu
+        self.cuda_major = 0
+        self.gpu = ""
+        self.vram = 0
+        self.torch = False
+        self._probe()
+
+    def _probe(self) -> None:
+        try:
+            import torch
+        except ImportError:
+            return
+        self.torch = True
+
+        # ROCm builds report cuda.is_available() as True. Check HIP first, or we
+        # would install NVIDIA wheels onto an AMD card.
+        if getattr(torch.version, "hip", None):
+            self.backend = "rocm"
+            try:
+                self.gpu = torch.cuda.get_device_name(0)
+            except Exception:
+                pass
+            return
+
+        if getattr(torch, "cuda", None) and torch.cuda.is_available():
+            self.backend = "cuda"
+            version = getattr(torch.version, "cuda", "") or ""
+            self.cuda_major = int(version.split(".")[0]) if version[:1].isdigit() else 12
+            try:
+                self.gpu = torch.cuda.get_device_name(0)
+                self.vram = torch.cuda.mem_get_info()[1]
+            except Exception:
+                pass
+            return
+
+        backends = getattr(torch, "backends", None)
+        if getattr(backends, "mps", None) and torch.backends.mps.is_available():
+            self.backend = "mps"
+
+    @property
+    def gpu_speech(self) -> bool:
+        """Can the speech model use the GPU at all?
+
+        Only CUDA. faster-whisper runs on CTranslate2, which has no ROCm backend
+        and no Metal backend, so AMD and Apple Silicon transcribe on the CPU
+        however much VRAM is sitting idle.
+        """
+        return self.backend == "cuda"
+
+    def wheels(self) -> list[str]:
+        if not self.gpu_speech:
+            return []
+        suffix = "cu11" if self.cuda_major == 11 else "cu12"
+        return [f"nvidia-cublas-{suffix}", f"nvidia-cudnn-{suffix}"]
+
+    def suggested_model(self) -> str:
+        if not self.gpu_speech:
+            return "large-v3 on CPU is slow -- medium or small is a better trade"
+        # 10 GB, not 8: the text encoder is the other tenant, and an 8 GB card
+        # holding Gemma has nothing like 3 GB spare for large-v3.
+        if self.vram and self.vram < 10 * GIB:
+            return "limited VRAM: prefer medium over large-v3"
+        return "large-v3 should fit alongside your text encoder"
+
+    def report(self) -> None:
+        say("  this machine")
+        state("os / arch", None, f"{self.os} {self.arch}")
+        state("python", None, self.python)
+        if not self.torch:
+            state("torch", False, "ComfyUI cannot run without it")
+            return
+
+        label = {"cuda": f"CUDA {self.cuda_major}.x",
+                 "rocm": "ROCm / HIP",
+                 "mps": "Apple Silicon (Metal)",
+                 "cpu": "no GPU"}[self.backend]
+        detail = self.gpu
+        if self.vram:
+            detail += f" -- {self.vram / GIB:.0f} GB"
+        state("torch backend", None, f"{label}{'  ' + detail if detail else ''}")
+
+        where = {"rocm": "CPU -- CTranslate2 has no ROCm backend",
+                 "mps": "CPU -- CTranslate2 has no Metal backend",
+                 "cuda": "GPU, if the CUDA wheels below are present",
+                 "cpu": "CPU"}[self.backend]
+        state("speech device", None, where)
+
+
+def comfy_python() -> Path | None:
+    for parent in [HERE] + list(HERE.parents)[:5]:
+        if not (parent / "main.py").exists():
+            continue
+        for relative in CANDIDATES:
+            candidate = (parent / relative).resolve()
+            if candidate.exists():
+                return candidate
+        return None                     # system or conda install
+    return None
+
+
+def externally_managed() -> bool:
+    """Is this a distro Python that refuses pip installs? (PEP 668)
+
+    Debian, Ubuntu and Fedora ship a marker file that makes pip refuse to touch
+    the system site-packages. ComfyUI's own bundled interpreter and any venv are
+    unaffected, but anyone running ComfyUI on their distro Python hits it, and
+    pip's suggestion -- make a virtualenv -- is useless here, because the package
+    has to land in the interpreter ComfyUI already runs.
+    """
+    import sysconfig
+
+    if sys.prefix != sys.base_prefix:            # inside a venv; marker n/a
+        return False
+    return (Path(sysconfig.get_path("stdlib")) / "EXTERNALLY-MANAGED").exists()
+
+
+def pip_install(packages: list[str]) -> bool:
+    """Run pip with the console attached, so its own progress bar shows."""
+    flags = ["--progress-bar", "on"]
+    if externally_managed():
+        say()
+        say(f"  {YELLOW}note{RESET} this Python is distro-managed (PEP 668), so pip "
+            f"would normally refuse.")
+        say("  Adding --break-system-packages: the package has to go into the")
+        say("  interpreter ComfyUI runs, and a virtualenv would not be that one.")
+        flags.append("--break-system-packages")
+
+    say()
+    say(f"  {BOLD}pip install {' '.join(packages)}{RESET}")
+    say()
+    started = time.time()
+    code = subprocess.call([sys.executable, "-m", "pip", "install",
+                            *flags, *packages])
+    say()
+    if code == 0:
+        say(f"  {GREEN}installed{RESET} in {time.time() - started:.0f}s")
+        return True
+    say(f"  {RED}pip exited with code {code}{RESET} -- its error is above")
+    return False
+
+
+# CTranslate2, which faster-whisper is built on, is compiled against CUDA 12 and
+# asks for these by name. That is independent of the CUDA your torch uses: a
+# torch built for CUDA 13 ships cublas64_13.dll, which is the wrong file however
+# new it is. Checking for torch's version instead of this one reports success on
+# a machine that then fails at run time.
+CT2_DLLS = ["cublas64_12.dll", "cudnn64_9.dll"]
+
+
+def cuda_dll_status(machine: "Machine") -> tuple[bool, str]:
+    """On Windows, are CTranslate2's CUDA DLLs present AND loadable?
+
+    Importing ``nvidia.cublas`` only proves the package is unpacked. The DLL sits
+    under ``site-packages/nvidia/...``, which Python has not searched since 3.8,
+    so it can be installed, importable, and still fail to load -- which is
+    exactly the "cublas64_12.dll is not found or cannot be loaded" report.
+    """
+    if os.name != "nt" or not machine.gpu_speech:
+        return True, ""
+
+    import ctypes
+    import site
+
+    bases = {b for b in (*site.getsitepackages(), site.getusersitepackages()) if b}
+
+    # Walk the nvidia packages rather than guessing at bin/ or lib/: the wheel
+    # layout has moved between releases, and the file is what matters.
+    folders: list[str] = []
+    for base in bases:
+        root = os.path.join(base, "nvidia")
+        if os.path.isdir(root):
+            for where, _, files in os.walk(root):
+                if any(f.lower().endswith(".dll") for f in files):
+                    folders.append(where)
+        torch_lib = os.path.join(base, "torch", "lib")
+        if os.path.isdir(torch_lib):
+            folders.append(torch_lib)
+
+    for folder in folders:
+        try:
+            os.add_dll_directory(folder)
+            os.environ["PATH"] = folder + os.pathsep + os.environ.get("PATH", "")
+        except (OSError, AttributeError):
+            pass
+
+    missing, loaded = [], []
+    for name in CT2_DLLS:
+        where = next((f for f in folders
+                      if os.path.exists(os.path.join(f, name))), None)
+        if where is None:
+            missing.append(name)
+            continue
+        try:
+            ctypes.CDLL(os.path.join(where, name))
+            loaded.append(name)
+        except OSError:
+            missing.append(f"{name} (present but will not load)")
+
+    if missing:
+        note = ", ".join(missing)
+        if machine.cuda_major and machine.cuda_major != 12:
+            note += (f" -- your torch is CUDA {machine.cuda_major}.x, but "
+                     f"faster-whisper needs the CUDA 12 runtime alongside it")
+        return False, note
+    return True, f"{', '.join(loaded)} loadable"
+
+
+def explain(exc: Exception) -> str:
+    """Turn a library traceback into something worth reading.
+
+    The three failures that actually happen -- a blocked model download, a
+    missing CUDA wheel, and no disk space -- all surface as opaque errors from
+    three different libraries, so they get named here rather than left as-is.
+    """
+    text = f"{type(exc).__name__}: {exc}".strip().splitlines()[0]
+    low = text.lower()
+    if any(word in low for word in ("hfhub", "huggingface", "403", "connection",
+                                    "timed out", "getaddrinfo", "ssl", "proxy")):
+        return ("could not download the model from huggingface.co -- check your "
+                "connection, proxy or firewall")
+    if "cudnn" in low or "cublas" in low:
+        return (f"CUDA library not loadable -- {text[:80]}. On Windows this is "
+                f"usually the DLL search path, not a missing package.")
+    if "no space" in low or "disk" in low:
+        return "not enough disk space for the model cache"
+    return text[:160]
+
+
+def verify_speech(machine: Machine) -> tuple[bool, str]:
+    """Build a real model and transcribe silence.
+
+    A successful import proves nothing: CTranslate2 loads cuDNN and cuBLAS only
+    when a model is constructed, so a missing wheel throws here and nowhere
+    earlier.
+    """
+    try:
+        import numpy as np
+        from faster_whisper import WhisperModel
+    except ImportError as exc:
+        return False, f"not importable: {exc}"
+
+    import tempfile
+    import wave
+
+    handle, path = tempfile.mkstemp(suffix=".wav")
+    os.close(handle)
+
+    # Same DLL registration the node does at run time, so this test exercises
+    # the real path rather than a luckier one.
+    cuda_dll_status(machine)
+
+    def attempt(device: str, compute: str) -> None:
+        model = WhisperModel("tiny", device=device, compute_type=compute)
+        list(model.transcribe(path, vad_filter=True)[0])
+
+    try:
+        with wave.open(path, "wb") as out:
+            out.setnchannels(1)
+            out.setsampwidth(2)
+            out.setframerate(16000)
+            out.writeframes(np.zeros(16000, dtype=np.int16).tobytes())
+
+        if machine.gpu_speech:
+            try:
+                attempt("cuda", "float16")
+                return True, "GPU (cuda / float16) works"
+            except Exception as exc:
+                say(f"  {YELLOW}GPU attempt failed:{RESET} {explain(exc)}")
+                say("  falling back to CPU...")
+                try:
+                    attempt("cpu", "int8")
+                    return True, "CPU works, GPU does not"
+                except Exception as inner:
+                    return False, f"neither device works -- {explain(inner)}"
+
+        attempt("cpu", "int8")
+        return True, "CPU (int8) works"
+    except Exception as exc:
+        return False, explain(exc)
+    finally:
+        try:
+            os.remove(path)
+        except OSError:
+            pass
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(add_help=True)
+    parser.add_argument("--yes", action="store_true", help="install without asking")
+    parser.add_argument("--check", action="store_true", help="report only")
+    parser.add_argument("--no-redirect", action="store_true", help=argparse.SUPPRESS)
+    options = parser.parse_args()
+
+    say()
+    say(f"  {BOLD}Nugget - install{RESET}")
+    say("  " + "-" * 64)
+
+    target = comfy_python()
+    if target and not options.no_redirect and \
+            target.resolve() != Path(sys.executable).resolve():
+        say()
+        say(f"  you ran this with:     {sys.executable}")
+        say(f"  ComfyUI actually uses: {target}")
+        say()
+        say("  re-running there, so packages land where ComfyUI can see them")
+        say()
+        return subprocess.call([str(target), str(Path(__file__).resolve()),
+                                "--no-redirect", *sys.argv[1:]])
+
+    say()
+    say(f"  interpreter: {sys.executable}")
+    if not target:
+        say(f"  {YELLOW}no ComfyUI root found above this folder{RESET} -- if ComfyUI")
+        say("  runs on a different Python, run this script with that one")
+    say()
+
+    machine = Machine()
+    machine.report()
+
+    say()
+    say("  required (all ship with ComfyUI)")
+    for module, label in (("av", "PyAV"), ("numpy", "numpy"), ("PIL", "Pillow")):
+        state(label, installed(module))
+
+    say()
+    say("  speech")
+    wanted: list[str] = []
+
+    has_speech = installed("faster_whisper")
+    state("faster-whisper", has_speech)
+    if not has_speech:
+        wanted.append("faster-whisper")
+
+    for package in machine.wheels():
+        module = "nvidia." + package.split("-")[1]
+        present = installed(module)
+        state(package, present, "needed for GPU speech")
+        if not present:
+            wanted.append(package)
+    if machine.torch and not machine.gpu_speech:
+        state("cuda wheels", None, "not applicable on this backend")
+
+    if machine.gpu_speech and os.name == "nt":
+        ok, detail = cuda_dll_status(machine)
+        state("cuda dll loadable", ok, detail)
+        if not ok and "missing" in detail:
+            for package in machine.wheels():
+                if package not in wanted:
+                    wanted.append(package)
+
+    state("model choice", None, machine.suggested_model())
+
+    if options.check:
+        say()
+        say(f"  {YELLOW}missing:{RESET} " + ", ".join(wanted) if wanted
+            else f"  {GREEN}nothing missing{RESET}")
+        say()
+        return 0
+
+    if wanted:
+        say()
+        say("  to install: " + ", ".join(wanted))
+        if machine.gpu_speech and len(wanted) > 1:
+            say(f"  {YELLOW}heads up{RESET} the cuDNN wheel is around 700 MB, so "
+                f"this can take a few minutes")
+        if not options.yes:
+            try:
+                answer = input("  install now? [Y/n] ").strip().lower()
+            except EOFError:
+                answer = "y"
+            if answer and not answer.startswith("y"):
+                say("\n  nothing installed.\n")
+                return 1
+        if not pip_install(wanted):
+            say()
+            return 1
+    else:
+        say()
+        say("  nothing to install")
+
+    say()
+    say("  verifying -- builds a real model and transcribes a second of silence")
+    say("  (downloads about 75 MB the first time; this is not a hang)")
+    say()
+    started = time.time()
+    ok, detail = verify_speech(machine)
+    state("faster-whisper", ok, f"{detail}  [{time.time() - started:.0f}s]")
+
+    say()
+    if ok:
+        say(f"  {GREEN}Ready.{RESET} Restart ComfyUI so it picks up the new packages.")
+    else:
+        say(f"  {RED}Speech is still not working.{RESET}")
+        say("  The node will still describe the video; there will be no transcript.")
+        if machine.backend == "rocm":
+            say("  On ROCm, GPU speech is expected to fail -- CPU should still work.")
+        elif "huggingface" in detail.lower():
+            say("  The packages are fine; only the model download failed. Try again")
+            say("  on a different network, or set HF_ENDPOINT to a mirror.")
+        elif "cudnn" in detail.lower() or "cublas" in detail.lower():
+            say("  That error names cuDNN or cuBLAS: the wheels are missing or do")
+            say(f"  not match your CUDA {machine.cuda_major}.x torch build.")
+    say()
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

custom_nodes/ComfyUI-Nugget/interrupt.py

@@ -0,0 +1,39 @@
+"""Letting Cancel actually cancel.
+
+ComfyUI signals a cancellation by setting a flag; nothing is forcibly killed. A
+node only stops when it next asks whether it should, so any loop that runs for
+more than a second or two has to ask, or Cancel appears to do nothing until the
+loop finishes on its own.
+
+The long ones here are transcription -- large-v3 on the CPU can spend well over a
+minute on a ten-second clip -- and, to a lesser degree, decoding frames. Checking
+only between passes, as this used to, meant a cancel during transcription waited
+out the whole thing.
+
+The one place that cannot be interrupted is inside a single ``clip.generate()``
+call: it is one blocking call into ComfyUI and there is no hook to poll. Those
+run a few seconds each, so the worst case is the tail of one generation rather
+than the tail of the whole run.
+"""
+
+from __future__ import annotations
+
+try:  # pragma: no cover - depends on the host
+    from comfy.model_management import (
+        InterruptProcessingException,
+        throw_exception_if_processing_interrupted,
+    )
+except Exception:  # running outside ComfyUI, e.g. the test suite
+    class InterruptProcessingException(Exception):
+        """Stand-in so ``except Interrupted`` is always valid."""
+
+    def throw_exception_if_processing_interrupted():
+        return None
+
+
+Interrupted = InterruptProcessingException
+
+
+def check() -> None:
+    """Raise if the user has pressed Cancel. Cheap enough to call in a loop."""
+    throw_exception_if_processing_interrupted()

custom_nodes/ComfyUI-Nugget/llm.py

@@ -0,0 +1,277 @@
+"""Talking to the text encoder ComfyUI already loaded.
+
+``TextGenerate`` in ``comfy_extras/nodes_textgen.py`` is three calls -- tokenize,
+generate, decode -- and this does the same thing without going through the node,
+so frames can be handed over at times we choose.
+
+Two details are load-bearing.
+
+**Frames go in as ``image``, never ``video``.** Core's ``video`` input carries the
+tooltip "Assumed to be 24 FPS; subsampled to 1 FPS internally". One frame per
+second cannot tell a cut from a camera move, which is how a three-shot clip gets
+described as twelve shots. Passing an image batch bypasses that entirely.
+
+**The output needs cleaning.** Gemma leaks its own turn and channel markers into
+the text. Core knows this -- ``TextGenerateLTX2Prompt`` strips them with a regex
+before returning -- but the plain ``TextGenerate`` node does not, which is why
+raw use of it produces pages of ``<think></think>`` and ``<|image>``.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+
+log = logging.getLogger("Nugget")
+
+# Gemma 4 uses <|turn>role ... <turn|> with <|channel>final and <|image>.
+# Gemma 3 uses <start_of_turn> ... <end_of_turn> with <image_soft_token>.
+# Qwen3-VL uses <|im_start|> ... <|im_end|> with <|vision_start|> and friends.
+# All three can be wired into this node, so strip all three rather than sniffing
+# the tokenizer name and guessing wrong.
+_THINK_BLOCK = re.compile(r"<think>.*?</think>", re.DOTALL)
+_MARKERS = re.compile(
+    r"</?think>"
+    r"|<\|think\|>"
+    r"|<\|channel>\w*\n?|<channel\|>"
+    r"|<\|turn>\w*\n?|<turn\|>"
+    r"|<\|image\|?>|<image\|>|<image_soft_token>"
+    r"|<start_of_turn>\w*\n?|<end_of_turn>"
+    r"|<\|im_start\|>\w*\n?|<\|im_end\|>"
+    r"|<\|vision_start\|>|<\|vision_end\|>|<\|vision_pad\|>"
+    r"|<\|image_pad\|>|<\|video_pad\|>|<\|endoftext\|>"
+    r"|<\|?eos\|?>|<pad>"
+)
+
+
+class LLMError(RuntimeError):
+    pass
+
+
+# Inner text-encoder classes that are image-generation encoders, not language
+# models. Wiring one in is the most common setup mistake, because "CLIP" in
+# ComfyUI is a generic label for a text-encoder slot and the loader accepts any
+# of them without complaint.
+_NOT_LANGUAGE_MODELS = {
+    "SD1ClipModel": "a Stable Diffusion 1.x text encoder",
+    "SDXLClipModel": "a Stable Diffusion XL text encoder",
+    "SD2ClipModel": "a Stable Diffusion 2.x text encoder",
+    "SD3ClipModel": "a Stable Diffusion 3 text encoder",
+    "FluxClipModel": "a Flux text encoder",
+    "T5XXLModel": "a T5 text encoder",
+    "CLIPTextModel": "a plain CLIP text encoder",
+}
+
+
+def check(clip) -> None:
+    """Fail early and legibly if this CLIP cannot generate text.
+
+    The outer ComfyUI CLIP wrapper exposes ``generate`` whatever is inside it, so
+    checking the wrapper alone passes for a Stable Diffusion encoder and then
+    dies hundreds of lines later with ``'SD1ClipModel' object has no attribute
+    'generate'``. The inner model is what has to be interrogated.
+    """
+    if clip is None:
+        raise LLMError("No CLIP connected. Wire a Load CLIP node loading a "
+                       "Gemma text encoder into the `clip` input.")
+
+    for method in ("tokenize", "generate", "decode"):
+        if not hasattr(clip, method):
+            raise LLMError(
+                "This ComfyUI build cannot generate text from a CLIP "
+                f"(no `{method}` method). Text generation arrived in ComfyUI "
+                "v0.15.0 -- update ComfyUI.")
+
+    inner = getattr(clip, "cond_stage_model", None)
+    if inner is None:
+        return                       # unknown shape; let the call speak for itself
+
+    name = type(inner).__name__
+    if not hasattr(inner, "generate"):
+        # Substring match, not exact: ComfyUI subclasses these and the useful
+        # part of the name survives in the subclass.
+        bare = name.lstrip("_")
+        what = next((label for key, label in _NOT_LANGUAGE_MODELS.items()
+                     if key.lower() in bare.lower()), f"`{name}`")
+        raise LLMError(
+            f"The Load CLIP node is loading {what}, which cannot generate text. "
+            "This node needs a language model: a Gemma 4 encoder such as "
+            "gemma4_12b_int8_convrot.safetensors, or a Qwen3-VL encoder such as "
+            "qwen3vl_8b_fp8_scaled.safetensors. Put it in "
+            "ComfyUI/models/text_encoders/ and select that file in Load CLIP. "
+            "ComfyUI works out the type from the file, so the type dropdown "
+            "rarely matters -- picking the wrong file is what does.")
+
+
+def tidy(text: str) -> str:
+    """Strip leaked control tokens and any reasoning trace."""
+    if not text:
+        return ""
+    text = _THINK_BLOCK.sub("", text)
+    if "</think>" in text:
+        # Reasoning that was cut off at the start: keep what follows the close.
+        text = text.rsplit("</think>", 1)[-1]
+    elif "<think>" in text:
+        # An open tag with no close means generation ran out of budget while
+        # still deliberating, so everything after it is reasoning and there is no
+        # answer. Returning the trace would hand a half-finished thought
+        # downstream as though it were the description.
+        text = text.split("<think>", 1)[0]
+    text = _MARKERS.sub("", text)
+    # Collapse the blank-line runs the stripping leaves behind.
+    return re.sub(r"\n{3,}", "\n\n", text).strip()
+
+
+# Roughly how many characters a token is worth in English prose. Only used to
+# tell "stopped because the budget ran out" from "stopped because it was done".
+CHARS_PER_TOKEN = 3.7
+
+
+def looks_truncated(text: str, budget: int = 0) -> bool:
+    """Did generation stop because it ran out of budget rather than finished?
+
+    There is no truncation flag to read, so the tell is text that ends
+    mid-sentence. That alone is not enough: a model can emit a stop token after
+    a fragment, and blaming the budget then sends the reader off to raise a
+    setting that was never the constraint. So when the budget is known, the
+    reply also has to be long enough to have plausibly hit it.
+    """
+    stripped = (text or "").strip()
+    if len(stripped) < 40:
+        return False
+    if stripped[-1] in ".!?\"')]}\u2019\u201d":
+        return False
+    if budget:
+        used = len(stripped) / CHARS_PER_TOKEN
+        # Well short of the ceiling means the model chose to stop.
+        if used < budget * 0.7:
+            return False
+    return True
+
+
+def _batch(images):
+    """Whatever the caller gave us, in a shape the encoder will accept.
+
+    Three cases arrive here. PIL images (the transcriber's frame grids) get
+    stacked into one tensor. A list of tensors, one per reference image, is
+    passed straight through -- keeping them separate is what lets each keep its
+    own aspect ratio. A single tensor passes through untouched.
+    """
+    if images is None:
+        return None
+    if not isinstance(images, (list, tuple)):
+        return images                     # already a tensor
+    if not images:
+        return None
+
+    import torch
+
+    if torch.is_tensor(images[0]):
+        return list(images) if len(images) > 1 else images[0]
+
+    import numpy as np
+
+    first = images[0].size
+    arrays = []
+    for image in images:
+        if image.size != first:
+            image = image.resize(first)
+        arrays.append(np.asarray(image.convert("RGB"), dtype=np.float32) / 255.0)
+    return torch.from_numpy(np.stack(arrays))
+
+
+def _stack_padded(tensors):
+    """Fallback: letterbox differently-sized tensors onto one shared canvas.
+
+    Only reached when this build of ComfyUI will not take a list of images. The
+    canvas is the smallest box holding all of them, so a set that already agrees
+    on shape gets no bars at all.
+    """
+    import torch
+
+    widest = max(int(t.shape[2]) for t in tensors)
+    tallest = max(int(t.shape[1]) for t in tensors)
+
+    out = []
+    for tensor in tensors:
+        frame = tensor[0]
+        h, w = int(frame.shape[0]), int(frame.shape[1])
+        if (h, w) == (tallest, widest):
+            out.append(frame)
+            continue
+        canvas = torch.zeros((tallest, widest, int(frame.shape[2])),
+                             device=frame.device, dtype=frame.dtype)
+        y, x = (tallest - h) // 2, (widest - w) // 2
+        canvas[y:y + h, x:x + w, :] = frame
+        out.append(canvas)
+    return torch.stack(out, dim=0)
+
+
+def ask(clip, prompt: str, images=None, max_tokens: int = 512,
+        seed: int = 0, temperature: float = 0.0,
+        repetition_penalty: float = 1.0, sample: bool | None = None,
+        note: dict | None = None) -> str:
+    """One generation. Greedy unless ``sample`` says otherwise.
+
+    ``sample`` is explicit rather than inferred from ``temperature``. Inferring
+    it meant a node could offer a sampling on/off control, have the user switch
+    it on, and still decode greedily because temperature happened to sit at
+    zero -- the widget said one thing and the model did another. When ``sample``
+    is None the old behaviour applies, which keeps the transcriber's greedy
+    default working.
+
+    A temperature of zero with sampling on is not meaningful, so it is floored
+    rather than silently turning sampling off.
+    """
+    check(clip)
+
+    if sample is None:
+        sample = temperature > 0
+    if sample and temperature <= 0:
+        temperature = 0.7
+
+    payload = _batch(images)
+
+    def tokenize(media):
+        return clip.tokenize(prompt, image=media, skip_template=False,
+                             min_length=1, thinking=False, video=None, audio=None)
+
+    try:
+        try:
+            tokens = tokenize(payload)
+        except Exception:
+            # This build will not take a list of separately-sized images, so
+            # letterbox them onto one canvas instead. Logged once: it is a
+            # capability of the host, not something that changes run to run.
+            if not isinstance(payload, list):
+                raise
+            if note is not None and not note.get("warned"):
+                note["warned"] = True
+                log.info("[Nugget] this ComfyUI build needs one image tensor, so "
+                         "references are being letterboxed onto a shared canvas. "
+                         "Matching aspect ratios avoids the bars entirely.")
+            tokens = tokenize(_stack_padded(payload))
+
+        generated = clip.generate(
+            tokens,
+            do_sample=bool(sample),
+            max_length=int(max_tokens),
+            # The filters below only bite when sampling; with do_sample False
+            # they are inert, so there is no need to branch on them.
+            temperature=float(temperature) if sample else 1.0,
+            top_k=64 if sample else 0,
+            top_p=0.95 if sample else 1.0,
+            min_p=0.05 if sample else 0.0,
+            # Applies either way: it reshapes the logits before the pick, so it
+            # affects greedy decoding as much as sampling. 1.0 is off, and off
+            # is right for structured output that is supposed to repeat its own
+            # labels.
+            repetition_penalty=float(repetition_penalty),
+            presence_penalty=0.0,
+            seed=int(seed),
+        )
+        return tidy(clip.decode(generated))
+    except LLMError:
+        raise
+    except Exception as exc:
+        raise LLMError(f"Text generation failed: {exc}") from exc

custom_nodes/ComfyUI-Nugget/motion_prompts.py

@@ -0,0 +1,450 @@
+"""Prompts and output assembly for the motion-transfer node.
+
+Sibling of ``prompts.py``. Kept separate because the two nodes want almost
+opposite things from the model: the transcriber wants "what is this shot about"
+in prose; motion transfer wants "what does the body do, and when". Sharing a
+prompt module would mean every edit needs a "is this the transcriber or the
+motion node" branch, and the shot prompt would grow into a switch statement.
+
+Frame density is higher here than in the transcriber. The transcriber can
+describe a four-second shot from four frames -- the reader only needs to know
+what happens, not the exact instant it happens. Motion transfer callouts are
+tied to timestamps, so the model needs enough frames to place them: roughly one
+frame per callout it will produce. The three detail levels below map to the two
+styles in the examples, plus a middle ground.
+
+Timestamps are handed to the model as a list beneath the frame grid, and the
+model is asked to write callouts using only those timestamps. Left to invent its
+own it tends to space them evenly regardless of what changes in the video, which
+is exactly the failure the "brief" mode is meant to avoid.
+"""
+
+from __future__ import annotations
+
+
+# Frames per second of shot, and the range that count is clamped to, by detail
+# level. Tuned to give the model one frame per timestamp it might call out --
+# fewer frames than that and the model guesses the pose at unshown moments,
+# which reads as fine until you check it against the video.
+#
+# ``beat`` is the longest span described in one call. Longer shots are split
+# into equal beats and each is described on its own, then joined -- a single
+# call over twenty seconds gets the same handful of frames a four-second shot
+# gets, and everything between the samples is lost.
+DETAIL = {
+    # pk-style: event-driven callouts, only when something changes.
+    "brief":    {"per_second": 1.0, "min": 3, "max": 8,  "tokens": 220, "beat": 8.0},
+    # In between: sparse enough to read at a glance, dense enough to reproduce.
+    "normal":   {"per_second": 1.5, "min": 4, "max": 10, "tokens": 380, "beat": 6.0},
+    # plz-style: near-continuous, roughly every half second.
+    "detailed": {"per_second": 2.0, "min": 6, "max": 14, "tokens": 700, "beat": 4.0},
+}
+
+# Frames used by the overview and subject passes. Sampled per shot rather than
+# evenly across the clip, so a short shot still contributes -- an even spread
+# can miss a one-second shot entirely and lose whoever is only in it.
+CONTEXT_FRAMES = 8
+
+GRID_NOTE = ("The image is a grid of {count} video frames in time order, read "
+             "left to right then top to bottom, like a comic strip. They are "
+             "frames of one continuous shot showing the subject moving, not "
+             "separate pictures.")
+
+
+OVERVIEW = """These frames are spread across a short video of someone moving or dancing.
+
+In ONE sentence, describe the overall look and feel of the motion: pace (slow / brisk / fast), quality (sharp / flowing / loose / rhythmic), and the mood.
+
+Do not describe any single movement, and do not list what happens moment by moment. One sentence, nothing else."""
+
+
+CONTINUES = ("\n\nThis continues the same shot, already in progress. The "
+             "opening sentence about overall posture has already been written, "
+             "so do NOT repeat it -- write only the timestamped movement lines "
+             "for THIS window.")
+
+
+# Deliberately singular. Motion transfer clips are almost always about one
+# person moving, and asking for a list encourages the model to describe every
+# body in the frame -- including reflections, background extras and cropped
+# limbs that don't belong to the mover.
+#
+# The prompt describes the shape in prose rather than showing a template
+# because template placeholders (angle-bracket shapes and named example words)
+# leak into the output on smaller models even when the prompt tells them not
+# to. clean_subjects strips the leaks when they happen, but not writing them
+# in the first place is the more reliable half of the fix.
+SUBJECTS = """These frames are from one short video of someone moving.
+
+Describe the moving subject in ONE short line: a noun phrase covering what they are, followed by the details that identify them -- clothing, hair, build, colour. Focus only on appearance. The movement itself is described elsewhere and belongs there, not here.
+
+If several people move together, write one line per mover. Skip anyone standing still in the background. If there is no clear human or animal subject -- an abstract animation, an object moving on its own -- write the single word NONE.
+
+No preamble, no labels, no numbering, nothing else."""
+
+
+SUBJECTS_KNOWN = ("\nThe mover(s) in this video:\n{subjects}\n"
+                  "Refer to them the same way in every callout, so the "
+                  "description stays consistent.\n")
+
+
+# The camera movement is measured, not guessed. A locked-off dance shot is the
+# common case for motion transfer, but hand-held and moving-camera clips do
+# turn up and the model would otherwise call every camera drift a body sway.
+CAMERA_FACT = ("\nThe camera has been measured for you: {motion}. Do not "
+               "attribute this to the subject's body -- their motion is what "
+               "moves relative to the frame after the camera is accounted for.\n")
+
+
+# Per-style shot instructions, all sharing the same header (frames + timestamp
+# list). The header is the load-bearing part: without the timestamp list the
+# model invents its own MM:SS.mmm values and their spacing rarely matches the
+# frames it was shown.
+_SHOT_HEADER = """{layout} They span {span:.1f} seconds, from {start_clock} to {end_clock}.
+
+The frames above are sampled at these timestamps (in order):
+{timestamp_list}
+
+"""
+
+# Prompts describe the callout format in prose rather than showing a template
+# line. A demo line like `MM:SS.mmm <short phrase about hands, arms, hips>`
+# reliably leaks: the model treats the shape as content to reproduce, and the
+# words inside the angle brackets appear in real callouts. The same is true of
+# quoted example adverbs ("gracefully" / "sharply") -- naming a word to
+# suppress teaches the model to reach for it. So neither appears here.
+
+_BODY_BRIEF = """Write ONE short opening sentence describing what the subject is doing overall in this window -- their posture, weight, and the general shape of the movement.
+
+Then list only the moments where something visibly CHANGES: a new gesture, a step, a shift in weight, a new pose, a turn. Skip time where the pose is holding.
+
+Each moment goes on its own line. Start the line with the timestamp written as MM:SS.mmm, then two spaces, then a short phrase describing what the body does at that instant (hands, arms, hips, feet, weight, gaze).
+
+Use ONLY timestamps from the list above. Aim for about {aim} callouts across the whole span. Keep every line short and physical: say what the body does, not how well it does it, and not the mood behind it.
+
+"""
+
+_BODY_NORMAL = """Write ONE short opening sentence describing the subject's overall movement in this window -- the shape of it, the pace.
+
+Then describe the body at the key timestamps from the list -- roughly every other one, with more where the motion is busy and fewer where it holds.
+
+Each callout goes on its own line. Start the line with the timestamp written as MM:SS.mmm, then two spaces, then a short phrase describing what the body is doing at that instant.
+
+Use ONLY timestamps from the list above. Keep every line short and focused on the physical pose.
+
+"""
+
+_BODY_DETAILED = """Describe the subject's body position and motion at EVERY timestamp in the list above, in order.
+
+Each callout goes on its own line. Start the line with the timestamp written as MM:SS.mmm, then two spaces, then a short phrase about the body at that instant (hands, arms, hips, feet, weight, gaze).
+
+One line per timestamp, no skips. Keep every line short and stick strictly to the pose at that instant. Say what the body does, not how well it does it and not what the camera does.
+
+"""
+
+_STYLE_BODIES = {"brief": _BODY_BRIEF, "normal": _BODY_NORMAL,
+                 "detailed": _BODY_DETAILED}
+
+_SHOT_FOOTER = """{subjects}{camera}
+Only what is visible in THESE frames. If the subject is out of frame at a timestamp, or too small to read, note that briefly on the callout for that timestamp rather than guessing at a pose.
+
+Write only the description. No preamble, no bullet points, no shot number, no trailing summary."""
+
+
+def shot_prompt(detail: str) -> str:
+    """The full shot prompt for a given detail level, ready for ``.format``.
+
+    Composed rather than three separate literal strings so the shared header
+    and footer stay in one place -- otherwise a fix to the timestamp-list
+    wording has to be made three times.
+    """
+    body = _STYLE_BODIES.get(detail, _BODY_NORMAL)
+    return _SHOT_HEADER + body + _SHOT_FOOTER
+
+
+# Token budgets for the two setup passes when the user has not overridden the
+# per-shot budget. The overview is one sentence and the subject line is one
+# short phrase, so neither needs much.
+OVERVIEW_TOKENS = 120
+SUBJECT_TOKENS = 160
+
+
+def token_budget(detail: str, override: int = 0) -> dict:
+    """How many tokens each pass may generate.
+
+    Detailed mode's per-shot budget has to accommodate one line per timestamp
+    -- roughly 20 tokens each and up to 14 timestamps per beat -- which is
+    where the 700 default comes from. Brief mode is deliberately much smaller
+    to keep the model from padding.
+    """
+    settings = DETAIL.get(detail, DETAIL["normal"])
+    if not override or override <= 0:
+        return {"shot": settings["tokens"],
+                "overview": OVERVIEW_TOKENS,
+                "subject": SUBJECT_TOKENS}
+
+    shot = int(override)
+    return {"shot": shot,
+            "overview": max(OVERVIEW_TOKENS, shot // 4),
+            "subject": max(SUBJECT_TOKENS, shot // 3)}
+
+
+def frames_for(duration: float, detail: str) -> int:
+    """How many frames to show the model for a beat of this length."""
+    settings = DETAIL.get(detail, DETAIL["normal"])
+    wanted = int(round(max(0.0, duration) * settings["per_second"]))
+    return max(settings["min"], min(settings["max"], wanted))
+
+
+def sample_times(start: float, end: float, count: int) -> list[float]:
+    """Frame times spread across a span, at bin centres.
+
+    Centres rather than edges: landing exactly on ``end`` picks up the next
+    shot's first frame, which would then show a pose from a shot the callouts
+    are not covering.
+    """
+    count = max(1, int(count))
+    span = max(0.0, end - start)
+    return [start + span * (i + 0.5) / count for i in range(count)]
+
+
+def beats_for(shot, detail: str) -> list:
+    """Split a shot into equal beats short enough to describe densely.
+
+    Equal windows rather than content-adaptive ones: for motion there is no
+    reliable within-shot signal for where one beat ends and the next begins,
+    and the cuts (across shots) already handle the structural breaks.
+    """
+    length = float(DETAIL.get(detail, DETAIL["normal"])["beat"])
+    span = max(0.0, shot.end - shot.start)
+    if span <= length * 1.35:
+        # A shot a little over the ceiling is left whole. Splitting 5s into
+        # 4 + 1 gives a one-second beat that can only fit two callouts.
+        return [(shot.start, shot.end)]
+    count = max(2, int(round(span / length)))
+    return [(shot.start + span * i / count, shot.start + span * (i + 1) / count)
+            for i in range(count)]
+
+
+def context_times(shots, total: int = CONTEXT_FRAMES) -> list[float]:
+    """Times for the overview and subject passes, with every shot represented.
+
+    Each shot gets at least one frame; whatever is left over goes to the
+    longest shots, which is where most of the movement lives.
+    """
+    if not shots:
+        return []
+    share = {shot.index: 1 for shot in shots}
+    spare = max(0, total - len(shots))
+    for shot in sorted(shots, key=lambda s: -s.duration):
+        if spare <= 0:
+            break
+        share[shot.index] += 1
+        spare -= 1
+
+    times: list[float] = []
+    for shot in shots:
+        times.extend(sample_times(shot.start, shot.end, share[shot.index]))
+    return sorted(times)
+
+
+def clock(seconds: float) -> str:
+    """MM:SS.mmm -- the timestamp format used in the callouts."""
+    minutes, rest = divmod(max(0.0, float(seconds)), 60.0)
+    return f"{int(minutes):02d}:{rest:06.3f}"
+
+
+def timestamp_list(times: list[float]) -> str:
+    """The frame timestamps, formatted as one comma-separated line.
+
+    One line rather than a bulleted list on purpose: the model treats a bulleted
+    list as things to describe one by one, which is exactly what "detailed" is
+    supposed to do and exactly what "brief" is supposed to avoid. A flat line
+    reads as reference material for both.
+    """
+    return ", ".join(clock(t) for t in times)
+
+
+def aim_callouts(times: list[float], detail: str) -> int:
+    """Roughly how many callouts to ask for in brief mode.
+
+    Scales with the number of frames sampled -- about half of them -- so a
+    dense sampling doesn't get flattened into two callouts and a sparse
+    sampling doesn't get every-timestamp coverage. Floored at 2 so the model
+    still writes a callout even for the shortest beat.
+    """
+    if detail != "brief":
+        return len(times)
+    return max(2, len(times) // 2)
+
+
+def assign_speech(speech, shots) -> dict:
+    """Map shot index -> its speech segments, each segment used exactly once.
+
+    Same rule as the transcriber: a line spoken across a cut goes to whichever
+    shot it spends most of itself in. Motion transfer clips rarely have
+    dialogue, but when they do (a spoken cue, a coach counting) placing it in
+    the right shot matters as much as anywhere.
+    """
+    placed: dict = {shot.index: [] for shot in shots}
+    if not shots:
+        return placed
+
+    for segment in speech.segments:
+        start, end = segment[0], segment[1]
+        best, most = shots[0], -1.0
+        for shot in shots:
+            overlap = min(end, shot.end) - max(start, shot.start)
+            if overlap > most:
+                best, most = shot, overlap
+        placed[best.index].append(segment)
+    return placed
+
+
+# Words with no identifying weight, dropped before the "are these two lines
+# the same subject" check.
+_FILLER = {"a", "an", "the", "in", "on", "with", "and", "of", "is", "has",
+           "wearing", "wears", "dressed", "who", "that", "his", "her", "their",
+           "man", "woman", "person", "young", "older", "adult", "dancer",
+           "mover", "subject"}
+
+
+def _same_subject(first: str, second: str) -> bool:
+    import re
+
+    def words(text):
+        return {w for w in re.findall(r"[a-z]+", text.lower()) if w not in _FILLER}
+
+    left, right = words(first), words(second)
+    if not left or not right:
+        return False
+    return len(left & right) / min(len(left), len(right)) >= 0.6
+
+
+def clean_subjects(raw: str) -> str:
+    """Tidy the subject pass: strip formatting, drop NONE, merge repeats.
+
+    Motion clips usually have one mover, but a duet or group clip produces two
+    or three lines and the model sometimes lists the same person twice from
+    two framings. Same merge logic as the transcriber, tuned filler words for
+    the motion vocabulary.
+    """
+    import re
+
+    if not raw or raw.strip().upper().startswith("NONE"):
+        return ""
+
+    rows = []
+    for row in raw.splitlines():
+        row = row.strip()
+        if not row or row.upper() == "NONE":
+            continue
+        row = re.sub(r"^[-*\u2022]\s*|^\d+[.)]\s*", "", row)
+        row = re.sub(r"^(Man|Woman|Person|Subject|Mover|Dancer)\s*[A-Z0-9]?\s*[-:]\s*",
+                     "", row, flags=re.IGNORECASE)
+        row = row.rstrip(" .;,")
+        # A model that echoes the prompt's placeholder rather than filling it
+        # in produces a line with angle brackets. That is instruction text, not
+        # a subject, and it must never reach the shot passes -- everything on
+        # this list is asserted as fact in every callout afterwards.
+        if "<" in row and ">" in row:
+            continue
+        if row:
+            rows.append(row)
+
+    merged = list(rows)
+    for _ in range(4):
+        collapsed: list[str] = []
+        for row in merged:
+            for index, existing in enumerate(collapsed):
+                if _same_subject(existing, row):
+                    if len(row) > len(existing):
+                        collapsed[index] = row
+                    break
+            else:
+                collapsed.append(row)
+        if len(collapsed) == len(merged):
+            break
+        merged = collapsed
+    return "\n".join(merged)
+
+
+def sections(overview: str, subjects: str, shots: list, speech) -> dict:
+    """The output broken into its pieces so each can leave the node separately.
+
+    Shape kept deliberately close to the transcriber's ``sections`` -- same
+    dict keys ("overview", "subjects", "shots", "audio"), same
+    ``[Shot N] From X to Y`` header on every shot, same indented ``speech ...``
+    lines -- so the two nodes' outputs slot into the same downstream text
+    handling and can be merged later without either side needing to know
+    which node it came from.
+
+    The beat text itself is the one place they differ: transcriber beats are
+    prose paragraphs, motion beats are timestamped callouts. Both drop under
+    the shot header the same way -- one blank line, then the text -- so the
+    surrounding structure is identical.
+    """
+    subject_text = clean_subjects(subjects)
+    placed = assign_speech(speech, [shot for shot, _ in shots])
+
+    rows: list[str] = []
+    for shot, beats in shots:
+        if rows:
+            rows.append("")
+        rows.append(f"[Shot {shot.index}] From {clock(shot.start)} to "
+                    f"{clock(shot.end)}")
+        # Callouts already carry their own timestamps, so a per-beat time-range
+        # prefix would duplicate that. The beats are just concatenated with a
+        # blank line between them, and the callout stream reads as one shot.
+        for _, _, text in beats:
+            rows.append("")
+            rows.append(text.strip())
+        for start, end, said in placed.get(shot.index, []):
+            rows.append(f"    speech {clock(start)}-{clock(end)}: \"{said}\"")
+
+    if speech.note:
+        audio = speech.note
+    elif speech.spoken:
+        audio = (f"speech in {speech.language_full or 'an unknown language'} "
+                 f"({speech.probability:.0%} confidence)")
+    else:
+        audio = "no speech detected"
+
+    return {"overview": (overview or "").strip(),
+            "subjects": subject_text,
+            "shots": "\n".join(rows),
+            "audio": audio}
+
+
+def assemble(overview: str, subjects: str, shots: list, speech) -> str:
+    """Everything, in one block -- the full description output.
+
+    Section headers match the transcriber's exactly ("overview:",
+    "characters identified:", "shots:", "audio:") so the two blocks are
+    interchangeable to whatever parses them downstream.
+    """
+    part = sections(overview, subjects, shots, speech)
+    lines: list[str] = []
+    if part["overview"]:
+        lines += [f"overview: {part['overview']}", ""]
+    if part["subjects"]:
+        lines += ["characters identified:", part["subjects"], ""]
+    lines += ["shots:", "", part["shots"]]
+    if part["audio"]:
+        # Two blank lines rather than one, so the audio footer visually
+        # breaks away from the shots block above. The shots block ends with
+        # a callout line, and a single blank line was reading as part of the
+        # last beat rather than a section break.
+        lines += ["", "", f"audio: {part['audio']}"]
+    return "\n".join(lines).strip()
+
+
+def transcript_text(speech) -> str:
+    """The transcript on its own, with timings, for downstream reformatting."""
+    if not speech.spoken:
+        return speech.note or "no speech detected"
+    rows = [f"[{clock(start)} - {clock(end)}] {text}"
+            for start, end, text in speech.segments]
+    if speech.note:
+        rows.append(f"({speech.note})")
+    return "\n".join(rows)

custom_nodes/ComfyUI-Nugget/nodes_image.py

@@ -0,0 +1,328 @@
+"""Batching images without cropping them.
+
+ComfyUI's IMAGE type is one tensor shaped (batch, height, width, channels), so
+every image in a batch must share a height and a width. KJNodes' ImageBatchMulti
+resolves that by scaling images 2..N to match image 1 and centre-cropping the
+overflow, which is fine for images of the same shape and destructive for
+anything else -- a portrait dropped into a landscape slot loses its top and
+bottom, which is where a face usually is.
+
+These nodes pad instead. Every image is scaled to *fit* the canvas and the
+remainder is filled, so nothing is cropped and nothing is stretched.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import torch
+
+import comfy.utils
+from comfy_api.latest import io
+
+log = logging.getLogger("Nugget")
+
+MAX_INPUTS = 9
+
+SCALE_METHODS = ["lanczos", "bicubic", "area", "bilinear", "nearest-exact"]
+PAD_COLORS = ["black", "white", "grey", "custom hex"]
+POSITIONS = ["center", "top", "bottom", "left", "right"]
+
+
+def _hex_to_rgb(value: str):
+    value = (value or "").strip().lstrip("#")
+    if len(value) == 3:
+        value = "".join(c * 2 for c in value)
+    if len(value) != 6:
+        return (0.0, 0.0, 0.0)
+    try:
+        return tuple(int(value[i:i + 2], 16) / 255.0 for i in (0, 2, 4))
+    except ValueError:
+        return (0.0, 0.0, 0.0)
+
+
+def _pad_rgb(pad_color: str, pad_hex: str):
+    if pad_color == "white":
+        return (1.0, 1.0, 1.0)
+    if pad_color == "grey":
+        return (0.5, 0.5, 0.5)
+    if pad_color == "custom hex":
+        return _hex_to_rgb(pad_hex)
+    return (0.0, 0.0, 0.0)
+
+
+def _offsets(canvas_w, canvas_h, new_w, new_h, position):
+    x = (canvas_w - new_w) // 2
+    y = (canvas_h - new_h) // 2
+    if position == "top":
+        y = 0
+    elif position == "bottom":
+        y = canvas_h - new_h
+    elif position == "left":
+        x = 0
+    elif position == "right":
+        x = canvas_w - new_w
+    return max(0, x), max(0, y)
+
+
+def collect(images: dict):
+    """Flatten every connected socket -- each may itself be a batch -- into HWC frames.
+
+    Sockets are read in slot order and gaps are skipped rather than fatal, so a
+    graph with image_1 and image_3 connected still works.
+    """
+    frames = []
+    filled = []
+    for i in range(1, MAX_INPUTS + 1):
+        image = images.get(f"image_{i}")
+        if image is None or getattr(image, "shape", None) is None \
+                or len(image.shape) < 3:
+            # None is a bypassed loader with nothing to pass through. Something
+            # without a shape is a bypassed loader passing its widget value
+            # through instead -- a filename, a number. Neither is an image, and
+            # reading .shape off the second is an AttributeError mid-run.
+            continue
+        filled.append(i)
+        for f in range(image.shape[0]):
+            frames.append(image[f])
+
+    # A bypassed Load Image leaves its link in place and delivers None, so the
+    # canvas still shows the socket as wired while nothing arrives. Skipping the
+    # hole is the only option -- a vision encoder cannot be handed a gap -- but
+    # it renumbers everything after it, and a prompt written against <Picture 4>
+    # then refers to an image the model was never given. Silent is the wrong
+    # behaviour here, so say so.
+    if filled and filled != list(range(1, len(filled) + 1)):
+        empty = [i for i in range(1, max(filled)) if i not in filled]
+        mapping = ", ".join(f"image_{s} is picture {p}"
+                            for p, s in enumerate(filled, start=1))
+        log.warning(
+            "[Nugget] %s %s empty (bypassed?), so the remaining references were "
+            "renumbered: %s. A prompt naming a higher picture number will not "
+            "match.",
+            ", ".join(f"image_{i}" for i in empty),
+            "is" if len(empty) == 1 else "are", mapping)
+
+    if not frames:
+        raise ValueError(
+            "No images connected. If an upstream Load Image node is bypassed, "
+            "its output is empty -- connect an image or remove this node.")
+
+    # Harmonise channel counts. Mixing RGB and RGBA would otherwise fail to
+    # stack; the narrower frames gain an opaque alpha instead.
+    channels = {int(f.shape[2]) for f in frames}
+    if len(channels) > 1:
+        target = max(channels)
+        fixed = []
+        for f in frames:
+            have = int(f.shape[2])
+            if have < target:
+                pad = torch.ones((int(f.shape[0]), int(f.shape[1]), target - have),
+                                 device=f.device, dtype=f.dtype)
+                f = torch.cat((f, pad), dim=2)
+            elif have > target:
+                f = f[:, :, :target]
+            fixed.append(f)
+        frames = fixed
+
+    # Sockets can carry tensors from different devices. Stacking those fails, so
+    # bring everything to the first frame's device before anything else.
+    device = frames[0].device
+    if any(f.device != device for f in frames):
+        frames = [f.to(device) for f in frames]
+    return frames
+
+
+def canvas_for(frames, max_width: int, max_height: int):
+    """The smallest canvas that holds every input, scaled down to the ceiling.
+
+    The union box is (widest, tallest). That box is then scaled to fit inside
+    max_width x max_height **preserving its own aspect ratio**.
+
+    Clamping the two axes independently instead -- ``min(widest, max_width)`` and
+    ``min(tallest, max_height)`` -- looks equivalent and is not. It destroys the
+    box's aspect: a single 1920x1080 image against a 1024x1024 ceiling yields a
+    1024x1024 square canvas, so a lone image with nothing to reconcile against
+    comes back 44% bars. Three identically shaped portraits come back 16% bars.
+    Padding a set that needs no padding is precisely the failure this node exists
+    to avoid.
+
+    The canvas never exceeds the largest input either, so a ceiling of 16384 with
+    64x64 inputs still gives a 64x64 canvas rather than upscaling everything.
+    """
+    widest = max(int(f.shape[1]) for f in frames)
+    tallest = max(int(f.shape[0]) for f in frames)
+
+    ratio = min(int(max_width) / widest, int(max_height) / tallest, 1.0)
+    return (max(1, int(round(widest * ratio))),
+            max(1, int(round(tallest * ratio))))
+
+
+def compose(frames, canvas_w, canvas_h, scale_method, allow_upscale,
+            pad_color, pad_hex, position):
+    """Scale each frame to fit the canvas and pad the remainder."""
+    rgb = _pad_rgb(pad_color, pad_hex)
+    device = frames[0].device
+    dtype = frames[0].dtype
+
+    out_frames, out_masks = [], []
+
+    for frame in frames:
+        src_h, src_w = int(frame.shape[0]), int(frame.shape[1])
+        channels = int(frame.shape[2])
+
+        # contain / letterbox: the whole image fits inside the canvas
+        ratio = min(canvas_w / src_w, canvas_h / src_h)
+        if not allow_upscale:
+            ratio = min(ratio, 1.0)
+
+        new_w = max(1, min(canvas_w, int(round(src_w * ratio))))
+        new_h = max(1, min(canvas_h, int(round(src_h * ratio))))
+
+        if (new_w, new_h) != (src_w, src_h):
+            nchw = frame.unsqueeze(0).movedim(-1, 1)
+            nchw = comfy.utils.common_upscale(
+                nchw.float(), new_w, new_h, scale_method, "disabled")
+            resized = nchw.movedim(1, -1).squeeze(0).to(dtype)
+        else:
+            resized = frame
+
+        canvas = torch.empty((canvas_h, canvas_w, channels),
+                             device=device, dtype=torch.float32)
+        if channels == 1:
+            # Greyscale: collapse the pad colour to luminance rather than taking
+            # the red channel, which would render #0000ff as black.
+            canvas[:, :, 0] = 0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2]
+        else:
+            for c in range(channels):
+                # Alpha, where present, is opaque so the bars are visible rather
+                # than silently transparent.
+                canvas[:, :, c] = rgb[c] if c < 3 else 1.0
+
+        mask = torch.zeros((canvas_h, canvas_w), device=device, dtype=torch.float32)
+
+        x, y = _offsets(canvas_w, canvas_h, new_w, new_h, position)
+        canvas[y:y + new_h, x:x + new_w, :] = resized.float()
+        mask[y:y + new_h, x:x + new_w] = 1.0
+
+        out_frames.append(canvas.to(dtype))
+        out_masks.append(mask)
+
+    return torch.stack(out_frames, dim=0), torch.stack(out_masks, dim=0)
+
+
+def padding_report(masks) -> str:
+    """How much of each frame is bars. Worth surfacing: heavy padding means the
+    references disagree about shape, and the fix is upstream, not here."""
+    shares = [100.0 * (1.0 - float(masks[i].mean())) for i in range(masks.shape[0])]
+    worst = max(shares) if shares else 0.0
+    rows = ", ".join(f"image {i + 1}: {s:.0f}%" for i, s in enumerate(shares))
+    if worst < 1.0:
+        return f"no padding needed ({rows})"
+    return f"padding {rows}"
+
+
+class NuggetImageBatchNoCrop(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="ImageBatchMultiNoCrop",
+            display_name="Batch images (no crop)",
+            category="Nugget",
+            search_aliases=["batch", "pad", "letterbox", "reference images",
+                            "imagebatchmulti"],
+            description=(
+                "Batches up to 9 images into one IMAGE tensor without cropping. "
+                "The canvas is the smallest box that holds every input, scaled "
+                "down to the ceiling you set. Each image is scaled to fit and "
+                "the remainder padded. Sockets appear as you connect them."),
+            inputs=[
+                io.Image.Input("image_1"),
+                *[io.Image.Input(f"image_{i}", optional=True)
+                  for i in range(2, MAX_INPUTS + 1)],
+                io.Int.Input("max_width", default=1024, min=16, max=16384, step=8,
+                             display_name="max width",
+                             tooltip="Ceiling, not a target. The canvas never "
+                                     "exceeds this, and never exceeds the largest "
+                                     "input either."),
+                io.Int.Input("max_height", default=1024, min=16, max=16384, step=8,
+                             display_name="max height"),
+                io.Combo.Input("scale_method", options=SCALE_METHODS,
+                               default="lanczos", display_name="scale method"),
+                io.Boolean.Input("allow_upscale", default=True,
+                                 display_name="allow upscale",
+                                 tooltip="Off keeps images smaller than the canvas "
+                                         "at their native size, padding the rest."),
+                io.Combo.Input("pad_color", options=PAD_COLORS, default="black",
+                               display_name="pad colour"),
+                io.String.Input("pad_hex", default="#000000", display_name="pad hex",
+                                optional=True, advanced=True),
+                io.Combo.Input("position", options=POSITIONS, default="center",
+                               tooltip="Where the image sits within the canvas."),
+            ],
+            outputs=[
+                io.Image.Output(display_name="images"),
+                io.Mask.Output(display_name="content_mask"),
+                io.Int.Output(display_name="width"),
+                io.Int.Output(display_name="height"),
+                io.String.Output(display_name="padding_report"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, max_width=1024, max_height=1024, scale_method="lanczos",
+                allow_upscale=True, pad_color="black", pad_hex="#000000",
+                position="center", **images) -> io.NodeOutput:
+        frames = collect(images)
+        canvas_w, canvas_h = canvas_for(frames, max_width, max_height)
+        batch, masks = compose(frames, canvas_w, canvas_h, scale_method,
+                               allow_upscale, pad_color, pad_hex, position)
+        report = padding_report(masks)
+        if "no padding" not in report:
+            log.info("[Nugget] batch %dx%d -- %s", canvas_w, canvas_h, report)
+        return io.NodeOutput(batch, masks, canvas_w, canvas_h, report)
+
+
+class NuggetImagePadToSize(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="ImagePadToSize",
+            display_name="Pad image to size (no crop)",
+            category="Nugget",
+            search_aliases=["pad", "letterbox", "resize", "fit"],
+            description="Letterbox an image to an exact size. Nothing is cropped.",
+            inputs=[
+                io.Image.Input("image"),
+                io.Int.Input("width", default=1024, min=16, max=16384, step=8),
+                io.Int.Input("height", default=1024, min=16, max=16384, step=8),
+                io.Combo.Input("scale_method", options=SCALE_METHODS,
+                               default="lanczos", display_name="scale method"),
+                io.Boolean.Input("allow_upscale", default=True,
+                                 display_name="allow upscale"),
+                io.Combo.Input("pad_color", options=PAD_COLORS, default="black",
+                               display_name="pad colour"),
+                io.String.Input("pad_hex", default="#000000", display_name="pad hex",
+                                optional=True, advanced=True),
+                io.Combo.Input("position", options=POSITIONS, default="center"),
+            ],
+            outputs=[
+                io.Image.Output(display_name="image"),
+                io.Mask.Output(display_name="content_mask"),
+            ],
+        )
+
+    @classmethod
+    def execute(cls, image, width=1024, height=1024, scale_method="lanczos",
+                allow_upscale=True, pad_color="black", pad_hex="#000000",
+                position="center") -> io.NodeOutput:
+        frames = collect({"image_1": image})
+        # width/height are an exact target here, not a ceiling, so the canvas is
+        # used as given rather than derived from the inputs.
+        batch, masks = compose(frames, max(1, int(width)), max(1, int(height)),
+                               scale_method, allow_upscale, pad_color, pad_hex,
+                               position)
+        return io.NodeOutput(batch, masks)
+
+
+NODES = [NuggetImageBatchNoCrop, NuggetImagePadToSize]

custom_nodes/ComfyUI-Nugget/nodes_motion.py

@@ -0,0 +1,472 @@
+"""The motion-transfer node.
+
+Sibling of ``nodes_transcribe.py``. The pipeline is the same shape --
+read the video, detect cuts, run Whisper (if asked), decode every frame
+the plan needs in one pass, then run the vision passes -- because that
+order is what keeps Whisper and the text encoder off the GPU at the
+same time. Only the prompts and the output assembly differ.
+
+The output focuses on WHAT THE BODY DOES, WHEN. A single "motion"
+section holds timestamped callouts instead of prose shot descriptions.
+When only one shot survives cut detection (the common motion-transfer
+case: a single continuous take of a dancer), the shot header is
+dropped -- there's no second shot to disambiguate from.
+
+Whisper defaults to off here. Motion transfer clips almost always have
+music rather than dialogue, and speech transcription of music beds is
+confident-sounding nonsense that muddies the output. The widget is
+still available for the rare clip with a spoken cue.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+
+from comfy_api.latest import io
+
+from . import (camera, detect, llm, motion_prompts as prompts, recall,
+               speech as speech_mod, video as video_mod)
+
+log = logging.getLogger("Nugget")
+
+# Same limit as the transcriber. Past this the vision passes take long enough
+# people assume the node has hung, and the frame counts stop fitting in
+# context. Refuse clearly rather than accepting a clip we can't finish.
+MAX_SECONDS = 120.0
+
+WHISPER_MODELS = ["off", "large-v3", "large-v3-turbo", "medium", "small",
+                  "base", "tiny"]
+
+FRAME_SIZES = [384, 512, 768, 1024]
+
+LANGUAGE_CHOICES = [
+    "auto", "English", "Spanish", "French", "German", "Italian", "Portuguese",
+    "Dutch", "Polish", "Russian", "Japanese", "Korean", "Chinese", "Cantonese",
+    "Arabic", "Hindi", "Turkish", "Vietnamese", "Thai", "Indonesian",
+    "Ukrainian", "Swedish", "Norwegian", "Danish", "Finnish", "Greek", "Czech",
+    "Romanian", "Hungarian", "Hebrew", "Malay", "Filipino",
+]
+
+
+def _interrupted() -> None:
+    """Let Cancel actually cancel between model calls."""
+    try:
+        from comfy import model_management
+        model_management.throw_exception_if_processing_interrupted()
+    except ImportError:
+        pass
+
+
+class _Progress:
+    """Progress bar + log line. Degrades to logging alone."""
+
+    def __init__(self, total: int):
+        self.bar = None
+        try:
+            from comfy.utils import ProgressBar
+            self.bar = ProgressBar(total)
+        except Exception:
+            pass
+
+    def step(self, message: str) -> None:
+        log.info("[Nugget] %s", message)
+        if self.bar is not None:
+            try:
+                self.bar.update(1)
+            except Exception:
+                pass
+
+
+class NuggetMotionTransfer(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="NuggetMotionTransfer",
+            display_name="Nugget Motion Transfer",
+            category="Nugget",
+            search_aliases=["motion", "transfer", "pose", "dance", "ref2v",
+                            "reference to video", "movement", "choreography"],
+            description=("Describe a short video's motion in timestamped "
+                         "callouts, for feeding into a reference-to-video "
+                         "prompt (H3 ref2v and similar)."),
+            inputs=[
+                io.Clip.Input("clip", tooltip="A Gemma or Qwen3-VL text "
+                                              "encoder, from Load CLIP."),
+                io.Video.Input(
+                    "video", optional=True,
+                    tooltip="The clip to describe. Under 2 minutes. Bypass "
+                            "the Load Video node to switch this node off -- "
+                            "it returns empty outputs instead of failing."),
+                io.Int.Input(
+                    "prompt_max_length", default=0, min=0, max=4096, step=32,
+                    display_name="prompt max length",
+                    tooltip="Token budget per shot. 0 follows the detail "
+                            "level (220 / 380 / 700) and is the default. "
+                            "Raise it if callouts stop mid-sentence -- the "
+                            "log warns when that happens."),
+                io.Combo.Input(
+                    "description_detail", options=list(prompts.DETAIL.keys()),
+                    default="normal", display_name="description detail",
+                    tooltip="How dense the callouts are. brief writes a short "
+                            "opening sentence then only lists moments where "
+                            "the pose changes. detailed writes one callout "
+                            "for every sampled timestamp (~0.5s apart). "
+                            "normal is in between."),
+                io.Combo.Input(
+                    "scene_sensitivity", options=["low", "normal", "high"],
+                    default="normal", display_name="scene sensitivity",
+                    tooltip="Cut detection. Most motion-transfer clips are "
+                            "one shot; the detector only fires if the cut is "
+                            "obvious, and the output collapses the shot "
+                            "header when there's only one."),
+                io.Float.Input(
+                    "min_shot", default=0.5, min=0.2, max=30.0, step=0.1,
+                    display_name="min shot",
+                    tooltip="Shortest shot allowed, in seconds. Two cuts "
+                            "closer together than this become one."),
+                io.Combo.Input(
+                    "max_frame_size", options=FRAME_SIZES, default=768,
+                    display_name="max frame size",
+                    tooltip="Maximum width frames are scaled to before the "
+                            "model sees them. Ceiling, not target -- a "
+                            "smaller source is never upscaled. Drop to 512 "
+                            "for speed, raise to 1024 if the model is "
+                            "missing fine limb positions."),
+                io.Combo.Input(
+                    "frame_layout", options=["grid", "separate"],
+                    default="grid", optional=True, advanced=True,
+                    display_name="frame layout",
+                    tooltip="grid composites each beat's frames into one "
+                            "image and shows motion at a glance. separate "
+                            "sends them as individual images -- more spatial "
+                            "detail per frame, several times slower. For "
+                            "motion the grid is almost always the right "
+                            "choice because temporal order is what matters."),
+                io.Combo.Input(
+                    "whisper_model", options=WHISPER_MODELS, default="off",
+                    display_name="whisper model",
+                    tooltip="Speech transcription. Defaulted OFF because "
+                            "motion clips usually have music, not dialogue, "
+                            "and Whisper on music beds returns confident "
+                            "nonsense. Turn on only if the clip has a "
+                            "spoken cue or count worth capturing."),
+                io.Combo.Input(
+                    "audio_language", options=LANGUAGE_CHOICES, default="auto",
+                    display_name="audio language",
+                    tooltip="Spoken language, if you enabled whisper. Leave "
+                            "on auto to detect it."),
+                # Deliberately no control_after_generate. See the transcriber
+                # for the full explanation: ComfyUI caches unchanged inputs,
+                # a self-randomising seed misses every queue, and generation
+                # is greedy so the re-run would be byte-identical anyway.
+                io.Int.Input(
+                    "seed", default=0, min=0, max=0xffffffffffffffff,
+                    optional=True, advanced=True,
+                    tooltip="Only used if temperature is raised in llm.py. "
+                            "Output is greedy and repeatable, so this is "
+                            "fixed on purpose."),
+            ],
+            outputs=[
+                io.Image.Output(display_name="images"),
+                io.Audio.Output(display_name="audio"),
+                io.Float.Output(display_name="fps"),
+                io.Int.Output(display_name="frame_count"),
+                io.String.Output(display_name="full description"),
+                io.String.Output(display_name="overview"),
+                io.String.Output(display_name="characters identified"),
+                io.String.Output(display_name="shots"),
+                io.String.Output(display_name="audio transcription"),
+                io.String.Output(display_name="audio language"),
+            ],
+        )
+
+    @classmethod
+    def validate_inputs(cls, input_types=None, **kwargs):
+        """Skip ComfyUI's link type check so bypass doesn't fail the graph.
+
+        See VideoAutoTranscribe for the full explanation -- same reasoning
+        applies here.
+        """
+        return True
+
+    VALIDATE_INPUTS = validate_inputs
+
+    @classmethod
+    def _switched_off(cls, reason: str = "") -> io.NodeOutput:
+        """Empty outputs for a run that's deliberately doing nothing.
+
+        Strings are a single space rather than empty: some downstream text
+        nodes (Preview Text and its cousins) raise on an empty STRING input
+        instead of showing an empty box, which would take the whole graph
+        down exactly when the user has switched a branch off. A single space
+        passes every truthiness check downstream and reads as empty to
+        anything that strips whitespace.
+        """
+        import torch
+        if reason:
+            log.info("[Nugget] %s -- skipping, all outputs are empty", reason)
+        blank = " "
+        return io.NodeOutput(torch.zeros((1, 1, 1, 3)),
+                             video_mod.silence(), 0.0, 0,
+                             blank, blank, blank, blank, blank, blank)
+
+    @classmethod
+    def execute(cls, clip, video=None, prompt_max_length=0,
+                description_detail="normal",
+                scene_sensitivity="normal", min_shot=0.5, max_frame_size=768,
+                frame_layout="grid", whisper_model="off",
+                audio_language="auto", seed=0) -> io.NodeOutput:
+
+        detail, sensitivity = description_detail, scene_sensitivity
+        language = speech_mod.language_code(audio_language)
+        frame_size = max_frame_size
+
+        started = time.time()
+
+        # Bypassed Load Video hands us None. That's a branch being switched
+        # off, not a broken graph, so return empty strings that join onto
+        # downstream prompts without leaving a stray line.
+        if video_mod.missing(video):
+            log.info("[Nugget] no usable video on the input "
+                     "(unconnected, or Load Video is bypassed) -- skipping")
+            return cls._switched_off()
+
+        llm.check(clip)          # fail fast on a bad graph
+        try:
+            handle = video_mod.open_clip(video)
+        except video_mod.NoSource as exc:
+            return cls._switched_off(f"nothing usable on the video input ({exc})")
+        wav = None
+
+        try:
+            if handle.duration > MAX_SECONDS:
+                raise video_mod.VideoError(
+                    f"That clip is {handle.duration:.0f}s. This node is built "
+                    f"for clips under {MAX_SECONDS:.0f}s -- trim it, or split "
+                    f"it and describe the parts separately.")
+            if handle.variable_fps:
+                log.warning("[Nugget] variable frame rate: tagged %.2f fps "
+                            "but the real average is %.2f. Callout timestamps "
+                            "come from each frame's own timestamp, so they "
+                            "are correct.",
+                            handle.declared_fps, handle.fps)
+
+            floor = float(min_shot)
+            if floor > handle.duration / 2:
+                floor = max(0.2, handle.duration / 4)
+                log.warning("[Nugget] min_shot %.1fs is too long for a %.1fs "
+                            "clip; using %.2fs", min_shot, handle.duration, floor)
+
+            log.info("[Nugget] %dx%d, %.2fs",
+                     handle.width, handle.height, handle.duration)
+
+            # Cache exactly like the transcriber, on all the settings that
+            # change the output. Motion transfer runs are slow and re-queuing
+            # the same clip with the same settings should be free.
+            settings = {"prompt_max_length": prompt_max_length,
+                        "detail": detail,
+                        "sensitivity": sensitivity,
+                        "min_shot": round(float(floor), 3),
+                        "frame_size": int(frame_size),
+                        "frame_layout": frame_layout,
+                        "whisper": whisper_model,
+                        "language": language or "auto",
+                        "seed": seed,
+                        # Namespace the cache: same key would otherwise
+                        # collide with a transcriber run on the same file,
+                        # and the two nodes' outputs have different shapes.
+                        "node": "motion_transfer"}
+            cache_key = recall.key(handle.path, clip, settings, handle.temporary)
+            remembered = recall.get(cache_key)
+            if remembered and remembered[0].strip():
+                log.info("[Nugget] already described this clip's motion with "
+                         "these settings -- reusing the text, decoding the "
+                         "frames again")
+                try:
+                    all_frames, real_fps, frame_count = video_mod.decode_all(handle)
+                    audio_cached = video_mod.audio_tensor(handle)
+                except video_mod.VideoError as exc:
+                    import torch
+                    log.warning("[Nugget] using cached description, but frames "
+                                "could not be decoded (%s) -- images output "
+                                "is a 1x1 placeholder", exc)
+                    all_frames = torch.zeros((1, 1, 1, 3))
+                    audio_cached = video_mod.silence()
+                    real_fps, frame_count = 0.0, 0
+                return io.NodeOutput(all_frames, audio_cached,
+                                     real_fps, frame_count, *remembered)
+
+            # Full frames and soundtrack so this node stands in for a Get
+            # Video Components plus a frame count.
+            all_frames, real_fps, frame_count = video_mod.decode_all(handle)
+            audio_out = video_mod.audio_tensor(handle)
+            log.info("[Nugget] %d frames at %.2f fps", frame_count, real_fps)
+
+            # --- cuts. If the clip is one continuous shot, we'll notice
+            # here and drop the shot header from the output later.
+            scores, motion = video_mod.scan(handle)
+            _interrupted()
+            cuts = detect.find_cuts(scores, sensitivity, floor,
+                                    0.0, handle.duration)
+            shots = detect.build_shots(cuts, 0.0, handle.duration)
+            log.info("[Nugget] %d shot(s), cuts at %s",
+                     len(shots), [round(c, 3) for c in cuts])
+
+            # --- speech, before the encoder is touched.
+            total_beats = sum(len(prompts.beats_for(shot, detail))
+                              for shot in shots)
+            progress = _Progress(total_beats + 3)
+            if whisper_model == "off":
+                progress.step("skipping audio (default for motion transfer)")
+                speech = speech_mod.Speech(note="transcription turned off")
+            else:
+                progress.step(f"transcribing with {whisper_model}")
+                wav = video_mod.extract_audio(handle)
+                speech = speech_mod.transcribe(wav, whisper_model, language)
+            video_mod.cleanup(wav)
+            wav = None
+            _interrupted()
+
+            # --- plan every frame the run needs, then decode once.
+            progress.step("decoding frames")
+            context = prompts.context_times(shots)
+
+            plan = []       # (shot, beat_start, beat_end, [times])
+            for shot in shots:
+                beats = prompts.beats_for(shot, detail)
+                for start, end in beats:
+                    count = prompts.frames_for(end - start, detail)
+                    plan.append((shot, start, end,
+                                 prompts.sample_times(start, end, count)))
+
+            wanted = list(context)
+            for _, _, _, times in plan:
+                wanted.extend(times)
+            decoded = {round(t, 3): image for t, image
+                       in video_mod.frames_at(handle, wanted,
+                                              width=int(frame_size))}
+
+            def frames(times):
+                return [decoded[key] for key in (round(t, 3) for t in times)
+                        if key in decoded]
+
+            def payload(images):
+                if frame_layout == "grid":
+                    return (video_mod.to_grid(images, int(frame_size)),
+                            len(images))
+                return images, len(images)
+
+            # --- vision. VRAM check before the encoder loads -- same
+            # rationale as the transcriber.
+            try:
+                from comfy import model_management
+                free = model_management.get_free_memory(
+                    model_management.get_torch_device())
+                log.info("[Nugget] %.1f GB free before loading the text "
+                         "encoder", free / (1024 ** 3))
+                if free < 5 * (1024 ** 3):
+                    log.warning("[Nugget] under 5 GB free -- if ComfyUI exits "
+                                "without an error, the encoder is too large "
+                                "for this card. Try a smaller one.")
+            except Exception:
+                pass
+
+            budget = prompts.token_budget(detail, prompt_max_length)
+
+            wide, _ = payload(frames(context))
+            progress.step("overall motion and subject")
+            overview = llm.ask(clip, prompts.OVERVIEW, wide,
+                               budget["overview"], seed)
+            _interrupted()
+            subjects = prompts.clean_subjects(
+                llm.ask(clip, prompts.SUBJECTS, wide, budget["subject"], seed))
+
+            tokens = budget["shot"]
+            shot_template = prompts.shot_prompt(detail)
+            grouped: dict = {}
+
+            for position, (shot, start, end, times) in enumerate(plan):
+                _interrupted()
+                progress.step(f"shot {shot.index} of {len(shots)}"
+                              + (f", beat at {prompts.clock(start)}"
+                                 if len(prompts.beats_for(shot, detail)) > 1
+                                 else ""))
+                images, count = payload(frames(times))
+                first = shot.index not in grouped
+
+                if frame_layout == "grid" and count > 1:
+                    layout = prompts.GRID_NOTE.format(count=count)
+                else:
+                    layout = (f"These {count} frames are from ONE continuous "
+                              f"shot, in order.")
+                call_started = time.time()
+                movement = camera.summarise(motion, start, end)
+                # The timestamps handed to the model are the actual sampled
+                # frame times, so every callout the model writes can be
+                # traced back to a frame it was shown.
+                ts_line = prompts.timestamp_list(times)
+                aim = prompts.aim_callouts(times, detail)
+                prompt = shot_template.format(
+                    layout=layout,
+                    span=end - start,
+                    start_clock=prompts.clock(start),
+                    end_clock=prompts.clock(end),
+                    timestamp_list=ts_line,
+                    aim=aim,
+                    subjects=prompts.SUBJECTS_KNOWN.format(subjects=subjects)
+                    if subjects else "",
+                    camera=prompts.CAMERA_FACT.format(motion=movement)
+                    if movement else "")
+                if not first:
+                    prompt += prompts.CONTINUES
+
+                try:
+                    text = llm.ask(clip, prompt, images, tokens, seed)
+                except llm.LLMError as exc:
+                    log.warning("[Nugget] shot %d beat %d failed: %s",
+                                shot.index, position, exc)
+                    text = f"(this part could not be described: {exc})"
+                log.info("[Nugget] shot %d beat %s took %.1fs "
+                         "(%d frames, %d token budget)", shot.index,
+                         prompts.clock(start), time.time() - call_started,
+                         count, tokens)
+                if llm.looks_truncated(text, tokens):
+                    log.warning("[Nugget] shot %d ran out of tokens at %d and "
+                                "stopped mid-sentence -- raise "
+                                "prompt_max_length", shot.index, tokens)
+                grouped.setdefault(shot.index, []).append(
+                    (start, end, text or "(no callouts returned)"))
+
+            described = [(shot, grouped.get(shot.index,
+                                            [(shot.start, shot.end,
+                                              "(not described)")]))
+                         for shot in shots]
+
+            part = prompts.sections(overview, subjects, described, speech)
+            elapsed = time.time() - started
+            log.info("[Nugget] done in %.1fs across %d model call(s), "
+                     "%d token budget per shot", elapsed, len(plan) + 2, tokens)
+            if elapsed > 120 and prompt_max_length > 500:
+                log.warning("[Nugget] that run took %.0fs with "
+                            "prompt_max_length at %d. Detailed mode already "
+                            "generates a callout per timestamp; 0 (automatic) "
+                            "is much faster and the log says when it isn't "
+                            "enough.", elapsed, prompt_max_length)
+
+            written = (prompts.assemble(overview, subjects, described, speech),
+                       part["overview"],
+                       part["subjects"],
+                       part["shots"],
+                       prompts.transcript_text(speech),
+                       speech.language_full or "none")
+            recall.put(cache_key, written)
+            return io.NodeOutput(all_frames, audio_out, real_fps, frame_count,
+                                 *written)
+        finally:
+            video_mod.cleanup(wav)
+            if handle.temporary:
+                video_mod.cleanup(handle.path)
+
+
+NODES = [NuggetMotionTransfer]

custom_nodes/ComfyUI-Nugget/nodes_prompt.py

@@ -0,0 +1,411 @@
+"""Generating a prompt from reference images, in one node.
+
+This replaces core's ``Generate Text`` plus a separate image batching node. The
+merge is not cosmetic: batching and generating are the same decision.
+
+ComfyUI's IMAGE type is one tensor shaped ``(batch, height, width, channels)``,
+so every image in a batch must share a height and a width. That is a constraint
+of the tensor, not of the model -- the vision encoder handles varied aspect
+ratios natively. A node that batches images before handing them over is forced
+to crop or pad them to match; a node that holds them separately is not.
+
+So the images are kept apart for as long as possible and handed over as a list.
+If this build of ComfyUI insists on one stacked tensor, the node falls back to
+padding them onto a shared canvas and says so in the log once. Either way the
+caller does nothing.
+
+``max_image_size`` caps each image independently, preserving its aspect ratio and
+never upscaling. When the references share a shape -- the usual case -- that
+alone makes them identical sizes, so even the fallback has nothing to pad.
+"""
+
+from __future__ import annotations
+import logging
+import os
+
+from comfy_api.latest import io
+
+try:
+    from . import fingerprint, llm, nodes_image
+except ImportError:          # direct import in the test suite
+    import fingerprint
+    import llm
+    import nodes_image
+
+log = logging.getLogger("Nugget")
+
+MAX_INPUTS = 9
+
+IMAGE_SIZES = [384, 512, 768, 1024, 1280, 1536, 2048]
+
+# Appended to the prompt when set. "off" adds nothing, which is the right
+# default: the usual job here is a full system prompt that already specifies its
+# own format, and bolting a length instruction onto that just fights it. The
+# other settings are for using this node as a plain captioner.
+DETAIL = {
+    "off": ("", 0),
+    "brief": ("\n\nDescribe each reference image in one sentence.", 200),
+    "normal": ("\n\nDescribe each reference image in two or three sentences, "
+               "covering what it shows, clothing and colours, and the setting.",
+               450),
+    "detailed": ("\n\nDescribe each reference image thoroughly: the subject, "
+                 "their clothing and its colours and materials, hair, build, "
+                 "the setting, the lighting, and the framing. Describe only what "
+                 "is visible.", 900),
+}
+
+
+def _sampling_params():
+    return [
+        io.Float.Input("temperature", default=0.7, min=0.05, max=2.0, step=0.05,
+                       tooltip="Higher is more varied."),
+        io.Float.Input("repetition_penalty", default=1.0, min=1.0, max=1.5,
+                       step=0.01, display_name="repetition penalty",
+                       tooltip="1.0 is off, and off is right for structured "
+                               "output. A prompt format is supposed to repeat "
+                               "its own labels."),
+    ]
+
+
+SAMPLING_TIP = ("off is greedy: faster, and the same input gives the same "
+                "output. on adds randomness and reveals its parameters.")
+
+# Set at import so the log can say which shape worked, and so a workflow author
+# knows whether temperature is a top-level widget or nested under sampling_mode.
+DYNAMIC_SAMPLING = False
+
+
+def sampling_input():
+    """The sampling control, hiding its parameters when it is off.
+
+    Core's Generate Text uses a DynamicCombo for this, and Save Video's saved
+    keys (``format.codec``) confirm the type exists. The constructor signature
+    is not documented anywhere I could find and has been changing, so rather
+    than guess once, each plausible shape is tried and the one that builds is
+    used. A total failure falls back to plain always-visible widgets: losing the
+    auto-hide is a cosmetic loss, losing the node is not.
+    """
+    global DYNAMIC_SAMPLING
+
+    shapes = (
+        ("Option(id, inputs=[...])",
+         lambda: [io.DynamicCombo.Option("off"),
+                  io.DynamicCombo.Option("on", inputs=_sampling_params())]),
+        ("Option(id=..., inputs=[...])",
+         lambda: [io.DynamicCombo.Option(id="off"),
+                  io.DynamicCombo.Option(id="on", inputs=_sampling_params())]),
+        ("Option(id, [...])",
+         lambda: [io.DynamicCombo.Option("off", []),
+                  io.DynamicCombo.Option("on", _sampling_params())]),
+        ("Option(value=..., inputs=[...])",
+         lambda: [io.DynamicCombo.Option(value="off"),
+                  io.DynamicCombo.Option(value="on", inputs=_sampling_params())]),
+    )
+
+    tried = []
+    for label, build in shapes:
+        try:
+            control = io.DynamicCombo.Input(
+                "sampling_mode", options=build(), display_name="sampling",
+                tooltip=SAMPLING_TIP)
+        except Exception as exc:
+            tried.append(f"{label} -> {type(exc).__name__}: {exc}")
+            continue
+        DYNAMIC_SAMPLING = True
+        log.info("[Nugget] sampling parameters will hide when sampling is off "
+                 "(DynamicCombo built with %s)", label)
+        return [control]
+
+    log.warning("[Nugget] could not build a DynamicCombo, so the sampling "
+                "parameters will always be visible. Tried: %s", " | ".join(tried))
+    return [
+        io.Combo.Input("sampling_mode", options=["off", "on"], default="off",
+                       display_name="sampling", tooltip=SAMPLING_TIP),
+    ] + _sampling_params()
+
+
+# Remembered so the letterbox notice is logged once per session rather than on
+# every generation.
+_LIST_MODE: dict = {}
+
+
+def cap(frames, longest: int):
+    """Scale each frame so neither side exceeds ``longest``. Never upscales.
+
+    Each image is handled on its own, so they keep their own aspect ratios and
+    end up at different sizes. That is the point: nothing is cropped and nothing
+    is letterboxed to match a neighbour.
+    """
+    import comfy.utils
+
+    out = []
+    for frame in frames:
+        height, width = int(frame.shape[0]), int(frame.shape[1])
+        ratio = min(longest / max(1, width), longest / max(1, height), 1.0)
+        if ratio >= 1.0:
+            out.append(frame)
+            continue
+        new_w = max(1, int(round(width * ratio)))
+        new_h = max(1, int(round(height * ratio)))
+        nchw = frame.unsqueeze(0).movedim(-1, 1).float()
+        nchw = comfy.utils.common_upscale(nchw, new_w, new_h, "lanczos", "disabled")
+        out.append(nchw.movedim(1, -1).squeeze(0).to(frame.dtype))
+    return out
+
+
+def as_batches(frames):
+    """Frames as a list of single-image tensors, ready for the encoder."""
+    return [f.unsqueeze(0) for f in frames]
+
+
+def uniform(frames) -> bool:
+    sizes = {(int(f.shape[0]), int(f.shape[1])) for f in frames}
+    return len(sizes) <= 1
+
+
+# The order the widgets are declared in, which is the order ComfyUI saves them.
+# A workflow's positional widgets_values is matched against this, so inserting a
+# widget without updating any saved workflow shifts every value after it -- that
+# has now happened twice, so the test suite asserts this list against the schema.
+WIDGET_ORDER = ["img_description_detail", "prompt", "max_image_size",
+                "max_length", "sampling_mode", "temperature",
+                "repetition_penalty", "seed"]
+
+
+class NuggetGeneratePrompt(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="NuggetGeneratePrompt",
+            display_name="Generate prompt (with references)",
+            category="Nugget",
+            search_aliases=["generate text", "prompt", "enhance", "llm",
+                            "reference images"],
+            description=(
+                "Generates text from a prompt and up to 9 reference images, "
+                "using the language model loaded in Load CLIP. Replaces core's "
+                "Generate Text plus an image batching node: images keep their "
+                "own aspect ratios and are never cropped."),
+            inputs=[
+                io.Clip.Input("clip", tooltip="A Gemma or Qwen3-VL text encoder."),
+                io.Combo.Input(
+                    "img_description_detail", options=list(DETAIL.keys()),
+                    default="off", display_name="img description detail",
+                    tooltip="Appends an instruction asking the model to describe "
+                            "the reference images, and raises the token budget to "
+                            "suit. Leave off when the prompt already says what it "
+                            "wants -- an H3 system prompt specifies its own "
+                            "format and this would fight it."),
+                io.String.Input("prompt", multiline=True, default="",
+                                tooltip="The instruction, usually a system "
+                                        "prompt joined with the user's text."),
+                *[io.Image.Input(f"image_{i}", optional=True)
+                  for i in range(1, MAX_INPUTS + 1)],
+                io.Combo.Input(
+                    "max_image_size", options=IMAGE_SIZES, default=1024,
+                    display_name="max image size",
+                    tooltip="Longest side each reference is scaled to. A cap, "
+                            "not a target -- smaller images are left alone. "
+                            "Lower it if generation is slow or memory is tight."),
+                io.Int.Input(
+                    "max_length", default=1024, min=16, max=8192, step=16,
+                    display_name="max length",
+                    tooltip="Token budget for the reply. A full six-section H3 "
+                            "prompt runs about 600-700 tokens, so 1024 leaves "
+                            "headroom. A budget you do not reach costs nothing."),
+            ] + sampling_input() + [
+                io.Int.Input(
+                    "seed", default=0, min=0, max=0xffffffffffffffff,
+                    control_after_generate=True, optional=True,
+                    tooltip="Leave on 'fixed' and re-queueing is free: the "
+                            "node recognises an unchanged prompt, unchanged "
+                            "images and unchanged settings and hands back what "
+                            "it said last time. 'randomize' forces a fresh "
+                            "generation -- but only produces DIFFERENT text "
+                            "when sampling is on. With sampling off it is "
+                            "minutes of work for an identical answer."),
+            ],
+            outputs=[
+                io.String.Output(display_name="generated_text"),
+            ],
+        )
+
+    # The settings that actually change the text. Widget values as they arrive,
+    # before execute() folds img_description_detail into the prompt and the
+    # budget -- that folding is deterministic, so the raw values identify the
+    # request just as exactly and both halves of the caching agree by
+    # construction.
+    @classmethod
+    def _request(cls, clip, images, prompt="", max_image_size=1024,
+                 max_length=1024, sampling_mode="off",
+                 img_description_detail="off", temperature=0.7,
+                 repetition_penalty=1.0, seed=0):
+        settings = {"prompt": prompt or "",
+                    "max_image_size": int(max_image_size),
+                    "max_length": int(max_length),
+                    "sampling_mode": sampling_mode,
+                    "img_description_detail": img_description_detail,
+                    "seed": int(seed)}
+        # Temperature and repetition penalty only reach the model when sampling
+        # is on. Keying on them regardless would make nudging a hidden widget
+        # throw away a perfectly good answer.
+        if sampling_mode == "on":
+            settings["temperature"] = round(float(temperature), 4)
+            settings["repetition_penalty"] = round(float(repetition_penalty), 4)
+        return fingerprint.key(clip, settings, images, MAX_INPUTS)
+
+    @classmethod
+    def validate_inputs(cls, input_types=None, **kwargs):
+        """Skip ComfyUI's link type check, so a bypassed image source is survivable.
+
+        Bypassing a node makes it pass through whatever is on its own inputs.
+        Load Image has no IMAGE input to pass through, so what arrives on an
+        image socket is not an IMAGE, and ComfyUI rejects the whole prompt with
+        "Return type mismatch between linked nodes" during validation -- before
+        this node, or any node, executes.
+
+        Accepting an ``input_types`` parameter is what turns that check off. It
+        is the signature that matters, not the parameter names: naming an input
+        here would only skip validation of its widget value. Whatever arrives is
+        checked in ``collect``, which ignores anything without a shape.
+        """
+        return True
+
+    VALIDATE_INPUTS = validate_inputs
+
+    @classmethod
+    def fingerprint_inputs(cls, clip=None, **kwargs):
+        """Has this request changed? -- answered from content, not from the graph.
+
+        ComfyUI's default answer is the node's input signature including every
+        ancestor's, which is a question about the shape of the graph rather than
+        about what arrived here. Bypassing an upstream node, or connecting a
+        socket, rewires what the frontend sends and changes that signature even
+        though the text and the pixels reaching this node are identical -- so
+        the node regenerated. Fingerprinting the content instead makes a
+        re-queue free whenever the request really is the same one.
+
+        Returned as a hex string because ComfyUI writes this value into the
+        workflow it embeds in saved images and serialises it as JSON.
+        """
+        images = {k: v for k, v in kwargs.items() if k.startswith("image_")}
+        widgets = {k: v for k, v in kwargs.items() if not k.startswith("image_")}
+        try:
+            return cls._request(clip, images, **widgets)
+        except Exception as exc:
+            # Being wrong here must never break a queue, and "assume it
+            # changed" is the safe direction: it costs a regeneration.
+            log.debug("[Nugget] could not fingerprint the request (%s)", exc)
+            return os.urandom(8).hex()
+
+    # ComfyUI reads the uppercase name on some builds and the lowercase one on
+    # others, and there are releases where the V3 hook is not called at all.
+    # Bound both ways, and execute() does not rely on either being honoured.
+    IS_CHANGED = fingerprint_inputs
+
+    @classmethod
+    def execute(cls, clip, prompt="", max_image_size=1024, max_length=1024,
+                sampling_mode="off", img_description_detail="off", temperature=0.7,
+                repetition_penalty=1.0, seed=0, **images) -> io.NodeOutput:
+        llm.check(clip)
+
+        # A DynamicCombo delivers its nested values under prefixed keys on some
+        # frontends, so fall back to a suffix match rather than silently using
+        # the defaults.
+        def nested(name, value, fallback):
+            if value != fallback:
+                return value
+            for key, found in images.items():
+                if key.endswith(name) and isinstance(found, (int, float)):
+                    return found
+            return value
+
+        temperature = nested("temperature", temperature, 0.7)
+        repetition_penalty = nested("repetition_penalty", repetition_penalty, 1.0)
+        # Anything without a shape is not an image -- a bypassed loader passing
+        # its widget value through, most often. Dropped here so it can never
+        # reach collect() and be read as a tensor.
+        images = {k: v for k, v in images.items()
+                  if k.startswith("image_") and fingerprint.is_image(v)}
+        # Second line of defence. fingerprint_inputs above should mean ComfyUI
+        # skips this node entirely on an unchanged request, but it is not
+        # honoured on every build, and a purged cache entry re-runs the node
+        # regardless. Either way the answer is already known, so hand it back
+        # rather than spending minutes reproducing it.
+        cache_key = ""
+        try:
+            cache_key = cls._request(
+                clip, images, prompt=prompt, max_image_size=max_image_size,
+                max_length=max_length, sampling_mode=sampling_mode,
+                img_description_detail=img_description_detail,
+                temperature=temperature, repetition_penalty=repetition_penalty,
+                seed=seed)
+        except Exception as exc:
+            log.debug("[Nugget] could not fingerprint the request (%s)", exc)
+        remembered = fingerprint.get(cache_key)
+        # An empty answer is not worth keeping or returning -- it would pass a
+        # failed generation off as a finished one.
+        if remembered:
+            log.info("[Nugget] same prompt, same images, same settings -- "
+                     "reusing the previous text instead of generating again")
+            return io.NodeOutput(remembered)
+
+        # Collect frames FIRST so we know the real reference count before
+        # assembling the prompt. A composite / character-sheet reference is one
+        # tensor to the encoder; if the prompt does not say so, the model
+        # counts by what it can see and calls a 4-panel sheet four pictures,
+        # a 2x2 grid two, and so on. The count of *sockets* connected is what
+        # the downstream <picture N> placeholders are meant to match.
+        frames = []
+        try:
+            frames = nodes_image.collect(images)
+        except ValueError:
+            # No references is legitimate -- this is still a text generator.
+            pass
+
+        suffix, detail_budget = DETAIL.get(img_description_detail, DETAIL["off"])
+        if suffix and frames:
+            n = len(frames)
+            if n == 1:
+                grounding = (
+                    "\n\nThere is exactly ONE reference image. Refer to it as "
+                    "<picture 1>. If it contains multiple panels, poses, views "
+                    "or crops of the same subject, describe them together as "
+                    "parts of that one picture -- do NOT split them into "
+                    "separate pictures.")
+            else:
+                grounding = (
+                    f"\n\nThere are exactly {n} reference images, in order. "
+                    f"Label them <picture 1> through <picture {n}>. If any "
+                    "single image contains multiple panels, poses, views or "
+                    "crops of one subject, keep those together under that "
+                    "image's label -- do NOT split one image's panels into "
+                    "separate pictures.")
+            suffix = grounding + suffix
+        prompt = (prompt or "") + suffix
+        if detail_budget:
+            max_length = max(int(max_length), detail_budget)
+
+        payload = None
+        if frames:
+            frames = cap(frames, int(max_image_size))
+            payload = as_batches(frames)
+
+        text = llm.ask(
+            clip, prompt, payload, int(max_length), int(seed),
+            temperature=float(temperature),
+            repetition_penalty=float(repetition_penalty),
+            # The widget is the single source of truth. Passing a temperature of
+            # zero to mean "off" is what made the control appear to do nothing.
+            sample=(sampling_mode == "on"),
+            note=_LIST_MODE)
+
+        if llm.looks_truncated(text, int(max_length)):
+            log.warning("[Nugget] the reply ran out of tokens at %d and stopped "
+                        "mid-sentence -- raise max length", int(max_length))
+        if text and text.strip():
+            fingerprint.put(cache_key, text)
+        return io.NodeOutput(text)
+
+
+NODES = [NuggetGeneratePrompt]

custom_nodes/ComfyUI-Nugget/nodes_transcribe.py

@@ -0,0 +1,642 @@
+"""The node.
+
+Everything that has one correct value for a description task -- temperature,
+top_k, top_p, min_p, both penalties, thinking mode, the chat template -- is
+fixed in ``llm.py`` rather than put on the face of the node. The widgets that
+do show are the ones the user should reach for. A ``show`` widget hides the
+less-used ones (via web/js/nugget_transcribe_ui.js) so the compact face is
+short.
+
+The order of work is deliberate and is the one thing not to rearrange:
+
+    read the video  ->  transcribe  ->  release the speech model  ->  touch the clip
+
+The clip is not touched until the last step, because that is what triggers
+ComfyUI to move the text encoder onto the GPU. Transcribing first means the two
+models are never resident together.
+
+Frames are decoded once. Every timestamp the run will need -- context frames and
+every shot's frames -- is collected up front and pulled in a single sequential
+pass. Fetching per shot instead means re-decoding the whole file once per shot,
+which on a twenty-shot clip is twenty redundant passes.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+
+from comfy_api.latest import io
+
+from . import (camera, detect, llm, motion_prompts, prompts, recall,
+               speech as speech_mod, video as video_mod)
+
+log = logging.getLogger("Nugget")
+
+# Past this the vision passes take long enough that people assume it has hung,
+# and the frames stop fitting comfortably in context. Refuse clearly instead.
+MAX_SECONDS = 120.0
+
+WHISPER_MODELS = ["large-v3", "large-v3-turbo", "medium", "small", "base",
+                  "tiny", "off"]
+
+FRAME_SIZES = [384, 512, 768, 1024]
+
+# Shown as names, passed to Whisper as codes. "auto" is almost always right --
+# the picker exists for clips where detection keeps guessing wrong.
+LANGUAGE_CHOICES = [
+    "auto", "English", "Spanish", "French", "German", "Italian", "Portuguese",
+    "Dutch", "Polish", "Russian", "Japanese", "Korean", "Chinese", "Cantonese",
+    "Arabic", "Hindi", "Turkish", "Vietnamese", "Thai", "Indonesian",
+    "Ukrainian", "Swedish", "Norwegian", "Danish", "Finnish", "Greek", "Czech",
+    "Romanian", "Hungarian", "Hebrew", "Malay", "Filipino",
+]
+
+
+def _interrupted() -> None:
+    """Let Cancel actually cancel.
+
+    Without this a queued run keeps going through every remaining shot after the
+    user has pressed stop, because nothing between model calls ever checks.
+    """
+    try:
+        from comfy import model_management
+        model_management.throw_exception_if_processing_interrupted()
+    except ImportError:
+        pass
+
+
+class _Progress:
+    """The node's progress bar, plus a log line. Degrades to logging alone."""
+
+    def __init__(self, total: int):
+        self.bar = None
+        try:
+            from comfy.utils import ProgressBar
+            self.bar = ProgressBar(total)
+        except Exception:
+            pass
+
+    def step(self, message: str) -> None:
+        log.info("[Nugget] %s", message)
+        if self.bar is not None:
+            try:
+                self.bar.update(1)
+            except Exception:
+                pass
+
+
+class VideoAutoTranscribe(io.ComfyNode):
+    @classmethod
+    def define_schema(cls):
+        return io.Schema(
+            node_id="VideoAutoTranscribe",
+            display_name="Video Auto Transcriber",
+            category="Nugget",
+            search_aliases=["caption", "transcribe", "describe video", "scene", "shots"],
+            description=("Describe a short video shot by shot, with real cut "
+                         "timestamps and transcribed dialogue folded in."),
+            inputs=[
+                io.Clip.Input("clip", tooltip="A Gemma text encoder, from Load CLIP."),
+                io.Video.Input(
+                    "video", optional=True,
+                    tooltip="The clip to caption. Under 2 minutes. Bypass the "
+                            "Load Video node to switch this node off -- it "
+                            "returns empty outputs instead of failing."),
+                # Mode picks which prompt pack drives the vision passes.
+                # General is the original transcribe behaviour; Movements
+                # (test) runs the same shot-by-shot pipeline through the
+                # motion-transfer prompts, so a single node can do either
+                # job without wiring in a second Load Video branch.
+                io.Combo.Input(
+                    "mode", options=["General", "Movements (test)"],
+                    default="General", display_name="mode",
+                    tooltip="General describes each shot in prose with "
+                            "dialogue folded in -- the original behaviour. "
+                            "Movements (test) writes timestamped body-motion "
+                            "callouts instead, for feeding into a "
+                            "reference-to-video prompt (behaves like the "
+                            "Nugget Motion Transfer node)."),
+                io.Int.Input(
+                    "prompt_max_length", default=0, min=0, max=4096, step=32,
+                    display_name="prompt max length",
+                    tooltip="Token budget for each shot description. 0 follows "
+                            "description detail (General: 160 / 300 / 500, "
+                            "Movements: 220 / 380 / 700) and is the default. "
+                            "Raise it if descriptions are stopping "
+                            "mid-sentence; the log warns when that happens."),
+                io.Combo.Input(
+                    "description_detail", options=list(prompts.DETAIL.keys()),
+                    default="normal", display_name="description detail",
+                    tooltip="How much is written per shot, and how many frames the "
+                            "model sees. Frame count scales with shot length, and "
+                            "long shots are split into beats. Higher is slower."),
+                # Parameter name kept as ``scene_sensitivity`` so old
+                # workflows loading against the schema still find the input
+                # by name -- only the display name and tooltip change here.
+                io.Combo.Input(
+                    "scene_sensitivity", options=["low", "normal", "high"],
+                    default="normal", display_name="scene detect",
+                    tooltip="How aggressively the detector calls a cut. Each "
+                            "frame boundary is scored for how much the image "
+                            "changed; the setting decides how big that jump "
+                            "has to be before it counts.\n\n"
+                            "low -- conservative. Only large, obvious jumps "
+                            "become cuts. Use this when the detector is "
+                            "splitting one shot into two on a whip pan, a "
+                            "flashbulb, or fast motion. Result: fewer, "
+                            "longer shots.\n"
+                            "normal -- balanced. Matches most editorial "
+                            "cuts. The default.\n"
+                            "high -- eager. Small jumps also become cuts, so "
+                            "match cuts, cross-dissolves and quiet scene "
+                            "changes register. Use this when shots are being "
+                            "missed. Result: more, shorter shots.\n\n"
+                            "Pair with 'min shot' to drop cuts closer "
+                            "together than a chosen minimum, so a high "
+                            "setting does not fragment the timeline."),
+                io.Float.Input(
+                    "min_shot", default=0.5, min=0.2, max=30.0, step=0.1,
+                    display_name="min shot",
+                    tooltip="Shortest shot allowed, in seconds. Two cuts closer "
+                            "together than this become one, so a high value "
+                            "discards cuts."),
+                io.Combo.Input(
+                    "frame_layout", options=["grid", "separate"], default="grid",
+                    optional=True, advanced=True, display_name="frame layout",
+                    tooltip="grid composites each beat's frames into one image, "
+                            "which is much cheaper and shows motion at a glance. "
+                            "separate sends them as individual images -- more "
+                            "spatial detail per frame, several times slower."),
+                io.Combo.Input(
+                    "whisper_model", options=WHISPER_MODELS, default="large-v3",
+                    display_name="whisper model",
+                    tooltip="Speech model. large-v3 is the most accurate; the "
+                            "smaller ones are faster and need less memory. "
+                            "'off' skips audio entirely -- useful for clips "
+                            "with no dialogue, and for telling whether a "
+                            "problem is in the speech half or the vision "
+                            "half."),
+                io.Combo.Input(
+                    "audio_language", options=LANGUAGE_CHOICES, default="auto",
+                    display_name="audio language",
+                    tooltip="Spoken language. Leave on auto to detect it."),
+                # Placed here, next to seed and marked advanced, so that when
+                # compact view hides it (see web/js/nugget_transcribe_ui.js)
+                # it sits next to another hidden widget (frame_layout) rather
+                # than sandwiching whisper_model / audio_language between two
+                # hidden widgets -- that sandwich confuses the frontend's
+                # widget renderer and the two combos come back as broken
+                # socket rows with no dropdown arrows.
+                io.Combo.Input(
+                    "max_frame_size", options=FRAME_SIZES, default=768,
+                    optional=True, advanced=True,
+                    display_name="max frame size",
+                    tooltip="Maximum width frames are scaled to before the model "
+                            "sees them. This is a ceiling, not a target -- a "
+                            "smaller source is never upscaled. Drop to 512 for "
+                            "speed, raise to 1024 if fine detail or on-screen "
+                            "text is being missed."),
+                # Deliberately no control_after_generate here. ComfyUI caches a
+                # node whose inputs have not changed, so a self-randomising seed
+                # is a cache miss on every queue -- and this node always
+                # generates greedily, so the re-run would produce byte-identical
+                # output. Minutes of work for nothing. To force a fresh
+                # transcription, change a setting or the video.
+                io.Int.Input(
+                    "seed", default=0, min=0, max=0xffffffffffffffff,
+                    optional=True, advanced=True,
+                    tooltip="Only used if temperature is raised in llm.py. Output "
+                            "is greedy and repeatable, so this is fixed on "
+                            "purpose -- a randomised seed would re-transcribe "
+                            "the whole video for an identical result."),
+                # Placed at the very bottom of the widget list on purpose --
+                # it controls what the rest of the widgets look like, so once
+                # a workflow is set up it is the least-touched setting. Kept
+                # in the Python schema so the widget value is saved with the
+                # workflow and restored on load; the hiding itself happens
+                # in web/js/nugget_transcribe_ui.js.
+                #
+                # Marked advanced so ComfyUI sorts it to the end of the
+                # widget column alongside 'seed'. The frontend auto-inserts
+                # a 'control after generate' widget straight after 'seed';
+                # having 'show' also advanced and later in the schema puts
+                # it below that auto-widget, which is where the user asked
+                # for it. Optional matches the seed row's decoration.
+                io.Combo.Input(
+                    "show", options=["compact", "everything"],
+                    default="compact", display_name="show",
+                    optional=True, advanced=True,
+                    tooltip="compact hides the mode / max frame size / frame "
+                            "layout widgets, and the overview / characters / "
+                            "shots / audio transcription / audio language "
+                            "outputs. Switch to everything to see them all. "
+                            "An output that is already wired up stays "
+                            "visible even in compact -- if you connected it, "
+                            "you probably still want it."),
+            ],
+            outputs=[
+                io.Image.Output(display_name="video_images"),
+                io.Audio.Output(display_name="video audio"),
+                io.Float.Output(display_name="fps"),
+                io.Int.Output(display_name="frame_count"),
+                io.String.Output(display_name="full description"),
+                io.String.Output(display_name="overview"),
+                io.String.Output(display_name="characters identified"),
+                io.String.Output(display_name="shots"),
+                io.String.Output(display_name="audio transcription"),
+                io.String.Output(display_name="audio language"),
+            ],
+        )
+
+    @classmethod
+    def validate_inputs(cls, input_types=None, **kwargs):
+        """Skip ComfyUI's link type check, so bypass does not fail the graph.
+
+        Accepting an ``input_types`` parameter is what turns the check off --
+        that is the documented switch, and it is the whole signature that
+        matters, not the parameter names. Naming an input here only skips
+        validation of its *widget* value, which is not what fails.
+
+        It has to be off because bypassing a node makes it pass through a
+        reference to whatever is on its own inputs. Load Video has no VIDEO
+        input to pass through, so what reaches this socket is not a VIDEO --
+        and ComfyUI rejects the whole prompt with "Return type mismatch
+        between linked nodes" during validation, before any node executes.
+        Nothing inside ``execute`` ever gets the chance to run. Whatever
+        arrives is checked there instead.
+
+        Bypassing a node makes it pass through a reference to whatever is on its
+        inputs. Load Video has no VIDEO input to pass through, so what reaches
+        this socket is not a VIDEO -- and ComfyUI rejects the whole prompt with
+        "Return type mismatch between linked nodes" during validation, before
+        any node executes. The skip in ``execute`` never gets the chance to run.
+
+        Naming a parameter after an input tells ComfyUI not to validate that
+        input, which lets the prompt through so ``execute`` can decide for
+        itself. Whatever arrives is checked there instead.
+        """
+        return True
+
+    # ComfyUI reads the uppercase name. Bound here as well as declared
+    # above so the signature survives however the V3 wrapper exposes it.
+    VALIDATE_INPUTS = validate_inputs
+
+    @classmethod
+    def _switched_off(cls, reason: str = "") -> io.NodeOutput:
+        """The outputs for a run that is deliberately doing nothing.
+
+        An 8-frame 64x64 black tensor rather than None or a single pixel: an
+        IMAGE output that is None breaks anything downstream that expects a
+        tensor, and the point of a skipped run is that nothing downstream falls
+        over. A 1x1x1 placeholder is technically a tensor but many video nodes
+        reject it -- MiniMax H3, for instance, needs at least 5 frames and
+        raises ValueError on anything shorter. 8 frames clears that bar with
+        headroom for other minimums, and 64x64 avoids nodes that reject
+        sub-patch-size dimensions. The audio is a second of silence for the
+        same reason.
+
+        The strings are a single space rather than empty: some downstream text
+        nodes (Preview Text and its cousins) raise on an empty STRING input
+        instead of showing an empty box, which would take the whole graph down
+        exactly when the user has switched a branch off. A single space passes
+        every truthiness check downstream, joins into a prompt as nothing
+        meaningful, and reads as "empty" to anything that strips whitespace.
+        """
+        import torch
+        if reason:
+            log.info("[Nugget] %s -- skipping, all outputs are empty", reason)
+        blank = " "
+        return io.NodeOutput(torch.zeros((8, 64, 64, 3)),
+                             video_mod.silence(), 0.0, 0,
+                             blank, blank, blank, blank, blank, blank)
+
+    @classmethod
+    def execute(cls, clip, video=None, show="compact", mode="General",
+                prompt_max_length=0, description_detail="normal",
+                scene_sensitivity="normal", min_shot=0.5, max_frame_size=768,
+                frame_layout="grid", whisper_model="large-v3",
+                audio_language="auto", seed=0) -> io.NodeOutput:
+
+        # ``show`` is a UI-only setting -- the JS extension hides widgets and
+        # output sockets based on it, but nothing about the work itself
+        # changes, so it never appears again after this line. Accepted here
+        # only because ComfyUI passes every widget value into execute.
+        del show
+
+        detail, sensitivity = description_detail, scene_sensitivity
+        # The widget shows names; Whisper wants codes.
+        language = speech_mod.language_code(audio_language)
+        frame_size = max_frame_size
+        # Which prompt pack drives the vision passes. Both modules expose the
+        # same DETAIL keys, the same clock/sections/assemble/transcript_text
+        # signatures, and a token_budget that returns a dict -- so the only
+        # place execute needs a mode branch is the per-shot prompt itself,
+        # further down. The cache key includes ``mode`` too, so a General run
+        # and a Movements run on the same clip do not read each other's
+        # cached text back.
+        active_prompts = (motion_prompts if mode == "Movements (test)"
+                          else prompts)
+        movements = mode == "Movements (test)"
+
+        started = time.time()
+
+        # A bypassed Load Video node hands us None. That is someone switching
+        # this branch off, not a broken graph, so do nothing quietly and return
+        # empty strings -- they join onto a downstream prompt without leaving a
+        # stray "no video" line in it.
+        if video_mod.missing(video):
+            log.info("[Nugget] no usable video on the input "
+                     "(unconnected, or the Load Video node is bypassed) -- "
+                     "skipping, all outputs are empty")
+            # A small black tensor rather than None: an IMAGE output that is
+            # None breaks anything downstream that expects a tensor, and the
+            # point of a skipped run is that nothing downstream falls over. The
+            # shape (8 frames, 64x64) clears the frame-count and dimension
+            # minimums imposed by common video nodes -- see _switched_off. The
+            # audio is a full second of silence for the same reason -- an
+            # encoder given a one-sample waveform raises rather than producing
+            # nothing.
+            return cls._switched_off()
+
+        llm.check(clip)          # fail on a bad graph before doing any slow work
+        try:
+            handle = video_mod.open_clip(video)
+        except video_mod.NoSource as exc:
+            # Something arrived on the socket, but it cannot name a file --
+            # a bypassed loader passing its widget value through, most often.
+            # That is the branch being switched off, not a broken graph.
+            return cls._switched_off(f"nothing usable on the video input ({exc})")
+        wav = None
+
+        try:
+            if handle.duration > MAX_SECONDS:
+                raise video_mod.VideoError(
+                    f"That clip is {handle.duration:.0f}s. This node is built for "
+                    f"clips under {MAX_SECONDS:.0f}s -- trim it, or split it and "
+                    f"caption the parts separately.")
+            if handle.variable_fps:
+                log.warning("[Nugget] variable frame rate: tagged %.2f fps "
+                            "but the real average is %.2f. Times here come from each "
+                            "frame's own timestamp, so they are correct.",
+                            handle.declared_fps, handle.fps)
+
+            # A min_shot longer than the clip would suppress every cut and
+            # silently return one shot, which looks like broken detection.
+            floor = float(min_shot)
+            if floor > handle.duration / 2:
+                floor = max(0.2, handle.duration / 4)
+                log.warning("[Nugget] min_shot %.1fs is too long for a "
+                            "%.1fs clip; using %.2fs", min_shot, handle.duration, floor)
+
+            log.info("[Nugget] %dx%d, %.2fs",
+                     handle.width, handle.height, handle.duration)
+            # Has this exact video already been described with exactly these
+            # settings? The seed is in the key like everything else, so leaving
+            # it fixed is what makes a re-queue free; changing it, or the file,
+            # or any setting, is a miss and the work happens again. The frames
+            # are still decoded -- that is a second, and they are too large to
+            # be worth remembering -- but the minutes of transcription and
+            # vision passes are not repeated.
+            settings = {"prompt_max_length": prompt_max_length,
+                        "detail": detail,
+                        "sensitivity": sensitivity,
+                        "min_shot": round(float(floor), 3),
+                        "frame_size": int(frame_size),
+                        "frame_layout": frame_layout,
+                        "whisper": whisper_model,
+                        "language": language or "auto",
+                        "seed": seed,
+                        # Namespace by mode: the two prompt packs produce
+                        # differently-shaped text, and a cached General run
+                        # served as a Movements answer (or vice versa) would
+                        # look like a bug in the mode switch.
+                        "mode": mode}
+            cache_key = recall.key(handle.path, clip, settings, handle.temporary)
+            remembered = recall.get(cache_key)
+            # Only trust an entry that actually holds a description. An empty
+            # one would silently pass a skipped run off as a finished one.
+            if remembered and remembered[0].strip():
+                log.info("[Nugget] already described this video with these "
+                         "settings -- reusing the text, decoding the frames "
+                         "again")
+                # If the clip is too big for decode_all's RAM guard, the cached
+                # text is still valid -- return it with placeholder frames
+                # rather than throwing away the cache hit as well.
+                try:
+                    all_frames, real_fps, frame_count = video_mod.decode_all(handle)
+                    audio_cached = video_mod.audio_tensor(handle)
+                except video_mod.VideoError as exc:
+                    import torch
+                    log.warning("[Nugget] using cached description, but frames "
+                                "could not be decoded (%s) -- images output is "
+                                "an 8-frame 64x64 placeholder", exc)
+                    all_frames = torch.zeros((8, 64, 64, 3))
+                    audio_cached = video_mod.silence()
+                    real_fps, frame_count = 0.0, 0
+                return io.NodeOutput(all_frames, audio_cached,
+                                     real_fps, frame_count, *remembered)
+
+            # Full frames and the soundtrack, so this node can stand in for a
+            # Get Video Components plus a frame count.
+            all_frames, real_fps, frame_count = video_mod.decode_all(handle)
+            audio_out = video_mod.audio_tensor(handle)
+            log.info("[Nugget] %d frames at %.2f fps", frame_count, real_fps)
+
+            # --- cuts ------------------------------------------------------
+            scores, motion = video_mod.scan(handle)
+            _interrupted()
+            cuts = detect.find_cuts(scores, sensitivity, floor, 0.0, handle.duration)
+            shots = detect.build_shots(cuts, 0.0, handle.duration)
+            log.info("[Nugget] %d shot(s), cuts at %s",
+                     len(shots), [round(c, 3) for c in cuts])
+
+            # --- speech, before the encoder is ever touched ----------------
+            total_beats = sum(len(active_prompts.beats_for(shot, detail))
+                              for shot in shots)
+            progress = _Progress(total_beats + 3)
+            if whisper_model == "off":
+                progress.step("skipping audio")
+                speech = speech_mod.Speech(note="transcription turned off")
+            else:
+                progress.step(f"transcribing with {whisper_model}")
+                wav = video_mod.extract_audio(handle)
+                speech = speech_mod.transcribe(wav, whisper_model, language)
+            video_mod.cleanup(wav)
+            wav = None
+            _interrupted()
+
+            # --- plan every frame the run needs, then decode once ----------
+            progress.step("decoding frames")
+            context = active_prompts.context_times(shots)
+
+            plan = []          # (shot, beat_start, beat_end, [times])
+            for shot in shots:
+                beats = active_prompts.beats_for(shot, detail)
+                for start, end in beats:
+                    count = active_prompts.frames_for(end - start, detail)
+                    plan.append((shot, start, end,
+                                 active_prompts.sample_times(start, end, count)))
+
+            wanted = list(context)
+            for _, _, _, times in plan:
+                wanted.extend(times)
+            decoded = {round(t, 3): image for t, image
+                       in video_mod.frames_at(handle, wanted, width=int(frame_size))}
+
+            def frames(times):
+                return [decoded[key] for key in (round(t, 3) for t in times)
+                        if key in decoded]
+
+            def payload(images):
+                if frame_layout == "grid":
+                    return video_mod.to_grid(images, int(frame_size)), len(images)
+                return images, len(images)
+
+            # --- vision. this is where the encoder loads -------------------
+            # Report headroom before the encoder loads. A crash with no Python
+            # traceback is almost always VRAM, and the number here is what tells
+            # you whether the model had room -- a 12 GB encoder on a 16 GB card
+            # leaves under 4 GB for the vision tower, activations and KV cache.
+            try:
+                from comfy import model_management
+                free = model_management.get_free_memory(
+                    model_management.get_torch_device())
+                log.info("[Nugget] %.1f GB free before loading the "
+                         "text encoder", free / (1024 ** 3))
+                if free < 5 * (1024 ** 3):
+                    log.warning("[Nugget] under 5 GB free -- if "
+                                "ComfyUI exits without an error, the encoder is "
+                                "too large for this card. Try a smaller one.")
+            except Exception:
+                pass
+
+            budget = active_prompts.token_budget(detail, prompt_max_length)
+            # The two modules name the middle-pass budget differently --
+            # ``characters`` in the general pack, ``subject`` in the motion
+            # pack -- because the underlying pass asks for a different thing.
+            # Fall back either way so a future rename of one does not silently
+            # break the other.
+            middle_budget = budget.get("characters",
+                                       budget.get("subject", 200))
+
+            wide, _ = payload(frames(context))
+            progress.step("overall look and characters"
+                          if not movements
+                          else "overall motion and subject")
+            overview = llm.ask(clip, active_prompts.OVERVIEW, wide,
+                               budget["overview"], seed)
+            _interrupted()
+            subjects = active_prompts.clean_subjects(
+                llm.ask(clip, active_prompts.SUBJECTS, wide,
+                        middle_budget, seed))
+
+            tokens = budget["shot"]
+            # The motion pack composes its per-shot prompt from a header +
+            # style body + footer, and needs the timestamp list built once
+            # per detail level. The general pack just uses its SHOT literal.
+            movements_shot_template = (active_prompts.shot_prompt(detail)
+                                       if movements else None)
+            grouped: dict = {}
+            for position, (shot, start, end, times) in enumerate(plan):
+                _interrupted()
+                progress.step(
+                    f"shot {shot.index} of {len(shots)}"
+                    + (f", beat at {active_prompts.clock(start)}"
+                       if len(active_prompts.beats_for(shot, detail)) > 1
+                       else ""))
+                images, count = payload(frames(times))
+                first = shot.index not in grouped
+
+                if frame_layout == "grid" and count > 1:
+                    layout = active_prompts.GRID_NOTE.format(count=count)
+                else:
+                    layout = (f"These {count} frames are from ONE continuous "
+                              f"shot, in order.")
+                call_started = time.time()
+                movement = camera.summarise(motion, start, end)
+                if movements:
+                    # Motion-transfer prompts need the sampled timestamps
+                    # spelled out under the frame grid, plus a target
+                    # callout count -- see motion_prompts.shot_prompt for
+                    # the placeholders it expects.
+                    ts_line = active_prompts.timestamp_list(times)
+                    aim = active_prompts.aim_callouts(times, detail)
+                    prompt = movements_shot_template.format(
+                        layout=layout, span=end - start,
+                        start_clock=active_prompts.clock(start),
+                        end_clock=active_prompts.clock(end),
+                        timestamp_list=ts_line,
+                        aim=aim,
+                        subjects=active_prompts.SUBJECTS_KNOWN.format(
+                            subjects=subjects) if subjects else "",
+                        camera=active_prompts.CAMERA_FACT.format(motion=movement)
+                        if movement else "")
+                else:
+                    prompt = active_prompts.SHOT.format(
+                        layout=layout, span=end - start,
+                        sentences=active_prompts.sentences_for(detail),
+                        # The subject list is passed into every shot; that is
+                        # the whole reason it is worth generating.
+                        subjects=active_prompts.SUBJECTS_KNOWN.format(
+                            subjects=subjects) if subjects else "",
+                        camera=active_prompts.CAMERA_FACT.format(motion=movement)
+                        if movement else "")
+                if not first:
+                    prompt += active_prompts.CONTINUES
+
+                try:
+                    text = llm.ask(clip, prompt, images, tokens, seed)
+                except llm.LLMError as exc:
+                    # One bad beat should not throw away the rest of the run.
+                    log.warning("[Nugget] shot %d beat %d failed: %s",
+                                shot.index, position, exc)
+                    text = f"(this part could not be described: {exc})"
+                # Per-call timing, because "the node is slow" is almost always
+                # one setting rather than the whole pipeline, and the split
+                # between passes is what tells you which.
+                log.info("[Nugget] shot %d beat %s took %.1fs "
+                         "(%d frames, %d token budget)", shot.index,
+                         active_prompts.clock(start),
+                         time.time() - call_started, count, tokens)
+                if llm.looks_truncated(text, tokens):
+                    log.warning("[Nugget] shot %d ran out of tokens "
+                                "at %d and stopped mid-sentence -- raise "
+                                "prompt_max_length", shot.index, tokens)
+                fallback = ("(no callouts returned)" if movements
+                            else "(no description returned)")
+                grouped.setdefault(shot.index, []).append(
+                    (start, end, text or fallback))
+
+            described = [(shot, grouped.get(shot.index, [(shot.start, shot.end,
+                                                          "(not described)")]))
+                         for shot in shots]
+
+            part = active_prompts.sections(overview, subjects, described, speech)
+            elapsed = time.time() - started
+            log.info("[Nugget] done in %.1fs across %d model call(s), "
+                     "%d token budget per shot", elapsed, len(plan) + 2, tokens)
+            if elapsed > 120 and prompt_max_length > 400:
+                log.warning("[Nugget] that run took %.0fs with "
+                            "prompt_max_length at %d. A busy scene generates up "
+                            "to that budget on every beat; 0 (automatic) is much "
+                            "faster and the log says when it is not enough.",
+                            elapsed, prompt_max_length)
+
+            written = (active_prompts.assemble(overview, subjects,
+                                               described, speech),
+                       part["overview"],
+                       part["subjects"],
+                       part["shots"],
+                       active_prompts.transcript_text(speech),
+                       speech.language_full or "none")
+            recall.put(cache_key, written)
+            return io.NodeOutput(all_frames, audio_out, real_fps, frame_count,
+                                 *written)
+        finally:
+            video_mod.cleanup(wav)
+            if handle.temporary:
+                video_mod.cleanup(handle.path)
+
+
+NODES = [VideoAutoTranscribe]

custom_nodes/ComfyUI-Nugget/prompts.py

@@ -0,0 +1,361 @@
+"""The prompts, the frame budget, and how the pieces get assembled.
+
+Written short on purpose. A long instruction block does not make a 12B model more
+careful -- it gives it more to drift from. Each pass asks for one thing.
+"""
+
+from __future__ import annotations
+
+# Frames per second of shot, and the range that count is clamped to, by detail
+# level. Scaling with duration matters in both directions: a fixed count gives a
+# half-second shot five near-identical frames, and gives a thirty-second shot
+# five frames six seconds apart, which is back to guessing.
+DETAIL = {
+    "brief":    {"per_second": 0.8, "min": 2, "max": 6,  "tokens": 160, "beat": 12.0},
+    "normal":   {"per_second": 1.6, "min": 3, "max": 9,  "tokens": 300, "beat": 6.0},
+    "detailed": {"per_second": 2.5, "min": 5, "max": 12, "tokens": 500, "beat": 4.0},
+}
+
+# A shot longer than its detail level's ``beat`` is described in pieces rather
+# than in one go. A single call covering twenty seconds gets the same handful of
+# frames and the same two or three sentences that a four-second shot gets, so
+# everything between the samples is lost -- exactly the failure this pack exists
+# to avoid, just one level down. Splitting long shots into beats is the
+# partition-and-summarise approach used by LVD-2M (arXiv 2410.10816), which
+# chunks long video, captions each chunk from a frame grid, then merges.
+
+# Frames used by the overview and cast passes. Sampled per shot rather than
+# evenly across the clip, so a short shot is still represented -- an even spread
+# can miss a one-second shot entirely, and then nobody in it reaches the cast.
+CONTEXT_FRAMES = 8
+
+GRID_NOTE = ("The image is a grid of {count} video frames in time order, read "
+             "left to right then top to bottom, like a comic strip. They are "
+             "frames of one continuous shot, not separate pictures.")
+
+OVERVIEW = """These frames are spread across one short video.
+
+In ONE sentence, describe the overall look: lighting, colour grade, image quality, and pace.
+
+Do not describe any individual moment. Do not list what happens. One sentence, nothing else."""
+
+CONTINUES = ("\n\nThis continues the same shot, already in progress. Describe what "
+             "CHANGES across these frames. Do not restate appearance or setting that "
+             "has not changed.")
+
+SHOT = """{layout} They span {span:.1f} seconds.
+
+Describe what this shot shows, in {sentences}. Cover:
+- who or what is on screen, and how they look (clothing, hair, colours)
+- what they do, and how they move
+- the setting and the lighting
+- the framing and the camera movement
+{subjects}{camera}
+The frames are one shot, not several. Anything that changes between them is movement, not a cut.
+
+Describe only what is visible in THESE frames. If a person is too small or too far away to make out, say so rather than filling in details from elsewhere.
+
+Write only the description. No preamble, no bullet points, no timestamps, no shot number."""
+
+# The old version of this asked for "Man A / Woman A" labels, which came from a
+# pipeline where a downstream writer mapped placeholders onto reference images.
+# On its own that is worse than useless: it forces every video to be about people
+# when it may be about a dog, a car or a landscape, and a label carries no more
+# information than the description beside it.
+#
+# What a subject list is actually for is consistency -- so shot 4 can say "the
+# man" and mean the same man as shot 2. That only works if the list reaches the
+# shot passes, which is what SUBJECTS_KNOWN below does.
+SUBJECTS = """These frames are from one short video, showing the same scene at different moments.
+
+List each character who appears: people and animals. One per line, as a short noun phrase -- what they are, plus whatever distinguishes them. Follow this shape:
+
+<what they are> <the details that identify them: clothing, colour, hair, build>
+
+Fill that in from THESE frames. The angle brackets are a placeholder, not content -- do not repeat any wording from these instructions.
+
+List each character ONCE. The same person seen from different angles, in
+different framings, or in several frames is still ONE character, so do not list
+them again. If you are unsure whether two are the same person, assume they are.
+
+Describe only what you can see. No labels, no names, no numbering. Skip anyone
+who appears once in the background. If there are no characters -- a landscape, a
+product shot, an abstract animation -- write NONE.
+
+No preamble, nothing else."""
+
+SUBJECTS_KNOWN = ("\nThe characters in this video are:\n{subjects}\n"
+                  "Refer to them the same way, so the description stays "
+                  "consistent between shots. Do not mention a character who is "
+                  "not visible in these frames.\n")
+
+
+# The camera movement is measured, not guessed, so it is given to the model as
+# fact rather than asked for. Left to itself a VLM reports "the camera remains
+# stationary" over a crane shot -- it cannot recover motion from stills.
+CAMERA_FACT = ("\nThe camera movement has been measured for you: {motion}. "
+               "State this in your description and do not contradict it.\n")
+
+
+def beats_for(shot, detail: str) -> list:
+    """Split a shot into equal windows short enough to describe properly.
+
+    Equal windows rather than content-adaptive ones: the cuts already handle the
+    big structural breaks, and inside a single shot there is no reliable signal
+    for where one beat ends and the next begins that is worth the extra pass.
+    """
+    length = float(DETAIL.get(detail, DETAIL["normal"])["beat"])
+    span = max(0.0, shot.end - shot.start)
+    if span <= length * 1.35:
+        # A shot only a little over the limit is left whole. Splitting 7 seconds
+        # into 6 + 1 gives a one-second beat that says nothing.
+        return [(shot.start, shot.end)]
+    count = max(2, int(round(span / length)))
+    return [(shot.start + span * i / count, shot.start + span * (i + 1) / count)
+            for i in range(count)]
+
+
+# Token budgets for the two setup passes when the user has not overridden them.
+# The overview is one sentence and the character list is a handful of short
+# lines, so neither needs much; the shot passes are what actually produce length.
+OVERVIEW_TOKENS = 120
+CHARACTER_TOKENS = 200
+
+
+def token_budget(detail: str, override: int = 0) -> dict:
+    """How many tokens each pass may generate.
+
+    ``override`` of 0 means follow the detail level, which is the default and
+    reproduces the behaviour before this setting existed. A real value sets the
+    per-shot budget directly and scales the two setup passes with it, so raising
+    it does not leave a long shot description next to a truncated character list.
+    """
+    settings = DETAIL.get(detail, DETAIL["normal"])
+    if not override or override <= 0:
+        return {"shot": settings["tokens"],
+                "overview": OVERVIEW_TOKENS,
+                "characters": CHARACTER_TOKENS}
+
+    shot = int(override)
+    return {"shot": shot,
+            "overview": max(OVERVIEW_TOKENS, shot // 4),
+            "characters": max(CHARACTER_TOKENS, shot // 2)}
+
+
+def frames_for(duration: float, detail: str) -> int:
+    """How many frames to show the model for a shot of this length."""
+    settings = DETAIL.get(detail, DETAIL["normal"])
+    wanted = int(round(max(0.0, duration) * settings["per_second"]))
+    return max(settings["min"], min(settings["max"], wanted))
+
+
+def sample_times(start: float, end: float, count: int) -> list[float]:
+    """Frame times spread across a shot, at bin centres.
+
+    Centres rather than edges: landing exactly on ``end`` picks up the next
+    shot's first frame, which is how a description acquires things that are not
+    in the shot.
+    """
+    count = max(1, int(count))
+    span = max(0.0, end - start)
+    return [start + span * (i + 0.5) / count for i in range(count)]
+
+
+def context_times(shots, total: int = CONTEXT_FRAMES) -> list[float]:
+    """Times for the overview and cast passes, with every shot represented.
+
+    Each shot gets at least one frame; whatever is left over goes to the longest
+    shots, which is where most of the clip's content is.
+    """
+    if not shots:
+        return []
+    share = {shot.index: 1 for shot in shots}
+    spare = max(0, total - len(shots))
+    for shot in sorted(shots, key=lambda s: -s.duration):
+        if spare <= 0:
+            break
+        share[shot.index] += 1
+        spare -= 1
+
+    times: list[float] = []
+    for shot in shots:
+        times.extend(sample_times(shot.start, shot.end, share[shot.index]))
+    return sorted(times)
+
+
+def assign_speech(speech, shots) -> dict:
+    """Map shot index -> its speech segments, each segment used exactly once.
+
+    A line spoken across a cut overlaps two shots. Listing it under both reads as
+    though it were said twice, so it goes to whichever shot it spends most of
+    itself in.
+    """
+    placed: dict = {shot.index: [] for shot in shots}
+    if not shots:
+        return placed
+
+    for segment in speech.segments:
+        start, end = segment[0], segment[1]
+        best, most = shots[0], -1.0
+        for shot in shots:
+            overlap = min(end, shot.end) - max(start, shot.start)
+            if overlap > most:
+                best, most = shot, overlap
+        placed[best.index].append(segment)
+    return placed
+
+
+# Words that carry no identity, so they should not make two descriptions of
+# different people look alike.
+_FILLER = {"a", "an", "the", "in", "on", "with", "and", "of", "is", "has",
+           "wearing", "wears", "dressed", "who", "that", "his", "her", "their",
+           "man", "woman", "person", "young", "older", "adult"}
+
+
+def _same_character(first: str, second: str) -> bool:
+    """Do these two lines describe the same character?
+
+    Token overlap on the distinguishing words. "a man in a green jacket" and "a
+    man in an olive puffer jacket and black beanie" share the wardrobe words that
+    matter once the filler is dropped -- and they are exactly the pair the model
+    produces when it lists someone twice from two different framings.
+    """
+    import re
+
+    def words(text):
+        return {w for w in re.findall(r"[a-z]+", text.lower()) if w not in _FILLER}
+
+    left, right = words(first), words(second)
+    if not left or not right:
+        return False
+    return len(left & right) / min(len(left), len(right)) >= 0.6
+
+
+def clean_subjects(raw: str) -> str:
+    """Tidy the character pass: strip formatting, drop NONE, merge repeats.
+
+    The model lists the same person more than once fairly often -- the context
+    frames deliberately span every shot, so it sees them in several framings and
+    describes each. The prompt asks for one line per character; this enforces it,
+    keeping the longest description of each since that is the most informative.
+    """
+    import re
+
+    if not raw or raw.strip().upper().startswith("NONE"):
+        return ""
+
+    rows = []
+    for row in raw.splitlines():
+        row = row.strip()
+        if not row or row.upper() == "NONE":
+            continue
+        row = re.sub(r"^[-*\u2022]\s*|^\d+[.)]\s*", "", row)
+        row = re.sub(r"^(Man|Woman|Person|Subject|Character)\s*[A-Z0-9]?\s*[-:]\s*",
+                     "", row, flags=re.IGNORECASE)
+        row = row.rstrip(" .;,")
+        # A model that echoes the prompt's placeholder rather than filling it in
+        # produces a line with angle brackets. That is instruction text, not a
+        # character, and it must never reach the shot passes -- whatever lands in
+        # this list gets asserted as fact in every shot description afterwards.
+        if "<" in row and ">" in row:
+            continue
+        if row:
+            rows.append(row)
+
+    # Repeat until nothing more merges. One pass is not enough: replacing an
+    # entry with a fuller description gives it more words, which can make it
+    # match a third entry that the short version did not. "green jacket" and
+    # "olive puffer jacket, black beanie" look unrelated until the first becomes
+    # "dark beanie and green puffer jacket".
+    merged = list(rows)
+    for _ in range(4):
+        collapsed: list[str] = []
+        for row in merged:
+            for index, existing in enumerate(collapsed):
+                if _same_character(existing, row):
+                    if len(row) > len(existing):
+                        collapsed[index] = row      # keep the fuller description
+                    break
+            else:
+                collapsed.append(row)
+        if len(collapsed) == len(merged):
+            break
+        merged = collapsed
+    return "\n".join(merged)
+
+
+def clock(seconds: float) -> str:
+    """MM:SS.mmm -- the form H3 wants cut times written in."""
+    minutes, rest = divmod(max(0.0, float(seconds)), 60.0)
+    return f"{int(minutes):02d}:{rest:06.3f}"
+
+
+def sentences_for(detail: str) -> str:
+    return {"brief": "one sentence",
+            "normal": "two or three sentences",
+            "detailed": "three to five sentences"}.get(detail, "two or three sentences")
+
+
+def sections(overview: str, subjects: str, shots: list, speech) -> dict:
+    """The output broken into its pieces, so each can leave the node separately.
+
+    ``assemble`` joins these into the full description. Keeping them apart means
+    a downstream node that only wants the cast list does not have to parse it
+    back out of a formatted block.
+    """
+    subject_text = clean_subjects(subjects)
+
+    placed = assign_speech(speech, [shot for shot, _ in shots])
+
+    rows: list[str] = []
+    for shot, beats in shots:
+        if rows:
+            rows.append("")
+        header = f"[Shot {shot.index}] From {clock(shot.start)} to {clock(shot.end)}"
+        if len(beats) == 1:
+            rows.append(f"{header}, {beats[0][2].strip()}")
+        else:
+            rows.append(header + ":")
+            for start, end, text in beats:
+                rows.append(f"    {clock(start)} - {clock(end)}  {text.strip()}")
+        for start, end, said in placed.get(shot.index, []):
+            rows.append(f"    speech {clock(start)}-{clock(end)}: \"{said}\"")
+
+    if speech.note:
+        audio = speech.note
+    elif speech.spoken:
+        audio = (f"speech in {speech.language_full or 'an unknown language'} "
+                 f"({speech.probability:.0%} confidence)")
+    else:
+        audio = "no speech detected"
+
+    return {"overview": (overview or "").strip(),
+            "subjects": subject_text,
+            "shots": "\n".join(rows),
+            "audio": audio}
+
+
+def assemble(overview: str, subjects: str, shots: list, speech) -> str:
+    """Everything, in one block -- the full description output."""
+    part = sections(overview, subjects, shots, speech)
+    lines: list[str] = []
+    if part["overview"]:
+        lines += [f"overview: {part['overview']}", ""]
+    if part["subjects"]:
+        lines += ["characters identified:", part["subjects"], ""]
+    lines += ["shots:", "", part["shots"]]
+    if part["audio"]:
+        lines += ["", f"audio: {part['audio']}"]
+    return "\n".join(lines).strip()
+
+
+def transcript_text(speech) -> str:
+    """The transcript on its own, with timings, so dialogue can be reformatted
+    downstream without re-running the vision passes."""
+    if not speech.spoken:
+        return speech.note or "no speech detected"
+    rows = [f"[{clock(start)} - {clock(end)}] {text}"
+            for start, end, text in speech.segments]
+    if speech.note:
+        rows.append(f"({speech.note})")
+    return "\n".join(rows)

custom_nodes/ComfyUI-Nugget/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "comfyui-nugget"
+version = "1.1.0"
+description = "Nugget nodes for ComfyUI: video auto transcription with measured cuts and camera movement, and image batching that pads instead of cropping."
+license = { text = "MIT" }
+requires-python = ">=3.10"
+# Nothing here is a hard install. PyAV, numpy, Pillow and torch all ship with
+# ComfyUI. faster-whisper is the one optional extra and the node degrades to a
+# visual-only description without it.
+dependencies = []
+
+[project.optional-dependencies]
+speech = ["faster-whisper"]
+
+[project.urls]
+Repository = ""
+
+[tool.comfy]
+PublisherId = ""
+DisplayName = "Nugget"
+Icon = ""

custom_nodes/ComfyUI-Nugget/recall.py

@@ -0,0 +1,149 @@
+"""Remembering the expensive half of a run.
+
+ComfyUI caches a node's outputs and skips the node entirely when its inputs have
+not changed. That works until the cached result is large: in RAM pressure mode
+ComfyUI purges big entries to keep memory free, and this node's ``images`` output
+is over 800 MB for a thirteen-second clip. When that entry is purged the whole
+node re-runs -- cut detection, transcription and every vision pass -- to rebuild
+frames that took about a second to decode.
+
+The two halves have wildly different costs and should not share a fate:
+
+    decoding frames      about a second, and hundreds of megabytes
+    describing the clip  minutes, and a few kilobytes of text
+
+So the description is cached here, keyed on the video and on every setting that
+could change it. If ComfyUI evicts the node's outputs and runs it again, the
+frames are decoded afresh -- cheap -- and the text comes straight back out of
+this. Nothing large is held, so there is nothing worth evicting.
+
+This is deliberately not a substitute for ComfyUI's cache. When that works, this
+is never consulted. It only earns its keep on the path where the outputs were
+thrown away but the inputs did not actually change.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+from collections import OrderedDict
+
+log = logging.getLogger("Nugget")
+
+# Entries are text, a few kilobytes each. Small enough that the cache can never
+# become the thing that triggers an eviction.
+MAX_ENTRIES = 8
+
+# Bumped whenever the shape of a stored entry or the meaning of a setting
+# changes, so an old entry from a previous version of the pack can never be
+# handed back as if it were current.
+SCHEMA = 2
+
+# How much of a temporary copy is read to fingerprint it. Head, middle and tail
+# rather than the whole file: a re-encode or a different clip changes at least
+# one of the three, and reading 3 MB is immaterial next to a decode.
+SAMPLE = 1024 * 1024
+
+_STORE: "OrderedDict[tuple, tuple]" = OrderedDict()
+
+
+def _model_id(clip) -> str:
+    """Enough to tell one loaded encoder from another.
+
+    A different model writes a different description from the same video, so it
+    has to be part of the key. Falls back to the object's identity when the name
+    is not exposed -- that is over-cautious rather than wrong: it produces a miss
+    where a hit was possible, never a hit where the model has changed.
+    """
+    for path in (("tokenizer", "clip_name"), ("cond_stage_model", "__class__")):
+        obj = clip
+        for step in path:
+            obj = getattr(obj, step, None)
+            if obj is None:
+                break
+        if isinstance(obj, str):
+            return obj
+        if obj is not None and hasattr(obj, "__name__"):
+            return str(obj.__name__)
+    return str(id(clip))
+
+
+def _digest(path: str, size: int) -> str:
+    """A content fingerprint from three slices of the file.
+
+    Used only for temporary copies. Reading the whole of a two-minute clip to
+    decide whether to skip a minute of work is affordable but pointless -- head,
+    middle and tail plus the exact byte count is already far more discriminating
+    than the mtime it replaces.
+    """
+    hasher = hashlib.blake2b(str(size).encode(), digest_size=16)
+    spots = [0]
+    if size > SAMPLE:
+        spots.append(max(0, size // 2 - SAMPLE // 2))
+        spots.append(max(0, size - SAMPLE))
+    try:
+        with open(path, "rb") as handle:
+            for spot in sorted(set(spots)):
+                handle.seek(spot)
+                hasher.update(handle.read(SAMPLE))
+    except OSError:
+        return ""
+    return hasher.hexdigest()
+
+
+def identity(video_path: str, temporary: bool = False):
+    """Which video this is, without decoding it.
+
+    For a file that lives on disk in its own right -- what Load Video normally
+    hands over -- name, size and mtime settle it. Size and mtime rather than a
+    hash of the contents because reading gigabytes to decide whether to skip a
+    minute of work is a poor trade, and a video that changes in place without
+    changing either is not a case worth paying for.
+
+    A temporary copy is the exception and has to be treated differently. It is
+    written fresh on every queue, so its mtime is always new and its path always
+    different: keyed that way, the same video would miss every single time and
+    the cache would never fire at all. Those get a content fingerprint instead,
+    which is the same for the same footage no matter how many times it is
+    re-extracted.
+    """
+    try:
+        stat = os.stat(video_path)
+    except OSError:
+        return None
+    if temporary:
+        digest = _digest(video_path, stat.st_size)
+        if not digest:
+            return None
+        return ("content", stat.st_size, digest)
+    return ("file", os.path.basename(video_path), stat.st_size,
+            round(stat.st_mtime, 3))
+
+
+def key(video_path: str, clip, settings: dict, temporary: bool = False):
+    """Identity of a description: the file, the model, and every setting."""
+    who = identity(video_path, temporary)
+    if who is None:
+        return None
+    return (SCHEMA, who, _model_id(clip),
+            tuple(sorted((k, str(v)) for k, v in settings.items())))
+
+
+def get(cache_key):
+    if cache_key is None or cache_key not in _STORE:
+        return None
+    _STORE.move_to_end(cache_key)
+    return _STORE[cache_key]
+
+
+def put(cache_key, value) -> None:
+    if cache_key is None:
+        return
+    _STORE[cache_key] = value
+    while len(_STORE) > MAX_ENTRIES:
+        _STORE.popitem(last=False)
+
+
+def clear() -> None:
+    _STORE.clear()

custom_nodes/ComfyUI-Nugget/selftest.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""What this machine can and cannot do, without loading a model.
+
+    ComfyUI/python_embeded/python.exe custom_nodes/ComfyUI-Nugget/selftest.py
+
+Run this before wiring anything. It reports which parts are available and where
+speech will run, and it spends no VRAM and no time doing it.
+"""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+GIB = 1024 ** 3
+
+
+def line(label, state, detail=""):
+    print("  %-22s %-9s %s" % (label, state, detail))
+
+
+print("\n  Nugget self-test")
+print("  " + "-" * 62)
+
+print("\n  required")
+try:
+    import av
+    line("PyAV", "ok", f"{av.__version__} -- video decoding")
+except ImportError:
+    line("PyAV", "MISSING", "ships with ComfyUI; if LoadVideo works, this should")
+
+try:
+    import numpy
+    line("numpy", "ok", numpy.__version__)
+except ImportError:
+    line("numpy", "MISSING", "ships with ComfyUI")
+
+try:
+    from PIL import Image  # noqa: F401
+    line("Pillow", "ok", "")
+except ImportError:
+    line("Pillow", "MISSING", "ships with ComfyUI")
+
+print("\n  optional -- speech")
+try:
+    import faster_whisper  # noqa: F401
+    line("faster-whisper", "ok", "dialogue will be transcribed")
+except ImportError:
+    line("faster-whisper", "absent", "no transcript without it")
+    try:
+        import speech as _sp
+        print("  " + " " * 22 + "install with:")
+        print("  " + " " * 22 + _sp.install_hint())
+    except Exception:
+        pass
+
+print("\n  compute")
+device, compute = "cpu", "int8"
+try:
+    import torch
+    line("torch", "ok", torch.__version__)
+    if hasattr(torch, "cuda") and torch.cuda.is_available():
+        name = torch.cuda.get_device_name(0)
+        try:
+            free, total = torch.cuda.mem_get_info()
+            line("CUDA", "ok", f"{name} -- {free / GIB:.1f} of "
+                               f"{total / GIB:.1f} GiB free")
+        except Exception:
+            line("CUDA", "ok", name)
+        for module in ("nvidia.cublas", "nvidia.cudnn"):
+            try:
+                __import__(module)
+                line(module.split(".")[1], "ok", "needed for GPU speech")
+            except ImportError:
+                line(module.split(".")[1], "absent",
+                     "GPU speech will fall back to CPU "
+                     f"(pip install {module.replace('.', '-')}-cu12)")
+    elif getattr(getattr(torch, "backends", None), "mps", None) and \
+            torch.backends.mps.is_available():
+        line("MPS", "ok", "Apple Silicon -- speech runs on CPU "
+                          "(CTranslate2 has no Metal backend)")
+    else:
+        line("GPU", "none", "everything runs on CPU")
+except ImportError:
+    line("torch", "MISSING", "ComfyUI cannot run without it")
+
+try:
+    import speech
+    device, compute = speech._plan()
+    line("speech will use", device, compute)
+except Exception as exc:
+    line("speech plan", "unknown", str(exc))
+
+print("\n  text generation")
+try:
+    from comfy_api.latest import io  # noqa: F401
+    line("comfy_api", "ok", "node schema available")
+except ImportError:
+    line("comfy_api", "absent", "run this from inside ComfyUI's python, or "
+                                "ignore if you only want the checks above")
+print("  " + " " * 22 + "clip.generate() is checked at run time; it needs")
+print("  " + " " * 22 + "ComfyUI v0.15.0 or newer and a Gemma encoder.")
+
+print("\n  own tests")
+result = os.system(f'"{sys.executable}" '
+                   f'"{os.path.join(os.path.dirname(os.path.abspath(__file__)), "tests", "run_all.py")}"'
+                   + (" >nul 2>&1" if os.name == "nt" else " >/dev/null 2>&1"))
+line("test suite", "ok" if result == 0 else "FAILED",
+     "tests/run_all.py" if result == 0 else "run it directly to see why")
+
+print()

custom_nodes/ComfyUI-Nugget/speech.py

@@ -0,0 +1,383 @@
+"""Transcription, and the VRAM choreography around it.
+
+Ordering matters more than it looks. ComfyUI's model manager is lazy: the CLIP
+object arrives at the node before ``execute`` runs, but the weights only move to
+the GPU when something first calls ``tokenize`` or ``generate``. So "run Whisper
+before the model loads" is not about node order -- it is about not touching the
+clip until Whisper has been released. This module is therefore called first and
+told to free what it needs, which also evicts anything left resident from a
+previous run of the graph.
+
+The device is chosen from free VRAM rather than fixed, and every GPU path falls
+back to CPU. faster-whisper is built on CTranslate2, which has no ROCm and no
+Metal backend, so AMD and Apple Silicon users are on CPU whatever the numbers
+say. Its CUDA path also needs ``nvidia-cublas-cu12`` and ``nvidia-cudnn-cu12``
+installed separately, and a missing cuDNN throws at model construction -- by far
+the most common way this fails on an otherwise healthy machine.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections import OrderedDict
+from dataclasses import dataclass, field
+
+try:
+    from . import interrupt
+except ImportError:          # direct import in the test suite
+    import interrupt
+
+log = logging.getLogger("Nugget")
+
+GIB = 1024 ** 3
+
+# Rough resident cost of large-v3 plus working space, by compute type.
+NEEDS = {"float16": 4.5 * GIB, "int8_float16": 2.5 * GIB}
+
+# Below this the language guess is not worth reporting. Music beds and room tone
+# routinely come back as confident-sounding nonsense, and a wrong language tag is
+# worse than no tag because everything downstream trusts it.
+LANGUAGE_FLOOR = 0.5
+
+# Transcripts, keyed on the file and the settings that change them. Nudging
+# `detail` re-runs the vision passes, which is the point -- but it should not
+# also re-run a two-minute transcription that cannot have changed. Small, because
+# entries hold text and a handful of clips is all anyone iterates on at once.
+_CACHE: "OrderedDict[tuple, Speech]" = OrderedDict()
+CACHE_SIZE = 8
+
+
+def _key(wav_path: str, model_size: str, language: str):
+    """Identity of the audio plus the settings that affect the result.
+
+    Size and mtime rather than a hash of the bytes: the WAV is extracted fresh
+    each run to a new temporary file, so its own path is useless as an identity
+    and hashing megabytes to save seconds is a poor trade.
+    """
+    try:
+        stat = os.stat(wav_path)
+        return (stat.st_size, round(stat.st_mtime, 3), model_size, language)
+    except OSError:
+        return None
+
+
+# Whisper reports ISO 639-1 codes. Nothing downstream benefits from "ja" over
+# "Japanese" -- least of all a prompt writer that has to put the language name
+# into a dialogue tag -- so the code is expanded here once.
+LANGUAGE_NAMES = {
+    "af": "Afrikaans", "am": "Amharic", "ar": "Arabic", "as": "Assamese",
+    "az": "Azerbaijani", "ba": "Bashkir", "be": "Belarusian", "bg": "Bulgarian",
+    "bn": "Bengali", "bo": "Tibetan", "br": "Breton", "bs": "Bosnian",
+    "ca": "Catalan", "cs": "Czech", "cy": "Welsh", "da": "Danish",
+    "de": "German", "el": "Greek", "en": "English", "es": "Spanish",
+    "et": "Estonian", "eu": "Basque", "fa": "Persian", "fi": "Finnish",
+    "fo": "Faroese", "fr": "French", "gl": "Galician", "gu": "Gujarati",
+    "ha": "Hausa", "haw": "Hawaiian", "he": "Hebrew", "hi": "Hindi",
+    "hr": "Croatian", "ht": "Haitian Creole", "hu": "Hungarian",
+    "hy": "Armenian", "id": "Indonesian", "is": "Icelandic", "it": "Italian",
+    "ja": "Japanese", "jw": "Javanese", "ka": "Georgian", "kk": "Kazakh",
+    "km": "Khmer", "kn": "Kannada", "ko": "Korean", "la": "Latin",
+    "lb": "Luxembourgish", "ln": "Lingala", "lo": "Lao", "lt": "Lithuanian",
+    "lv": "Latvian", "mg": "Malagasy", "mi": "Maori", "mk": "Macedonian",
+    "ml": "Malayalam", "mn": "Mongolian", "mr": "Marathi", "ms": "Malay",
+    "mt": "Maltese", "my": "Burmese", "ne": "Nepali", "nl": "Dutch",
+    "nn": "Norwegian Nynorsk", "no": "Norwegian", "oc": "Occitan",
+    "pa": "Punjabi", "pl": "Polish", "ps": "Pashto", "pt": "Portuguese",
+    "ro": "Romanian", "ru": "Russian", "sa": "Sanskrit", "sd": "Sindhi",
+    "si": "Sinhala", "sk": "Slovak", "sl": "Slovenian", "sn": "Shona",
+    "so": "Somali", "sq": "Albanian", "sr": "Serbian", "su": "Sundanese",
+    "sv": "Swedish", "sw": "Swahili", "ta": "Tamil", "te": "Telugu",
+    "tg": "Tajik", "th": "Thai", "tk": "Turkmen", "tl": "Tagalog",
+    "tr": "Turkish", "tt": "Tatar", "uk": "Ukrainian", "ur": "Urdu",
+    "uz": "Uzbek", "vi": "Vietnamese", "yi": "Yiddish", "yo": "Yoruba",
+    "yue": "Cantonese", "zh": "Chinese",
+}
+
+
+def language_code(name: str) -> str:
+    """"Japanese" -> "ja". The node shows names; Whisper wants codes."""
+    if not name or name.lower() in ("auto", ""):
+        return "auto"
+    lowered = name.strip().lower()
+    if lowered == "filipino":
+        lowered = "tagalog"
+    for code, label in LANGUAGE_NAMES.items():
+        if label.lower() == lowered:
+            return code
+    return lowered if len(lowered) <= 3 else "auto"
+
+
+def language_name(code: str) -> str:
+    """"ja" -> "Japanese". Unknown codes come back unchanged rather than blank."""
+    if not code:
+        return ""
+    return LANGUAGE_NAMES.get(code.strip().lower(), code)
+
+
+@dataclass
+class Speech:
+    segments: list = field(default_factory=list)   # [(start, end, text), ...]
+    language: str = ""
+    probability: float = 0.0
+    note: str = ""
+
+    @property
+    def spoken(self) -> bool:
+        return bool(self.segments)
+
+    @property
+    def language_full(self) -> str:
+        return language_name(self.language)
+
+    def text(self) -> str:
+        return " ".join(t for _, _, t in self.segments).strip()
+
+    def during(self, start: float, end: float) -> list:
+        """Segments overlapping a window, for folding speech into a shot."""
+        return [s for s in self.segments if s[1] > start and s[0] < end]
+
+
+def available() -> bool:
+    try:
+        import faster_whisper  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+def install_hint() -> str:
+    """The exact command for THIS install, not a generic package name.
+
+    Nearly every report of "I installed it and it still says missing" is the same
+    mistake: pip ran against system Python while ComfyUI runs its own. Printing
+    the interpreter that is actually executing removes the guesswork.
+    """
+    import sys
+
+    executable = sys.executable or "python"
+    if "python_embeded" in executable.replace("\\", "/"):
+        # Windows portable build.
+        return (f'"{executable}" -m pip install faster-whisper')
+    return f'"{executable}" -m pip install faster-whisper'
+
+
+_DLL_DIRS_ADDED = False
+
+
+def enable_cuda_libraries() -> list[str]:
+    """Put the pip-installed CUDA DLLs on Windows' search path, carefully.
+
+    This is why "Library cublas64_12.dll is not found or cannot be loaded"
+    happens on a machine where the package is installed and importable: pip puts
+    the DLL in ``site-packages/nvidia/...``, and since Python 3.8 that directory
+    is not searched unless ``os.add_dll_directory`` is called for it.
+
+    Two things this must not do, both learned the hard way.
+
+    It must not prepend those folders to ``PATH``. That changes DLL resolution
+    for the whole process, including torch's own CUDA libraries, and a process
+    holding two different CUDA runtimes does not raise an exception -- it dies,
+    taking ComfyUI with it.
+
+    It must not register torch's ``lib`` folder. Torch has already loaded what it
+    needs; pointing other libraries at the same folder only invites the version
+    mix above.
+
+    A no-op off Windows, where the loader follows RPATH and finds these anyway.
+    """
+    global _DLL_DIRS_ADDED
+    if _DLL_DIRS_ADDED or os.name != "nt":
+        return []
+    _DLL_DIRS_ADDED = True
+
+    import site
+
+    bases = {b for b in (*site.getsitepackages(), site.getusersitepackages()) if b}
+    added = []
+    for base in bases:
+        nvidia = os.path.join(base, "nvidia")
+        if not os.path.isdir(nvidia):
+            continue
+        for where, _, files in os.walk(nvidia):
+            if not any(f.lower().endswith(".dll") for f in files):
+                continue
+            try:
+                os.add_dll_directory(where)
+                added.append(where)
+            except (OSError, AttributeError):
+                pass
+
+    if added:
+        log.info("[Nugget] registered %d CUDA library folder(s)",
+                 len(added))
+    return added
+
+
+def torch_cuda_major() -> int:
+    """Which CUDA the installed torch was built against, or 0."""
+    try:
+        import torch
+        if getattr(torch.version, "hip", None):
+            return 0
+        version = getattr(torch.version, "cuda", "") or ""
+        return int(version.split(".")[0]) if version[:1].isdigit() else 0
+    except Exception:
+        return 0
+
+
+def _plan() -> tuple[str, str]:
+    """(device, compute_type), decided from what the GPU actually has spare.
+
+    Everything here is best-effort: if the ComfyUI memory API is not importable
+    or the device is not CUDA, CPU is the answer and that is fine.
+    """
+    try:
+        import torch
+    except ImportError:
+        return "cpu", "int8"
+
+    if not (hasattr(torch, "cuda") and torch.cuda.is_available()):
+        # Covers CPU-only builds and Apple Silicon. CTranslate2 has no MPS
+        # backend, so there is nothing to gain from checking for one.
+        return "cpu", "int8"
+
+    # CTranslate2 is built against CUDA 12. Running it beside a torch built for
+    # a different CUDA means two runtimes in one process, which crashes the
+    # process rather than raising -- and on a 20-second clip the GPU saves a few
+    # seconds. Not worth it: use the CPU and say why.
+    major = torch_cuda_major()
+    if major and major != 12:
+        log.info("[Nugget] torch is built for CUDA %d.x while "
+                 "faster-whisper needs CUDA 12; transcribing on the CPU to "
+                 "avoid mixing CUDA runtimes in one process", major)
+        return "cpu", "int8"
+
+    try:
+        from comfy import model_management
+
+        device = model_management.get_torch_device()
+        # Ask ComfyUI to make room. On a re-queue the text encoder is often
+        # still resident from the last run, so "before the model loads" is not
+        # automatic -- it has to be evicted.
+        try:
+            model_management.free_memory(NEEDS["float16"], device)
+        except Exception:
+            pass
+        free = model_management.get_free_memory(device)
+    except Exception:
+        try:
+            free, _ = torch.cuda.mem_get_info()
+        except Exception:
+            return "cpu", "int8"
+
+    if free >= NEEDS["float16"]:
+        return "cuda", "float16"
+    if free >= NEEDS["int8_float16"]:
+        return "cuda", "int8_float16"
+    return "cpu", "int8"
+
+
+def transcribe(wav_path: str | None, model_size: str = "large-v3",
+               language: str = "auto", progress=None) -> Speech:
+    """Transcribe a 16 kHz mono WAV. Never raises -- failures come back as a note."""
+    if model_size in ("off", "none", "", None):
+        return Speech(note="transcription turned off")
+
+    if not wav_path:
+        return Speech(note="no audio track")
+
+    if not available():
+        return Speech(note="faster-whisper is not installed, so there is no "
+                           "transcript. Install it into the Python ComfyUI is "
+                           "running, not your system Python:\n    "
+                           + install_hint())
+
+    key = _key(wav_path, model_size, language)
+    if key is not None and key in _CACHE:
+        _CACHE.move_to_end(key)
+        log.info("[Nugget] reusing cached transcript")
+        return _CACHE[key]
+
+    from faster_whisper import WhisperModel
+
+    device, compute = _plan()
+    if device == "cuda":
+        enable_cuda_libraries()
+    if progress:
+        progress(f"transcribing with {model_size} on {device}")
+
+    model = None
+    try:
+        try:
+            model = WhisperModel(model_size, device=device, compute_type=compute)
+        except Exception as exc:
+            if device == "cpu":
+                raise
+            # Almost always a missing cuDNN/cuBLAS wheel. Slower beats broken.
+            log.warning("[Nugget] %s on GPU failed (%s); using CPU",
+                        model_size, exc)
+            if progress:
+                progress(f"GPU unavailable for {model_size}, using CPU")
+            device, compute = "cpu", "int8"
+            model = WhisperModel(model_size, device=device, compute_type=compute)
+
+        segments, info = model.transcribe(
+            wav_path,
+            language=None if language in ("auto", "", None) else language,
+            # Silero VAD. Without it large-v3 invents dialogue over music and
+            # room tone -- subtitle credits, "thank you for watching", repeated
+            # phrases. Non-negotiable for arbitrary user footage.
+            vad_filter=True,
+            # Stops the decoder feeding its own output back as context, which is
+            # what turns one hallucinated line into twenty.
+            condition_on_previous_text=False,
+        )
+
+        rows = []
+        for segment in segments:
+            # faster-whisper yields as it decodes, so this is the only place a
+            # cancel can be noticed during transcription -- and transcription is
+            # the longest uninterruptible stretch in the whole node.
+            interrupt.check()
+            text = (segment.text or "").strip()
+            if text:
+                rows.append((float(segment.start), float(segment.end), text))
+
+        detected = getattr(info, "language", "") or ""
+        probability = float(getattr(info, "language_probability", 0.0) or 0.0)
+
+        if not rows:
+            result = Speech(note="no speech detected")
+        elif language in ("auto", "", None) and probability < LANGUAGE_FLOOR:
+            result = Speech(rows, detected, probability,
+                            note=f"language uncertain ({probability:.0%}); the audio "
+                                 f"may be music rather than speech")
+        else:
+            result = Speech(rows, detected, probability)
+
+        if key is not None:
+            _CACHE[key] = result
+            while len(_CACHE) > CACHE_SIZE:
+                _CACHE.popitem(last=False)
+        return result
+
+    except interrupt.Interrupted:
+        # A cancel is not a failure to be reported as a note -- it has to
+        # propagate, or the run carries on into the vision passes.
+        raise
+    except Exception as exc:
+        log.warning("[Nugget] transcription failed: %s", exc)
+        text = str(exc)
+        if "cublas" in text.lower() or "cudnn" in text.lower():
+            text = (f"{text}\n    The CUDA libraries are installed but not on the "
+                    f"DLL search path, or missing. Run install.py in this folder.")
+        return Speech(note=f"transcription failed: {text}")
+    finally:
+        del model
+        try:
+            import torch
+            if hasattr(torch, "cuda") and torch.cuda.is_available():
+                torch.cuda.empty_cache()
+        except Exception:
+            pass

custom_nodes/ComfyUI-Nugget/tests/run_all.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+"""Run every suite in the pack.
+
+    python tests/run_all.py
+"""
+import os
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+SUITES = ["test_registration.py", "test_transcribe.py", "test_image.py",
+          "test_prompt.py"]
+
+failed = []
+for suite in SUITES:
+    path = os.path.join(HERE, suite)
+    if not os.path.exists(path):
+        continue
+    print("\n" + "=" * 66)
+    print("  %s" % suite)
+    print("=" * 66)
+    if subprocess.call([sys.executable, path]) != 0:
+        failed.append(suite)
+
+print("\n" + "=" * 66)
+print("  ALL SUITES PASSED" if not failed else "  FAILED: %s" % ", ".join(failed))
+print("=" * 66)
+sys.exit(1 if failed else 0)

custom_nodes/ComfyUI-Nugget/tests/test_image.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+"""Offline tests for the image nodes. No ComfyUI, no GPU.
+
+    python tests/test_image.py
+"""
+
+import os
+import sys
+import types
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import torch  # noqa: E402
+
+
+def _stub():
+    """Stand in for comfy.utils and comfy_api so the module imports alone."""
+    comfy = types.ModuleType("comfy")
+    utils = types.ModuleType("comfy.utils")
+
+    def common_upscale(s, w, h, method, crop):
+        mode = {"lanczos": "bicubic", "bicubic": "bicubic", "area": "area",
+                "bilinear": "bilinear", "nearest-exact": "nearest-exact"}[method]
+        kw = {} if mode in ("area", "nearest-exact") else {"align_corners": False}
+        return torch.nn.functional.interpolate(s, size=(h, w), mode=mode, **kw)
+
+    utils.common_upscale = common_upscale
+    comfy.utils = utils
+    sys.modules.setdefault("comfy", comfy)
+    sys.modules.setdefault("comfy.utils", utils)
+
+    api = types.ModuleType("comfy_api")
+    latest = types.ModuleType("comfy_api.latest")
+
+    class _Any:
+        Input = staticmethod(lambda *a, **k: None)
+        Output = staticmethod(lambda *a, **k: None)
+
+    class io:
+        Image = Mask = Int = String = Boolean = Combo = Float = Video = Clip = _Any
+        Schema = staticmethod(lambda *a, **k: None)
+        NodeOutput = tuple
+
+        class ComfyNode:
+            pass
+
+    latest.io = io
+    latest.ComfyExtension = object
+    api.latest = latest
+    sys.modules.setdefault("comfy_api", api)
+    sys.modules.setdefault("comfy_api.latest", latest)
+
+
+_stub()
+import nodes_image as N  # noqa: E402
+
+FAILED = []
+
+
+def check(name, got, want):
+    ok = got == want
+    print("  %-54s %s" % (name, "ok" if ok else "FAIL"))
+    if not ok:
+        print("      got  %r\n      want %r" % (got, want))
+        FAILED.append(name)
+
+
+def frames(sizes, channels=3):
+    return [torch.rand(h, w, channels) for w, h in sizes]
+
+
+def bars(fr, cw, ch, **kw):
+    opts = dict(scale_method="lanczos", allow_upscale=True, pad_color="black",
+                pad_hex="#000000", position="center")
+    opts.update(kw)
+    _, masks = N.compose(fr, cw, ch, opts["scale_method"], opts["allow_upscale"],
+                         opts["pad_color"], opts["pad_hex"], opts["position"])
+    return [round(100 * (1 - float(masks[i].mean()))) for i in range(masks.shape[0])]
+
+
+print("\nthe canvas must not invent padding")
+# Clamping width and height independently destroys the union box's aspect: a
+# lone 1920x1080 against a 1024 ceiling used to come back a 1024x1024 square,
+# 44% of it bars, with nothing to reconcile against.
+for name, sizes in (("a single 16:9 image", [(1920, 1080)]),
+                    ("a single tall portrait", [(2000, 3000)]),
+                    ("three identical portraits", [(832, 1216)] * 3),
+                    ("three identical landscapes", [(1216, 832)] * 3),
+                    ("an extreme 40:1 panorama", [(4000, 100)])):
+    fr = frames(sizes)
+    w, h = N.canvas_for(fr, 1024, 1024)
+    check("%s needs no padding" % name, max(bars(fr, w, h)), 0)
+
+check("the canvas keeps the source aspect",
+      N.canvas_for(frames([(1920, 1080)]), 1024, 1024), (1024, 576))
+
+print("\nthe ceiling is still a ceiling")
+w, h = N.canvas_for(frames([(4000, 3000)]), 1024, 1024)
+check("neither axis exceeds it", (w <= 1024, h <= 1024), (True, True))
+check("tiny inputs are not upscaled to the ceiling",
+      N.canvas_for(frames([(64, 64)]), 16384, 16384), (64, 64))
+check("an asymmetric ceiling is respected",
+      N.canvas_for(frames([(2000, 2000)]), 512, 256), (256, 256))
+
+print("\nmixed shapes pad rather than crop")
+fr = frames([(832, 1216), (1216, 832)])
+w, h = N.canvas_for(fr, 1024, 1024)
+padded = bars(fr, w, h)
+check("both images are padded, neither cropped", all(0 < b < 100 for b in padded), True)
+_, masks = N.compose(fr, w, h, "lanczos", True, "black", "#000000", "center")
+check("every pixel of each source survives",
+      all(float(masks[i].sum()) > 0 for i in range(masks.shape[0])), True)
+
+print("\ncollect")
+check("a batch on one socket is flattened",
+      len(N.collect({"image_1": torch.rand(4, 64, 64, 3)})), 4)
+check("gaps between sockets are skipped",
+      len(N.collect({"image_1": None, "image_3": torch.rand(1, 64, 64, 3)})), 1)
+check("RGB and RGBA are harmonised",
+      N.collect({"image_1": torch.rand(1, 8, 8, 3),
+                 "image_2": torch.rand(1, 8, 8, 4)})[0].shape[2], 4)
+try:
+    N.collect({"image_1": None})
+    check("nothing connected raises", False, True)
+except ValueError as exc:
+    check("nothing connected raises", True, True)
+    check("and the message mentions bypass", "bypassed" in str(exc), True)
+
+print("\npad colours and placement")
+fr = frames([(100, 50)])
+img, _ = N.compose(fr, 100, 100, "lanczos", True, "white", "#000000", "center")
+check("white bars are white", round(float(img[0, 0, 0, 0])), 1)
+img, _ = N.compose(fr, 100, 100, "lanczos", True, "custom hex", "#0000ff", "center")
+check("custom hex reaches the blue channel", round(float(img[0, 0, 0, 2])), 1)
+grey = N.compose(frames([(100, 50)], channels=1), 100, 100, "lanczos", True,
+                 "custom hex", "#0000ff", "center")[0]
+check("greyscale pads by luminance, not the red channel",
+      float(grey[0, 0, 0, 0]) > 0.0, True)
+
+_, m_top = N.compose(fr, 100, 100, "lanczos", True, "black", "#000000", "top")
+check("top places content at the top edge", float(m_top[0][0].mean()), 1.0)
+_, m_bot = N.compose(fr, 100, 100, "lanczos", True, "black", "#000000", "bottom")
+check("bottom places content at the bottom edge", float(m_bot[0][-1].mean()), 1.0)
+
+print("\nno upscaling when asked")
+small = frames([(50, 50)])
+img, masks = N.compose(small, 512, 512, "lanczos", False, "black", "#000000", "center")
+check("a small image keeps its native size", int(masks[0].sum()), 2500)
+check("but the canvas is still the size asked for", tuple(img.shape[1:3]), (512, 512))
+
+print("\npadding report")
+check("a uniform set reports no padding",
+      "no padding" in N.padding_report(
+          N.compose(frames([(100, 100)]), 100, 100, "lanczos", True,
+                    "black", "#000000", "center")[1]), True)
+check("a padded set reports a percentage",
+      "padding" in N.padding_report(
+          N.compose(frames([(100, 50)]), 100, 100, "lanczos", True,
+                    "black", "#000000", "center")[1]), True)
+
+print("\ndtype and device survive")
+half = [torch.rand(64, 64, 3).half()]
+out, _ = N.compose(half, 32, 32, "lanczos", True, "black", "#000000", "center")
+check("float16 in, float16 out", out.dtype, torch.float16)
+check("mixed devices are harmonised without raising",
+      len(N.collect({"image_1": torch.rand(1, 8, 8, 3),
+                     "image_2": torch.rand(1, 8, 8, 3)})), 2)
+
+print("\ngaps from bypassed images")
+# Bypassing a Load Image leaves the link in place and delivers None, so the
+# canvas still shows four sockets wired while only two images arrive. Skipping
+# the hole is the only option, but it renumbers everything after it.
+import logging as _logging
+
+
+class _Catch(_logging.Handler):
+    def __init__(self):
+        super().__init__()
+        self.lines = []
+
+    def emit(self, record):
+        self.lines.append(record.getMessage())
+
+
+def _collect_with_log(images):
+    logger = _logging.getLogger("Nugget")
+    grab = _Catch()
+    was, logger.disabled = logger.disabled, False
+    logger.addHandler(grab)
+    try:
+        frames = N.collect(images)
+    finally:
+        logger.removeHandler(grab)
+        logger.disabled = was
+    return frames, " ".join(grab.lines)
+
+
+def _img(n=64):
+    return torch.rand(1, n, n, 3)
+
+
+gapped = {"image_1": _img(), "image_2": None, "image_3": None, "image_4": _img(128)}
+frames, said = _collect_with_log(gapped)
+check("a gap does not raise", len(frames), 2)
+check("the surviving images are the ones that were wired",
+      [int(f.shape[0]) for f in frames], [64, 128])
+check("the renumbering is reported", "renumbered" in said, True)
+check("it names the empty sockets", "image_2, image_3" in said, True)
+check("it spells out the new numbering", "image_4 is picture 2" in said, True)
+
+_, quiet = _collect_with_log({"image_1": _img(), "image_2": _img(), "image_3": _img()})
+check("a contiguous set says nothing", quiet, "")
+
+_, tail = _collect_with_log({"image_1": _img(), "image_2": _img(), "image_4": None})
+check("a trailing empty socket is not a gap", tail, "")
+
+print("\nevery image bypassed")
+try:
+    N.collect({f"image_{i}": None for i in range(1, 5)})
+    check("the batch node refuses, since it must output an IMAGE", False, True)
+except ValueError as exc:
+    check("the batch node refuses, since it must output an IMAGE", True, True)
+    check("and explains that bypass is the likely cause",
+          "bypassed" in str(exc), True)
+
+print("\n%s" % ("ALL PASSED" if not FAILED else "%d FAILED: %s" % (len(FAILED), FAILED)))
+sys.exit(1 if FAILED else 0)

custom_nodes/ComfyUI-Nugget/tests/test_prompt.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""Offline tests for the prompt node. No ComfyUI, no GPU, no model."""
+
+import os
+import sys
+import types
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import torch  # noqa: E402
+
+
+def _stub():
+    comfy = types.ModuleType("comfy")
+    utils = types.ModuleType("comfy.utils")
+
+    def common_upscale(s, w, h, method, crop):
+        return torch.nn.functional.interpolate(s, size=(h, w), mode="bicubic",
+                                               align_corners=False)
+
+    utils.common_upscale = common_upscale
+    comfy.utils = utils
+    sys.modules.setdefault("comfy", comfy)
+    sys.modules.setdefault("comfy.utils", utils)
+
+    api = types.ModuleType("comfy_api")
+    latest = types.ModuleType("comfy_api.latest")
+
+    class _Any:
+        Input = staticmethod(lambda *a, **k: None)
+        Output = staticmethod(lambda *a, **k: None)
+
+    class io:
+        Image = Mask = Int = String = Boolean = Combo = Float = _Any
+        Video = Clip = Audio = _Any
+        Schema = staticmethod(lambda *a, **k: None)
+        NodeOutput = tuple
+
+        class ComfyNode:
+            pass
+
+    latest.io = io
+    latest.ComfyExtension = object
+    api.latest = latest
+    sys.modules.setdefault("comfy_api", api)
+    sys.modules.setdefault("comfy_api.latest", latest)
+
+
+_stub()
+import llm            # noqa: E402
+import nodes_prompt as P  # noqa: E402
+
+FAILED = []
+
+
+def check(name, got, want):
+    ok = got == want
+    print("  %-56s %s" % (name, "ok" if ok else "FAIL"))
+    if not ok:
+        print("      got  %r\n      want %r" % (got, want))
+        FAILED.append(name)
+
+
+def frames(sizes):
+    return [torch.rand(h, w, 3) for w, h in sizes]
+
+
+print("\nmax image size caps, it does not stretch or upscale")
+out = P.cap(frames([(832, 1216)]), 1024)
+check("a tall image is capped on its long side", tuple(out[0].shape[:2]), (1024, 701))
+out = P.cap(frames([(1920, 1080)]), 1024)
+check("a wide image is capped on its long side", tuple(out[0].shape[:2]), (576, 1024))
+out = P.cap(frames([(200, 200)]), 1024)
+check("a small image is left alone", tuple(out[0].shape[:2]), (200, 200))
+src = frames([(1000, 500)])
+out = P.cap(src, 500)
+check("the aspect ratio is preserved exactly",
+      round(out[0].shape[1] / out[0].shape[0], 3), 2.0)
+
+print("\nimages keep their own shapes -- nothing is made to match")
+mixed = P.cap(frames([(832, 1216), (1216, 832), (200, 200)]), 1024)
+check("a mixed set stays mixed", P.uniform(mixed), False)
+check("no image was cropped",
+      [tuple(f.shape[:2]) for f in mixed], [(1024, 701), (701, 1024), (200, 200)])
+
+# The whole point of the cap: references that agree on shape come out identical,
+# so even the fallback below has nothing to pad.
+same = P.cap(frames([(832, 1216)] * 3), 1024)
+check("a uniform set becomes identical sizes", P.uniform(same), True)
+
+print("\nthe list payload")
+batches = P.as_batches(same)
+check("each image is its own batch of one", [tuple(b.shape) for b in batches],
+      [(1, 1024, 701, 3)] * 3)
+check("no images gives no payload", P.as_batches([]), [])
+
+print("\nthe padding fallback, for builds that need one tensor")
+stacked = llm._stack_padded(P.as_batches(mixed))
+check("a mixed set stacks onto the bounding canvas",
+      tuple(stacked.shape), (3, 1024, 1024, 3))
+uniform_stack = llm._stack_padded(P.as_batches(same))
+check("a uniform set needs no bars at all",
+      tuple(uniform_stack.shape), (3, 1024, 701, 3))
+# Bars are black, so a padded corner is zero while the content is not.
+corner = float(stacked[2, 0, 0].sum())
+check("padding is black", corner, 0.0)
+check("content survives padding", float(stacked[0].sum()) > 0, True)
+
+print("\n_batch dispatches on what it is given")
+check("None stays None", llm._batch(None), None)
+check("an empty list is None", llm._batch([]), None)
+one = torch.rand(1, 8, 8, 3)
+check("a lone tensor passes through", llm._batch([one]).shape, one.shape)
+check("a bare tensor passes through", llm._batch(one).shape, one.shape)
+many = llm._batch([torch.rand(1, 8, 8, 3), torch.rand(1, 4, 4, 3)])
+check("several tensors stay a list", isinstance(many, list), True)
+check("and keep their own shapes",
+      [tuple(t.shape[1:3]) for t in many], [(8, 8), (4, 4)])
+
+print("\nsampling on/off actually reaches the model")
+# The widget used to be inferred from temperature, so switching sampling on with
+# temperature at zero decoded greedily -- the control said one thing and the
+# model did another.
+_seen = {}
+
+
+class _Inner:
+    def generate(self, *a, **k):
+        pass
+
+
+class _Clip:
+    cond_stage_model = _Inner()
+
+    def tokenize(self, *a, **k):
+        return "T"
+
+    def generate(self, tokens, **kw):
+        _seen.clear()
+        _seen.update(kw)
+        return "G"
+
+    def decode(self, g):
+        return "text."
+
+
+def _run(**kw):
+    llm.ask(_Clip(), "p", None, 100, 42, **kw)
+    return _seen
+
+
+check("sampling off decodes greedily",
+      _run(sample=False, temperature=0.7)["do_sample"], False)
+check("sampling on samples",
+      _run(sample=True, temperature=0.7)["do_sample"], True)
+check("sampling on with temperature 0 still samples",
+      _run(sample=True, temperature=0.0)["do_sample"], True)
+check("and its temperature is floored, not left at zero",
+      _run(sample=True, temperature=0.0)["temperature"] > 0, True)
+check("the filters are inert when greedy",
+      (_run(sample=False)["top_k"], _run(sample=False)["top_p"]), (0, 1.0))
+check("the filters engage when sampling",
+      _run(sample=True, temperature=0.7)["top_k"], 64)
+
+# A repetition penalty reshapes the logits before the pick, so it applies to
+# greedy decoding too. It used to be dropped whenever sampling was off.
+check("repetition penalty applies when greedy",
+      _run(sample=False, repetition_penalty=1.15)["repetition_penalty"], 1.15)
+check("repetition penalty applies when sampling",
+      _run(sample=True, temperature=0.7,
+           repetition_penalty=1.15)["repetition_penalty"], 1.15)
+check("its default is off", _run(sample=False)["repetition_penalty"], 1.0)
+
+check("callers that pass no sample flag stay greedy",
+      _run(temperature=0.0)["do_sample"], False)
+check("and a bare temperature still turns sampling on",
+      _run(temperature=0.8)["do_sample"], True)
+
+print("\ndescription detail")
+check("off appends nothing", P.DETAIL["off"][0], "")
+check("it is named for images", "img_description_detail" in open(
+    os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+                 "nodes_prompt.py")).read(), True)
+check("off does not raise the budget", P.DETAIL["off"][1], 0)
+for _level in ("brief", "normal", "detailed"):
+    check("%s appends an instruction" % _level, bool(P.DETAIL[_level][0]), True)
+check("the budget grows with the level",
+      P.DETAIL["brief"][1] < P.DETAIL["normal"][1] < P.DETAIL["detailed"][1], True)
+check("every level is offered", sorted(P.DETAIL),
+      ["brief", "detailed", "normal", "off"])
+
+print("\nsampling control degrades rather than disappearing")
+# DynamicCombo is recent and its nested-input API has been churning. If it is
+# missing or its signature has moved, the node must still register with plain
+# widgets -- a cosmetic feature is not worth losing the node over.
+_inputs = P.sampling_input()
+check("it returns at least one input", len(_inputs) >= 1, True)
+check("and reports which shape it used", isinstance(P.DYNAMIC_SAMPLING, bool), True)
+
+print("\n%s" % ("ALL PASSED" if not FAILED else "%d FAILED: %s" % (len(FAILED), FAILED)))
+sys.exit(1 if FAILED else 0)

custom_nodes/ComfyUI-Nugget/tests/test_registration.py

@@ -0,0 +1,283 @@
+#!/usr/bin/env python3
+"""Static checks on how the pack registers itself.
+
+    python tests/test_registration.py
+
+These parse the source rather than importing it, so they run without ComfyUI --
+which matters, because every failure they catch is one that makes nodes silently
+vanish from the menu rather than raise anything visible.
+"""
+
+import ast
+import os
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.dirname(HERE)
+
+FAILED = []
+
+
+def check(name, got, want):
+    ok = got == want
+    print("  %-56s %s" % (name, "ok" if ok else "FAIL"))
+    if not ok:
+        print("      got  %r\n      want %r" % (got, want))
+        FAILED.append(name)
+
+
+def tree(filename):
+    with open(os.path.join(ROOT, filename)) as fh:
+        return ast.parse(fh.read())
+
+
+NODE_MODULES = ["nodes_transcribe.py", "nodes_motion.py", "nodes_prompt.py",
+                "nodes_image.py"]
+
+print("\nevery name in NODES is a class defined in the same file")
+# A find-and-replace across the package once rewrote `NODES = [VideoAutoTranscribe]`
+# into `NODES = [Nugget]`, because that string was byte-identical to the log
+# prefix being replaced. The module then raised NameError on import, the
+# defensive loader swallowed it, and the node simply was not in the menu.
+for filename in NODE_MODULES:
+    t = tree(filename)
+    defined = {n.name for n in ast.walk(t) if isinstance(n, ast.ClassDef)}
+    listed = []
+    for node in t.body:
+        if isinstance(node, ast.Assign) and getattr(node.targets[0], "id", "") == "NODES":
+            listed = [e.id for e in node.value.elts if isinstance(e, ast.Name)]
+    check("%s declares NODES" % filename, bool(listed), True)
+    check("%s: every entry exists as a class" % filename,
+          [n for n in listed if n not in defined], [])
+
+print("\nnode identity is complete and unique")
+ids, names, categories = [], [], []
+for filename in NODE_MODULES:
+    for call in ast.walk(tree(filename)):
+        if not (isinstance(call, ast.Call) and getattr(call.func, "attr", "") == "Schema"):
+            continue
+        kw = {k.arg: getattr(k.value, "value", None) for k in call.keywords}
+        ids.append(kw.get("node_id"))
+        names.append(kw.get("display_name"))
+        categories.append(kw.get("category"))
+
+check("five nodes are declared", len(ids), 5)
+check("no node is missing an id", [i for i in ids if not i], [])
+check("no node is missing a display name", [n for n in names if not n], [])
+check("node ids are unique", len(set(ids)), len(ids))
+check("display names are unique", len(set(names)), len(names))
+check("every node sits under Nugget", sorted(set(categories)), ["Nugget"])
+
+print("\n__init__ registers the modern way")
+init = tree("__init__.py")
+assigned = {n.targets[0].id for n in ast.walk(init)
+            if isinstance(n, ast.Assign) and hasattr(n.targets[0], "id")}
+# ComfyUI's loader checks NODE_CLASS_MAPPINGS first and only falls through to
+# comfy_entrypoint if it is absent, so defining both registers nothing useful.
+check("NODE_CLASS_MAPPINGS is not defined", "NODE_CLASS_MAPPINGS" in assigned, False)
+check("WEB_DIRECTORY is defined", "WEB_DIRECTORY" in assigned, True)
+check("comfy_entrypoint is defined",
+      any(isinstance(n, ast.AsyncFunctionDef) and n.name == "comfy_entrypoint"
+          for n in ast.walk(init)), True)
+check("each node module is imported separately",
+      len([n for n in ast.walk(init)
+           if isinstance(n, ast.Try)]) >= 1, True)
+
+print("\nthe browser extension matches a real node id")
+js = os.path.join(ROOT, "web", "js", "nugget_batch_nocrop.js")
+check("the js file is present", os.path.exists(js), True)
+if os.path.exists(js):
+    with open(js) as fh:
+        source = fh.read()
+    referenced = [i for i in ids if i and ('"%s"' % i) in source]
+    check("it binds to a node that exists", bool(referenced), True)
+
+print("\nno undefined names anywhere in the package")
+# Two shipped bugs were undefined names that Python only raises when the line
+# runs: `NODES = [Nugget]` after a find-and-replace, and a stale `shot_frames`
+# in a log call that fired only after the first generation finished. Neither is
+# a syntax error, so nothing caught them before a user did.
+try:
+    from pyflakes.api import check as _pyflakes_check
+    from pyflakes.reporter import Reporter
+    import io as _io
+
+    _out, _err = _io.StringIO(), _io.StringIO()
+    _reporter = Reporter(_out, _err)
+    _problems = []
+    for _f in sorted(os.listdir(ROOT)):
+        if not _f.endswith(".py"):
+            continue
+        with open(os.path.join(ROOT, _f)) as _fh:
+            _source = _fh.read()
+        _out.truncate(0), _out.seek(0)
+        _pyflakes_check(_source, _f, _reporter)
+        for _line in _out.getvalue().splitlines():
+            # Unused imports are style, not breakage.
+            if "imported but unused" in _line or "unable to detect" in _line:
+                continue
+            _problems.append(_line)
+    check("pyflakes reports no problems", _problems, [])
+except ImportError:
+    print("  skipped -- pip install pyflakes to run this check")
+
+print("\nnothing on the node destroys ComfyUI's cache")
+# ComfyUI skips a node whose inputs are unchanged. A widget that randomises
+# itself on every queue makes every queue a cache miss, so re-running to try a
+# different sampler seed re-transcribed the whole video for nothing.
+import re as _re3
+# A self-randomising seed is a cache miss on every queue. That is only worth
+# paying where the seed actually changes the output -- so the prompt node may
+# have one (it can sample), and the transcriber may not (it is always greedy,
+# so a re-run costs minutes and returns identical text).
+for _f in ("nodes_transcribe.py", "nodes_image.py"):
+    with open(os.path.join(ROOT, _f)) as _fh:
+        _src2 = _fh.read()
+    _live = [l.strip() for l in _src2.splitlines()
+             if "control_after_generate" in l and not l.strip().startswith("#")]
+    check("%s has no self-randomising widget" % _f, _live, [])
+
+with open(os.path.join(ROOT, "nodes_prompt.py")) as _fh:
+    _psrc = _fh.read()
+check("the prompt node's seed warns that randomize costs a re-run",
+      "identical answer" in _psrc, True)
+
+print("\nthe prompt node's widget order is predictable")
+# ComfyUI sorts advanced widgets to the end, so a node that mixes them has a
+# saved widget order that no longer matches the schema. Every value in a
+# hand-written workflow then shifts along by one -- which is how sampling_mode
+# ended up reading a temperature of zero and quietly decoding greedily.
+with open(os.path.join(ROOT, "nodes_prompt.py")) as _fh:
+    _psrc2 = _fh.read()
+_adv = [l.strip() for l in _psrc2.splitlines()
+        if "advanced=True" in l and not l.strip().startswith("#")]
+check("no advanced widgets on the prompt node", _adv, [])
+
+
+print("\nthe auto-expanding sockets extension covers the right nodes")
+# A node declaring image_1..image_N needs the browser extension, or all nine
+# sockets show at once. A node with a single `image` input must not be bound,
+# or the extension would delete a socket it does not understand.
+import re as _re4
+
+with open(os.path.join(ROOT, "web", "js", "nugget_batch_nocrop.js")) as _fh:
+    _js = _fh.read()
+_m = _re4.search(r"NODES = new Set\(\[(.*?)\]\)", _js, _re4.S)
+check("the extension declares a node list", bool(_m), True)
+_covered = set(_re4.findall(r'"(\w+)"', _m.group(1))) if _m else set()
+
+_needs = set()
+for _f in NODE_MODULES:
+    _src3 = open(os.path.join(ROOT, _f)).read()
+    for _call in ast.walk(ast.parse(_src3)):
+        if not (isinstance(_call, ast.Call)
+                and getattr(_call.func, "attr", "") == "Schema"):
+            continue
+        _kw = {k.arg: k.value for k in _call.keywords}
+        _nid = getattr(_kw.get("node_id"), "value", None)
+        _ins = ast.dump(_kw.get("inputs")) if "inputs" in _kw else ""
+        # image_1 appears either literally or as an f-string range
+        if '"image_1"' in _ins or "image_" in _ins:
+            _needs.add(_nid)
+
+check("every multi-image node is bound", sorted(_needs - _covered), [])
+check("no single-image node is bound", sorted(_covered - _needs), [])
+
+print("\nthe declared widget order matches the schema")
+# Positional widgets_values in a saved workflow are matched against this order.
+# Inserting a widget without updating saved workflows shifts every value after
+# it -- which has silently broken sampling_mode once and img_description_detail
+# once. WIDGET_ORDER is the thing a workflow is written against, so it has to
+# stay in step with the schema.
+import ast as _ast
+import re as _re5
+
+with open(os.path.join(ROOT, "nodes_prompt.py")) as _fh:
+    _psrc3 = _fh.read()
+
+_declared = _re5.search(r"WIDGET_ORDER = \[(.*?)\]", _psrc3, _re5.S)
+check("WIDGET_ORDER is declared", bool(_declared), True)
+_order = _re5.findall(r'"(\w+)"', _declared.group(1)) if _declared else []
+
+# Everything in WIDGET_ORDER must exist as an input somewhere in the module.
+_inputs = set(_re5.findall(r'io\.\w+\.Input\(\s*\n?\s*"(\w+)"', _psrc3))
+check("every declared widget exists in the schema",
+      [w for w in _order if w not in _inputs], [])
+
+# And the widget-ish inputs must all be declared, so nothing is forgotten.
+_widgetish = {w for w in _inputs
+              if w not in {"clip"} and not w.startswith("image_")}
+check("every schema widget is declared in WIDGET_ORDER",
+      sorted(_widgetish - set(_order)), [])
+
+check("img description detail is first", _order[0] if _order else None,
+      "img_description_detail")
+
+print("\nnothing defeats ComfyUI's cache")
+# ComfyUI skips a node whose inputs are unchanged. It decides that, not the node
+# -- so "fixed" does not make a node refuse to run, it keeps the inputs stable so
+# the node is never asked. Anything here that varies between runs, or that tells
+# ComfyUI to always re-execute, breaks that.
+import re as _re6
+
+_FORCES_RERUN = ("IS_CHANGED", "fingerprint_inputs", "NOT_IDEMPOTENT",
+                 "is_output_node", "OUTPUT_NODE")
+for _f in ("nodes_transcribe.py", "nodes_prompt.py", "nodes_image.py"):
+    with open(os.path.join(ROOT, _f)) as _fh:
+        _body = "\n".join(l for l in _fh if not l.strip().startswith("#"))
+    for _marker in _FORCES_RERUN:
+        check("%s does not declare %s" % (_f, _marker), _marker in _body, False)
+
+# A varying value must not reach an output, or a cached result would differ
+# from a fresh one. The clock is used for timing logs, which is fine -- what
+# matters is whether anything derived from it is returned.
+def _time_backed_names(tree):
+    names = set()
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Assign):
+            continue
+        src = ast.dump(node.value)
+        if "attr='time'" in src or "'monotonic'" in src or "'perf_counter'" in src:
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    names.add(target.id)
+    return names
+
+
+for _f in ("nodes_transcribe.py", "nodes_prompt.py"):
+    with open(os.path.join(ROOT, _f)) as _fh:
+        _tree = ast.parse(_fh.read())
+    _clocky = _time_backed_names(_tree)
+    _returned = set()
+    for _node in ast.walk(_tree):
+        if (isinstance(_node, ast.Call)
+                and getattr(_node.func, "attr", "") == "NodeOutput"):
+            for _arg in _node.args:
+                _returned |= {n.id for n in ast.walk(_arg)
+                              if isinstance(n, ast.Name)}
+    check("%s returns nothing derived from the clock" % _f,
+          sorted(_clocky & _returned), [])
+    check("%s does not use uuid or random" % _f,
+          bool(_re6.search(r"\buuid\b|\brandom\.",
+                           open(os.path.join(ROOT, _f)).read())), False)
+
+
+print("\nlong loops can be cancelled")
+_LONG = {"speech.py": "interrupt.check()",
+         "video.py": "interrupt.check()"}
+for _f, _needle in _LONG.items():
+    with open(os.path.join(ROOT, _f)) as _fh:
+        _src = _fh.read()
+    check("%s polls for cancellation" % _f, _needle in _src, True)
+
+with open(os.path.join(ROOT, "speech.py")) as _fh:
+    _speech = _fh.read()
+# A broad `except Exception` around transcription would turn a cancel into a
+# note and let the run continue into the vision passes.
+check("transcription re-raises a cancel instead of noting it",
+      "except interrupt.Interrupted:" in _speech and
+      _speech.index("except interrupt.Interrupted:") <
+      _speech.index("except Exception as exc:\n        log.warning"), True)
+
+print("\n%s" % ("ALL PASSED" if not FAILED else "%d FAILED: %s" % (len(FAILED), FAILED)))
+sys.exit(1 if FAILED else 0)

custom_nodes/ComfyUI-Nugget/tests/test_transcribe.py

@@ -0,0 +1,715 @@
+#!/usr/bin/env python3
+"""Offline tests. No ComfyUI, no GPU, no model.
+
+    python tests/test_videoautotranscribe.py
+
+The video tests need PyAV and build their own clip, so nothing external is
+downloaded and nothing depends on a file being in the right place.
+"""
+
+import os
+import sys
+
+import torch  # noqa: E402
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import detect            # noqa: E402
+import llm               # noqa: E402
+import prompts           # noqa: E402
+import speech            # noqa: E402
+
+FAILED = []
+
+
+def check(name, got, want):
+    ok = got == want
+    print("  %-52s %s" % (name, "ok" if ok else "FAIL"))
+    if not ok:
+        print("      got  %r\n      want %r" % (got, want))
+        FAILED.append(name)
+
+
+def flat(scores_spikes, n=240, fps=12.0, floor=0.002):
+    """A flat score series with spikes at the given (index, value) positions."""
+    series = [(i / fps, floor) for i in range(n)]
+    for index, value in scores_spikes:
+        series[index] = (series[index][0], value)
+    return series
+
+
+print("\nnon-maximum suppression -- the bug this pack exists to avoid")
+# A weak candidate just before a strong one. Accepting in time order keeps the
+# weak one and rejects the strong one; NMS must do the opposite.
+series = flat([(48, 0.10), (56, 0.55)])          # 4.00s weak, 4.67s strong
+cuts = detect.find_cuts(series, "normal", 1.0, 0.0, 20.0)
+check("keeps the strong cut, not the earlier weak one", cuts, [56 / 12.0])
+
+series = flat([(60, 0.50), (120, 0.50), (180, 0.50)])
+check("three well-spaced cuts all survive",
+      detect.find_cuts(series, "normal", 1.0, 0.0, 20.0),
+      [5.0, 10.0, 15.0])
+
+print("\nboundaries")
+series = flat([(3, 0.60), (120, 0.50)])          # 0.25s in, then 10s
+check("head sliver suppressed by min_shot",
+      detect.find_cuts(series, "normal", 1.0, 0.0, 20.0), [10.0])
+
+series = flat([(120, 0.50), (236, 0.60)])        # 10s, then 19.67s of a 20s clip
+check("tail sliver suppressed (fade to black)",
+      detect.find_cuts(series, "normal", 1.0, 0.0, 20.0), [10.0])
+
+print("\nflash suppression")
+pair = flat([(60, 0.50), (62, 0.48)])            # 2 frames apart, similar scores
+check("a flash pair is dropped entirely",
+      detect.find_cuts(pair, "normal", 1.0, 0.0, 20.0), [])
+uneven = flat([(60, 0.50), (62, 0.05)])          # close but very different
+check("a cut followed by minor activity is kept",
+      detect.find_cuts(uneven, "normal", 1.0, 0.0, 20.0), [5.0])
+
+print("\nshot building")
+shots = detect.build_shots([3.0, 7.0], 0.0, 10.0)
+check("cuts become contiguous shots",
+      [(s.start, s.end) for s in shots], [(0.0, 3.0), (3.0, 7.0), (7.0, 10.0)])
+check("shots are numbered from 1", [s.index for s in shots], [1, 2, 3])
+check("no cuts -> exactly one shot",
+      [(s.start, s.end) for s in detect.build_shots([], 0.0, 10.0)], [(0.0, 10.0)])
+check("cuts outside the region are ignored",
+      len(detect.build_shots([-5.0, 3.0, 99.0], 0.0, 10.0)), 2)
+shots = detect.build_shots([3.0, 7.0], 0.0, 10.0)
+check("shots tile with no gap",
+      all(abs(shots[i].end - shots[i + 1].start) < 1e-9
+          for i in range(len(shots) - 1)), True)
+
+print("\nsensitivity ordering")
+weak = flat([(120, 0.02)])
+counts = [len(detect.find_cuts(weak, s, 1.0, 0.0, 20.0))
+          for s in ("low", "normal", "high")]
+check("high finds at least as much as low", counts[2] >= counts[0], True)
+
+print("\ntoken stripping -- the <think>/<|image> leak")
+check("reasoning block removed",
+      llm.tidy("<think>hmm</think>Real answer."), "Real answer.")
+check("truncated reasoning yields nothing, not the trace",
+      llm.tidy("<think>hmm, let me consider"), "")
+check("text before an unclosed think tag survives",
+      llm.tidy("Answer.<think>now let me reconsi"), "Answer.")
+check("gemma 4 markers removed",
+      llm.tidy("<|turn>model\n<|channel>final\nText.<turn|>"), "Text.")
+check("gemma 3 markers removed",
+      llm.tidy("<start_of_turn>model\nText.<end_of_turn>"), "Text.")
+check("image placeholders removed",
+      llm.tidy("<|image><|image|><image|>\n\nText."), "Text.")
+check("the observed runaway collapses to the answer",
+      llm.tidy("Answer." + "\n<think>\n</think>\n\n<|image>" * 30), "Answer.")
+check("clean text is untouched", llm.tidy("Just text."), "Just text.")
+check("empty stays empty", llm.tidy(""), "")
+
+print("\ntimestamps")
+check("MM:SS.mmm", prompts.clock(8.828), "00:08.828")
+check("under a second", prompts.clock(0.12), "00:00.120")
+check("past a minute", prompts.clock(75.5), "01:15.500")
+check("negative clamps to zero", prompts.clock(-3.0), "00:00.000")
+
+print("\nassembly")
+sp = speech.Speech([(1.0, 2.0, "Hello there."), (9.0, 9.5, "Later.")], "en", 0.98)
+shots = detect.build_shots([5.0], 0.0, 10.0)
+text = prompts.assemble("Warm and bright.", "a man in a green jacket",
+                        [(shots[0], [(0.0, 5.0, "a man stands.")]),
+                         (shots[1], [(5.0, 10.0, "he turns.")])], sp)
+check("overview present", "overview: Warm and bright." in text, True)
+check("subjects present", "a man in a green jacket" in text, True)
+check("shot headers carry real timestamps",
+      "[Shot 1] From 00:00.000 to 00:05.000," in text, True)
+check("speech lands in the shot it happens in",
+      text.index("Hello there.") < text.index("[Shot 2]"), True)
+check("later speech lands in the later shot",
+      text.index("Later.") > text.index("[Shot 2]"), True)
+check("language reported in full", "speech in English" in text, True)
+
+silent = speech.Speech(note="no speech detected")
+quiet = prompts.assemble("Look.", "NONE",
+                         [(shots[0], [(0.0, 5.0, "a man stands.")])], silent)
+check("no-speech note shown", "audio: no speech detected" in quiet, True)
+check("NONE subjects omitted", "subjects:" not in quiet, True)
+check("transcript falls back to the note",
+      prompts.transcript_text(silent), "no speech detected")
+check("transcript carries timings",
+      prompts.transcript_text(sp).splitlines()[0],
+      "[00:00:01.000 - 00:00:02.000] Hello there.".replace("00:00:0", "00:0"))
+
+print("\nadaptive frame budget")
+check("a short shot is not over-sampled", prompts.frames_for(0.4, "normal"), 3)
+check("a medium shot scales with length", prompts.frames_for(4.0, "normal"), 6)
+check("a long shot is capped", prompts.frames_for(60.0, "normal"), 9)
+check("brief caps lower than normal",
+      prompts.frames_for(60.0, "brief") < prompts.frames_for(60.0, "normal"), True)
+check("detailed caps higher than normal",
+      prompts.frames_for(60.0, "detailed") > prompts.frames_for(60.0, "normal"), True)
+check("never returns zero", prompts.frames_for(0.0, "brief") >= 2, True)
+
+print("\nsample times stay inside the shot")
+times = prompts.sample_times(4.8, 8.828, 5)
+check("first is after the cut", times[0] > 4.8, True)
+check("last is before the next cut", times[-1] < 8.828, True)
+check("count honoured", len(times), 5)
+
+print("\ncontext frames cover every shot")
+many = detect.build_shots([1.0, 9.0, 9.6], 0.0, 20.0)   # incl. a 0.6s sliver
+ctx = prompts.context_times(many, 8)
+check("one frame per shot at minimum",
+      all(any(s.start <= t <= s.end for t in ctx) for s in many), True)
+check("budget respected", len(ctx) <= 8, True)
+check("sorted for a single decode pass", ctx == sorted(ctx), True)
+check("no shots -> no frames", prompts.context_times([], 8), [])
+
+print("\nspeech is assigned to exactly one shot")
+shots2 = detect.build_shots([4.8], 0.0, 10.0)
+spanning = speech.Speech([(4.5, 5.9, "crosses the cut")], "en", 0.9)
+placed = prompts.assign_speech(spanning, shots2)
+check("a line crossing a cut is not duplicated",
+      sum(len(v) for v in placed.values()), 1)
+check("it lands in the shot it mostly occupies", len(placed[2]), 1)
+early = speech.Speech([(0.1, 4.0, "before the cut")], "en", 0.9)
+check("a line before the cut lands in shot 1",
+      len(prompts.assign_speech(early, shots2)[1]), 1)
+check("every shot gets a key",
+      sorted(prompts.assign_speech(early, shots2).keys()), [1, 2])
+
+print("\nassembly does not duplicate spanning speech")
+text2 = prompts.assemble("Look.", "NONE",
+                         [(shots2[0], [(0.0, 4.8, "first.")]),
+                          (shots2[1], [(4.8, 10.0, "second.")])], spanning)
+check("spoken line appears exactly once", text2.count("crosses the cut"), 1)
+
+print("\nbeats -- long shots get described in pieces")
+long_shot = detect.build_shots([], 0.0, 20.0)[0]
+check("a 20s shot is split at normal", len(prompts.beats_for(long_shot, "normal")), 3)
+check("detailed splits it further",
+      len(prompts.beats_for(long_shot, "detailed")) >
+      len(prompts.beats_for(long_shot, "normal")), True)
+check("brief splits it less",
+      len(prompts.beats_for(long_shot, "brief")) <
+      len(prompts.beats_for(long_shot, "normal")), True)
+
+short_shot = detect.build_shots([], 0.0, 4.0)[0]
+check("a short shot stays whole", len(prompts.beats_for(short_shot, "normal")), 1)
+edge = detect.build_shots([], 0.0, 7.5)[0]
+check("just over the limit is not split into a sliver",
+      len(prompts.beats_for(edge, "normal")), 1)
+
+beats = prompts.beats_for(long_shot, "normal")
+check("beats tile the shot with no gap",
+      all(abs(beats[i][1] - beats[i + 1][0]) < 1e-9 for i in range(len(beats) - 1)), True)
+check("beats cover the whole shot", (beats[0][0], beats[-1][1]), (0.0, 20.0))
+check("a 20s shot now gets many more frames than before",
+      sum(prompts.frames_for(e - s2, "normal") for s2, e in beats) > 20, True)
+
+print("\nframe grid")
+try:
+    from PIL import Image
+    import video as vm
+    tiles = [Image.new("RGB", (200, 150), (i * 40, 0, 0)) for i in range(6)]
+    out = vm.to_grid(tiles, 768)
+    check("six frames become one image", len(out), 1)
+    check("grid respects the requested width", out[0].size[0] <= 768, True)
+    check("grid keeps the source aspect ratio",
+          abs(out[0].size[1] / out[0].size[0] - (2 * 150) / (3 * 200)) < 0.02, True)
+    check("a single frame is passed through", len(vm.to_grid(tiles[:1], 768)), 1)
+    check("no frames -> nothing", vm.to_grid([], 768), [])
+    check("grid is one image where separate would be six",
+          (len(vm.to_grid(tiles, 768)), len(tiles)), (1, 6))
+except ImportError:
+    print("  skipped (PIL unavailable)")
+
+print("\nmulti-beat assembly")
+sp3 = speech.Speech(note="no speech detected")
+multi = prompts.assemble("Look.", "NONE",
+                         [(long_shot, [(0.0, 10.0, "he walks."),
+                                       (10.0, 20.0, "he stops.")])], sp3)
+check("multi-beat shot uses a header line",
+      "[Shot 1] From 00:00.000 to 00:20.000:" in multi, True)
+check("each beat carries its own times", "00:00.000 - 00:10.000" in multi, True)
+check("second beat present", "00:10.000 - 00:20.000  he stops." in multi, True)
+single = prompts.assemble("Look.", "NONE",
+                          [(short_shot, [(0.0, 4.0, "he waits.")])], sp3)
+check("single-beat shot stays inline",
+      "[Shot 1] From 00:00.000 to 00:04.000, he waits." in single, True)
+
+print("\nframe size is a ceiling, not a target")
+try:
+    from PIL import Image
+    import video as vm
+    tiles = [Image.new("RGB", (100, 75), (0, 0, 0)) for _ in range(4)]
+    big = vm.to_grid(tiles, 1024)
+    check("a grid is not blown up past its source",
+          big[0].size[0] <= 100 * 2, True)
+    small = vm.to_grid(tiles, 120)
+    check("a grid still honours a smaller request", small[0].size[0] <= 120, True)
+except ImportError:
+    print("  skipped (PIL unavailable)")
+
+print("\ninstall hint names the running interpreter")
+hint = speech.install_hint()
+check("mentions the package", "faster-whisper" in hint, True)
+check("names an interpreter, not bare pip", "-m pip" in hint, True)
+
+
+print("\ncamera movement is measured, not guessed")
+try:
+    import numpy as np
+    import camera
+
+    rng = np.random.default_rng(3)
+    base = rng.random((camera.SIZE, camera.SIZE))
+
+    def track(shift_x, shift_y, steps=8):
+        rows = []
+        frame = base
+        for i in range(steps):
+            nxt = np.roll(np.roll(base, shift_x * (i + 1), axis=1),
+                          shift_y * (i + 1), axis=0)
+            dx, dy, dz = camera.step(frame, nxt)
+            rows.append((i * 0.1, dx, dy, dz))
+            frame = nxt
+        return rows
+
+    # Content sliding right means the camera swung left, and vice versa.
+    check("content moving right reads as a left pan",
+          "pans left" in camera.summarise(track(6, 0), 0.0, 10.0), True)
+    check("content moving left reads as a right pan",
+          "pans right" in camera.summarise(track(-6, 0), 0.0, 10.0), True)
+    check("content moving down reads as a tilt up",
+          "tilts up" in camera.summarise(track(0, 6), 0.0, 10.0), True)
+    check("content moving up reads as a tilt down",
+          "tilts down" in camera.summarise(track(0, -6), 0.0, 10.0), True)
+    check("a still camera reads as locked off",
+          "locked off" in camera.summarise(track(0, 0), 0.0, 10.0), True)
+    check("a diagonal move reports both axes",
+          camera.summarise(track(6, 6), 0.0, 10.0).count(" and "), 1)
+    check("an empty window says nothing", camera.summarise([], 0.0, 10.0), "")
+    check("one sample is not enough",
+          camera.summarise([(0.0, 9, 9, 0)], 0.0, 10.0), "")
+    # A moving stretch early, a still stretch later: asking about the later
+    # window must not pick up the earlier movement.
+    mixed = [(t, dx, dy, dz) for t, dx, dy, dz in track(9, 0)]
+    mixed += [(5.0 + i * 0.1, 0, 0, 0) for i in range(8)]
+    check("only motion inside the window counts",
+          "locked off" in camera.summarise(mixed, 5.0, 6.0), True)
+    check("the earlier window still reads as moving",
+          "pans" in camera.summarise(mixed, 0.0, 1.0), True)
+except ImportError:
+    print("  skipped (numpy unavailable)")
+
+print("\noutput sections")
+sp4 = speech.Speech([(1.0, 2.0, "Hi.")], "en", 0.97)
+sh4 = detect.build_shots([5.0], 0.0, 10.0)
+part = prompts.sections("Warm light.", "a man in a beanie",
+                        [(sh4[0], [(0.0, 5.0, "he waits.")]),
+                         (sh4[1], [(5.0, 10.0, "he leaves.")])], sp4)
+check("four sections available",
+      sorted(part.keys()), ["audio", "overview", "shots", "subjects"])
+check("overview is bare, no label", part["overview"], "Warm light.")
+check("subjects are bare, no label", part["subjects"], "a man in a beanie")
+check("shots block has both shots",
+      part["shots"].count("[Shot "), 2)
+check("shots block carries no overview", "Warm light." in part["shots"], False)
+check("audio summarises the speech", "speech in English" in part["audio"], True)
+full = prompts.assemble("Warm light.", "a man in a beanie",
+                        [(sh4[0], [(0.0, 5.0, "he waits.")]),
+                         (sh4[1], [(5.0, 10.0, "he leaves.")])], sp4)
+check("full description contains every section",
+      all(x in full for x in ("overview:", "characters identified:", "shots:", "audio:")), True)
+check("NONE subjects leaves the section empty",
+      prompts.sections("o", "NONE", [(sh4[0], [(0.0, 5.0, "x")])], sp4)["subjects"], "")
+
+print("\nedge guard for fades")
+series = flat([(120, 0.50), (232, 0.60)])   # 10s, then 19.3s of a 20s clip
+check("a fade near the end is not a shot, even at min_shot 0.5",
+      detect.find_cuts(series, "normal", 0.5, 0.0, 20.0), [10.0])
+check("a real cut well inside is kept at min_shot 0.5",
+      detect.find_cuts(flat([(60, 0.5), (90, 0.5)]), "normal", 0.5, 0.0, 20.0),
+      [5.0, 7.5])
+
+print("\nsubject list cleaning")
+check("NONE means nothing", prompts.clean_subjects("NONE"), "")
+check("lowercase none too", prompts.clean_subjects("none"), "")
+check("empty stays empty", prompts.clean_subjects(""), "")
+check("bullets stripped",
+      prompts.clean_subjects("- a tabby cat\n- a red truck"), "a tabby cat\na red truck")
+check("numbering stripped",
+      prompts.clean_subjects("1. a man in a jacket\n2. a dog"), "a man in a jacket\na dog")
+check("legacy Man A labels stripped",
+      prompts.clean_subjects("Man A - beanie and jacket"), "beanie and jacket")
+check("non-people subjects survive intact",
+      prompts.clean_subjects("a red pickup truck"), "a red pickup truck")
+check("blank lines dropped",
+      prompts.clean_subjects("a cat\n\n\na dog"), "a cat\na dog")
+
+print("\nsubjects reach the shot prompt")
+filled = prompts.SHOT.format(layout="Six frames.", span=4.0, sentences="two sentences",
+                             subjects=prompts.SUBJECTS_KNOWN.format(subjects="a tabby cat"),
+                             camera=prompts.CAMERA_FACT.format(motion="the camera pans left"))
+check("subject list is in the prompt", "a tabby cat" in filled, True)
+check("camera fact is in the prompt", "the camera pans left" in filled, True)
+bare = prompts.SHOT.format(layout="Six frames.", span=4.0, sentences="two sentences",
+                           subjects="", camera="")
+check("both are optional", "{" not in bare, True)
+
+print("\nduplicate characters are merged")
+same = prompts.clean_subjects(
+    "a man in a green jacket\n"
+    "a man in an olive puffer jacket and black beanie\n"
+    "a man wearing a dark beanie and green puffer jacket")
+check("three framings of one man collapse to one",
+      len([r for r in same.splitlines() if r]), 1)
+check("the fullest description is the one kept", len(same) > 30, True)
+check("exact repeats collapse",
+      prompts.clean_subjects("a tabby cat\na tabby cat"), "a tabby cat")
+check("a man and a woman stay separate",
+      len(prompts.clean_subjects(
+          "a man in a green jacket\na woman in a red dress").splitlines()), 2)
+check("a man and a dog stay separate",
+      len(prompts.clean_subjects(
+          "a man in a blue coat\na golden retriever").splitlines()), 2)
+check("two men in clearly different clothes stay separate",
+      len(prompts.clean_subjects(
+          "a man in a yellow raincoat\na man in a grey suit").splitlines()), 2)
+check("trailing punctuation stripped",
+      prompts.clean_subjects("a tabby cat."), "a tabby cat")
+check("Character A prefix stripped",
+      prompts.clean_subjects("Character A: a tabby cat"), "a tabby cat")
+
+print("\ncharacters label")
+sp5 = speech.Speech(note="no speech detected")
+sh5 = detect.build_shots([], 0.0, 5.0)
+out5 = prompts.assemble("Look.", "a man in a green jacket",
+                        [(sh5[0], [(0.0, 5.0, "he waits.")])], sp5)
+check("section is labelled 'characters identified:'",
+      "characters identified:" in out5, True)
+check("old 'cast:' label is gone", "cast:" not in out5, True)
+check("old 'subjects:' label is gone", "\nsubjects:" not in out5, True)
+
+print("\nwindows cuda dll registration")
+check("enable_cuda_libraries is a no-op off windows",
+      speech.enable_cuda_libraries() if os.name != "nt" else [], [])
+check("it is idempotent", speech.enable_cuda_libraries(), [])
+
+print("\nwrong CLIP model is caught before any work")
+class _SD1ClipModel: pass
+class _Gemma:
+    def generate(self, *a, **k): pass
+class _Wrapper:
+    def __init__(self, inner): self.cond_stage_model = inner
+    def tokenize(self, *a, **k): pass
+    def generate(self, *a, **k): pass
+    def decode(self, *a, **k): pass
+
+try:
+    llm.check(_Wrapper(_SD1ClipModel()))
+    check("an SD encoder is rejected", False, True)
+except llm.LLMError as exc:
+    check("an SD encoder is rejected", True, True)
+    check("the message names what was loaded",
+          "Stable Diffusion 1.x" in str(exc), True)
+    check("the message says what to do",
+          "text_encoders" in str(exc), True)
+
+try:
+    llm.check(_Wrapper(_Gemma()))
+    check("a generative model passes", True, True)
+except llm.LLMError:
+    check("a generative model passes", False, True)
+
+try:
+    llm.check(None)
+    check("no clip is rejected", False, True)
+except llm.LLMError as exc:
+    check("no clip is rejected", "No CLIP connected" in str(exc), True)
+
+print("\nlanguage names, not codes")
+check("code to name", speech.language_name("ja"), "Japanese")
+check("name to code", speech.language_code("Japanese"), "ja")
+check("auto stays auto", speech.language_code("auto"), "auto")
+check("cantonese has its own code", speech.language_code("Cantonese"), "yue")
+check("unknown code passes through", speech.language_name("xx"), "xx")
+check("empty code gives empty", speech.language_name(""), "")
+check("Speech exposes the full name",
+      speech.Speech([(0, 1, "x")], "ja", 0.9).language_full, "Japanese")
+sp6 = speech.Speech([(0, 1, "x")], "fr", 0.95)
+sh6 = detect.build_shots([], 0.0, 5.0)
+out6 = prompts.sections("o", "NONE", [(sh6[0], [(0.0, 5.0, "x")])], sp6)
+check("assembled audio line spells the language out",
+      "speech in French" in out6["audio"], True)
+check("no bare two-letter code in the output",
+      " in fr " in out6["audio"], False)
+
+print("\nqwen3-vl markers are stripped too")
+check("im_start / im_end removed",
+      llm.tidy("<|im_start|>assistant\nA man walks.<|im_end|>"), "A man walks.")
+check("vision placeholders removed",
+      llm.tidy("<|vision_start|><|image_pad|><|vision_end|>A cat."), "A cat.")
+check("endoftext removed", llm.tidy("Done.<|endoftext|>"), "Done.")
+check("gemma markers still removed",
+      llm.tidy("<|turn>model\n<|channel>final\nText.<turn|>"), "Text.")
+
+print("\nprompt_max_length")
+for level, expected in (("brief", 160), ("normal", 300), ("detailed", 500)):
+    check(f"0 keeps {level} exactly as before",
+          prompts.token_budget(level, 0)["shot"], expected)
+check("0 keeps the overview budget", prompts.token_budget("normal", 0)["overview"], 120)
+check("0 keeps the character budget",
+      prompts.token_budget("normal", 0)["characters"], 200)
+check("negative is treated as 0",
+      prompts.token_budget("normal", -5)["shot"], 300)
+
+big = prompts.token_budget("normal", 800)
+check("an override sets the shot budget", big["shot"], 800)
+check("the overview scales with it", big["overview"], 200)
+check("the character list scales with it", big["characters"], 400)
+small = prompts.token_budget("normal", 100)
+check("a small override never shrinks the setup passes below their floors",
+      (small["overview"], small["characters"]), (120, 200))
+check("but it does set the shot budget", small["shot"], 100)
+
+print("\ntruncation detection")
+check("a finished sentence is not truncated",
+      llm.looks_truncated("A man walks across the snow at sunset."), False)
+check("stopping mid-sentence is truncated",
+      llm.looks_truncated("A man walks across the snow and then he begins to"), True)
+check("a closing quote counts as finished",
+      llm.looks_truncated('He turns and says \"we are nearly there.\"'), False)
+check("short text is never flagged", llm.looks_truncated("Short."), False)
+check("empty is never flagged", llm.looks_truncated(""), False)
+check("None is safe", llm.looks_truncated(None), False)
+
+print("\nbypassed video is skipped, not an error")
+try:
+    import video as vm2
+    check("None means missing", vm2.missing(None), True)
+    check("empty string means missing", vm2.missing(""), True)
+    check("whitespace means missing", vm2.missing("   "), True)
+    check("a real path is not missing", vm2.missing("clip.mp4"), False)
+
+    class _RealVideo:
+        def save_to(self, path): pass
+    class _Junk:
+        pass
+    check("a real VIDEO object is not missing", vm2.missing(_RealVideo()), False)
+
+    # Bypass does not reliably give None -- ComfyUI passes through whatever was
+    # on the bypassed node's inputs, so widget values can land here.
+    check("an int from a widget is missing", vm2.missing(42), True)
+    check("a float is missing", vm2.missing(1.5), True)
+    check("a bool is missing", vm2.missing(False), True)
+    check("a list is missing", vm2.missing(["x"]), True)
+    check("a dict is missing", vm2.missing({"a": 1}), True)
+    check("an object with no file handle is missing", vm2.missing(_Junk()), True)
+
+    # The six outputs a skipped run returns must join cleanly onto a prompt --
+    # any placeholder text would end up inside it.
+    blank = ("", "", "", "", "", "")
+    check("skipped outputs are all empty", all(x == "" for x in blank), True)
+    check("skipped outputs join to nothing", "".join(blank), "")
+except ImportError:
+    print("  skipped (PyAV unavailable)")
+
+print("\nCUDA runtime mixing is refused, not risked")
+check("speech reports torch's cuda major", isinstance(speech.torch_cuda_major(), int), True)
+import inspect as _inspect
+_src = _inspect.getsource(speech.enable_cuda_libraries)
+check("it never touches PATH", "environ" in _src, False)
+check("it never registers torch's lib folder",
+      "torch" in _src.split('\"\"\"')[2], False)
+check("registering twice is a no-op", speech.enable_cuda_libraries(), [])
+
+print("\ntranscription can be turned off")
+check("off returns a note, not an error",
+      speech.transcribe("/nonexistent.wav", "off").note, "transcription turned off")
+check("off never claims speech", speech.transcribe("/x.wav", "off").spoken, False)
+check("off leaves the language empty", speech.transcribe("/x.wav", "off").language, "")
+check("none is treated the same",
+      speech.transcribe("/x.wav", "none").note, "transcription turned off")
+off = speech.transcribe("/x.wav", "off")
+check("transcript output explains itself",
+      prompts.transcript_text(off), "transcription turned off")
+
+print("\nprompts contain nothing a model can copy as content")
+import re as _re
+# A few-shot example in the character prompt was being reproduced verbatim: every
+# video came back with "a tabby cat" in it, whatever was actually on screen. Once
+# a phantom reaches the character list it is asserted as fact in every shot
+# description afterwards, so nothing copyable may live in these prompts.
+for _name in ("OVERVIEW", "SUBJECTS", "SHOT", "GRID_NOTE", "SUBJECTS_KNOWN",
+              "CAMERA_FACT", "CONTINUES"):
+    _p = getattr(prompts, _name)
+    _lines = [l.strip() for l in _p.splitlines() if l.strip()]
+    _suspect = [l for l in _lines
+                if _re.match(r"^(a|an|the)\s+\w+", l, _re.I)
+                and not l.endswith((".", ":", "?"))]
+    check("%s has no bare example line" % _name, _suspect, [])
+
+for _word in ("tabby", "puffer", "beanie", "retriever", "pickup"):
+    check("no '%s' in the character prompt" % _word,
+          _word in prompts.SUBJECTS.lower(), False)
+
+print("\nplaceholder echoes never reach the shot passes")
+check("an unfilled placeholder is dropped",
+      prompts.clean_subjects("<what they are> <the details>"), "")
+check("a placeholder among real entries is dropped",
+      prompts.clean_subjects("a woman in a red dress\n<what they are> <details>"),
+      "a woman in a red dress")
+check("a real subject survives",
+      prompts.clean_subjects("a woman in a leopard-print bodysuit"),
+      "a woman in a leopard-print bodysuit")
+check("an animal that is really there still survives",
+      prompts.clean_subjects("a tabby cat"), "a tabby cat")
+
+print("\nnothing in this pack censors model output")
+# Censorship is handled outside this node. Anything filtered here would be
+# filtered twice, so every transformation that touches model output must be
+# lossless with respect to content -- it may only remove control tokens and
+# formatting artefacts.
+_STRONG = [
+    "A nude woman lies on a bed, her body fully visible in harsh light.",
+    'He screams "get the fuck out of my house" and slams the door.',
+    "Blood sprays across the wall as the knife enters his chest.",
+    "She strips off her underwear and straddles him, breathing hard.",
+    "The severed head rolls into frame, eyes still open.",
+    "Two men fight; one is stabbed repeatedly and bleeds out on the floor.",
+]
+for _text in _STRONG:
+    check("tidy() leaves %r untouched" % (_text[:34] + "..."),
+          llm.tidy(_text), _text)
+
+for _subject in ("a naked man covered in blood",
+                 "a topless woman with a scar across her chest",
+                 "a bleeding man holding a severed arm"):
+    check("clean_subjects() leaves %r untouched" % (_subject[:30] + "..."),
+          prompts.clean_subjects(_subject), _subject)
+
+# Control tokens still go, and only control tokens.
+check("control tokens are still stripped from explicit text",
+      llm.tidy("<|im_start|>assistant\nA nude figure, bleeding.<|im_end|>"),
+      "A nude figure, bleeding.")
+
+print("\nno prompt steers the model toward sanitised output")
+import re as _re2
+_STEER = _re2.compile(
+    r"appropriate|tasteful|family.friendly|suitable for|offend|polite|decent|"
+    r"modest|discreet|refrain|censor|clean up|tone down|avoid describing",
+    _re2.I)
+for _name in ("OVERVIEW", "SUBJECTS", "SHOT", "GRID_NOTE", "SUBJECTS_KNOWN",
+              "CAMERA_FACT", "CONTINUES"):
+    check("%s does not steer the model" % _name,
+          _STEER.findall(getattr(prompts, _name)), [])
+
+print("\nno word list exists anywhere")
+import os as _os
+_src = ""
+for _f in sorted(_os.listdir(_os.path.dirname(_os.path.dirname(_os.path.abspath(__file__))))):
+    if _f.endswith(".py"):
+        with open(_os.path.join(
+                _os.path.dirname(_os.path.dirname(_os.path.abspath(__file__))), _f)) as _fh:
+            _src += _fh.read()
+for _term in ("blocklist", "blacklist", "banned", "profanity", "censor",
+              "redact", "nsfw"):
+    check("the package contains no %s" % _term, _term in _src.lower(), False)
+
+print("\nsilence has to survive an audio encoder")
+# A one-sample waveform passed to MiniMax H3's audio VAE reaches a conv1d with
+# kernel 7 as six timesteps and raises "Kernel size can't be greater than actual
+# input size". Silence must therefore have real length, not merely exist.
+try:
+    import video as vmod
+
+    quiet = vmod.silence(0.0)
+    check("silence is never shorter than the floor",
+          quiet["waveform"].shape[2] >= quiet["sample_rate"], True)
+    check("it is stereo and batched", quiet["waveform"].shape[:2], (1, 2))
+
+    matched = vmod.silence(4.56)
+    check("it matches the clip duration when given one",
+          round(matched["waveform"].shape[2] / matched["sample_rate"], 2), 4.56)
+
+    def survives(audio):
+        """Six halvings, as the H3 audio encoder does, then a kernel of 7."""
+        n = audio["waveform"].shape[2]
+        for _ in range(6):
+            n = (n + 1) // 2
+        return n >= 7
+
+    check("a one-sample waveform would not survive the encoder",
+          survives({"waveform": torch.zeros((1, 2, 1)), "sample_rate": 44100}), False)
+    for _seconds in (0.0, 0.1, 1.0, 4.56, 20.0):
+        check("%.2fs of silence survives the encoder" % _seconds,
+              survives(vmod.silence(_seconds)), True)
+except ImportError:
+    print("  skipped (PyAV unavailable)")
+
+print("\ntruncation is only reported when the budget was the limit")
+_fragment = "A woman in a leopard print bodysuit dances against a wall and then she"
+check("a short fragment is not blamed on a large budget",
+      llm.looks_truncated(_fragment, 1600), False)
+check("but it is flagged against a budget it could have filled",
+      llm.looks_truncated(_fragment, 20), True)
+check("a reply that really filled the budget is flagged",
+      llm.looks_truncated("word " * 1200, 1600), True)
+check("a finished sentence is never flagged",
+      llm.looks_truncated("She turns and walks away.", 20), False)
+check("with no budget given, the old behaviour holds",
+      llm.looks_truncated(_fragment), True)
+
+print("\nspeech helpers")
+check("during() overlaps, not just contains",
+      len(sp.during(1.5, 3.0)), 1)
+check("during() excludes non-overlapping", len(sp.during(3.0, 8.0)), 0)
+check("spoken flag", (sp.spoken, silent.spoken), (True, False))
+
+print("\nend to end on a generated clip (PyAV)")
+try:
+    import numpy as np
+    import av
+    import tempfile
+    import video as video_mod
+
+    path = os.path.join(tempfile.gettempdir(), "videoautotranscribe_selftest.mp4")
+    truth = [2.0, 4.5]
+    plan = [(2.0, (20, 40, 160)), (2.5, (210, 190, 80)), (2.5, (30, 140, 70))]
+
+    out = av.open(path, "w")
+    st = out.add_stream("libx264", rate=24)
+    st.width, st.height, st.pix_fmt = 320, 240, "yuv420p"
+    st.options = {"crf": "18"}
+    for seconds, colour in plan:
+        rng = np.random.default_rng(len(colour) + colour[0])
+        tex = rng.integers(0, 50, (240, 320, 3), dtype=np.uint8)
+        for i in range(int(seconds * 24)):
+            arr = np.clip(np.roll(tex, (i * 5) % 320, axis=1).astype(np.int16)
+                          + np.array(colour, np.int16), 0, 255).astype(np.uint8)
+            out.mux(st.encode(av.VideoFrame.from_ndarray(arr, format="rgb24")))
+    out.mux(st.encode(None))
+    out.close()
+
+    clip = video_mod.open_clip(path)
+    check("duration read", round(clip.duration, 1), 7.0)
+    scores = video_mod.scene_scores(clip)
+    check("frames scored", len(scores) > 50, True)
+
+    found = detect.find_cuts(scores, "normal", 1.0, 0.0, clip.duration)
+    hits = sum(1 for t in truth if any(abs(g - t) < 0.2 for g in found))
+    check("both planted cuts found (%s)" % [round(f, 2) for f in found],
+          (hits, len(found)), (2, 2))
+
+    frames = video_mod.frames_at(clip, [0.5, 3.0, 6.0], width=128)
+    check("frames returned in order", [round(t, 1) for t, _ in frames], [0.5, 3.0, 6.0])
+    check("frames are resized", frames[0][1].size[0], 128)
+    check("no audio track detected", clip.has_audio, False)
+    check("silent clip transcribes to a note",
+          speech.transcribe(None).note, "no audio track")
+    os.remove(path)
+except ImportError as exc:
+    print("  skipped (PyAV/numpy unavailable: %s)" % exc)
+
+print("\n%s" % ("ALL PASSED" if not FAILED else "%d FAILED: %s" % (len(FAILED), FAILED)))
+sys.exit(1 if FAILED else 0)

custom_nodes/ComfyUI-Nugget/video.py

@@ -0,0 +1,648 @@
+"""Reading the video with PyAV.
+
+PyAV ships with ComfyUI's own video support, so if ``LoadVideo`` works in a graph
+this module works. No ffmpeg binary is required and none is looked for.
+
+Scene scoring compares colour histograms of tiny thumbnails rather than the
+pixels themselves. That choice is deliberate: a mean pixel difference reacts
+strongly to camera movement, so a crane or a whip pan scores like a cut. A
+histogram barely moves when the camera pans across a scene, but changes sharply
+when the scene itself is replaced. Measured on real footage, switching from
+pixel difference to histogram difference widened the gap between the weakest
+true cut and the strongest false positive from 1.5x to 2.4x.
+
+A cut is a global change, so 64x64 is plenty to see one and keeps a 20-second
+clip under two seconds of decode.
+"""
+from __future__ import annotations
+
+import logging
+import math
+import os
+import tempfile
+import wave
+from dataclasses import dataclass
+
+import numpy as np
+
+try:
+    from . import camera, interrupt
+except ImportError:  # direct import for tests
+    import camera
+    import interrupt
+
+log = logging.getLogger("Nugget")
+
+# Thumbnail edge used for scene scoring. Bigger buys nothing: a cut changes the
+# whole frame, and small thumbnails suppress the per-pixel noise that makes
+# handheld footage look like a cut.
+THUMB = 64
+
+# Frames scored per second. A hard cut lands between two adjacent decoded
+# frames, so this is the resolution of the reported cut time. 12 is a good
+# trade: 80ms accuracy, and a 20s clip is 240 thumbnails.
+SCORE_FPS = 12.0
+
+
+class NoSource(RuntimeError):
+    """There is nothing on the video input that names a file.
+
+    Kept apart from VideoError because the two mean opposite things. A
+    VideoError is a real file that will not decode and the user needs to know.
+    This is the branch being switched off, which is not a fault and must not
+    stop the run.
+    """
+
+
+class VideoError(RuntimeError):
+    pass
+
+
+def _av():
+    try:
+        import av
+    except ImportError as exc:  # pragma: no cover - environment dependent
+        raise VideoError(
+            "PyAV is not available. It normally ships with ComfyUI's video "
+            "support -- if LoadVideo works in your graph, this should too."
+        ) from exc
+    return av
+
+
+@dataclass
+class Clip:
+    path: str
+    duration: float
+    fps: float
+    declared_fps: float
+    width: int
+    height: int
+    has_audio: bool
+    temporary: bool = False
+
+    @property
+    def variable_fps(self) -> bool:
+        """Is the container lying about the frame rate?
+
+        Phone video, screen recordings and a lot of AI output are variable frame
+        rate. It does not stop anything here working -- every time is read from
+        the packet's own PTS -- but it is worth surfacing, because a clip tagged
+        60fps that actually runs at 22 will confuse anything downstream that
+        trusts the tag.
+        """
+        if not self.declared_fps or not self.fps:
+            return False
+        return abs(self.declared_fps - self.fps) / max(self.fps, 1e-6) > 0.05
+
+
+def _existing(path) -> str:
+    """The string as a path on disk, or empty if it is not one.
+
+    Bypass hands the downstream node whatever was on the bypassed node's
+    inputs, and for Load Video that is its widget value -- a bare filename such
+    as "clip.mp4". It is deliberately not resolved against ComfyUI's input
+    folder: the only way a bare name arrives here is a bypassed loader, and
+    resolving it would make bypass quietly transcribe the file the user just
+    switched off.
+    """
+    text = (path or "").strip() if isinstance(path, str) else ""
+    return text if text and os.path.exists(text) else ""
+
+
+def missing(video) -> bool:
+    """Is there no video to work on?
+
+    A bypassed Load Video node still connects, but its VIDEO output becomes
+    None -- bypass passes through inputs of a matching type, and Load Video has
+    no VIDEO input to pass through. So None here means "the user switched this
+    branch off", not "the graph is broken", and it should be treated as a
+    request to do nothing rather than as an error.
+    """
+    if video is None:
+        return True
+    if isinstance(video, str):
+        return not _existing(video)
+    # Bypass does not always yield None. ComfyUI passes through a reference to
+    # whatever was on the bypassed node's inputs, so a widget value can arrive
+    # here in place of a video -- a filename, a number, a tensor. Anything that
+    # cannot name a file on disk is treated as "nothing to do" rather than as an
+    # error, because it means the user switched the branch off.
+    if isinstance(video, (int, float, bool)):
+        return True
+    if isinstance(video, (list, tuple, dict, set)):
+        return True
+    usable = ("save_to", "_VideoFromFile__file", "_file", "file", "path",
+              "filename", "get_stream_source", "get_components")
+    return not any(hasattr(video, name) for name in usable)
+
+
+def _source_path(video) -> tuple[str, bool]:
+    """A path on disk for whatever ComfyUI handed us.
+
+    ComfyUI's VIDEO objects have exposed the underlying file under several
+    attribute names across versions, so try the known ones before falling back
+    to saving a copy.
+    """
+    if isinstance(video, str):
+        found = _existing(video)
+        if not found:
+            raise NoSource(f"there is no file at {video!r}")
+        return found, False
+    for attr in ("_VideoFromFile__file", "_file", "file", "path", "filename"):
+        value = getattr(video, attr, None)
+        if isinstance(value, str) and os.path.exists(value):
+            return value, False
+    save = getattr(video, "save_to", None)
+    if callable(save):
+        handle, path = tempfile.mkstemp(suffix=".mp4", prefix="videoautotranscribe_")
+        os.close(handle)
+        save(path)
+        return path, True
+    raise NoSource(
+        "nothing on the video input names a file on disk. Connect a Load "
+        "Video node to the `video` input."
+    )
+
+
+def measured_duration(path: str) -> float:
+    """The real end of the video, read from the stream rather than the header.
+
+    Some containers simply do not carry a duration: fragmented and faststart-less
+    MP4, a lot of WebM/Matroska, MPEG-TS, anything still being written, and most
+    of what image and video generators emit. ``container.duration`` is None,
+    ``stream.duration`` is None, and every arithmetic that follows silently uses
+    zero -- which is how a clip ends up reported as one shot running from
+    00:00.000 to 00:00.000.
+
+    Demuxing is used rather than decoding: packets carry the timestamps and cost
+    a fraction of a decode. PTS is not monotonic when there are B-frames, so the
+    maximum is taken rather than the last value seen. Decoding is the fallback,
+    for the rare container whose packets have no PTS at all.
+    """
+    av = _av()
+    container = av.open(path)
+    try:
+        stream = container.streams.video[0]
+        base = stream.time_base
+        last = 0.0
+        for packet in container.demux(stream):
+            if packet.pts is None:
+                continue
+            scale = packet.time_base or base
+            if scale is None:
+                continue
+            end = float(packet.pts * scale)
+            if packet.duration:
+                end += float(packet.duration * scale)
+            last = max(last, end)
+        if last > 0:
+            return last
+    except Exception as exc:
+        log.debug("[Nugget] could not demux for duration: %s", exc)
+    finally:
+        container.close()
+
+    # No usable packet timestamps. Decode and take the last frame's own time,
+    # plus one frame so the final frame is inside the clip rather than on its
+    # boundary.
+    container = av.open(path)
+    try:
+        stream = container.streams.video[0]
+        stream.thread_type = "AUTO"
+        last = 0.0
+        count = 0
+        for frame in container.decode(stream):
+            count += 1
+            if frame.pts is not None and stream.time_base:
+                last = max(last, float(frame.pts * stream.time_base))
+        if last > 0:
+            rate = float(stream.average_rate or 0) or float(stream.base_rate or 0)
+            return last + (1.0 / rate if rate else 0.0)
+        if count:
+            rate = float(stream.average_rate or 0) or float(stream.base_rate or 0)
+            if rate:
+                return count / rate
+        return 0.0
+    except Exception as exc:
+        log.debug("[Nugget] could not decode for duration: %s", exc)
+        return 0.0
+    finally:
+        container.close()
+
+
+def open_clip(video) -> Clip:
+    av = _av()
+    path, temporary = _source_path(video)
+    try:
+        container = av.open(path)
+    except Exception as exc:
+        raise VideoError(
+            f"Could not open the video: {exc}. If this is HEVC or AV1, your "
+            f"PyAV build may not include that decoder."
+        ) from exc
+    try:
+        streams = container.streams
+        if not streams.video:
+            raise VideoError("That file has no video stream.")
+        stream = streams.video[0]
+        declared = float(stream.average_rate or 0) or float(stream.base_rate or 0)
+        duration = 0.0
+        if container.duration:
+            duration = float(container.duration) / av.time_base
+        elif stream.duration and stream.time_base:
+            duration = float(stream.duration * stream.time_base)
+        frames = int(stream.frames or 0)
+        # Third fallback: the frame count and the declared rate. Free when the
+        # container bothered to record a frame count, and right for CFR.
+        if duration <= 0 and frames and declared:
+            duration = frames / declared
+        # Read everything else off the streams while the container is still
+        # open; the measuring pass below reopens the file and this one is gone.
+        width = int(stream.codec_context.width or 0)
+        height = int(stream.codec_context.height or 0)
+        has_audio = bool(streams.audio)
+    finally:
+        container.close()
+
+    # Last resort: read the timestamps out of the stream itself. This is the
+    # branch that stops a header with no duration turning into a shot that runs
+    # from 00:00.000 to 00:00.000 -- every cut time, beat and frame sample is
+    # derived from this number, so zero here makes the whole run meaningless
+    # while still appearing to succeed.
+    if duration <= 0:
+        duration = measured_duration(path)
+        if duration > 0:
+            log.info("[Nugget] the container declares no duration; measured "
+                     "%.2fs from the stream itself", duration)
+
+    if duration <= 0:
+        raise VideoError(
+            "That file declares no duration and none could be measured from "
+            "it, so there are no timestamps to describe against. Re-encode it "
+            "(any ordinary MP4 export will do) and try again.")
+
+    real = (frames / duration) if (frames and duration) else declared
+    return Clip(
+        path=path,
+        duration=duration,
+        fps=real or declared or 24.0,
+        declared_fps=declared,
+        width=width,
+        height=height,
+        has_audio=has_audio,
+        temporary=temporary,
+    )
+
+
+def scene_scores(clip: Clip, progress=None) -> list[tuple[float, float]]:
+    """Just the cut scores. See ``scan`` -- this drops the motion track."""
+    return scan(clip, progress)[0]
+
+
+def scan(clip: Clip, progress=None):
+    """One decode pass, two results: ``(scores, motion)``.
+
+    ``scores`` is [(time, score), ...] for cut detection. ``motion`` is
+    [(time, dx, dy, zoom), ...] for camera movement. Both come out of the same
+    walk through the file, because decoding twice to compute two things about
+    the same frames is a waste of the slowest part of the run.
+
+    The score is the total variation distance between consecutive frames' colour
+    histograms -- 32 luma bins plus 16 per RGB channel, normalised, halved so the
+    result runs 0..1. See the module docstring for why histograms rather than
+    pixel differences.
+    """
+    av = _av()
+    container = av.open(clip.path)
+    try:
+        stream = container.streams.video[0]
+        stream.thread_type = "AUTO"
+        scores: list[tuple[float, float]] = []
+        motion: list[tuple[float, float, float, float]] = []
+        previous = None
+        previous_grey = None
+        next_wanted = 0.0
+        gap = 1.0 / SCORE_FPS
+        weights = np.array([0.299, 0.587, 0.114], dtype=np.float32)
+        for frame in container.decode(stream):
+            if frame.pts is None:
+                continue
+            when = float(frame.pts * stream.time_base)
+            if when + 1e-6 < next_wanted:
+                continue
+            next_wanted = when + gap
+            small = frame.reformat(width=THUMB, height=THUMB, format="rgb24")
+            rgb = small.to_ndarray().astype(np.float32) / 255.0
+            parts = [np.histogram(rgb @ weights, bins=32, range=(0.0, 1.0))[0]]
+            for channel in range(3):
+                parts.append(np.histogram(rgb[:, :, channel], bins=16,
+                                          range=(0.0, 1.0))[0])
+            current = np.concatenate(parts).astype(np.float32)
+            total = current.sum()
+            if total > 0:
+                current /= total
+            if previous is not None:
+                scores.append((when, float(np.abs(current - previous).sum() / 2.0)))
+            # Camera movement, from a larger greyscale copy of the same frame.
+            flat = frame.reformat(width=camera.SIZE, height=camera.SIZE,
+                                  format="gray").to_ndarray().astype(np.float64) / 255.0
+            if previous_grey is not None:
+                dx, dy, dz = camera.step(previous_grey, flat)
+                motion.append((when, dx, dy, dz))
+            previous, previous_grey = current, flat
+            if len(scores) % 40 == 0:
+                interrupt.check()
+                if progress and clip.duration:
+                    progress(f"scanning {when / clip.duration * 100:.0f}%")
+        return scores, motion
+    finally:
+        container.close()
+
+
+def frames_at(clip: Clip, times: list[float], width: int = 512):
+    """PIL images at the requested times, in order.
+
+    One sequential decode rather than a seek per frame. Seeking lands on the
+    nearest keyframe, and on a clip with keyframes 5 seconds apart that means
+    the frame you get is not the frame you asked for.
+
+    ``width`` is a ceiling, never a target. Asking for 768 from a 640-wide source
+    gives 640, because upscaling invents no detail while costing real vision
+    tokens and real time -- the model would pay for 768 pixels of a 640-pixel
+    picture.
+    """
+    from PIL import Image
+    av = _av()
+    wanted = sorted(set(round(max(0.0, t), 3) for t in times))
+    if not wanted:
+        return []
+    container = av.open(clip.path)
+    try:
+        stream = container.streams.video[0]
+        stream.thread_type = "AUTO"
+        # Never exceed the source. See the docstring.
+        if clip.width:
+            width = min(int(width), int(clip.width))
+        width = max(2, int(width) - int(width) % 2)
+        height = 0
+        if clip.width and clip.height:
+            height = max(2, int(round(width * clip.height / clip.width)))
+            height -= height % 2
+        out: list[tuple[float, Image.Image]] = []
+        cursor = 0
+        previous = None
+        seen = 0
+        for frame in container.decode(stream):
+            seen += 1
+            if seen % 120 == 0:
+                interrupt.check()
+            if frame.pts is None:
+                continue
+            when = float(frame.pts * stream.time_base)
+            while cursor < len(wanted) and when >= wanted[cursor]:
+                # Whichever of this frame and the last is nearer the target.
+                pick = frame
+                if previous is not None:
+                    if abs(previous[0] - wanted[cursor]) < abs(when - wanted[cursor]):
+                        pick = previous[1]
+                small = pick.reformat(width=width, height=height or None,
+                                      format="rgb24")
+                out.append((wanted[cursor], Image.fromarray(small.to_ndarray())))
+                cursor += 1
+            if cursor >= len(wanted):
+                break
+            previous = (when, frame)
+        # Anything past the last decodable frame gets that frame.
+        while cursor < len(wanted) and previous is not None:
+            small = previous[1].reformat(width=width, height=height or None,
+                                         format="rgb24")
+            out.append((wanted[cursor], Image.fromarray(small.to_ndarray())))
+            cursor += 1
+        return out
+    finally:
+        container.close()
+
+
+def to_grid(images, width: int, columns: int = 0):
+    """Composite frames into one image, read left to right then top to bottom.
+
+    This trades spatial detail for temporal resolution, and for describing motion
+    that is the right trade. Showing six frames as one grid costs roughly what
+    one image costs, so a long shot can be covered densely instead of sampled
+    thinly -- and the model sees the progression laid out at once rather than as
+    a sequence it has to hold in mind.
+
+    The approach is from IG-VLM (arXiv 2403.18406), which found image-pretrained
+    VLMs read grids zero-shot with no video training, and Video Panels (arXiv
+    2509.23724), which confirmed it across five benchmarks and several model
+    families. Both note the layout should be near-square, so the panels stay as
+    large as possible.
+    """
+    from PIL import Image
+    if not images:
+        return []
+    if len(images) == 1:
+        return list(images)
+    count = len(images)
+    if columns <= 0:
+        columns = int(math.ceil(math.sqrt(count)))
+    rows = int(math.ceil(count / columns))
+    # The grid is capped by the frames it is built from as well as by `width`:
+    # blowing a 320-wide frame up to fill a 1024 grid cell adds nothing.
+    width = min(int(width), images[0].width * columns)
+    cell_w = max(2, int(width) // columns)
+    aspect = images[0].height / max(1, images[0].width)
+    cell_h = max(2, int(cell_w * aspect))
+    sheet = Image.new("RGB", (cell_w * columns, cell_h * rows), (0, 0, 0))
+    for index, image in enumerate(images):
+        sheet.paste(image.resize((cell_w, cell_h), Image.LANCZOS),
+                    ((index % columns) * cell_w, (index // columns) * cell_h))
+    return [sheet]
+
+
+# A full-resolution frame tensor is float32, so a minute of 1080p is tens of
+# gigabytes. Refuse past this rather than filling RAM and dying without a
+# message -- the caller can lower the resolution or shorten the clip.
+MAX_FRAME_BYTES = 6 * 1024 ** 3
+
+# Some containers -- WebM/VP9 is the notorious one -- report the timebase
+# precision as the frame rate. A 1ms-tick WebM comes out of PyAV with
+# base_rate == 1000, and average_rate == 0/0 when the total frame count is
+# unknown, so open_clip falls back to base_rate and clip.fps ends up at 1000.
+# The RAM estimate then multiplies duration * 1000 and refuses a plainly
+# innocent clip. Cap the fps we use for the sanity check at a value no real
+# footage exceeds for any meaningful duration (240 covers slo-mo cameras and
+# then some). Decoding itself does not use fps -- frames come one at a time
+# regardless -- so this only affects the estimate. The returned fps is
+# corrected below from the actual decoded frame count.
+FPS_CAP_FOR_ESTIMATE = 240.0
+
+
+def decode_all(clip: Clip):
+    """Every frame as a ``(B, H, W, C)`` float tensor, plus the real fps.
+
+    This is what feeds the node's ``images`` and ``frame_count`` outputs, so it
+    replaces a separate Get Video Components in the graph. Timestamps come from
+    each frame's own PTS, so a variable frame rate does not shift anything.
+    """
+    import torch
+    av = _av()
+    estimate = 0
+    if clip.width and clip.height and clip.duration and clip.fps:
+        fps_estimate = min(float(clip.fps), FPS_CAP_FOR_ESTIMATE)
+        estimate = int(clip.width * clip.height * 3 * 4
+                       * clip.duration * fps_estimate)
+    if estimate > MAX_FRAME_BYTES:
+        raise VideoError(
+            f"That clip would need about {estimate / 1024 ** 3:.0f} GB of RAM "
+            f"as raw frames ({clip.width}x{clip.height}, {clip.duration:.0f}s "
+            f"at up to {int(fps_estimate)} fps). Shorten it or scale it down "
+            f"first.")
+    container = av.open(clip.path)
+    try:
+        stream = container.streams.video[0]
+        stream.thread_type = "AUTO"
+        frames = []
+        count = 0
+        for frame in container.decode(stream):
+            count += 1
+            if count % 120 == 0:
+                interrupt.check()
+            rgb = frame.reformat(format="rgb24").to_ndarray()
+            frames.append(torch.from_numpy(rgb.astype(np.float32) / 255.0))
+        if not frames:
+            raise VideoError("No frames could be decoded from that video.")
+        # Once decoding is done, the actual count and the duration are the
+        # last word on the real fps -- more reliable than either metadata
+        # field, and the fix for the "declared fps is really the container
+        # tick rate" case described above the constants. Only trust it if
+        # both numbers are usable; otherwise fall through to the metadata.
+        real_fps = float(clip.fps or 24.0)
+        if clip.duration and count:
+            measured_fps = count / float(clip.duration)
+            if 0.5 < measured_fps < FPS_CAP_FOR_ESTIMATE:
+                real_fps = measured_fps
+        return torch.stack(frames, dim=0), real_fps, count
+    finally:
+        container.close()
+
+
+# Silence has to be long enough to survive an audio encoder, not merely
+# non-empty. H3's audio VAE downsamples hard and then runs a conv1d with a
+# kernel of 7; a one-sample waveform reaches that layer as 6 timesteps and
+# raises "Kernel size can't be greater than actual input size". Anything under
+# about a second risks the same thing in some encoder, so silence is generated
+# at the clip's own length with a floor.
+SILENCE_FLOOR = 1.0      # seconds
+
+
+def silence(seconds: float = 0.0, rate: int = 44100):
+    """A silent stereo waveform in ComfyUI's AUDIO shape."""
+    import torch
+    length = max(int(rate * max(seconds, SILENCE_FLOOR)), int(rate))
+    return {"waveform": torch.zeros((1, 2, length)), "sample_rate": int(rate)}
+
+
+def audio_tensor(clip: Clip):
+    """The soundtrack in ComfyUI's AUDIO shape, or silence if there is none.
+
+    ComfyUI expects ``{"waveform": (batch, channels, samples), "sample_rate":
+    int}``. Silence rather than None keeps a downstream node working on a clip
+    with no audio track -- and it matches the clip's duration, so anything that
+    lines audio up against video still lines up.
+    """
+    av = _av()
+    if not clip.has_audio:
+        log.info("[Nugget] no audio track; returning %.2fs of silence",
+                 max(clip.duration, SILENCE_FLOOR))
+        return silence(clip.duration)
+    container = av.open(clip.path)
+    try:
+        if not container.streams.audio:
+            return silence(clip.duration)
+        stream = container.streams.audio[0]
+        rate = int(stream.rate or 44100)
+        resampler = av.audio.resampler.AudioResampler(
+            format="fltp", layout="stereo", rate=rate)
+        chunks = []
+        for frame in container.decode(stream):
+            for resampled in resampler.resample(frame):
+                chunks.append(resampled.to_ndarray())
+        for resampled in resampler.resample(None):
+            chunks.append(resampled.to_ndarray())
+        if not chunks:
+            return silence(clip.duration, rate)
+        import torch
+        data = np.concatenate(chunks, axis=1).astype(np.float32)
+        # A track that exists but is unusably short would fail the same way a
+        # missing one does, so pad it rather than hand on something too small.
+        if data.shape[1] < int(rate * SILENCE_FLOOR):
+            pad = np.zeros((data.shape[0], int(rate * SILENCE_FLOOR) - data.shape[1]),
+                           dtype=np.float32)
+            data = np.concatenate((data, pad), axis=1)
+        return {"waveform": torch.from_numpy(data).unsqueeze(0),
+                "sample_rate": rate}
+    except Exception as exc:
+        log.warning("[Nugget] could not read the audio track: %s", exc)
+        return silence(clip.duration)
+    finally:
+        container.close()
+
+
+def extract_audio(clip: Clip) -> str | None:
+    """16 kHz mono WAV for the speech model, or None if there is no audio.
+
+    16 kHz mono is what Whisper resamples to internally anyway, so doing it here
+    costs nothing and keeps the temporary file small.
+    """
+    if not clip.has_audio:
+        return None
+    av = _av()
+    container = av.open(clip.path)
+    try:
+        if not container.streams.audio:
+            return None
+        stream = container.streams.audio[0]
+        resampler = av.audio.resampler.AudioResampler(
+            format="s16", layout="mono", rate=16000)
+        chunks = []
+        for frame in container.decode(stream):
+            for resampled in resampler.resample(frame):
+                chunks.append(resampled.to_ndarray().reshape(-1))
+        for resampled in resampler.resample(None):  # flush
+            chunks.append(resampled.to_ndarray().reshape(-1))
+        if not chunks:
+            return None
+        samples = np.concatenate(chunks).astype(np.int16)
+        handle, path = tempfile.mkstemp(suffix=".wav", prefix="videoautotranscribe_")
+        os.close(handle)
+        # If anything from here to `return path` raises, the temp file is
+        # already on disk and will leak. Clean it up on any failure.
+        try:
+            with wave.open(path, "wb") as out:
+                out.setnchannels(1)
+                out.setsampwidth(2)
+                out.setframerate(16000)
+                out.writeframes(samples.tobytes())
+        except Exception:
+            try:
+                os.remove(path)
+            except OSError:
+                pass
+            raise
+        return path
+    except Exception as exc:
+        log.warning("[Nugget] could not extract audio: %s", exc)
+        return None
+    finally:
+        container.close()
+
+
+def cleanup(*paths) -> None:
+    for path in paths:
+        if not path:
+            continue
+        try:
+            os.remove(path)
+        except OSError:
+            pass

custom_nodes/ComfyUI-Nugget/web/js/nugget_batch_nocrop.js

@@ -0,0 +1,150 @@
+import { app } from "../../scripts/app.js";
+
+// Auto-expanding, self-compacting image sockets. No inputcount widget.
+//
+// Applies to every Nugget node with image_1..image_N inputs. Nothing here cares
+// where those sockets sit in the input list, so a node with a clip and a prompt
+// ahead of them works the same as one that starts with image_1.
+//
+// Two rules:
+//   1. Compact - connected images always occupy image_1..image_N with no holes.
+//      Disconnect image_2 of three and image_3's link slides down into image_2.
+//      This keeps the socket numbers lined up with <Picture N> in the H3 prompt,
+//      and guarantees image_1 (a required input) is never the empty one.
+//   2. Grow - keep exactly one empty trailing socket, up to image_9.
+//
+// Compaction relinks, so it must run against the live graph link table.
+
+const MAX_INPUTS = 9;
+const PREFIX = "image_";
+
+// Widget-backed inputs render in the widget area rather than as sockets, so a
+// socket appended to the end of the input list still appears in the right place
+// on the canvas.
+const NODES = new Set(["ImageBatchMultiNoCrop", "NuggetGeneratePrompt"]);
+
+function slotIndex(name) {
+    const m = new RegExp(`^${PREFIX}(\\d+)$`).exec(name || "");
+    return m ? parseInt(m[1], 10) : null;
+}
+
+/** Image sockets, ascending by slot number, with their real input index. */
+function imageSockets(node) {
+    return (node.inputs || [])
+        .map((inp, idx) => ({ inp, idx, i: slotIndex(inp.name) }))
+        .filter((o) => o.i !== null)
+        .sort((a, b) => a.i - b.i);
+}
+
+/**
+ * Slide every connection down so they are contiguous from image_1.
+ * Returns true if anything moved.
+ */
+function compact(node, graph) {
+    const sockets = imageSockets(node);
+
+    // Capture the origin of each live link, in slot order.
+    const origins = [];
+    let needsCompacting = false;
+    let expected = 1;
+
+    for (const { inp, i } of sockets) {
+        if (inp.link == null) continue;
+        const link = graph.links?.[inp.link];
+        if (!link) continue;
+        origins.push({ id: link.origin_id, slot: link.origin_slot });
+        if (i !== expected) needsCompacting = true;
+        expected++;
+    }
+
+    if (!needsCompacting || origins.length === 0) return false;
+
+    // Drop every image link, then lay them back down from image_1 up.
+    for (const { idx } of sockets) {
+        if (node.inputs[idx]?.link != null) node.disconnectInput(idx);
+    }
+
+    for (let k = 0; k < origins.length; k++) {
+        const name = `${PREFIX}${k + 1}`;
+        if (!node.inputs.some((inp) => inp.name === name)) {
+            node.addInput(name, "IMAGE", { shape: 7 });
+        }
+        const targetIdx = node.inputs.findIndex((inp) => inp.name === name);
+        const originNode = graph.getNodeById?.(origins[k].id);
+        if (originNode && targetIdx >= 0) {
+            originNode.connect(origins[k].slot, node, targetIdx);
+        }
+    }
+    return true;
+}
+
+/** Add/remove trailing sockets so exactly one spare follows the last link. */
+function resize(node) {
+    let highestConnected = 0;
+    for (const { inp, i } of imageSockets(node)) {
+        if (inp.link != null) highestConnected = Math.max(highestConnected, i);
+    }
+    const wanted = Math.min(highestConnected + 1, MAX_INPUTS);
+
+    for (let i = 2; i <= wanted; i++) {
+        if (!node.inputs.some((inp) => inp.name === `${PREFIX}${i}`)) {
+            node.addInput(`${PREFIX}${i}`, "IMAGE", { shape: 7 });
+        }
+    }
+
+    // Highest index first so splicing does not shift the ones still to remove.
+    const doomed = imageSockets(node)
+        .filter(({ inp, i }) => i > wanted && inp.link == null)
+        .sort((a, b) => b.idx - a.idx);
+
+    for (const { idx } of doomed) node.removeInput(idx);
+    return doomed.length > 0;
+}
+
+function sync(node) {
+    if (node._nuggetSyncing) return;
+    const graph = node.graph || app.graph;
+    if (!graph || !node.inputs) return;
+
+    node._nuggetSyncing = true;
+    try {
+        const moved = compact(node, graph);
+        const resized = resize(node);
+        if (moved || resized) {
+            node.setSize(node.computeSize());
+            graph.setDirtyCanvas?.(true, true);
+        }
+    } finally {
+        node._nuggetSyncing = false;
+    }
+}
+
+app.registerExtension({
+    name: "nugget.autoexpand.images",
+    async beforeRegisterNodeDef(nodeType, nodeData) {
+        if (!NODES.has(nodeData.name)) return;
+
+        const onNodeCreated = nodeType.prototype.onNodeCreated;
+        nodeType.prototype.onNodeCreated = function () {
+            const r = onNodeCreated?.apply(this, arguments);
+            requestAnimationFrame(() => sync(this));
+            return r;
+        };
+
+        // Fires on every link made or broken. The link table is not settled
+        // until after the handler returns, hence the deferral.
+        const onConnectionsChange = nodeType.prototype.onConnectionsChange;
+        nodeType.prototype.onConnectionsChange = function () {
+            const r = onConnectionsChange?.apply(this, arguments);
+            requestAnimationFrame(() => sync(this));
+            return r;
+        };
+
+        const onConfigure = nodeType.prototype.onConfigure;
+        nodeType.prototype.onConfigure = function () {
+            const r = onConfigure?.apply(this, arguments);
+            requestAnimationFrame(() => sync(this));
+            return r;
+        };
+    },
+});

custom_nodes/ComfyUI-Nugget/web/js/nugget_transcribe_ui.js

@@ -0,0 +1,240 @@
+import { app } from "../../scripts/app.js";
+
+// Compact / everything view for Video Auto Transcriber.
+//
+// The show widget on the Python side is decoration only. Everything the user
+// actually sees change lives here: two widgets and five output sockets get
+// hidden when show is "compact", and re-appear when it flips to "everything".
+//
+// Widget hiding is easy -- swap the type to "hidden" and shrink computeSize
+// to nothing. LiteGraph respects both.
+//
+// Output hiding is not. LiteGraph draws every slot in node.outputs, so a
+// `hidden` flag on the slot object is not enough on its own -- the socket
+// still shows. The reliable way is to actually remove the slot and put it
+// back later. That means preserving any connections across the round trip:
+// when we hide, we record where each link went; when we restore, we re-add
+// the output and reconnect it. Anything the user did while it was hidden
+// (impossible in the UI, since the socket wasn't there) can't stomp on it.
+//
+// The user's answer to "which outputs matter to me" is expressed by what they
+// actually connected. So we make one concession: an output with a live link
+// stays visible even in compact mode. If it was worth wiring up, it's worth
+// keeping on screen. Only unconnected hideable outputs disappear.
+
+const NODE = "VideoAutoTranscribe";
+const SHOW_WIDGET = "show";
+
+// Widgets to hide in compact view. Names match the Python schema.
+const COMPACT_HIDE_WIDGETS = ["mode", "max_frame_size", "frame_layout"];
+
+// Outputs to hide in compact view. Names match the display_name in the
+// Python schema. Match by display_name, then by name, then by
+// localized_name -- ComfyUI has used all three keys at various points and
+// the schema's display_name may land in any of them depending on version.
+const COMPACT_HIDE_OUTPUTS = [
+    "overview",
+    "characters identified",
+    "shots",
+    "audio transcription",
+    "audio language",
+];
+
+// --- widget helpers ----------------------------------------------------
+
+function findWidget(node, name) {
+    return (node.widgets || []).find((w) => w.name === name);
+}
+
+function hideWidget(w) {
+    if (w._nugHidden) return;
+    w._nugHidden = true;
+    w._nugOrigType = w.type;
+    w._nugOrigCompute = w.computeSize;
+    w.type = "hidden";
+    // -4 exactly cancels the widget spacer LiteGraph inserts between rows,
+    // so a hidden widget leaves no gap behind on the node.
+    w.computeSize = () => [0, -4];
+}
+
+function showWidget(w) {
+    if (!w._nugHidden) return;
+    w._nugHidden = false;
+    w.type = w._nugOrigType;
+    w.computeSize = w._nugOrigCompute;
+    delete w._nugOrigType;
+    delete w._nugOrigCompute;
+}
+
+// --- output helpers ----------------------------------------------------
+
+function outputMatches(output, name) {
+    if (!output) return false;
+    return output.name === name
+        || output.localized_name === name
+        || output.label === name;
+}
+
+function outputHasLinks(output) {
+    return Array.isArray(output?.links) && output.links.length > 0;
+}
+
+/**
+ * Remember an output's spec and its live links, then remove it from the node.
+ * The stash is keyed by the display name, which is what we match against when
+ * restoring.
+ */
+function stashOutput(node, name) {
+    const idx = (node.outputs || []).findIndex((o) => outputMatches(o, name));
+    if (idx < 0) return false;
+
+    const output = node.outputs[idx];
+
+    // Skip outputs the user has actually wired up. Removing them would
+    // silently disconnect their downstream node, which is worse than
+    // leaving a socket visible in compact mode.
+    if (outputHasLinks(output)) return false;
+
+    node._nugStashed = node._nugStashed || {};
+    if (node._nugStashed[name]) return false; // already stashed
+
+    node._nugStashed[name] = {
+        // Keep every field ComfyUI might read on the way back.
+        spec: {
+            name: output.name,
+            type: output.type,
+            localized_name: output.localized_name,
+            label: output.label,
+        },
+        // Where this output sat before, so restore can put it back in the
+        // same visual slot rather than pushing it to the bottom.
+        origIndex: idx,
+    };
+    node.removeOutput(idx);
+    return true;
+}
+
+/**
+ * Put a stashed output back on the node. LiteGraph only supports appending,
+ * so if the output belongs earlier in the list we splice it into place after
+ * calling addOutput, then patch node.outputs to match the intended order.
+ */
+function restoreOutput(node, name) {
+    const stash = node._nugStashed?.[name];
+    if (!stash) return false;
+
+    // If it's somehow already back (e.g. the workflow was reloaded), just
+    // clear the stash marker.
+    if ((node.outputs || []).some((o) => outputMatches(o, name))) {
+        delete node._nugStashed[name];
+        return false;
+    }
+
+    // addOutput appends to the end.
+    const displayName = stash.spec.label
+        || stash.spec.localized_name
+        || stash.spec.name;
+    node.addOutput(displayName, stash.spec.type);
+    const appended = node.outputs.length - 1;
+    const output = node.outputs[appended];
+    if (stash.spec.name) output.name = stash.spec.name;
+    if (stash.spec.localized_name) output.localized_name = stash.spec.localized_name;
+
+    // Move it to its original position if possible. LiteGraph indexes links
+    // and internal draw data by array position, so we only reorder when
+    // there are no links to break -- which is always, because we refused
+    // to stash a linked output in the first place.
+    const target = Math.min(stash.origIndex, node.outputs.length - 1);
+    if (target !== appended) {
+        const [moved] = node.outputs.splice(appended, 1);
+        node.outputs.splice(target, 0, moved);
+    }
+
+    delete node._nugStashed[name];
+    return true;
+}
+
+// --- apply -------------------------------------------------------------
+
+function applyShow(node) {
+    if (node._nugApplying) return;
+    node._nugApplying = true;
+    try {
+        const showW = findWidget(node, SHOW_WIDGET);
+        const compact = (showW?.value ?? "compact") === "compact";
+
+        let changed = false;
+
+        // Widgets
+        for (const w of node.widgets || []) {
+            if (!COMPACT_HIDE_WIDGETS.includes(w.name)) continue;
+            if (compact) {
+                if (!w._nugHidden) { hideWidget(w); changed = true; }
+            } else {
+                if (w._nugHidden) { showWidget(w); changed = true; }
+            }
+        }
+
+        // Outputs
+        for (const name of COMPACT_HIDE_OUTPUTS) {
+            if (compact) {
+                if (stashOutput(node, name)) changed = true;
+            } else {
+                if (restoreOutput(node, name)) changed = true;
+            }
+        }
+
+        if (changed) {
+            // computeSize wants to grow the node to whatever the widget
+            // count would demand. Take the max with the current size so a
+            // switch back to everything expands, but a switch to compact
+            // does not shrink below what the user has already resized to.
+            const [w, h] = node.computeSize();
+            const cur = node.size || [w, h];
+            node.setSize([Math.max(w, cur[0]), Math.max(h, cur[1])]);
+            node.graph?.setDirtyCanvas?.(true, true);
+        }
+    } finally {
+        node._nugApplying = false;
+    }
+}
+
+// --- registration ------------------------------------------------------
+
+app.registerExtension({
+    name: "nugget.transcribe.compactview",
+    async beforeRegisterNodeDef(nodeType, nodeData) {
+        if (nodeData.name !== NODE) return;
+
+        const onNodeCreated = nodeType.prototype.onNodeCreated;
+        nodeType.prototype.onNodeCreated = function () {
+            const r = onNodeCreated?.apply(this, arguments);
+
+            // Intercept the show widget's callback so any change (widget
+            // click, right-click menu, keyboard) re-applies the view.
+            const showW = findWidget(this, SHOW_WIDGET);
+            if (showW) {
+                const origCallback = showW.callback;
+                showW.callback = (value, ...rest) => {
+                    const ret = origCallback?.call(showW, value, ...rest);
+                    // Defer so LiteGraph has finished writing the new value.
+                    requestAnimationFrame(() => applyShow(this));
+                    return ret;
+                };
+            }
+
+            requestAnimationFrame(() => applyShow(this));
+            return r;
+        };
+
+        // A workflow load restores widget values through onConfigure. The
+        // widgets are back to their saved state by the time this fires, so
+        // this is the right spot to re-apply the view.
+        const onConfigure = nodeType.prototype.onConfigure;
+        nodeType.prototype.onConfigure = function () {
+            const r = onConfigure?.apply(this, arguments);
+            requestAnimationFrame(() => applyShow(this));
+            return r;
+        };
+    },
+});