Upload folder using huggingface_hub

.gitattributes

@@ -296,3 +296,9 @@ v3-nodes/ComfyUI-RMBG/example_workflows/V3.0.0_nodes.jpg filter=lfs diff=lfs mer
 v3-nodes/ComfyUI-RMBG/example_workflows/YOLO_Node.jpg filter=lfs diff=lfs merge=lfs -text
 v3-nodes/ComfyUI-RMBG/example_workflows/florence2_node.jpg filter=lfs diff=lfs merge=lfs -text
 v3-nodes/ComfyUI-RMBG/models/sam3/perflib/tests/assets/masks.tiff filter=lfs diff=lfs merge=lfs -text
+v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/docs/demo_01.jpg filter=lfs diff=lfs merge=lfs -text
+v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/docs/demo_02.jpg filter=lfs diff=lfs merge=lfs -text
+v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/docs/usage_01.png filter=lfs diff=lfs merge=lfs -text
+v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/docs/usage_02.png filter=lfs diff=lfs merge=lfs -text
+v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/example_workflows/example_inputs/Mustache_640x360.mp4 filter=lfs diff=lfs merge=lfs -text
+v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/example_workflows/example_inputs/Sadhu_320x478.png filter=lfs diff=lfs merge=lfs -text

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [adrientoupet, numz]

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to Comfy registry
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - "pyproject.toml"
+
+permissions:
+  issues: write
+
+jobs:
+  publish-node:
+    name: Publish Custom Node to registry
+    runs-on: ubuntu-latest
+    if: ${{ github.repository_owner == 'numz' }}
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: Publish Custom Node
+        uses: Comfy-Org/publish-node-action@v1
+        with:
+          ## Add your own personal access token to your Github Repository secrets and reference it here.
+          personal_access_token: ${{ secrets.REGISTRY_ACCESS_TOKEN }}

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/.gitignore

