Limitations of bradautomates/claude-video: Critical Constraints Before You Deploy

The bradautomates/claude-video repository requires external binaries (ffmpeg and yt-dlp), imposes hard caps on frame extraction (50-100 frames by default), and demands a Whisper API key for transcription fallback, making it unsuitable for offline environments or machines without media processing tools installed.

The claude-video skill is a self-contained Agent-Skill designed to let Claude models analyze video content by downloading media, extracting representative frames, and surfacing transcripts. While powerful for its intended use case, understanding the limitations of bradautomates/claude-video is essential before integrating it into your workflow, as several architectural constraints dictate where and how the tool can operate.

External Binary Dependencies

The skill cannot function without specific command-line tools installed on the host system. It is essentially a Python wrapper around external binaries rather than a pure Python implementation.

• ffmpeg is required for frame extraction in skills/watch/scripts/frames.py.
• yt-dlp (or yt-dlp) is mandatory for downloading media and fetching captions, handled in skills/watch/scripts/download.py.

If either binary is missing from the system PATH, the core workflow fails immediately with a runtime error. The test suite in tests/test_frames.py and tests/test_watch.py also requires a working ffmpeg installation and cannot execute in fully sandboxed CI environments without these binaries.

Network and API Requirements

Two hard dependencies limit offline usage:

Internet Connectivity – Any URL source triggers network requests to fetch video metadata, captions, or the actual media file. The functions download.is_url, download.fetch_captions, and download.download in skills/watch/scripts/download.py assume outbound internet access. Firewalled or air-gapped environments cannot resolve URLs.

Whisper API Key – When caption files are missing, the fallback transcription requires a valid API key. According to skills/watch/scripts/whisper.py, the load_api_key function expects credentials in ~/.config/watch/.env (Groq or OpenAI). Without this key, the skill degrades to "frames-only" mode, providing visual analysis without transcript context.

Frame Processing Constraints

The tool imposes strict limits to manage token usage and processing time for Claude consumption.

Hard Frame Caps – The detail setting enforces maximum frame limits defined in skills/watch/scripts/config.py (frame_cap). The "efficient" setting caps at 50 frames, while "balanced" caps at 100 frames. Lines 71-80 and 95-99 in skills/watch/scripts/watch.py implement this budgeting logic, preventing users from extracting unlimited frames regardless of video length.

Optional Deduplication – Near-duplicate frame removal is disabled by default via the --no-dedup flag in watch.py. When disabled, static screen recordings generate many identical frames, significantly increasing token usage. The deduplication logic exists in skills/watch/scripts/frames.py, but users must explicitly enable it to avoid processing redundant visual data.

Input Format Limitations

The skill accepts only specific temporal and subtitle formats, rejecting alternative specifications.

Restricted Timestamp Syntax – The parse_timestamps utility (accessed via watch.py and configuration utilities) recognizes only SS, MM:SS, or HH:MM:SS formats. Complex time expressions like frame numbers, percentages, or decimal seconds are not supported.

Single Subtitle Format – Only WebVTT (.vtt) files are parsed. The transcribe.parse_vtt function in skills/watch/scripts/transcribe.py targets YouTube captions specifically, ignoring SRT, ASS, or other subtitle formats.

Platform and Workflow Constraints

Several design choices limit portability and usability:

POSIX-Assumed Paths – The codebase assumes a POSIX-like filesystem, utilizing Path objects, tempfile.mkdtemp, and executable bits throughout scripts in skills/watch/scripts/. Windows edge cases may cause path handling failures.

No Built-in Caching – Each execution re-downloads the video unless the user manually supplies a local file via --out-dir. The download.download function always writes to a fresh temporary directory, making repeated analysis of the same URL inefficient.

Audio-Only Optimization Limit – The audio-only shortcut (lines 111-113 in watch.py) activates only when detail=transcript and no timestamps are supplied. This optimization cannot be used when frame extraction is required, forcing full video downloads for any visual analysis.

No Visual Interface – Output is a markdown report with frame file paths printed to stdout. Users must manually open each image; there is no GUI or visual preview, as the skill is designed for Claude model consumption rather than human interaction.

Practical Failure Examples

The following snippets demonstrate typical failure modes caused by these limitations:

# This will fail if ffmpeg is not installed

# Error: OSError: ffmpeg not found – please install ffmpeg to use the watch skill

import subprocess
subprocess.run([
    "python", "-m", "skills.watch.scripts.watch",
    "https://youtube.com/watch?v=example",
    "--detail", "balanced"
])

# Attempting Whisper fallback without API key

# Results in frames-only mode, no transcript

subprocess.run([
    "python", "-m", "skills.watch.scripts.watch",
    "https://example.com/video.mp4",
    "--whisper", "openai"
])

# Exceeding frame caps silently truncates output

# Only 50 frames extracted despite longer video

subprocess.run([
    "python", "-m", "skills.watch.scripts.watch",
    "local_video.mp4",
    "--detail", "efficient"  # Hard cap at 50

])

Summary

• External binaries required: ffmpeg and yt-dlp must be pre-installed and available in system PATH.
• Network dependent: URL processing requires internet access; no offline URL resolution capability.
• API key dependency: Whisper fallback requires Groq or OpenAI credentials in ~/.config/watch/.env.
• Frame extraction limits: Hard caps at 50 (efficient) or 100 (balanced) frames defined in config.py.
• Format restrictions: Supports only WebVTT subtitles and simple timestamp formats (SS, MM:SS, HH:MM:SS).
• POSIX preference: Path handling assumes Linux/macOS environments; Windows compatibility is not guaranteed.
• No caching mechanism: Repeated runs re-download content unless local files are specified.

Frequently Asked Questions

What happens if I run bradautomates/claude-video without ffmpeg installed?

The skill will raise a RuntimeError or OSError during the frame extraction phase. Specifically, skills/watch/scripts/frames.py attempts to spawn ffmpeg subprocesses; if the binary is missing, the script exits with the message "ffmpeg not found – please install ffmpeg to use the watch skill."

Can I use bradautomates/claude-video entirely offline with local video files?

Partially. While you can process local video files without downloading from URLs, the Whisper fallback for transcription still requires an API key and network access to Groq or OpenAI. Additionally, the tool assumes internet connectivity for any URL-based input, and the test suite requires network resources to validate functionality.

Why does the tool extract only 50 frames from my hour-long video?

The default "efficient" detail setting imposes a hard cap defined in skills/watch/scripts/config.py to manage token costs. To extract more frames, you must explicitly set --detail balanced (100 frames) or adjust frame_cap parameters, though the skill prioritizes Claude token limits over comprehensive frame sampling.

Does bradautomates/claude-video support Windows operating systems?

The repository is designed for POSIX-like environments typical of Claude Code workflows. While Python's pathlib provides some abstraction, the code uses POSIX-specific assumptions for temporary directories and executable handling. Windows users may encounter path resolution issues or need to run the tool within WSL (Windows Subsystem for Linux).

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