Base Segmenter

Defines the base segmenter schema.

Segmenters divide media attachments (video or audio) into semantically or temporally distinct segments. This module provides BaseSegmenter, the abstract base class that defines the segment-and-materialize lifecycle.

Lifecycle

1. await segmenter.segment(attachment) — computes segment boundaries only.
2. await segmenter.process(attachment) — computes boundaries AND materializes media segments into separate Attachment objects.

Architecture

BaseSegmenter (abstract)
├── uses CompositeMediaMixin for nested processor resolution
├── calls get_processor("VideoClipProcessor") during materialization
└── FixedDurationSegmenter (concrete implementation)

BaseSegmenter()

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

Abstract base class for segmenting media attachments.

Segmenters are responsible for dividing a media attachment (usually video or audio) into semantically or temporally distinct segments. The resulting attachments should contain Segment metadata.

Attributes:

Name	Type	Description
backend	MediaBackend | str | None	Preferred backend for nested processor lookup. Set when built via the registry with an explicit or resolved backend.

Processing contract

• await segment(attachment) computes boundaries only.
• await process(attachment) computes + materializes media segments.
• Materialization can call nested processors via get_processor(...) and uses this segmenter's backend preference.

Example

segmenter = build_media_toolkit( "FixedDurationSegmenter", backend=MediaBackend.GSTREAMER, ... ) then await segmenter.process(video_attachment) uses the GStreamer video clip processor during materialization.

Initialize the segmenter.

materialize(attachment, segment, segment_index=0) async

Materialize one segment plan into a media attachment.

Guarantees mimetype validation before calling _materialize.

Parameters:

Name	Type	Description	Default
attachment	Attachment	Source attachment to clip or reference.	required
segment	Segment	Segment plan with boundary metadata.	required
segment_index	int	Zero-based index within the segment plan list. Defaults to 0.	0

Returns:

Name	Type	Description
Attachment	Attachment	Materialized segment attachment with Segment metadata.

output_validator(attachment)

Validate that each output attachment has Segment-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 Segment.

segment(attachment) async

Compute segment boundaries for one attachment without materializing media.

Guarantees mimetype validation before calling _segment.

Parameters:

Name	Type	Description	Default
attachment	Attachment	The attachment to segment.	required

Returns:

Type	Description
list[Segment]	list[Segment]: Segment plans containing at least start_time and end_time.