How the Setup Preflight in claude-video Detects Missing ffmpeg or yt-dlp Binaries

The setup preflight in claude-video uses shutil.which() via the _which() helper in skills/watch/scripts/setup.py to scan for ffmpeg, ffprobe, and yt-dlp, returning platform-specific installation hints or auto-installing via Homebrew on macOS when binaries are missing.

The claude-video repository provides a preflight validation system that ensures required multimedia binaries are present before processing video content. This setup preflight detects missing ffmpeg or yt-dlp binaries across macOS, Linux, and Windows by executing platform-aware detection logic that returns distinct exit codes and remediation guidance.

Core Binary Detection Logic

The detection mechanism centers on skills/watch/scripts/setup.py, where the _check_binaries() function iterates through REQUIRED_BINARIES = ["ffmpeg", "ffprobe", "yt-dlp"] to verify availability on the system path.

def _which(name: str) -> str | None:
    return shutil.which(name)

def _check_binaries() -> list[str]:
    return [b for b in REQUIRED_BINARIES if not _which(b)]

When _which() returns None for a binary, its name is added to the missing list. This list drives the _status() function, which combines binary availability with Whisper API-key detection—loaded from skills/watch/scripts/config.py—to set status, can_proceed, and missing_binaries flags for downstream consumption.

Platform-Specific Installation Handling

The cmd_install() function branches based on platform.system() to provide appropriate remediation paths for each operating system.

macOS Auto-Installation via Homebrew

On macOS (platform.system() == "Darwin"), the script attempts automatic resolution through _install_macos(missing). This function first verifies Homebrew presence using shutil.which("brew"). If Homebrew is detected, it constructs installation commands via _brew_pkg(missing) and executes them directly. Without Homebrew, it returns the exact brew commands for manual execution.

Linux Installation Hints

For Linux systems, cmd_install() does not auto-install. Instead, it invokes _install_hint_linux(missing) to generate package-manager-specific commands. Users see targeted instructions such as apt: sudo apt install ffmpeg or pipx install yt-dlp rather than automated system modifications.

Windows Installation Hints

Windows follows a similar pattern to Linux, utilizing _install_hint_windows(missing) to display winget commands like winget install Gyan.FFmpeg and winget install yt-dlp.yt-dlp. This approach respects system security policies while providing clear next steps for manual resolution.

Exit Codes and Validation Output

The cmd_check() function translates detection results into discrete exit codes consumed by CI pipelines and wrapper scripts:

• Exit 0: All binaries present and API configured
• Exit 2: Required binaries missing
• Exit 3: First run without Whisper API key
• Exit 4: Both binaries and API key missing

The _status() snapshot aggregates these states for programmatic consumption, enabling the --json flag to output a complete system readiness report.

Running the Preflight Checks

Execute the validation silently or with detailed output using the following commands:

# Silent check - exits 0 only when ready

python3 -m skills.watch.scripts.setup --check

# JSON snapshot for agent integration

python3 -m skills.watch.scripts.setup --json

Typical Linux output when ffmpeg is absent:

[setup] dependencies missing on Linux — please install:
  apt: `sudo apt install ffmpeg` or dnf: `sudo dnf install ffmpeg`
  `pipx install yt-dlp` (recommended) or `pip install --user yt-dlp`

On macOS with Homebrew installed but ffmpeg missing, the output shows:

[setup] running: brew install ffmpeg

Summary

• The preflight logic resides in skills/watch/scripts/setup.py, using shutil.which() for cross-platform binary detection.
• REQUIRED_BINARIES lists ffmpeg, ffprobe, and yt-dlp as mandatory dependencies.
• macOS supports automatic installation via Homebrew when available, while Linux and Windows provide specific installation hints.
• Distinct exit codes (2, 3, 4) enable automated workflows to handle missing dependencies programmatically.
• Configuration integration through skills/watch/scripts/config.py combines binary checks with Whisper API key validation.

Frequently Asked Questions

Which file contains the binary detection logic for claude-video?

The detection logic is implemented in skills/watch/scripts/setup.py, specifically within the _check_binaries() and _which() functions that wrap Python's shutil.which() utility to locate executables on the system PATH.

Does claude-video automatically install missing dependencies on all platforms?

No. Automatic installation only occurs on macOS when Homebrew is detected via shutil.which("brew"). On Linux and Windows, the preflight provides platform-specific installation hints through _install_hint_linux() and _install_hint_windows() but requires manual execution to maintain system security.

What exit code indicates missing binaries in the setup preflight?

Exit code 2 specifically indicates missing binaries. Exit code 3 signals a missing Whisper API key on first run, while exit code 4 indicates both conditions are present simultaneously.

How can I check if my system has the required binaries without installing anything?

Run python3 -m skills.watch.scripts.setup --check for a silent validation that exits with code 0 if all binaries are present, or use --json to receive a detailed status snapshot including the missing_binaries list and API configuration state.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}