SceneDetector

scenedetect.scene_detector Module

This module contains the SceneDetector interface, from which all scene detectors in scenedetect.detectors module are derived from.

The SceneDetector class represents the interface which detection algorithms are expected to provide in order to be compatible with PySceneDetect.

Warning

This API is still unstable, and changes and design improvements are planned for the v1.0 release. Instead of just timecodes, detection algorithms will also provide a specific type of event (in, out, cut, etc…).

class scenedetect.scene_detector.SceneDetector

Base class to inherit from when implementing a scene detection algorithm.

This API is not yet stable and subject to change.

This represents a “dense” scene detector, which returns a list of frames where the next scene/shot begins in a video.

Also see the implemented scene detectors in the scenedetect.detectors module to get an idea of how a particular detector can be created.

get_metrics()

Get Metrics: Get a list of all metric names/keys used by the detector.

Returns:

List of strings of frame metric key names that will be used by the detector when a StatsManager is passed to process_frame.

Return type:

List[str]

is_processing_required(frame_num)

[DEPRECATED] DO NOT USE

Test if all calculations for a given frame are already done.

Returns:

False if the SceneDetector has assigned _metric_keys, and the stats_manager property is set to a valid StatsManager object containing the required frame metrics/calculations for the given frame - thus, not needing the frame to perform scene detection.

True otherwise (i.e. the frame_img passed to process_frame is required to be passed to process_frame for the given frame_num).

Parameters:

frame_num (int) –

Return type:

bool

post_process(frame_num)

Post Process: Performs any processing after the last frame has been read.

Prototype method, no actual detection.

Returns:

List of frame numbers of cuts to be added to the cutting list.

Parameters:

frame_num (int) –

Return type:

List[int]

process_frame(frame_num, frame_img)

Process the next frame. frame_num is assumed to be sequential.

Parameters:

• frame_num (int) – Frame number of frame that is being passed. Can start from any value but must remain sequential.

• frame_img (numpy.ndarray or None) – Video frame corresponding to frame_img.

Returns:

List of frames where scene cuts have been detected. There may be 0 or more frames in the list, and not necessarily the same as frame_num.

Return type:

List[int]

Returns:

List of frame numbers of cuts to be added to the cutting list.

stats_manager_required()

Stats Manager Required: Prototype indicating if detector requires stats.

Returns:

True if a StatsManager is required for the detector, False otherwise.

Return type:

bool

property event_buffer_length: int

The amount of frames a given event can be buffered for, in time. Represents maximum amount any event can be behind frame_number in the result of process_frame().

stats_manager: StatsManager | None = None

Optional StatsManager to use for caching frame metrics to and from.

class scenedetect.scene_detector.SparseSceneDetector

Base class to inherit from when implementing a sparse scene detection algorithm.

This class will be removed in v1.0 and should not be used.

Unlike dense detectors, sparse detectors detect “events” and return a pair of frames, as opposed to just a single cut.

An example of a SparseSceneDetector is the MotionDetector.

post_process(frame_num)

Post Process: Performs any processing after the last frame has been read.

Prototype method, no actual detection.

Returns:

List of frame pairs representing individual scenes to be added to the output scene list directly.

Parameters:

frame_num (int) –

Return type:

List[Tuple[int, int]]

process_frame(frame_num, frame_img)

Process Frame: Computes/stores metrics and detects any scene changes.

Prototype method, no actual detection.

Returns:

List of frame pairs representing individual scenes to be added to the output scene list directly.

Parameters:

• frame_num (int) –

• frame_img (ndarray) –

Return type:

List[Tuple[int, int]]