ATH-MaaS/Pixelle-Video · error · RuntimeError

FFmpeg not found. Please install it: macOS: brew install f

Error message

FFmpeg not found. Please install it:
  macOS: brew install ffmpeg
  Ubuntu/Debian: apt-get install ffmpeg
  Windows: https://ffmpeg.org/download.html

What it means

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.

Source

Thrown at pixelle_video/services/video.py:52

import ffmpeg
from loguru import logger

from pixelle_video.utils.os_util import (
    get_resource_path,
    list_resource_files,
    resource_exists
)


def check_ffmpeg() -> None:
    """
    Check if FFmpeg is installed on the system
    
    Raises:
        RuntimeError: If FFmpeg is not found
    """
    if not shutil.which("ffmpeg"):
        raise RuntimeError(
            "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"
        )


class VideoService:
    """
    Video compositor for common video processing tasks

    Uses ffmpeg-python for high-performance video processing.
    All operations preserve video quality when possible (stream copy).

    Examples:
        >>> compositor = VideoCompositor()
        >>>
        >>> # Concatenate videos

View on GitHub (pinned to 848b054e4f)

Solutions

1. Install FFmpeg: macOS `brew install ffmpeg`, Ubuntu/Debian `apt-get install ffmpeg`, Windows download from ffmpeg.org and add to PATH.
2. 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).
3. For Docker, use a base image with ffmpeg or add `RUN apt-get update && apt-get install -y ffmpeg` to the Dockerfile.
4. Bake a startup check into the application that calls shutil.which('ffmpeg') and fails fast with a clear message.

Example fix

// before
service = VideoService()
service.concat_videos(['a.mp4','b.mp4'], 'out.mp4')  # RuntimeError if ffmpeg missing
// after
import shutil
if not shutil.which('ffmpeg'):
    raise SystemExit('Install ffmpeg first: brew install ffmpeg / apt-get install ffmpeg')
service = VideoService()
service.concat_videos(['a.mp4','b.mp4'], 'out.mp4')

import shutil
if not shutil.which('ffmpeg'):
    raise SystemExit('ffmpeg not found on PATH; install it before using pixelle_video')

def has_ffmpeg() -> bool:
    return shutil.which('ffmpeg') is not None

try:
    service.concat_videos(videos, out)
except RuntimeError as e:
    if 'FFmpeg not found' in str(e):
        print('Install ffmpeg: brew install ffmpeg / apt-get install ffmpeg')
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• ARK_API_KEY not set.
• DashScope VLM API key is not configured.
• Failed to concatenate videos: {error_msg}
• Failed to concatenate videos: {e}
• Failed to add audio to video: {error_msg}

AI-assisted analysis of ATH-MaaS/Pixelle-Video@848b054e4f (2026-08-30). Data as JSON: /api/errors/7ba25c33ad0ebd42. Report an issue: GitHub.