docling-project/docling · error · ValueError

min_scene_duration_seconds must be >= 0

Error message

min_scene_duration_seconds must be >= 0

What it means

ValueError raised by the scene-detection sampler's __init__ in docling/utils/video_frame_sampling.py when min_scene_duration_seconds is negative. This parameter enforces a minimum scene length by suppressing cuts closer than the given duration to the previous one; negative durations have no geometric meaning for ordering cuts on a timeline, so they are rejected at construction time.

Source

Thrown at docling/utils/video_frame_sampling.py:340

    """

    def __init__(
        self,
        probe_fps: float = 1.0,
        prominence: float | None = None,
        cuts_per_minute: float | None = None,
        min_scene_duration_seconds: float = 2.0,
        max_frames: int | None = None,
        probe_size: int = 64,
        smooth_window: int = 1,
        sharpness_candidates: int = 5,
    ):
        if probe_fps <= 0:
            raise ValueError("probe_fps must be > 0")
        if prominence is not None and prominence < 0:
            raise ValueError("prominence must be >= 0")
        if min_scene_duration_seconds < 0:
            raise ValueError("min_scene_duration_seconds must be >= 0")
        if max_frames is not None and max_frames <= 0:
            raise ValueError("max_frames must be > 0 when set")
        self.probe_fps = probe_fps
        self.prominence = prominence
        self.cuts_per_minute = cuts_per_minute
        self.min_scene_duration_seconds = min_scene_duration_seconds
        self.max_frames = max_frames
        self.probe_size = probe_size
        self.smooth_window = smooth_window
        self.sharpness_candidates = sharpness_candidates

    def _probe_frames(self, video_path: Path) -> list[tuple[float, Image.Image]]:
        """Extract downscaled RGB probe frames at probe_fps in a single decode pass."""
        return _extract_frames_grid(video_path, self.probe_fps, self.probe_size)

    @staticmethod
    def _mean_abs_diff(a: Image.Image, b: Image.Image) -> float:
        """Normalized mean absolute difference of two images in [0, 1]."""

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Use 0.0 to disable the minimum-scene-duration constraint; keep the value positive otherwise (default 2.0).
2. Translate sentinel config values before construction: min_dur = 0.0 if cfg.min_scene_duration in (-1, None) else cfg.min_scene_duration.
3. Double-check formulas that derive the duration from cuts-per-minute budgets for sign/order-of-operations errors.

Example fix

# before
sampler = SceneAwareSampler(min_scene_duration_seconds=cfg.min_scene)  # cfg uses -1 = off

# after
min_scene = 0.0 if cfg.min_scene in (-1, None) else cfg.min_scene
sampler = SceneAwareSampler(min_scene_duration_seconds=min_scene)

min_dur = 0.0 if cfg.min_scene_duration in (-1, None) else cfg.min_scene_duration
if min_dur < 0:
    raise ValueError("min_scene_duration_seconds cannot be negative")
sampler = SceneAwareSampler(min_scene_duration_seconds=min_dur)

When it happens

Trigger: Constructing the scene detector with min_scene_duration_seconds=-1 or any negative value, e.g. when a caller tries to express 'no minimum' as -1 instead of 0.0.

Common situations: Config conventions where -1 means 'disabled' colliding with an API that uses 0.0 for 'no minimum'; arithmetic slips when computing the minimum from cuts_per_minute targets (e.g. 60 / rate with rate as a negative or inverted value).

Related errors

• probe_fps must be > 0
• prominence must be >= 0
• interval_seconds must be > 0
• max_frames must be > 0 when set
• Cannot convert Box Note with hash {self.document_hash}: no '

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/48133ca6e0e78a49. Report an issue: GitHub.