Skip to content

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("FrameExtractionProcessor") during materialization
├── UniformKeyframeExtractor (concrete implementation)
└── LDDRKeyframeExtractor (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.

Raises:

Type Description
MediaInputUnsupportedError

If the attachment is not a supported video.

MediaOperationFailedError

If the subclass fails with an error outside the taxonomy.

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.

Raises:

Type Description
MediaInputUnsupportedError

If the attachment is not a supported video.

MediaOperationFailedError

If the subclass fails with an error outside the taxonomy.

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
MediaResultOperationError

If any result is not an Attachment, or its metadata is not a dictionary or cannot be parsed as Keyframe.

process(attachment, **kwargs) async

Plan keyframes and materialize each one, converting failures outside the taxonomy.

Parameters:

Name Type Description Default
attachment Attachment

The video attachment to process.

required
**kwargs Any

Forwarded to _process.

{}

Returns:

Type Description
list[Attachment]

list[Attachment]: Materialized keyframe attachments.

Raises:

Type Description
MediaInputUnsupportedError

If the attachment is not a supported video.

MediaResultOperationError

If a keyframe's metadata is missing or invalid.

MediaOperationFailedError

If a subclass fails with an error outside the taxonomy.