@@ -0,0 +1,26 @@
+.git/*
+**/__pycache__/
+tests/
+.vscode/
+.cursor/
+benchmark/
+advanced_optimizations.py
+BENCHMARK_*
+environment.yml
+install_safetensors.py
+manage_quantized_models.py
+quantization_config.py
+quantize_model.py
+quantize_vae.py
+README_*.md
+run_*.py
+vram_diagnostic.py
+test_*.py
+VRAM_OPTIMIZATIONS_SUMMARY.md
+seedvr2.py
+src/core/isolated_generation.py
+src/core/subprocess_runner.py
+models/video_vae_v3_mine_bad/
+src/processing/
+TILE_VAE*
+.DS_Store

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing to ComfyUI-SeedVR2_VideoUpscaler
+
+Thank you for your interest in contributing to ComfyUI-SeedVR2_VideoUpscaler! We appreciate your effort and to help us incorporate your contribution in the best way possible, please follow the following contribution guidelines.
+
+## Reporting Bugs
+
+If you find a bug in the project, we encourage you to report it. Here's how:
+
+1. First, check the [existing Issues](https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler/issues) to see if the issue has already been reported. If it has, please add a comment to the existing issue rather than creating a new one.
+2. If you can't find an existing issue that matches your bug, create a new issue. Make sure to include as many details as possible so we can understand and reproduce the problem.
+
+## Proposing Changes
+
+We welcome code contributions from the community. Here's how to propose changes:
+
+1. Fork this repository to your own GitHub account.
+2. Create a new branch on your fork for your changes.
+3. Make your changes in this branch.
+4. When you are ready, submit a pull request to the **`main`** branch.
+
+We use the GitHub Flow workflow.
+
+Before submitting a pull request, please make sure your code adheres to the project's coding conventions and it has passed all tests. If you are adding features, please also add appropriate tests.
+
+## Contact
+
+If you have any questions or need help, please reach out to the developers:
+
+- **NumZ**: Discord NumZ#7184
+- **adrientoupet** from AInVFX: [YouTube Channel](https://www.youtube.com/@AInVFX)
+
+You can also open an issue on GitHub for general questions and discussions.
+
+Thank you again for your contribution !

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 seed
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/README.md

@@ -0,0 +1,1053 @@
+# ComfyUI-SeedVR2_VideoUpscaler
+
+[![View Code](https://img.shields.io/badge/📂_View_Code-GitHub-181717?style=for-the-badge&logo=github)](https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler)
+
+Official release of [SeedVR2](https://github.com/ByteDance-Seed/SeedVR) for ComfyUI that enables high-quality video and image upscaling.
+
+Can run as **Multi-GPU standalone CLI** too, see [🖥️ Run as Standalone](#-run-as-standalone-cli) section.
+
+[![SeedVR2 v2.5 Deep Dive Tutorial](https://img.youtube.com/vi/MBtWYXq_r60/maxresdefault.jpg)](https://youtu.be/MBtWYXq_r60)
+
+![Usage Example](docs/usage_01.png)
+
+![Usage Example](docs/usage_02.png)
+
+## 📋 Quick Access
+
+- [🆙 Future Work](#-future-work)
+- [🚀 Release Notes](#-release-notes)
+- [🎯 Features](#-features)
+- [🔧 Requirements](#-requirements)
+- [📦 Installation](#-installation)
+- [📖 Usage](#-usage)
+- [🖥️ Run as Standalone](#️-run-as-standalone-cli)
+- [⚠️ Limitations](#️-limitations)
+- [🤝 Contributing](#-contributing)
+- [🙏 Credits](#-credits)
+- [📜 License](#-license)
+
+## 🆙 Future Work
+
+We're actively working on improvements and new features. To stay informed:
+
+- **📌 Track Active Development**: Visit [Issues](https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler/issues) to see active development, report bugs, and request new features
+- **💬 Join the Community**: Learn from others, share your workflows, and get help in the [Discussions](https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler/discussions)
+- **🔮 Next Model Survey**: We're looking for community input on the next open-source super-powerful generic restoration model. Share your suggestions in [Issue #164](https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler/issues/164)
+
+## 🚀 Release Notes
+
+**2025.12.24 - Version 2.5.24**
+
+- **🍎 Fix: MPS memory leak regression** - Restored MPS cache clearing after VAE encode/decode operations that was accidentally removed during code cleanup in v2.5.23
+
+**2025.12.24 - Version 2.5.23**
+
+- **🔒 Security: Prevent code execution in model loading** - Added protection against malicious .pth files by restricting deserialization to tensors only
+- **🎥 Fix: FFmpeg video writer reliability** - Resolved ffmpeg process hanging issues by redirecting stderr and adding buffer flush, with improved error messages for debugging *(thanks [@thehhmdb](https://github.com/thehhmdb))*
+- **⚡ Fix: GGUF VAE model support** - Enabled automatic weight dequantization for convolution operations, making GGUF-quantized VAE models fully functional *(thanks [@naxci1](https://github.com/naxci1))*
+- **🛡️ Fix: VAE slicing edge cases** - Protected against division by zero crashes when using small split sizes with high temporal downsampling *(thanks [@naxci1](https://github.com/naxci1))*
+- **🎨 Fix: LAB color transfer precision** - Resolved dtype mismatch errors during video upscaling by ensuring consistent float types before matrix operations
+- **🔧 Fix: PyTorch 2.9+ compatibility** - Extended Conv3d memory workaround to all PyTorch 2.9+ versions, fixing 3x VRAM usage on newer PyTorch releases
+- **📦 Fix: Bitsandbytes compatibility** - Added ValueError exception handling for Intel Gaudi version detection failures on non-Gaudi systems
+- **🍎 MPS: Memory optimization** - Reduced memory usage during encode/decode operations on Apple Silicon *(thanks [@s-cerevisiae](https://github.com/s-cerevisiae))*
+
+
+**2025.12.13 - Version 2.5.22**
+
+- **🎬 CLI: FFmpeg video backend with 10-bit support** - New `--video_backend ffmpeg` and `--10bit` flags enable x265 encoding with 10-bit color depth, reducing banding artifacts in gradients compared to 8-bit OpenCV output *(based on PR by [@thehhmdb](https://github.com/thehhmdb) - thank you!)*
+- **🍎 Fix: MPS bicubic upscaling compatibility** - Added CPU fallback for bicubic+antialias interpolation on PyTorch versions before 2.8.0, resolving RGBA alpha upscaling errors on Apple Silicon
+- **⚡ Fix: Cross-platform histogram matching** - Replaced scatter_ operation with argsort+index_select for improved reliability across CUDA, ROCm, and MPS backends
+- **🧹 MPS: Remove sync overhead** - Reverted unnecessary `torch.mps.synchronize()` calls introduced in v2.5.21 for consistent behavior with CUDA pipeline
+
+**2025.12.12 - Version 2.5.21**
+
+- **🛠️ Fix: GGUF dequantization error on MPS** - Resolved shape mismatch error introduced in 2.5.20 by skipping GGUF quantized buffers in precision conversion - these must remain in packed format for on-the-fly dequantization during inference
+- **🍎 MPS: Eliminate CPU sync overhead** - Skip unnecessary CPU tensor offload on Apple Silicon unified memory architecture, preventing sync stalls that caused slowdowns. Input images and output video now stay on MPS device throughout the pipeline
+- **⚡ MPS: Preload text embeddings** - Load text embeddings before Phase 1 encoding to avoid sync stall at Phase 2 start, improving timing accuracy and throughput
+- **🧹 MPS: Optimized model cleanup** - Skip redundant CPU movement before model deletion on unified memory
+
+**2025.12.12 - Version 2.5.20**
+
+- **⚡ Expanded attention backends** - Full support for Flash Attention 2 (Ampere+), Flash Attention 3 (Hopper+), SageAttention 2, and SageAttention 3 (Blackwell/RTX 50xx), with automatic fallback chains to PyTorch SDPA when unavailable *(based on PR by [@naxci1](https://github.com/naxci1) - thank you!)*
+- **🍎 macOS/Apple Silicon compatibility** - Replaced MPS autocast with explicit dtype conversion throughout VAE and DiT pipelines, resolving hangs and crashes on M-series Macs. BlockSwap now auto-disables with warning (unified memory makes it meaningless)
+- **🛡️ Flash Attention graceful fallback** - Added compatibility shims for corrupted or partially installed flash_attn/xformers DLLs, preventing startup crashes
+- **🛡️ AMD ROCm: bitsandbytes conflict fix** - Prevent kernel registration errors when diffusers attempts to re-import broken bitsandbytes installations
+- **📦 ComfyUI Manager: macOS classifier fix** - Removed NVIDIA CUDA classifier causing false "GPU not supported" warnings on macOS
+- **📚 Documentation updates** - Updated README with attention backend details, BlockSwap macOS notes, and clarified model caching descriptions
+
+**2025.12.10 - Version 2.5.19**
+
+- **🎨 New header logo design** - Refreshed ASCII art banner *(thanks [@naxci1](https://github.com/naxci1))*
+- **🧹 Remove dead flash attention wrapper** - Removed legacy code from FP8CompatibleDiT; FlashAttentionVarlen already handles backend switching via its `attention_mode` attribute
+- **🛡️ Fix graceful fallback from flash-attn** - Add compatibility shims for corrupted flash_attn/xformers DLLs, preventing startup crashes when CUDA extensions are broken
+- **📊 Improved VRAM tracking** - Separate allocated vs reserved memory tracking, Windows-only overflow detection (WDDM paging behavior)
+- **♻️ Centralize backend detection** - Unified `is_mps_available()`, `is_cuda_available()`, `get_gpu_backend()` helpers across codebase
+- **🔄 Revert 2.5.14 VRAM limit enforcement** - Removed `set_per_process_memory_fraction` call; Overflow detection and warnings remain.
+
+**2025.12.09 - Version 2.5.18**
+
+- **🚀 CLI: Streaming mode for long videos** - New `--chunk_size` flag processes videos in memory-bounded chunks, enabling arbitrarily long videos without RAM limits. Works with model caching (`--cache_dit`/`--cache_vae`) for chunk-to-chunk reuse *(inspired by [disk02](https://github.com/disk02) PR contribution)*
+- **⚡ CLI: Multi-GPU streaming** - Each GPU now streams its segment internally with independent model caching, improving memory efficiency and enabling `--temporal_overlap` blending at GPU boundaries
+- **🔧 CLI: Fix large video MemoryError** - Shared memory transfer replaces numpy pickling, preventing crashes on high-resolution/long video outputs *(inspired by  [FurkanGozukara](https://github.com/FurkanGozukara) PR contribution)*
+
+**2025.12.05 - Version 2.5.17**
+
+- **🔧 Fix: Older GPU compatibility (GTX 970, etc.)** - Runtime bf16 CUBLAS probe replaces compute capability heuristics, correctly detecting unsupported GPUs without affecting RTX 20XX
+
+**2025.12.05 - Version 2.5.16**
+
+- **🔧 Fix: Older GPU compatibility (GTX 970, etc.)** - Automatic fallback for GPUs without bfloat16 support
+- **🐛 Fix: Quality regression** - Reverted bfloat16 detection that was causing artifact issues
+- **📋 Debug: Environment info display** - Shows system info in debug mode to help with issue reporting
+- **📚 Docs: Simplified contribution workflow** - Streamlined to main branch only
+
+**2025.12.03 - Version 2.5.15**
+
+- **🍎 Fix: MPS compatibility** - Disable antialias for MPS tensors and fix bfloat16 arange issues
+- **⚡ Fix: Autocast device type** - Use proper device type attribute to prevent autocast errors
+- **📊 Memory: Accurate VRAM tracking** - Use max_memory_reserved for more precise peak reporting
+- **🔧 Fix: Triton compatibility** - Add shim for bitsandbytes 0.45+ / triton 3.0+ (fixes PyTorch 2.7 installation errors)
+
+**2025.12.01 - Version 2.5.14**
+
+- **🍎 Fix: MPS device comparison** - Normalize device strings to prevent unnecessary tensor movements
+- **📊 Memory: VRAM swap detection** - Peak stats now show GPU+swap breakdown when overflow occurs, with warning when swap detected
+- **🛡️ Memory: Enforce physical VRAM limit** - PyTorch now OOMs instead of silently swapping to shared memory (prevents extreme slowdowns on Windows)
+
+**2025.11.30 - Version 2.5.13**
+
+- **🔧 Fix: PyTorch 2.7+ triton import error** - Resolved installation crash caused by triton.ops import chain on newer triton versions
+- **💾 Fix: OOM on float32 conversion for long videos** - Graceful fallback to native dtype when insufficient memory for float32 conversion
+- **🍎 Fix: CLI watermark error on macOS** - Resolved MPS-related watermark processing crash on Apple Silicon
+
+**2025.11.28 - Version 2.5.12**
+
+- **🐛 Fix: Color artifacts regression** - Reverted in-place tensor operations in video transform pipeline that caused color artifacts on some images
+
+**2025.11.28 - Version 2.5.11**
+
+- **⚡ Feature: CUDNN attention backend** - Added support for PyTorch 2.3+ CUDNN_ATTENTION backend with automatic fallback for older versions (thanks @eadwu)
+- **💾 Fix: Memory spike for long videos** - VAE decode now streams directly to pre-allocated tensor, eliminating OOM errors during long video processing
+- **🎨 Fix: LAB color correction artifacts** - Resolved tile boundary artifacts using wavelet reconstruction preprocessing
+- **🎨 Fix: Color reference misalignment** - Fixed color correction frame alignment with temporal overlap
+- **🍎 Fix: MPS detection reliability** - Switched to canonical `torch.backends.mps.is_available()` API for consistent Apple Silicon detection
+- **🖥️ Fix: Mac subprocess error** - CLI now uses direct processing on Mac to avoid MPS allocator failures in child processes
+- **🖥️ Fix: Multi-GPU device assignment** - CUDA_VISIBLE_DEVICES now set before spawn for proper worker inheritance
+- **📊 Fix: BlockSwap logging** - Now shows effective/total blocks (e.g., 32/32) instead of raw requested value
+- **🔧 Feature: Auto bfloat16 detection** - Automatically detects bfloat16 support to prevent CUBLAS errors on older GPUs
+- **📊 Feature: Peak RAM tracking** - Added RAM usage alongside VRAM in debug summary
+- **⚡ Performance: In-place tensor ops** - Reduced memory allocation overhead with in-place operations throughout pipeline
+- **📖 Docs: Multi-GPU clarification** - Clarified frame-level parallelism behavior expectations for multi-GPU setups
+
+**2025.11.13 - Version 2.5.10**
+
+- **🎯 Fix: Deterministic generation** - Identical images with the same seed now produce identical results across different sessions and batch positions
+- **🔧 Fix: Model caching with BlockSwap** - Resolved issue where cached DiT models wouldn't properly reload when VAE caching state changed
+- **💾 Fix: Runner caching optimization** - Runner templates now correctly cache whenever both DiT and VAE are cached, regardless of caching order
+- **📁 Fix: Case-insensitive model paths** - Extra model paths in YAML config now work regardless of case (seedvr2, SEEDVR2, SeedVR2, etc.)
+- **🐛 Fix: High resolution tile debug crash** - Fixed "NoneType has no attribute log" error when using maximum resolution with VAE tiling
+- **📊 Fix: Temporal overlap logging** - Corrected frame count reporting when temporal overlap is automatically adjusted
+- **🔍 Feature: Enhanced model path debugging** - Added detailed logging to help troubleshoot model loading issues (visible in debug mode)
+
+**2025.11.12 - Version 2.5.9**
+
+- **🐛 Fix: Tile debug visualization crash** - Fixed OpenCV error when using VAE tile debug mode on certain systems.
+- **🍎 Fix: macOS MPS loading error** - Added automatic CPU fallback for MPS allocator issues on certain PyTorch/macOS versions.
+- **🖥️ Fix: Windows log buffering** - Added flush to print statements for real-time log visibility in ComfyUI on Windows
+- **📦 Fix: ComfyUI Registry logo** - Updated icon URL to display properly in ComfyUI node registry
+- **ℹ️ Feature: Version display** - Added version number to node name and CLI/ComfyUI header for better tracking
+- **💝 Feature: GitHub Sponsors** - Added sponsor button to support project development. Thank you everyone for your support!
+- **📜 License: Apache 2.0** - Reverted License from MIT to Apache 2.0 to match ByteDance Seed project
+
+**2025.11.10 - Version 2.5.8**
+
+- **🐛 Fix (CLI): Windows batch processing duplicate files** - Fixed CLI batch mode processing each file twice on Windows due to case-insensitive filesystem. Improved directory scanning performance by 2-3x
+- **📁 Fix(CLI): Output folder location** - Output files now created in sensible locations: batch mode creates `{folder_name}_upscaled/` sibling folder with original filenames preserved; single file mode adds `_upscaled` suffix in same directory. All logs now show absolute paths for clarity
+- **🎨 Fix(CLI): RGBA alpha channel support** - PNG images with transparency are now properly detected and preserved through the upscaling pipeline, matching ComfyUI behavior
+
+**2025.11.10 - Version 2.5.7**
+
+- **🔧 Fix: Conv3d workaround compatibility** - Enhanced platform detection and added graceful fallback to prevent errors on PyTorch dev builds and AMD ROCm systems
+
+**2025.11.09 - Version 2.5.6**
+
+- 🎨 **Fix: Restored natural look for 7b model** - Corrected torch.compile optimization that was causing overly plastic/ high-specular appearance in upscaled videos with 7b model.
+
+- 💾 **Memory: Fixed RAM leak for long videos** - On-demand reconstruction with lightweight batch indices instead of storing full transformed videos, fixed release_tensor_memory to handle CPU/CUDA/MPS consistently, and refactored batch processing helpers
+
+**2025.11.08 - Version 2.5.4**
+
+- 🎨 **Fix: AdaIN color correction** - Replace `.view()` with `.reshape()` to handle non-contiguous tensors after spatial padding, resolving "view size is not compatible with input tensor's size and stride" error
+- 🔴 **Fix: AMD ROCm compatibility** - Add cuDNN availability check in Conv3d workaround to prevent "ATen not compiled with cuDNN support" error on ROCm systems (AMD GPUs on Windows/Linux)
+
+**2025.11.08 - Version 2.5.3**
+
+- 🍎 **Fix: Apple Silicon MPS device handling** - Corrected MPS device enumeration to use `"mps"` instead of `"mps:0"`, resolving invalid device errors on M-series Macs
+- 🪟 **Fix: torch.mps AttributeError on Windows** - Add defensive checks for `torch.mps.is_available()` to handle PyTorch versions where the method doesn't exist on non-Mac platforms
+
+**2025.11.07 - Version 2.5.0** 🎉
+
+⚠️ **BREAKING CHANGE**: This is a major update requiring workflow recreation. All nodes and CLI parameters have been redesigned for better usability and consistency. Watch the latest video from [AInVFX](https://www.youtube.com/@AInVFX) for a deep dive and check out the [usage](#-usage) section.
+
+**📦 Official Release**: Now available on main branch with ComfyUI Manager support for easy installation and automatic version tracking. Updated dependencies and local imports prevent conflicts with other ComfyUI custom nodes.
+
+### 🎨 ComfyUI Improvements
+
+- **Four-Node Modular Architecture**: Split into dedicated nodes for DiT model, VAE model, torch.compile settings, and main upscaler for granular control
+- **Global Model Cache**: Models now shared across multiple upscaler instances with automatic config updates - no more redundant loading
+- **ComfyUI V3 Migration**: Full compatibility with ComfyUI V3 stateless node design
+- **RGBA Support**: Native alpha channel processing with edge-guided upscaling for clean transparency
+- **Improved Memory Management**: Streaming architecture prevents VRAM spikes regardless of video length
+- **Flexible Resolution Support**: Upscale to any resolution divisible by 2 with lossless padding approach (replaced restrictive cropping)
+- **Enhanced Parameters**: Added `uniform_batch_size`, `temporal_overlap`, `prepend_frames`, and `max_resolution` for better control
+
+### 🖥️ CLI Enhancements
+
+- **Batch Directory Processing**: Process entire folders of videos/images with model caching for efficiency
+- **Single Image Support**: Direct image upscaling without video conversion
+- **Smart Output Detection**: Auto-detects output format (MP4/PNG) based on input type
+- **Enhanced Multi-GPU**: Improved workload distribution with temporal overlap blending
+- **Unified Parameters**: CLI and ComfyUI now use identical parameter names for consistency
+- **Better UX**: Auto-display help, validation improvements, progress tracking, and cleaner output
+
+### ⚡ Performance & Optimization
+
+- **torch.compile Support**: 20-40% DiT speedup and 15-25% VAE speedup with full graph compilation
+- **Optimized BlockSwap**: Adaptive memory clearing (5% threshold), separate I/O component handling, reduced overhead
+- **Enhanced VAE Tiling**: Tensor offload support for accumulation buffers, separate encode/decode configuration
+- **Native Dtype Pipeline**: Eliminated unnecessary conversions, maintains bfloat16 precision throughout for speed and quality
+- **Optimized Tensor Operations**: Replaced einops rearrange with native PyTorch ops for 2-5x faster transforms
+
+### 🎯 Quality Improvements
+
+- **LAB Color Correction**: New perceptual color transfer method with superior color accuracy (now default)
+- **Additional Color Methods**: HSV saturation matching, wavelet adaptive, and hybrid approaches
+- **Deterministic Generation**: Seed-based reproducibility with phase-specific seeding strategy
+- **Better Temporal Consistency**: Hann window blending for smooth transitions between batches
+
+### 💾 Memory Management
+
+- **Smarter Offloading**: Independent device configuration for DiT, VAE, and tensors (CPU/GPU/none)
+- **Four-Phase Pipeline**: Completes each phase (encode→upscale→decode→postprocess) for all batches before moving to next, minimizing model swaps
+- **Better Cleanup**: Phase-specific resource management with proper tensor memory release
+- **Peak VRAM Tracking**: Per-phase memory monitoring with summary display
+
+### 🔧 Technical Improvements
+
+- **GGUF Quantization Support**: Added full GGUF support for 4-bit/8-bit inference on low-VRAM systems
+- **Improved GGUF Handling**: Fixed VRAM leaks, torch.compile compatibility, non-persistent buffers
+- **Apple Silicon Support**: Full MPS (Metal Performance Shaders) support for Apple Silicon Macs
+- **AMD ROCm Compatibility**: Conditional FSDP imports for PyTorch ROCm 7+ support
+- **Conv3d Memory Workaround**: Fixes PyTorch 2.9+ cuDNN memory bug (3x usage reduction)
+- **Flash Attention Optional**: Graceful fallback to SDPA when flash-attn unavailable
+
+### 📚 Code Quality
+
+- **Modular Architecture**: Split monolithic files into focused modules (generation_phases, model_configuration, etc.)
+- **Comprehensive Documentation**: Extensive docstrings with type hints across all modules
+- **Better Error Handling**: Early validation, clear error messages, installation instructions
+- **Consistent Logging**: Unified indentation, better categorization, concise messages
+
+**2025.08.07**
+
+- 🎯 **Unified Debug System**: New structured logging with categories, timers, and memory tracking. `enable_debug` now available on main node
+- ⚡ **Smart FP8 Optimization**: FP8 models now keep native FP8 storage, converting to BFloat16 only for arithmetic - faster and more memory efficient than FP16
+- 📦 **Model Registry**: Multi-repo support (numz/ & AInVFX/), auto-discovery of user models, added mixed FP8 variants to fix 7B artifacts
+- 💾 **Model Caching**: `cache_model` moved to main node, fixed memory leaks with proper RoPE/wrapper cleanup
+- 🧹 **Code Cleanup**: New modular structure (`constants.py`, `model_registry.py`, `debug.py`), removed legacy code
+- 🚀 **Performance**: Better memory management with `torch.cuda.ipc_collect()`, improved RoPE handling
+
+**2025.07.17**
+
+- 🛠️ Add 7B sharp Models: add 2 new 7B models with sharpen output
+
+**2025.07.11**
+
+- 🎬 Complete tutorial released: Adrien from [AInVFX](https://www.youtube.com/@AInVFX) created an in-depth ComfyUI SeedVR2 guide covering everything from basic setup to advanced BlockSwap techniques for running on consumer GPUs. Perfect for understanding memory optimization and upscaling of image sequences with alpha channel! [Watch the tutorial](#-usage)
+
+**2025.09.07**
+
+- 🛠️ Blockswap Integration: Big thanks to [Adrien Toupet](https://github.com/adrientoupet) from [AInVFX](https://www.youtube.com/@AInVFX) for this :), useful for low VRAM users (see [usage](#-usage) section)
+
+**2025.07.03**
+
+- 🛠️ Can run as **standalone mode** with **Multi GPU** see [🖥️ Run as Standalone](#run-as-standalone-cli)
+
+**2025.06.30**
+
+- 🚀 Speed Up the process and less VRAM used
+- 🛠️ Fixed memory leak on 3B models
+- ❌ Can now interrupt process if needed
+- ✅ Refactored the code for better sharing with the community, feel free to propose pull requests
+- 🛠️ Removed flash attention dependency (thanks to [luke2642](https://github.com/Luke2642) !!)
+
+**2025.06.24**
+
+- 🚀 Speed up the process until x4
+
+**2025.06.22**
+
+- 💪 FP8 compatibility !
+- 🚀 Speed Up all Process
+- 🚀 less VRAM consumption (Stay high, batch_size=1 for RTX4090 max, I'm trying to fix that)
+- 🛠️ Better benchmark coming soon
+
+**2025.06.20**
+
+- 🛠️ Initial push
+
+## 🎯 Features
+
+### Core Capabilities
+- **High-Quality Diffusion-Based Upscaling**: One-step diffusion model for video and image enhancement
+- **Temporal Consistency**: Maintains coherence across video frames with configurable batch processing
+- **Multi-Format Support**: Handles RGB and RGBA (alpha channel) for both videos and images
+- **Any Video Length**: Suitable for any video length
+
+### Model Support
+- **Multiple Model Variants**: 3B and 7B parameter models with different precision options
+- **FP16, FP8, and GGUF Quantization**: Choose between full precision (FP16), mixed precision (FP8), or heavily quantized GGUF models for different VRAM requirements
+- **Automatic Model Downloads**: Models are automatically downloaded from HuggingFace on first use
+
+### Memory Optimization
+- **BlockSwap Technology**: Dynamically swap transformer blocks between GPU and CPU memory to run large models on limited VRAM
+- **VAE Tiling**: Process large resolutions with tiled encoding/decoding to reduce VRAM usage
+- **Intelligent Offloading**: Offload models and intermediate tensors to CPU or secondary GPUs between processing phases
+- **GGUF Quantization Support**: Run models with 4-bit or 8-bit quantization for extreme VRAM savings
+
+### Performance Features
+- **torch.compile Integration**: Optional 20-40% DiT speedup and 15-25% VAE speedup with PyTorch 2.0+ compilation
+- **Multi-GPU CLI**: Distribute workload across multiple GPUs with automatic temporal overlap blending
+- **Model Caching**: Keep models loaded between generations for single-GPU directory processing or multi-GPU streaming
+- **Flexible Attention Backends**: Choose between PyTorch SDPA (stable, always available), Flash Attention 2/3, or SageAttention 2/3 for faster computation on supported hardware
+
+### Quality Control
+- **Advanced Color Correction**: Five methods including LAB (recommended for highest fidelity), wavelet, wavelet adaptive, HSV, and AdaIN
+- **Noise Injection Controls**: Fine-tune input and latent noise scales for artifact reduction at high resolutions
+- **Configurable Resolution Limits**: Set target and maximum resolutions with automatic aspect ratio preservation
+
+### Workflow Features
+- **ComfyUI Integration**: Four dedicated nodes for complete control over the upscaling pipeline
+- **Standalone CLI**: Command-line interface for batch processing and automation
+- **Debug Logging**: Comprehensive debug mode with memory tracking, timing information, and processing details
+- **Progress Reporting**: Real-time progress updates during processing
+
+## 🔧 Requirements
+
+### Hardware
+
+With the current optimizations (tiling, BlockSwap, GGUF quantization), SeedVR2 can run on a wide range of hardware:
+
+- **Minimal VRAM** (8GB or less): Use GGUF Q4_K_M models with BlockSwap and VAE tiling enabled
+- **Moderate VRAM** (12-16GB): Use FP8 models with BlockSwap or VAE tiling as needed
+- **High VRAM** (24GB+): Use FP16 models for best quality and speed without memory optimizations
+
+### Software
+
+- **ComfyUI**: Latest version recommended
+- **Python**: 3.12+ (Python 3.12 and 3.13 tested and recommended)
+- **PyTorch**: 2.0+ for torch.compile support (optional but recommended)
+- **Triton**: Required for torch.compile with inductor backend (optional)
+- **Flash Attention / SageAttention**: Flash Attention 2 (Ampere+), Flash Attention 3 (Hopper+), SageAttention 2 or SageAttention 3 (Blackwell) provide faster attention computation on supported hardware (optional, falls back to PyTorch SDPA)
+
+## 📦 Installation
+
+### Option 1: ComfyUI Manager (Recommended)
+
+1. Open ComfyUI Manager in your ComfyUI interface
+2. Click "Custom Nodes Manager"
+3. Search for "ComfyUI-SeedVR2_VideoUpscaler"
+4. Click "Install" and restart ComfyUI
+
+**Registry Link**: [ComfyUI Registry - SeedVR2 Video Upscaler](https://registry.comfy.org/nodes/seedvr2_videoupscaler)
+
+### Option 2: Manual Installation
+
+1. **Clone the repository** into your ComfyUI custom nodes directory:
+```bash
+cd ComfyUI
+git clone https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler.git custom_nodes/seedvr2_videoupscaler
+```
+
+2. **Install dependencies using standalone Python**:
+```bash
+# Install requirements (from same ComfyUI directory)
+# Windows:
+.venv\Scripts\python.exe -m pip install -r custom_nodes\seedvr2_videoupscaler\requirements.txt
+# Linux/macOS:
+.venv/bin/python -m pip install -r custom_nodes/seedvr2_videoupscaler/requirements.txt
+```
+
+3. **Restart ComfyUI**
+
+### Model Installation
+
+Models will be **automatically downloaded** on first use and saved to `ComfyUI/models/SEEDVR2`.
+
+You can also manually download models from:
+- Main models available at [numz/SeedVR2_comfyUI](https://huggingface.co/numz/SeedVR2_comfyUI/tree/main) and [AInVFX/SeedVR2_comfyUI](https://huggingface.co/AInVFX/SeedVR2_comfyUI/tree/main)
+- Additional GGUF models available at [cmeka/SeedVR2-GGUF](https://huggingface.co/cmeka/SeedVR2-GGUF/tree/main)
+
+## 📖 Usage
+
+### 🎬 Video Tutorials
+
+#### Latest Version Deep Dive (Recommended)
+
+Complete walkthrough of version 2.5 by Adrien from [AInVFX](https://www.youtube.com/@AInVFX), covering the new 4-node architecture, GGUF support, memory optimizations, and production workflows:
+
+[![SeedVR2 v2.5 Deep Dive Tutorial](https://img.youtube.com/vi/MBtWYXq_r60/maxresdefault.jpg)](https://youtu.be/MBtWYXq_r60)
+
+This comprehensive tutorial covers:
+- Installing v2.5 through ComfyUI Manager and troubleshooting conflicts
+- Understanding the new 4-node modular architecture and why we rebuilt it
+- Running 7B models on 8GB VRAM with GGUF quantization
+- Configuring BlockSwap, VAE tiling, and torch.compile for your hardware
+- Image and video upscaling workflows with alpha channel support
+- CLI for batch processing and multi-GPU rendering
+- Memory optimization strategies for different VRAM levels
+- Real production tips and the critical batch_size formula (4n+1)
+
+#### Previous Version Tutorial
+
+For reference, here's the original tutorial covering the initial release:
+
+[![SeedVR2 Deep Dive Tutorial](https://img.youtube.com/vi/I0sl45GMqNg/maxresdefault.jpg)](https://youtu.be/I0sl45GMqNg)
+
+*Note: This tutorial covers the previous single-node architecture. While the UI has changed significantly in v2.5, the core concepts about BlockSwap and memory management remain valuable.*
+
+### Node Setup
+
+SeedVR2 uses a modular node architecture with four specialized nodes:
+
+#### 1. SeedVR2 (Down)Load DiT Model
+
+![SeedVR2 (Down)Load DiT Model](docs/dit_model_loader.png)
+
+Configure the DiT (Diffusion Transformer) model for video upscaling.
+
+**Parameters:**
+
+- **model**: Choose your DiT model
+  - **3B Models**: Faster, lower VRAM requirements
+    - `seedvr2_ema_3b_fp16.safetensors`: FP16 (best quality)
+    - `seedvr2_ema_3b_fp8_e4m3fn.safetensors`: FP8 8-bit (good quality)
+    - `seedvr2_ema_3b-Q4_K_M.gguf`: GGUF 4-bit quantized (acceptable quality)
+    - `seedvr2_ema_3b-Q8_0.gguf`: GGUF 8-bit quantized (good quality)
+  - **7B Models**: Higher quality, higher VRAM requirements
+    - `seedvr2_ema_7b_fp16.safetensors`: FP16 (best quality)
+    - `seedvr2_ema_7b_fp8_e4m3fn_mixed_block35_fp16.safetensors`: FP8 with last block in FP16 to reduce artifacts (good quality)
+    - `seedvr2_ema_7b-Q4_K_M.gguf`: GGUF 4-bit quantized (acceptable quality)
+    - `seedvr2_ema_7b_sharp_*`: Sharp variants for enhanced detail
+
+- **device**: GPU device for DiT inference (e.g., `cuda:0`)
+
+- **offload_device**: Device to offload DiT model when not actively processing
+  - `none`: Keep model on inference device (fastest, highest VRAM)
+  - `cpu`: Offload to system RAM (reduces VRAM)
+  - `cuda:X`: Offload to another GPU (good balance if available)
+
+- **cache_model**: Keep DiT model loaded on offload_device between workflow runs
+  - Useful for batch processing to avoid repeated loading
+  - Requires offload_device to be set
+
+- **blocks_to_swap**: BlockSwap memory optimization
+  - `0`: Disabled (default)
+  - `1-32`: Number of transformer blocks to swap for 3B model
+  - `1-36`: Number of transformer blocks to swap for 7B model
+  - Higher values = more VRAM savings but slower processing
+  - Requires offload_device to be set and different from device
+
+- **swap_io_components**: Offload input/output embeddings and normalization layers
+  - Additional VRAM savings when combined with blocks_to_swap
+  - Requires offload_device to be set and different from device
+
+- **attention_mode**: Attention computation backend
+  - `sdpa`: PyTorch scaled_dot_product_attention (default, always available)
+  - `flash_attn_2`: Flash Attention 2 (Ampere+, requires flash-attn package)
+  - `flash_attn_3`: Flash Attention 3 (Hopper+, requires flash-attn with FA3 support)
+  - `sageattn_2`: SageAttention 2 (requires sageattention package)
+  - `sageattn_3`: SageAttention 3 (Blackwell/RTX 50xx, requires sageattn3 package)
+
+- **torch_compile_args**: Connect to SeedVR2 Torch Compile Settings node for 20-40% speedup
+
+**BlockSwap Explained:**
+
+BlockSwap enables running large models on GPUs with limited VRAM by dynamically swapping transformer blocks between GPU and CPU memory during inference.
+
+> **Note:** BlockSwap is not available on macOS. Apple Silicon Macs use unified memory architecture where GPU and CPU share the same memory pool, making BlockSwap meaningless. The option will be automatically disabled with a warning if requested on macOS.
+
+Here's how it works:
+
+- **What it does**: Keeps only the currently-needed transformer blocks on the GPU, while storing the rest on CPU or another device
+- **When to use it**: When you get OOM (Out of Memory) errors during the upscaling phase
+- **How to configure**:
+  1. Set `offload_device` to `cpu` or another GPU
+  2. Start with `blocks_to_swap=16` (half the blocks)
+  3. If still getting OOM, increase to 24 or 32 (3B) / 36 (7B)
+  4. Enable `swap_io_components` for maximum VRAM savings
+  5. If you have plenty of VRAM, decrease or set to 0 for faster processing
+
+**Example Configuration for Low VRAM (8GB)**:
+- model: `seedvr2_ema_3b-Q8_0.gguf`
+- device: `cuda:0`
+- offload_device: `cpu`
+- blocks_to_swap: `32`
+- swap_io_components: `True`
+
+#### 2. SeedVR2 (Down)Load VAE Model
+
+![SeedVR2 (Down)Load VAE Model](docs/vae_model_loader.png)
+
+Configure the VAE (Variational Autoencoder) model for encoding/decoding video frames.
+
+**Parameters:**
+
+- **model**: VAE model selection
+  - `ema_vae_fp16.safetensors`: Default and recommended
+
+- **device**: GPU device for VAE inference (e.g., `cuda:0`)
+
+- **offload_device**: Device to offload VAE model when not actively processing
+  - `none`: Keep model on inference device (default, fastest)
+  - `cpu`: Offload to system RAM (reduces VRAM)
+  - `cuda:X`: Offload to another GPU (good balance if available)
+
+- **cache_model**: Keep VAE model loaded on offload_device between workflow runs
+  - Requires offload_device to be set
+
+- **encode_tiled**: Enable tiled encoding to reduce VRAM usage during encoding phase
+  - Enable if you see OOM errors during the "Encoding" phase in debug logs
+
+- **encode_tile_size**: Encoding tile size in pixels (default: 1024)
+  - Applied to both height and width
+  - Lower values reduce VRAM but may increase processing time
+
+- **encode_tile_overlap**: Encoding tile overlap in pixels (default: 128)
+  - Reduces visible seams between tiles
+
+- **decode_tiled**: Enable tiled decoding to reduce VRAM usage during decoding phase
+  - Enable if you see OOM errors during the "Decoding" phase in debug logs
+
+- **decode_tile_size**: Decoding tile size in pixels (default: 1024)
+
+- **decode_tile_overlap**: Decoding tile overlap in pixels (default: 128)
+
+- **torch_compile_args**: Connect to SeedVR2 Torch Compile Settings node for 15-25% speedup
+
+**VAE Tiling Explained:**
+
+VAE tiling processes large resolutions in smaller tiles to reduce VRAM requirements. Here's how to use it:
+
+1. **Run without tiling first** and monitor the debug logs (enable `enable_debug` on main node)
+2. **If OOM during "Encoding" phase**:
+   - Enable `encode_tiled`
+   - If still OOM, reduce `encode_tile_size` (try 768, 512, etc.)
+3. **If OOM during "Decoding" phase**:
+   - Enable `decode_tiled`
+   - If still OOM, reduce `decode_tile_size`
+4. **Adjust overlap** (default 128) if you see visible seams in output (increase it) or processing times are too slow (decrease it).
+
+**Example Configuration for High Resolution (4K)**:
+- encode_tiled: `True`
+- encode_tile_size: `1024`
+- encode_tile_overlap: `128`
+- decode_tiled: `True`
+- decode_tile_size: `1024`
+- decode_tile_overlap: `128`
+
+#### 3. SeedVR2 Torch Compile Settings (Optional)
+
+![SeedVR2 Torch Compile Settings](docs/torch_compile_settings.png)
+
+Configure torch.compile optimization for 20-40% DiT speedup and 15-25% VAE speedup.
+
+**Requirements:**
+- PyTorch 2.0+
+- Triton (for inductor backend)
+
+**Parameters:**
+
+- **backend**: Compilation backend
+  - `inductor`: Full optimization with Triton kernel generation and fusion (recommended)
+  - `cudagraphs`: Lightweight wrapper using CUDA graphs, no kernel optimization
+
+- **mode**: Optimization level (compilation time vs runtime performance)
+  - `default`: Fast compilation with good speedup (recommended for development)
+  - `reduce-overhead`: Lower overhead, optimized for smaller models
+  - `max-autotune`: Slowest compilation, best runtime performance (recommended for production)
+  - `max-autotune-no-cudagraphs`: Like max-autotune but without CUDA graphs
+
+- **fullgraph**: Compile entire model as single graph without breaks
+  - `False`: Allow graph breaks for better compatibility (default, recommended)
+  - `True`: Enforce no breaks for maximum optimization (may fail with dynamic shapes)
+
+- **dynamic**: Handle varying input shapes without recompilation
+  - `False`: Specialize for exact input shapes (default)
+  - `True`: Create dynamic kernels that adapt to shape variations (enable when processing different resolutions or batch sizes)
+
+- **dynamo_cache_size_limit**: Max cached compiled versions per function (default: 64)
+  - Higher = more memory, lower = more recompilation
+
+- **dynamo_recompile_limit**: Max recompilation attempts before falling back to eager mode (default: 128)
+  - Safety limit to prevent compilation loops
+
+**Usage:**
+1. Add this node to your workflow
+2. Connect its output to the `torch_compile_args` input of DiT and/or VAE loader nodes
+3. First run will be slow (compilation), subsequent runs will be much faster
+
+**When to use:**
+- torch.compile only makes sense when processing **multiple batches, long videos, or many tiles**
+- For single images or short clips, the compilation time outweighs the speed improvement
+- Best suited for batch processing workflows or long videos
+
+**Recommended Settings:**
+- For development/testing: `mode=default`, `backend=inductor`, `fullgraph=False`
+- For production: `mode=max-autotune`, `backend=inductor`, `fullgraph=False`
+
+#### 4. SeedVR2 Video Upscaler (Main Node)
+
+![SeedVR2 Video Upscaler](docs/video_upscaler.png)
+
+Main upscaling node that processes video frames using DiT and VAE models.
+
+**Required Inputs:**
+
+- **image**: Input video frames as image batch (RGB or RGBA format)
+- **dit**: DiT model configuration from SeedVR2 (Down)Load DiT Model node
+- **vae**: VAE model configuration from SeedVR2 (Down)Load VAE Model node
+
+**Parameters:**
+
+- **seed**: Random seed for reproducible generation (default: 42)
+  - Same seed with same inputs produces identical output
+
+- **resolution**: Target resolution for shortest edge in pixels (default: 1080)
+  - Maintains aspect ratio automatically
+
+- **max_resolution**: Maximum resolution for any edge (default: 0 = no limit)
+  - Automatically scales down if exceeded to prevent OOM
+
+- **batch_size**: Frames per batch (default: 5)
+  - **CRITICAL REQUIREMENT**: Must follow the **4n+1 formula** (1, 5, 9, 13, 17, 21, 25, ...)
+  - **Why this matters**: The model uses these frames for temporal consistency calculations
+  - **Minimum 5 for temporal consistency**: Use 1 only for single images or when temporal consistency isn't needed
+  - **Match shot length ideally**: For best results, set batch_size to match your shot length (e.g., batch_size=21 for a 20-frame shot)
+  - **VRAM impact**: Higher batch_size = better quality and speed but requires more VRAM
+  - **If you get OOM with batch_size=5**: Try optimization techniques first (model offloading, BlockSwap, GGUF models...) before reducing batch_size or input resolution, as these directly impact quality
+
+**uniform_batch_size** (default: False)
+  - Pads the final batch to match `batch_size` for uniform processing
+  - Prevents temporal artifacts when the last batch is significantly smaller than others
+  - Example: 45 frames with `batch_size=33` creates [33, 33] instead of [33, 12]
+  - Recommended when using large batch sizes and video length is not a multiple of `batch_size`
+  - Increases VRAM usage slightly but ensures consistent temporal coherence across all batches
+
+- **temporal_overlap**: Overlapping frames between batches (default: 0)
+  - Used for blending between batches to reduce temporal artifacts
+  - Range: 0-16 frames
+
+- **prepend_frames**: Frames to prepend (default: 0)
+  - Prepends reversed frames to reduce artifacts at video start
+  - Automatically removed after processing
+  - Range: 0-32 frames
+
+- **color_correction**: Color correction method (default: "wavelet")
+  - **`lab`**: Full perceptual color matching with detail preservation (recommended for highest fidelity to original)
+  - **`wavelet`**: Frequency-based natural colors, preserves details well
+  - **`wavelet_adaptive`**: Wavelet base + targeted saturation correction
+  - **`hsv`**: Hue-conditional saturation matching
+  - **`adain`**: Statistical style transfer
+  - **`none`**: No color correction
+
+- **input_noise_scale**: Input noise injection scale 0.0-1.0 (default: 0.0)
+  - Adds noise to input frames to reduce artifacts at very high resolutions
+  - Try 0.1-0.3 if you see artifacts with high output resolutions
+
+- **latent_noise_scale**: Latent space noise scale 0.0-1.0 (default: 0.0)
+  - Adds noise during diffusion process, can soften excessive detail
+  - Use if input_noise doesn't help, try 0.05-0.15
+
+- **offload_device**: Device for storing intermediate tensors between processing phases (default: "cpu")
+  - `none`: Keep all tensors on inference device (fastest but highest VRAM)
+  - `cpu`: Offload to system RAM (recommended for long videos, slower transfers)
+  - `cuda:X`: Offload to another GPU (good balance if available, faster than CPU)
+
+- **enable_debug**: Enable detailed debug logging (default: False)
+  - Shows memory usage, timing information, and processing details
+  - **Highly recommended** for troubleshooting OOM issues
+
+**Output:**
+- Upscaled video frames with color correction applied
+- Format (RGB/RGBA) matches input
+- Range [0, 1] normalized for ComfyUI compatibility
+
+### Typical Workflow Setup
+
+**Basic Workflow (High VRAM - 24GB+)**:
+```
+Load Video Frames
+    ↓
+SeedVR2 Load DiT Model
+  ├─ model: seedvr2_ema_3b_fp16.safetensors
+  └─ device: cuda:0
+    ↓
+SeedVR2 Load VAE Model
+  ├─ model: ema_vae_fp16.safetensors
+  └─ device: cuda:0
+    ↓
+SeedVR2 Video Upscaler
+  ├─ batch_size: 21
+  └─ resolution: 1080
+    ↓
+Save Video/Frames
+```
+
+**Low VRAM Workflow (8-12GB)**:
+```
+Load Video Frames
+    ↓
+SeedVR2 Load DiT Model
+  ├─ model: seedvr2_ema_3b-Q8_0.gguf
+  ├─ device: cuda:0
+  ├─ offload_device: cpu
+  ├─ blocks_to_swap: 32
+  └─ swap_io_components: True
+    ↓
+SeedVR2 Load VAE Model
+  ├─ model: ema_vae_fp16.safetensors
+  ├─ device: cuda:0
+  ├─ encode_tiled: True
+  └─ decode_tiled: True
+    ↓
+SeedVR2 Video Upscaler
+  ├─ batch_size: 5
+  └─ resolution: 720
+    ↓
+Save Video/Frames
+```
+
+**High Performance Workflow (24GB+ with torch.compile)**:
+```
+Load Video Frames
+    ↓
+SeedVR2 Torch Compile Settings
+  ├─ mode: max-autotune
+  └─ backend: inductor
+    ↓
+SeedVR2 Load DiT Model
+  ├─ model: seedvr2_ema_7b_sharp_fp16.safetensors
+  ├─ device: cuda:0
+  └─ torch_compile_args: connected
+    ↓
+SeedVR2 Load VAE Model
+  ├─ model: ema_vae_fp16.safetensors
+  ├─ device: cuda:0
+  └─ torch_compile_args: connected
+    ↓
+SeedVR2 Video Upscaler
+  ├─ batch_size: 81
+  └─ resolution: 1080
+    ↓
+Save Video/Frames
+```
+
+## 🖥️ Run as Standalone (CLI)
+
+The standalone CLI provides powerful batch processing capabilities with multi-GPU support and sophisticated optimization options.
+
+### Prerequisites
+
+Choose the appropriate setup based on your installation:
+
+#### Option 1: Already Have ComfyUI with SeedVR2 Installed
+
+If you've already installed SeedVR2 as part of ComfyUI (via [ComfyUI installation](#-installation)), you can use the CLI directly:
+
+```bash
+# Navigate to your ComfyUI directory
+cd ComfyUI
+
+# Run the CLI using standalone Python (display help message)
+# Windows:
+.venv\Scripts\python.exe custom_nodes\seedvr2_videoupscaler\inference_cli.py --help
+# Linux/macOS:
+.venv/bin/python custom_nodes/seedvr2_videoupscaler/inference_cli.py --help
+```
+
+**Skip to [Command Line Usage](#command-line-usage) below.**
+
+#### Option 2: Standalone Installation (Without ComfyUI)
+
+If you want to use the CLI without ComfyUI installation, follow these steps:
+
+1. **Install [uv](https://docs.astral.sh/uv/getting-started/installation/)** (modern Python package manager):
+```bash
+# Windows
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# macOS and Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+2. **Clone the repository**:
+```bash
+git clone https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler.git seedvr2_videoupscaler
+cd seedvr2_videoupscaler
+```
+
+3. **Create virtual environment and install dependencies**:
+```bash
+# Create virtual environment with Python 3.13
+uv venv --python 3.13
+
+# Activate virtual environment
+# Windows:
+.venv\Scripts\activate
+# Linux/macOS:
+source .venv/bin/activate
+
+# Install PyTorch with CUDA support
+# Check command line based on your environment: https://pytorch.org/get-started/locally/
+uv pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu130
+
+# Install SeedVR2 requirements
+uv pip install -r requirements.txt
+
+# Run the CLI (display help message)
+# Windows:
+.venv\Scripts\python.exe inference_cli.py --help
+# Linux/macOS:
+.venv/bin/python inference_cli.py --help
+```
+
+### Command Line Usage
+
+The CLI provides comprehensive options for single-GPU, multi-GPU, and batch processing workflows.
+
+**Basic Usage Examples:**
+
+```bash
+# Basic image upscaling
+python inference_cli.py image.jpg
+
+# Basic video upscaling with temporal consistency
+python inference_cli.py video.mp4 --resolution 720 --batch_size 33
+
+# Streaming mode for long videos (memory-efficient) with 10-bit video output (requires FFMPEG)
+# Processes video in chunks of 330 frames to avoid loading entire video into RAM
+# Use --temporal_overlap to ensure smooth transitions between chunks
+python inference_cli.py long_video.mp4 \
+    --resolution 1080 \
+    --batch_size 33 \
+    --chunk_size 330 \
+    --temporal_overlap 3 \
+    --video_backend ffmpeg \
+    --10bit
+
+# Multi-GPU processing with temporal overlap
+python inference_cli.py video.mp4 \
+    --cuda_device 0,1 \
+    --resolution 1080 \
+    --batch_size 81 \
+    --uniform_batch_size \
+    --temporal_overlap 3 \
+    --prepend_frames 4
+
+# Memory-optimized for low VRAM (8GB)
+python inference_cli.py image.png \
+    --dit_model seedvr2_ema_3b-Q8_0.gguf \
+    --resolution 1080 \
+    --blocks_to_swap 32 \
+    --swap_io_components \
+    --dit_offload_device cpu \
+    --vae_offload_device cpu
+
+# High resolution with VAE tiling
+python inference_cli.py video.mp4 \
+    --resolution 1440 \
+    --batch_size 31 \
+    --uniform_batch_size \
+    --temporal_overlap 3 \
+    --vae_encode_tiled \
+    --vae_decode_tiled
+
+# Batch directory processing with model caching
+python inference_cli.py media_folder/ \
+    --output processed/ \
+    --cuda_device 0 \
+    --cache_dit \
+    --cache_vae \
+    --dit_offload_device cpu \
+    --vae_offload_device cpu \
+    --resolution 1080 \
+    --max_resolution 1920
+```
+
+### Command Line Arguments
+
+**Input/Output:**
+- `<input>`: Input file (.mp4, .avi, .png, .jpg, etc.) or directory
+- `--output`: Output path (default: auto-generated in 'output/' directory)
+- `--output_format`: Output format: 'mp4' (video) or 'png' (image sequence). Default: auto-detect from input type
+- `--video_backend`: Video encoder backend: 'opencv' (default) or 'ffmpeg' (requires ffmpeg in PATH)
+- `--10bit`: Save 10-bit video with x265 codec and yuv420p10le pixel format (reduces banding in gradients). Without this flag, ffmpeg uses x264 (yuv420p) for maximum compatibility. Requires --video_backend ffmpeg
+- `--model_dir`: Model directory (default: ./models/SEEDVR2)
+
+**Model Selection:**
+- `--dit_model`: DiT model to use. Options: 3B/7B with fp16/fp8/GGUF variants (default: 3B FP8)
+
+**Processing Parameters:**
+- `--resolution`: Target short-side resolution in pixels (default: 1080)
+- `--max_resolution`: Maximum resolution for any edge. Scales down if exceeded. 0 = no limit (default: 0)
+- `--batch_size`: Frames per batch (must follow 4n+1: 1, 5, 9, 13, 17, 21...). Ideally matches shot length for best temporal consistency (default: 5)
+- `--seed`: Random seed for reproducibility (default: 42)
+- `--skip_first_frames`: Skip N initial frames (default: 0)
+- `--load_cap`: Maximum total frames to load from video. 0 = load all (default: 0)
+- `--chunk_size`: Frames per chunk for streaming mode. When > 0, processes video in memory-bounded chunks of N frames, writing each chunk before loading the next. Essential for long videos that would otherwise exceed RAM. Use with `--temporal_overlap` for seamless chunk transitions. 0 = load all frames at once (default: 0)
+- `--prepend_frames`: Prepend N reversed frames to reduce start artifacts (auto-removed) (default: 0)
+- `--temporal_overlap`: Frames to overlap between batches/GPUs for smooth blending (default: 0)
+
+**Quality Control:**
+- `--color_correction`: Color correction method: 'lab' (perceptual, recommended), 'wavelet', 'wavelet_adaptive', 'hsv', 'adain', or 'none' (default: lab)
+- `--input_noise_scale`: Input noise injection scale (0.0-1.0). Reduces artifacts at high resolutions (default: 0.0)
+- `--latent_noise_scale`: Latent space noise scale (0.0-1.0). Softens details if needed (default: 0.0)
+
+**Memory Management:**
+- `--dit_offload_device`: Device to offload DiT model: 'none' (keep on GPU), 'cpu', or 'cuda:X' (default: none)
+- `--vae_offload_device`: Device to offload VAE model: 'none', 'cpu', or 'cuda:X' (default: none)
+- `--blocks_to_swap`: Number of transformer blocks to swap (0=disabled, 3B: 0-32, 7B: 0-36). Requires dit_offload_device (default: 0). Not available on macOS.
+- `--swap_io_components`: Offload I/O components for additional VRAM savings. Requires dit_offload_device. Not available on macOS.
+
+**VAE Tiling:**
+- `--vae_encode_tiled`: Enable VAE encode tiling to reduce VRAM during encoding
+- `--vae_encode_tile_size`: VAE encode tile size in pixels (default: 1024)
+- `--vae_encode_tile_overlap`: VAE encode tile overlap in pixels (default: 128)
+- `--vae_decode_tiled`: Enable VAE decode tiling to reduce VRAM during decoding
+- `--vae_decode_tile_size`: VAE decode tile size in pixels (default: 1024)
+- `--vae_decode_tile_overlap`: VAE decode tile overlap in pixels (default: 128)
+- `--tile_debug`: Visualize tiles: 'false' (default), 'encode', or 'decode'
+
+**Performance Optimization:**
+- `--allow_vram_overflow`: Allow VRAM overflow to system RAM. Prevents OOM but may cause severe slowdown
+- `--attention_mode`: Attention backend: 'sdpa' (default), 'flash_attn_2' (Ampere+), 'flash_attn_3' (Hopper+), 'sageattn_2', or 'sageattn_3' (Blackwell)
+- `--compile_dit`: Enable torch.compile for DiT model (20-40% speedup, requires PyTorch 2.0+ and Triton)
+- `--compile_vae`: Enable torch.compile for VAE model (15-25% speedup, requires PyTorch 2.0+ and Triton)
+- `--compile_backend`: Compilation backend: 'inductor' (full optimization) or 'cudagraphs' (lightweight) (default: inductor)
+- `--compile_mode`: Optimization level: 'default', 'reduce-overhead', 'max-autotune', 'max-autotune-no-cudagraphs' (default: default)
+- `--compile_fullgraph`: Compile entire model as single graph (faster but less flexible) (default: False)
+- `--compile_dynamic`: Handle varying input shapes without recompilation (default: False)
+- `--compile_dynamo_cache_size_limit`: Max cached compiled versions per function (default: 64)
+- `--compile_dynamo_recompile_limit`: Max recompilation attempts before fallback (default: 128)
+
+**Model Caching (batch processing):**
+- `--cache_dit`: Keep DiT model in memory between generations. Works with single-GPU directory processing or multi-GPU streaming (`--chunk_size`). Requires `--dit_offload_device`
+- `--cache_vae`: Keep VAE model in memory between generations. Works with single-GPU directory processing or multi-GPU streaming (`--chunk_size`). Requires `--vae_offload_device`
+
+**Multi-GPU:**
+- `--cuda_device`: CUDA device id(s). Single id (e.g., '0') or comma-separated list '0,1' for multi-GPU
+
+**Debugging:**
+- `--debug`: Enable verbose debug logging
+
+### Multi-GPU Processing Explained
+
+The CLI's multi-GPU mode uses **frame-level parallelism**: the video is split into chunks and each GPU processes its chunk independently through all 4 phases (encode → upscale → decode → postprocess). This is ideal for long videos where you want to reduce total processing time by dividing the workload.
+
+**How it works:**
+1. Video frames are split evenly across GPUs (e.g., 100 frames on 2 GPUs → 50 frames each)
+2. Each GPU loads its own copy of the models and processes its chunk independently
+3. When `--temporal_overlap` is set, chunks include overlapping frames for seamless blending
+4. Results are concatenated (and blended at overlap regions) into the final video
+
+**Example for 100 frames on 2 GPUs with temporal_overlap=4:**
+```
+GPU 0: Frames 0-53 (50 base + 4 overlap at end, processed as independent video)
+GPU 1: Frames 50-99 (50 frames, 4 overlap at start, processed as independent video)
+Result: Frames 0-99 with smooth blending at the transition point
+```
+
+**Important considerations:**
+- Each GPU processes its chunk as a separate video with its own batch splitting
+- `batch_size` controls batching *within* each GPU's chunk, not across GPUs
+- For short videos (< 100 frames), single GPU is often more efficient due to model loading overhead
+- Multi-GPU doubles VRAM usage (each GPU loads full models) but roughly halves processing time
+
+**When to use multi-GPU:**
+- Long videos (100+ frames) where splitting provides significant time savings
+- When you have multiple GPUs with sufficient VRAM each
+
+**When to use single GPU:**
+- Short videos where model loading overhead outweighs parallel gains
+- When you want all frames processed together for maximum temporal coherence
+
+**Best practices:**
+- Set `--temporal_overlap` to 2-4 frames for smooth blending between GPU chunks
+- Higher overlap = smoother transitions but more redundant processing
+- Use `--prepend_frames` to reduce artifacts at video start
+- For optimal quality on short videos, use single GPU with `batch_size` matching your shot length
+
+## ⚠️ Limitations
+
+### Model Limitations
+
+**Batch Size Constraint**: The model requires batch_size to follow the **4n+1 formula** (1, 5, 9, 13, 17, 21, 25, ...) due to temporal consistency architecture. All frames in a batch are processed together for temporal coherence, then batches can be blended using temporal_overlap. Ideally, set batch_size to match your shot length for optimal quality.
+
+### Performance Considerations
+
+**VAE Bottleneck**: Even with optimized DiT upscaling (BlockSwap, GGUF, torch.compile), the VAE encoding/decoding stages can be the bottleneck, especially for high resolutions. The VAE is slow. Use large batch_size to mitigate this.
+
+**VRAM Usage**: While the integration now supports low VRAM systems (8GB or less with proper optimization), VRAM usage varies based on:
+- Input/output resolution (larger = more VRAM)
+- Batch size (higher = more VRAM but better temporal consistency and speed)
+- Model choice (FP16 > FP8 > GGUF in VRAM usage)
+- Optimization settings (BlockSwap, VAE tiling significantly reduce VRAM)
+
+**Speed**: Processing speed depends on:
+- GPU capabilities (compute performance, VRAM bandwidth, and architecture generation)
+- Model size (3B faster than 7B)
+- Batch size (larger batch sizes are faster per frame due to better GPU utilization)
+- Optimization settings (torch.compile provides significant speedup)
+- Resolution (higher resolutions are slower)
+
+### Best Practices
+
+1. **Start with debug enabled** to understand where VRAM is being used
+2. **For OOM errors during encoding**: Enable VAE encode tiling and reduce tile size
+3. **For OOM errors during upscaling**: Enable BlockSwap and increase blocks_to_swap
+4. **For OOM errors during decoding**: Enable VAE decode tiling and reduce tile size
+   - **If still getting OOM after trying all above**: Reduce batch_size or resolution
+5. **For best quality**: Use higher batch_size matching your shot length, FP16 models, and LAB color correction
+6. **For speed**: Use FP8/GGUF models, enable torch.compile, and use Flash Attention if available
+7. **Test settings with a short clip first** before processing long videos
+
+## 🤝 Contributing
+
+Contributions are welcome! We value community input and improvements.
+
+For detailed contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+**Quick Start:**
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request to the **main** branch
+
+**Get Help:**
+- YouTube: [AInVFX Channel](https://www.youtube.com/@AInVFX)
+- GitHub [Issues](https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler/issues): For bug reports and feature requests
+- GitHub [Discussions](https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler/discussions): For questions and community support
+- Discord: adrientoupet & NumZ#7184
+
+## 🙏 Credits
+
+This ComfyUI implementation is a collaborative project by **[NumZ](https://github.com/numz)** and **[AInVFX](https://www.youtube.com/@AInVFX)** (Adrien Toupet), based on the original [SeedVR2](https://github.com/ByteDance-Seed/SeedVR) by ByteDance Seed Team.
+
+Special thanks to our community contributors including [naxci1](https://github.com/naxci1), [thehhmdb](https://github.com/thehhmdb), [s-cerevisiae](https://github.com/s-cerevisiae), [benjaminherb](https://github.com/benjaminherb), [cmeka](https://github.com/cmeka), [FurkanGozukara](https://github.com/FurkanGozukara), [JohnAlcatraz](https://github.com/JohnAlcatraz), [lihaoyun6](https://github.com/lihaoyun6), [Luchuanzhao](https://github.com/Luchuanzhao), [Luke2642](https://github.com/Luke2642), [proxyid](https://github.com/proxyid), [q5sys](https://github.com/q5sys), and many others for their improvements, bug fixes, and testing.
+
+## 📜 License
+
+The code in this repository is released under the Apache 2.0 license as found in the [LICENSE](LICENSE) file.

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/__init__.py

@@ -0,0 +1,9 @@
+"""
+ComfyUI-SeedVR2_VideoUpscaler
+Official SeedVR2 integration for ComfyUI
+"""
+
+from .src.optimization.compatibility import ensure_triton_compat  # noqa: F401
+from .src.interfaces import comfy_entrypoint, SeedVR2Extension
+
+__all__ = ["comfy_entrypoint", "SeedVR2Extension"]

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/configs_3b/main.yaml

@@ -0,0 +1,91 @@
+__object__:
+  path: projects.video_diffusion_sr.train
+  name: VideoDiffusionTrainer
+
+dit:
+  model:
+    __object__:
+      path: "dit_3b.nadit"
+      name: "NaDiT"
+      args: "as_params"
+    vid_in_channels: 33
+    vid_out_channels: 16
+    vid_dim: 2560
+    vid_out_norm: fusedrms
+    txt_in_dim: 5120
+    txt_in_norm: fusedln
+    txt_dim: ${.vid_dim}
+    emb_dim: ${eval:'6 * ${.vid_dim}'}
+    heads: 20
+    head_dim: 128 # llm-like
+    expand_ratio: 4
+    norm: fusedrms
+    norm_eps: 1.0e-05
+    ada: single
+    qk_bias: False
+    qk_norm: fusedrms
+    patch_size: [1, 2, 2]
+    num_layers: 32 # llm-like
+    mm_layers: 10
+    mlp_type: swiglu
+    msa_type: None
+    block_type: ${eval:'${.num_layers} * ["mmdit_sr"]'} # space-full
+    window: ${eval:'${.num_layers} * [(4,3,3)]'} # space-full
+    window_method: ${eval:'${.num_layers} // 2 * ["720pwin_by_size_bysize","720pswin_by_size_bysize"]'} # space-full
+    rope_type: mmrope3d
+    rope_dim: 128
+  compile: False
+  gradient_checkpoint: True
+  fsdp:
+    sharding_strategy: _HYBRID_SHARD_ZERO2
+
+ema:
+  decay: 0.9998
+
+vae:
+  model:
+    __object__:
+      path: "video_vae_v3.modules.attn_video_vae"
+      name: "VideoAutoencoderKLWrapper"
+      args: "as_params"
+    freeze_encoder: False
+    gradient_checkpoint: True # Disabled to prevent VRAM leaks in inference
+  slicing:
+    split_size: 4
+    memory_device: same
+  memory_limit:
+    conv_max_mem: 0.5
+    norm_max_mem: 0.5
+  checkpoint: ema_vae_fp16.safetensors
+  scaling_factor: 0.9152
+  compile: False
+  grouping: False
+  dtype: float16
+
+diffusion:
+  schedule:
+    type: lerp
+    T: 1000.0
+  sampler:
+    type: euler
+    prediction_type: v_lerp
+  timesteps:
+    training:
+      type: logitnormal
+      loc: 0.0
+      scale: 1.0
+    sampling:
+      type: uniform_trailing
+      steps: 50
+    transform: True
+  loss:
+    type: v_lerp
+  cfg:
+    scale: 7.5
+    rescale: 0
+
+condition:
+  i2v: 0.0
+  v2v: 0.0
+  sr: 1.0
+  noise_scale: 0.25

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/configs_7b/main.yaml

@@ -0,0 +1,88 @@
+__object__:
+  path: projects.video_diffusion_sr.train
+  name: VideoDiffusionTrainer
+
+dit:
+  model:
+    __object__:
+      path: "dit_7b.nadit"
+      name: "NaDiT"
+      args: "as_params"
+    vid_in_channels: 33
+    vid_out_channels: 16
+    vid_dim: 3072
+    txt_in_dim: 5120
+    txt_dim: ${.vid_dim}
+    emb_dim: ${eval:'6 * ${.vid_dim}'}
+    heads: 24
+    head_dim: 128 # llm-like
+    expand_ratio: 4
+    norm: fusedrms
+    norm_eps: 1e-5
+    ada: single
+    qk_bias: False
+    qk_rope: True
+    qk_norm: fusedrms
+    patch_size: [1, 2, 2]
+    num_layers: 36 # llm-like
+    shared_mlp: False
+    shared_qkv: False
+    mlp_type: normal
+    block_type: ${eval:'${.num_layers} * ["mmdit_sr"]'} # space-full
+    window: ${eval:'${.num_layers} * [(4,3,3)]'} # space-full
+    window_method: ${eval:'${.num_layers} // 2 * ["720pwin_by_size_bysize","720pswin_by_size_bysize"]'} # space-full
+  compile: False
+  gradient_checkpoint: True
+  fsdp:
+    sharding_strategy: _HYBRID_SHARD_ZERO2
+
+ema:
+  decay: 0.9998
+
+vae:
+  model:
+    __object__:
+      path: "video_vae_v3.modules.attn_video_vae"
+      name: "VideoAutoencoderKLWrapper"
+      args: "as_params"
+    freeze_encoder: False
+    # gradient_checkpoint: True
+  slicing:
+    split_size: 4
+    memory_device: same
+  memory_limit:
+    conv_max_mem: 0.5
+    norm_max_mem: 0.5
+  checkpoint: ema_vae_fp16.safetensors
+  scaling_factor: 0.9152
+  compile: False
+  grouping: False
+  dtype: float16
+
+diffusion:
+  schedule:
+    type: lerp
+    T: 1000.0
+  sampler:
+    type: euler
+    prediction_type: v_lerp
+  timesteps:
+    training:
+      type: logitnormal
+      loc: 0.0
+      scale: 1.0
+    sampling:
+      type: uniform_trailing
+      steps: 50
+    transform: True
+  loss:
+    type: v_lerp
+  cfg:
+    scale: 7.5
+    rescale: 0
+
+condition:
+  i2v: 0.0
+  v2v: 0.0
+  sr: 1.0
+  noise_scale: 0.25

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/example_workflows/SeedVR2_4K_image_upscale.json

@@ -0,0 +1 @@
+{"id":"e2c8e6ec-9e8a-4a81-a240-7e7d2befc2bf","revision":0,"last_node_id":20,"last_link_id":19,"nodes":[{"id":19,"type":"SeedVR2TorchCompileSettings","pos":[-366.25065217175177,401.8303561599628],"size":[307.671484375,178],"flags":{},"order":0,"mode":4,"inputs":[{"localized_name":"backend","name":"backend","type":"COMBO","widget":{"name":"backend"},"link":null},{"localized_name":"mode","name":"mode","type":"COMBO","widget":{"name":"mode"},"link":null},{"localized_name":"fullgraph","name":"fullgraph","type":"BOOLEAN","widget":{"name":"fullgraph"},"link":null},{"localized_name":"dynamic","name":"dynamic","type":"BOOLEAN","widget":{"name":"dynamic"},"link":null},{"localized_name":"dynamo_cache_size_limit","name":"dynamo_cache_size_limit","type":"INT","widget":{"name":"dynamo_cache_size_limit"},"link":null},{"localized_name":"dynamo_recompile_limit","name":"dynamo_recompile_limit","type":"INT","widget":{"name":"dynamo_recompile_limit"},"link":null}],"outputs":[{"localized_name":"TORCH_COMPILE_ARGS","name":"TORCH_COMPILE_ARGS","type":"TORCH_COMPILE_ARGS","links":[18,19]}],"properties":{"aux_id":"ainvfx/ComfyUI-SeedVR2_VideoUpscaler","ver":"690cc39379c1481159ddd451368dbf2295930fc6","Node name for S&R":"SeedVR2TorchCompileSettings"},"widgets_values":["inductor","default",false,false,64,128]},{"id":18,"type":"Note","pos":[420.71483854947945,-81.0108307454865],"size":[210,94.05179298404067],"flags":{},"order":1,"mode":0,"inputs":[],"outputs":[],"properties":{},"widgets_values":["Enable to upscale alpha/mask channel along with RGB channel (for RGBA inputs)"],"color":"#432","bgcolor":"#653"},{"id":16,"type":"LoadImage","pos":[80.5773583147188,-182.2697173004957],"size":[274.080078125,314],"flags":{},"order":3,"mode":0,"inputs":[{"localized_name":"image","name":"image","type":"COMBO","widget":{"name":"image"},"link":null},{"localized_name":"choose file to upload","name":"upload","type":"IMAGEUPLOAD","widget":{"name":"upload"},"link":null}],"outputs":[{"localized_name":"IMAGE","name":"IMAGE","type":"IMAGE","links":[14]},{"localized_name":"MASK","name":"MASK","type":"MASK","links":[17]}],"properties":{"cnr_id":"comfy-core","ver":"0.3.68","Node name for S&R":"LoadImage"},"widgets_values":["Sadhu_320x478.png","image"]},{"id":14,"type":"SeedVR2LoadDiTModel","pos":[64.4234520647185,212.7072358245033],"size":[307.6646484375,202],"flags":{},"order":4,"mode":0,"inputs":[{"localized_name":"torch_compile_args","name":"torch_compile_args","shape":7,"type":"TORCH_COMPILE_ARGS","link":18},{"localized_name":"model","name":"model","type":"COMBO","widget":{"name":"model"},"link":null},{"localized_name":"device","name":"device","type":"COMBO","widget":{"name":"device"},"link":null},{"localized_name":"blocks_to_swap","name":"blocks_to_swap","shape":7,"type":"INT","widget":{"name":"blocks_to_swap"},"link":null},{"localized_name":"swap_io_components","name":"swap_io_components","shape":7,"type":"BOOLEAN","widget":{"name":"swap_io_components"},"link":null},{"localized_name":"offload_device","name":"offload_device","shape":7,"type":"COMBO","widget":{"name":"offload_device"},"link":null},{"localized_name":"cache_model","name":"cache_model","shape":7,"type":"BOOLEAN","widget":{"name":"cache_model"},"link":null},{"localized_name":"attention_mode","name":"attention_mode","shape":7,"type":"COMBO","widget":{"name":"attention_mode"},"link":null}],"outputs":[{"localized_name":"SEEDVR2_DIT","name":"SEEDVR2_DIT","type":"SEEDVR2_DIT","links":[11]}],"properties":{"aux_id":"ainvfx/ComfyUI-SeedVR2_VideoUpscaler","ver":"690cc39379c1481159ddd451368dbf2295930fc6","Node name for S&R":"SeedVR2LoadDiTModel"},"widgets_values":["seedvr2_ema_7b_sharp_fp16.safetensors","cuda:0",36,false,"cpu",false,"sdpa"]},{"id":13,"type":"SeedVR2LoadVAEModel","pos":[60.33985831471847,499.8798920745057],"size":[312.866796875,298],"flags":{},"order":5,"mode":0,"inputs":[{"localized_name":"torch_compile_args","name":"torch_compile_args","shape":7,"type":"TORCH_COMPILE_ARGS","link":19},{"localized_name":"model","name":"model","type":"COMBO","widget":{"name":"model"},"link":null},{"localized_name":"device","name":"device","type":"COMBO","widget":{"name":"device"},"link":null},{"localized_name":"encode_tiled","name":"encode_tiled","shape":7,"type":"BOOLEAN","widget":{"name":"encode_tiled"},"link":null},{"localized_name":"encode_tile_size","name":"encode_tile_size","shape":7,"type":"INT","widget":{"name":"encode_tile_size"},"link":null},{"localized_name":"encode_tile_overlap","name":"encode_tile_overlap","shape":7,"type":"INT","widget":{"name":"encode_tile_overlap"},"link":null},{"localized_name":"decode_tiled","name":"decode_tiled","shape":7,"type":"BOOLEAN","widget":{"name":"decode_tiled"},"link":null},{"localized_name":"decode_tile_size","name":"decode_tile_size","shape":7,"type":"INT","widget":{"name":"decode_tile_size"},"link":null},{"localized_name":"decode_tile_overlap","name":"decode_tile_overlap","shape":7,"type":"INT","widget":{"name":"decode_tile_overlap"},"link":null},{"localized_name":"tile_debug","name":"tile_debug","shape":7,"type":"COMBO","widget":{"name":"tile_debug"},"link":null},{"localized_name":"offload_device","name":"offload_device","shape":7,"type":"COMBO","widget":{"name":"offload_device"},"link":null},{"localized_name":"cache_model","name":"cache_model","shape":7,"type":"BOOLEAN","widget":{"name":"cache_model"},"link":null}],"outputs":[{"localized_name":"SEEDVR2_VAE","name":"SEEDVR2_VAE","type":"SEEDVR2_VAE","links":[10]}],"properties":{"aux_id":"ainvfx/ComfyUI-SeedVR2_VideoUpscaler","ver":"690cc39379c1481159ddd451368dbf2295930fc6","Node name for S&R":"SeedVR2LoadVAEModel"},"widgets_values":["ema_vae_fp16.safetensors","cuda:0",true,1024,128,true,1024,128,"false","cpu",false]},{"id":10,"type":"SeedVR2VideoUpscaler","pos":[843.8992333147189,191.3224701995034],"size":[270,386],"flags":{},"order":7,"mode":0,"inputs":[{"localized_name":"image","name":"image","type":"IMAGE","link":16},{"localized_name":"dit","name":"dit","type":"SEEDVR2_DIT","link":11},{"localized_name":"vae","name":"vae","type":"SEEDVR2_VAE","link":10},{"localized_name":"seed","name":"seed","type":"INT","widget":{"name":"seed"},"link":null},{"localized_name":"resolution","name":"resolution","type":"INT","widget":{"name":"resolution"},"link":null},{"localized_name":"max_resolution","name":"max_resolution","type":"INT","widget":{"name":"max_resolution"},"link":null},{"localized_name":"batch_size","name":"batch_size","type":"INT","widget":{"name":"batch_size"},"link":null},{"localized_name":"uniform_batch_size","name":"uniform_batch_size","type":"BOOLEAN","widget":{"name":"uniform_batch_size"},"link":null},{"localized_name":"color_correction","name":"color_correction","type":"COMBO","widget":{"name":"color_correction"},"link":null},{"localized_name":"temporal_overlap","name":"temporal_overlap","shape":7,"type":"INT","widget":{"name":"temporal_overlap"},"link":null},{"localized_name":"prepend_frames","name":"prepend_frames","shape":7,"type":"INT","widget":{"name":"prepend_frames"},"link":null},{"localized_name":"input_noise_scale","name":"input_noise_scale","shape":7,"type":"FLOAT","widget":{"name":"input_noise_scale"},"link":null},{"localized_name":"latent_noise_scale","name":"latent_noise_scale","shape":7,"type":"FLOAT","widget":{"name":"latent_noise_scale"},"link":null},{"localized_name":"offload_device","name":"offload_device","shape":7,"type":"COMBO","widget":{"name":"offload_device"},"link":null},{"localized_name":"enable_debug","name":"enable_debug","shape":7,"type":"BOOLEAN","widget":{"name":"enable_debug"},"link":null}],"outputs":[{"localized_name":"IMAGE","name":"IMAGE","type":"IMAGE","links":[12]}],"properties":{"aux_id":"ainvfx/ComfyUI-SeedVR2_VideoUpscaler","ver":"690cc39379c1481159ddd451368dbf2295930fc6","Node name for S&R":"SeedVR2VideoUpscaler"},"widgets_values":[42,"fixed",4096,4096,1,false,"lab",0,0,0,0,"cpu",false]},{"id":17,"type":"JoinImageWithAlpha","pos":[449.4979840435381,-180.32741340177097],"size":[176.86484375,46],"flags":{},"order":6,"mode":0,"inputs":[{"localized_name":"image","name":"image","type":"IMAGE","link":14},{"localized_name":"alpha","name":"alpha","type":"MASK","link":17}],"outputs":[{"localized_name":"IMAGE","name":"IMAGE","type":"IMAGE","links":[16]}],"properties":{"cnr_id":"comfy-core","ver":"0.3.68","Node name for S&R":"JoinImageWithAlpha"},"widgets_values":[]},{"id":15,"type":"SaveImage","pos":[1167.7234520647182,192.0920014495034],"size":[270,270],"flags":{},"order":8,"mode":0,"inputs":[{"localized_name":"images","name":"images","type":"IMAGE","link":12},{"localized_name":"filename_prefix","name":"filename_prefix","type":"STRING","widget":{"name":"filename_prefix"},"link":null}],"outputs":[],"properties":{"cnr_id":"comfy-core","ver":"0.3.68"},"widgets_values":["ComfyUI"]},{"id":20,"type":"Note","pos":[-353.44461861972593,641.0883773827939],"size":[290.1922351462714,97.95592567265356],"flags":{},"order":2,"mode":0,"inputs":[],"outputs":[],"properties":{},"widgets_values":["Enable torch.compile optimization. First batch has compilation overhead, but speeds up subsequent batches. Best for long videos, not single images."],"color":"#432","bgcolor":"#653"}],"links":[[10,13,0,10,2,"SEEDVR2_VAE"],[11,14,0,10,1,"SEEDVR2_DIT"],[12,10,0,15,0,"IMAGE"],[14,16,0,17,0,"IMAGE"],[16,17,0,10,0,"IMAGE"],[17,16,1,17,1,"MASK"],[18,19,0,14,0,"TORCH_COMPILE_ARGS"],[19,19,0,13,0,"TORCH_COMPILE_ARGS"]],"groups":[],"config":{},"extra":{"ds":{"scale":0.6934334949441353,"offset":[1011.3669791186508,462.16171611318566]}},"version":0.4}

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/example_workflows/SeedVR2_HD_video_upscale.json

@@ -0,0 +1 @@
+{"id":"e2c8e6ec-9e8a-4a81-a240-7e7d2befc2bf","revision":0,"last_node_id":24,"last_link_id":25,"nodes":[{"id":17,"type":"JoinImageWithAlpha","pos":[415.46463925106394,-269.3527671179127],"size":[176.86484375,46],"flags":{},"order":7,"mode":4,"inputs":[{"localized_name":"image","name":"image","type":"IMAGE","link":21},{"localized_name":"alpha","name":"alpha","type":"MASK","link":null}],"outputs":[{"localized_name":"IMAGE","name":"IMAGE","type":"IMAGE","links":[16]}],"properties":{"cnr_id":"comfy-core","ver":"0.3.68","Node name for S&R":"JoinImageWithAlpha"},"widgets_values":[]},{"id":19,"type":"SeedVR2TorchCompileSettings","pos":[-369.50847923647007,315.0949953354577],"size":[307.671484375,178],"flags":{},"order":0,"mode":4,"inputs":[{"localized_name":"backend","name":"backend","type":"COMBO","widget":{"name":"backend"},"link":null},{"localized_name":"mode","name":"mode","type":"COMBO","widget":{"name":"mode"},"link":null},{"localized_name":"fullgraph","name":"fullgraph","type":"BOOLEAN","widget":{"name":"fullgraph"},"link":null},{"localized_name":"dynamic","name":"dynamic","type":"BOOLEAN","widget":{"name":"dynamic"},"link":null},{"localized_name":"dynamo_cache_size_limit","name":"dynamo_cache_size_limit","type":"INT","widget":{"name":"dynamo_cache_size_limit"},"link":null},{"localized_name":"dynamo_recompile_limit","name":"dynamo_recompile_limit","type":"INT","widget":{"name":"dynamo_recompile_limit"},"link":null}],"outputs":[{"localized_name":"TORCH_COMPILE_ARGS","name":"TORCH_COMPILE_ARGS","type":"TORCH_COMPILE_ARGS","links":[18,19]}],"properties":{"aux_id":"ainvfx/ComfyUI-SeedVR2_VideoUpscaler","ver":"690cc39379c1481159ddd451368dbf2295930fc6","Node name for S&R":"SeedVR2TorchCompileSettings"},"widgets_values":["inductor","default",false,false,64,128]},{"id":20,"type":"Note","pos":[-358.9923959032341,553.3187800066305],"size":[290.1922351462714,97.95592567265356],"flags":{},"order":1,"mode":0,"inputs":[],"outputs":[],"properties":{},"widgets_values":["Enable torch.compile optimization. First batch has compilation overhead, but speeds up subsequent batches. Best for long videos, not single images."],"color":"#432","bgcolor":"#653"},{"id":21,"type":"LoadVideo","pos":[-201.66033140975628,-266.86977401462417],"size":[274.080078125,228.1700439453125],"flags":{},"order":2,"mode":0,"inputs":[{"localized_name":"file","name":"file","type":"COMBO","widget":{"name":"file"},"link":null},{"localized_name":"choose file to upload","name":"upload","type":"IMAGEUPLOAD","widget":{"name":"upload"},"link":null}],"outputs":[{"localized_name":"VIDEO","name":"VIDEO","type":"VIDEO","links":[20]}],"properties":{"cnr_id":"comfy-core","ver":"0.3.68","Node name for S&R":"LoadVideo"},"widgets_values":["Mustache_640x360.mp4","image"]},{"id":18,"type":"Note","pos":[417.45701148476115,-167.7461915699906],"size":[210,94.05179298404067],"flags":{},"order":3,"mode":0,"inputs":[],"outputs":[],"properties":{},"widgets_values":["Enable + connect input alpha to upscale alpha/mask channel along with RGB channel (for RGBA inputs)"],"color":"#432","bgcolor":"#653"},{"id":24,"type":"CreateVideo","pos":[1171.8133710326213,102.33318716823825],"size":[270,78],"flags":{},"order":9,"mode":0,"inputs":[{"localized_name":"images","name":"images","type":"IMAGE","link":22},{"localized_name":"audio","name":"audio","shape":7,"type":"AUDIO","link":25},{"localized_name":"fps","name":"fps","type":"FLOAT","widget":{"name":"fps"},"link":24}],"outputs":[{"localized_name":"VIDEO","name":"VIDEO","type":"VIDEO","links":[23]}],"properties":{"cnr_id":"comfy-core","ver":"0.3.68","Node name for S&R":"CreateVideo"},"widgets_values":[30]},{"id":23,"type":"SaveVideo","pos":[1499.476781650457,101.92559527677722],"size":[270,249.875],"flags":{},"order":10,"mode":0,"inputs":[{"localized_name":"video","name":"video","type":"VIDEO","link":23},{"localized_name":"filename_prefix","name":"filename_prefix","type":"STRING","widget":{"name":"filename_prefix"},"link":null},{"localized_name":"format","name":"format","type":"COMBO","widget":{"name":"format"},"link":null},{"localized_name":"codec","name":"codec","type":"COMBO","widget":{"name":"codec"},"link":null}],"outputs":[],"properties":{"cnr_id":"comfy-core","ver":"0.3.68","Node name for S&R":"SaveVideo"},"widgets_values":["video/ComfyUI","auto","auto"]},{"id":22,"type":"GetVideoComponents","pos":[149.28727188425574,-267.41033914727126],"size":[185.17734375,66],"flags":{},"order":6,"mode":0,"inputs":[{"localized_name":"video","name":"video","type":"VIDEO","link":20}],"outputs":[{"localized_name":"images","name":"images","type":"IMAGE","links":[21]},{"localized_name":"audio","name":"audio","type":"AUDIO","links":[25]},{"localized_name":"fps","name":"fps","type":"FLOAT","links":[24]}],"properties":{"cnr_id":"comfy-core","ver":"0.3.68","Node name for S&R":"GetVideoComponents"},"widgets_values":[]},{"id":13,"type":"SeedVR2LoadVAEModel","pos":[57.08203125,413.14453125],"size":[312.866796875,298],"flags":{},"order":5,"mode":0,"inputs":[{"localized_name":"torch_compile_args","name":"torch_compile_args","shape":7,"type":"TORCH_COMPILE_ARGS","link":19},{"localized_name":"model","name":"model","type":"COMBO","widget":{"name":"model"},"link":null},{"localized_name":"device","name":"device","type":"COMBO","widget":{"name":"device"},"link":null},{"localized_name":"encode_tiled","name":"encode_tiled","shape":7,"type":"BOOLEAN","widget":{"name":"encode_tiled"},"link":null},{"localized_name":"encode_tile_size","name":"encode_tile_size","shape":7,"type":"INT","widget":{"name":"encode_tile_size"},"link":null},{"localized_name":"encode_tile_overlap","name":"encode_tile_overlap","shape":7,"type":"INT","widget":{"name":"encode_tile_overlap"},"link":null},{"localized_name":"decode_tiled","name":"decode_tiled","shape":7,"type":"BOOLEAN","widget":{"name":"decode_tiled"},"link":null},{"localized_name":"decode_tile_size","name":"decode_tile_size","shape":7,"type":"INT","widget":{"name":"decode_tile_size"},"link":null},{"localized_name":"decode_tile_overlap","name":"decode_tile_overlap","shape":7,"type":"INT","widget":{"name":"decode_tile_overlap"},"link":null},{"localized_name":"tile_debug","name":"tile_debug","shape":7,"type":"COMBO","widget":{"name":"tile_debug"},"link":null},{"localized_name":"offload_device","name":"offload_device","shape":7,"type":"COMBO","widget":{"name":"offload_device"},"link":null},{"localized_name":"cache_model","name":"cache_model","shape":7,"type":"BOOLEAN","widget":{"name":"cache_model"},"link":null}],"outputs":[{"localized_name":"SEEDVR2_VAE","name":"SEEDVR2_VAE","type":"SEEDVR2_VAE","links":[10]}],"properties":{"aux_id":"ainvfx/ComfyUI-SeedVR2_VideoUpscaler","ver":"690cc39379c1481159ddd451368dbf2295930fc6","Node name for S&R":"SeedVR2LoadVAEModel"},"widgets_values":["ema_vae_fp16.safetensors","cuda:0",true,1024,128,true,768,128,"false","cpu",false]},{"id":10,"type":"SeedVR2VideoUpscaler","pos":[840.6414062499999,104.58710937499997],"size":[270,386],"flags":{},"order":8,"mode":0,"inputs":[{"localized_name":"image","name":"image","type":"IMAGE","link":16},{"localized_name":"dit","name":"dit","type":"SEEDVR2_DIT","link":11},{"localized_name":"vae","name":"vae","type":"SEEDVR2_VAE","link":10},{"localized_name":"seed","name":"seed","type":"INT","widget":{"name":"seed"},"link":null},{"localized_name":"resolution","name":"resolution","type":"INT","widget":{"name":"resolution"},"link":null},{"localized_name":"max_resolution","name":"max_resolution","type":"INT","widget":{"name":"max_resolution"},"link":null},{"localized_name":"batch_size","name":"batch_size","type":"INT","widget":{"name":"batch_size"},"link":null},{"localized_name":"uniform_batch_size","name":"uniform_batch_size","type":"BOOLEAN","widget":{"name":"uniform_batch_size"},"link":null},{"localized_name":"color_correction","name":"color_correction","type":"COMBO","widget":{"name":"color_correction"},"link":null},{"localized_name":"temporal_overlap","name":"temporal_overlap","shape":7,"type":"INT","widget":{"name":"temporal_overlap"},"link":null},{"localized_name":"prepend_frames","name":"prepend_frames","shape":7,"type":"INT","widget":{"name":"prepend_frames"},"link":null},{"localized_name":"input_noise_scale","name":"input_noise_scale","shape":7,"type":"FLOAT","widget":{"name":"input_noise_scale"},"link":null},{"localized_name":"latent_noise_scale","name":"latent_noise_scale","shape":7,"type":"FLOAT","widget":{"name":"latent_noise_scale"},"link":null},{"localized_name":"offload_device","name":"offload_device","shape":7,"type":"COMBO","widget":{"name":"offload_device"},"link":null},{"localized_name":"enable_debug","name":"enable_debug","shape":7,"type":"BOOLEAN","widget":{"name":"enable_debug"},"link":null}],"outputs":[{"localized_name":"IMAGE","name":"IMAGE","type":"IMAGE","links":[22]}],"properties":{"aux_id":"ainvfx/ComfyUI-SeedVR2_VideoUpscaler","ver":"690cc39379c1481159ddd451368dbf2295930fc6","Node name for S&R":"SeedVR2VideoUpscaler"},"widgets_values":[42,"fixed",1080,0,33,true,"lab",3,0,0,0,"cpu",false]},{"id":14,"type":"SeedVR2LoadDiTModel","pos":[61.165625,125.97187500000004],"size":[307.6646484375,202],"flags":{},"order":4,"mode":0,"inputs":[{"localized_name":"torch_compile_args","name":"torch_compile_args","shape":7,"type":"TORCH_COMPILE_ARGS","link":18},{"localized_name":"model","name":"model","type":"COMBO","widget":{"name":"model"},"link":null},{"localized_name":"device","name":"device","type":"COMBO","widget":{"name":"device"},"link":null},{"localized_name":"blocks_to_swap","name":"blocks_to_swap","shape":7,"type":"INT","widget":{"name":"blocks_to_swap"},"link":null},{"localized_name":"swap_io_components","name":"swap_io_components","shape":7,"type":"BOOLEAN","widget":{"name":"swap_io_components"},"link":null},{"localized_name":"offload_device","name":"offload_device","shape":7,"type":"COMBO","widget":{"name":"offload_device"},"link":null},{"localized_name":"cache_model","name":"cache_model","shape":7,"type":"BOOLEAN","widget":{"name":"cache_model"},"link":null},{"localized_name":"attention_mode","name":"attention_mode","shape":7,"type":"COMBO","widget":{"name":"attention_mode"},"link":null}],"outputs":[{"localized_name":"SEEDVR2_DIT","name":"SEEDVR2_DIT","type":"SEEDVR2_DIT","links":[11]}],"properties":{"aux_id":"ainvfx/ComfyUI-SeedVR2_VideoUpscaler","ver":"690cc39379c1481159ddd451368dbf2295930fc6","Node name for S&R":"SeedVR2LoadDiTModel"},"widgets_values":["seedvr2_ema_3b_fp16.safetensors","cuda:0",32,false,"cpu",false,"sdpa"]}],"links":[[10,13,0,10,2,"SEEDVR2_VAE"],[11,14,0,10,1,"SEEDVR2_DIT"],[16,17,0,10,0,"IMAGE"],[18,19,0,14,0,"TORCH_COMPILE_ARGS"],[19,19,0,13,0,"TORCH_COMPILE_ARGS"],[20,21,0,22,0,"VIDEO"],[21,22,0,17,0,"IMAGE"],[22,10,0,24,0,"IMAGE"],[23,24,0,23,0,"VIDEO"],[24,22,2,24,2,"FLOAT"],[25,22,1,24,1,"AUDIO"]],"groups":[],"config":{},"extra":{"ds":{"scale":0.8441465687687482,"offset":[739.339356050958,625.120941260255]}},"version":0.4}

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/example_workflows/SeedVR2_simple_image_upscale.json

@@ -0,0 +1 @@
+{"id":"e2c8e6ec-9e8a-4a81-a240-7e7d2befc2bf","revision":0,"last_node_id":20,"last_link_id":19,"nodes":[{"id":16,"type":"LoadImage","pos":[529.6515751584279,98.66389637266899],"size":[274.080078125,314],"flags":{},"order":0,"mode":0,"inputs":[{"localized_name":"image","name":"image","type":"COMBO","widget":{"name":"image"},"link":null},{"localized_name":"choose file to upload","name":"upload","type":"IMAGEUPLOAD","widget":{"name":"upload"},"link":null}],"outputs":[{"localized_name":"IMAGE","name":"IMAGE","type":"IMAGE","links":[14]},{"localized_name":"MASK","name":"MASK","type":"MASK","links":[17]}],"properties":{"cnr_id":"comfy-core","ver":"0.3.68","Node name for S&R":"LoadImage"},"widgets_values":["example.png","image"]},{"id":17,"type":"JoinImageWithAlpha","pos":[867.7966831594896,98.31620737975611],"size":[176.86484375,46],"flags":{},"order":4,"mode":4,"inputs":[{"localized_name":"image","name":"image","type":"IMAGE","link":14},{"localized_name":"alpha","name":"alpha","type":"MASK","link":17}],"outputs":[{"localized_name":"IMAGE","name":"IMAGE","type":"IMAGE","links":[16]}],"properties":{"cnr_id":"comfy-core","ver":"0.3.68","Node name for S&R":"JoinImageWithAlpha"},"widgets_values":[]},{"id":19,"type":"SeedVR2TorchCompileSettings","pos":[82.82356467195704,682.7639698331246],"size":[307.671484375,178],"flags":{},"order":1,"mode":4,"inputs":[{"localized_name":"backend","name":"backend","type":"COMBO","widget":{"name":"backend"},"link":null},{"localized_name":"mode","name":"mode","type":"COMBO","widget":{"name":"mode"},"link":null},{"localized_name":"fullgraph","name":"fullgraph","type":"BOOLEAN","widget":{"name":"fullgraph"},"link":null},{"localized_name":"dynamic","name":"dynamic","type":"BOOLEAN","widget":{"name":"dynamic"},"link":null},{"localized_name":"dynamo_cache_size_limit","name":"dynamo_cache_size_limit","type":"INT","widget":{"name":"dynamo_cache_size_limit"},"link":null},{"localized_name":"dynamo_recompile_limit","name":"dynamo_recompile_limit","type":"INT","widget":{"name":"dynamo_recompile_limit"},"link":null}],"outputs":[{"localized_name":"TORCH_COMPILE_ARGS","name":"TORCH_COMPILE_ARGS","type":"TORCH_COMPILE_ARGS","links":[18,19]}],"properties":{"aux_id":"ainvfx/ComfyUI-SeedVR2_VideoUpscaler","ver":"690cc39379c1481159ddd451368dbf2295930fc6","Node name for S&R":"SeedVR2TorchCompileSettings"},"widgets_values":["inductor","default",false,false,64,128]},{"id":13,"type":"SeedVR2LoadVAEModel","pos":[509.41407515842775,780.813505747667],"size":[312.866796875,298],"flags":{},"order":6,"mode":0,"inputs":[{"localized_name":"torch_compile_args","name":"torch_compile_args","shape":7,"type":"TORCH_COMPILE_ARGS","link":19},{"localized_name":"model","name":"model","type":"COMBO","widget":{"name":"model"},"link":null},{"localized_name":"device","name":"device","type":"COMBO","widget":{"name":"device"},"link":null},{"localized_name":"encode_tiled","name":"encode_tiled","shape":7,"type":"BOOLEAN","widget":{"name":"encode_tiled"},"link":null},{"localized_name":"encode_tile_size","name":"encode_tile_size","shape":7,"type":"INT","widget":{"name":"encode_tile_size"},"link":null},{"localized_name":"encode_tile_overlap","name":"encode_tile_overlap","shape":7,"type":"INT","widget":{"name":"encode_tile_overlap"},"link":null},{"localized_name":"decode_tiled","name":"decode_tiled","shape":7,"type":"BOOLEAN","widget":{"name":"decode_tiled"},"link":null},{"localized_name":"decode_tile_size","name":"decode_tile_size","shape":7,"type":"INT","widget":{"name":"decode_tile_size"},"link":null},{"localized_name":"decode_tile_overlap","name":"decode_tile_overlap","shape":7,"type":"INT","widget":{"name":"decode_tile_overlap"},"link":null},{"localized_name":"tile_debug","name":"tile_debug","shape":7,"type":"COMBO","widget":{"name":"tile_debug"},"link":null},{"localized_name":"offload_device","name":"offload_device","shape":7,"type":"COMBO","widget":{"name":"offload_device"},"link":null},{"localized_name":"cache_model","name":"cache_model","shape":7,"type":"BOOLEAN","widget":{"name":"cache_model"},"link":null}],"outputs":[{"localized_name":"SEEDVR2_VAE","name":"SEEDVR2_VAE","type":"SEEDVR2_VAE","links":[10]}],"properties":{"aux_id":"ainvfx/ComfyUI-SeedVR2_VideoUpscaler","ver":"690cc39379c1481159ddd451368dbf2295930fc6","Node name for S&R":"SeedVR2LoadVAEModel"},"widgets_values":["ema_vae_fp16.safetensors","cuda:0",false,1024,128,false,1024,128,"false","none",false]},{"id":14,"type":"SeedVR2LoadDiTModel","pos":[513.4976689084277,493.64084949766976],"size":[307.6646484375,202],"flags":{},"order":5,"mode":0,"inputs":[{"localized_name":"torch_compile_args","name":"torch_compile_args","shape":7,"type":"TORCH_COMPILE_ARGS","link":18},{"localized_name":"model","name":"model","type":"COMBO","widget":{"name":"model"},"link":null},{"localized_name":"device","name":"device","type":"COMBO","widget":{"name":"device"},"link":null},{"localized_name":"blocks_to_swap","name":"blocks_to_swap","shape":7,"type":"INT","widget":{"name":"blocks_to_swap"},"link":null},{"localized_name":"swap_io_components","name":"swap_io_components","shape":7,"type":"BOOLEAN","widget":{"name":"swap_io_components"},"link":null},{"localized_name":"offload_device","name":"offload_device","shape":7,"type":"COMBO","widget":{"name":"offload_device"},"link":null},{"localized_name":"cache_model","name":"cache_model","shape":7,"type":"BOOLEAN","widget":{"name":"cache_model"},"link":null},{"localized_name":"attention_mode","name":"attention_mode","shape":7,"type":"COMBO","widget":{"name":"attention_mode"},"link":null}],"outputs":[{"localized_name":"SEEDVR2_DIT","name":"SEEDVR2_DIT","type":"SEEDVR2_DIT","links":[11]}],"properties":{"aux_id":"ainvfx/ComfyUI-SeedVR2_VideoUpscaler","ver":"690cc39379c1481159ddd451368dbf2295930fc6","Node name for S&R":"SeedVR2LoadDiTModel"},"widgets_values":["seedvr2_ema_3b_fp8_e4m3fn.safetensors","cuda:0",0,false,"none",false,"sdpa"]},{"id":18,"type":"Note","pos":[869.7890553931869,199.9227829276786],"size":[210,94.05179298404067],"flags":{},"order":2,"mode":0,"inputs":[],"outputs":[],"properties":{},"widgets_values":["Enable to upscale alpha/mask channel along with RGB channel (for RGBA inputs)"],"color":"#432","bgcolor":"#653"},{"id":20,"type":"Note","pos":[93.33964800519301,920.9877545042978],"size":[290.1922351462714,97.95592567265356],"flags":{},"order":3,"mode":0,"inputs":[],"outputs":[],"properties":{},"widgets_values":["Enable torch.compile optimization. First batch has compilation overhead, but speeds up subsequent batches. Best for long videos, not single images."],"color":"#432","bgcolor":"#653"},{"id":10,"type":"SeedVR2VideoUpscaler","pos":[1292.9734501584262,472.2560838726697],"size":[270,386],"flags":{},"order":7,"mode":0,"inputs":[{"localized_name":"image","name":"image","type":"IMAGE","link":16},{"localized_name":"dit","name":"dit","type":"SEEDVR2_DIT","link":11},{"localized_name":"vae","name":"vae","type":"SEEDVR2_VAE","link":10},{"localized_name":"seed","name":"seed","type":"INT","widget":{"name":"seed"},"link":null},{"localized_name":"resolution","name":"resolution","type":"INT","widget":{"name":"resolution"},"link":null},{"localized_name":"max_resolution","name":"max_resolution","type":"INT","widget":{"name":"max_resolution"},"link":null},{"localized_name":"batch_size","name":"batch_size","type":"INT","widget":{"name":"batch_size"},"link":null},{"localized_name":"uniform_batch_size","name":"uniform_batch_size","type":"BOOLEAN","widget":{"name":"uniform_batch_size"},"link":null},{"localized_name":"color_correction","name":"color_correction","type":"COMBO","widget":{"name":"color_correction"},"link":null},{"localized_name":"temporal_overlap","name":"temporal_overlap","shape":7,"type":"INT","widget":{"name":"temporal_overlap"},"link":null},{"localized_name":"prepend_frames","name":"prepend_frames","shape":7,"type":"INT","widget":{"name":"prepend_frames"},"link":null},{"localized_name":"input_noise_scale","name":"input_noise_scale","shape":7,"type":"FLOAT","widget":{"name":"input_noise_scale"},"link":null},{"localized_name":"latent_noise_scale","name":"latent_noise_scale","shape":7,"type":"FLOAT","widget":{"name":"latent_noise_scale"},"link":null},{"localized_name":"offload_device","name":"offload_device","shape":7,"type":"COMBO","widget":{"name":"offload_device"},"link":null},{"localized_name":"enable_debug","name":"enable_debug","shape":7,"type":"BOOLEAN","widget":{"name":"enable_debug"},"link":null}],"outputs":[{"localized_name":"IMAGE","name":"IMAGE","type":"IMAGE","links":[12]}],"properties":{"aux_id":"ainvfx/ComfyUI-SeedVR2_VideoUpscaler","ver":"690cc39379c1481159ddd451368dbf2295930fc6","Node name for S&R":"SeedVR2VideoUpscaler"},"widgets_values":[42,"randomize",1080,0,1,false,"lab",0,0,0,0,"cpu",false]},{"id":15,"type":"SaveImage","pos":[1616.797668908428,473.0256151226697],"size":[270,270],"flags":{},"order":8,"mode":0,"inputs":[{"localized_name":"images","name":"images","type":"IMAGE","link":12},{"localized_name":"filename_prefix","name":"filename_prefix","type":"STRING","widget":{"name":"filename_prefix"},"link":null}],"outputs":[],"properties":{"cnr_id":"comfy-core","ver":"0.3.68"},"widgets_values":["ComfyUI"]}],"links":[[10,13,0,10,2,"SEEDVR2_VAE"],[11,14,0,10,1,"SEEDVR2_DIT"],[12,10,0,15,0,"IMAGE"],[14,16,0,17,0,"IMAGE"],[16,17,0,10,0,"IMAGE"],[17,16,1,17,1,"MASK"],[18,19,0,14,0,"TORCH_COMPILE_ARGS"],[19,19,0,13,0,"TORCH_COMPILE_ARGS"]],"groups":[],"config":{},"extra":{"ds":{"scale":0.9229599817706443,"offset":[268.65279462308837,183.8749573202125]}},"version":0.4}

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/example_workflows/example_inputs/Mustache_640x360.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:21581bc8454e234e3d3f833172bb358215f47d33cfcf5fc12f3dd0dff3319d1d
+size 115496

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/inference_cli.py

@@ -0,0 +1,1712 @@
+#!/usr/bin/env python3
+"""
+SeedVR2 Video Upscaler - Standalone CLI Interface
+
+Command-line interface for high-quality upscaling using SeedVR2 diffusion models.
+Supports single and multi-GPU processing with advanced memory optimization.
+
+Key Features:
+    • Multi-GPU Processing: Automatic workload distribution across multiple GPUs with
+      temporal overlap blending for seamless transitions
+    • Streaming Mode: Memory-efficient processing of long videos in chunks, avoiding
+      full video loading into RAM while maintaining temporal consistency
+    • Memory Optimization: BlockSwap for limited VRAM, VAE tiling for large resolutions,
+      intelligent tensor offloading between processing phases
+    • Performance: Torch.compile integration, BFloat16 compute pipeline,
+      efficient model caching for batch and streaming processing
+    • Flexibility: Multiple output formats (MP4/PNG), advanced color correction methods,
+      directory batch processing with auto-format detection
+    • Quality Control: Temporal overlap blending, frame prepending for artifact reduction,
+      configurable noise scales for detail preservation
+
+Architecture:
+    The CLI implements a 4-phase processing pipeline:
+    1. Encode: VAE encoding with optional input noise and tiling
+    2. Upscale: DiT transformer upscaling with latent space diffusion
+    3. Decode: VAE decoding with optional tiling
+    4. Postprocess: Color correction and temporal blending
+
+Usage:
+    python inference_cli.py video.mp4 --resolution 1080
+    For complete usage examples, run: python inference_cli.py --help
+
+Requirements:
+    • Python 3.10+
+    • PyTorch 2.4+ with CUDA 12.1+ (NVIDIA) or MPS (Apple Silicon)
+    • 16GB+ VRAM recommended (8GB minimum with BlockSwap)
+    • OpenCV, NumPy for video I/O
+
+Model Support:
+    • 3B models: seedvr2_ema_3b_fp16.safetensors (default), _fp8_e4m3fn/GGUF variants
+    • 7B models: seedvr2_ema_7b_fp16.safetensors, _fp8_e4m3fn/GGUF variants
+    • VAE: ema_vae_fp16.safetensors (shared across all models)
+    • Auto-downloads from HuggingFace on first run with SHA256 validation
+"""
+
+# Standard library imports
+import sys
+import os
+import argparse
+import time
+import platform
+import multiprocessing as mp
+from typing import Dict, Any, List, Optional, Tuple, Literal, Generator
+from datetime import datetime
+from pathlib import Path
+
+# Set up path before any other imports to fix module resolution
+script_dir = os.path.dirname(os.path.abspath(__file__))
+if script_dir not in sys.path:
+    sys.path.insert(0, script_dir)
+
+# Set environment variable so all spawned processes can find modules
+os.environ['PYTHONPATH'] = script_dir + ':' + os.environ.get('PYTHONPATH', '')
+
+# Ensure safe CUDA usage with multiprocessing
+if mp.get_start_method(allow_none=True) != 'spawn':
+    mp.set_start_method('spawn', force=True)
+
+# Configure platform-specific memory management before heavy imports
+# Must be set BEFORE import torch
+if platform.system() == "Darwin":
+    # MPS allocator requires: low_watermark <= high_watermark
+    # Setting both to 0.0 disables PyTorch memory limits, letting macOS manage memory
+    os.environ.setdefault("PYTORCH_MPS_HIGH_WATERMARK_RATIO", "0.0")
+    os.environ.setdefault("PYTORCH_MPS_LOW_WATERMARK_RATIO", "0.0")
+else:
+    os.environ.setdefault("PYTORCH_CUDA_ALLOC_CONF", "backend:cudaMallocAsync")
+
+    # Pre-parse arguments that must be handled before torch import
+    _pre_parser = argparse.ArgumentParser(add_help=False)
+    _pre_parser.add_argument("--cuda_device", type=str, default=None)
+    _pre_args, _ = _pre_parser.parse_known_args()
+    
+    if _pre_args.cuda_device is not None:
+        device_list_env = [x.strip() for x in _pre_args.cuda_device.split(',') if x.strip()!='']
+        
+        # Skip validation if CUDA_VISIBLE_DEVICES is already set (worker process)
+        if os.environ.get("CUDA_VISIBLE_DEVICES") is None:
+            # Temporary torch import for CUDA device validation only
+            # Must happen before setting CUDA_VISIBLE_DEVICES and before main torch import
+            import torch as _torch_check
+            if _torch_check.cuda.is_available():
+                available_count = _torch_check.cuda.device_count()
+                invalid_devices = [d for d in device_list_env if not d.isdigit() or int(d) >= available_count]
+                if invalid_devices:
+                    print(f"❌ [ERROR] Invalid CUDA device ID(s): {', '.join(invalid_devices)}. "
+                        f"Available devices: 0-{available_count-1} (total: {available_count})")
+                    sys.exit(1)
+            else:
+                print("❌ [ERROR] CUDA is not available on this system. Cannot use --cuda_device argument.")
+                sys.exit(1)
+            
+            # Set CUDA_VISIBLE_DEVICES for single GPU after validation
+            if len(device_list_env) == 1:
+                os.environ["CUDA_VISIBLE_DEVICES"] = device_list_env[0]
+
+# Heavy dependency imports after environment configuration
+import torch
+import cv2
+import numpy as np
+import subprocess
+import shutil
+
+# Project imports
+from src.utils.downloads import download_weight
+from src.utils.model_registry import get_available_dit_models, DEFAULT_DIT, DEFAULT_VAE
+from src.utils.constants import SEEDVR2_FOLDER_NAME
+from src.core.generation_utils import (
+    setup_generation_context, 
+    prepare_runner, 
+    compute_generation_info, 
+    log_generation_start,
+    blend_overlapping_frames,
+    load_text_embeddings,
+    script_directory
+)
+from src.core.generation_phases import (
+    encode_all_batches, 
+    upscale_all_batches, 
+    decode_all_batches, 
+    postprocess_all_batches
+)
+from src.utils.debug import Debug
+from src.optimization.memory_manager import clear_memory, get_gpu_backend, is_cuda_available
+debug = Debug(enabled=False)  # Will be enabled via --debug CLI flag
+
+
+# =============================================================================
+# FFMPEG Class
+# =============================================================================
+
+class FFMPEGVideoWriter:
+    """
+    Video writer using ffmpeg subprocess for encoding with 10-bit support.
+    
+    Provides cv2.VideoWriter-compatible interface (write, isOpened, release) while
+    using ffmpeg for encoding. Enables 10-bit output (yuv420p10le with x265) which
+    reduces banding artifacts in gradients compared to 8-bit opencv output.
+    
+    Args:
+        path: Output video file path
+        width: Frame width in pixels
+        height: Frame height in pixels
+        fps: Frames per second
+        use_10bit: If True, uses x265 codec with yuv420p10le pixel format.
+                   If False, uses x264 with yuv420p (default: False)
+    
+    Raises:
+        RuntimeError: If ffmpeg is not found in system PATH
+    
+    Note:
+        Frames must be passed to write() in BGR format (same as cv2.VideoWriter).
+        Internally converts to RGB for ffmpeg rawvideo input.
+    """
+    
+    def __init__(self, path: str, width: int, height: int, fps: float, use_10bit: bool = False):
+        pix_fmt = 'yuv420p10le' if use_10bit else 'yuv420p'
+        codec = 'libx265' if use_10bit else 'libx264'
+        
+        self.proc = subprocess.Popen(
+            ['ffmpeg', '-y', '-f', 'rawvideo', '-pix_fmt', 'rgb24',
+             '-s', f'{width}x{height}', '-r', str(fps), '-i', '-',
+             '-c:v', codec, '-pix_fmt', pix_fmt, '-preset', 'medium', '-crf', '12', path],
+            stdin=subprocess.PIPE, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
+        )
+    
+    def write(self, frame_bgr: np.ndarray):
+        if not self.isOpened():
+            raise RuntimeError("FFMPEGVideoWriter: ffmpeg process is not running")
+        
+        frame_rgb = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB)
+        try:
+            self.proc.stdin.write(frame_rgb.astype(np.uint8).tobytes())
+            self.proc.stdin.flush()  # Critical: prevent buffering issues
+        except BrokenPipeError:
+            raise RuntimeError(
+                "FFMPEGVideoWriter: ffmpeg process terminated unexpectedly. "
+                "Check video path, codec support, and disk space."
+            )
+    
+    def isOpened(self) -> bool:
+        return self.proc is not None and self.proc.poll() is None
+    
+    def release(self):
+        if self.proc:
+            try:
+                self.proc.stdin.close()
+            except Exception:
+                pass  # Ignore errors on close
+            
+            self.proc.wait()
+            
+            if self.proc.returncode != 0:
+                debug.log(
+                    f"ffmpeg exited with code {self.proc.returncode}. "
+                    "Check output file for corruption.",
+                    level="WARNING", force=True, category="file"
+                )
+            self.proc = None
+
+
+# =============================================================================
+# Device Management Helpers
+# =============================================================================
+
+def _device_id_to_name(device_id: str, platform_type: str = None) -> str:
+    """
+    Convert device ID to full device name.
+    
+    Args:
+        device_id: Device ID ("0", "1") or special value ("cpu", "none")
+        platform_type: Override platform type ("cuda", "mps", "cpu")
+    
+    Returns:
+        Full device name ("cuda:0", "mps:0", "cpu", "none")
+    """
+    if device_id in ("cpu", "none"):
+        return device_id
+    
+    if platform_type is None:
+        platform_type = get_gpu_backend()
+    
+    # MPS typically doesn't use indices
+    if platform_type == "mps":
+        return "mps"
+    
+    return f"{platform_type}:{device_id}"
+
+
+def _parse_offload_device(offload_arg: str, platform_type: str = None, cache_enabled: bool = False) -> Optional[str]:
+    """
+    Parse offload device argument to full device name.
+    
+    Args:
+        offload_arg: Offload device argument ("none", "cpu", "0", "1", or "cuda:1")
+        platform_type: Override platform type
+        cache_enabled: If True and offload_arg is "none", default to "cpu"
+    
+    Returns:
+        Full device name or None
+    """
+    if offload_arg == "none":
+        # If caching enabled but no offload device specified, default to CPU
+        return "cpu" if cache_enabled else None
+    
+    if offload_arg == "cpu":
+        return "cpu"
+    
+    # If already a full device name (cuda:1, mps:0), return as-is
+    if ":" in offload_arg:
+        return offload_arg
+    
+    # Otherwise treat as device ID
+    return _device_id_to_name(offload_arg, platform_type)
+
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+# Supported file extensions
+VIDEO_EXTENSIONS = {'.mp4', '.avi', '.mov', '.mkv', '.webm', '.flv', '.wmv', '.m4v'}
+IMAGE_EXTENSIONS = {'.png', '.jpg', '.jpeg', '.bmp', '.tiff', '.tif', '.webp'}
+
+
+# =============================================================================
+# Video I/O Functions
+# =============================================================================
+
+def get_media_files(directory: str) -> List[str]:
+    """
+    Get all video and image files from directory, sorted alphabetically.
+    
+    Args:
+        directory: Path to directory to scan
+        
+    Returns:
+        Sorted list of file paths (strings) matching video or image extensions
+    """
+    valid_extensions = VIDEO_EXTENSIONS | IMAGE_EXTENSIONS
+    path = Path(directory)
+    
+    # Get all files and filter by extension (case-insensitive)
+    files = [f for f in path.iterdir() if f.is_file() and f.suffix.lower() in valid_extensions]
+    
+    return sorted([str(f) for f in files])
+
+
+def extract_frames_from_image(image_path: str) -> Tuple[torch.Tensor, float]:
+    """
+    Extract single frame from image file and convert to tensor format.
+    
+    Reads image using OpenCV, converts BGR to RGB, normalizes to [0,1] range,
+    and formats as single-frame video tensor for consistent processing.
+    
+    Args:
+        image_path: Path to input image file
+        
+    Returns:
+        Tuple containing:
+            - frames_tensor: Single frame as tensor [1, H, W, C], Float16, range [0,1] (C=3 for RGB, C=4 for RGBA)
+            - fps: Default FPS value (30.0) for image-to-video conversion
+    
+    Raises:
+        FileNotFoundError: If image file doesn't exist
+        ValueError: If image cannot be opened
+    """
+    debug.log(f"Loading image: {image_path}", category="file")
+    
+    if not os.path.exists(image_path):
+        raise FileNotFoundError(f"Image file not found: {image_path}")
+    
+    # Read image with alpha channel preserved
+    frame = cv2.imread(image_path, cv2.IMREAD_UNCHANGED)
+    if frame is None:
+        raise ValueError(f"Cannot open image file: {image_path}")
+    
+    # Convert BGR(A) to RGB(A) based on channel count
+    if frame.shape[2] == 4:
+        frame = cv2.cvtColor(frame, cv2.COLOR_BGRA2RGBA)
+        debug.log(f"Detected RGBA image (alpha channel preserved)", category="file")
+    else:
+        frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+    
+    # Convert to float32 and normalize
+    frame = frame.astype(np.float32) / 255.0
+    
+    # Convert to tensor [1, H, W, C]
+    frames_tensor = torch.from_numpy(frame[None, ...]).to(torch.float16)
+    
+    debug.log(f"Image tensor shape: {frames_tensor.shape}, dtype: {frames_tensor.dtype}", category="memory")
+    
+    return frames_tensor, 30.0  # Default FPS for images
+
+
+def get_input_type(input_path: str) -> Literal['video', 'image', 'directory', 'unknown']:
+    """
+    Determine input type from file path.
+    
+    Args:
+        input_path: Path to input file or directory
+        
+    Returns:
+        Input type: 'video', 'image', 'directory', or 'unknown'
+        
+    Raises:
+        FileNotFoundError: If input path doesn't exist
+    """
+    path = Path(input_path)
+    
+    if not path.exists():
+        raise FileNotFoundError(f"Input path not found: {input_path}")
+    
+    if path.is_dir():
+        return 'directory'
+    
+    ext = path.suffix.lower()
+    if ext in VIDEO_EXTENSIONS:
+        return "video"
+    elif ext in IMAGE_EXTENSIONS:
+        return "image"
+    else:
+        return "unknown"
+
+
+def generate_output_path(input_path: str, output_format: str, output_dir: Optional[str] = None, 
+                        input_type: Optional[str] = None, from_directory: bool = False) -> str:
+    """
+    Generate output path based on input path and format.
+    
+    Args:
+        input_path: Source file path
+        output_format: "mp4" or "png"
+        output_dir: Optional output directory (overrides default behavior)
+        input_type: Optional input type ("image", "video", "directory")
+        from_directory: True if processing files from a directory (batch mode)
+    
+    Returns:
+        Absolute output path (file for single image/video, directory for sequences)
+    """
+    input_path_obj = Path(input_path)
+    input_name = input_path_obj.stem
+    
+    # Determine base directory and whether to add suffix
+    if output_dir:
+        # User specified output directory - use as-is, no suffix
+        base_dir = Path(output_dir)
+        add_suffix = False
+    elif from_directory:
+        # Batch mode: create sibling folder with _upscaled, keep original filenames
+        original_dir = input_path_obj.parent
+        base_dir = original_dir.parent / f"{original_dir.name}_upscaled"
+        add_suffix = False
+    else:
+        # Single file mode: output to same directory with _upscaled suffix
+        base_dir = input_path_obj.parent
+        add_suffix = True
+    
+    # Build filename with optional suffix
+    file_suffix = "_upscaled" if add_suffix else ""
+    
+    # Generate output path based on format
+    if output_format == "png":
+        if input_type == "image":
+            output_path = base_dir / f"{input_name}{file_suffix}.png"
+        else:
+            output_path = base_dir / f"{input_name}{file_suffix}"
+    else:
+        output_path = base_dir / f"{input_name}{file_suffix}.mp4"
+    
+    return str(output_path.resolve())
+
+
+def process_single_file(input_path: str, args: argparse.Namespace, device_list: List[str], 
+                       output_path: Optional[str] = None, format_auto_detected: bool = False,
+                       runner_cache: Optional[Dict[str, Any]] = None) -> int:
+    """
+    Process a single video or image file with optional model caching.
+    
+    For videos, supports streaming mode (chunk_size > 0) which processes in memory-bounded
+    chunks with temporal overlap for seamless transitions between chunks.
+    
+    Args:
+        input_path: Path to input file
+        args: Command-line arguments with all processing settings
+        device_list: List of GPU device IDs as strings
+        output_path: Optional explicit output path (auto-generated if None)
+        format_auto_detected: Whether output format was auto-detected
+        runner_cache: Optional cache dict for model reuse across multiple files
+    
+    Returns:
+        Number of frames written to output
+    """
+    input_type = get_input_type(input_path)
+    
+    if input_type == "unknown":
+        debug.log(f"Skipping unsupported file: {input_path}", level="WARNING", category="file", force=True)
+        return 0
+    
+    debug.log(f"Processing {input_type}: {Path(input_path).name}", category="generation", force=True)
+    
+    # Generate or validate output path
+    if output_path is None:
+        output_path = generate_output_path(input_path, args.output_format, input_type=input_type)
+    elif not Path(output_path).suffix or (args.output_format == "png" and input_type != "image"):
+        # No extension or PNG sequence → treat as directory, generate filename
+        output_path = generate_output_path(input_path, args.output_format, 
+                                         output_dir=output_path, input_type=input_type)
+    
+    # Show format with auto-detection indicator
+    format_prefix = "Auto-detected" if format_auto_detected else "Requested"
+    debug.log(f"{format_prefix} output format: {args.output_format}", category="info", force=True, indent_level=1)
+    
+    # === VIDEO PROCESSING ===
+    if input_type == "video":
+        if not os.path.exists(input_path):
+            raise FileNotFoundError(f"Video file not found: {input_path}")
+        
+        cap = cv2.VideoCapture(input_path)
+        if not cap.isOpened():
+            raise ValueError(f"Cannot open video file: {input_path}")
+        
+        fps = cap.get(cv2.CAP_PROP_FPS) or 30.0
+        total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+        width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        
+        debug.log(f"Video info: {total_frames} frames, {width}x{height}, {fps:.2f} FPS", category="info")
+        
+       # Skip initial frames
+        if args.skip_first_frames > 0:
+            debug.log(f"Skipping first {args.skip_first_frames} frames", category="info")
+            cap.set(cv2.CAP_PROP_POS_FRAMES, args.skip_first_frames)
+        
+        # Calculate frames to process (apply load_cap if set)
+        frames_to_process = total_frames - args.skip_first_frames
+        if args.load_cap > 0:
+            frames_to_process = min(frames_to_process, args.load_cap)
+        
+        # Early exit for empty/exhausted video
+        if frames_to_process <= 0:
+            debug.log(f"No frames to process after skipping {args.skip_first_frames} of {total_frames}", 
+                     level="WARNING", category="file", force=True)
+            cap.release()
+            return 0
+        
+        # Streaming mode: process in chunks
+        chunk_size = args.chunk_size if args.chunk_size > 0 else frames_to_process
+        streaming = args.chunk_size > 0
+        total_chunks = (frames_to_process + chunk_size - 1) // chunk_size  # ceiling division
+        
+        if streaming:
+            debug.log(f"Streaming mode: chunks of {chunk_size} frames, overlap={args.temporal_overlap}", 
+                     category="info", force=True, indent_level=1)
+        
+        is_png = args.output_format == "png"
+        video_writer = None
+        overlap = args.temporal_overlap
+        frames_written = 0
+        chunk_idx = 0
+        base_name = Path(input_path).stem
+        
+        # Multi-GPU: workers stream their own segments
+        if len(device_list) > 1:
+            cap.release()  # Workers will reopen
+            video_info = {
+                'video_path': input_path,
+                'start_frame': args.skip_first_frames,
+                'frames_to_process': frames_to_process,
+            }
+            result = _gpu_processing(None, device_list, args, video_info=video_info)
+            
+            # Save result
+            if is_png:
+                save_frames_to_image(result, output_path, base_name)
+            else:
+                video_writer = save_frames_to_video(result, output_path, fps, 
+                    video_backend=args.video_backend, use_10bit=args.use_10bit)
+                if video_writer is not None:
+                    video_writer.release()
+            
+            frames_written = result.shape[0]
+        
+        # Single GPU: stream in main process
+        else:
+            chunk_count = 0
+            for result in _stream_video_chunks(
+                cap=cap,
+                frames_to_process=frames_to_process,
+                chunk_size=chunk_size,
+                overlap=overlap,
+                args=args,
+                device_id=device_list[0],
+                debug=debug,
+                runner_cache=runner_cache,
+                log_progress=streaming,
+                total_chunks=total_chunks,
+                cleanup_timer_name="chunk_cleanup"
+            ):
+                chunk_count += 1
+                
+                # Save output
+                if is_png:
+                    save_frames_to_image(result, output_path, base_name, start_index=frames_written)
+                else:
+                    video_writer = save_frames_to_video(result, output_path, fps, writer=video_writer,
+                        video_backend=args.video_backend, use_10bit=args.use_10bit)
+                
+                frames_written += result.shape[0]
+                del result
+            
+            chunk_idx = chunk_count
+            cap.release()
+            if video_writer is not None:
+                video_writer.release()
+        
+        if streaming:
+            debug.log("", category="none", force=True)
+            if len(device_list) > 1:
+                debug.log(f"Streaming complete: {frames_written} frames across {len(device_list)} GPUs", category="success", force=True)
+            else:
+                debug.log(f"Streaming complete: {frames_written} frames in {chunk_idx} chunks", category="success", force=True)
+        
+        debug.log(f"Output saved to: {output_path}", category="file", force=True)
+        return frames_written
+    
+    # === IMAGE PROCESSING ===
+    frames_tensor, _ = extract_frames_from_image(input_path)
+    
+    processing_start = time.time()
+    # Process frames (multiprocessing only for multi-GPU)
+    if len(device_list) > 1:
+        result = _gpu_processing(frames_tensor, device_list, args)
+    else:
+        result = _single_gpu_direct_processing(frames_tensor, args, device_list[0], runner_cache)
+    debug.log(f"Processing time: {time.time() - processing_start:.2f}s", category="timing")
+    
+    # Save single image
+    os.makedirs(Path(output_path).parent, exist_ok=True)
+    frame_np = (result[0].cpu().numpy() * 255.0).astype(np.uint8)
+    _save_image_bgr(frame_np, output_path)
+    
+    debug.log(f"Output saved to: {output_path}", category="file", force=True)
+    return 1
+
+
+def _read_frames_from_cap(cap: cv2.VideoCapture, max_frames: int) -> Optional[torch.Tensor]:
+    """
+    Read up to max_frames from an already-open VideoCapture.
+    
+    Args:
+        cap: An already opened cv2.VideoCapture instance
+        max_frames: Maximum number of frames to read in this call
+    
+    Returns:
+        Tensor [T, H, W, C] float32 [0,1], or None if no frames available
+    """
+    frames = []
+    for _ in range(max_frames):
+        ret, frame = cap.read()
+        if not ret:
+            break
+        frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB).astype(np.float32) / 255.0
+        frames.append(frame)
+    
+    if not frames:
+        return None
+    return torch.from_numpy(np.stack(frames)).to(torch.float32)
+
+
+def _stream_video_chunks(
+    cap: cv2.VideoCapture,
+    frames_to_process: int,
+    chunk_size: int,
+    overlap: int,
+    args: argparse.Namespace,
+    device_id: str,
+    debug: 'Debug',
+    runner_cache: Optional[Dict[str, Any]],
+    log_progress: bool = False,
+    total_chunks: int = 0,
+    cleanup_timer_name: Optional[str] = None,
+    log_prefix: str = ""
+) -> Generator[torch.Tensor, None, None]:
+    """
+    Generator that streams and processes video chunks.
+    
+    Handles frame reading, temporal context prepending, processing via
+    _process_frames_core, context removal from output, and memory cleanup.
+    Caller is responsible for VideoCapture lifecycle and result handling.
+    
+    Args:
+        cap: Open VideoCapture positioned at start frame
+        frames_to_process: Total frames to read and process
+        chunk_size: Frames per chunk (use frames_to_process for single chunk)
+        overlap: Temporal overlap frames between chunks for blending
+        args: Processing arguments (copied internally, prepend_frames zeroed after first chunk)
+        device_id: GPU device ID for processing
+        debug: Debug instance for logging
+        runner_cache: Optional model cache dict for reuse across chunks
+        log_progress: If True, log chunk progress with separators
+        total_chunks: Total chunks for progress display (used if log_progress=True)
+        cleanup_timer_name: Optional timer name for memory cleanup logging
+        log_prefix: Optional prefix for log messages (e.g., "[GPU 0] " for worker identification)
+    
+    Yields:
+        Processed frames tensor [T, H, W, C] for each chunk, context frames removed
+    """
+    chunk_args = argparse.Namespace(**vars(args))
+    frames_read = 0
+    prev_raw_tail = None
+    chunk_idx = 0
+    streaming = chunk_size < frames_to_process
+    
+    while frames_read < frames_to_process:
+        read_count = min(chunk_size, frames_to_process - frames_read)
+        new_frames = _read_frames_from_cap(cap, read_count)
+        if new_frames is None:
+            break
+        frames_read += new_frames.shape[0]
+        chunk_idx += 1
+        
+        # Disable prepend_frames after first chunk
+        if chunk_idx > 1:
+            chunk_args.prepend_frames = 0
+        
+        # Prepend context from previous chunk
+        if prev_raw_tail is not None and overlap > 0:
+            context_count = min(overlap, prev_raw_tail.shape[0])
+            frames = torch.cat([prev_raw_tail[-context_count:], new_frames], dim=0)
+        else:
+            frames = new_frames
+            context_count = 0
+        
+        # Log progress if enabled
+        if log_progress and streaming:
+            if chunk_idx > 1:
+                debug.log("", category="none", force=True)
+                debug.log("━" * 60, category="none", force=True)
+            debug.log("", category="none", force=True)
+            debug.log(f"{log_prefix}Chunk {chunk_idx}/{total_chunks}: {new_frames.shape[0]} new + {context_count} context frames", 
+                     category="generation", force=True)
+            debug.log("", category="none", force=True)
+        
+        # Process chunk
+        result = _process_frames_core(
+            frames_tensor=frames.to(torch.float16),
+            args=chunk_args,
+            device_id=device_id,
+            debug=debug,
+            runner_cache=runner_cache
+        )
+        
+        # Remove context frames from output
+        if context_count > 0:
+            result = result[context_count:]
+        
+        # Save tail for next chunk context
+        prev_raw_tail = new_frames[-overlap:].clone() if overlap > 0 else None
+        
+        # Cleanup before yield
+        del frames
+        
+        yield result
+        
+        # Memory cleanup between chunks
+        if streaming:
+            clear_memory(debug=debug, deep=True, force=True, timer_name=cleanup_timer_name)
+
+
+def _save_image_bgr(frame_np: np.ndarray, file_path: str) -> None:
+    """
+    Save a single RGB(A) uint8 frame to disk, converting to BGR(A) for OpenCV.
+    
+    Args:
+        frame_np: Frame as uint8 numpy array [H, W, C] where C is 3 (RGB) or 4 (RGBA)
+        file_path: Output file path
+    """
+    if frame_np.shape[2] == 4:
+        frame_bgr = cv2.cvtColor(frame_np, cv2.COLOR_RGBA2BGRA)
+    else:
+        frame_bgr = cv2.cvtColor(frame_np, cv2.COLOR_RGB2BGR)
+    cv2.imwrite(file_path, frame_bgr)
+
+
+def save_frames_to_video(
+    frames_tensor: torch.Tensor, 
+    output_path: str, 
+    fps: float = 30.0,
+    writer: Optional[cv2.VideoWriter] = None,
+    video_backend: str = "opencv",
+    use_10bit: bool = False
+) -> Optional[cv2.VideoWriter]:
+    """
+    Save frames tensor to MP4 video file.
+    
+    Converts tensor from Float32 [0,1] to uint8 [0,255], RGB to BGR for OpenCV,
+    and writes to video file using mp4v codec. Supports streaming mode where
+    an existing writer is passed and kept open for subsequent chunks.
+    
+    Args:
+        frames_tensor: Frames in format [T, H, W, C], Float32, range [0,1]
+        output_path: Output video file path (directory created if doesn't exist)
+        fps: Frames per second for output video (default: 30.0)
+        writer: Existing VideoWriter for streaming (if None, creates new one)
+    
+    Returns:
+        VideoWriter if streaming mode (caller must close), None if standalone mode
+    
+    Raises:
+        ValueError: If video writer cannot be initialized
+    """
+    frames_np = (frames_tensor.cpu().numpy() * 255.0).astype(np.uint8)
+    T, H, W, C = frames_np.shape
+    
+    if writer is None:
+        debug.log(f"Saving {T} frames to video: {output_path} (backend={video_backend})", category="file")
+        os.makedirs(Path(output_path).parent, exist_ok=True)
+        if video_backend == "ffmpeg":
+            writer = FFMPEGVideoWriter(output_path, W, H, fps, use_10bit)
+        else:
+            fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+            writer = cv2.VideoWriter(output_path, fourcc, fps, (W, H))
+        if not writer.isOpened():
+            raise ValueError(f"Cannot create video writer for: {output_path}")
+    
+    for i, frame in enumerate(frames_np):
+        frame_bgr = cv2.cvtColor(frame, cv2.COLOR_RGB2BGR)
+        writer.write(frame_bgr)
+        if debug.enabled and (i + 1) % 100 == 0:
+            debug.log(f"Written {i + 1}/{T} frames", category="file")
+    
+    return writer  # Caller always closes
+
+
+def save_frames_to_image(
+    frames_tensor: torch.Tensor, 
+    output_dir: str, 
+    base_name: str,
+    start_index: int = 0
+) -> int:
+    """
+    Save frames tensor as sequential PNG image files.
+    
+    Each frame saved as {base_name}_{index:0Nd}.png with zero-padded indices.
+    Converts Float32 [0,1] to uint8 [0,255] and RGB(A) to BGR(A) for OpenCV.
+    
+    Args:
+        frames_tensor: Frames in format [T, H, W, C], Float32, range [0,1]
+        output_dir: Directory to save PNG files (created if doesn't exist)
+        base_name: Base name for output files (e.g., "frame" → "frame_00000.png")
+        start_index: Starting index for filenames (for streaming continuation)
+    
+    Returns:
+        Number of frames saved
+    """
+    os.makedirs(output_dir, exist_ok=True)
+    
+    frames_np = (frames_tensor.cpu().numpy() * 255.0).astype(np.uint8)
+    total = frames_np.shape[0]
+    
+    if start_index == 0:
+        debug.log(f"Saving {total} frames as PNGs to directory: {output_dir}", category="file")
+    digits = 6  # Supports up to 999,999 frames (~11.5 hours at 24fps)
+
+    for idx, frame in enumerate(frames_np):
+        filename = f"{base_name}_{start_index + idx:0{digits}d}.png"
+        file_path = os.path.join(output_dir, filename)
+        _save_image_bgr(frame, file_path)
+        if debug.enabled and (idx + 1) % 100 == 0:
+            debug.log(f"Saved {idx + 1}/{total} images", category="file")
+
+    debug.log(f"Saved {total} images to '{output_dir}'", category="success")
+    return total
+
+
+# =============================================================================
+# Core Processing Logic
+# =============================================================================
+
+def _process_frames_core(
+    frames_tensor: torch.Tensor,
+    args: argparse.Namespace,
+    device_id: str,
+    debug: Debug,
+    runner_cache: Optional[Dict[str, Any]] = None
+) -> torch.Tensor:
+    """
+    Core frame processing logic shared between worker and direct processing.
+    
+    Executes the complete 4-phase pipeline: encode → upscale → decode → postprocess.
+    Supports both cached (direct) and non-cached (worker) execution modes.
+    
+    Args:
+        frames_tensor: Input frames [T, H, W, C], Float16/Float32, range [0,1]
+        args: Command-line arguments with all processing settings
+        device_id: Device ID for inference ("0", "1", etc.)
+        debug: Debug instance for logging
+        runner_cache: Optional cache dict for model reuse (direct mode only)
+    
+    Returns:
+        Upscaled frames tensor [T', H', W', C], Float32, range [0,1]
+    """    
+    # Determine platform and convert device IDs to full names
+    platform_type = get_gpu_backend()
+    inference_device = _device_id_to_name(device_id, platform_type)
+    
+    # Parse offload devices (with caching defaults)
+    cache_dit = args.cache_dit if runner_cache is not None else False
+    cache_vae = args.cache_vae if runner_cache is not None else False
+    
+    dit_offload = _parse_offload_device(args.dit_offload_device, platform_type, cache_dit)
+    vae_offload = _parse_offload_device(args.vae_offload_device, platform_type, cache_vae)
+    tensor_offload = _parse_offload_device(args.tensor_offload_device, platform_type, False)
+    
+    # Setup or reuse generation context
+    if runner_cache is not None and 'ctx' in runner_cache:
+        ctx = runner_cache['ctx']
+        # Clear previous run data but keep device config
+        keys_to_keep = {'dit_device', 'vae_device', 'dit_offload_device', 
+                       'vae_offload_device', 'tensor_offload_device', 'compute_dtype'}
+        for key in list(ctx.keys()):
+            if key not in keys_to_keep:
+                del ctx[key]
+    else:
+        ctx = setup_generation_context(
+            dit_device=inference_device,
+            vae_device=inference_device,
+            dit_offload_device=dit_offload,
+            vae_offload_device=vae_offload,
+            tensor_offload_device=tensor_offload,
+            debug=debug
+        )
+        if runner_cache is not None:
+            runner_cache['ctx'] = ctx
+    
+    # Build torch compile args
+    torch_compile_args_dit = None
+    torch_compile_args_vae = None
+    if args.compile_dit:
+        torch_compile_args_dit = {
+            "backend": args.compile_backend,
+            "mode": args.compile_mode,
+            "fullgraph": args.compile_fullgraph,
+            "dynamic": args.compile_dynamic,
+            "dynamo_cache_size_limit": args.compile_dynamo_cache_size_limit,
+            "dynamo_recompile_limit": args.compile_dynamo_recompile_limit,
+        }
+    if args.compile_vae:
+        torch_compile_args_vae = {
+            "backend": args.compile_backend,
+            "mode": args.compile_mode,
+            "fullgraph": args.compile_fullgraph,
+            "dynamic": args.compile_dynamic,
+            "dynamo_cache_size_limit": args.compile_dynamo_cache_size_limit,
+            "dynamo_recompile_limit": args.compile_dynamo_recompile_limit,
+        }
+    
+    # Prepare runner with caching support
+    model_dir = args.model_dir if args.model_dir is not None else f"./models/{SEEDVR2_FOLDER_NAME}"
+    
+    # Use fixed IDs for CLI caching when enabled
+    dit_id = "cli_dit" if cache_dit else None
+    vae_id = "cli_vae" if cache_vae else None
+    
+    runner, cache_context = prepare_runner(
+        dit_model=args.dit_model,
+        vae_model=DEFAULT_VAE,
+        model_dir=model_dir,
+        debug=debug,
+        ctx=ctx,
+        dit_cache=cache_dit,
+        vae_cache=cache_vae,
+        dit_id=dit_id,
+        vae_id=vae_id,
+        block_swap_config={
+            'blocks_to_swap': args.blocks_to_swap,
+            'swap_io_components': args.swap_io_components,
+            'offload_device': dit_offload,
+        },
+        encode_tiled=args.vae_encode_tiled,
+        encode_tile_size=(args.vae_encode_tile_size, args.vae_encode_tile_size),
+        encode_tile_overlap=(args.vae_encode_tile_overlap, args.vae_encode_tile_overlap),
+        decode_tiled=args.vae_decode_tiled,
+        decode_tile_size=(args.vae_decode_tile_size, args.vae_decode_tile_size),
+        decode_tile_overlap=(args.vae_decode_tile_overlap, args.vae_decode_tile_overlap),
+        tile_debug=args.tile_debug.lower() if args.tile_debug else "false",
+        attention_mode=args.attention_mode,
+        torch_compile_args_dit=torch_compile_args_dit,
+        torch_compile_args_vae=torch_compile_args_vae
+    )
+    
+    ctx['cache_context'] = cache_context
+    if runner_cache is not None:
+        runner_cache['runner'] = runner
+    
+    # Preload text embeddings before Phase 1 to avoid sync stall in Phase 2
+    ctx['text_embeds'] = load_text_embeddings(script_directory, ctx['dit_device'], ctx['compute_dtype'], debug)
+    debug.log("Loaded text embeddings for DiT", category="dit")
+    
+    # Compute generation info and log start (handles prepending internally)
+    frames_tensor, gen_info = compute_generation_info(
+        ctx=ctx,
+        images=frames_tensor,
+        resolution=args.resolution,
+        max_resolution=args.max_resolution,
+        batch_size=args.batch_size,
+        uniform_batch_size=args.uniform_batch_size,
+        seed=args.seed,
+        prepend_frames=args.prepend_frames,
+        temporal_overlap=args.temporal_overlap,
+        debug=debug
+    )
+    log_generation_start(gen_info, debug)
+    
+    # Phase 1: Encode
+    ctx = encode_all_batches(
+        runner, ctx=ctx, images=frames_tensor,
+        debug=debug, 
+        batch_size=args.batch_size,
+        uniform_batch_size=args.uniform_batch_size,
+        seed=args.seed,
+        progress_callback=None, 
+        temporal_overlap=args.temporal_overlap,
+        resolution=args.resolution,
+        max_resolution=args.max_resolution,
+        input_noise_scale=args.input_noise_scale,
+        color_correction=args.color_correction
+    )
+    
+    # Phase 2: Upscale
+    ctx = upscale_all_batches(
+        runner, ctx=ctx, debug=debug, progress_callback=None,
+        seed=args.seed,
+        latent_noise_scale=args.latent_noise_scale,
+        cache_model=cache_dit
+    )
+    
+    # Phase 3: Decode
+    ctx = decode_all_batches(
+        runner, ctx=ctx, debug=debug, progress_callback=None,
+        cache_model=cache_vae
+    )
+    
+    # Phase 4: Post-process
+    ctx = postprocess_all_batches(
+        ctx=ctx, debug=debug, progress_callback=None,
+        color_correction=args.color_correction,
+        prepend_frames=0,  # Worker mode handles this in main process
+        temporal_overlap=args.temporal_overlap,
+        batch_size=args.batch_size
+    )
+    
+    result_tensor = ctx['final_video']
+    
+    # Convert to CPU and compatible dtype
+    if result_tensor.is_cuda or result_tensor.is_mps:
+        result_tensor = result_tensor.cpu()
+    if result_tensor.dtype in (torch.bfloat16, torch.float8_e4m3fn, torch.float8_e5m2):
+        result_tensor = result_tensor.to(torch.float32)
+    
+    return result_tensor
+
+
+def _worker_process(
+    proc_idx: int, 
+    device_id: str, 
+    frames_np: Optional[np.ndarray],
+    shared_args: Dict[str, Any], 
+    return_queue: mp.Queue,
+    done_barrier: mp.Barrier,
+    video_info: Optional[Dict[str, Any]] = None
+) -> None:
+    """
+    Worker process for multi-GPU upscaling.
+    
+    Supports two modes:
+    1. frames_np provided: Process pre-loaded frames (for images)
+    2. video_info provided: Stream video segment internally (for videos)
+       - Each worker opens the video, seeks to its assigned range, and streams
+         with internal chunking and model caching for memory efficiency
+    
+    Args:
+        proc_idx: Worker index for result ordering
+        device_id: GPU device ID (used for CUDA_VISIBLE_DEVICES inheritance)
+        frames_np: Pre-loaded frames as numpy array, or None for video streaming
+        shared_args: Serialized args namespace as dict
+        return_queue: Queue for returning results to parent
+        done_barrier: Barrier for synchronizing shared memory handoff
+        video_info: Optional dict with 'video_path', 'start_frame', 'end_frame'
+                   for video streaming mode
+    """
+    # Create debug instance for this worker
+    worker_debug = Debug(enabled=shared_args["debug"])
+    
+    args = argparse.Namespace(**shared_args)
+    
+    # Video streaming mode: worker reads and processes its assigned segment
+    if video_info is not None:
+        cap = cv2.VideoCapture(video_info['video_path'])
+        cap.set(cv2.CAP_PROP_POS_FRAMES, video_info['start_frame'])
+        
+        segment_frames = video_info['end_frame'] - video_info['start_frame']
+        chunk_size = args.chunk_size if args.chunk_size > 0 else segment_frames
+        
+        worker_debug.log(f"GPU {proc_idx}: frames {video_info['start_frame']}-{video_info['end_frame']} "
+                        f"({segment_frames} frames, chunks of {chunk_size})",
+                        category="generation", force=True)
+        
+        # Only GPU 0 uses prepend_frames (applies to video start only)
+        worker_args = argparse.Namespace(**vars(args))
+        if proc_idx != 0:
+            worker_args.prepend_frames = 0
+        
+        # Enable model caching within worker only if requested
+        runner_cache = {} if (args.cache_dit or args.cache_vae) else None
+        
+        total_chunks = (segment_frames + chunk_size - 1) // chunk_size
+        results = []
+        for result in _stream_video_chunks(
+            cap=cap,
+            frames_to_process=segment_frames,
+            chunk_size=chunk_size,
+            overlap=args.temporal_overlap,
+            args=worker_args,
+            device_id="0",
+            debug=worker_debug,
+            runner_cache=runner_cache,
+            log_progress=total_chunks > 1,
+            total_chunks=total_chunks,
+            log_prefix=f"[GPU {proc_idx}] "
+        ):
+            results.append(result.cpu())
+        
+        cap.release()
+        result_tensor = torch.cat(results, dim=0) if results else torch.empty(0, dtype=torch.float32)
+    
+    # Pre-loaded frames mode (original behavior)
+    else:
+        frames_tensor = torch.from_numpy(frames_np).to(torch.float16)
+        result_tensor = _process_frames_core(
+            frames_tensor=frames_tensor,
+            args=args,
+            device_id="0",
+            debug=worker_debug,
+            runner_cache=None
+        )
+    
+    # Share tensor memory for efficient cross-process transfer (avoids pickling large arrays)
+    return_queue.put((proc_idx, result_tensor.share_memory_()))
+    
+    # Wait for parent to copy shared tensors before exiting
+    # (shared memory requires creating process to stay alive during access)
+    done_barrier.wait()
+
+
+def _single_gpu_direct_processing(
+    frames_tensor: torch.Tensor,
+    args: argparse.Namespace,
+    device_id: str,
+    runner_cache: Optional[Dict[str, Any]]
+) -> torch.Tensor:
+    """
+    Direct single-GPU processing with model caching support.
+    
+    Uses main process and shared runner cache for efficient multi-file processing.
+    """
+    return _process_frames_core(
+        frames_tensor=frames_tensor,
+        args=args,
+        device_id=device_id,
+        debug=debug,
+        runner_cache=runner_cache
+    )
+
+
+def _gpu_processing(
+    frames_tensor: Optional[torch.Tensor],
+    device_list: List[str], 
+    args: argparse.Namespace,
+    video_info: Optional[Dict[str, Any]] = None
+) -> torch.Tensor:
+    """
+    Orchestrate multi-GPU parallel video upscaling with temporal overlap blending.
+    
+    Supports two modes:
+    1. video_info provided: Workers stream their assigned video segments internally
+       (each GPU reads and processes its frame range with internal chunking)
+    2. frames_tensor provided: Workers process pre-loaded frame chunks
+       (non streaming behavior for images or pre-loaded videos)
+    
+    Args:
+        frames_tensor: Input frames [T, H, W, C] or None if using video_info mode
+        device_list: List of device IDs as strings (e.g., ["0", "1"])
+        args: Parsed command-line arguments containing all processing settings
+        video_info: Optional dict with 'video_path', 'start_frame', 'frames_to_process'
+                   for streaming mode where workers read video directly
+    
+    Returns:
+        Upscaled frames tensor [T', H', W', C], Float32, range [0,1]
+    """
+    num_devices = len(device_list)
+    overlap = args.temporal_overlap
+    
+    return_queue = mp.Queue(maxsize=0)
+    done_barrier = mp.Barrier(num_devices + 1)
+    workers = []
+    shared_args = vars(args).copy()
+    
+    # Video streaming mode: distribute frame ranges to workers
+    if video_info is not None:
+        total_frames = video_info['frames_to_process']
+        start_frame = video_info['start_frame']
+        video_path = video_info['video_path']
+        
+        base_per_gpu = total_frames // num_devices
+        remainder = total_frames % num_devices
+        
+        current_start = start_frame
+        for idx, device_id in enumerate(device_list):
+            gpu_frames = base_per_gpu + (1 if idx < remainder else 0)
+            gpu_end = current_start + gpu_frames
+            
+            # Add overlap frames for blending (except last GPU)
+            if idx < num_devices - 1 and overlap > 0:
+                gpu_end = min(gpu_end + overlap, start_frame + total_frames)
+            
+            worker_video_info = {
+                'video_path': video_path,
+                'start_frame': current_start,
+                'end_frame': gpu_end,
+            }
+            
+            os.environ["CUDA_VISIBLE_DEVICES"] = device_id
+            p = mp.Process(
+                target=_worker_process,
+                args=(idx, device_id, None, shared_args, return_queue, done_barrier),
+                kwargs={'video_info': worker_video_info}
+            )
+            p.start()
+            workers.append(p)
+            
+            current_start += gpu_frames
+    
+    # Pre-loaded frames mode (original behavior for images or non-streaming)
+    else:
+        total_frames = frames_tensor.shape[0]
+        
+        if overlap > 0 and num_devices > 1:
+            chunk_with_overlap = total_frames // num_devices + overlap
+            if args.batch_size > 1:
+                chunk_with_overlap = ((chunk_with_overlap + args.batch_size - 1) // args.batch_size) * args.batch_size
+            base_chunk_size = chunk_with_overlap - overlap
+
+            chunks = []
+            for i in range(num_devices):
+                start_idx = i * base_chunk_size
+                if i == num_devices - 1:
+                    end_idx = total_frames
+                else:
+                    end_idx = min(start_idx + chunk_with_overlap, total_frames)
+                chunks.append(frames_tensor[start_idx:end_idx])
+        else:
+            chunks = torch.chunk(frames_tensor, num_devices, dim=0)
+
+        for idx, (device_id, chunk_tensor) in enumerate(zip(device_list, chunks)):
+            os.environ["CUDA_VISIBLE_DEVICES"] = device_id
+            p = mp.Process(
+                target=_worker_process,
+                args=(idx, device_id, chunk_tensor.cpu().numpy(), shared_args, return_queue, done_barrier),
+            )
+            p.start()
+            workers.append(p)
+
+    # Collect results before joining to prevent deadlock
+    # Tensors arrive via shared memory - copy to numpy while workers still alive
+    results_np = [None] * num_devices
+    collected = 0
+    while collected < num_devices:
+        proc_idx, result_tensor = return_queue.get()
+        results_np[proc_idx] = result_tensor.numpy()
+        collected += 1
+    
+    # Release workers now that shared tensors are copied
+    done_barrier.wait()
+    
+    # Now safe to join
+    for p in workers:
+        p.join()
+
+    # Concatenate results with overlap blending using shared function
+    if args.temporal_overlap > 0 and num_devices > 1:        
+        overlap = args.temporal_overlap
+        result_tensor = None
+        
+        for idx, res_np in enumerate(results_np):
+            chunk_tensor = torch.from_numpy(res_np).to(torch.float32)
+            
+            if idx == 0:
+                # First chunk: keep all frames
+                result_tensor = chunk_tensor
+            else:
+                # Subsequent chunks: blend overlapping region with accumulated result
+                if chunk_tensor.shape[0] > overlap and result_tensor.shape[0] >= overlap:
+                    # Get overlapping regions
+                    prev_tail = result_tensor[-overlap:]  # Last N frames from accumulated result
+                    cur_head = chunk_tensor[:overlap]      # First N frames from current chunk
+                    
+                    # Blend using shared function
+                    blended = blend_overlapping_frames(prev_tail, cur_head, overlap)
+                    
+                    # Replace tail of result with blended frames, then append rest of chunk
+                    result_tensor = torch.cat([
+                        result_tensor[:-overlap],           # Everything except the tail
+                        blended,                            # Blended overlapping frames
+                        chunk_tensor[overlap:]              # Non-overlapping part of current chunk
+                    ], dim=0)
+                else:
+                    # Edge case: chunk too small, just append non-overlapping part
+                    if chunk_tensor.shape[0] > overlap:
+                        result_tensor = torch.cat([result_tensor, chunk_tensor[overlap:]], dim=0)
+        
+        if result_tensor is None:
+            result_tensor = torch.from_numpy(results_np[0]).to(torch.float32)
+    else:
+        # Simple concatenation without overlap
+        result_tensor = torch.from_numpy(np.concatenate(results_np, axis=0)).to(torch.float32)
+
+    # Handle prepend_frames removal (multi-GPU safe - done after all workers complete)
+    if args.prepend_frames > 0:
+        if args.prepend_frames < result_tensor.shape[0]:
+            debug.log(f"Removing {args.prepend_frames} prepended frames from output", category="generation")
+            result_tensor = result_tensor[args.prepend_frames:]
+        else:
+            debug.log(f"prepend_frames ({args.prepend_frames}) >= total frames ({result_tensor.shape[0]}), skipping removal", 
+                     level="WARNING", category="generation", force=True)
+    
+    return result_tensor
+
+
+# =============================================================================
+# Argument Parsing
+# =============================================================================
+
+def parse_arguments() -> argparse.Namespace:
+    """
+    Parse and validate command-line arguments for SeedVR2 CLI.
+    
+    Configures all available options including model selection, processing parameters,
+    memory optimization settings, and output configuration.
+    
+    Returns:
+        Parsed arguments namespace with all CLI parameters
+    
+    Note:
+        - cuda_device argument only available on non-macOS systems
+        - Default model directory resolves to "models/SEEDVR2" if not specified
+    """
+    
+    # Get the actual invocation path for usage examples
+    invocation = sys.argv[0]
+    
+    # Multi-line usage examples for --help
+    usage_examples = f"""
+Examples:
+
+  Basic image upscaling:
+    python {invocation} image.jpg
+
+  Basic video upscaling with temporal consistency:
+    python {invocation} video.mp4 --resolution 720 --batch_size 33
+    
+  Streaming mode for long videos with 10-bit video output (requires FFMPEG):
+    python {invocation} long_video.mp4 --resolution 1080 --batch_size 33 --chunk_size 330 --temporal_overlap 3 --video_backend ffmpeg --10bit
+
+  Multi-GPU processing with temporal overlap:
+    python {invocation} video.mp4 --cuda_device 0,1 --resolution 1080 --batch_size 81 --uniform_batch_size --temporal_overlap 3 --prepend_frames 4 
+
+  Memory-optimized for low VRAM (8GB):
+    python {invocation} image.png --dit_model seedvr2_ema_3b-Q8_0.gguf --blocks_to_swap 32 --swap_io_components --dit_offload_device cpu --vae_offload_device cpu
+    
+  High resolution with VAE tiling:
+    python {invocation} video.mp4 --resolution 1440 --batch_size 31 --uniform_batch_size --temporal_overlap 3 --vae_encode_tiled --vae_decode_tiled
+    
+  Batch directory processing:
+    python {invocation} media_folder/ --output processed/ --cuda_device 0 --cache_dit --cache_vae --dit_offload_device cpu --vae_offload_device cpu --resolution 1080 --max_resolution 1920
+"""
+    
+    parser = argparse.ArgumentParser(
+        description="SeedVR2 Video Upscaler - CLI for high-quality image/video upscaling and batch processing",
+        epilog=usage_examples,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False
+    )
+    
+    # Input/Output
+    io_group = parser.add_argument_group('Input/Output options')
+    io_group.add_argument("input", type=str,
+                        help="Input: video file (.mp4, .avi, etc.), image file (.png, .jpg, etc.), or directory")
+    io_group.add_argument("--output", type=str, default=None,
+                        help="Output path (default: auto-generated in 'output/' directory)")
+    io_group.add_argument("--output_format", type=str, default=None, choices=["mp4", "png", None],
+                        help="Output format: 'mp4' (video) or 'png' (image sequence). Default: auto-detect from input type")
+    io_group.add_argument("--video_backend", type=str, default="opencv", choices=["opencv", "ffmpeg"],
+                        help="Video encoder backend: 'opencv' (default) or 'ffmpeg' (requires ffmpeg in PATH)")
+    io_group.add_argument("--10bit", dest="use_10bit", action="store_true",
+                        help="Save 10-bit video with x265 codec (reduces banding). Without this flag, "
+                         "ffmpeg uses x264 for maximum compatibility. Requires --video_backend ffmpeg")
+    io_group.add_argument("--model_dir", type=str, default=None,
+                        help=f"Model directory (default: ./models/{SEEDVR2_FOLDER_NAME})")
+    
+    # Model Selection
+    model_group = parser.add_argument_group('Model selection')
+    model_group.add_argument("--dit_model", type=str, default=DEFAULT_DIT,
+                        choices=get_available_dit_models(),
+                        help="DiT model to use. Options: 3B (fp16/fp8/GGUF) or 7B (fp16/fp8/GGUF). Default: 3B FP8")
+    
+    # Processing Parameters
+    process_group = parser.add_argument_group('Processing parameters')
+    process_group.add_argument("--resolution", type=int, default=1080,
+                        help="Target short-side resolution in pixels (default: 1080)")
+    process_group.add_argument("--max_resolution", type=int, default=0,
+                        help="Maximum resolution for any edge. Scales down if exceeded. 0 = no limit (default: 0)")
+    process_group.add_argument("--batch_size", type=int, default=5,
+                        help="Frames per batch (must follow 4n+1: 1, 5, 9, 13, 17, 21,...). "
+                         "Ideally matches shot length for best temporal consistency. Higher values improve "
+                         "quality and speed but require more VRAM. Default: 5")
+    process_group.add_argument("--uniform_batch_size", action="store_true",
+                        help="Pad final batch to match batch_size. Prevents temporal artifacts caused by small "
+                         "final batches. Add extra compute but recommended for optimal quality.")
+    process_group.add_argument("--seed", type=int, default=42,
+                        help="Random seed for reproducibility (default: 42)")
+    process_group.add_argument("--skip_first_frames", type=int, default=0,
+                        help="Skip N initial frames (default: 0)")
+    process_group.add_argument("--load_cap", type=int, default=0,
+                        help="Load maximum N frames from video. 0 = load all (default: 0)")
+    process_group.add_argument("--chunk_size", type=int, default=0,
+                        help="Frames per chunk for streaming mode. When > 0, processes video in "
+                             "memory-bounded chunks of N frames. 0 = load all frames at once (default: 0)")
+    process_group.add_argument("--prepend_frames", type=int, default=0,
+                        help="Prepend N reversed frames to reduce start artifacts (auto-removed). Default: 0")
+    process_group.add_argument("--temporal_overlap", type=int, default=0,
+                        help="Frames to overlap between batches/GPUs for smooth blending (default: 0)")
+    
+    # Quality Control
+    quality_group = parser.add_argument_group('Quality control')
+    quality_group.add_argument("--color_correction", type=str, default="lab", 
+                    choices=["lab", "wavelet", "wavelet_adaptive", "hsv", "adain", "none"],
+                    help="Color correction method: 'lab' (perceptual color matching, recommended), 'wavelet' (frequency-based), "
+                    "'wavelet_adaptive' (wavelet + saturation correction), 'hsv' (hue-conditional), 'adain' (statistical transfer), "
+                    "'none' (disabled) (default: lab)")
+    quality_group.add_argument("--input_noise_scale", type=float, default=0.0,
+                        help="Input noise injection scale (0.0-1.0). Adds variation to input images (default: 0.0)")
+    quality_group.add_argument("--latent_noise_scale", type=float, default=0.0,
+                        help="Latent noise injection scale (0.0-1.0). Adds variation to latent space (default: 0.0)")
+    
+    # Device Management
+    device_group = parser.add_argument_group('Device management')
+    if platform.system() != "Darwin":
+        device_group.add_argument("--cuda_device", type=str, default=None,
+                        help="CUDA device(s): single '0' or multi-GPU '0,1,2'. Default: device 0")
+    device_group.add_argument("--dit_offload_device", type=str, default="none",
+                        help="DiT offload device when idle: 'none' (keep on GPU), 'cpu' (offload to RAM), or GPU ID. "
+                             "Frees VRAM between phases. Required for BlockSwap. Default: none")
+    device_group.add_argument("--vae_offload_device", type=str, default="none",
+                        help="VAE offload device when idle: 'none', 'cpu', or GPU ID. Frees VRAM between phases. Default: none")
+    device_group.add_argument("--tensor_offload_device", type=str, default="cpu",
+                        help="Intermediate tensor storage: 'cpu' (recommended), 'none' (keep on GPU), or GPU ID. Default: cpu")
+    
+    # Memory Optimization (BlockSwap)
+    blockswap_group = parser.add_argument_group('Memory optimization (BlockSwap)')
+    blockswap_group.add_argument("--blocks_to_swap", type=int, default=0,
+                        help="Transformer blocks to swap for VRAM savings. 0-32 (3B) or 0-36 (7B). "
+                             "Requires --dit_offload_device. Not available on macOS. Default: 0 (disabled)")
+    blockswap_group.add_argument("--swap_io_components", action="store_true",
+                        help="Offload DiT I/O layers for extra VRAM savings. Requires --dit_offload_device. "
+                             "Not available on macOS")
+    
+    # VAE Tiling
+    vae_group = parser.add_argument_group('VAE tiling (for high resolution upscale)')
+    vae_group.add_argument("--vae_encode_tiled", action="store_true",
+                        help="Enable VAE encode tiling to reduce VRAM during encoding")
+    vae_group.add_argument("--vae_encode_tile_size", type=int, default=1024,
+                        help="VAE encode tile size in pixels (default: 1024). Applied to both height and width. Only used if --vae_encode_tiled is set")
+    vae_group.add_argument("--vae_encode_tile_overlap", type=int, default=128,
+                        help="VAE encode tile overlap in pixels (default: 128). Reduces visible seams between tiles. Only used if --vae_encode_tiled is set")
+    vae_group.add_argument("--vae_decode_tiled", action="store_true",
+                        help="Enable VAE decode tiling to reduce VRAM during decoding")
+    vae_group.add_argument("--vae_decode_tile_size", type=int, default=1024,
+                        help="VAE decode tile size in pixels (default: 1024). Applied to both height and width. Only used if --vae_decode_tiled is set")
+    vae_group.add_argument("--vae_decode_tile_overlap", type=int, default=128,
+                        help="VAE decode tile overlap in pixels (default: 128). Reduces visible seams between tiles. Only used if --vae_decode_tiled is set")
+    vae_group.add_argument("--tile_debug", type=str, default="false", choices=["false", "encode", "decode"],
+                        help="Visualize tiles: 'false' (default), 'encode', or 'decode'")
+    
+    # Performance
+    perf_group = parser.add_argument_group('Performance optimization')
+    perf_group.add_argument("--attention_mode", type=str, default="sdpa",
+                        choices=["sdpa", "flash_attn_2", "flash_attn_3", "sageattn_2", "sageattn_3"],
+                        help="Attention backend: 'sdpa' (default), 'flash_attn_2', 'flash_attn_3', 'sageattn_2', or 'sageattn_3' (Blackwell GPUs)")
+    perf_group.add_argument("--compile_dit", action="store_true", 
+                        help="Enable torch.compile for DiT model (20-40%% speedup, requires PyTorch 2.0+ and Triton)")
+    perf_group.add_argument("--compile_vae", action="store_true",
+                        help="Enable torch.compile for VAE model (15-25%% speedup, requires PyTorch 2.0+ and Triton)")
+    perf_group.add_argument("--compile_backend", type=str, default="inductor", choices=["inductor", "cudagraphs"],
+                        help="Compilation backend: 'inductor' (full optimization with Triton) or 'cudagraphs' (lightweight, no kernel optimization) (default: inductor)")
+    perf_group.add_argument("--compile_mode", type=str, default="default", choices=["default", "reduce-overhead", "max-autotune", "max-autotune-no-cudagraphs"],
+                        help="Optimization level: 'default' (fast compilation), 'reduce-overhead' (lower overhead), 'max-autotune' (best runtime, slow compilation), "
+                        "'max-autotune-no-cudagraphs' (like max-autotune without cudagraphs) (default: default)")
+    perf_group.add_argument("--compile_fullgraph", action="store_true",
+                        help="Compile entire model as single graph (faster but less flexible). May fail with dynamic shapes (default: False)")
+    perf_group.add_argument("--compile_dynamic", action="store_true",
+                        help="Handle varying input shapes without recompilation. Useful for different resolutions/batch sizes (default: False)")
+    perf_group.add_argument("--compile_dynamo_cache_size_limit", type=int, default=64,
+                        help="Max cached compiled versions per function. Increase when using many different input shapes. Higher uses more memory (default: 64)")
+    perf_group.add_argument("--compile_dynamo_recompile_limit", type=int, default=128,
+                        help="Max recompilation attempts before fallback to eager mode. Safety limit to prevent compilation loops (default: 128)")
+    
+    # Model Caching (for batch processing)
+    cache_group = parser.add_argument_group('Model caching (batch processing)')
+    cache_group.add_argument("--cache_dit", action="store_true",
+                        help="Keep DiT model in memory between generations. Works with single-GPU directory processing "
+                             "or multi-GPU streaming (--chunk_size). Requires --dit_offload_device")
+    cache_group.add_argument("--cache_vae", action="store_true",
+                        help="Keep VAE model in memory between generations. Works with single-GPU directory processing "
+                             "or multi-GPU streaming (--chunk_size). Requires --vae_offload_device")
+    
+    # Debugging
+    debug_group = parser.add_argument_group('Debugging')
+    debug_group.add_argument("--debug", action="store_true",
+                        help="Enable verbose debug logging")
+    
+    # Auto-show help if no arguments provided
+    if len(sys.argv) == 1:
+        sys.argv.append('--help')
+
+    return parser.parse_args()
+
+
+# =============================================================================
+# Main Entry Point
+# =============================================================================
+
+def main() -> None:
+    """
+    Main entry point for SeedVR2 Video Upscaler CLI.
+    
+    Orchestrates the complete upscaling workflow:
+        1. Parse and validate command-line arguments
+        2. Extract frames from input video/image(s)
+        3. Download required models if not cached
+        4. Process frames on single or multiple GPUs
+        5. Save results as video or PNG sequence
+        6. Report timing and FPS (calculated from total wall-clock time)
+    
+    Error handling:
+        - Validates tile configuration before processing
+        - Provides detailed error messages with traceback
+        - Ensures proper cleanup on exit (VRAM automatically freed)
+    
+    Raises:
+        SystemExit: On argument validation failure or processing error
+    """
+    # Parse arguments
+    args = parse_arguments()
+
+    # Update debug instance with --debug flag
+    debug.enabled = args.debug
+
+    # print header
+    debug.print_header(cli=True)
+    
+    debug.log("Arguments:", category="setup")
+    for key, value in vars(args).items():
+        debug.log(f"{key}: {value}", category="none", indent_level=1)
+
+    if args.vae_encode_tiled and args.vae_encode_tile_overlap >= args.vae_encode_tile_size:
+        debug.log(f"VAE encode tile overlap ({args.vae_encode_tile_overlap}) must be smaller than tile size ({args.vae_encode_tile_size})", level="ERROR", category="vae", force=True)
+        sys.exit(1)
+    
+    if args.vae_decode_tiled and args.vae_decode_tile_overlap >= args.vae_decode_tile_size:
+        debug.log(f"VAE decode tile overlap ({args.vae_decode_tile_overlap}) must be smaller than tile size ({args.vae_decode_tile_size})", level="ERROR", category="vae", force=True)
+        sys.exit(1)
+    
+    # Validate ffmpeg availability if selected
+    if args.video_backend == "ffmpeg" and shutil.which("ffmpeg") is None:
+        debug.log("--video_backend ffmpeg requires ffmpeg in PATH. Install ffmpeg or use --video_backend opencv", 
+                 level="ERROR", category="setup", force=True)
+        sys.exit(1)
+    
+    # Inform about caching defaults
+    if args.cache_dit and args.dit_offload_device == "none":
+        offload_target = "system memory (CPU)" if get_gpu_backend() != "mps" else "unified memory"
+        debug.log(
+            f"DiT caching enabled: Using default {offload_target} for offload. "
+            "Set --dit_offload_device explicitly to use a different device.",
+            category="cache", force=True
+        )
+    
+    if args.cache_vae and args.vae_offload_device == "none":
+        offload_target = "system memory (CPU)" if get_gpu_backend() != "mps" else "unified memory"
+        debug.log(
+            f"VAE caching enabled: Using default {offload_target} for offload. "
+            "Set --vae_offload_device explicitly to use a different device.",
+            category="cache", force=True
+        )
+
+    if args.debug:
+        if platform.system() == "Darwin":
+            debug.log("You are running on macOS and will use the MPS backend!", category="info", force=True)
+        else:
+            # Show actual CUDA device visibility
+            debug.log(f"CUDA_VISIBLE_DEVICES: {os.environ.get('CUDA_VISIBLE_DEVICES', 'Not set (all)')}", category="device")
+            if is_cuda_available():
+                debug.log(f"torch.cuda.device_count(): {torch.cuda.device_count()}", category="device")
+                debug.log(f"Using device index 0 inside script (mapped to selected GPU)", category="device")
+    
+    try:
+        start_time = time.time()
+        
+        # Parse GPU list
+        if platform.system() == "Darwin":
+            device_list = ["0"]
+        else:
+            if args.cuda_device:
+                device_list = [d.strip() for d in str(args.cuda_device).split(',') if d.strip()]
+            else:
+                device_list = ["0"]
+        if args.debug:
+            debug.log(f"Using devices: {device_list}", category="device")
+        
+        # Download models once before processing
+        if not download_weight(dit_model=args.dit_model, vae_model=DEFAULT_VAE, model_dir=args.model_dir, debug=debug):
+            debug.log("Failed to download required models. Check console output above.", level="ERROR", category="download", force=True)
+            sys.exit(1)
+        
+        # Determine input type and process accordingly
+        input_type = get_input_type(args.input)
+
+        # Track total frames for FPS calculation (time tracked via start_time)
+        total_frames_processed = 0
+        
+        # Track if output format was user-specified or auto-detected
+        format_auto_detected = args.output_format is None
+        
+        if input_type == 'directory':
+            media_files = get_media_files(args.input)
+            if not media_files:
+                debug.log(f"No video or image files found in directory: {args.input}", 
+                        level="ERROR", category="file", force=True)
+                sys.exit(1)
+            
+            debug.log(f"Found {len(media_files)} media files to process", category="file", force=True)
+            
+            # Multi-GPU caching requires streaming (workers cache within their chunk loops)
+            if (args.cache_dit or args.cache_vae) and len(device_list) > 1 and args.chunk_size <= 0:
+                debug.log(
+                    "Model caching requires streaming mode (--chunk_size > 0) for multi-GPU. "
+                    "Disabling caching for this run.",
+                    level="WARNING", category="cache", force=True
+                )
+                args.cache_dit = False
+                args.cache_vae = False
+            
+            # Single-GPU: runner_cache persists across files; multi-GPU: workers cache internally
+            runner_cache = {} if (args.cache_dit or args.cache_vae) and len(device_list) == 1 else None
+            
+            for idx, file_path in enumerate(media_files, 1):
+                # Visual separation between files (except before first file)
+                if idx > 1:
+                    debug.log("", category="none", force=True)
+                    debug.log("━" * 60, category="none", force=True)
+                    debug.log("", category="none", force=True)
+                
+                debug.log(f"Processing file {idx}/{len(media_files)}", category="generation", force=True)
+                
+                # Auto-detect format per file if not user-specified
+                if format_auto_detected:
+                    file_type = get_input_type(file_path)
+                    file_output_format = "mp4" if file_type == "video" else "png"
+                else:
+                    file_output_format = args.output_format
+                
+                # Temporarily override args.output_format for this file
+                original_format = args.output_format
+                args.output_format = file_output_format
+                
+                # generate_output_path handles None gracefully with "outputs" default
+                output_path = generate_output_path(file_path, file_output_format, args.output, 
+                                   input_type=get_input_type(file_path), from_directory=True)
+                
+                # Process with explicit output path and runner cache
+                frames = process_single_file(file_path, args, device_list, output_path, 
+                                            format_auto_detected=format_auto_detected,
+                                            runner_cache=runner_cache)
+                total_frames_processed += frames
+                
+                # Restore original format
+                args.output_format = original_format
+
+        elif input_type in ("video", "image"):
+            # Auto-detect output format for single file if not specified
+            if format_auto_detected:
+                args.output_format = "mp4" if input_type == "video" else "png"
+            
+            # Caching: single-GPU streaming uses runner_cache, multi-GPU streaming workers cache internally
+            runner_cache = None
+            streaming = args.chunk_size > 0
+            
+            if args.cache_dit or args.cache_vae:
+                if len(device_list) > 1:
+                    if not streaming:
+                        debug.log(
+                            "Model caching requires streaming mode (--chunk_size > 0) for multi-GPU. "
+                            "Disabling caching for this run.",
+                            level="WARNING", category="cache", force=True
+                        )
+                        args.cache_dit = False
+                        args.cache_vae = False
+                elif streaming:
+                    runner_cache = {}
+                else:
+                    debug.log(
+                        "Model caching has no benefit for single file processing (only useful for directories or streaming mode). "
+                        "Consider removing --cache_dit/--cache_vae for single files.",
+                        category="tip", force=True
+                    )
+            
+            frames = process_single_file(args.input, args, device_list, args.output,
+                                        format_auto_detected=format_auto_detected,
+                                        runner_cache=runner_cache)
+            total_frames_processed += frames
+        
+        else:
+            debug.log(f"Unsupported input type: {args.input}", level="ERROR", category="file", force=True)
+            sys.exit(1)
+        
+        # Calculate total execution time
+        total_time = time.time() - start_time
+        
+        debug.log("", category="none", force=True)
+        debug.log(f"All upscaling processes completed successfully in {total_time:.2f}s", category="success", force=True)
+        
+        # Calculate and display FPS based on overall wall-clock time
+        if total_time > 0 and total_frames_processed > 0:
+            fps = total_frames_processed / total_time
+            debug.log(f"Average FPS: {fps:.2f} frames/sec", category="timing", force=True)
+        
+    except Exception as e:
+        debug.log(f"Error during processing: {e}", level="ERROR", category="generation", force=True)
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)
+    
+    finally:
+        debug.log(f"Process {os.getpid()} terminating - VRAM will be automatically freed", category="cleanup", force=True)
+
+        # print footer
+        debug.print_footer()
+
+if __name__ == "__main__":
+    main()

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/neg_emb.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6a43e5800ef2354f1c156d27535834da055cbec8248298b8923492bba2076581
+size 656540

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/pos_emb.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fa07a14844314772266b66c3b95deb0027696d8fe7065721263db5176f45d799
+size 595100

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "seedvr2_videoupscaler"
+description = "SeedVR2 official ComfyUI integration: ByteDance-Seed's one-step diffusion-based video/image upscaling with memory-efficient inference"
+version = "2.5.24"
+authors = [
+    {name = "numz"},
+    {name = "adrientoupet"}
+]
+license = {file = "LICENSE"} 
+classifiers = [
+     "Operating System :: OS Independent"
+]
+dependencies = [
+    "torch",
+    "torchvision",
+    "safetensors",
+    "numpy",
+    "tqdm",
+    "psutil",
+    "einops",
+    "omegaconf>=2.3.0",
+    "diffusers>=0.33.1",
+    "peft>=0.17.0",
+    "rotary_embedding_torch>=0.5.3",
+    "opencv-python",
+    "gguf",
+    "matplotlib"
+]
+
+[project.urls]
+Repository = "https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler"
+Documentation = "https://www.youtube.com/@AInVFX"
+"Bug Tracker" = "https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler/issues"
+Forum = "https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler/discussions"
+
+[tool.comfy]
+PublisherId = "ainvfx"
+DisplayName = "ComfyUI-SeedVR2_VideoUpscaler"
+Icon = "https://raw.githubusercontent.com/numz/ComfyUI-SeedVR2_VideoUpscaler/refs/heads/main/docs/seedvr_logo.png"
+includes = []

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/requirements.txt

@@ -0,0 +1,14 @@
+torch
+torchvision
+safetensors
+numpy
+tqdm
+psutil
+einops
+omegaconf>=2.3.0
+diffusers>=0.33.1
+peft>=0.17.0
+rotary_embedding_torch>=0.5.3
+opencv-python
+gguf
+matplotlib

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/src/common/cache.py

@@ -0,0 +1,47 @@
+# // Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# //
+# // Licensed under the Apache License, Version 2.0 (the "License");
+# // you may not use this file except in compliance with the License.
+# // You may obtain a copy of the License at
+# //
+# //     http://www.apache.org/licenses/LICENSE-2.0
+# //
+# // Unless required by applicable law or agreed to in writing, software
+# // distributed under the License is distributed on an "AS IS" BASIS,
+# // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# // See the License for the specific language governing permissions and
+# // limitations under the License.
+
+from typing import Callable
+
+
+class Cache:
+    """Caching reusable args for faster inference"""
+
+    def __init__(self, disable=False, prefix="", cache=None):
+        self.cache = cache if cache is not None else {}
+        self.disable = disable
+        self.prefix = prefix
+
+    def __call__(self, key: str, fn: Callable):
+        if self.disable:
+            return fn()
+
+        key = self.prefix + key
+        try:
+            result = self.cache[key]
+        except KeyError:
+            result = fn()
+            self.cache[key] = result
+        return result
+
+    def namespace(self, namespace: str):
+        return Cache(
+            disable=self.disable,
+            prefix=self.prefix + namespace + ".",
+            cache=self.cache,
+        )
+
+    def get(self, key: str):
+        key = self.prefix + key
+        return self.cache[key]

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/src/common/config.py

@@ -0,0 +1,134 @@
+# // Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# //
+# // Licensed under the Apache License, Version 2.0 (the "License");
+# // you may not use this file except in compliance with the License.
+# // You may obtain a copy of the License at
+# //
+# //     http://www.apache.org/licenses/LICENSE-2.0
+# //
+# // Unless required by applicable law or agreed to in writing, software
+# // distributed under the License is distributed on an "AS IS" BASIS,
+# // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# // See the License for the specific language governing permissions and
+# // limitations under the License.
+
+"""
+Configuration utility functions
+"""
+
+import importlib
+from typing import Any, Callable, List, Union
+from omegaconf import DictConfig, ListConfig, OmegaConf
+from ..utils.model_registry import MODEL_CLASSES
+
+try:
+    OmegaConf.register_new_resolver("eval", eval)
+except Exception as e:
+    if "already registered" not in str(e):
+        raise
+
+
+
+def load_config(path: str, argv: List[str] = None) -> Union[DictConfig, ListConfig]:
+    """
+    Load a configuration. Will resolve inheritance.
+    """
+    
+    #print(path)
+    config = OmegaConf.load(path)
+    if argv is not None:
+        config_argv = OmegaConf.from_dotlist(argv)
+        config = OmegaConf.merge(config, config_argv)
+    config = resolve_recursive(config, resolve_inheritance)
+    return config
+
+
+def resolve_recursive(
+    config: Any,
+    resolver: Callable[[Union[DictConfig, ListConfig]], Union[DictConfig, ListConfig]],
+) -> Any:
+    config = resolver(config)
+    if isinstance(config, DictConfig):
+        for k in config.keys():
+            v = config.get(k)
+            if isinstance(v, (DictConfig, ListConfig)):
+                config[k] = resolve_recursive(v, resolver)
+    if isinstance(config, ListConfig):
+        for i in range(len(config)):
+            v = config.get(i)
+            if isinstance(v, (DictConfig, ListConfig)):
+                config[i] = resolve_recursive(v, resolver)
+    return config
+
+
+def resolve_inheritance(config: Union[DictConfig, ListConfig]) -> Any:
+    """
+    Recursively resolve inheritance if the config contains:
+    __inherit__: path/to/parent.yaml or a ListConfig of such paths.
+    """
+    if isinstance(config, DictConfig):
+        inherit = config.pop("__inherit__", None)
+
+        if inherit:
+            inherit_list = inherit if isinstance(inherit, ListConfig) else [inherit]
+
+            parent_config = None
+            for parent_path in inherit_list:
+                assert isinstance(parent_path, str)
+                parent_config = (
+                    load_config(parent_path)
+                    if parent_config is None
+                    else OmegaConf.merge(parent_config, load_config(parent_path))
+                )
+
+            if len(config.keys()) > 0:
+                config = OmegaConf.merge(parent_config, config)
+            else:
+                config = parent_config
+    return config
+
+
+def import_item(path: str, name: str) -> Any:
+    """
+    Import a python item, checking model registry first.
+    
+    Args:
+        path: Module path
+        name: Class/function name to import
+        
+    Returns:
+        Imported object
+    """
+    # Simple lookup with path as key
+    if path in MODEL_CLASSES:
+        return MODEL_CLASSES[path]
+    
+    # Fallback to dynamic import for everything else
+    try:
+        return getattr(importlib.import_module(path), name)
+    except (ImportError, AttributeError) as e:
+        raise ImportError(f"Could not import '{name}' from '{path}': {e}")
+
+
+def create_object(config: DictConfig) -> Any:
+    """
+    Create an object from config.
+    The config is expected to contains the following:
+    __object__:
+      path: path.to.module
+      name: MyClass
+      args: as_config | as_params (default to as_config)
+    """
+    
+    item = import_item(
+        path=config.__object__.path,
+        name=config.__object__.name,
+    )
+    args = config.__object__.get("args", "as_config")
+    if args == "as_config":
+        return item(config)
+    if args == "as_params":
+        config = OmegaConf.to_object(config)
+        config.pop("__object__")
+        return item(**config)
+    raise NotImplementedError(f"Unknown args type: {args}")

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/src/common/decorators.py

@@ -0,0 +1,130 @@
+# // Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# //
+# // Licensed under the Apache License, Version 2.0 (the "License");
+# // you may not use this file except in compliance with the License.
+# // You may obtain a copy of the License at
+# //
+# //     http://www.apache.org/licenses/LICENSE-2.0
+# //
+# // Unless required by applicable law or agreed to in writing, software
+# // distributed under the License is distributed on an "AS IS" BASIS,
+# // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# // See the License for the specific language governing permissions and
+# // limitations under the License.
+
+"""
+Decorators.
+"""
+
+import functools
+import threading
+import time
+from typing import Callable
+import torch
+
+from .distributed import barrier_if_distributed, get_global_rank, get_local_rank
+from .logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def log_on_entry(func: Callable) -> Callable:
+    """
+    Functions with this decorator will log the function name at entry.
+    When using multiple decorators, this must be applied innermost to properly capture the name.
+    """
+
+    def log_on_entry_wrapper(*args, **kwargs):
+        logger.info(f"Entering {func.__name__}")
+        return func(*args, **kwargs)
+
+    return log_on_entry_wrapper
+
+
+def barrier_on_entry(func: Callable) -> Callable:
+    """
+    Functions with this decorator will start executing when all ranks are ready to enter.
+    """
+
+    def barrier_on_entry_wrapper(*args, **kwargs):
+        barrier_if_distributed()
+        return func(*args, **kwargs)
+
+    return barrier_on_entry_wrapper
+
+
+def _conditional_execute_wrapper_factory(execute: bool, func: Callable) -> Callable:
+    """
+    Helper function for local_rank_zero_only and global_rank_zero_only.
+    """
+
+    def conditional_execute_wrapper(*args, **kwargs):
+        # Only execute if needed.
+        result = func(*args, **kwargs) if execute else None
+        # All GPUs must wait.
+        barrier_if_distributed()
+        # Return results.
+        return result
+
+    return conditional_execute_wrapper
+
+
+def _asserted_wrapper_factory(condition: bool, func: Callable, err_msg: str = "") -> Callable:
+    """
+    Helper function for some functions with special constraints,
+    especially functions called by other global_rank_zero_only / local_rank_zero_only ones,
+    in case they are wrongly invoked in other scenarios.
+    """
+
+    def asserted_execute_wrapper(*args, **kwargs):
+        assert condition, err_msg
+        result = func(*args, **kwargs)
+        return result
+
+    return asserted_execute_wrapper
+
+
+def local_rank_zero_only(func: Callable) -> Callable:
+    """
+    Functions with this decorator will only execute on local rank zero.
+    """
+    return _conditional_execute_wrapper_factory(get_local_rank() == 0, func)
+
+
+def global_rank_zero_only(func: Callable) -> Callable:
+    """
+    Functions with this decorator will only execute on global rank zero.
+    """
+    return _conditional_execute_wrapper_factory(get_global_rank() == 0, func)
+
+
+def assert_only_global_rank_zero(func: Callable) -> Callable:
+    """
+    Functions with this decorator are only accessible to processes with global rank zero.
+    """
+    return _asserted_wrapper_factory(
+        get_global_rank() == 0, func, err_msg="Not accessible to processes with global_rank != 0"
+    )
+
+
+def assert_only_local_rank_zero(func: Callable) -> Callable:
+    """
+    Functions with this decorator are only accessible to processes with local rank zero.
+    """
+    return _asserted_wrapper_factory(
+        get_local_rank() == 0, func, err_msg="Not accessible to processes with local_rank != 0"
+    )
+
+
+def new_thread(func: Callable) -> Callable:
+    """
+    Functions with this decorator will run in a new thread.
+    The function will return the thread, which can be joined to wait for completion.
+    """
+
+    def new_thread_wrapper(*args, **kwargs):
+        thread = threading.Thread(target=func, args=args, kwargs=kwargs)
+        thread.start()
+        return thread
+
+    return new_thread_wrapper

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/src/common/diffusion/__init__.py

@@ -0,0 +1,56 @@
+# // Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# //
+# // Licensed under the Apache License, Version 2.0 (the "License");
+# // you may not use this file except in compliance with the License.
+# // You may obtain a copy of the License at
+# //
+# //     http://www.apache.org/licenses/LICENSE-2.0
+# //
+# // Unless required by applicable law or agreed to in writing, software
+# // distributed under the License is distributed on an "AS IS" BASIS,
+# // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# // See the License for the specific language governing permissions and
+# // limitations under the License.
+
+"""
+Diffusion package.
+"""
+
+from .config import (
+    create_sampler_from_config,
+    create_sampling_timesteps_from_config,
+    create_schedule_from_config,
+)
+from .samplers.base import Sampler
+from .samplers.euler import EulerSampler
+from .schedules.base import Schedule
+from .schedules.lerp import LinearInterpolationSchedule
+from .timesteps.base import SamplingTimesteps, Timesteps
+from .timesteps.sampling.trailing import UniformTrailingSamplingTimesteps
+from .types import PredictionType, SamplingDirection
+from .utils import classifier_free_guidance, classifier_free_guidance_dispatcher, expand_dims
+
+__all__ = [
+    # Configs
+    "create_sampler_from_config",
+    "create_sampling_timesteps_from_config",
+    "create_schedule_from_config",
+    # Schedules
+    "Schedule",
+    "DiscreteVariancePreservingSchedule",
+    "LinearInterpolationSchedule",
+    # Samplers
+    "Sampler",
+    "EulerSampler",
+    # Timesteps
+    "Timesteps",
+    "SamplingTimesteps",
+    # Types
+    "PredictionType",
+    "SamplingDirection",
+    "UniformTrailingSamplingTimesteps",
+    # Utils
+    "classifier_free_guidance",
+    "classifier_free_guidance_dispatcher",
+    "expand_dims",
+]

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/src/common/diffusion/config.py

@@ -0,0 +1,75 @@
+# // Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# //
+# // Licensed under the Apache License, Version 2.0 (the "License");
+# // you may not use this file except in compliance with the License.
+# // You may obtain a copy of the License at
+# //
+# //     http://www.apache.org/licenses/LICENSE-2.0
+# //
+# // Unless required by applicable law or agreed to in writing, software
+# // distributed under the License is distributed on an "AS IS" BASIS,
+# // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# // See the License for the specific language governing permissions and
+# // limitations under the License.
+
+"""
+Utility functions for creating schedules and samplers from config.
+"""
+
+import torch
+from omegaconf import DictConfig
+
+from .samplers.base import Sampler
+from .samplers.euler import EulerSampler
+from .schedules.base import Schedule
+from .schedules.lerp import LinearInterpolationSchedule
+from .timesteps.base import SamplingTimesteps
+from .timesteps.sampling.trailing import UniformTrailingSamplingTimesteps
+
+
+def create_schedule_from_config(
+    config: DictConfig,
+    device: torch.device,
+    dtype: torch.dtype = torch.float32,
+) -> Schedule:
+    """
+    Create a schedule from configuration.
+    """
+    if config.type == "lerp":
+        return LinearInterpolationSchedule(T=config.get("T", 1.0))
+
+    raise NotImplementedError
+
+
+def create_sampler_from_config(
+    config: DictConfig,
+    schedule: Schedule,
+    timesteps: SamplingTimesteps,
+) -> Sampler:
+    """
+    Create a sampler from configuration.
+    """
+    if config.type == "euler":
+        return EulerSampler(
+            schedule=schedule,
+            timesteps=timesteps,
+            prediction_type=config.prediction_type,
+        )
+    raise NotImplementedError
+
+
+def create_sampling_timesteps_from_config(
+    config: DictConfig,
+    schedule: Schedule,
+    device: torch.device,
+    dtype: torch.dtype = torch.float32,
+) -> SamplingTimesteps:
+    if config.type == "uniform_trailing":
+        return UniformTrailingSamplingTimesteps(
+            T=schedule.T,
+            steps=config.steps,
+            shift=config.get("shift", 1.0),
+            device=device,
+            dtype=dtype,
+        )
+    raise NotImplementedError

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/src/common/diffusion/samplers/base.py

@@ -0,0 +1,108 @@
+# // Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# //
+# // Licensed under the Apache License, Version 2.0 (the "License");
+# // you may not use this file except in compliance with the License.
+# // You may obtain a copy of the License at
+# //
+# //     http://www.apache.org/licenses/LICENSE-2.0
+# //
+# // Unless required by applicable law or agreed to in writing, software
+# // distributed under the License is distributed on an "AS IS" BASIS,
+# // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# // See the License for the specific language governing permissions and
+# // limitations under the License.
+
+"""
+Sampler base class.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Callable
+import torch
+from tqdm import tqdm
+
+from ..schedules.base import Schedule
+from ..timesteps.base import SamplingTimesteps
+from ..types import PredictionType, SamplingDirection
+from ..utils import assert_schedule_timesteps_compatible
+
+
+@dataclass
+class SamplerModelArgs:
+    x_t: torch.Tensor
+    t: torch.Tensor
+    i: int
+
+
+class Sampler(ABC):
+    """
+    Samplers are ODE/SDE solvers.
+    """
+
+    def __init__(
+        self,
+        schedule: Schedule,
+        timesteps: SamplingTimesteps,
+        prediction_type: PredictionType,
+        return_endpoint: bool = True,
+    ):
+        assert_schedule_timesteps_compatible(
+            schedule=schedule,
+            timesteps=timesteps,
+        )
+        self.schedule = schedule
+        self.timesteps = timesteps
+        self.prediction_type = prediction_type
+        self.return_endpoint = return_endpoint
+
+    @abstractmethod
+    def sample(
+        self,
+        x: torch.Tensor,
+        f: Callable[[SamplerModelArgs], torch.Tensor],
+    ) -> torch.Tensor:
+        """
+        Generate a new sample given the the intial sample x and score function f.
+        """
+
+    def get_next_timestep(
+        self,
+        t: torch.Tensor,
+    ) -> torch.Tensor:
+        """
+        Get the next sample timestep.
+        Support multiple different timesteps t in a batch.
+        If no more steps, return out of bound value -1 or T+1.
+        """
+        T = self.timesteps.T
+        steps = len(self.timesteps)
+        curr_idx = self.timesteps.index(t)
+        next_idx = curr_idx + 1
+        bound = -1 if self.timesteps.direction == SamplingDirection.backward else T + 1
+
+        s = self.timesteps[next_idx.clamp_max(steps - 1)]
+        s = s.where(next_idx < steps, bound)
+        return s
+
+    def get_endpoint(
+        self,
+        pred: torch.Tensor,
+        x_t: torch.Tensor,
+        t: torch.Tensor,
+    ) -> torch.Tensor:
+        """
+        Get to the endpoint of the probability flow.
+        """
+        x_0, x_T = self.schedule.convert_from_pred(pred, self.prediction_type, x_t, t)
+        return x_0 if self.timesteps.direction == SamplingDirection.backward else x_T
+
+    def get_progress_bar(self):
+        """
+        Get progress bar for sampling.
+        """
+        return tqdm(
+            iterable=range(len(self.timesteps) - (0 if self.return_endpoint else 1)),
+            dynamic_ncols=True,
+            desc=self.__class__.__name__,
+        )

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/src/common/diffusion/samplers/euler.py

@@ -0,0 +1,99 @@
+# // Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# //
+# // Licensed under the Apache License, Version 2.0 (the "License");
+# // you may not use this file except in compliance with the License.
+# // You may obtain a copy of the License at
+# //
+# //     http://www.apache.org/licenses/LICENSE-2.0
+# //
+# // Unless required by applicable law or agreed to in writing, software
+# // distributed under the License is distributed on an "AS IS" BASIS,
+# // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# // See the License for the specific language governing permissions and
+# // limitations under the License.
+
+
+"""
+Euler ODE solver.
+"""
+
+from typing import Callable
+import torch
+from einops import rearrange
+from torch.nn import functional as F
+
+from ..types import PredictionType
+from ..utils import expand_dims
+from .base import Sampler, SamplerModelArgs
+
+
+class EulerSampler(Sampler):
+    """
+    The Euler method is the simplest ODE solver.
+    <https://en.wikipedia.org/wiki/Euler_method>
+    """
+
+    def sample(
+        self,
+        x: torch.Tensor,
+        f: Callable[[SamplerModelArgs], torch.Tensor],
+    ) -> torch.Tensor:
+        timesteps = self.timesteps.timesteps
+        progress = self.get_progress_bar()
+        i = 0
+        
+        # Keep native dtype throughout sampling
+        # The DiT model already handles dtype internally via compatibility wrapper
+        for t, s in zip(timesteps[:-1], timesteps[1:]):
+            pred = f(SamplerModelArgs(x, t, i))
+            
+            # Next step
+            x = self.step_to(pred, x, t, s)
+            
+            # Clean up temporary tensors
+            del pred
+            
+            i += 1
+            progress.update()
+
+        if self.return_endpoint:
+            t = timesteps[-1]
+            pred = f(SamplerModelArgs(x, t, i))
+            x = self.get_endpoint(pred, x, t)
+            del pred
+            progress.update()
+            
+        return x
+
+    def step(
+        self,
+        pred: torch.Tensor,
+        x_t: torch.Tensor,
+        t: torch.Tensor,
+    ) -> torch.Tensor:
+        """
+        Step to the next timestep.
+        """
+        return self.step_to(pred, x_t, t, self.get_next_timestep(t))
+
+    def step_to(
+        self,
+        pred: torch.Tensor,
+        x_t: torch.Tensor,
+        t: torch.Tensor,
+        s: torch.Tensor,
+    ) -> torch.Tensor:
+        """
+        Steps from x_t at timestep t to x_s at timestep s. Returns x_s.
+        """
+        t = expand_dims(t, x_t.ndim)
+        s = expand_dims(s, x_t.ndim)
+        T = self.schedule.T
+        # Step from x_t to x_s.
+        pred_x_0, pred_x_T = self.schedule.convert_from_pred(pred, self.prediction_type, x_t, t)
+        pred_x_s = self.schedule.forward(pred_x_0, pred_x_T, s.clamp(0, T))
+        # Clamp x_s to x_0 and x_T if s is out of bound.
+        pred_x_s = pred_x_s.where(s >= 0, pred_x_0)
+        pred_x_s = pred_x_s.where(s <= T, pred_x_T)
+        return pred_x_s
+    

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/src/common/diffusion/schedules/base.py

@@ -0,0 +1,131 @@
+# // Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# //
+# // Licensed under the Apache License, Version 2.0 (the "License");
+# // you may not use this file except in compliance with the License.
+# // You may obtain a copy of the License at
+# //
+# //     http://www.apache.org/licenses/LICENSE-2.0
+# //
+# // Unless required by applicable law or agreed to in writing, software
+# // distributed under the License is distributed on an "AS IS" BASIS,
+# // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# // See the License for the specific language governing permissions and
+# // limitations under the License.
+
+"""
+Schedule base class.
+"""
+
+from abc import ABC, abstractmethod, abstractproperty
+from typing import Tuple, Union
+import torch
+
+from ..types import PredictionType
+from ..utils import expand_dims
+
+
+class Schedule(ABC):
+    """
+    Diffusion schedules are uniquely defined by T, A, B:
+
+        x_t = A(t) * x_0 + B(t) * x_T, where t in [0, T]
+
+    Schedules can be continuous or discrete.
+    """
+
+    @abstractproperty
+    def T(self) -> Union[int, float]:
+        """
+        Maximum timestep inclusive.
+        Schedule is continuous if float, discrete if int.
+        """
+
+    @abstractmethod
+    def A(self, t: torch.Tensor) -> torch.Tensor:
+        """
+        Interpolation coefficient A.
+        Returns tensor with the same shape as t.
+        """
+
+    @abstractmethod
+    def B(self, t: torch.Tensor) -> torch.Tensor:
+        """
+        Interpolation coefficient B.
+        Returns tensor with the same shape as t.
+        """
+
+    # ----------------------------------------------------
+
+    def snr(self, t: torch.Tensor) -> torch.Tensor:
+        """
+        Signal to noise ratio.
+        Returns tensor with the same shape as t.
+        """
+        return (self.A(t) ** 2) / (self.B(t) ** 2)
+
+    def isnr(self, snr: torch.Tensor) -> torch.Tensor:
+        """
+        Inverse signal to noise ratio.
+        Returns tensor with the same shape as snr.
+        Subclass may implement.
+        """
+        raise NotImplementedError
+
+    # ----------------------------------------------------
+
+    def is_continuous(self) -> bool:
+        """
+        Whether the schedule is continuous.
+        """
+        return isinstance(self.T, float)
+
+    def forward(self, x_0: torch.Tensor, x_T: torch.Tensor, t: torch.Tensor) -> torch.Tensor:
+        """
+        Diffusion forward function.
+        """
+        t = expand_dims(t, x_0.ndim)
+        return self.A(t) * x_0 + self.B(t) * x_T
+
+    def convert_from_pred(
+        self, pred: torch.Tensor, pred_type: PredictionType, x_t: torch.Tensor, t: torch.Tensor
+    ) -> Tuple[torch.Tensor, torch.Tensor]:
+        """
+        Convert from prediction. Return predicted x_0 and x_T.
+        """
+        t = expand_dims(t, x_t.ndim)
+        A_t = self.A(t)
+        B_t = self.B(t)
+
+        if pred_type == PredictionType.x_T:
+            pred_x_T = pred
+            pred_x_0 = (x_t - B_t * pred_x_T) / A_t
+        elif pred_type == PredictionType.x_0:
+            pred_x_0 = pred
+            pred_x_T = (x_t - A_t * pred_x_0) / B_t
+        elif pred_type == PredictionType.v_cos:
+            pred_x_0 = A_t * x_t - B_t * pred
+            pred_x_T = A_t * pred + B_t * x_t
+        elif pred_type == PredictionType.v_lerp:
+            pred_x_0 = (x_t - B_t * pred) / (A_t + B_t)
+            pred_x_T = (x_t + A_t * pred) / (A_t + B_t)
+        else:
+            raise NotImplementedError
+
+        return pred_x_0, pred_x_T
+
+    def convert_to_pred(
+        self, x_0: torch.Tensor, x_T: torch.Tensor, t: torch.Tensor, pred_type: PredictionType
+    ) -> torch.FloatTensor:
+        """
+        Convert to prediction target given x_0 and x_T.
+        """
+        if pred_type == PredictionType.x_T:
+            return x_T
+        if pred_type == PredictionType.x_0:
+            return x_0
+        if pred_type == PredictionType.v_cos:
+            t = expand_dims(t, x_0.ndim)
+            return self.A(t) * x_T - self.B(t) * x_0
+        if pred_type == PredictionType.v_lerp:
+            return x_T - x_0
+        raise NotImplementedError

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/src/common/diffusion/schedules/lerp.py

@@ -0,0 +1,55 @@
+# // Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# //
+# // Licensed under the Apache License, Version 2.0 (the "License");
+# // you may not use this file except in compliance with the License.
+# // You may obtain a copy of the License at
+# //
+# //     http://www.apache.org/licenses/LICENSE-2.0
+# //
+# // Unless required by applicable law or agreed to in writing, software
+# // distributed under the License is distributed on an "AS IS" BASIS,
+# // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# // See the License for the specific language governing permissions and
+# // limitations under the License.
+
+"""
+Linear interpolation schedule (lerp).
+"""
+
+from typing import Union
+import torch
+
+from .base import Schedule
+
+
+class LinearInterpolationSchedule(Schedule):
+    """
+    Linear interpolation schedule (lerp) is proposed by flow matching and rectified flow.
+    It leads to straighter probability flow theoretically. It is also used by Stable Diffusion 3.
+    <https://arxiv.org/abs/2209.03003>
+    <https://arxiv.org/abs/2210.02747>
+
+        x_t = (1 - t) * x_0 + t * x_T
+
+    Can be either continuous or discrete.
+    """
+
+    def __init__(self, T: Union[int, float] = 1.0):
+        self._T = T
+
+    @property
+    def T(self) -> Union[int, float]:
+        return self._T
+
+    def A(self, t: torch.Tensor) -> torch.Tensor:
+        return 1 - (t / self.T)
+
+    def B(self, t: torch.Tensor) -> torch.Tensor:
+        return t / self.T
+
+    # ----------------------------------------------------
+
+    def isnr(self, snr: torch.Tensor) -> torch.Tensor:
+        t = self.T / (1 + snr**0.5)
+        t = t if self.is_continuous() else t.round().int()
+        return t

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/src/common/diffusion/timesteps/base.py

@@ -0,0 +1,72 @@
+from abc import ABC, abstractmethod
+from typing import Sequence, Union
+import torch
+
+from ..types import SamplingDirection
+
+
+class Timesteps(ABC):
+    """
+    Timesteps base class.
+    """
+
+    def __init__(self, T: Union[int, float]):
+        assert T > 0
+        self._T = T
+
+    @property
+    def T(self) -> Union[int, float]:
+        """
+        Maximum timestep inclusive.
+        int if discrete, float if continuous.
+        """
+        return self._T
+
+    def is_continuous(self) -> bool:
+        """
+        Whether the schedule is continuous.
+        """
+        return isinstance(self.T, float)
+
+
+class SamplingTimesteps(Timesteps):
+    """
+    Sampling timesteps.
+    It defines the discretization of sampling steps.
+    """
+
+    def __init__(
+        self,
+        T: Union[int, float],
+        timesteps: torch.Tensor,
+        direction: SamplingDirection,
+    ):
+        assert timesteps.ndim == 1
+        super().__init__(T)
+        self.timesteps = timesteps
+        self.direction = direction
+
+    def __len__(self) -> int:
+        """
+        Number of sampling steps.
+        """
+        return len(self.timesteps)
+
+    def __getitem__(self, idx: Union[int, torch.IntTensor]) -> torch.Tensor:
+        """
+        The timestep at the sampling step.
+        Returns a scalar tensor if idx is int,
+        or tensor of the same size if idx is a tensor.
+        """
+        return self.timesteps[idx]
+
+    def index(self, t: torch.Tensor) -> torch.Tensor:
+        """
+        Find index by t.
+        Return index of the same shape as t.
+        Index is -1 if t not found in timesteps.
+        """
+        i, j = t.reshape(-1, 1).eq(self.timesteps).nonzero(as_tuple=True)
+        idx = torch.full_like(t, fill_value=-1, dtype=torch.int)
+        idx.view(-1)[i] = j.int()
+        return idx

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/src/common/diffusion/timesteps/sampling/trailing.py

@@ -0,0 +1,50 @@
+# // Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# //
+# // Licensed under the Apache License, Version 2.0 (the "License");
+# // you may not use this file except in compliance with the License.
+# // You may obtain a copy of the License at
+# //
+# //     http://www.apache.org/licenses/LICENSE-2.0
+# //
+# // Unless required by applicable law or agreed to in writing, software
+# // distributed under the License is distributed on an "AS IS" BASIS,
+# // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# // See the License for the specific language governing permissions and
+# // limitations under the License.
+
+import torch
+
+from ...types import SamplingDirection
+from ..base import SamplingTimesteps
+
+
+class UniformTrailingSamplingTimesteps(SamplingTimesteps):
+    """
+    Uniform trailing sampling timesteps.
+    Defined in (https://arxiv.org/abs/2305.08891)
+
+    Shift is proposed in SD3 for RF schedule.
+    Defined in (https://arxiv.org/pdf/2403.03206) eq.23
+    """
+
+    def __init__(
+        self,
+        T: int,
+        steps: int,
+        shift: float = 1.0,
+        device: torch.device = "cpu",
+        dtype: torch.dtype = torch.float32,
+    ):
+        # Create trailing timesteps with specified dtype
+        timesteps = torch.arange(1.0, 0.0, -1.0 / steps, device='cpu').to(device=device, dtype=dtype)
+
+        # Shift timesteps.
+        timesteps = shift * timesteps / (1 + (shift - 1) * timesteps)
+
+        # Scale to T range.
+        if isinstance(T, float):
+            timesteps = timesteps * T
+        else:
+            timesteps = timesteps.mul(T + 1).sub(1).round().int()
+
+        super().__init__(T=T, timesteps=timesteps, direction=SamplingDirection.backward)

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/src/common/diffusion/types.py

@@ -0,0 +1,59 @@
+# // Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# //
+# // Licensed under the Apache License, Version 2.0 (the "License");
+# // you may not use this file except in compliance with the License.
+# // You may obtain a copy of the License at
+# //
+# //     http://www.apache.org/licenses/LICENSE-2.0
+# //
+# // Unless required by applicable law or agreed to in writing, software
+# // distributed under the License is distributed on an "AS IS" BASIS,
+# // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# // See the License for the specific language governing permissions and
+# // limitations under the License.
+
+"""
+Type definitions.
+"""
+
+from enum import Enum
+
+
+class PredictionType(str, Enum):
+    """
+    x_0:
+        Predict data sample.
+    x_T:
+        Predict noise sample.
+        Proposed by DDPM (https://arxiv.org/abs/2006.11239)
+        Proved problematic by zsnr paper (https://arxiv.org/abs/2305.08891)
+    v_cos:
+        Predict velocity dx/dt based on the cosine schedule (A_t * x_T - B_t * x_0).
+        Proposed by progressive distillation (https://arxiv.org/abs/2202.00512)
+    v_lerp:
+        Predict velocity dx/dt based on the lerp schedule (x_T - x_0).
+        Proposed by rectified flow (https://arxiv.org/abs/2209.03003)
+    """
+
+    x_0 = "x_0"
+    x_T = "x_T"
+    v_cos = "v_cos"
+    v_lerp = "v_lerp"
+
+
+class SamplingDirection(str, Enum):
+    """
+    backward: Sample from x_T to x_0 for data generation.
+    forward:  Sample from x_0 to x_T for noise inversion.
+    """
+
+    backward = "backward"
+    forward = "forward"
+
+    @staticmethod
+    def reverse(direction):
+        if direction == SamplingDirection.backward:
+            return SamplingDirection.forward
+        if direction == SamplingDirection.forward:
+            return SamplingDirection.backward
+        raise NotImplementedError

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/src/common/diffusion/utils.py

@@ -0,0 +1,84 @@
+# // Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# //
+# // Licensed under the Apache License, Version 2.0 (the "License");
+# // you may not use this file except in compliance with the License.
+# // You may obtain a copy of the License at
+# //
+# //     http://www.apache.org/licenses/LICENSE-2.0
+# //
+# // Unless required by applicable law or agreed to in writing, software
+# // distributed under the License is distributed on an "AS IS" BASIS,
+# // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# // See the License for the specific language governing permissions and
+# // limitations under the License.
+
+"""
+Utility functions.
+"""
+
+from typing import Callable
+import torch
+
+
+def expand_dims(tensor: torch.Tensor, ndim: int):
+    """
+    Expand tensor to target ndim. New dims are added to the right.
+    For example, if the tensor shape was (8,), target ndim is 4, return (8, 1, 1, 1).
+    """
+    shape = tensor.shape + (1,) * (ndim - tensor.ndim)
+    return tensor.reshape(shape)
+
+
+def assert_schedule_timesteps_compatible(schedule, timesteps):
+    """
+    Check if schedule and timesteps are compatible.
+    """
+    if schedule.T != timesteps.T:
+        raise ValueError("Schedule and timesteps must have the same T.")
+    if schedule.is_continuous() != timesteps.is_continuous():
+        raise ValueError("Schedule and timesteps must have the same continuity.")
+
+
+def classifier_free_guidance(
+    pos: torch.Tensor,
+    neg: torch.Tensor,
+    scale: float,
+    rescale: float = 0.0,
+):
+    """
+    Apply classifier-free guidance.
+    """
+    # Classifier-free guidance (https://arxiv.org/abs/2207.12598)
+    cfg = neg + scale * (pos - neg)
+
+    # Classifier-free guidance rescale (https://arxiv.org/pdf/2305.08891.pdf)
+    if rescale != 0.0:
+        pos_std = pos.std(dim=list(range(1, pos.ndim)), keepdim=True)
+        cfg_std = cfg.std(dim=list(range(1, cfg.ndim)), keepdim=True)
+        factor = pos_std / cfg_std
+        factor = rescale * factor + (1 - rescale)
+        cfg *= factor
+
+    return cfg
+
+
+def classifier_free_guidance_dispatcher(
+    pos: Callable,
+    neg: Callable,
+    scale: float,
+    rescale: float = 0.0,
+):
+    """
+    Optionally execute models depending on classifer-free guidance scale.
+    """
+    # If scale is 1, no need to execute neg model.
+    if scale == 1.0:
+        return pos()
+
+    # Otherwise, execute both pos nad neg models and apply cfg.
+    return classifier_free_guidance(
+        pos=pos(),
+        neg=neg(),
+        scale=scale,
+        rescale=rescale,
+    )

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/src/common/distributed/__init__.py

@@ -0,0 +1,37 @@
+# // Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# //
+# // Licensed under the Apache License, Version 2.0 (the "License");
+# // you may not use this file except in compliance with the License.
+# // You may obtain a copy of the License at
+# //
+# //     http://www.apache.org/licenses/LICENSE-2.0
+# //
+# // Unless required by applicable law or agreed to in writing, software
+# // distributed under the License is distributed on an "AS IS" BASIS,
+# // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# // See the License for the specific language governing permissions and
+# // limitations under the License.
+
+"""
+Distributed package.
+"""
+
+from .basic import (
+    barrier_if_distributed,
+    convert_to_ddp,
+    get_device,
+    get_global_rank,
+    get_local_rank,
+    get_world_size,
+    init_torch,
+)
+
+__all__ = [
+    "barrier_if_distributed",
+    "convert_to_ddp",
+    "get_device",
+    "get_global_rank",
+    "get_local_rank",
+    "get_world_size",
+    "init_torch",
+]

v3-nodes/ComfyUI-SeedVR2_VideoUpscaler/src/common/distributed/advanced.py

@@ -0,0 +1,223 @@
+# // Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+# //
+# // Licensed under the Apache License, Version 2.0 (the "License");
+# // you may not use this file except in compliance with the License.
+# // You may obtain a copy of the License at
+# //
+# //     http://www.apache.org/licenses/LICENSE-2.0
+# //
+# // Unless required by applicable law or agreed to in writing, software
+# // distributed under the License is distributed on an "AS IS" BASIS,
+# // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# // See the License for the specific language governing permissions and
+# // limitations under the License.
+
+"""
+Advanced distributed functions for sequence parallel.
+"""
+
+from typing import Optional, List, TYPE_CHECKING
+import torch
+import torch.distributed as dist
+
+# Conditional imports for distributed training features (not needed for inference)
+try:
+    from torch.distributed.device_mesh import DeviceMesh, init_device_mesh
+    from torch.distributed.fsdp import ShardingStrategy
+    _FSDP_AVAILABLE = True
+except (ImportError, AttributeError):
+    # AMD ROCm and other builds may not have full FSDP support
+    DeviceMesh = None
+    init_device_mesh = None
+    ShardingStrategy = None
+    _FSDP_AVAILABLE = False
+
+from .basic import get_global_rank, get_world_size
+
+
+_DATA_PARALLEL_GROUP = None
+_SEQUENCE_PARALLEL_GROUP = None
+_SEQUENCE_PARALLEL_CPU_GROUP = None
+_MODEL_SHARD_CPU_INTER_GROUP = None
+_MODEL_SHARD_CPU_INTRA_GROUP = None
+_MODEL_SHARD_INTER_GROUP = None
+_MODEL_SHARD_INTRA_GROUP = None
+_SEQUENCE_PARALLEL_GLOBAL_RANKS = None
+
+
+def get_data_parallel_group() -> Optional[dist.ProcessGroup]:
+    """
+    Get data parallel process group.
+    """
+    return _DATA_PARALLEL_GROUP
+
+
+def get_sequence_parallel_group() -> Optional[dist.ProcessGroup]:
+    """
+    Get sequence parallel process group.
+    """
+    return _SEQUENCE_PARALLEL_GROUP
+
+
+def get_sequence_parallel_cpu_group() -> Optional[dist.ProcessGroup]:
+    """
+    Get sequence parallel CPU process group.
+    """
+    return _SEQUENCE_PARALLEL_CPU_GROUP
+
+
+def get_data_parallel_rank() -> int:
+    """
+    Get data parallel rank.
+    """
+    group = get_data_parallel_group()
+    return dist.get_rank(group) if group else get_global_rank()
+
+
+def get_data_parallel_world_size() -> int:
+    """
+    Get data parallel world size.
+    """
+    group = get_data_parallel_group()
+    return dist.get_world_size(group) if group else get_world_size()
+
+
+def get_sequence_parallel_rank() -> int:
+    """
+    Get sequence parallel rank.
+    """
+    group = get_sequence_parallel_group()
+    return dist.get_rank(group) if group else 0
+
+
+def get_sequence_parallel_world_size() -> int:
+    """
+    Get sequence parallel world size.
+    """
+    group = get_sequence_parallel_group()
+    return dist.get_world_size(group) if group else 1
+
+
+def get_model_shard_cpu_intra_group() -> Optional[dist.ProcessGroup]:
+    """
+    Get the CPU intra process group of model sharding.
+    """
+    return _MODEL_SHARD_CPU_INTRA_GROUP
+
+
+def get_model_shard_cpu_inter_group() -> Optional[dist.ProcessGroup]:
+    """
+    Get the CPU inter process group of model sharding.
+    """
+    return _MODEL_SHARD_CPU_INTER_GROUP
+
+
+def get_model_shard_intra_group() -> Optional[dist.ProcessGroup]:
+    """
+    Get the GPU intra process group of model sharding.
+    """
+    return _MODEL_SHARD_INTRA_GROUP
+
+
+def get_model_shard_inter_group() -> Optional[dist.ProcessGroup]:
+    """
+    Get the GPU inter process group of model sharding.
+    """
+    return _MODEL_SHARD_INTER_GROUP
+
+
+def init_sequence_parallel(sequence_parallel_size: int):
+    """
+    Initialize sequence parallel.
+    """
+    global _DATA_PARALLEL_GROUP
+    global _SEQUENCE_PARALLEL_GROUP
+    global _SEQUENCE_PARALLEL_CPU_GROUP
+    global _SEQUENCE_PARALLEL_GLOBAL_RANKS
+    assert dist.is_initialized()
+    world_size = dist.get_world_size()
+    rank = dist.get_rank()
+    data_parallel_size = world_size // sequence_parallel_size
+    for i in range(data_parallel_size):
+        start_rank = i * sequence_parallel_size
+        end_rank = (i + 1) * sequence_parallel_size
+        ranks = range(start_rank, end_rank)
+        group = dist.new_group(ranks)
+        cpu_group = dist.new_group(ranks, backend="gloo")
+        if rank in ranks:
+            _SEQUENCE_PARALLEL_GROUP = group
+            _SEQUENCE_PARALLEL_CPU_GROUP = cpu_group
+            _SEQUENCE_PARALLEL_GLOBAL_RANKS = list(ranks)
+
+
+def init_model_shard_group(
+    *,
+    sharding_strategy: ShardingStrategy,
+    device_mesh: Optional[DeviceMesh] = None,
+):
+    """
+    Initialize process group of model sharding.
+    """
+    if not _FSDP_AVAILABLE:
+        raise RuntimeError(
+            "FSDP features are not available in this PyTorch build. "
+            "Model sharding requires torch.distributed.fsdp support."
+        )
+    global _MODEL_SHARD_INTER_GROUP
+    global _MODEL_SHARD_INTRA_GROUP
+    global _MODEL_SHARD_CPU_INTER_GROUP
+    global _MODEL_SHARD_CPU_INTRA_GROUP
+    assert dist.is_initialized()
+    world_size = dist.get_world_size()
+    if device_mesh is not None:
+        num_shards_per_group = device_mesh.shape[1]
+    elif sharding_strategy == ShardingStrategy.NO_SHARD:
+        num_shards_per_group = 1
+    elif sharding_strategy in [
+        ShardingStrategy.HYBRID_SHARD,
+        ShardingStrategy._HYBRID_SHARD_ZERO2,
+    ]:
+        num_shards_per_group = torch.cuda.device_count()
+    else:
+        num_shards_per_group = world_size
+    num_groups = world_size // num_shards_per_group
+    device_mesh = (num_groups, num_shards_per_group)
+
+    gpu_mesh_2d = init_device_mesh("cuda", device_mesh, mesh_dim_names=("inter", "intra"))
+    cpu_mesh_2d = init_device_mesh("cpu", device_mesh, mesh_dim_names=("inter", "intra"))
+
+    _MODEL_SHARD_INTER_GROUP = gpu_mesh_2d.get_group("inter")
+    _MODEL_SHARD_INTRA_GROUP = gpu_mesh_2d.get_group("intra")
+    _MODEL_SHARD_CPU_INTER_GROUP = cpu_mesh_2d.get_group("inter")
+    _MODEL_SHARD_CPU_INTRA_GROUP = cpu_mesh_2d.get_group("intra")
+
+def get_sequence_parallel_global_ranks() -> List[int]:
+    """
+    Get all global ranks of the sequence parallel process group
+    that the caller rank belongs to.
+    """
+    if _SEQUENCE_PARALLEL_GLOBAL_RANKS is None:
+        return [dist.get_rank()]
+    return _SEQUENCE_PARALLEL_GLOBAL_RANKS
+
+
+def get_next_sequence_parallel_rank() -> int:
+    """
+    Get the next global rank of the sequence parallel process group
+    that the caller rank belongs to.
+    """
+    sp_global_ranks = get_sequence_parallel_global_ranks()
+    sp_rank = get_sequence_parallel_rank()
+    sp_size = get_sequence_parallel_world_size()
+    return sp_global_ranks[(sp_rank + 1) % sp_size]
+
+
+def get_prev_sequence_parallel_rank() -> int:
+    """
+    Get the previous global rank of the sequence parallel process group
+    that the caller rank belongs to.
+    """
+    sp_global_ranks = get_sequence_parallel_global_ranks()
+    sp_rank = get_sequence_parallel_rank()
+    sp_size = get_sequence_parallel_world_size()
+    return sp_global_ranks[(sp_rank + sp_size - 1) % sp_size]