Overview

Keyframe extractor toolkit for video processing.

This module provides the base class for extracting keyframes from video streams based on scene changes or fixed intervals.

Exported Classes

• BaseKeyframeExtractor -- Abstract base for keyframe extraction.

BaseKeyframeExtractor()

Bases: CompositeMediaMixin, MediaToolkit[Attachment, list[Attachment]], ABC

Abstract base class for keyframe extraction from video attachments.

Keyframe extractors identify representative frames (extract) and optionally materialize them into image attachments (materialize).

extract(attachment) async

Compute keyframe plans for one attachment without materializing frame bytes.

Guarantees mimetype validation before calling _extract.

Parameters:

Name	Type	Description	Default
attachment	Attachment	The video attachment to analyze.	required

Returns:

Type	Description
list[Keyframe]	list[Keyframe]: Keyframe plans containing at least time_offset.

materialize(attachment, keyframe, keyframe_index=0) async

Materialize one keyframe plan into an image attachment.

Guarantees mimetype validation before calling _materialize.

Parameters:

Name	Type	Description	Default
attachment	Attachment	Source video attachment.	required
keyframe	Keyframe	Keyframe plan with time_offset.	required
keyframe_index	int	Zero-based index within the keyframe plan list. Defaults to 0.	0

Returns:

Name	Type	Description
Attachment	Attachment	Materialized keyframe attachment with Keyframe metadata.

output_validator(attachment)

Validate that each output attachment has Keyframe-compatible metadata dict.

Parameters:

Name	Type	Description	Default
attachment	Attachment | list[Attachment]	The attachment(s) to validate.	required

Returns:

Type	Description
Attachment | list[Attachment]	Attachment | list[Attachment]: The validated attachment(s).

Raises:

Type	Description
TypeError	If any attachment metadata is not a dictionary.
ValueError	If any metadata dictionary cannot be parsed as Keyframe.