scenedetect Package

See also

For the scenedetect command, see the CLI reference.

The scenedetect API is easy to integrate with most application workflows, while also being highly extensible. See the Usage 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.7

Usage

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", scene_list)

More tasks, each shown as a command and as Python, are on the Examples page. For advanced workflows, start with the SceneManager. Logging is covered under Platform & Logging.

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.

detect(video_path, detector, stats_file_path=None, show_progress=False, start_time=None, end_time=None, start_in_scene=False, backend='opencv')

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

Parameters:

  • video_path (StrPath | list[StrPath] | tuple[StrPath, ...]) – Path to input video (absolute or relative to working directory). May also be a list of paths, in which case the videos are concatenated and treated as a single continuous stream.

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

  • stats_file_path (str | PathLike[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 (int | float | str | Timecode | FrameTimecode | 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 (int | float | str | Timecode | FrameTimecode | 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.

  • backend (str) – Name of the backend to use for video decoding. See scenedetect.backends.AVAILABLE_BACKENDS for backends available on the current system. Defaults to OpenCV; falls back to OpenCV if the requested backend is unavailable or fails to open the video.

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’]]

open_video(path, frame_rate=None, backend='opencv', framerate=None, **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 | PathLike[str] | list[str | os.PathLike[str]] | tuple[str | os.PathLike[str], ...]) – Path to video file to open. May also be a list of paths, in which case the videos are concatenated and treated as a single continuous stream (see VideoStreamConcat).

  • frame_rate (float | Fraction | None) – Overrides detected frame rate if set. Takes precedence over framerate.

  • 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.

  • framerate (float | None) – [DEPRECATED] Use frame_rate instead. Retained as a deprecated alias for backwards compatibility; ignored when frame_rate is provided.

  • 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