# Why Long Videos Trigger Sparse Scan Warnings in Claude-Video’s Capped Detail Modes > Discover why long videos (>10min) trigger sparse scan warnings in Claude-Video capped detail modes. Learn how frame budgets impact processing for efficient and balanced modes. - Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video) - Tags: internals - Published: 2026-07-14 --- **Long videos trigger sparse scan warnings in Claude-Video when using capped detail modes because fixed frame-budget limits (50 frames for `efficient` and 100 for `balanced`) become spread too thin across durations exceeding 10 minutes.** The `claude-video` repository by bradautomates provides a video analysis framework that extracts frames for Claude’s vision model. When processing videos longer than ten minutes, the script protects token budgets by enforcing strict caps, which results in **sparse scan warnings** when frame density drops too low. Understanding this mechanism requires examining the detail mode implementations in the source code. ## How Frame-Budget Caps Work in Capped Detail Modes Claude-Video offers three detail modes that control frame extraction density: `efficient`, `balanced`, and `token-burner`. The first two operate as **capped detail modes** with strict frame-budget limits to prevent excessive token consumption. According to the [README.md](https://github.com/bradautomates/claude-video/blob/main/README.md#L55-L64), the caps are: - **50 frames** for `efficient` mode - **100 frames** for `balanced` mode (the default) These limits ensure that the total image tokens sent to Claude remain within manageable context window boundaries. When you process a video, [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) calculates the extraction interval by dividing the video duration by the frame budget, implementing what the codebase calls **auto-FPS logic**. ## The 10-Minute Threshold and Frame Distribution The sparse scan warning emerges from simple math. When a video exceeds **10 minutes** in duration, the fixed frame caps force the extractor to sample fewer than 10 frames per minute—or less than one frame every six seconds. For example, a 20-minute video in `balanced` mode spreads 100 frames across 1,200 seconds, yielding one frame every 12 seconds. This coverage is too sparse for Claude to reliably follow visual narratives or scene changes, prompting the system to alert you about insufficient temporal resolution. ## The Warning Mechanism in frames.py The actual warning generation occurs in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), which implements both the frame-budget enforcement and the sparse scan detection. When the calculated frame interval exceeds the density threshold for meaningful video analysis, the script outputs: > “Sparse scan – re‑run focused, or `--detail token‑burner` for full uncapped coverage” This message, documented in [README.md lines 104-107](https://github.com/bradautomates/claude-video/blob/main/README.md#L104-L107), serves as a safety indicator that the capped mode will not provide adequate visual context for comprehensive analysis of the long video. ## Solutions: Focused Scans vs. Uncapped Mode When you encounter the sparse scan warning, the codebase provides two resolution paths that maintain token efficiency or maximize coverage. ### Focused Segment Analysis You can concentrate the frame budget on a specific time window using `--start` and `--end` parameters. This applies the full 50 or 100 frame allowance to only a portion of the video, dramatically increasing frame density. ```bash # Focus on a 30-second segment to get dense frame coverage /watch https://youtu.be/example-video --start 2:15 --end 2:45 --detail balanced ``` By limiting the duration to 30 seconds, the same 100-frame budget now provides one frame every 0.3 seconds instead of one every 12 seconds in a 20-minute video. ### Uncapped Token-Burner Mode Alternatively, use `--detail token-burner` to remove the frame-budget limitation entirely. As noted in [README.md lines 93-95](https://github.com/bradautomates/claude-video/blob/main/README.md#L93-L95), this mode keeps every scene-change frame without artificial caps, eliminating the sparse scan warning at the cost of significantly higher token usage. ```bash # Process every scene-change frame without budget constraints /watch https://youtu.be/example-video --detail token-burner ``` ## Summary - **Sparse scan warnings** in `claude-video` occur when capped detail modes (`efficient` or `balanced`) spread their fixed frame budgets (50 and 100 frames respectively) across videos longer than 10 minutes. - The warning originates in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), which detects when frame density becomes insufficient for reliable visual analysis. - You can resolve the warning by either using **focused time windows** (`--start`/`--end`) to concentrate the frame budget, or switching to **`token-burner` mode** for uncapped frame extraction. - The orchestration logic resides in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), while configuration defaults are handled in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py). ## Frequently Asked Questions ### What exactly triggers the sparse scan warning in claude-video? The warning triggers when the calculated frame interval in a capped detail mode exceeds the threshold for adequate video coverage. Specifically, when videos longer than approximately 10 minutes force the extractor to drop below roughly one frame every 6-12 seconds, [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) generates the sparse scan alert to warn that Claude will receive insufficient visual context. ### How many frames does each detail mode allow? According to the source documentation, `efficient` mode caps extraction at **50 frames**, while `balanced` mode (the default) caps at **100 frames**. Only `token-burner` mode operates without these artificial limits, processing every detected scene change regardless of count. ### Can I avoid the sparse scan warning without using token-burner mode? Yes. You can use the `--start` and `--end` parameters to define a specific time window within the long video. By applying the fixed frame budget to a shorter duration (for example, a 30-second clip instead of a 20-minute video), you increase frame density sufficiently to suppress the warning while maintaining the token efficiency of capped modes. ### Where is the frame budget logic implemented? The frame budget enforcement and sparse scan detection are implemented in **[`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)**. This file contains the auto-FPS calculation logic that determines extraction intervals based on the selected detail mode’s cap. The orchestration layer that coordinates this extraction resides in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), while default configurations are read from [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py).