ComfyUI-NL_Nodes

ComfyUI-NL_Nodes

Custom ComfyUI nodes and UI panels maintained by NOLABEL. The pack focuses on studio workflow context, IO helpers, model localization, and targeted video workflow utilities.

Artist Documentation

• Artist guide: docs/index.html (Polish default) and docs/index.en.html (English).
• docs/index.html and docs/index.en.html are self-contained single-file guides. They can be opened directly in a browser, including document-portal file:// paths that expose only one file.
• Editable source remains in docs/artist-guide/index.source.html, docs/artist-guide/index.en.source.html, docs/artist-guide/styles.css, docs/artist-guide/app.js, docs/artist-guide/assets/, and media/.
• Rebuild the standalone file with scripts/codex/build-artist-guide.sh. The build refreshes the guide's localized "last updated" labels.
• Enable the tracked pre-commit hook with git config core.hooksPath .githooks to refresh and rebuild the artist guide automatically when docs/artist-guide/ changes are committed.

Installation

• Copy //alien/comfyui/extra_model_paths.yaml to your local ComfyUI installation folder directory (if you have existing one, rename it to extra_model_paths_old.yaml or backup it somewhere).
• Open the newly created ComfyUI/extra_model_paths.yaml and adjust models1 paths so they will point to your chosen local /models folder.
• Restart ComfyUI. You should see top-bar buttons for "NL Workflow" and "NL Tools".

https://github.com/user-attachments/assets/5d2572b3-5aec-476f-8f9c-c039f73219be

What You Get

Color-managed IO roadmap:

• Concrete v1 spec and rollout notes live in docs/nl_color_io_v1_spec.md.
• Live preview viewer redesign spec lives in docs/nl_preview_viewer_v1_spec.md.
• Manual verification checklist for the current foundation lives in docs/nl_color_io_manual_test.md.

Top-bar tools:

• NL Workflow: shot context panel (project, shot, resolution, fps, frame range, project path).
• NL Tools menu: groups NL buttons and includes a simple Configuration panel (username).
• NL Models Manager: model localization manager (network <-> local cache).
• NL Templates: shared workflow library with metadata, tags, and poster images.
• NL Subgraphs: shared blueprint library for reusable graph blocks.
• NL Cost Ledger: API usage and cost tracking panel.

Nodes:

• NOLABEL/IO: NL Read, NL Write.
• NOLABEL/Workflow: NL Resolution, NL FPS, NL Frame Range, NL Project Path, NL Context Debug.
• NOLABEL/Color: NL Preview, NL OCIO Convert, NL Preview Transform, NL Grade, NL Merge, NL Shuffle.
• NOLABEL/Utilities: NL Constant Color, NL Fit Frame, NL Match, NL Edit, NL Bernini Prompt Enhancer.
• conditioning/video_models: NL LTXV Img To Video Inplace At Index.
• WanVideoWrapper: NL WanVideo ImageToVideo Encode v2 (multi-ref).

Artist Quick Start

1. Open NL Workflow, fill project/scene/shot and project_path, then click Apply.
2. Use NL Read, NL Edit, and NL Write in your graph as needed.
3. Open NL Templates to load a starting setup, or NL Subgraphs to insert reusable blueprint blocks.
4. If a model is missing locally, open NL Models Manager and localize it from network storage.

Panels (Top Bar)

NL Workflow

• Stores the current shot context in the top-bar modal and makes it available to helper/IO nodes.
• NL Workflow is workflow-level UI state, not a graph node.
• Save defaults and history for quick reuse between sessions.
• Includes quick tools such as copy workflow JSON and context helpers.

Saved files:

• ComfyUI/user/default/nl_workflow.json
• ComfyUI/user/default/nl_workflow_history.json

NL Models (Model Manager)

• Scans the current graph for model path widgets.
• Shows local/network availability, file size, and usage.
• Supports Localize, Re-localize, Upload, Delete local, and batch actions.
• Includes cache pruning by size with optional auto-delete.

Notes:

• Uses models1 as local root and models2 as network root from extra_model_paths.yaml.
• If categories only exist on one side, missing side entries are auto-filled.
• Required core ComfyUI folders such as frame_interpolation and optical_flow are auto-registered at runtime from the models1/models2 base paths when YAML entries are missing. The startup prompt can persist those entries into extra_model_paths.yaml with a backup.

NL Templates

• Browse templates with search, sort, tags, and popularity signals.
• Load templates directly into the current graph.
• On load, network paths are normalized for the host OS (\\server\\... <-> /mnt/server/...; set normalize_paths=0 on /nl_templates/load to disable).
• Create/update templates from the current graph or from JSON.
• During create/update, NL Read source assets are copied into shared template storage (<templates_root>/<user>/__assets/<template_stem>/...) and workflow paths are rewritten to those copies so templates stay self-contained.
• Supports metadata, versioning, stack confirmations, and poster images (card/header).
• Includes a Copy Prompt helper to generate a metadata-writing prompt with current tags and workflow JSON.

Requires:

• shared.nl_templates in extra_model_paths.yaml.
• Optional migration helper for existing templates: python scripts/nl_templates_localize_assets.py --root /path/to/templates.

