scenedetect 🎬 Package

The scenedetect API is easy to integrate with most application workflows, while also being highly extensible. See the Getting Started section below for some common use cases and integrations. The scenedetect package is organized into several sub-modules:

Most types/functions are also available directly from the scenedetect package to make imports simpler.

Warning

The PySceneDetect API is still under development. It is recommended that you pin the scenedetect version in your requirements to below the next major release:

scenedetect<0.8

Getting Started

PySceneDetect makes it very easy to find scene transitions in a video with the scenedetect.detect() function:

from scenedetect import detect, ContentDetector
path = "video.mp4"
scenes = detect(path, ContentDetector())
for (scene_start, scene_end) in scenes:
    print(f"{scene_start}-{scene_end}")

scenes now contains a list of FrameTimecode pairs representing the start/end of each scene. Note that you can set show_progress=True when calling detect to display a progress bar with estimated time remaining.

Here, we use ContentDetector to detect fast cuts. There are many detector types which can be used to find fast cuts and fades in/out. PySceneDetect can also export scene data in various formats, and can split the input video automatically if ffmpeg is available:

from scenedetect import detect, ContentDetector, split_video_ffmpeg
scene_list = detect("my_video.mp4", ContentDetector())
split_video_ffmpeg("my_video.mp4", scenes)

Recipes for common use cases can be found on Github including limiting detection time and storing per-frame metrics. For advanced workflows, start with the SceneManager usage examples.

Functions

The scenedetect module comes with helper functions to simplify common use cases. detect() can be used to perform scene detection on a video by path. open_video() can be used to open a video for a SceneManager.

scenedetect.detect(video_path, detector, stats_file_path=None, show_progress=False, start_time=None, end_time=None, start_in_scene=False)

Perform scene detection on a given video path using the specified detector.

Parameters:

  • video_path (str) – Path to input video (absolute or relative to working directory).

  • detector (SceneDetector) – A SceneDetector instance (see scenedetect.detectors for a full list of detectors).

  • stats_file_path (str | None) – Path to save per-frame metrics to for statistical analysis or to determine a better threshold value.

  • show_progress (bool) – Show a progress bar with estimated time remaining. Default is False.

  • start_time (str | float | int | None) – Starting point in video, in the form of a timecode HH:MM:SS[.nnn] (str), number of seconds 123.45 (float), or number of frames 200 (int).

  • end_time (str | float | int | None) – Starting point in video, in the form of a timecode HH:MM:SS[.nnn] (str), number of seconds 123.45 (float), or number of frames 200 (int).

  • start_in_scene (bool) – Assume the video begins in a scene. This means that when detecting fast cuts with ContentDetector, if no cuts are found, the resulting scene list will contain a single scene spanning the entire video (instead of no scenes). When detecting fades with ThresholdDetector, the beginning portion of the video will always be included until the first fade-out event is detected.

Returns:

List of scenes as pairs of (start, end) FrameTimecode objects.

Raises:

  • VideoOpenFailure – video_path could not be opened.

  • StatsFileCorrupt – stats_file_path is an invalid stats file

  • ValueError – start_time or end_time are incorrectly formatted.

  • TypeError – start_time or end_time are invalid types.

Return type:

List[Tuple[FrameTimecode, FrameTimecode]]

scenedetect.open_video(path, framerate=None, backend='opencv', **kwargs)

Open a video at the given path. If backend is specified but not available on the current system, OpenCV (VideoStreamCv2) will be used as a fallback.

Parameters:

  • path (str) – Path to video file to open.

  • framerate (float | None) – Overrides detected framerate if set.

  • backend (str) – Name of specific backend to use, if possible. See scenedetect.backends.AVAILABLE_BACKENDS for backends available on the current system. If the backend fails to open the video, OpenCV will be used as a fallback.

  • kwargs – Optional named arguments to pass to the specified backend constructor for overriding backend-specific options.

Returns:

Backend object created with the specified video path.

Raises:

VideoOpenFailure – Constructing the VideoStream fails. If multiple backends have been attempted, the error from the first backend will be returned.

Return type:

VideoStream

Module Reference

PySceneDetect Module Documentation

Logging

PySceneDetect outputs messages to a logger named pyscenedetect which does not have any default handlers. You can use scenedetect.init_logger with show_stdout=True or specify a log file (verbosity can also be specified) to attach some common handlers, or use logging.getLogger("pyscenedetect") and attach log handlers manually.