# Claude-Video Sparse Scan Warning: Why Long Videos Trigger It and How to Fix It

> Understand the Claude-Video sparse scan warning for long videos. Learn why it occurs and discover solutions to optimize processing and avoid token overload. Fix sparse scan issues now.

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

---

**TLDR:** The sparse scan warning appears when claude-video processes videos longer than 10 minutes under default settings, indicating that the fixed frame budget is spread thin across the entire duration to prevent excessive token consumption.

The claude-video repository provides AI-powered video analysis by extracting representative frames for Claude to process. When you encounter the **sparse scan warning**, it signals that the automatic frame-rate reduction has kicked in to manage costs on lengthy content, specifically when the video exceeds approximately 10 minutes without time-range restrictions.

## What Triggers the Sparse Scan Warning

The warning fires from [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) when two conditions align: the video duration exceeds 600 seconds (10 minutes), and the detail mode is neither `transcript` nor `token-burner`. Lines 26-33 in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) implement this check, comparing the total runtime against the threshold before emitting the alert.

When these conditions are met, the script knows that the frame budget—capped at 100 frames by default—will yield low frame-density across the full timeline, potentially missing important visual details.

## How Frame Budgeting Works in frames.py

The underlying logic resides in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), specifically within the `auto_fps` function (lines 22-36). This function calculates the target frames per second based on video length:

- For videos under 600 seconds, it selects a higher frame density appropriate for the content.
- For durations exceeding 600 seconds, it caps extraction at `max_frames` (default 100), distributing these frames evenly across the entire runtime.

This automatic throttling creates the sparse coverage that triggers the warning in the main script.

## Solutions to Eliminate the Sparse Scan Warning

You have two primary methods to resolve the warning, both documented in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) (lines 129-136) and the README (lines 55-66).

**Focus on a Specific Segment**

Use the `--start` and `--end` parameters to restrict processing to a relevant portion of the video. This invokes a focused-mode budget that applies the full frame allowance to a shorter duration, increasing density and eliminating the warning:

```bash
$ claude-video watch "https://example.com/long-video.mp4" --start 00:02:15 --end 00:02:45

```

**Enable Token-Burner Mode**

Switch to `--detail token-burner` to retain every scene-change frame regardless of duration. This prevents the sparse scan logic from activating but significantly increases token consumption:

```bash
$ claude-video watch "https://example.com/long-video.mp4" --detail token-burner

```

## Why This Safety Mechanism Exists

According to the claude-video source code, this warning serves as a cost-control safeguard. Without it, users might unknowingly process 30-minute videos with only 100 frames scattered sparsely throughout, resulting in poor AI comprehension while still incurring token charges. The warning explicitly suggests either narrowing the temporal scope or accepting higher costs for complete coverage.

## Summary

- The sparse scan warning activates for videos exceeding 600 seconds (10 minutes) when using default or balanced detail modes.
- It originates in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) (lines 26-33) based on logic from `auto_fps` in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) (lines 22-36).
- Resolve it by using time-range constraints (`--start`/`--end`) or switching to `--detail token-burner`.
- The warning protects users from poor analysis quality due to insufficient frame density on long videos.

## Frequently Asked Questions

### At what exact duration does the sparse scan warning appear?

The warning triggers when video length exceeds 600 seconds (10 minutes), as defined in the duration check within [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).

### Does the sparse scan warning mean frames are being skipped?

No, it means the frame budget is spread evenly across the entire video duration, resulting in low frame-density. The `auto_fps` function in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) reduces the extraction rate rather than skipping intervals, creating temporal gaps between captured frames.

### How can I maintain high frame density on a long video?

Use the `--detail token-burner` flag to disable the frame cap, or narrow your analysis window using `--start` and `--end` timestamps to focus the default frame budget on a specific segment.

### Will the warning appear if I only want a transcript?

No. The warning is suppressed when using `--detail transcript` mode, as this mode does not rely on frame extraction for visual analysis, bypassing the frame-density concerns entirely.