How the setup.py Installer Detects Platform and Installs Dependencies in claude-video

The setup.py script uses Python's platform.system() function to identify macOS, Linux, or Windows, then executes platform-specific logic to either auto-install dependencies via Homebrew on macOS or provide package manager commands for Linux and Windows.

The setup.py installer serves as the pre-flight dependency manager for the /watch skill in the bradautomates/claude-video repository. Located at skills/watch/scripts/setup.py, this script ensures that required binaries like ffmpeg, ffprobe, and yt-dlp are present before the video processing pipeline executes. Understanding how this installer detects your operating system and handles dependency resolution is essential for troubleshooting environment setup issues.

Platform Detection with platform.system()

The installer begins by importing Python's built-in platform module to query the host operating system at runtime. According to the source code at line 23, the script imports platform to access the system() method.

When invoked without the --check or --json flags, the cmd_install() function captures the OS identifier and branches accordingly. As implemented in lines 3035-3042, the detection logic follows this pattern:

system = platform.system()
if system == "Darwin":
    # macOS auto-install via Homebrew

elif system == "Linux":
    # print apt/pipx hints

elif system == "Windows":
    # print winget hints

else:
    # fallback message for unknown platforms

This branching structure ensures that each operating system receives appropriate installation instructions without unnecessary privilege escalation.

Dependency Installation Logic

The installer employs different strategies depending on the detected platform. While macOS supports automatic installation through Homebrew, Linux and Windows receive detailed command hints because the repository avoids invoking sudo or privileged package managers directly.

macOS Auto-Installation via Homebrew

On Darwin systems (macOS), the _install_macos() helper function checks for the presence of the Homebrew package manager. If brew is available, the script constructs a package list using the _brew_pkg variable and executes brew install commands automatically. This logic resides in lines 80-95 of setup.py, enabling a zero-intervention setup experience for Mac users.

Linux Installation Hints

For Linux environments, the _install_hint_linux() function assembles human-readable instructions targeting common package managers. As found in lines 196-202, the script provides specific commands for APT (Debian/Ubuntu) and DNF (Fedora/RHEL), plus a recommendation to use pipx for installing the yt-dlp Python tool. These hints guide users through manual installation without requiring the script to execute with elevated privileges.

Windows Installation Hints

On Windows, the _install_hint_windows() function generates winget commands for acquiring ffmpeg and yt-dlp. Located at lines 207-213, this helper outputs copy-paste ready commands that leverage Windows Package Manager, allowing users to resolve dependencies through their preferred terminal without administrative complexity.

Binary Checking and Execution Flow

The installation process begins with _check_binaries(), which verifies the presence of required executables in the system PATH. When a missing binary is detected, the script selects the appropriate platform-specific helper based on the earlier OS detection.

The cmd_install() function orchestrates this workflow: it identifies the operating system, invokes the relevant installation method, and exits with status code 2 if dependencies remain unsatisfied after the hint or installation attempt. This explicit exit code allows automation scripts to detect incomplete setups programmatically.

Running the Installer

Execute the script from the repository root to trigger platform detection and dependency resolution:

# Run the full interactive installer (detects platform automatically)

python3 skills/watch/scripts/setup.py

# Only perform a silent pre-flight check – returns 0 when ready

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

# Get a machine-readable JSON status report

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

Running setup.py on macOS will attempt to install missing binaries via Homebrew automatically, while Linux or Windows executions output the appropriate installation hints for manual execution.

Summary

• The installer uses platform.system() imported at line 23 to distinguish between Darwin, Linux, and Windows operating systems.
• macOS receives automatic dependency installation via the _install_macos() function and Homebrew (lines 80-95).
• Linux and Windows receive command hints through _install_hint_linux() (lines 196-202) and _install_hint_windows() (lines 207-213) rather than automatic installation.
• The _check_binaries() function validates requirements before the main logic branches, exiting with code 2 if dependencies are missing after attempted resolution.
• Three execution modes exist: interactive install, silent --check, and machine-readable --json output.

Frequently Asked Questions

How does setup.py detect the operating system?

The script calls platform.system() within the cmd_install() function to retrieve the OS name as a string ("Darwin", "Linux", or "Windows"). This value determines which platform-specific helper function executes, as shown in lines 3035-3042 of skills/watch/scripts/setup.py.

Does the installer automatically install dependencies on all platforms?

No. According to the bradautomates/claude-video source code, automatic installation only occurs on macOS when Homebrew is present. On Linux and Windows, the script prints specific installation hints using apt, dnf, pipx, or winget commands, requiring the user to execute them manually to avoid privilege escalation.

What happens if a required binary is missing?

When _check_binaries() detects a missing dependency, the script invokes the appropriate platform handler. If automatic installation fails or the platform requires manual intervention (Linux/Windows), the installer prints the necessary commands and exits with status code 2, signaling that the environment is not ready for the /watch skill.

Where can I find the platform-specific installation helpers?

The helper functions are defined in skills/watch/scripts/setup.py: _install_macos() at lines 80-95, _install_hint_linux() at lines 196-202, and _install_hint_windows() at lines 207-213. These functions handle the actual command generation and execution logic for their respective operating systems.

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