NL Subgraphs

• Lists local and shared subgraph blueprints (.json).
• Click an entry to insert its blueprint node into the active workflow.
• Publish local subgraphs to shared storage (with overwrite confirmation).
• Marks local/shared conflicts when hashes differ.

Shared path keys (first available is used):

• shared.nl_subgraphs
• shared.subgraphs
• shared.nl_subgraph_blueprints
• shared.subgraph_blueprints

NL Cost Ledger

• Tracks API workflow usage rows in SQLite with production tags (project, scene, shot, user, optional task).
• Non-API prompts are ignored.
• Backend implementation is split across nl_cost_ledger.py (facade), nl_cost_ledger_core.py, nl_cost_ledger_persistence.py, nl_cost_ledger_billing.py, and nl_cost_ledger_routes.py.
• Includes list filtering, detail modal, summary, and CSV export.
• Read source toggle supports Local (default) and optional read-only Global DB.
• After each successful run, NL Ledger schedules delayed Local -> Global sync (upsert).
• Refresh still triggers manual Local -> Global sync before reloading panel data.
• Uses POST /nlnodes/prompt for queueing plus ledger capture.
• Optional credits from Comfy /customers/balance deltas (211 credits = 1 USD).
• Balance amounts are normalized to USD with NL_LEDGER_BALANCE_USD_SCALE (default 0.01).
• Ledger rows also store post-run Wallet state (after-balance USD) when available from balance tracking, plus derived wallet-in-credits.
• Balance-delta rows include confidence classification (high/medium/low) and the panel colors cost cells green/yellow/red.
• When credits cannot be resolved immediately, ledger rows store capture status/reason in credits_json and retry in the background with exponential backoff.
• Retry tuning: NL_LEDGER_BALANCE_RETRY_ATTEMPTS, NL_LEDGER_BALANCE_RETRY_INITIAL_DELAY_SEC, NL_LEDGER_BALANCE_RETRY_MAX_DELAY_SEC, NL_LEDGER_BALANCE_RETRY_BACKOFF, NL_LEDGER_BALANCE_RETRY_BATCH.
• Local DB defaults to ComfyUI/user/default/nl_cost_ledger.sqlite3 (or NL_LEDGER_DB_PATH override).
• Global DB path: NL_LEDGER_GLOBAL_DB_PATH or legacy extra_model_paths.yaml ledger db_path.
• Auto sync controls: NL_LEDGER_AUTO_SYNC (true/false) and NL_LEDGER_AUTO_SYNC_DELAY_SEC.
• Debug-only destructive/test routes stay off by default; set NL_LEDGER_DEBUG_ROUTES=true to enable /nlnodes/ledger/test_insert and /nlnodes/ledger/clear intentionally.

More verification steps:

• See TESTING.md.

NL Tools Menu + Configuration

• Consolidates NL buttons into one dropdown menu (cleaner top bar).
• Stores username used by NL Templates and NL Ledger flows.
• Shows a username prompt strip when required data is missing.

Nodes

NOLABEL/IO

• NL Read: read image, sequence, or video with range controls, sampling, reverse, resize, preview, upload-to-input support, and an optional serialized image-info output for the color-managed IO foundation. Still images and image sequences resolve OCIO config from workflow/global settings and normalize color inputs into ACEScg; raw/data inputs bypass color conversion. The artist-facing color controls are input_colorspace, populated from the active OCIO config and auto-seeded from the current source when a new source is loaded, and preview_colorspace, populated from the NL Workflow OCIO View list and defaulted to the selected workflow View. That preview target now applies to both still and animated NL Read previews. The selected input_colorspace is the actual source interpretation used by NL Read, while workflow-owned technical OCIO controls stay hidden from the normal node UI.
• NL Write: write stills or sequences with versioned names based on workflow context; new nodes now default to EXR-first still/sequence output, with optional PNG previews, MP4/MOV (ffmpeg), alpha/mask, compare outputs, comparison-reveal preview mode, and optional image-info metadata passthrough into JSON sidecars. Color EXRs write ACEScg header metadata, mask/data EXRs write Raw metadata, output_colorspace remains the canonical EXR/managed output space, and 8-bit color/video outputs are transformed to output_colorspace while preview_colorspace stays preview-only.

Path safety:

• NL Read and NL Canvas now default to guarded mode instead of full filesystem bypass.
• Guarded mode allows normal artist paths by default, but blocks obvious system locations such as /etc, /proc, /sys, /dev, /usr, and the Windows system/app roots.
• NL_READ_EXTRA_ROOTS adds trusted overrides and browse roots. Use it for network shares or any studio-specific folder that should stay explicitly allowed.
• NL_READ_BLOCKED_ROOTS adds more blocked roots on top of the defaults.
• NL_READ_ALLOW_ANY=1 restores the old unrestricted behavior and should be treated as a debugging-only escape hatch.
• GET /nl_read/policy returns the effective browse roots, trusted roots, and blocked roots for the current runtime.

NOLABEL/Workflow

• NL Resolution, NL FPS, NL Frame Range, NL Project Path: reads cached workflow values.
• NL Workflow Color Context: exposes the resolved OCIO/runtime color fields from workflow context.
• NL Context Debug: outputs cached context JSON (and optional console print).

