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

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 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 module depends on these binaries to extract images and query video metadata. According to the source code, 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 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, which creates this configuration file automatically if missing.

Running the Setup Script

The installation process centers on 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:

nano ~/.config/watch/.env

Add your credentials:

GROQ_API_KEY=sk-your-groq-key-here

# OR

OPENAI_API_KEY=sk-your-openai-key-here

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

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

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

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. The script orchestrates download.py for yt-dlp operations, frames.py for image extraction, and whisper.py for transcription.

Download and analyze a YouTube video with balanced detail:

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:

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
• 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
• Completion Marker: The installer writes SETUP_COMPLETE=true to your .env file after successful configuration
• Entry Point: Use skills/watch/scripts/watch.py to process videos, leveraging download.py for yt-dlp integration and 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, 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 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 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 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 serves as the runtime entry point that orchestrates the actual video processing workflow, importing modules from download.py, frames.py, and whisper.py to generate markdown reports with extracted frames and transcripts.

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