How the setup.py Preflight Check Handles Different Operating Systems

The setup.py preflight check uses platform detection to automatically install dependencies via Homebrew on macOS while providing manual installation hints for Linux and Windows users.

The setup.py script in the bradautomates/claude-video repository serves as the entry point for preparing the /watch skill. Its preflight logic determines whether required binaries are present and adapts its installation strategy based on the detected operating system. This ensures users on macOS, Linux, and Windows receive appropriate guidance for configuring FFmpeg and yt-dlp.

Silent Readiness Check vs. Interactive Installer

The script operates in two distinct modes depending on the arguments passed. When invoked with --check, it runs cmd_check() to build a status snapshot via _status() and exits silently with code 0 if all requirements are met. This path is completely OS-agnostic and requires no platform-specific branching.

The default mode triggers cmd_install(), which first discovers missing binaries through _check_binaries() and then applies OS-specific remediation logic based on platform.system().

Operating System Branching Strategy

When dependencies are missing, the installer inspects platform.system() to determine the appropriate action. The implementation distinguishes between macOS (Darwin), Linux, Windows, and unsupported platforms, tailoring the user experience for each.

macOS (Darwin) Automatic Installation

On macOS, identified when platform.system() returns "Darwin", the script executes _install_macos(missing) to attempt automatic remediation via Homebrew. If Homebrew is absent, the function returns a failure message directing users to https://brew.sh and displays the exact brew install command needed, as seen in lines 81-86 of skills/watch/scripts/setup.py.

When Homebrew is present, the script collapses ffmpeg and ffprobe into a single ffmpeg entry via _brew_pkg() and executes the installation command (lines 87-95). This provides a fully automated setup experience for macOS users.

Linux Manual Installation Hints

For Linux systems ("Linux"), the installer does not attempt automatic package management. Instead, it calls _install_hint_linux() (lines 98-104) to print distribution-specific commands and exits with code 2.

The generated hints include:

• sudo apt install ffmpeg or sudo dnf install ffmpeg for the FFmpeg stack
• pipx install yt-dlp (recommended) or pip install --user yt-dlp for the video downloader

Windows Manual Installation Hints

Windows platforms ("Windows") receive similar treatment through _install_hint_windows() (lines 106-113). The script outputs Windows-specific installation commands and exits with code 2.

The suggested commands include:

• winget install Gyan.FFmpeg for FFmpeg installation
• winget install yt-dlp.yt-dlp or pip install --user yt-dlp for yt-dlp

Unsupported Platforms

If the detected OS does not match Darwin, Linux, or Windows, the installer falls back to a generic manual-install message (lines 124-126) and exits with code 2. This ensures the script fails gracefully on BSD, Solaris, or other uncommon systems.

Post-Installation Configuration

After resolving binary dependencies, the script scaffolds a .env file if one does not exist. It then checks for a Whisper API key in the environment. If GROQ_API_KEY or OPENAI_API_KEY is present, the script writes SETUP_COMPLETE=true to the environment (lines 140-159) and reports success.

If no API key is detected, the script prints a reminder to add the required environment variable (lines 242-249) and exits with code 3, allowing the user to complete configuration manually.

Usage Examples

Run these commands from the repository root to interact with the preflight check:

# Silent readiness check (works on any OS)

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

# → exit 0 if ready, otherwise prints error and exits 2/3/4

# Full installer (auto-installs on macOS, shows hints elsewhere)

python3 skills/watch/scripts/setup.py

# Machine-readable status output (useful for automation)

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

Summary

• The setup.py preflight check operates in two modes: a silent --check flag for verification and a default installer mode for remediation.
• macOS users receive automatic installation via Homebrew through _install_macos(), while Linux and Windows users receive platform-specific manual instructions.
• The script uses platform.system() to detect Darwin, Linux, and Windows, falling back to generic messages for unsupported operating systems.
• Binary checks cover FFmpeg, ffprobe, and yt-dlp, with macOS collapsing ffmpeg and ffprobe into a single Homebrew package.
• Configuration completion requires a Whisper API key (GROQ_API_KEY or OPENAI_API_KEY) to set SETUP_COMPLETE=true.

Frequently Asked Questions

What exit codes does setup.py return?

The script returns 0 if the system passes the readiness check, 2 if binaries are missing or the OS is unsupported, 3 if the Whisper API key is missing, and 4 for other configuration errors. These codes allow CI/CD pipelines and automation scripts to handle failures programmatically.

Does the preflight check modify system packages on Linux or Windows?

No. According to the source code in skills/watch/scripts/setup.py, the installer only attempts automatic package installation on macOS via Homebrew. For Linux and Windows, it strictly prints manual installation hints via _install_hint_linux() and _install_hint_windows() without executing system commands.

How does the script handle FFmpeg and ffprobe on macOS?

The _brew_pkg() function collapses both ffmpeg and ffprobe into a single ffmpeg entry when building the Homebrew install command. Since the FFmpeg Homebrew formula includes both binaries, this prevents duplicate installation attempts while ensuring both requirements are satisfied.

Can I run the preflight check without installing anything?

Yes. Use the --check flag to run cmd_check(), which performs a read-only verification of your system. This mode checks for required binaries and API keys without triggering _install_macos() or any installation hints, making it safe for non-destructive validation.

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