Detection Algorithms

PySceneDetect scenedetect.detectors Module

This module contains implementations of scene detection algorithms by inhereting from the base SceneDetector class (in scenedetect.scene_detector) and implementing the required methods. This allows implementation of other generic algorithms as well as custom scenario-specific algorithms.

Individual detectors are imported in this file for easy access from other modules (i.e. from scenedetect.detectors import ContentDetector).

ContentDetector

PySceneDetect scenedetect.detectors.content_detector Module

This module implements the ContentDetector, which compares the difference in content between adjacent frames against a set threshold/score, which if exceeded, triggers a scene cut.

class scenedetect.detectors.content_detector.ContentDetector(threshold=30.0, min_scene_len=15)

Detects fast cuts using changes in colour and intensity between frames.

Since the difference between frames is used, unlike the ThresholdDetector, only fast cuts are detected with this method. To detect slow fades between content scenes still using HSV information, use the DissolveDetector.

process_frame(frame_num, frame_img)

Similar to ThresholdDetector, but using the HSV colour space DIFFERENCE instead of single-frame RGB/grayscale intensity (thus cannot detect slow fades with this method).

Parameters:
  • frame_num (int) – Frame number of frame that is being passed.
  • frame_img (Optional[int]) – Decoded frame image (numpy.ndarray) to perform scene detection on. Can be None only if the self.is_processing_required() method (inhereted from the base SceneDetector class) returns True.
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]

ThresholdDetector

PySceneDetect scenedetect.detectors.threshold_detector Module

This module implements the ThresholdDetector, which uses a set intensity level to detect scene cuts when the average frame intensity passes the set threshold.

class scenedetect.detectors.threshold_detector.ThresholdDetector(threshold=12, min_percent=0.95, min_scene_len=15, fade_bias=0.0, add_final_scene=False, block_size=8)

Detects fast cuts/slow fades in from and out to a given threshold level.

Detects both fast cuts and slow fades so long as an appropriate threshold is chosen (especially taking into account the minimum grey/black level).

threshold

8-bit intensity value that each pixel value (R, G, and B) must be <= to in order to trigger a fade in/out.

min_percent

Float between 0.0 and 1.0 which represents the minimum percent of pixels in a frame that must meet the threshold value in order to trigger a fade in/out.

min_scene_len

Unsigned integer greater than 0 representing the minimum length, in frames, of a scene (or subsequent scene cut).

fade_bias

Float between -1.0 and +1.0 representing the percentage of timecode skew for the start of a scene (-1.0 causing a cut at the fade-to-black, 0.0 in the middle, and +1.0 causing the cut to be right at the position where the threshold is passed).

add_final_scene

Boolean indicating if the video ends on a fade-out to generate an additional scene at this timecode.

block_size

Number of rows in the image to sum per iteration (can be tuned to increase performance in some cases; should be computed programmatically in the future).

frame_under_threshold(frame)

Check if the frame is below (true) or above (false) the threshold.

Instead of using the average, we check all pixel values (R, G, and B) meet the given threshold (within the minimum percent). This ensures that the threshold is not exceeded while maintaining some tolerance for compression and noise.

This is the algorithm used for absolute mode of the threshold detector.

Returns:Boolean, True if the number of pixels whose R, G, and B values are all <= the threshold is within min_percent pixels, or False if not.
post_process(frame_num)

Writes a final scene cut if the last detected fade was a fade-out.

Only writes the scene cut if add_final_scene is true, and the last fade that was detected was a fade-out. There is no bias applied to this cut (since there is no corresponding fade-in) so it will be located at the exact frame where the fade-out crossed the detection threshold.

process_frame(frame_num, frame_img)
Parameters:
  • frame_num (int) – Frame number of frame that is being passed.
  • frame_img (numpy.ndarray or None) – Decoded frame image (numpy.ndarray) to perform scene detection with. Can be None only if the self.is_processing_required() method (inhereted from the base SceneDetector class) returns True.
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]

scenedetect.detectors.threshold_detector.compute_frame_average(frame)

Computes the average pixel value/intensity for all pixels in a frame.

The value is computed by adding up the 8-bit R, G, and B values for each pixel, and dividing by the number of pixels multiplied by 3.

Returns:Floating point value representing average pixel intensity.