88dbfedf86
* feat(nodes): Easy Image Batch keyframes_insert + insert-over-source + clean batch - Rename optional input keyframe_batch -> keyframes_insert (node ID unchanged). - Insert-over-source mode: when keyframes_insert AND source_batch are both connected, composite the inserts over the source cut window (instead of the placeholder background). keyframes_insert alone keeps the offset/reconstruct behaviour over placeholder. - No image source connected -> clean placeholder batch sized by new width/height fallback widgets, instead of raising. width/height are appended LAST so older saved workflows keep their positional widgets_values alignment (fixes a mid-list insertion that shifted placeholder_color into source_frames). - alpha_batch marks only inserted/placed positions; source background is not counted as placed. - New pure planner plan_source_base_fill (torch-free) alongside plan_offset_placements; both unit-tested in CI. - Docs: behavior matrix spec, interactive HTML demo, and a generated "all versions" ComfyUI demo workflow under docs/designs/. Not yet implemented (specced as DRAFT in docs/designs, pending maintainer approval + tie-break decision): image1-4 "super-overwrite" layer across all modes, and removal of the Mode 2 unconnected-slot source_batch fallback. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(deps): raise aiohttp [test] floor to >=3.14.1 The constraints lock already pins aiohttp 3.14.1 (the CVE-2026-54273..54280 fix line), but pyproject's [test] extra still declared aiohttp>=3.9. Dependabot keys off pyproject, not the lock, so the open declared range kept eight range-based alerts open even though the installed version is patched. Raising the floor to >=3.14.1 aligns the declared range with the lock and clears the alerts once this reaches the default branch. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * feat(nodes): Easy Image Batch image1-4 super-overwrite + source passthrough Make the four manual slots the top compositing layer in every mode (select and insert): a connected imageN overwrites output frame imageN_frame on top of the sequence/inserts and the background. Higher slot wins a collision (image4 > image1); a slot beats a sequence pick / insert at the same position. Extracted as the torch-free plan_slot_overwrites planner + a shared _apply_slot_overwrites helper used by both code paths. Two model fixes ride along, per the finalised behaviour matrix: - An unconnected slot now contributes nothing -- imageN_frame is only a placement target for a wired image, never a source_batch pick. The old unwired-slot fallback (which surfaced seemingly-random frames) is removed. - source_batch + an empty frame list (no insert) now passes the source cut window straight through instead of a placeholder batch, matching the insert-mode empty-list passthrough. Tests: new plan_slot_overwrites planner cases + fake-tensor behaviour tests covering slot-beats-pick/insert, higher-slot-wins, passthrough-not-placed, and the removed phantom fallback. Docstring, tooltips, user guide, design spec (promoted DRAFT -> canonical), and CHANGELOG updated. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * test(nodes): assert selected_image_batch = picks/inserts + slots; drop matrix HTML demo selected_image_batch already packs every placed position -- both the source_frames picks / inserts and the manual-slot overwrites, with slots winning on overlap. Add explicit select- and insert-mode tests asserting the composition and ascending order, locking the behaviour in. Also delete docs/designs/easy-image-batch-matrix.html (stale interactive demo built against an earlier draft) and drop its companion reference from the design spec. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * feat(nodes): Easy Image Batch passthrough inpaint mask + frame-range syntax Two refinements to the Easy Image Batch passthrough/list behaviour: - Short-source passthrough is now an extend/inpaint mask. When source_batch is connected and the frame list is empty, the covered source frames are kept content (alpha 0.0) and the uncovered tail becomes the selection (selected_image_batch / selected_frames) with alpha 1.0 -- "keep the first N, generate the rest". Full coverage -> no gap, empty selection. The selection is the gap here (inverse of select mode); insert mode is unchanged. - The source_frames field accepts inclusive ranges: "1-5, 7, 9, 14-17" expands to 1,2,3,4,5,7,9,14,15,16,17, in both select and insert, via a shared torch-free parse_frame_tokens (descending/non-integer tokens warn). Tests cover the gap selection (short/full/cut-start-offset/slot-in-gap), the parser (ranges, bad tokens), and range syntax end-to-end. Docstring, tooltip, user guide, design spec, and CHANGELOG updated. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(designs): remove draft-era Easy Image Batch demo workflow + builder Delete easy-image-batch-demo-setup.json and build_easy_image_batch_demo.py (the leftover draft-era demo, sibling to the already-removed matrix HTML) and drop the companion reference from the behavior spec. A purpose-built demo will replace them later; the spec matrix + the node remain the canonical reference. Also drop the now-stale "(proposed)" from the spec title (it is canonical). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(user-guide): remove stale v0.1.5 Easy Image Batch screenshot The screenshot predates the node's keyframes_insert / super-overwrite / passthrough rework and is unreferenced. Removing it to be re-created fresh. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: point Easy Image Batch docs at the bundled Select-and-Rebuild demo Note the runnable demo workflow ("Easy Image Batch - Select and Rebuild", bundled into the Kforge Labs Workflows sidebar folder via #248) in both the user guide and the design spec, replacing the generated demo removed earlier. Referenced by path (not a clickable link) since the workflow lands via #248. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(nodes): address PR review — keyframe_batch alias + input guards - Restore keyframe_batch as a deprecated alias of keyframes_insert so pre-rename workflows (origin/main exposes the input) keep loading; an explicit keyframes_insert wins. Follows docs/maintainers/node-versioning.md (alias-then-deprecate); removal deferred to a release boundary. - Warn instead of silently returning a clean batch when source_frames is non-empty but no image source is connected. - Cap frame-list range expansion at 8192 frames/token to guard against typos like 1-99999999. - Docs: reframe the bundled demo-workflow note as forthcoming (the JSON lands via #248, not on this branch); document the alias, cap, and no-source guard in the user guide / design spec / CHANGELOG. Tests: alias routing + precedence, no-source warning, range cap + boundary (46 node tests). Fresh-eyes review: no correctness/compat issues (the IMAGE alias input adds no widget-position shift). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: point Easy Image Batch docs at the now-merged Select-and-Rebuild demo #248 merged to main and is now in this branch (via the main merge), so the demo workflow exists at docs/workflows/kforge-labs-workflows/. Repoint the user guide and design spec at it directly (present tense, real folder link) instead of the earlier "coming soon / pending" framing. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: AI Machine <ai.machine@x.baconcph.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
ComfyUI-Koolook
Kforge Labs for ComfyUI: a project-kit sidebar plus Koolook nodes for VFX, image, and video workflows.
Start here: KForge Labs ComfyUI-Koolook overview
That overview explains the sidebar, snapshots, saved workflows, modules, recovery tools, and included nodes for new users.
The main experience is the Kforge Labs sidebar. It helps you keep a project setup together: favorite nodes, saved workflows, reusable modules, tags, snapshots, and recovery tools.
Kforge Labs Sidebar
Use the sidebar as a reusable project kit.
| Feature | What it does |
|---|---|
| Snapshots | Save and load the whole Kforge Labs state: favorite nodes, workflows, modules, tags, archive, and recovery data. |
| Search | Find nodes, workflows, directories, and tags from one field. Tags keep exact capitalization, so Depth and depth can be separate folders. |
| Nodes | Keep favorite nodes close, grouped by theme or repository name. |
| Workflows | Save the whole script, save a selection of nodes, load workflows, or insert saved modules into the current canvas. |
| Recovery | Use autosaves, starter presets, snapshot library settings, and missing-pack install helpers. |
New here? Start with the KForge overview. Using it inside ComfyUI? Open the operational guide:
- Browse on the web: malkuthro.github.io/ComfyUI-Koolook/web/guide/
- Inside ComfyUI: Kforge Labs sidebar → Tools row → Help (
Hicon). The in-app button opens the bundled offline copy atweb/guide/index.html.
Included Nodes
| Node ID | Display name | Category |
|---|---|---|
EasyWan22Prompt |
Wan 2.2 Easy Prompt (Koolook) | Koolook/Wan_Video |
EasyResize_Koolook |
Easy Resize (Koolook) | Koolook/Image |
EasyAIPipeline |
Easy AI Pipeline (Koolook) | Koolook/Pipeline |
easy_ImageBatch |
Easy Image Batch (Koolook) | Koolook/Image |
KoolookLoadCameraPosesAbsolute |
Koolook Load Camera Poses (Absolute Path) | Koolook/Camera |
Easy_hdr_VAE_encode |
Easy HDR VAE Encode (Koolook) | Koolook/VAE |
Easy_hdr_VAE_decode |
Easy HDR VAE Decode (Koolook) | Koolook/VAE |
Easy_Pattern |
Easy Pattern (Koolook) | Koolook/Testing |
Easy_LoadVideo |
Easy Load Video (Koolook) | Koolook/Video |
Easy_VideoCombine |
Easy Video Combine (Koolook) | Koolook/Video |
Easy_Utility |
Easy Utility (Koolook) | Koolook/Utility |
Koolook_LoopStatus |
Koolook Loop Status | Koolook/Loop |
LTXDirector__koolook |
LTX Director (Koolook) | Koolook/PromptRelay |
The root Koolook nodes and the slim Radiance Koolook VAE wrappers have no
extra Python dependencies beyond torch, which ComfyUI already requires.
The video wrappers require Video Helper Suite, and the LTX Director fork is
for workflows that already use the LTX / Prompt Relay node ecosystem.
Install
ComfyUI-Manager
- Open ComfyUI Manager.
- Choose Install Custom Nodes.
- Install by Git URL:
https://github.com/malkuthro/ComfyUI-Koolook.git - Restart ComfyUI.
- Open the Kforge Labs sidebar tab.
Manual
Clone this repository into ComfyUI/custom_nodes/:
git clone https://github.com/malkuthro/ComfyUI-Koolook.git
Restart ComfyUI after installation.
One install at a time. If you already installed Kforge Labs via ComfyUI Manager, it lives at
custom_nodes/koolook/(the Manager / Registry-derived folder name). A secondcustom_nodes/ComfyUI-Koolook/created bygit cloneis a parallel install — ComfyUI loads BOTH on every boot, both register the same routes and sidebar tab, and the workflow store silently corrupts on every restart. From v0.3.8 the plugin detects this and prints a critical log naming both paths, disabling the non-winning copy — but the cleanest fix is to remove one folder. Pick the install method you want and stick with it.
Learn More
- Public overview: kforgelabs.com/comfyui-projects/comfyui-koolook/
- In-app visual guide: malkuthro.github.io/ComfyUI-Koolook/web/guide/
(offline copy:
web/guide/index.html) - Support / bug reports:
SUPPORT.md - User guide:
docs/user_guide/ - Change history:
CHANGELOG.md - Maintainer docs:
docs/maintainers/ - Fork attribution and provenance:
forks/THIRD_PARTY.md - Versioning reference:
docs/reference/versioning.md
Troubleshooting
| What you see | What it usually means | What to do |
|---|---|---|
| The Kforge Labs tab does not appear | ComfyUI needs a restart, or the extension did not load | Restart ComfyUI and check the terminal for [Koolook] messages. |
| The Help guide does not open | The browser blocked the popup | Allow popups for the ComfyUI page, or open web/guide/index.html directly. |
| Missing custom nodes after loading a workflow | One or more node packs used by that workflow are not installed | In Kforge Labs, use Tools → Install missing packs, or use ComfyUI Manager's Install Missing Custom Nodes flow. |
| Snapshot save/load fails | The snapshot library path may be missing, read-only, or unavailable | Use Snapshot → Save to... or Load from... and choose a writable folder. |
| A loaded snapshot looks older than expected | Named saves and auto-saves are intentionally separate | In Snapshot → Load, select the snapshot and check Recovery auto-saves for a newer periodic/pre-load recovery. |
Support
For reproducible bugs, open a
GitHub issue.
For the fastest answer, include your ComfyUI version, Koolook version,
operating system, install method, terminal log, browser console errors, and
steps to reproduce. See SUPPORT.md for the exact checklist.
Stability
For production work, install a pinned release tag or commit instead of following a moving branch head. Node IDs are treated carefully so saved ComfyUI workflows continue to load across compatible updates.
License
GPL-3.0. See LICENSE.
This package incorporates and adapts GPL-3.0 code from
fxtdstudios/radiance under
forks/radiance_koolook/. Attribution and per-fork modification notes are
tracked in forks/THIRD_PARTY.md and
forks/forks_manifest.yaml.