# Claude Video Sparse Scan Warning: Causes and Solutions

> Resolve the Claude Video sparse scan warning. Learn why long videos trigger this error and discover solutions to ensure smooth video processing with the watch skill.

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

---

**The "sparse scan" warning appears when the `watch` skill in `bradautomates/claude-video` processes videos longer than approximately 10 minutes using capped detail modes (`efficient` or `balanced`), forcing widely spaced frame sampling after hitting the 50 or 100 frame limit.**

The `claude-video` repository provides a `watch` skill that extracts video frames to supply Claude with visual context. Because each frame converts to a JPEG that consumes tokens, the system imposes strict frame budgets to control costs. When these budgets cap the frame count for long videos, the script emits a **sparse scan warning** to alert you that the sampling has become thin.

## What Causes the Sparse Scan Warning

The warning triggers due to a combination of video duration and the selected **detail mode**. 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 calculates a frame budget based on how long the video runs. For videos exceeding roughly 10 minutes, the budget becomes constrained by the hard caps defined in the detail mode settings documented in [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md) (lines 205-209).

### Frame Budget Caps by Detail Mode

The `watch` skill offers three detail modes that determine how many frames the system extracts:

- **`efficient`**: Caps at **50 frames**
- **`balanced`**: Caps at **100 frames**
- **`token-burner`**: **Uncapped**, extracts every scene-change frame regardless of duration

When you process a long video using `efficient` or `balanced` mode, the script stops adding frames once it reaches the respective cap. The remaining duration must be covered by sparsely spaced frames, triggering the warning described in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) (lines 130-166).

### The Token Cost Constraint

Each extracted frame converts to a JPEG image that feeds directly into Claude's context window. As noted in the repository documentation, longer videos would generate prohibitive token costs without these caps, so the system favors a "sparse scan" over an exhaustive one when budgets are exhausted.

## How to Avoid the Sparse Scan Warning

You can eliminate or suppress the warning through four distinct strategies, each targeting different workflow requirements.

### Use Token-Burner Mode (Uncapped)

Switching to **`token-burner`** detail mode removes the frame cap entirely. As documented in [`CHANGELOG.md`](https://github.com/bradautomates/claude-video/blob/main/CHANGELOG.md) (lines 20-21), this mode is explicitly exempt from the sparse-scan warning because it retains every scene-change frame regardless of video length.

```bash
python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/abc123" --detail token-burner

```

This approach provides maximum visual fidelity but consumes significantly more tokens.

### Focus on Specific Time Segments

Rather than scanning the entire video, use **`--start`** and **`--end`** flags to define a focused window. As explained in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md), forcing a "focused" budget allocates frames densely within the selected segment rather than sparsely across the full duration.

```bash
python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/longvideo" \
    --start 02:15 --end 02:45

```

This method avoids the warning by reducing the sampled duration to fit comfortably within the frame budget.

### Adjust Maximum Frame Limits

You can manually override the default caps using the **`--max-frames`** parameter in [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py). Setting a lower limit prevents the script from attempting to fill a full-video budget that would trigger the warning.

```bash
python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/longvideo" \
    --detail balanced --max-frames 60

```

Note that this reduces the total frames analyzed but maintains predictable density.

### Accept the Informational Warning

If you require a full-video overview and accept the trade-off of sparse sampling, simply proceed with the default settings. The warning is informational only and does not halt execution.

## Technical Implementation Details

The warning logic resides in the frame-selection module at [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), while the entry point at [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) parses arguments and computes the budget. The specific warning text and guidance appear in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md), which advises asking users for specific sections before "burning tokens on a sparse scan" when handling long videos.

## Summary

- The **sparse scan warning** appears when videos exceed ~10 minutes and hit the frame caps of `efficient` (50 frames) or `balanced` (100 frames) modes.
- **Token-burner mode** bypasses the warning entirely by removing frame caps.
- **Time segmentation** (`--start`/`--end`) allows dense sampling of specific portions without triggering the warning.
- **Manual frame limits** (`--max-frames`) provide fine-grained control over the trade-off between coverage and density.
- The warning is generated by budget calculation logic in [`scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/frames.py) and surfaced through [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py).

## Frequently Asked Questions

### Why does the sparse scan warning only appear for long videos?

Videos shorter than 10 minutes typically fit within the frame budgets of `efficient` or `balanced` modes without requiring sparse sampling. Once duration exceeds this threshold, the calculated budget exceeds the detail mode cap, forcing the script to space frames widely across the remaining timeline according to the logic in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).

### Is the sparse scan warning an error that stops processing?

No, the warning is purely informational. As implemented in `bradautomates/claude-video`, it alerts you that the analysis will use thin sampling, but the script continues executing and passes the available frames to Claude.

### How does token-burner mode avoid the sparse scan warning?

The `token-burner` mode removes the frame cap entirely, allowing the script to extract every scene-change frame regardless of video length. Since no artificial limit forces sparse spacing, the warning condition never triggers, though token consumption increases significantly.

### Can I eliminate the warning without increasing token usage?

Yes, by using **`--start`** and **`--end`** to analyze only a specific segment of the video. This reduces the temporal scope so the frame budget can sample densely within the window without hitting the sparse-scan threshold, keeping token costs controlled while maintaining analytical density.