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

> Discover how claude-video's setup preflight uses shutil.which() to detect missing ffmpeg and yt-dlp binaries. Get platform-specific install hints or automatic Homebrew installation on macOS.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-07-14

---

**The setup preflight in claude-video uses `shutil.which()` via the `_which()` helper in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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:

```bash

# 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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.