Overview
Segmenter components for temporal media splitting.
This module provides segmenters that split media files (audio, video) into fixed-duration segments for parallel processing.
Exported Classes
BaseSegmenter-- Abstract base for media segmentation.FixedDurationSegmenter-- Fixed-duration segment splitting.
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 |
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(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 |
FixedDurationSegmenter(segment_durations, start_time=0.0)
Bases: BaseSegmenter
Segment attachments using explicit per-segment durations.
segment returns cumulative time windows from segment_durations.
materialize clips each window into a separate attachment using a
shared GstVideoClipProcessor instance that is created on first use
and reused across all subsequent segments and videos.
Initialize the segmenter with manually provided segment durations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
segment_durations
|
list[float]
|
Ordered segment durations in seconds. |
required |
start_time
|
float
|
Base start time for the first segment. Defaults to 0.0. |
0.0
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If no segment duration is provided, or any duration is non-positive. |