Video Utils
Video utilities for duration probing.
This module provides utility functions for working with video files, including
whole-video duration resolution used by keyframe extraction. Per-timestamp
frame decoding lives in
FrameExtractionProcessor.
get_video_duration_seconds(video_attachment)
Probe video duration in seconds from attachment bytes or a local file URL.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
video_attachment
|
Attachment
|
Source video attachment. |
required |
Returns:
| Type | Description |
|---|---|
float | None
|
float | None: Duration in seconds, or None when probing fails. |
resolve_video_duration(video_attachment, explicit_duration=None)
Resolve whole-video duration from explicit input, metadata, or probing.
Resolution order:
1. explicit_duration when provided and positive.
2. video_duration / duration keys on attachment.metadata.
3. Container metadata probed from attachment bytes (hachoir, then OpenCV fallback).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
video_attachment
|
Attachment
|
Source video attachment. |
required |
explicit_duration
|
float | None
|
Caller-provided duration in seconds. |
None
|
Returns:
| Type | Description |
|---|---|
float | None
|
float | None: Resolved duration in seconds, or None when unavailable. |
valid_frame_rate(frame_rate)
Return a decoder-reported frame rate when it is a finite positive number.
Missing, zero, negative, NaN and infinite values return None, so the caller falls back to FALLBACK_FPS
instead of failing on a frame rate it cannot use.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
frame_rate
|
Any
|
The |
required |
Returns:
| Type | Description |
|---|---|
float | None
|
float | None: The frame rate as a float, or None when it cannot be used. |