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

> Manually set up ffmpeg and yt-dlp dependencies for Claude Video on Linux and Windows. Ensure these essential binaries are on your PATH for the watch skill to work.

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

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/setup.py) can automate macOS setup via Homebrew, you may prefer manual installation or need to install without Homebrew:

```bash

# 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:**

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

```

**Fedora/RHEL:**

```bash
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:

```powershell

# 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:

```bash
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:

```bash

# 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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py) script can fetch videos using `yt-dlp`, while [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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:

```bash

# 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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py).
- The [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/download.py) and [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/tests/test_setup.py) provides additional validation scenarios for troubleshooting.