Claude Video Sparse Scan Warning: Causes and Solutions

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, 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 (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 (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 (lines 20-21), this mode is explicitly exempt from the sparse-scan warning because it retains every scene-change frame regardless of video length.

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, forcing a "focused" budget allocates frames densely within the selected segment rather than sparsely across the full duration.

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. Setting a lower limit prevents the script from attempting to fill a full-video budget that would trigger the warning.

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, while the entry point at skills/watch/scripts/watch.py parses arguments and computes the budget. The specific warning text and guidance appear in 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 and surfaced through 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.

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.

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