Sequential Group Controller for ComfyUI

Sequential Group Controller for ComfyUI

Control which groups execute based on iteration ranges - a simplified alternative to complex conditional branching workflows.

🆕 Version 2.0 Now Available!

Two versions included:

| Version | Interface | Muting | Best For | |---------|-----------|--------|----------| | v2.0 🎛️ | Visual toggles + ranges | Automatic | Most users - easier, faster | | v1.0 🔄 | Text inputs | Manual (via outputs) | Advanced routing scenarios |

📖 Quick Links:

• v2.0: README_V2.md | V2_QUICK_START.md
• v1.0: Continue reading below

Features

• Auto-Discovery: Automatically finds all groups in your workflow
• Range Syntax: Simple, intuitive syntax for controlling execution
• Internal Counter: Tracks iterations automatically across queue runs
• Dynamic UI: Updates when you add/remove/rename groups
• Visual Feedback: Color-coded group indicators and iteration display

Installation

1. Clone or download this repository into your ComfyUI custom_nodes directory:

   cd ComfyUI/custom_nodes/
   git clone https://github.com/styletransfer/ComfyUI_SequentialGroupController.git
   

2. Restart ComfyUI

3. The node will appear as "🔄 Sequential Group Controller" in the SequentialGroupController category

📖 New to This Node?

Start here: Read HOW_IT_WORKS.md for a visual step-by-step guide!

Try the demos:

• workflows/DEMO_WORKFLOW.json - Full demo with 3 groups
• workflows/ONE_THEN_LOOP_WORKFLOW.json - Simple "run once, then loop" pattern

Quick Start

Basic Usage

1. Create Groups: Organize your workflow into groups using ComfyUI's group feature

   • Select nodes → Right-click → "Add Group"
   • Name your groups (e.g., "Setup", "Main Loop", "Cleanup")

2. Add Controller Node: Add "Sequential Group Controller" to your workflow

3. Configure Ranges: The node auto-discovers groups and shows a text field for each

   • Enter range syntax for when each group should run

4. Queue Workflow: Run your workflow multiple times

   • The controller tracks iterations automatically
   • Groups execute only when their range matches the current iteration

Example Setup

Groups:
- "Image Generation" → Range: "1"      (runs once on first iteration)
- "Processing"       → Range: "2+"     (runs from iteration 2 onwards)
- "Cleanup"          → Range: "10"     (runs only on iteration 10)

Queue the workflow 10 times:
Iteration 1: Only "Image Generation" runs
Iteration 2-9: Only "Processing" runs
Iteration 10: Only "Cleanup" runs

Range Syntax

The controller supports flexible range specifications:

| Syntax | Meaning | Example Use Case | |--------|---------|------------------| | 1 | Run only on iteration 1 | One-time setup | | 2+ | Run from iteration 2 onwards | Main processing loop | | 1-5 | Run on iterations 1 through 5 | Limited batch | | 3,5,7 | Run only on iterations 3, 5, and 7 | Specific checkpoints | | once | Alias for 1 | One-time initialization | | always or empty | Run every iteration | Always-active groups | | never | Never run (skip group) | Temporary disable |

Syntax Examples

Single Iteration

"1"     → Iteration 1 only
"5"     → Iteration 5 only
"once"  → Iteration 1 only (alias)

From Iteration X Onwards

"2+"    → Iterations 2, 3, 4, 5, ...
"5+"    → Iterations 5, 6, 7, 8, ...
"+"     → Iterations 1, 2, 3, ... (same as "always")

Range (Inclusive)

"1-3"   → Iterations 1, 2, 3
"5-10"  → Iterations 5, 6, 7, 8, 9, 10
"1-1"   → Iteration 1 only (same as "1")

Specific Iterations

"2,4,6"     → Iterations 2, 4, 6 (even numbers example)
"1,5,10"    → Iterations 1, 5, 10 (checkpoints)
"3,5,7,11"  → Iterations 3, 5, 7, 11 (custom list)

Special Keywords

"always"  → Every iteration
""        → Every iteration (empty = always)
"never"   → No iterations (skip group)
"skip"    → No iterations (alias for never)

Use Cases

1. Multi-Stage Generation Pipeline

Workflow with 3 stages:

Group: "Initial Generation" → "1"
- Generate base images on first run

Group: "Refinement Loop" → "2-10"
- Refine images on runs 2 through 10

Group: "Final Export" → "11"
- Export results on run 11

2. A/B Testing

Group: "Variant A" → "1,3,5,7,9"
- Test one approach on odd iterations

Group: "Variant B" → "2,4,6,8,10"
- Test alternate approach on even iterations

Group: "Compare Results" → "11"
- Analyze results after both variants complete

3. Progressive Quality

Group: "Draft Quality" → "1-5"
- Quick drafts for first 5 iterations

Group: "High Quality" → "6+"
- High quality renders from iteration 6 onwards

4. Checkpoint System

Group: "Regular Processing" → "always"
- Runs every iteration

