Migration Guide

This page details how to transition a program written using PySceneDetect v0.5 to the new v0.6 API. It is recommended to review the new Quickstart and Example sections first, as they should cover the majority of use cases. Also see tests/test_api.py for a set of demonstrations covering many high level use cases.

PySceneDetect v0.6 is a major step towards a more stable and simplified API. The biggest change to existing workflows is how video input is handled, and that Python 3.6 or above is now required.

This page covers commonly used APIs which require updates to work with v0.6. Note that this page is not an exhaustive set of changes. For a complete list of breaking API changes, see the changelog.

In some places, a backwards compatibility layer has been added to avoid breaking most applications upon release. This should not be relied upon, and will be removed in the future. You can call scenedetect.platform.init_logger(show_stdout=True) or attach a custom log handler to the 'pyscenedetect' logger to help find these cases.

VideoManager Class

VideoManager has been deprecated and replaced with scenedetect.backends. For most applications, the open_video function should be used instead:

from scenedetect import open_video
video = open_video(video.mp4')

The resulting object can then be passed to a SceneManager when calling detect_scenes, or any other function/method that used to take a VideoManager, e.g.:

from scenedetect import open_video, SceneManager, ContentDetector
video = open_video('video.mp4')
scene_manager = SceneManager()
scene_manager.add_detector(ContentDetector(threshold=threshold))
scene_manager.detect_scenes(video)
print(scene_manager.get_scene_list())

See scenedetect.backends for examples of how to create specific backends. Where previously a list of paths was accepted, now only a single string should be provided.

Seeking and Start/End Times

Instead of setting the start time via the VideoManager, now seek to the starting time on the VideoStream object.

Instead of setting the duration or end time via the VideoManager, now set the duration or end_time parameters when calling detect_scenes.

from scenedetect import open_video, SceneManager, ContentDetector
video = open_video('video.mp4')
# Can be seconds (float), frame # (int), or FrameTimecode
start_time, end_time = 2.5, 5.0
scene_manager = SceneManager()
scene_manager.add_detector(ContentDetector(threshold=threshold))
video.seek(start_time)
# Note there is also a `duration` parameter that can also be set.
# If neither `duration` nor `end_time` is provided, the video will
# be processed from its current position until the end.
scene_manager.detect_scenes(video, end_time=end_time)
print(scene_manager.get_scene_list())

SceneManager Class

The first argument of the detect_scenes method has been renamed to video and should now be a VideoStream object (see above).

save_images Function

The second argument of save_images in scenedetect.scene_manager has been renamed from video_manager to video.

The downscale_factor parameter has been removed from save_images (use the scale parameter instead). To achieve the same result as the previous version, set scale to 1.0 / downscale_factor.

split_video_* Functions

The the scenedetect.video_splitter functions split_video_ffmpeg and split_video_mkvmerge now only accept a single path as the input (first) argument.

The suppress_output and hide_progress arguments to the split_video_ffmpeg and split_video_mkvmerge have been removed, and two new options have been added:

  • suppress_output is now show_output, default is False

  • hide_progress is now show_progress, default is False

This makes the API consistent with that of SceneManager.

StatsManager Class

The save_to_csv and load_from_csv methods now accept either a path or an open file handle.

The base_timecode argument has been removed from save_to_csv. It is no longer required.

AdaptiveDetector Class

The video_manager parameter has been removed and is no longer required when constructing an AdaptiveDetector object.

Other

ThresholdDetector Class

The block_size argument has been removed from the ThresholdDetector constructor. It is no longer required.

ContentDetector Class

The calculate_frame_score method of ContentDetector has been renamed to _calculate_frame_score. Use new global function calculate_frame_score to achieve the same result.

MINIMUM_FRAMES_PER_SECOND_* Constants

In scenedetect.frame_timecode the constants MINIMUM_FRAMES_PER_SECOND_FLOAT and MINIMUM_FRAMES_PER_SECOND_DELTA_FLOAT have been replaced with MAX_FPS_DELTA.

get_aspect_ratio Function

The get_aspect_ratio function has been removed from scenedetect.platform. Use the aspect_ratio property from the VideoStream object instead.