# Claude Video Installation Process: Complete ffmpeg, yt-dlp, and API Setup Guide

> Install Claude Video easily with our step-by-step guide. Effortlessly set up ffmpeg, yt-dlp, and configure your Whisper API key for seamless video transcription. Get started today!

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

---

**To install Claude Video, run `python3 skills/watch/scripts/setup.py` to check for ffmpeg, ffprobe, and yt-dlp binaries, then configure your Whisper API key in `~/.config/watch/.env` to enable video transcription.**

The Claude Video skill from the `bradautomates/claude-video` repository enables Claude models to download videos, extract frames, and generate transcripts using native captions or Whisper fallback. This self-contained Agent Skill requires specific system binaries and optional API credentials before you can execute the `/watch` command. Understanding the complete **Claude Video installation process ffmpeg yt-dlp setup** ensures your environment meets all prerequisites for seamless video analysis.

## Prerequisites for Claude Video Installation

Before running the setup script, your system must satisfy three core dependencies. The installer at [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) verifies these automatically, but understanding what each component does helps troubleshoot platform-specific issues.

### ffmpeg and ffprobe

**ffmpeg** and **ffprobe** handle video decoding and frame extraction. The [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) module depends on these binaries to extract images and query video metadata. According to the source code, [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) verifies their presence via the `_check_binaries()` function, which scans your system `PATH` for both executables.

### yt-dlp

**yt-dlp** provides robust video download and caption extraction capabilities. This Python application powers the [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) module, specifically the `fetch_captions()` function for pulling source videos and embedded subtitles. Like ffmpeg, yt-dlp is listed in `REQUIRED_BINARIES` and validated during the installation check.

### Whisper API Key (Optional)

While optional, a **Whisper API key** enables transcription fallback when videos lack captions. The skill supports Groq (preferred) and OpenAI backends. Keys are read from `~/.config/watch/.env` by the `_read_env_key()` function in [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py), which creates this configuration file automatically if missing.

## Running the Setup Script

The installation process centers on [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py), which orchestrates binary detection, platform-specific installation hints, and environment scaffolding.

### Binary Detection and Installation

When you execute the setup script, the `main()` entry point triggers `_check_binaries()` to detect missing dependencies. The script provides platform-specific assistance:

- **macOS**: If Homebrew is present, `_install_macos()` runs `brew install ffmpeg yt-dlp` automatically
- **Linux**: `_install_hint_linux()` prints apt/dnf/pipx installation commands
- **Windows**: `_install_hint_windows()` displays `winget` commands for manual installation

### Environment Configuration

After binary verification, `_scaffold_env()` creates `~/.config/watch/.env` if it does not exist. This template includes placeholders for `GROQ_API_KEY=` and `OPENAI_API_KEY=`. Once you add a valid API key, `_write_setup_complete()` appends `SETUP_COMPLETE=true` to the file, marking the installation as finished and silencing subsequent setup prompts.

## Configuring Whisper API Access

To enable transcription capabilities, edit the generated environment file and add your preferred provider:

```bash
nano ~/.config/watch/.env

```

Add your credentials:

```text
GROQ_API_KEY=sk-your-groq-key-here

# OR

OPENAI_API_KEY=sk-your-openai-key-here

```

The [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) module uses `load_api_key()` to select the active backend, preferring Groq when both keys are present. Without this configuration, the skill still functions but skips the Whisper fallback when native captions are unavailable.

## Verifying Your Installation

Run the setup script with the `--check` flag to verify your environment without triggering installation:

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

```

For programmatic verification (useful for Claude Code integration), use the JSON output mode:

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

```

This returns a structured snapshot indicating binary availability, missing components, and which Whisper backend is selected.

## Using Claude Video After Installation

Once setup completes, invoke the skill through [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py). The script orchestrates [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) for yt-dlp operations, [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) for image extraction, and [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) for transcription.

Download and analyze a YouTube video with balanced detail:

```bash
python3 skills/watch/scripts/watch.py "https://www.youtube.com/watch?v=abc123" \
    --detail balanced --resolution 720 --max-frames 150

```

Extract frames at specific timestamps without downloading the full video:

```bash
python3 skills/watch/scripts/watch.py "https://www.youtube.com/watch?v=abc123" \
    --detail transcript --timestamps "00:30,01:10,02:45"

```

## Summary

- **Binary Requirements**: Claude Video requires `ffmpeg`, `ffprobe`, and `yt-dlp` installed on your system, verified via `_check_binaries()` in [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py)
- **Automated Setup**: Run `python3 skills/watch/scripts/setup.py` to check dependencies; macOS users get automatic Homebrew installation while Linux/Windows receive platform-specific commands
- **API Configuration**: Create `~/.config/watch/.env` with `GROQ_API_KEY` or `OPENAI_API_KEY` to enable Whisper transcription fallback via [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py)
- **Completion Marker**: The installer writes `SETUP_COMPLETE=true` to your `.env` file after successful configuration
- **Entry Point**: Use [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) to process videos, leveraging [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) for yt-dlp integration and [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) for image extraction

## Frequently Asked Questions

### How does Claude Video handle missing binaries on different operating systems?

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 `_check_binaries()` function detects missing dependencies and routes to platform-specific handlers. On macOS, `_install_macos()` automatically executes `brew install` commands if Homebrew is available. For Linux and Windows, the script prints manual installation hints via `_install_hint_linux()` and `_install_hint_windows()` rather than auto-installing, showing apt/dnf or winget commands respectively.

### Where does Claude Video store API keys and configuration settings?

The skill stores configuration in `~/.config/watch/.env`, created automatically by `_scaffold_env()` during first run. This file holds your `GROQ_API_KEY` or `OPENAI_API_KEY` for Whisper transcription, along with the `SETUP_COMPLETE=true` marker that indicates successful installation. The `_read_env_key()` function reads these values at runtime to determine which transcription backend to use.

### Can I use Claude Video without a Whisper API key?

Yes, the skill functions without API keys if your target videos contain native captions. The `fetch_captions()` function in [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) attempts to extract embedded subtitles first, parsing them via `parse_vtt()`. However, without a configured Whisper key in `~/.config/watch/.env`, the `transcribe_video()` function in [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) will not execute, meaning videos without captions will lack transcript data in the final report.

### What is the difference between the setup script and the main watch script?

[`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) handles pre-flight checks, binary installation hints, and environment scaffolding through functions like `_check_binaries()` and `_write_setup_complete()`. In contrast, [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) serves as the runtime entry point that orchestrates the actual video processing workflow, importing modules from [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py), [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py), and [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) to generate markdown reports with extracted frames and transcripts.