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
await extractor.extract(attachment)— computes keyframe plans (time offsets) without materializing frame bytes.await extractor.process(attachment)— computes plans AND materializes each keyframe into anAttachmentcontaining 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 |
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 |
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 |
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 |
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 |
{}
|
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. |