# What the Claude Video Sparse Scan Warning Means and How to Fix It

> Understand the Claude Video sparse scan warning for long videos. Learn how to fix it to ensure accurate answers and optimize your analysis.

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

---

**The "sparse scan" warning appears when Claude Video analyzes videos longer than approximately 10 minutes in `efficient` or `balanced` mode, indicating that the frame budget is spread too thinly across the timeline, which may reduce answer accuracy.**

Claude Video extracts keyframes from videos to send to the language model for analysis. To manage token costs, the tool caps the number of frames extracted in the default `efficient` and `balanced` detail modes. When a video exceeds roughly 10 minutes, this budget gets distributed across such a long duration that only a few frames represent each minute of content, triggering the sparse scan warning.

## What Triggers the Sparse Scan Warning

The warning fires when the frame extraction logic determines that the number of available keyframes significantly exceeds the token budget allowed for the selected detail mode. Rather than analyzing every scene change, the script samples frames at intervals that leave large gaps in the video timeline.

When this condition occurs, the CLI prints a message similar to:

```

⚠️  This is a 12‑minute video. Frame coverage is sparse at this length …

```

This is an intentional safeguard to prevent unexpected token costs, not a processing error.

## Where the Warning Is Generated in the Code

### Frame Budget Logic in frames.py

The density calculation happens in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). This module decodes the video stream, identifies keyframes (scene changes), and determines whether the clip qualifies as "too sparse for key-frame coverage" given the current detail setting.

### Warning Emission in watch.py

The user-facing warning is emitted in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) around line 330. After computing the video duration and the resulting frame budget, the script checks if the coverage will be sparse and logs the warning before proceeding with the API call.

### Documentation References

The behavior is documented in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) under "Long video warning printed" and explained in [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md) within the "Token cost is dominated by frames" section, both detailing why the warning appears and how to remediate it.

## Three Ways to Fix the Sparse Scan Warning

### Run a Focused Scan (--start and --end)

Limit analysis to a specific time segment using the `--start` and `--end` flags. By reducing the total duration, the fixed frame budget concentrates on a smaller window, eliminating sparse coverage.

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

```

Use this approach when your question targets a specific moment, such as "what happens at 2:30?"

### Switch to Token-Burner Mode (--detail token-burner)

Disable the frame cap entirely by selecting `token-burner` mode. This keeps every detected scene-change frame regardless of video length, maximizing coverage at the expense of higher token usage and cost.

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

```

Choose this mode when you require comprehensive visual coverage and accept the associated API costs.

### Use Thorough Detail Mode (--detail thorough)

Increase the frame budget without disabling caps entirely. The `thorough` mode raises the maximum frames per second limit while still respecting overall token constraints, offering a middle ground between `balanced` and `token-burner`.

```bash
claude-video watch https://example.com/long-video.mp4 --detail thorough

```

This option works best when you need better coverage than `efficient` provides but want to avoid the uncapped expense of `token-burner`.

## Code Examples

Here is a comparison of how different invocations handle a 12-minute source file:

```bash

# Default efficient mode - triggers sparse scan warning

claude-video watch https://example.com/long-video.mp4

# Focused 30-second segment - dense coverage, no warning

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

# Uncapped analysis - maximum detail, warning suppressed

claude-video watch https://example.com/long-video.mp4 --detail token-burner

```

## Summary

- The **sparse scan warning** signals that Claude Video's frame budget is spread too thin across a long video (10+ minutes) in `efficient` or `balanced` mode
- The logic resides in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (density calculation) and [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (warning emission)
- **Three fixes** eliminate the warning: focused time ranges (`--start`/`--end`), uncapped `token-burner` mode, or higher-budget `thorough` mode
- The warning is informational, not fatal, but indicates potentially reduced answer accuracy due to missed visual content

## Frequently Asked Questions

### Is the sparse scan warning an error?

No. The warning is an informational message indicating reduced frame density. Processing continues normally, but the model receives fewer visual samples from the video timeline, which may affect accuracy for questions about specific moments.

### How does Claude Video determine if a scan is sparse?

According to the source code in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), the script compares the number of available keyframes (scene changes) against the token budget defined by the detail mode. If the video duration forces the budget to sample fewer than optimal frames per minute, the system classifies the coverage as sparse.

### Will using token-burner mode always eliminate the warning?

Yes. The `token-burner` detail mode removes the frame budget cap entirely, allowing the script to process every detected keyframe regardless of video length. Since there is no artificial constraint creating gaps in coverage, the sparse condition cannot occur.

### Can I disable the sparse scan warning without changing detail modes?

No. The warning is hardcoded in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) as a safeguard against degraded output quality. You must either accept the sparse coverage (and the warning) or change your analysis parameters—through time ranges or detail modes—to increase frame density and automatically suppress the message.