scenedetect 🎬 Package

Overview

The scenedetect API is designed to be extensible and easy to integrate with most application workflows. Many use cases are covered by the Quickstart and Example sections below. The scenedetect package provides:

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

Note

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

Quickstart

To get started, the scenedetect.detect() function takes a path to a video and a scene detector object, and returns a list of start/end timecodes. For detecting fast cuts (shot changes), we use the ContentDetector:

from scenedetect import detect, ContentDetector
scene_list = detect('my_video.mp4', ContentDetector())

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

Next, let’s print the scene list in a more readable format by iterating over it:

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].get_frames(),
        scene[1].get_timecode(), scene[1].get_frames(),))

Now that we know where each scene is, we can also split the input video automatically using ffmpeg (mkvmerge is also supported):

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

This is just a small snippet of what PySceneDetect offers. The library is very modular, and can integrate with most application workflows easily.

In the next example, we show how the library components can be used to create a more customizable scene cut/shot detection pipeline. Additional demonstrations/recipes can be found in the tests/test_api.py file.

Example

In this example, we create a function find_scenes() which will load a video, detect the scenes, and return a list of tuples containing the (start, end) timecodes of each detected scene. Note that you can modify the threshold argument to modify the sensitivity of the ContentDetector, or use other detection algorithms (e.g. ThresholdDetector, AdaptiveDetector).

from scenedetect import SceneManager, open_video, ContentDetector

def find_scenes(video_path, threshold=27.0):
    video = open_video(video_path)
    scene_manager = SceneManager()
    scene_manager.add_detector(
        ContentDetector(threshold=threshold))
    # Detect all scenes in video from current position to end.
    scene_manager.detect_scenes(video)
    # `get_scene_list` returns a list of start/end timecode pairs
    # for each scene that was found.
    return scene_manager.get_scene_list()

Using a SceneManager directly allows tweaking the Parameters passed to detect_scenes including setting a limit to the number of frames to process, which is useful for live streams/camera devices. You can also combine detection algorithms or create new ones from scratch.

For a more advanced example of using the PySceneDetect API to with a stats file (to save per-frame metrics to disk and/or speed up multiple passes of the same video), take a look at the example in the SceneManager reference.

In addition to module-level examples, demonstrations of some common use cases can be found in the tests/test_api.py file.

Migrating From 0.5

PySceneDetect 0.6 introduces several breaking changes which are incompatible with 0.5. See Migration Guide for details on how to update your application. In addition, demonstrations of common use cases can be found in the tests/test_api.py file.

Module-Level Functions

detect

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 (pairs of 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

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

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.