docling-project/docling · error · ValueError

prominence must be >= 0

Error message

prominence must be >= 0

What it means

ValueError raised by the scene-detection sampler's __init__ in docling/utils/video_frame_sampling.py when an explicit prominence threshold is negative. prominence sets how large a frame-difference peak must be to count as a scene cut (find_peaks-style); None enables auto-calibration from the video's ambient motion, and negative thresholds are physically meaningless.

Source

Thrown at docling/utils/video_frame_sampling.py:338

    5. Selects the sharpest frame in a window around each scene midpoint
       as the representative keyframe, avoiding motion-blurred frames.
    """

    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

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Pass prominence=None to let the sampler auto-calibrate the cut threshold from the video's ambient motion — usually the best default.
2. If setting it manually, use 0.0 or a positive fraction; 0.0 is the permissive extreme (every peak counts).
3. Fix sentinel handling: map config 'unset' values (-1) to None before constructing the sampler.

Example fix

# before
prominence = cfg.prominence if cfg.prominence != -1 else None  # forgot the -1 mapping
sampler = SceneAwareSampler(prominence=cfg.prominence)

# after
prominence = cfg.prominence if (cfg.prominence is not None and cfg.prominence >= 0) else None
sampler = SceneAwareSampler(prominence=prominence)

prominence = cfg.prominence if cfg.prominence is not None and cfg.prominence >= 0 else None
sampler = SceneAwareSampler(prominence=prominence)

When it happens

Trigger: Constructing the scene detector with prominence=-0.5 or any negative float. Note the check applies only when prominence is not None; auto mode (None) always passes validation.

Common situations: Sign errors when converting 'sensitivity' knobs to prominence (e.g. prominence = auto_value - user_offset where offset exceeds the base); config schemas that default numerics to -1 as 'unset' sentinel; copying thresholds tuned for a different normalization of the diff signal (0-1 vs 0-255 scale).

Related errors

• probe_fps must be > 0
• min_scene_duration_seconds 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/1caa11759c5e453b. Report an issue: GitHub.