{"record":{"id":"07ba539faaba18a6","repo":"docling-project/docling","slug":"ffmpeg-is-required-for-video-processing-but-was-no","errorCode":null,"errorMessage":"FFmpeg is required for video processing but was not found on PATH. Install it with your system package manager (e.g., 'brew install ffmpeg' on macOS, 'apt-get install ffmpeg' on Linux, 'winget install ffmpeg' on Windows).","messagePattern":"FFmpeg is required for video processing but was not found on PATH\\. Install it with your system package manager \\(e\\.g\\., 'brew install ffmpeg' on macOS, 'apt-get install ffmpeg' on Linux, 'winget install ffmpeg' on Windows\\)\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/utils/video_frame_sampling.py","lineNumber":70,"sourceCode":"    scene_id: int | None = Field(\n        None, description=\"Scene index if produced by a scene sampler.\"\n    )\n\n\nclass VideoScene(BaseModel):\n    \"\"\"A contiguous time window treated as one scene.\"\"\"\n\n    model_config = ConfigDict(arbitrary_types_allowed=True)\n\n    scene_id: int\n    start_time: float = Field(..., ge=0)\n    end_time: float = Field(..., ge=0)\n    representative_frame: VideoFrame | None = None\n\n\ndef _require_ffmpeg() -> None:\n    if shutil.which(\"ffmpeg\") is None:\n        raise RuntimeError(MISSING_FFMPEG_MESSAGE)\n\n\n# Auto-prominence calibration. The frame-diff signal is mostly ambient motion\n# (near-zero for static screen shares, elevated for podcasts/vlogs where people\n# move constantly) with sparse spikes at genuine scene cuts.\n_AUTO_PROMINENCE_FLOOR: Final[float] = 0.012\n\"\"\"Minimum auto threshold. Keeps static footage sensitive to subtle cuts while\nstaying above codec noise (~0.005-0.01). Below this, tiny diffs are ignored.\"\"\"\n\n_AUTO_PROMINENCE_K: Final[float] = 5.0\n\"\"\"Robust sigmas above ambient motion a peak must clear to count as a cut.\nHigher = stricter (fewer scenes on busy video); lower = more sensitive.\"\"\"\n\n\ndef _auto_prominence(diffs: np.ndarray) -> float:\n    \"\"\"Adapt the scene-cut threshold to how busy the video is.\n\n    Uses the median frame difference as the ambient-motion floor and the","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/utils/video_frame_sampling.py#L52-L88","documentation":"RuntimeError raised by _require_ffmpeg() in docling/utils/video_frame_sampling.py when shutil.which('ffmpeg') finds no ffmpeg executable on PATH. Video frame sampling (fixed-interval sampling and scene detection) shells out to ffmpeg to decode frames, so the binary is a hard runtime dependency for any video input, unlike the pure-Python document converters.","triggerScenarios":"Instantiating FixedIntervalFrameSampler(...).sample(video_path) or the scene-detection sampler's sample() on a machine where ffmpeg is not installed or not on PATH — including minimal Docker images, slim CI runners, and Windows systems where ffmpeg was downloaded but not added to PATH.","commonSituations":"Running Docling's video pipeline inside a python:* slim Docker image (no ffmpeg preinstalled); CI environments without system packages; conda/venv setups where ffmpeg was installed into a different environment than the one running Docling; Windows installs where the zip was extracted but PATH was never updated.","solutions":["Install ffmpeg with the system package manager: 'apt-get install ffmpeg' (Debian/Ubuntu), 'brew install ffmpeg' (macOS), 'winget install ffmpeg' (Windows).","If ffmpeg is installed but not found, add its directory to PATH or invoke Python from a shell where 'ffmpeg --version' succeeds.","In Dockerfiles, add 'RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg' (or 'apt-get install -y ffmpeg' in the final stage) and rebuild.","Optionally check availability up front with shutil.which('ffmpeg') and fail fast with a clear message before submitting video jobs."],"exampleFix":"# Dockerfile (before): plain python image, ffmpeg missing\nFROM python:3.12-slim\nRUN pip install docling\n\n# after\nFROM python:3.12-slim\nRUN apt-get update && apt-get install -y --no-install-recommends ffmpeg && rm -rf /var/lib/apt/lists/*\nRUN pip install docling","handlingStrategy":"validation","validationCode":"import shutil\n\nif shutil.which(\"ffmpeg\") is None:\n    raise RuntimeError(\"ffmpeg not on PATH; install it before processing video\")\nframes = sampler.sample(video_path)","typeGuard":null,"tryCatchPattern":"try:\n    frames = sampler.sample(video_path)\nexcept RuntimeError as exc:\n    if \"ffmpeg\" in str(exc):\n        raise SystemExit(\"Install ffmpeg (apt-get install ffmpeg) and retry\") from exc\n    raise","preventionTips":["Precheck 'ffmpeg -version' (or shutil.which('ffmpeg')) when video inputs are configured, not at first sample call.","Bake ffmpeg into Docker images and CI runners used for video processing.","Document ffmpeg as a system prerequisite for any workflow that accepts video files."],"tags":["video","ffmpeg","environment","dependency"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}