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

> Discover the limitations of bradautomates/claude-video. Understand essential constraints like external binaries, frame caps, and Whisper API key requirements before deploying this tool.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: limitations
- Published: 2026-07-15

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/tests/test_frames.py) and [`tests/test_watch.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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:

```python

# 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"
])

```

```python

# 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"
])

```

```python

# 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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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).