{"record":{"id":"7ba25c33ad0ebd42","repo":"ATH-MaaS/Pixelle-Video","slug":"ffmpeg-not-found-please-install-it-macos-brew","errorCode":null,"errorMessage":"FFmpeg not found. Please install it:\n  macOS: brew install ffmpeg\n  Ubuntu/Debian: apt-get install ffmpeg\n  Windows: https://ffmpeg.org/download.html","messagePattern":"FFmpeg not found\\. Please install it:\n  macOS: brew install ffmpeg\n  Ubuntu/Debian: apt-get install ffmpeg\n  Windows: https://ffmpeg\\.org/download\\.html","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"pixelle_video/services/video.py","lineNumber":52,"sourceCode":"import ffmpeg\nfrom loguru import logger\n\nfrom pixelle_video.utils.os_util import (\n    get_resource_path,\n    list_resource_files,\n    resource_exists\n)\n\n\ndef check_ffmpeg() -> None:\n    \"\"\"\n    Check if FFmpeg is installed on the system\n    \n    Raises:\n        RuntimeError: If FFmpeg is not found\n    \"\"\"\n    if not shutil.which(\"ffmpeg\"):\n        raise RuntimeError(\n            \"FFmpeg not found. Please install it:\\n\"\n            \"  macOS: brew install ffmpeg\\n\"\n            \"  Ubuntu/Debian: apt-get install ffmpeg\\n\"\n            \"  Windows: https://ffmpeg.org/download.html\"\n        )\n\n\nclass VideoService:\n    \"\"\"\n    Video compositor for common video processing tasks\n\n    Uses ffmpeg-python for high-performance video processing.\n    All operations preserve video quality when possible (stream copy).\n\n    Examples:\n        >>> compositor = VideoCompositor()\n        >>>\n        >>> # Concatenate videos","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/ATH-MaaS/Pixelle-Video/blob/848b054e4fae40dabc62ec58e960b573e83793ac/pixelle_video/services/video.py#L34-L70","documentation":"check_ffmpeg verifies that the ffmpeg binary is available on PATH using shutil.which. If it cannot be found, it raises this RuntimeError with platform-specific install instructions. Every VideoService operation that shells out to FFmpeg calls this check first via _ensure_ffmpeg, so this error blocks all video processing when FFmpeg is missing.","triggerScenarios":"Calling any VideoService method (concat_videos, merge_audio_video, add_bgm, etc.) on a machine where `shutil.which('ffmpeg')` returns None — ffmpeg not installed, installed but not on PATH, or running inside a slim Docker image without ffmpeg.","commonSituations":"Fresh CI runners or containers (e.g. python:slim) without ffmpeg; macOS dev machines after a Homebrew migration; virtualenv/container environments that do not inherit the host PATH; deployment targets that differ from the dev machine where ffmpeg was installed manually.","solutions":["Install FFmpeg: macOS `brew install ffmpeg`, Ubuntu/Debian `apt-get install ffmpeg`, Windows download from ffmpeg.org and add to PATH.","If already installed, ensure the ffmpeg executable directory is on the PATH of the process running this code (check `which ffmpeg` in the same shell/container).","For Docker, use a base image with ffmpeg or add `RUN apt-get update && apt-get install -y ffmpeg` to the Dockerfile.","Bake a startup check into the application that calls shutil.which('ffmpeg') and fails fast with a clear message."],"exampleFix":"// before\nservice = VideoService()\nservice.concat_videos(['a.mp4','b.mp4'], 'out.mp4')  # RuntimeError if ffmpeg missing\n// after\nimport shutil\nif not shutil.which('ffmpeg'):\n    raise SystemExit('Install ffmpeg first: brew install ffmpeg / apt-get install ffmpeg')\nservice = VideoService()\nservice.concat_videos(['a.mp4','b.mp4'], 'out.mp4')","handlingStrategy":"validation","validationCode":"import shutil\nif not shutil.which('ffmpeg'):\n    raise SystemExit('ffmpeg not found on PATH; install it before using pixelle_video')","typeGuard":"def has_ffmpeg() -> bool:\n    return shutil.which('ffmpeg') is not None","tryCatchPattern":"try:\n    service.concat_videos(videos, out)\nexcept RuntimeError as e:\n    if 'FFmpeg not found' in str(e):\n        print('Install ffmpeg: brew install ffmpeg / apt-get install ffmpeg')\n    else:\n        raise","preventionTips":["Install ffmpeg in every environment (dev, CI, production Docker image) where the library runs.","Add `RUN apt-get install -y ffmpeg` or a full base image to Dockerfiles.","Fail fast at app startup with a shutil.which('ffmpeg') probe.","Verify `which ffmpeg` inside the exact shell/container/user that runs the pipeline, since PATH differs per environment."],"tags":["ffmpeg","environment","dependency-missing"],"backgroundTag":"ffmpeg-binary-not-found","analyzedSha":"848b054e4fae40dabc62ec58e960b573e83793ac","analyzedAt":"2026-08-30T03:24:41.468Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}