ComfyUI-Simple-Iterator

ComfyUI custom nodes for one-sample-per-run iteration across image, video, and text sources.

Language: English | 简体中文

Features

• Persistent iterator cursor state (.iterator_state.json)
• Scope isolation by node id + source settings
• Edge-triggered reset (False -> True)
• Safe stop mode to prevent silent duplicate processing
• File name output with or without extension

Common Semantics

• loop_mode
  • loop: wrap to the first item after the last item
  • stop: raise an error when exhausted (recommended for batch jobs)
  • hold_last: keep returning the last item after exhaustion
• reset
  • Edge-triggered reset only
  • Reset happens only when reset changes from False to True
• load_always (image/video nodes)
  • False: allow normal cache checks
  • True: force node execution each run
• enable_log (all nodes)
  • False: no runtime log output
  • True: print node runtime traces to ComfyUI console

Nodes

Iterator Load Image

Supports: .jpg/.jpeg/.png/.webp/.bmp/.tif/.tiff

Inputs

Name	Type	Default	Meaning
directory	STRING	""	Image directory path.
pattern	STRING	"*.png,*.jpg,*.jpeg,*.webp"	Glob patterns, supports comma/semicolon separated values.
recursive	BOOLEAN	False	Recursively scan subdirectories.
order	ENUM	name_asc	name_asc/name_desc/mtime_asc/mtime_desc.
loop_mode	ENUM	stop	loop/stop/hold_last.
reset	BOOLEAN	False	Edge-triggered reset signal.
load_always	BOOLEAN	False	Force execution every run.
enable_log	BOOLEAN	False	Print iterator debug logs for this node run.
filename_with_ext	BOOLEAN	True	Whether FILE_NAME includes extension.

Outputs

Name	Type	Meaning
IMAGE	IMAGE	Current image tensor (RGB).
MASK	MASK	Current mask tensor (all zeros if no alpha channel).
FILE_PATH	STRING	Full path of current image.
FILE_NAME	STRING	File name with or without extension.
INDEX	INT	Current index (0-based).
TOTAL	INT	Total available items.

Iterator Load Video Path

Supports: .mp4/.mov/.mkv/.avi/.webm/.m4v/.mpg/.mpeg/.wmv/.flv

Inputs

Name	Type	Default	Meaning
directory	STRING	""	Video directory path.
pattern	STRING	"*.mp4"	Glob patterns, supports comma/semicolon separated values.
recursive	BOOLEAN	False	Recursively scan subdirectories.
order	ENUM	name_asc	name_asc/name_desc/mtime_asc/mtime_desc.
loop_mode	ENUM	stop	loop/stop/hold_last.
reset	BOOLEAN	False	Edge-triggered reset signal.
load_always	BOOLEAN	False	Force execution every run.
enable_log	BOOLEAN	False	Print iterator debug logs for this node run.
filename_with_ext	BOOLEAN	True	Whether FILE_NAME includes extension.

Outputs

Name	Type	Meaning
VIDEO_PATH	STRING	Full path of current video.
FILE_NAME	STRING	File name with or without extension.
INDEX	INT	Current index (0-based).
TOTAL	INT	Total available items.

Iterator Load Text From Dir

Each text file is emitted as one output item.
Supports: .txt/.md/.prompt/.json/.jsonl

Inputs

Name	Type	Default	Meaning
directory	STRING	""	Text directory path.
pattern	STRING	"*.txt,*.md,*.prompt,*.json,*.jsonl"	Glob patterns, supports comma/semicolon separated values.
recursive	BOOLEAN	False	Recursively scan subdirectories.
order	ENUM	name_asc	name_asc/name_desc/mtime_asc/mtime_desc.
encoding	STRING	"utf-8"	File encoding.
loop_mode	ENUM	stop	loop/stop/hold_last.
reset	BOOLEAN	False	Edge-triggered reset signal.
enable_log	BOOLEAN	False	Print iterator debug logs for this node run.

Outputs

Name	Type	Meaning
TEXT	STRING	Full text content of current file.
SOURCE_PATH	STRING	Full path of current file.
INDEX	INT	Current index (0-based).
TOTAL	INT	Total available items.

Iterator Load Text From File

Loads multiple text items from a single file.

Inputs

Name	Type	Default	Meaning
file_path	STRING	""	Input file path.
parse_mode	ENUM	file_split	file_split/json_array/jsonl.
delimiter	STRING	"\\n---\\n"	Delimiter for file_split mode (supports escaped characters).
json_field	STRING	""	Field path for object entries (dot path supported).
encoding	STRING	"utf-8"	File encoding.
loop_mode	ENUM	stop	loop/stop/hold_last.
reset	BOOLEAN	False	Edge-triggered reset signal.
enable_log	BOOLEAN	False	Print iterator debug logs for this node run.

Outputs

Name	Type	Meaning
TEXT	STRING	Current text segment or record.
SOURCE_PATH	STRING	Source marker (#segment or :line).
INDEX	INT	Current index (0-based).
TOTAL	INT	Total available items.

Minimal Workflow Examples

1. Image batch processing
   • Iterator Load Image -> existing image workflow head node
2. Video batch processing
   • Iterator Load Video Path -> your video path-based loader node
3. Prompt/text batch processing
   • Iterator Load Text From Dir or Iterator Load Text From File -> prompt input branch

Installation

1. Clone this repo into your ComfyUI custom_nodes directory.
2. Install runtime dependencies in the same Python environment used by ComfyUI:

python -m pip install -r requirements.txt

3. Restart ComfyUI.

Notes:

• torch is expected to be provided by your ComfyUI environment.
• Keep your torch version aligned with your ComfyUI setup.

Testing

Core layer tests (no ComfyUI runtime dependency):

python -m pip install pytest
python -m pytest tests/core -m core -q

Runtime layer tests (optional, requires torch/ComfyUI runtime):

RUN_RUNTIME_TESTS=1 python -m pytest tests/runtime -m runtime -q

Release quality gate (version + lint + core tests):

python -m pip install pytest ruff
python scripts/release_gate.py

State File

• Cursor state is stored in .iterator_state.json
• The file is ignored by git
• State entries are auto-pruned to avoid unbounded growth:
  • TTL cleanup: remove entries not updated for 30 days
  • Capacity cleanup: keep at most 2000 most recently updated entries
• GC settings are configurable with priority:
  • Environment variables (highest)
  • iterator_config.json
  • Built-in defaults (lowest)

GC Config

Create iterator_config.json in the plugin root, for example:

{
  "state_ttl_seconds": 2592000,
  "state_max_entries": 2000
}

Environment variable override keys:

• SIMPLE_ITERATOR_STATE_TTL_SECONDS (>= 0, 0 means disable TTL cleanup)
• SIMPLE_ITERATOR_STATE_MAX_ENTRIES (>= 1)

Tracked example file:

• iterator_config.example.json (copy to iterator_config.json for local overrides)

Logging

• Set enable_log=True on a node when you want runtime traces.
• Logs are printed to the ComfyUI console with prefix [SimpleIterator].
• Any parameter value longer than 64 characters is truncated automatically.