NOLABEL/Color

• NL Preview: standalone artist-facing managed viewer/output node for arbitrary IMAGE tensors. It previews single images and batches as sequences, supports color, mask, rgba, comparison, and comparison reveal modes, consumes image_info_json when available, and keeps preview_colorspace as a display-only OCIO View transform so downstream tensors stay unchanged.
• NL OCIO Convert: explicit colorspace transform node for pipeline/debug cases; consumes image_info_json when available and emits updated metadata.
• NL Preview Transform: display/view transform node for explicit preview-only image conversion.
• NL Grade: Nuke-style primary RGB grade in the current working space, with lift/gain/gamma, blackpoint/whitepoint, multiply/offset, reverse, clamps, mask or mask-image blending, mix, and unchanged image_info_json passthrough.
• NL Merge: Nuke-inspired A/B image merge with optional A/B mattes, A/B image-info metadata inputs, effect mask, bbox-style canvas options, invert mask, and mix.
• NL Shuffle: Nuke-inspired channel shuffle that routes B/A RGB and mask channels plus black/white constants into a new IMAGE and MASK.

IO Debug

• NL Image Info Debug: pretty-prints the serialized image_info_json emitted by NL Read.

NOLABEL/Utilities

• NL Constant Color: constant color image + mask at workflow or custom resolution.
• NL Fit Frame: detect image or mask bounds, crop/fit the subject to a target frame, and preserve image-info metadata.
• NL Match: align A/B streams by resolution, batch length, and optional color-space context while preserving masks and metadata.
• NL Edit: built-in paint and mask editor node that can fetch upstream inputs, composite RGB edits, merge mask strokes, and export the current result to a new NL Read node.
• NL Bernini Prompt Enhancer: builds task-specific GPT prompt strings for Bernini/ByteDance prompt enhancement modes without calling an API or storing API keys. The node context menu includes a Bernini mode guide entry for mode descriptions. Connect full_prompt to single-prompt API nodes, or connect system_prompt and user_prompt separately when the downstream node supports chat roles.

LTXV

• NL LTXV Img To Video Inplace At Index: LTXV image-to-video latent conditioning helper that places an encoded image at an arbitrary pixel frame index, supports -1 for the final frame, preserves existing chained noise masks, and exposes LTXV preprocessing controls for compression, blur, interpolation, crop, and bypass.

WanVideoWrapper

• NL WanVideo ImageToVideo Encode v2 (multi-ref): WanVideo reference encode utility with optional temporal mask/control embeds/tiled VAE paths.

Dependencies

• Provided by the ComfyUI runtime: torch, aiohttp.
• Installed from base requirements.txt: numpy, Pillow, PyYAML, imageio.
• Optional system dependency for video previews/writes: ffmpeg.
• Optional color pipeline dependencies live in requirements-color.txt: opencolorio (PyOpenColorIO import) and OpenEXR.
• Optional ShotGrid Toolkit integration lives in requirements-sgtk.txt: nl_sgtk.

Developer Verification

• scripts/codex/check-python.sh: compile tracked Python files with the preferred ComfyUI Python.
• scripts/codex/check-js.sh: run syntax checks for tracked js/*.js.
• scripts/codex/run-unit-tests.sh: run the repo-local stdlib unit tests for pure helpers.
• scripts/codex/check-browser-tools.mjs / npm run check:browser-tools: verify Playwright and Puppeteer can launch headless Chromium.
• scripts/codex/build-artist-guide.sh: rebuild the standalone artist guide from docs/artist-guide/ sources.
• scripts/codex/probe-runtime.sh: read-only route probes against a live ComfyUI instance.
• scripts/codex/show-required-checks.sh: map changed files to the right manual smoke checklist.
• scripts/codex/release-preflight.sh: inspect local develop/stable/network release state without publishing anything.

Manual Testing

• NL Preview: execute it directly with IMAGE, MASK, comparison_images, and image_info_json; verify managed preview, sequence playback, comparison mode, comparison reveal mode persistence, mask/RGBA modes, and that changing preview_colorspace only changes the viewer result.
• NL Grade: test default identity, lift/gain/gamma, per-channel controls, reverse round-trip, MASK and IMAGE mask inputs, mix, clamps, and metadata passthrough.
• NL Fit Frame, NL Match, NL Merge, NL Shuffle: test representative image/mask inputs, batch sizing, bbox/canvas behavior, color-space options, and metadata passthrough.
• NL Workflow: apply context, save defaults, restart ComfyUI, verify reload + history behavior.
• NL Read/Write: test image, sequence, and video; verify naming/versioning and optional video output.
• NL Edit: fetch upstream input, draw RGB and mask edits, verify saved state reloads, and export the result into NL Read.
• NL Models: test scan/localize/upload/delete/prune and missing-network behavior.
• NL Templates: test load, create/update, search/tags/sort, posters, and confirmations.
• NL Subgraphs: test list, click-to-insert, publish, overwrite prompt, and conflict indicators.
• NL Ledger: run TESTING.md checklist end-to-end.