Skip to content

Fixed Duration Segmenter

Defines a segmenter that uses fixed segment durations.

FixedDurationSegmenter(config=None)

Bases: BaseSegmenter[FixedDurationSegmenterConfig]

Segment attachments using explicit per-segment durations.

segment returns cumulative time windows from config.segment_durations. materialize clips each window into a separate attachment using the cached VideoClipProcessor obtained from CompositeMediaMixin.

config_model() classmethod

Return this segmenter's concrete config model.

Returns:

Type Description
type[FixedDurationSegmenterConfig]

type[FixedDurationSegmenterConfig]: The model used to validate fixed-duration segmenter configuration.

materialize(attachment, segment, segment_index=0) async

Clip and return one attachment for a precomputed segment window.

This method is convenient when segment planning and clip extraction are performed in separate stages, and only selected windows should be materialized.

Parameters:

Name Type Description Default
attachment Attachment

Source media attachment to clip.

required
segment VideoSegment

Segment boundary plan to materialize.

required
segment_index int

Zero-based index used in generated output filenames. Defaults to 0.

0

Returns:

Name Type Description
Attachment Attachment

Clipped attachment with [VideoSegment][gllm_core.schema.multimodal.video_caption.VideoSegment] metadata.

Raises:

Type Description
MediaInputInvalidError

If attachment is not an Attachment, or has a malformed or empty MIME type or no media bytes.

MediaInputUnsupportedError

If the attachment is not a video.

MediaOperationConfigError

If segment is not a VideoSegment with finite times where 0 <= start_time < end_time.

MediaProfilingError

If the media format cannot be identified from the bytes.

MediaTrackMissingError

If the media has no video track.

MediaOperationTimeoutError

If clipping exceeds the clip processor's timeout.

MediaBackendUnavailableError

If the clip processor's backend is unavailable.

MediaResultOperationError

If the clip is missing or invalid.

MediaOperationFailedError

If clipping fails with an error outside the taxonomy.

process(attachment, **kwargs) async

Materialize fixed-duration clips from one media attachment.

Unlike calling segment directly, this method returns real clipped attachment outputs with [VideoSegment][gllm_core.schema.multimodal.video_caption.VideoSegment] metadata embedded on each result. It is the main runtime entrypoint when you need files/bytes for every configured duration window, not only boundary plans.

Parameters:

Name Type Description Default
attachment Attachment

Source media attachment to split.

required
**kwargs Any

Forwarded processing arguments accepted by the base media-toolkit contract.

{}
Notes
  1. Delegates shared validation and orchestration to MediaToolkit.process (inherited by BaseSegmenter).

Returns:

Type Description
list[Attachment]

list[Attachment]: One clipped attachment per configured segment window.

Raises:

Type Description
MediaOperationConfigError

If a per-call option other than process_config=None is passed.

MediaInputInvalidError

If attachment is not an Attachment, or has a malformed or empty MIME type or no media bytes.

MediaInputUnsupportedError

If the attachment is not a video.

MediaProfilingError

If the media format cannot be identified from the bytes.

MediaTrackMissingError

If the media has no video track.

MediaOperationTimeoutError

If clipping a segment exceeds the clip processor's timeout.

MediaBackendUnavailableError

If the clip processor's backend is unavailable.

MediaResultOperationError

If a clip or its segment metadata is missing or invalid.

MediaOperationFailedError

If clipping fails with an error outside the taxonomy.

segment(attachment) async

Return computed fixed windows without creating clip attachments.

This is useful for previewing time boundaries (for inspection, logging, or downstream planning) before paying the cost of media clipping.

Parameters:

Name Type Description Default
attachment Attachment

Source media attachment. The payload itself is not read by this implementation when computing boundaries.

required
Notes
  1. Delegates shared validation to BaseSegmenter.segment.

Returns:

Type Description
list[VideoSegment]

list[VideoSegment]: Fixed cumulative windows derived from

list[VideoSegment]

segment_durations and start_time.

Raises:

Type Description
MediaInputInvalidError

If attachment is not an Attachment or its MIME type is malformed.

MediaInputUnsupportedError

If the attachment is not a video.

FixedDurationSegmenterConfig(**data)

Bases: BaseSegmenterConfig

Configuration for FixedDurationSegmenter.

Requires a non-empty segment_durations list. Invalid options raise ComponentConfigError when the model is constructed.

Attributes:

Name Type Description
segment_durations list[float]

Ordered segment durations in seconds.

start_time float

Base start time for the first segment. Defaults to 0.0.

validate_segment_durations(value) classmethod

Reject non-positive or non-finite segment durations.

Parameters:

Name Type Description Default
value list[float]

Candidate segment durations.

required

Returns:

Type Description
list[float]

list[float]: The durations unchanged when valid.

Raises:

Type Description
ValueError

If any duration is non-positive, NaN, or infinite.

validate_start_time(value) classmethod

Reject a negative or non-finite start time.

Parameters:

Name Type Description Default
value float

Candidate start time in seconds.

required

Returns:

Name Type Description
float float

The start time unchanged when valid.

Raises:

Type Description
ValueError

If the start time is negative, NaN, or infinite.