Comfyui-SceneDetect

Comfyui-SceneDetect

Comfyui-SceneDetect adds PySceneDetect-based scene detection to ComfyUI. The recommended node accepts ComfyUI's built-in VIDEO type and processes the source without materializing every frame as an IMAGE batch. A Legacy VHS node is retained for existing workflows. Both nodes return one representative image per scene, scene metadata as JSON, and the detected scene count.

Features

• Direct support for ComfyUI's built-in Load Video and VIDEO type
• Low-memory processing in the recommended node without materializing the complete video as a float32 IMAGE batch
• Backward-compatible Legacy VHS node for existing workflows
• Export one representative frame per scene as an IMAGE batch (choose start/middle/end)
• Provide detailed scene metadata as JSON (frame numbers, timestamps, durations, etc.)
• Optionally store representative frames as JPEG thumbnails

Requirements

• ComfyUI with built-in VIDEO support for the recommended node
• Python 3.10 or newer
• PySceneDetect 0.7 and OpenCV (installed through this package's dependency list)
• ComfyUI-VideoHelperSuite (VHS) only when using the Legacy VHS node

Installation

Installing from ComfyUI Manager also installs the Python dependencies listed below. For a manual clone:

1. Place this repository under the ComfyUI custom_nodes directory.

   • Example: ComfyUI/custom_nodes/Comfyui-SceneDetect

2. Install the Python dependencies.

   pip install -r requirements.txt
   

   The requirements.txt file includes:

   • scenedetect-headless>=0.7.1,<0.8
   • opencv-python-headless>=4.9
   • numpy

   scenedetect-headless provides the same scenedetect Python module without GUI dependencies.

   PyTorch (torch) ships with the standard ComfyUI installation, so it is intentionally not listed here.

3. Restart ComfyUI.

Node Name and Category

• Node: PySceneDetect: Video → Scenes (recommended, built-in VIDEO input)
• Legacy node: PySceneDetect: Scenes → Images (Legacy VHS)
• Category: Video/PySceneDetect

Once installed, the node can be searched and placed directly inside ComfyUI.

Which node should I use?

| | Recommended | Legacy | |---|---|---| | SceneDetect node | PySceneDetect: Video → Scenes | PySceneDetect: Scenes → Images (Legacy VHS) | | Loader | ComfyUI built-in Load Video | VHS Load Video (Upload) | | Input | Lazy VIDEO | Full IMAGE batch + VHS_VIDEOINFO | | Memory use | Only compressed video decoding and representative frames | VHS must keep the full float32 frame batch in memory | | Use case | New workflows and long/high-resolution videos | Existing VHS workflows |

Inputs and Outputs

PySceneDetect: Video → Scenes

• Required inputs

  • video (VIDEO): Connect the output from ComfyUI's built-in Load Video node. The video is streamed from the compressed source instead of being expanded into a full frame batch.
  • method (content|adaptive|threshold): Scene detection method.
  • threshold (FLOAT): Detection threshold used by the content/threshold methods.
  • min_scene_len_sec (FLOAT): Minimum scene length in seconds. Values greater than zero override min_scene_len_frames.
  • min_scene_len_frames (INT): Minimum scene length in frames, used when min_scene_len_sec is 0.
  • luma_only (BOOLEAN): Use luma-only detection (content/adaptive only; threshold uses color in PySceneDetect 0.7).

• Optional inputs

  • representative (start|middle|end): Position of the representative frame.
  • max_width (INT): Maximum width of the representative frame (0 disables resizing).
  • max_height (INT): Maximum height of the representative frame (0 disables resizing).
  • limit_scenes (INT): Limit the number of scenes processed from the start (0 disables the limit).
  • write_thumbs (BOOLEAN): Save representative frames as JPEG thumbnails.
  • thumbs_dir (STRING): Relative directory under ComfyUI's output directory. When empty, thumbnails are written to output/scene_thumbs.

• Outputs

  • images (IMAGE): Representative frame batch ((B,H,W,C)).
  • scenes_json (STRING): JSON string with scene metadata (includes video_info).
  • scene_count (INT): Number of detected scenes.

PySceneDetect: Scenes → Images (Legacy VHS)

workflow_legacy_vhs

The legacy node keeps its original node ID, inputs, and outputs so existing workflows continue to load.

• Connect IMAGE output 1 from VHS Load Video (Upload) to image.
• Connect VHS_VIDEOINFO output 4 to video_info.
• Do not connect a VAE; latent batches are unsupported.
• The node processes the supplied tensor one frame at a time, but the full VHS IMAGE batch still remains resident in memory.

JSON Output Example (scenes_json)

{
  "video_path": "",
  "video_info": {
    "loaded_fps": 29.97,
    "loaded_frame_count": 120,
    "source_fps": 29.97
  },
  "fps": 29.97,
  "method": "content",
  "threshold": 27.0,
  "min_scene_len_frames": 15,
  "representative": "start",
  "scenes": [
    {
      "index": 1,
      "start_frame": 0,
      "end_frame": 153,
      "duration_frames": 153,
      "fps": 29.97,
      "start_time": "00:00:00.000",
      "end_time": "00:00:05.105",
      "duration_sec": 5.105105105105105
    }
  ]
}

Each entry in the scenes array provides the start/end frame indices, SMPTE-style timestamps, and the duration of the scene.

Usage in ComfyUI

1. Load a video with ComfyUI's built-in Load Video node.
2. Add PySceneDetect: Video → Scenes and connect the VIDEO output directly.
3. Adjust method, threshold, and min_scene_len_* to match the video source.
4. Configure the representative frame position, optional resizing, and thumbnail export settings.
5. Execute the graph to receive representative frames on images and scene metadata on scenes_json.

Both samples use ComfyUI's built-in Preview Image and Preview as Text nodes:

• Recommended: workflow/pyscene_workflow.json
• Legacy VHS: workflow/pyscene_workflow_legacy_vhs.json

Existing workflows containing PySceneDetectToImages continue to load as the Legacy VHS node.

Memory Behavior

The recommended node receives a lazy VIDEO object from ComfyUI's built-in loader. PySceneDetect reads the original compressed file directly, and only the selected representative frames are returned as an IMAGE batch. It does not create a full float32 frame batch.

The Legacy VHS path cannot release the frame batch supplied by VHS, but SceneDetect processes that batch one frame at a time without creating full RGB/BGR copies. For new workflows, use the built-in Load Video path to avoid the VHS batch allocation entirely.

Project Layout

• The root __init__.py follows the standard ComfyUI structure and registers nodes.
• The built-in VIDEO implementation lives in nodes/pyscenedetect_video.py, the VHS-compatible implementation lives in nodes/pyscenedetect_to_images.py, and shared helpers reside in utils/video_ops.py.

Troubleshooting

• High memory use with VHS: Prefer the built-in Load Video and PySceneDetect: Video → Scenes. The legacy VHS path must keep its full IMAGE batch in memory.
• Latent batches in legacy workflows: If a VAE is connected to the VHS Load Video, its LATENT output is unsupported. Output RGB frames instead.
• OpenCV fails to open the video: Check codecs and file paths. Confirm that opencv-python-headless is installed.
• PySceneDetect version mismatch: Reinstall within the range defined in requirements.txt.
• Empty or 1x1 black output: Indicates the input failed to decode. Validate the source frames and configuration.

License

This project is licensed under the MIT License. See LICENSE for the complete text. Files that specify a different license are governed by the terms noted within those files.

Third-party notices:

• PySceneDetect is distributed under the BSD 3-Clause License. When redistributing binaries or source packages that bundle PySceneDetect, ensure that its copyright notice, license text, and disclaimer are included alongside your distribution.