StatsManager

scenedetect.stats_manager Module

This module contains the StatsManager class, which provides a key-value store for each SceneDetector to write the metrics calculated for each frame. The StatsManager must be registered to a SceneManager upon construction.

The entire StatsManager can be saved to a human-readable CSV file, allowing for precise determination of the ideal threshold (or other detection parameters) for the given input.

StatsManager Class

class scenedetect.stats_manager.StatsManager(base_timecode=None)

Provides a key-value store for frame metrics/calculations which can be used for two-pass detection algorithms, as well as saving stats to a CSV file.

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.

Only metrics consisting of float or int should be used currently. All metrics loaded from disk are treated as float.

Initialize a new StatsManager.

Parameters:

base_timecode (FrameTimecode) – Timecode associated with this object. Must not be None (default value will be removed in a future release).

get_metrics(frame_number, metric_keys)

Return 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.

Return type:

List[Any]

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)

[DEPRECATED] DO NOT USE

Load all metrics stored in a CSV file into the StatsManager instance. Will be removed in a future release after becoming a no-op.

Parameters:

csv_file (str | bytes | TextIO) – A file handle opened in read mode (e.g. open(’…’, ‘r’)) or a path as str.

Returns:

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

Return type:

int or None

Raises:

StatsFileCorrupt – Stats file is corrupt and can’t be loaded, or wrong 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

Parameters:

  • frame_number (int) –

  • metric_keys (Iterable[str]) –

register_metrics(metric_keys)

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.

Parameters:

metric_keys (Iterable[str]) –

Return type:

None

save_to_csv(csv_file, base_timecode=None, force_save=True)

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

Parameters:

  • csv_file (str | bytes | TextIO) – A file handle opened in write mode (e.g. open(’…’, ‘w’)) or a path as str.

  • base_timecode (FrameTimecode | None) – [DEPRECATED] DO NOT USE. For backwards compatibility.

  • force_save – If True, writes metrics out even if an update is not required.

Raises:

OSError – If path cannot be opened or a write failure occurs.

Return type:

None

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, Any]) – A dict mapping metric keys to the respective integer/floating-point metric values to set.

Return type:

None

static valid_header(row)

Check that the given CSV row is a valid header for a statsfile.

Parameters:

row (List[str]) – A row decoded from the CSV reader.

Returns:

True if row is a valid statsfile header, False otherwise.

Return type:

bool

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.

Parameters:

  • metric_key (str) –

  • message (str) –

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.

Parameters:

  • metric_key (str) –

  • message (str) –

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.

Parameters:

message (str) –