StatsManager

PySceneDetect scenedetect.stats_manager Module

This module contains the StatsManager class, which provides a key-value store for each SceneDetector to read/write the metrics calculated for each frame. The StatsManager must be registered to a SceneManager by passing it to the SceneManager constructor as the stats_manager argument.

The entire StatsManager can be saved to and loaded from a human-readable CSV file, also allowing both precise determination of the threshold or other optimal values for video files. See the save_to_csv() and load_from_csv() methods for more information.

The StatsManager can also be used to cache the calculation results of the scene detectors being used, speeding up subsequent scene detection runs using the same pair of SceneManager/StatsManager objects.

StatsManager Class

class scenedetect.stats_manager.StatsManager

Provides a key-value store for frame metrics/calculations which can be used as a cache to speed up subsequent calls to a SceneManager’s detect_scenes(…) method. The statistics can be saved to a CSV file, and loaded from disk.

Analyzing a statistics CSV file is also very useful for finding the optimal algorithm parameters for certain detection methods. Additionally, the data may be plotted by a graphing module (e.g. matplotlib) by obtaining the metric of interest for a series of frames by iteratively calling get_metrics(), after having called the detect_scenes(…) method on the SceneManager object which owns the given StatsManager instance.

get_metrics(frame_number, metric_keys)

Get Metrics: Returns the requested statistics/metrics for a given frame.

Parameters:
  • frame_number (int) – Frame number to retrieve metrics for.
  • metric_keys (List[str]) – A list of metric keys to look up.
Returns:

A list containing the requested frame metrics for the given frame number in the same order as the input list of metric keys. If a metric could not be found, None is returned for that particular metric.

is_save_required()

Is Save Required: Checks if the stats have been updated since loading.

Returns:True if there are frame metrics/statistics not yet written to disk, False otherwise.
Return type:bool
load_from_csv(csv_file, base_timecode=None, reset_save_required=True)

Load From CSV: Loads all metrics stored in a CSV file into the StatsManager instance.

Parameters:
  • csv_file – A file handle opened in read mode (e.g. open(‘…’, ‘r’)).
  • base_timecode – The base_timecode obtained from the frame source VideoManager. If using an OpenCV VideoCapture, create one using the video framerate by setting base_timecode=FrameTimecode(0, fps=video_framerate). If base_timecode is not set (i.e. is None), the framerate is not validated.
  • reset_save_required – If True, clears the flag indicating that a save is required.
Returns:

Number of frames/rows read from the CSV file, or None if the input file was blank.

Return type:

int or None

Raises:
  • StatsFileCorrupt – Stats file is corrupt and can’t be loaded, or wrong file was specified.
  • StatsFileFramerateMismatch – Framerate does not match the loaded stats file, indicating either the wrong video or wrong stats file was specified.
metrics_exist(frame_number, metric_keys)

Metrics Exist: Checks if the given metrics/stats exist for the given frame.

Returns:True if the given metric keys exist for the frame, False otherwise.
Return type:bool
register_metrics(metric_keys)

Register Metrics

Register a list of metric keys that will be used by the detector. Used to ensure that multiple detector keys don’t overlap.

Raises:FrameMetricRegistered – A particular metric_key has already been registered/added to the StatsManager. Only if the StatsManager is being used for read-only access (i.e. all frames in the video have already been processed for the given metric_key in the exception) is this behavior desirable.
save_to_csv(csv_file, base_timecode, force_save=True)

Save To CSV: Saves all frame metrics stored in the StatsManager to a CSV file.

Parameters:
  • csv_file – A file handle opened in write mode (e.g. open(‘…’, ‘w’)).
  • base_timecode – The base_timecode obtained from the frame source VideoManager. If using an OpenCV VideoCapture, create one using the video framerate by setting base_timecode=FrameTimecode(0, fps=video_framerate).
  • force_save – If True, forcably writes metrics out even if there are no registered metrics or frame statistics. If False, a NoMetricsRegistered will be thrown if there are no registered metrics, and a NoMetricsSet exception will be thrown if is_save_required() returns False.
Raises:
  • NoMetricsRegistered – No frame metrics have been registered to save, nor is there any frame data to save.
  • NoMetricsSet – No frame metrics have been entered/updated, thus there is no frame data to save.
set_metrics(frame_number, metric_kv_dict)

Set Metrics: Sets the provided statistics/metrics for a given frame.

Parameters:
  • frame_number (int) – Frame number to retrieve metrics for.
  • metric_kv_dict (Dict[str, metric]) – A dict mapping metric keys to the respective integer/floating-point metric values to set.

Exceptions

exception scenedetect.stats_manager.FrameMetricRegistered(metric_key, message='Attempted to re-register frame metric key.')

Raised when attempting to register a frame metric key which has already been registered.

exception scenedetect.stats_manager.FrameMetricNotRegistered(metric_key, message='Attempted to get/set frame metrics for unregistered metric key.')

Raised when attempting to call get_metrics(…)/set_metrics(…) with a frame metric that does not exist, or has not been registered.

exception scenedetect.stats_manager.StatsFileCorrupt(message='Could not load frame metric data data from passed CSV file.')

Raised when frame metrics/stats could not be loaded from a provided CSV file.

exception scenedetect.stats_manager.StatsFileFramerateMismatch(base_timecode_fps, stats_file_fps, message='Framerate differs between stats file and base timecode.')

Raised when attempting to load a CSV file with a framerate that differs from the current base timecode / VideoManager.

exception scenedetect.stats_manager.NoMetricsRegistered

Raised when attempting to save a CSV file via save_to_csv(…) without any frame metrics having been registered (i.e. no SceneDetector objects were added to the owning SceneManager object, if any).

exception scenedetect.stats_manager.NoMetricsSet

Raised if no frame metrics have been set via set_metrics(…) when attempting to save the stats to a CSV file via save_to_csv(…). This may also indicate that detect_scenes(…) was not called on the owning SceneManager object, if any.