Claude-Video Sparse Scan Warning: Why Long Videos Trigger It and How to Fix It

TLDR: The sparse scan warning appears when claude-video processes videos longer than 10 minutes under default settings, indicating that the fixed frame budget is spread thin across the entire duration to prevent excessive token consumption.

The claude-video repository provides AI-powered video analysis by extracting representative frames for Claude to process. When you encounter the sparse scan warning, it signals that the automatic frame-rate reduction has kicked in to manage costs on lengthy content, specifically when the video exceeds approximately 10 minutes without time-range restrictions.

What Triggers the Sparse Scan Warning

The warning fires from skills/watch/scripts/watch.py when two conditions align: the video duration exceeds 600 seconds (10 minutes), and the detail mode is neither transcript nor token-burner. Lines 26-33 in watch.py implement this check, comparing the total runtime against the threshold before emitting the alert.

When these conditions are met, the script knows that the frame budget—capped at 100 frames by default—will yield low frame-density across the full timeline, potentially missing important visual details.

How Frame Budgeting Works in frames.py

The underlying logic resides in skills/watch/scripts/frames.py, specifically within the auto_fps function (lines 22-36). This function calculates the target frames per second based on video length:

• For videos under 600 seconds, it selects a higher frame density appropriate for the content.
• For durations exceeding 600 seconds, it caps extraction at max_frames (default 100), distributing these frames evenly across the entire runtime.

This automatic throttling creates the sparse coverage that triggers the warning in the main script.

Solutions to Eliminate the Sparse Scan Warning

You have two primary methods to resolve the warning, both documented in skills/watch/SKILL.md (lines 129-136) and the README (lines 55-66).

Focus on a Specific Segment

Use the --start and --end parameters to restrict processing to a relevant portion of the video. This invokes a focused-mode budget that applies the full frame allowance to a shorter duration, increasing density and eliminating the warning:

$ claude-video watch "https://example.com/long-video.mp4" --start 00:02:15 --end 00:02:45

Enable Token-Burner Mode

Switch to --detail token-burner to retain every scene-change frame regardless of duration. This prevents the sparse scan logic from activating but significantly increases token consumption:

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

Why This Safety Mechanism Exists

According to the claude-video source code, this warning serves as a cost-control safeguard. Without it, users might unknowingly process 30-minute videos with only 100 frames scattered sparsely throughout, resulting in poor AI comprehension while still incurring token charges. The warning explicitly suggests either narrowing the temporal scope or accepting higher costs for complete coverage.

Summary

• The sparse scan warning activates for videos exceeding 600 seconds (10 minutes) when using default or balanced detail modes.
• It originates in watch.py (lines 26-33) based on logic from auto_fps in frames.py (lines 22-36).
• Resolve it by using time-range constraints (--start/--end) or switching to --detail token-burner.
• The warning protects users from poor analysis quality due to insufficient frame density on long videos.

Frequently Asked Questions

At what exact duration does the sparse scan warning appear?

The warning triggers when video length exceeds 600 seconds (10 minutes), as defined in the duration check within skills/watch/scripts/watch.py.

Does the sparse scan warning mean frames are being skipped?

No, it means the frame budget is spread evenly across the entire video duration, resulting in low frame-density. The auto_fps function in frames.py reduces the extraction rate rather than skipping intervals, creating temporal gaps between captured frames.

How can I maintain high frame density on a long video?

Use the --detail token-burner flag to disable the frame cap, or narrow your analysis window using --start and --end timestamps to focus the default frame budget on a specific segment.

Will the warning appear if I only want a transcript?

No. The warning is suppressed when using --detail transcript mode, as this mode does not rely on frame extraction for visual analysis, bypassing the frame-density concerns entirely.

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