PySceneDetect
title: PySceneDetect type: tool created: 2026-06-22 last_updated: 2026-06-22 related: ["radar/techniques/SemanticFrameScoring", "radar/languages/CLIP", "radar/languages/Ultralytics", "radar/tools/FireRedOpenStoryline"] sources: ["https://github.com/Breakthrough/PySceneDetect"] radar_quadrant: Tools radar_ring: Assess radar_position: inner
PySceneDetect is a Python library and CLI tool for detecting shot boundaries in video files. It segments a video into scenes by detecting content transitions, fades, and cuts, and optionally splits the video into individual clip files. BSD-3-Clause license, 4.9k stars, v0.7 released May 3 2026, maintained by Brandon Castellano.
pip install scenedetect --upgradeCLI usage:
scenedetect -i video.mp4 detect-content split-videoPython API:
from scenedetect import detect, ContentDetector
scenes = detect("video.mp4", ContentDetector())
# scenes: list of (FrameTimecode, FrameTimecode) tuplesThree built-in detectors: ContentDetector (frame difference), AdaptiveDetector (two-pass, handles fast camera movement), ThresholdDetector (fade in/out). Video splitting requires an external binary (ffmpeg or mkvmerge).
detect() returns a list of (start, end) FrameTimecode pairs. Each FrameTimecode exports as seconds, frame number, or timecode string, making the output directly consumable as a segment list. The library describes itself as "highly configurable, and can easily integrate with any pipeline." In the radar/techniques/SemanticFrameScoring pattern, PySceneDetect runs as the first stage: it identifies shot boundaries so that radar/languages/CLIP scores only representative frames per shot rather than every frame in the video. This reduces CLIP calls by a factor proportional to average shot length.
PySceneDetect solves the frame sampling problem upstream of both detection and semantic scoring stages. Without shot segmentation, a naive approach samples frames at a fixed interval and may over-represent long static shots or under-represent rapid cuts. PySceneDetect's AdaptiveDetector handles both: it identifies genuine content changes and ignores within-shot camera movement.
Downstream of PySceneDetect, the segment list feeds either radar/languages/Ultralytics (object detection per shot), radar/languages/CLIP (semantic frame scoring), or both. The final ranked and filtered segment list passes to radar/tools/FireRedOpenStoryline as editing instructions.
Placed in Tools / Trial / inner.
PySceneDetect is actively maintained (v0.7, May 2026), BSD-licensed, pip-installable, and explicitly designed for pipeline integration. The CLI and Python API cover both one-shot scripts and embedded pipeline use. 61 open issues is a manageable backlog for a single-maintainer project. The inner Trial position reflects that it fills a specific, well-defined role (shot boundary detection) at the entry point of any video discovery pipeline, with no architectural complexity and no GPU requirement.
Trial gate: confirmed use in a production video pipeline where scene boundaries feed a downstream selection or editing stage with programmatic consumption of the output timestamps.
