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.

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.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.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) –

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.

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

scenedetect.stats_manager.COLUMN_NAME_FRAME_NUMBER = 'Frame Number'

Name of column containing frame numbers in the statsfile CSV.

scenedetect.stats_manager.COLUMN_NAME_TIMECODE = 'Timecode'

Name of column containing timecodes in the statsfile CSV.