# How the setup.py Preflight Check Handles Different Operating Systems > Discover how setup.py preflight check detects your OS, installing dependencies with Homebrew on macOS and offering manual hints for Linux and Windows. - Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video) - Tags: how-to-guide - Published: 2026-08-13 --- **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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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: ```bash # 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 ``` ```bash # Full installer (auto-installs on macOS, shows hints elsewhere) python3 skills/watch/scripts/setup.py ``` ```bash # 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`](https://github.com/bradautomates/claude-video/blob/main/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.