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
[ |
Raises:
| Type | Description |
|---|---|
MediaInputInvalidError
|
If |
MediaInputUnsupportedError
|
If the attachment is not a video. |
MediaOperationConfigError
|
If |
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
- Delegates shared validation and orchestration to
MediaToolkit.process(inherited byBaseSegmenter).
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 |
MediaInputInvalidError
|
If |
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
- Delegates shared validation to
BaseSegmenter.segment.
Returns:
| Type | Description |
|---|---|
list[VideoSegment]
|
list[VideoSegment]: Fixed cumulative windows derived from |
list[VideoSegment]
|
|
Raises:
| Type | Description |
|---|---|
MediaInputInvalidError
|
If |
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. |