♾️ ComfyUI Sequential Batcher

v1.6.0 | VRAM-Optimized Generation | Recursive Self-Queuing | Perfect Audio Sync

A professional-grade suite of custom nodes for ComfyUI. Designed to bypass extreme VRAM limits in heavy video generation (WanVideo, Hunyuan, LTX) through Recursive Auto-Queuing, autonomous batch-by-batch processing, and forensic memory management.

🇪🇸 Leer en Español: README.md

---

🌟 What's New in v1.6.0 (Perfect Sync Update)

• 🛡️ VAE Safe Frame Padder (Hold Last Frame): The engine now dynamically expands incomplete tensors at the end of the video. If frames are missing to meet the strict requirements of WanVideo (multiples of 4) or LTX (8n+1), it clones the last frame imperceptibly. Result: Zero VAE crashes and 100% audio sync with no micro-stutters.
• 📈 Mathematical Inversion to "Expansion": The AutoLoopCalculatorWan and AutoLoopCalculatorLTX calculators now safely round the timeline upwards, guaranteeing total fluidity in intermediate cycles.

---

✨ Key Features

• Autonomous Orchestration: Turn your ComfyUI into a continuous rendering engine. Press "Queue Prompt" just once and the flow will feed itself by modifying seeds and indices until the entire video is finished.
• Smart Chunking: Analyzes the base video and makes mathematical cuts protecting the frames where faces are sharpest, maintaining identity coherence (Face Cuts).
• Native Audio Extraction: Extracts the original track directly from the initial node and injects it back into the final assembly.
• DiT Architectures Support (WanVideo & LTX 2.3): Specific mathematical calculators ensure video batches comply with strict decompression rules (multiples of 4 for WanVideo, or the 8n + 1 rule for LTX).
• Protected Resolutions (Megapixel Shield): Mathematical tools (ResTool) that automatically scale dimensions protecting the training floor of each base model.

---

⚠️ System Requirements (Critical)

For the VideoAnalyzerWithAudio node to unpack .mp4 containers and extract audio with torchaudio, FFmpeg is absolutely mandatory.

• 🐧 Ubuntu / Linux / WSL2: The script will attempt to install it for you. If it fails, run manually:

  sudo apt update && sudo apt install ffmpeg -y
  

• 🪟 Windows: Download the precompiled FFmpeg binaries and add the bin folder to your environment variables (PATH).

---

🧠 The Hybrid Architecture (Node Breakdown)

Processing is divided into highly specialized roles:

• 🕵️ Video Analyzer Face detector + Audio: Scans the video via OpenCV or using a GPU-accelerated YOLO model. Extracts faces, audio, and the Reference Frame.
• 📊 Auto Loop Calculator (Base / WanVideo / LTX): Receives the biometrics and calculates cut coordinates (chunk_frames, skip_frames).
• 🛡️ VAE Safe Frame Padder: Intercepts the final VHS tensor and pads it by cloning the last frame if material is missing, saving the VAE from a collapse.
• 🎞️ Incremental Auto-Stitcher: Collects rendered batches and the audio track, progressively stitching the final video in the temporary folder.
• 📥 Receiver & 📤 Sender: Retain and transfer the last valid keyframe across cycles to maintain temporal coherence.
• ⏱️ Auto FPS Limiter: Smartly reduces FPS guaranteeing audio and motion maintain perfect synchronization without breaking VRAM.
• 🔀 Master Switch (Lazy Evaluation): Physically amputates wires from inactive routes in the JSON sent to ComfyUI. Heavy nodes not needed in a specific cycle aren't even loaded into memory.
• 🧹 VRAM Defragmenter: Forensic memory purge (Sacred Sequence) that clears CUDA/MPS cache and forces the Garbage Collector between heavy cycles.

---

🔌 Quick Wiring Guide (Workflow Setup)

1. The Explorer: Place the Video Analyzer at the beginning. Upload a video (or use a YTDLP path).
2. Math: Connect total_frames and safe_faces_list to your chosen Auto Loop Calculator.
3. Safe Extraction: Add the native VHS_LoadVideo node. Convert its input to video_name and connect it to the Analyzer. Connect its IMAGE output to the new VAE Safe Frame Padder node.
4. Audio Passthrough: Route the source_audio wire from the Explorer directly to the audio port of your Incremental Auto-Stitcher (at the end of the flow).
5. The Trigger: Connect the output of your Stitcher to the Loop Trigger (Auto-Queue) node.
6. Execution: Connect the Loop Start (Index) to the Brain and the Stitcher.
7. Fire: Click "Queue Prompt" JUST ONCE. Enjoy the autonomous magic!

---

🚀 GPU Acceleration (Face Scanning)

The VideoAnalyzerWithAudio has a bbox_detector port to delegate facial scanning to the graphics card:

1. Install the Impact Pack.
2. Add the UltralyticsDetectorProvider node and select a face model (e.g. face_yolov8m.pt).
3. Connect its output to the Analyzer's port. (The node features auto-unload: it will destroy this model from VRAM upon completion to make room for generation).

---

📝 Recent Changelog

• v1.6.0: Implementation of VAESafeFramePadder (Hold Last Frame) and mathematical redesign to Expansion mode. Goodbye to audio cuts and crashes in the final cycle of WanVideo and LTX.
• v1.5.4: Injection of the PyTorch environment variable max_split_size_mb:128 to avoid VRAM micro-fragmentation with Triton kernels (SageAttention). Early YOLO model auto-unload.
• v1.5.3: "Sacred Sequence" in the VRAM Defragmenter (Break cycles -> Soft Evacuation -> IPC Cleanup -> Thread Synchronization).