{"record":{"id":"dcd13cd1a30790ff","repo":"docling-project/docling","slug":"probe-fps-must-be-0","errorCode":null,"errorMessage":"probe_fps must be > 0","messagePattern":"probe_fps must be > 0","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/utils/video_frame_sampling.py","lineNumber":336,"sourceCode":"       with a prominence criterion — self-calibrating per video, no manual\n       threshold needed.\n    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)","sourceCodeStart":318,"sourceCodeEnd":354,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/utils/video_frame_sampling.py#L318-L354","documentation":"ValueError raised by the scene-detection sampler's __init__ in docling/utils/video_frame_sampling.py when probe_fps is zero or negative. The detector first decodes the video into a downscaled probe stream at probe_fps frames per second to measure frame-difference signals, so a non-positive probe rate is meaningless and would break frame extraction.","triggerScenarios":"Constructing the scene-detection sampler with probe_fps=0 or a negative value, or with a computed rate such as probe_fps = n / duration where n is 0 or duration is huge relative to n (underflow to 0).","commonSituations":"Auto-tuning probe rate from video metadata (duration probes returning 0.0 for broken/corrupt files make the division 0); config files where the key was left at 0; passing fps values from a probe tool that reports 0 for variable-frame-rate streams.","solutions":["Pass a positive probe rate; the default probe_fps=1.0 (one probe frame per second) is a sensible baseline.","If computing probe_fps from metadata, guard the division: probe_fps = n / duration if duration > 0 else 1.0.","Validate the video with ffprobe first when metadata-driven rates come out as 0 (the file may be corrupt or unreadable)."],"exampleFix":"# before\nprobe_fps = num_probes / duration  # duration=0.0 -> ZeroDivisionError / 0\nsampler = SceneAwareSampler(probe_fps=probe_fps)\n\n# after\nprobe_fps = num_probes / duration if duration > 0 else 1.0\nsampler = SceneAwareSampler(probe_fps=max(probe_fps, 0.1))","handlingStrategy":"validation","validationCode":"probe_fps = num_probes / duration if duration and duration > 0 else 1.0\nif probe_fps <= 0:\n    probe_fps = 1.0\nsampler = SceneAwareSampler(probe_fps=probe_fps)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Guard probe-rate arithmetic against zero durations from ffprobe (possible for corrupt files).","Treat probe_fps=0 from any source as 'unknown' and substitute the 1.0 default.","Validate ffprobe metadata before configuring the sampler."],"tags":["video","validation","constructor","scene-detection"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}