# How Claude-Video Warns About Long Videos and Handles Sparse Frame Coverage

> Discover how Claude-Video handles long videos and sparse frame coverage. Learn about warnings for videos over 10 minutes and strategies for focused analysis.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: deep-dive
- Published: 2026-07-10

---

**Claude-Video emits an explicit warning when processing videos longer than 10 minutes under capped detail modes, and mitigates sparse coverage by offering focused time windows or the uncapped `token-burner` detail level.**

The `bradautomates/claude-video` repository provides a Python-based workflow for analyzing video content through frame extraction and transcription. When processing long videos exceeding 10 minutes, the tool implements specific safeguards against sparse frame coverage that could compromise analysis quality.

## The 10-Minute Threshold and Warning System

### Trigger Conditions in watch.py

The warning logic resides in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) at lines 326-334. The script evaluates three conditions before emitting the alert:

- The video is not running in focused mode (`not focused`)
- Total duration exceeds 600 seconds (`full_duration > 600`)
- Current detail mode applies a frame cap (`detail` not in `"transcript"` or `"token-burner"`)

When these conditions are met, the script calculates the minute count and prints a formatted warning:

```python
if not focused and full_duration > 600 and detail not in ("transcript", "token-burner"):
    mins = int(full_duration // 60)
    print()
    print(
        f"> **Warning:** This is a {mins}-minute video. Frame coverage is sparse at this length "
        f"under `{detail}` detail — its cap spreads thin across the full clip. For better results, "
        "re-run with `--start HH:MM:SS --end HH:MM:SS` to zoom into a section, or use "
        "`--detail token-burner` to keep every scene‑change frame across the whole video."
    )

```

### Understanding the Sparse Scan Warning

In the default **capped** detail modes—**efficient** (50 frames) and **balanced** (100 frames)—the frame budget is shared across the entire video duration. When a video exceeds 10 minutes, this distribution causes timestamps to become widely spaced, creating what the tool calls a "sparse scan." The warning explicitly informs users that the current detail mode’s cap spreads thin across the full clip, potentially missing visual details in long-form content.

## Mitigation Strategies for Sparse Coverage

### Focused Mode with Time Windows

Supplying `--start` and `--end` parameters forces a *focused* budget that densely populates the requested interval. The script uses `auto_fps_focus()` (implemented in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)) to compute a higher effective frames-per-second rate for the shorter window, ensuring comprehensive coverage of the specific segment rather than sparse sampling across the whole video.

### Token-Burner Detail Mode

Selecting `--detail token-burner` **removes the frame cap entirely**, preserving every scene-change frame even for long videos. This mode suppresses the long-video warning because it eliminates the sparse coverage problem by processing all detected scene changes regardless of duration. According to the source code, this is the only detail mode besides `transcript` that bypasses the 600-second warning check.

### User Guidance and Documentation

The warning message explicitly advises users to either re-run with focused parameters or switch to `token-burner` mode. This guidance is reinforced in the project documentation:

- **SKILL.md** (lines 129-130): Documents the long-video warning and recommended actions
- **README.md** (lines 30-33): Explains the frame budget mechanics and sparse-scan mitigation

The documentation states: *"Long-video accuracy depends on the detail mode. On capped modes (`efficient`, default `balanced`) coverage thins out past ~10 minutes—the script prints a 'sparse scan' warning and you're better off re-running focused with `--start`/`--end`. `token-burner` lifts the cap and keeps every scene-change frame across the full video."*

## Practical Implementation Examples

The following commands demonstrate the three approaches to handling long videos:

```bash

# 1. Default run (balanced detail) on a 12-minute video → sparse-scan warning

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/longvideo"

# 2. Re-run focused on the 2-minute to 3-minute segment (denser coverage)

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/longvideo" \
    --start 2:00 --end 3:00

# 3. Use token-burner to keep every scene-change frame (no warning)

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/longvideo" \
    --detail token-burner

```

Replace `SKILL_DIR` with the absolute path of the `skills/watch` folder as described in the SKILL contract.

## Summary

- **Automatic Detection**: The script in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) automatically detects videos exceeding 10 minutes and warns when using capped detail modes (`efficient` or `balanced`).
- **Root Cause**: Sparse coverage occurs because fixed frame budgets (50 or 100 frames) spread thin across long durations, creating gaps between sampled timestamps.
- **Focused Solution**: The `--start` and `--end` parameters trigger `auto_fps_focus()` to concentrate the frame budget on specific intervals.
- **Uncapped Solution**: The `token-burner` detail mode removes frame limits entirely, processing every scene-change frame while suppressing the duration warning.
- **Documentation**: Both the warning output and the project's [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) and [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md) files provide clear remediation guidance.

## Frequently Asked Questions

### At what exact duration does Claude-Video warn about sparse coverage?

The warning triggers when `full_duration > 600` seconds (10 minutes). This check occurs in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) and only applies when the video is not in focused mode and the detail level is neither `transcript` nor `token-burner`.

### Why does the token-burner mode suppress the long-video warning?

The `token-burner` mode suppresses the warning because it removes the frame cap entirely. Unlike `efficient` (50 frames) or `balanced` (100 frames), this mode preserves every scene-change frame regardless of video length, eliminating the sparse coverage problem that the warning is designed to address.

### How does focused mode improve frame density?

Focused mode utilizes the `auto_fps_focus()` function in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) to calculate a higher effective frames-per-second rate for the specified time window. By limiting the scope to a `--start` and `--end` range, the fixed frame budget concentrates on a shorter duration, resulting in more frequent sampling and denser visual coverage.

### Where is the warning logic documented in the repository?

The warning implementation is documented in the source code at [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) lines 326-334. User-facing documentation appears in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) (lines 129-130) and the root [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md) (lines 30-33), both explaining the sparse-scan behavior and recommended remediation strategies.