How to Manually Set Up ffmpeg and yt-dlp Dependencies for Claude Video

Claude Video requires three external binaries—ffmpeg, ffprobe, and yt-dlp—which must be present on your system's PATH before the /watch skill can function, and while macOS users can rely on automated Homebrew installation via setup.py, Linux and Windows users must install these dependencies manually.

The bradautomates/claude-video repository provides a video analysis skill that depends on external media processing tools. While the included setup.py script handles automated installation on macOS, Linux and Windows environments require manual intervention to satisfy the binary dependencies. Understanding the architecture of the dependency detection system helps ensure you install the correct versions and verify them properly.

Architecture of the Dependency Check System

The setup logic resides in skills/watch/scripts/setup.py, which orchestrates pre-flight validation through several key components.

Required Binaries Declaration

At lines 35-38, the script defines REQUIRED_BINARIES as a constant listing the three mandatory executables: ffmpeg, ffprobe, and yt-dlp. This constant drives all subsequent validation logic in the setup.py orchestrator.

Binary Detection Mechanism

The helper function _which (lines 62-64) wraps Python's shutil.which to locate executables on your $PATH. It returns the absolute path if found or None if the binary is missing, enabling the script to determine which components need installation without performing privileged operations.

Status Aggregation

The _status function (lines 17-28) aggregates the environment state by checking for missing binaries, validating the presence of a Whisper API key, and tracking whether the installer has run previously. This dictionary powers both the --check and --json output modes, providing machine-readable status reports for CI/CD pipelines or manual verification.

Platform-Specific Installation Strategies

The script implements distinct strategies per operating system:

• _install_macos (lines 80-94): Automatically executes brew install commands when Homebrew is detected, handling both ffmpeg and yt-dlp installation without user intervention.
• _install_hint_linux (lines 97-104): Prints manual installation commands using apt, dnf, or pipx rather than executing them, ensuring the script never runs with elevated privileges.
• _install_hint_windows (lines 107-114): Outputs winget or pip installation instructions for Windows environments.

Platform-Specific Installation Guides

macOS Installation

While setup.py can automate macOS setup via Homebrew, you may prefer manual installation or need to install without Homebrew:

# Automated approach (if you want the script to handle it)

python3 skills/watch/scripts/setup.py

# Manual Homebrew installation

brew install ffmpeg yt-dlp

# Manual build from source (fallback without Homebrew)

curl -L https://ffmpeg.org/releases/ffmpeg-snapshot.tar.bz2 | tar -xj
cd ffmpeg
./configure && make && sudo make install
python3 -m pip install --user yt-dlp

Linux Installation

Linux distributions require manual package management since the script only provides hints rather than executing commands.

Debian/Ubuntu:

sudo apt update && sudo apt install -y ffmpeg
pipx install yt-dlp

Fedora/RHEL:

sudo dnf install ffmpeg
pipx install yt-dlp

The ffmpeg package includes both ffmpeg and ffprobe binaries. For yt-dlp, pipx is recommended over pip --user because it creates an isolated executable environment that avoids dependency conflicts with system Python packages.

Windows Installation

Windows users should leverage winget for FFmpeg and pip for yt-dlp:

# Install FFmpeg (includes ffprobe)

winget install Gyan.FFmpeg

# Install yt-dlp

pip install --user yt-dlp

# Alternative via winget:

winget install yt-dlp.yt-dlp

Ensure both executables are added to your system PATH during installation, or restart your terminal session after completion.

Verifying Your Installation

After installing the binaries, validate them through both direct command checks and the Claude Video setup script.

Direct Binary Verification

Run these commands to confirm each binary is accessible:

ffmpeg -version
ffprobe -version
yt-dlp --version

Each command should return version information without errors.

Pre-flight Check with setup.py

Navigate to the repository root and execute the validation script:

# Standard check (exit code 0 indicates success)

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

# Machine-readable JSON output for automation

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

The --check mode invokes cmd_check (lines 59-70), returning exit code 0 only when all required binaries are present. The --json mode outputs a structured report including the missing_binaries array, which is useful for debugging containerized environments or CI pipelines.

Integration with Download and Watch Scripts

Once binaries are verified, the skills/watch/scripts/download.py script can fetch videos using yt-dlp, while skills/watch/scripts/watch.py orchestrates the complete workflow from download to frame extraction to transcription. These downstream components will fail immediately if the required binaries are absent from the PATH.

Configuring Optional Transcription Services

While not strictly required for video processing, the /watch skill supports Whisper transcription via Groq or OpenAI APIs. The setup.py script scaffolds a configuration file at ~/.config/watch/.env (lines 29-40) if it doesn't exist, but you must manually populate your API keys:

# Edit the scaffolded configuration

nano ~/.config/watch/.env

Add your service-specific keys to enable transcription features after the core binaries are installed.

Summary

• Claude Video requires ffmpeg, ffprobe, and yt-dlp binaries to be present on your system's PATH before the /watch skill can execute according to the REQUIRED_BINARIES constant in skills/watch/scripts/setup.py.
• The setup.py file provides automated installation only for macOS via Homebrew; Linux and Windows users receive installation hints and must run package commands manually.
• Key functions include _which for binary detection (lines 62-64), _status for environment aggregation (lines 17-28), and platform-specific installer hints at lines 97-114.
• Linux users should use apt or dnf for FFmpeg and pipx for yt-dlp to avoid privilege escalation and system package conflicts.
• Windows users can utilize winget install Gyan.FFmpeg and pip install --user yt-dlp to satisfy dependencies.
• Always verify installation using python3 skills/watch/scripts/setup.py --check before attempting video processing, as the script validates the same binaries used by download.py and watch.py.

Frequently Asked Questions

Why does the setup script not automatically install dependencies on Linux?

The _install_hint_linux function (lines 97-104) intentionally prints installation commands rather than executing them. This design prevents the script from requiring sudo privileges or making system-level changes without explicit user consent, adhering to security best practices for open-source automation tools.

What is the difference between ffprobe and ffmpeg, and why does Claude Video need both?

According to the REQUIRED_BINARIES declaration in setup.py (lines 35-38), Claude Video requires ffmpeg for video encoding/decoding and stream processing, while ffprobe extracts metadata such as duration, codec information, and frame counts. The download.py script uses ffprobe to validate downloaded media before processing.

Can I use a virtual environment for yt-dlp instead of system-wide installation?

Yes, using pipx install yt-dlp creates an isolated virtual environment that exposes the binary to your PATH without conflicting with system Python packages. This is the recommended approach on Linux where yt-dlp is not typically available through standard distribution repositories.

Where should I report issues if the --check command still fails after installation?

If python3 skills/watch/scripts/setup.py --check returns a non-zero exit code despite successful manual installation, verify that your shell environment has refreshed its PATH cache. The _which function relies on shutil.which, which checks the current environment variables—restarting your terminal session often resolves PATH detection issues without code changes. The automated test suite in tests/test_setup.py provides additional validation scenarios for troubleshooting.

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