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

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.
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.
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.

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.

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

Run tests:

python -m pip install pytest
python -m pytest

State File

• Cursor state is stored in .iterator_state.json
• The file is ignored by git