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

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 (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:

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 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, 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

$ 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

$ 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

$ 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 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 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, frame logic in skills/watch/scripts/frames.py, user guidance in skills/watch/SKILL.md and 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.

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

No. The warning is hardcoded in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}