StatsManager

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 a human-readable CSV file, also allowing both precise determination of the threshold or other optimal values for video files.

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 (Union[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 (Union[str, bytes, TextIO]) – A file handle opened in write mode (e.g. open(’…’, ‘w’)) or a path as str.

  • base_timecode (Optional[FrameTimecode]) – [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) –