# How Claude Video's Preflight Setup Checks and Installs Dependencies

> Learn how Claude Video's preflight setup checks and installs dependencies like ffmpeg and yt-dlp on macOS via Homebrew, sets up your config, and verifies API keys for smooth operation.

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

---

**Claude Video's preflight setup script detects missing system binaries (`ffmpeg`, `ffprobe`, `yt-dlp`), auto-installs them on macOS via Homebrew while providing platform-specific hints for Linux and Windows, scaffolds a configuration file at `~/.config/watch/.env`, and verifies Whisper API keys before marking the setup complete.**

The `/watch` skill in the [bradautomates/claude-video](https://github.com/bradautomates/claude-video) repository relies on a comprehensive preflight routine to ensure all dependencies are present before processing video content. Located at [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py), this Python script serves as the gatekeeper that validates system readiness, handles cross-platform installation logic, and manages API configuration without requiring elevated privileges.

## What the Preflight Setup Validates

The [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) script performs three essential tasks before allowing video processing to begin. First, it **detects missing system binaries** by scanning for `ffmpeg`, `ffprobe`, and `yt-dlp` using `shutil.which`. Second, it **installs missing dependencies** or provides exact installation commands for the user's operating system. Third, it **scaffolds and finalizes user configuration** by creating a `.env` file and verifying the presence of Whisper API keys.

## Step-by-Step Implementation Details

### Binary Detection with `_check_binaries()`

The core validation logic resides in `_check_binaries()`, which iterates through the `REQUIRED_BINARIES` list and uses Python's `shutil.which` to verify each tool is accessible in the system PATH.

```python

# From skills/watch/scripts/setup.py

def _check_binaries():
    missing = []
    for binary in REQUIRED_BINARIES:
        if not shutil.which(binary):
            missing.append(binary)
    return missing

```

This function returns a list of missing binaries that drives all subsequent installation logic.

### Platform-Specific Installation Logic

When binaries are missing, the script routes to platform-specific handlers. **macOS** receives automatic installation via the `_install_macos()` function, which verifies Homebrew presence and executes `brew install ffmpeg yt-dlp`. The mapping from binary names to package names uses the internal `_brew_pkg` abstraction.

For **Linux** and **Windows**, the script calls `_install_hint_linux()` or `_install_hint_windows()` to generate precise terminal commands rather than attempting automatic installation. Linux users receive `apt` or `dnf` suggestions for FFmpeg and `pipx` recommendations for `yt-dlp`, while Windows users get `winget` commands like `winget install Gyan.FFmpeg`.

### Configuration Scaffolding with `_scaffold_env()`

The `_scaffold_env()` function creates `~/.config/watch/.env` from a template defined in `ENV_TEMPLATE`. This operation is idempotent; re-running the setup never overwrites existing configuration files or API keys.

Once scaffolding completes, `_write_setup_complete()` appends `SETUP_COMPLETE=true` to the file, marking the installation as finalized for future preflight checks.

### API Key Verification

The setup verifies Whisper API availability through `_have_api_key()`, which checks for `GROQ_API_KEY` or `OPENAI_API_KEY` in either the environment variables or the scaffolded `.env` file. The helper `_read_env_key()` reads the configuration file to detect existing keys without exposing them in logs.

## Command-Line Interface Modes

The script exposes three distinct operational modes controlled by command-line arguments in the `main()` entry point.

**`--check` Mode**: Used by the `/watch` skill during regular operation. The `cmd_check()` function calls `_status()` and exits with code `0` if `can_proceed` is true. Non-zero exit codes indicate specific failure states: `2` for missing binaries, `3` for missing API key when setup is otherwise complete, and `4` for both binaries and API key missing.

**`--json` Mode**: Invoked via `cmd_json()`, this produces machine-readable status output including fields like `status`, `can_proceed`, `missing_binaries`, and `platform`.

**Interactive Mode** (default): The `cmd_install()` function provides the full setup experience, attempting auto-installation on macOS, displaying hints for other platforms, scaffolding the environment file, and guiding users through API key configuration.

## Practical Usage Examples

### Silent Preflight Check

Run this to verify readiness without interactive prompts, as the `/watch` skill does internally:

```bash
python3 skills/watch/scripts/setup.py --check

```

**Exit codes:**
- `0` - All binaries present and API key configured (or setup complete)
- `2` - Binaries missing
- `3` - No API key but setup marked complete
- `4` - Both binaries missing and no API key

### Machine-Readable Status

For debugging or CI/CD pipelines:

```bash
python3 skills/watch/scripts/setup.py --json

```

Sample output:

```json
{
  "status": "needs_install_and_key",
  "can_proceed": false,
  "first_run": true,
  "setup_complete": false,
  "missing_binaries": ["ffmpeg", "yt-dlp"],
  "whisper_backend": null,
  "has_api_key": false,
  "config_file": "/home/user/.config/watch/.env",
  "platform": "Linux"
}

```

### First-Time Interactive Setup

For initial installation, run without flags:

```bash
python3 skills/watch/scripts/setup.py

```

This executes the full workflow: binary checks, macOS auto-installation (if applicable), `.env` scaffolding, and API key instructions. Once you add `GROQ_API_KEY` or `OPENAI_API_KEY` to `~/.config/watch/.env` and re-run, the script confirms readiness with the message: `[setup] ready. whisper backend: groq`.

## Summary

- **[`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py)** serves as the central preflight mechanism for Claude Video's `/watch` skill.
- **Binary detection** uses `shutil.which` via `_check_binaries()` to locate `ffmpeg`, `ffprobe`, and `yt-dlp`.
- **macOS auto-installation** leverages Homebrew through `_install_macos()`, while Linux and Windows receive precise terminal commands via hint generators.
- **Configuration management** creates `~/.config/watch/.env` idempotently using `_scaffold_env()` and tracks completion state with `_write_setup_complete()`.
- **API validation** checks for `GROQ_API_KEY` or `OPENAI_API_KEY` through `_have_api_key()` before allowing processing.
- **Exit codes** (`0`, `2`, `3`, `4`) enable programmatic consumption by the `/watch` skill and automation hooks.

## Frequently Asked Questions

### What system binaries does Claude Video require?

Claude Video requires three system binaries: **FFmpeg** (`ffmpeg` and `ffprobe`) for video processing, and **yt-dlp** for downloading video content from URLs. The `_check_binaries()` function in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) validates these are present in your system PATH before allowing any video operations.

### Does the setup script require sudo or administrator privileges?

No. The preflight setup is designed for **zero-sudo operation**. On macOS, it uses Homebrew (which typically runs without sudo when properly configured), and on Linux/Windows it only prints installation hints rather than executing system-level commands. This safety design allows the script to run within Claude Code, Cursor, or other AI coding environments without elevation prompts.

### How does the script handle API keys for Whisper transcription?

The script checks for `GROQ_API_KEY` (preferred for cost and speed) or `OPENAI_API_KEY` via `_have_api_key()` and `_read_env_key()`. If found in environment variables or `~/.config/watch/.env`, the setup marks itself complete. If missing, the interactive installer displays specific instructions pointing to `console.groq.com` or `platform.openai.com` without terminating, allowing users to configure credentials after initial binary setup.

### Can I run the preflight check without installing anything?

Yes. Use the `--check` flag to perform a read-only validation: `python3 skills/watch/scripts/setup.py --check`. This command exits silently with code `0` if ready, or returns specific error codes (`2`, `3`, or `4`) indicating what dependencies are missing, without triggering installation attempts or scaffolding new files.