When Does Claude-Video Issue a Sparse Scan Warning for Long Videos?

The watch skill emits a sparse scan warning to stderr when a video exceeds 10 minutes (600 seconds) and the selected detail mode is neither transcript nor token-burner, as implemented in skills/watch/scripts/watch.py lines 26-33.

The claude-video repository by bradautomates provides a watch skill for AI-powered video analysis with configurable frame extraction. Understanding the sparse scan warning for long videos helps developers optimize their commands to ensure adequate visual coverage or suppress unnecessary alerts.

The 600-Second Threshold in watch.py

The warning logic resides in skills/watch/scripts/watch.py at lines 26-33. After retrieving video metadata, the system compares the total duration against a hardcoded threshold of 600 seconds (10 minutes).

When the duration exceeds this limit, the code examines the current detail parameter. Only two modes suppress the warning entirely: transcript and token-burner. All other detail configurations trigger the stderr message alerting users that frame coverage will be sparse.

Why the 10-Minute Limit Exists

This threshold represents the point where default frame sampling strategies become too sparse for reliable scene analysis. According to comments in skills/watch/scripts/frames.py, clips with very few decoded keyframes provide insufficient visual coverage, which the warning system flags to prevent analysis gaps.

Detail Modes That Suppress the Warning

The warning system respects specific detail configurations that either eliminate frame extraction or maximize it:

• transcript — Extracts only audio transcription data with no visual frames, rendering the sparse scan warning irrelevant.
• token-burner — Processes every scene-change frame without caps, ensuring comprehensive coverage regardless of video length.

How to Avoid the Sparse Scan Warning

When processing videos longer than 10 minutes, you have three primary strategies to prevent or address the warning.

Use Token-Burner Detail Mode

Override the default detail level to process all keyframes without duration-based sampling:

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

Focus on a Specific Segment

Use --start and --end parameters to reduce the effective duration below 600 seconds:

watch "https://example.com/long-video.mp4" --start 00:03:00 --end 00:05:00

Switch to Transcript-Only Analysis

For audio-focused processing without visual frames:

watch "https://example.com/long-video.mp4" --detail transcript

Configuration and Supporting Files

The warning system relies on configuration defaults defined in skills/watch/scripts/config.py, which establishes the frame caps and detail level behaviors that determine when sparse coverage occurs. While watch.py contains the actual warning emission logic, skills/watch/scripts/frames.py provides the conceptual foundation regarding keyframe density that justifies the 10-minute threshold.

Code Examples

Default Detail on a 12-Minute Video

watch "https://example.com/long-video.mp4"

This command emits the following to stderr:

**Warning:** This is a 12-minute video. Frame coverage is sparse at this length
  under `balanced` detail — its cap spreads thin across the full clip...

Same Video with Token-Burner Detail

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

No warning appears because every scene-change frame is preserved.

Two-Minute Segment Extraction

watch "https://example.com/long-video.mp4" --start 00:03:00 --end 00:05:00

The warning is suppressed because the effective duration is under 10 minutes.

Transcript-Only Processing

watch "https://example.com/long-video.mp4" --detail transcript

No frames are extracted, so the sparse scan warning does not apply.

Summary

• The sparse scan warning triggers when video duration exceeds 600 seconds (10 minutes) and the detail mode is neither transcript nor token-burner.
• The logic resides in skills/watch/scripts/watch.py at lines 26-33.
• Exempt modes: transcript (no frames) and token-burner (all frames).
• Avoid the warning by using time-range arguments (--start/--end), switching to token-burner detail, or using transcript mode.
• Configuration defaults in skills/watch/scripts/config.py define the frame caps that make the warning necessary.

Frequently Asked Questions

What is the exact duration threshold for the sparse scan warning?

The warning triggers at 600 seconds (10 minutes) of total video duration. This threshold is hardcoded in skills/watch/scripts/watch.py and represents the point where standard detail modes cannot maintain adequate frame coverage across the entire clip.

Does the transcript detail mode ever trigger a sparse scan warning?

No. The transcript detail mode is explicitly exempt from the warning because it performs audio transcription without extracting visual frames. Since no frame sampling occurs, the concept of sparse coverage does not apply.

How can I process a 15-minute video without seeing the warning?

You have three options: use --detail token-burner to process all scene-change frames regardless of length, use --detail transcript to skip visual analysis entirely, or specify a --start and --end time range that keeps the segment under 10 minutes.

Where is the sparse scan warning logic implemented in the source code?

The warning emission logic is located in skills/watch/scripts/watch.py at lines 26-33. Supporting configuration for detail levels and frame caps resides in skills/watch/scripts/config.py, while skills/watch/scripts/frames.py contains comments explaining the "too sparse" concept regarding keyframe coverage.

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