PySceneDetect is a BSD-3-Clause licensed Python and OpenCV program and library that detects scene cuts and transitions in video, built for developers, video engineers, and automated media pipelines that need to locate shot boundaries without scrubbing through footage by hand.

What it is

PySceneDetect is an open-source video cut detection and analysis tool that ships in two forms: a command line program invoked as scenedetect, and a Python library imported as scenedetect that exposes the same detection engine through an API. It lives in the Python and OpenCV ecosystem, using image-processing detectors to analyse frames, and it pairs with external video tools rather than duplicating them — ffmpeg and mkvmerge are required for video splitting support. The project is distributed on PyPI, as Windows builds (an MSI installer and a portable ZIP), and as a Docker image published to GitHub Container Registry. Documentation, a CLI quickstart, and a download page are maintained at scenedetect.com.

The concrete problem it solves is the manual identification of shot boundaries. Rather than a person scrubbing a timeline and writing down timecodes, PySceneDetect analyses the video and returns a scene list containing the start and end times and frame numbers of every scene it finds. That list is what the rest of a workflow consumes: it can be printed, iterated over scene by scene, used to drive video splitting, or passed into a Python pipeline. It replaces hand-logged cut lists with a repeatable, configurable detection pass, and it can also export representative frames from each cut automatically.

Key capabilities

• Content-aware detection through a single high-level call: detect("my_video.mp4", ContentDetector()) returns a scene list, with print(scene_list) or per-scene iteration using scene[0].get_timecode(), scene[0].frame_num, and the corresponding end values.
• Alternative detection algorithms for harder material: a two-pass AdaptiveDetector that handles fast camera movement better, and a ThresholdDetector for fade out and fade in events.
• Command line operations including scenedetect -i video.mp4 split-video to split on each fast cut using ffmpeg, save-images to save frames from each cut, and time -s 10s to skip the first ten seconds of input.
• Programmatic video splitting through split_video_ffmpeg("my_video.mp4", scene_list), with mkvmerge also supported as a splitter.
• Lower-level API access built from open_video, SceneManager, and detectors imported from scenedetect.detectors, allowing configuration that integrates with an existing pipeline.
• Deployment packages that remove setup work: a Docker image at ghcr.io/breakthrough/pyscenedetect with all dependencies included, plus Windows MSI and portable ZIP builds.

Who uses it and how

• Editorial and post-production workflows that need to log every cut in a clip and export a frame from each scene for thumbnails or storyboards.
• Automated pipelines and developer tooling that call the Python API directly — for example a split_video_into_scenes(video_path, threshold=27.0) function — and need configurable thresholds rather than a fixed behaviour.
• Headless and containerised deployments that run the Docker image, mounting the folder holding the videos and reading results back from the same mount.
• Batch processing of local video collections, where the command line interface is driven repeatedly on files in a directory.
• Windows-based users who prefer installing the MSI or unpacking the portable ZIP instead of managing a Python environment.

Getting started

Install and upgrade with pip install scenedetect --upgrade, then run commands such as scenedetect -i video.mp4 split-video; video splitting additionally requires ffmpeg or mkvmerge. Alternatively, run the Docker image ghcr.io/breakthrough/pyscenedetect, which includes those dependencies, or download the Windows MSI installer or portable ZIP from the project's download page.

How it compares

The supplied facts do not name any comparable scene-detection projects, so PySceneDetect stands alone in this registry as a dedicated cut and transition detection entry rather than as one option among several listed alternatives. It is complementary to the tools it names: ffmpeg and mkvmerge are used for the splitting step, while PySceneDetect supplies the scene list that tells them where to cut.

When to use it — and when not to

A self-hoster should expect to provide a Python environment, or use the Docker image or Windows packages if they would rather not, and should note that video splitting depends on an external ffmpeg or mkvmerge installation unless the Docker image is used. Detection also requires some tuning: the documented example threshold is 27.0, and material with fast camera movement may call for the two-pass AdaptiveDetector instead of the default. It is the wrong choice for anyone expecting a graphical editing interface, since the documented interfaces are the command line, the Python API, and the packaged installers rather than a point-and-click application.

pip install scenedetect --upgrade

scenedetect -i video.mp4 split-video

scenedetect -i video.mp4 save-images

scenedetect -i video.mp4 time -s 10s

docker run --rm -v "$(pwd):/files" ghcr.io/breakthrough/pyscenedetect -i /files/video.mp4 split-video -o /files

from scenedetect import detect, ContentDetector

scene_list = detect("my_video.mp4", ContentDetector())

from scenedetect import detect, ContentDetector

scene_list = detect("my_video.mp4", ContentDetector())
for i, scene in enumerate(scene_list):
    print(
        "    Scene %2d: Start %s / Frame %d, End %s / Frame %d"
        % (
            i + 1,
            scene[0].get_timecode(),
            scene[0].frame_num,
            scene[1].get_timecode(),
            scene[1].frame_num,
        )
    )

from scenedetect import detect, ContentDetector, split_video_ffmpeg

scene_list = detect("my_video.mp4", ContentDetector())
split_video_ffmpeg("my_video.mp4", scene_list)

from scenedetect import open_video, SceneManager, split_video_ffmpeg
from scenedetect.detectors import ContentDetector
from scenedetect.video_splitter import split_video_ffmpeg


def split_video_into_scenes(video_path, threshold=27.0):
    # Open our video, create a scene manager, and add a detector.
    video = open_video(video_path)
    scene_manager = SceneManager()
    scene_manager.add_detector(ContentDetector(threshold=threshold))
    scene_manager.detect_scenes(video, show_progress=True)
    scene_list = scene_manager.get_scene_list()
    split_video_ffmpeg(video_path, scene_list, show_progress=True)