Group: "Save Checkpoint" → "10,20,30,40,50"
- Saves progress every 10 iterations

5. Warmup and Cooldown

Group: "Warmup" → "1"
- Initialize models, load data

Group: "Processing" → "2+"
- Main processing with warmed-up models

Group: "Cleanup" → "never"
- Manual cleanup (set to a specific iteration when needed)

Node Inputs/Outputs

Inputs

| Input | Type | Default | Description | |-------|------|---------|-------------| | reset_counter | BOOLEAN | False | Reset iteration counter to 0 | | manual_iteration | INT | -1 | Override auto counter (-1 to use auto) |

Outputs

| Output | Type | Description | |--------|------|-------------| | iteration | INT | Current iteration number | | status | STRING | Status summary showing which groups are active | | active_groups | STRING | Comma-separated list of active group names |

Output Examples

iteration: 3
status: "Iter 3 | Setup[1]:✗ Main[2+]:✓ Cleanup[10]:✗"
active_groups: "Main"

Advanced Features

Manual Iteration Override

Use manual_iteration input to manually control which iteration to simulate:

Connect an INT node to manual_iteration:
- Value: 1  → Simulate first iteration
- Value: 10 → Simulate 10th iteration
- Value: -1 → Use automatic counter (default)

Reset Counter

Set reset_counter to True to restart from iteration 1:

• Useful when starting a new batch
• Can connect to a button/toggle for easy reset

Group Discovery

The node automatically refreshes when:

• Groups are added or removed
• Groups are renamed
• Workflow is loaded

Manual refresh:

• Right-click node → "🔄 Refresh Groups"

Quick Presets

Right-click node for preset options:

• Set All: Always - Enable all groups
• Set All: Never - Disable all groups

How It Works

Iteration Tracking

The controller maintains an internal counter that:

1. Starts at 0 when node is first created
2. Increments by 1 each time the workflow is queued
3. Persists across workflow runs (until ComfyUI restarts)
4. Can be reset manually via reset_counter input

Group Control

For each queue run:

1. Controller reads current iteration number
2. Checks each group's range configuration
3. Evaluates if current iteration matches the range
4. Outputs which groups are active
5. Note: Currently the node provides information only. Full mute/unmute integration requires connecting to group control nodes (see Limitations below)

Limitations & Future Work

Current Limitations

1. No Direct Muting - This version provides iteration tracking and group information but doesn't directly mute/unmute groups. You'll need to use the output signals with conditional nodes to control execution.

2. Counter Persistence - The iteration counter resets when ComfyUI restarts (not when workflow is reloaded)

3. No Preview - Doesn't show a preview of which groups will run on future iterations

Planned Features

• Direct Group Muting: Integrate with ComfyUI's internal muting system to automatically mute/unmute groups
• Visual Timeline: Show which groups run on which iterations in a graphical timeline
• Range Presets: Dropdown with common patterns (once, after-first, every-N, etc.)
• Iteration History: Track which groups ran on previous iterations
• Export/Import: Save and load range configurations
• Group Filtering: Show/hide specific groups from the controller

Integration with Existing Workflows

Replacing Easy-Use Conditional Logic

Before (complex):

easy int → easy compare → easy ifElse → Route to different groups

After (simplified):

Sequential Group Controller
- Group "Path A": "1,3,5"
- Group "Path B": "2,4,6"

Working with Impact Pack

Use controller outputs with Impact Pack nodes:

Sequential Group Controller
  ↓ active_groups
ImpactControlBridge or ImpactNodeSetMuteState

Troubleshooting

Groups Not Appearing

Problem: Node doesn't show my groups Solution: Right-click node → "🔄 Refresh Groups"

Counter Not Incrementing

Problem: Iteration stays at 1 Solution: Make sure you're queuing the workflow multiple times (not running once)

Syntax Not Working

Problem: Range syntax doesn't parse Solution: Check syntax reference above. Invalid syntax defaults to "always"

Groups Still Execute

Problem: Groups run even when range doesn't match Solution: This version provides information only. Connect outputs to conditional routing nodes to control execution.

Examples

See the examples/ directory for:

• basic_usage.json - Simple 3-group workflow
• ab_testing.json - A/B testing setup
• progressive_quality.json - Quality progression example
• checkpoint_system.json - Checkpoint saving workflow

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Test your changes thoroughly
4. Submit a pull request

License

MIT License - see LICENSE file for details

Credits

• Inspired by rgthree's Fast Groups Muter
• Built with ComfyUI Node Development Skill
• Created for the ComfyUI community

Support

• Issues: https://github.com/styletransfer/ComfyUI_SequentialGroupController/issues
• Discussions: https://github.com/styletransfer/ComfyUI_SequentialGroupController/discussions
• Discord: ComfyUI Official Discord

Changelog

v1.0.0 (2025-01-21)

• Initial release
• Auto-discovery of groups
• Range syntax support (1, 2+, 1-5, 3,5,7, always, never)
• Internal iteration counter
• Dynamic UI with visual feedback
• Status and active groups outputs