Base Keyframe Extractor

Defines the base keyframe extractor schema.

Keyframe extractors identify representative frames from video attachments and optionally materialize them into image attachments. This module provides BaseKeyframeExtractor, the abstract base class for keyframe extraction.

Lifecycle

1. await extractor.extract(attachment) — computes keyframe plans (time offsets) without materializing frame bytes.
2. await extractor.process(attachment) — computes plans AND materializes each keyframe into an Attachment containing the frame image data.

Architecture

BaseKeyframeExtractor (abstract)
├── uses CompositeMediaMixin for nested processor resolution
├── calls get_processor("FrameSamplingProcessor") during materialization
└── UniformKeyframeExtractor (concrete implementation)

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.