# Sparse Scan Warnings in Claude-Video: When to Re-Run with Focused Ranges for Long Videos

> Understand sparse scan warnings in Claude-Video. Learn when to re-run with focused ranges for long videos to ensure reliable frame coverage and detailed analysis.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: performance
- Published: 2026-08-03

---

**A sparse scan warning appears when the `watch` script analyzes videos longer than approximately 10 minutes using default detail modes, indicating that frame coverage has become too thin to capture reliable visual detail.**

The **sparse scan warning** is a critical alert emitted by the `claude-video` repository's `watch` script. It signals that the default frame extraction strategy—designed to balance cost and coverage—has spread too thin across a lengthy video duration, potentially missing important visual information. Understanding when this warning triggers and how to respond with focused time ranges ensures accurate video analysis without wasted tokens.

## What Triggers a Sparse Scan Warning?

The warning fires in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 26-34) when two conditions align:

- **Video duration exceeds ~10 minutes**
- **Detail mode is `efficient` or `balanced` (the defaults)**

These modes enforce a hard cap on total frames extracted—approximately 250 frames. For a 15-minute video, that cap distributes to roughly 0.3 frames per second. The script detects this low density and prints a warning:

```bash
Warning: This is a 15-minute video. Frame coverage is sparse at this length 
under `balanced` 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.

```

The core issue is **mathematical inevitability**: a fixed frame budget divided by extended duration yields sparse sampling. Visual transitions, text overlays, or rapid scene changes occurring between sampled frames become invisible to the model.

## Why Re-Run with Focused Ranges?

Restricting analysis to a specific segment via `--start` and `--end` parameters transforms three key metrics:

- **Higher frame density** – The ~250 frame cap applies only to your selected window. A 30-second segment achieves up to 2 fps, delivering rich visual context rather than scattered snapshots.
- **Lower token consumption** – Fewer frames means fewer image tokens in your prompt, directly reducing API costs according to the repository's documented token-cost model.
- **Improved answer quality** – The model reasons over contiguous, detailed frames from your region of interest instead of guessing from sparse, disconnected samples.

The [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file explicitly recommends this workflow: for long videos, "ask whether they want a specific section" before processing.

## Alternative: The Token-Burner Detail Mode

If you genuinely need full-duration coverage without sparsity, the **`token-burner`** detail mode bypasses the frame cap entirely. As implemented in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), this mode retains every detected scene-change frame regardless of video length.

Trade-offs are significant:

| Approach | Frame Density | Token Cost | Use Case |
|----------|---------------|------------|----------|
| Default (`balanced`) | Low on long videos | Moderate | Quick overview, short clips |
| Focused range | High in segment | Low | Deep analysis of specific period |
| `token-burner` | Maximum everywhere | Very high | Critical full-video review |

## Working with Sparse Scan Warnings: Code Examples

### Scenario 1: Default Run Triggering the Warning

```bash
$ watch https://example.com/long-video.mp4
> Warning: This is a 12-minute video. Frame coverage is sparse ...

```

The script completes but warns you that results may be unreliable for detailed questions.

### Scenario 2: Focused Segment Analysis

```bash
$ watch https://example.com/long-video.mp4 --start 00:02:30 --end 00:03:00

```

This 30-second window receives the full frame budget, yielding dense coverage suitable for reading text, analyzing motion, or identifying objects.

### Scenario 3: Full Coverage Without Sparsity

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

```

No warning appears. All scene-change frames are preserved and sent to the model.

## How Frame Caps Work Under the Hood

The [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) script implements **auto-fps logic** that calculates extraction frequency from duration and detail mode. For `balanced` mode on long videos, this automatically reduces fps to stay under the cap—directly causing the sparse sampling that triggers the warning.

The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) warning logic (lines 26-34) checks duration against mode, then prints guidance matching the repository's documented best practices.

## Summary

- **Sparse scan warnings** appear when default modes face long videos, indicating unreliable frame density
- **Re-run with `--start` and `--end`** to concentrate the frame budget on your actual analysis target
- **`token-burner` mode** eliminates sparsity at substantial token cost for cases requiring full-duration coverage
- **File locations**: Warning generation in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), frame logic in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), user guidance in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) and [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md)

## Frequently Asked Questions

### What duration triggers a sparse scan warning?

Videos longer than approximately **10 minutes** trigger the warning when processed with `efficient` or `balanced` detail modes. The exact threshold depends on the specific frame cap and auto-fps calculations in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py).

### Can I disable sparse scan warnings without using token-burner mode?

No. The warning is hardcoded in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) (lines 26-34) as a safeguard. You can only avoid it by either limiting duration with `--start`/`--end` or switching to `token-burner` mode, which inherently prevents sparse sampling by removing the frame cap.

### How precise should my `--start` and `--end` timestamps be?

Use **standard `HH:MM:SS` format**. The parser accepts partial precision (e.g., `00:02:30` or `2:30`), but explicit formatting ensures unambiguous interpretation across different locales and shell environments.

### Does focused range selection affect scene detection quality?

No. The same scene-change detection algorithm runs regardless of range. The difference is purely quantitative: **more frames per second** survive the cap, providing richer context for the model's reasoning without altering how keyframes are identified.