{"record":{"id":"1caa11759c5e453b","repo":"docling-project/docling","slug":"prominence-must-be-0","errorCode":null,"errorMessage":"prominence must be >= 0","messagePattern":"prominence must be >= 0","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/utils/video_frame_sampling.py","lineNumber":338,"sourceCode":"    5. Selects the sharpest frame in a window around each scene midpoint\n       as the representative keyframe, avoiding motion-blurred frames.\n    \"\"\"\n\n    def __init__(\n        self,\n        probe_fps: float = 1.0,\n        prominence: float | None = None,\n        cuts_per_minute: float | None = None,\n        min_scene_duration_seconds: float = 2.0,\n        max_frames: int | None = None,\n        probe_size: int = 64,\n        smooth_window: int = 1,\n        sharpness_candidates: int = 5,\n    ):\n        if probe_fps <= 0:\n            raise ValueError(\"probe_fps must be > 0\")\n        if prominence is not None and prominence < 0:\n            raise ValueError(\"prominence must be >= 0\")\n        if min_scene_duration_seconds < 0:\n            raise ValueError(\"min_scene_duration_seconds must be >= 0\")\n        if max_frames is not None and max_frames <= 0:\n            raise ValueError(\"max_frames must be > 0 when set\")\n        self.probe_fps = probe_fps\n        self.prominence = prominence\n        self.cuts_per_minute = cuts_per_minute\n        self.min_scene_duration_seconds = min_scene_duration_seconds\n        self.max_frames = max_frames\n        self.probe_size = probe_size\n        self.smooth_window = smooth_window\n        self.sharpness_candidates = sharpness_candidates\n\n    def _probe_frames(self, video_path: Path) -> list[tuple[float, Image.Image]]:\n        \"\"\"Extract downscaled RGB probe frames at probe_fps in a single decode pass.\"\"\"\n        return _extract_frames_grid(video_path, self.probe_fps, self.probe_size)\n\n    @staticmethod","sourceCodeStart":320,"sourceCodeEnd":356,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/utils/video_frame_sampling.py#L320-L356","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Pass prominence=None to let the sampler auto-calibrate the cut threshold from the video's ambient motion — usually the best default.","If setting it manually, use 0.0 or a positive fraction; 0.0 is the permissive extreme (every peak counts).","Fix sentinel handling: map config 'unset' values (-1) to None before constructing the sampler."],"exampleFix":"# before\nprominence = cfg.prominence if cfg.prominence != -1 else None  # forgot the -1 mapping\nsampler = SceneAwareSampler(prominence=cfg.prominence)\n\n# after\nprominence = cfg.prominence if (cfg.prominence is not None and cfg.prominence >= 0) else None\nsampler = SceneAwareSampler(prominence=prominence)","handlingStrategy":"validation","validationCode":"prominence = cfg.prominence if cfg.prominence is not None and cfg.prominence >= 0 else None\nsampler = SceneAwareSampler(prominence=prominence)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer prominence=None (auto-calibration) unless you have tuned a positive threshold for your footage.","Never use -1 as an 'unset' sentinel for prominence; use None.","Keep thresholds in the 0..1 scale of the frame-diff signal."],"tags":["video","validation","scene-detection","constructor"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}