How Claude-Video Warns About Long Videos and Handles Sparse Frame Coverage

Claude-Video emits an explicit warning when processing videos longer than 10 minutes under capped detail modes, and mitigates sparse coverage by offering focused time windows or the uncapped token-burner detail level.

The bradautomates/claude-video repository provides a Python-based workflow for analyzing video content through frame extraction and transcription. When processing long videos exceeding 10 minutes, the tool implements specific safeguards against sparse frame coverage that could compromise analysis quality.

The 10-Minute Threshold and Warning System

Trigger Conditions in watch.py

The warning logic resides in skills/watch/scripts/watch.py at lines 326-334. The script evaluates three conditions before emitting the alert:

• The video is not running in focused mode (not focused)
• Total duration exceeds 600 seconds (full_duration > 600)
• Current detail mode applies a frame cap (detail not in "transcript" or "token-burner")

When these conditions are met, the script calculates the minute count and prints a formatted warning:

if not focused and full_duration > 600 and detail not in ("transcript", "token-burner"):
    mins = int(full_duration // 60)
    print()
    print(
        f"> **Warning:** This is a {mins}-minute video. Frame coverage is sparse at this length "
        f"under `{detail}` detail — its cap spreads thin across the full clip. For better results, "
        "re-run with `--start HH:MM:SS --end HH:MM:SS` to zoom into a section, or use "
        "`--detail token-burner` to keep every scene‑change frame across the whole video."
    )

Understanding the Sparse Scan Warning

In the default capped detail modes—efficient (50 frames) and balanced (100 frames)—the frame budget is shared across the entire video duration. When a video exceeds 10 minutes, this distribution causes timestamps to become widely spaced, creating what the tool calls a "sparse scan." The warning explicitly informs users that the current detail mode’s cap spreads thin across the full clip, potentially missing visual details in long-form content.

Mitigation Strategies for Sparse Coverage

Focused Mode with Time Windows

Supplying --start and --end parameters forces a focused budget that densely populates the requested interval. The script uses auto_fps_focus() (implemented in skills/watch/scripts/frames.py) to compute a higher effective frames-per-second rate for the shorter window, ensuring comprehensive coverage of the specific segment rather than sparse sampling across the whole video.

Token-Burner Detail Mode

Selecting --detail token-burner removes the frame cap entirely, preserving every scene-change frame even for long videos. This mode suppresses the long-video warning because it eliminates the sparse coverage problem by processing all detected scene changes regardless of duration. According to the source code, this is the only detail mode besides transcript that bypasses the 600-second warning check.

User Guidance and Documentation

The warning message explicitly advises users to either re-run with focused parameters or switch to token-burner mode. This guidance is reinforced in the project documentation:

• SKILL.md (lines 129-130): Documents the long-video warning and recommended actions
• README.md (lines 30-33): Explains the frame budget mechanics and sparse-scan mitigation

The documentation states: "Long-video accuracy depends on the detail mode. On capped modes (efficient, default balanced) coverage thins out past ~10 minutes—the script prints a 'sparse scan' warning and you're better off re-running focused with --start/--end. token-burner lifts the cap and keeps every scene-change frame across the full video."

Practical Implementation Examples

The following commands demonstrate the three approaches to handling long videos:

# 1. Default run (balanced detail) on a 12-minute video → sparse-scan warning

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/longvideo"

# 2. Re-run focused on the 2-minute to 3-minute segment (denser coverage)

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/longvideo" \
    --start 2:00 --end 3:00

# 3. Use token-burner to keep every scene-change frame (no warning)

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/longvideo" \
    --detail token-burner

Replace SKILL_DIR with the absolute path of the skills/watch folder as described in the SKILL contract.

Summary

• Automatic Detection: The script in watch.py automatically detects videos exceeding 10 minutes and warns when using capped detail modes (efficient or balanced).
• Root Cause: Sparse coverage occurs because fixed frame budgets (50 or 100 frames) spread thin across long durations, creating gaps between sampled timestamps.
• Focused Solution: The --start and --end parameters trigger auto_fps_focus() to concentrate the frame budget on specific intervals.
• Uncapped Solution: The token-burner detail mode removes frame limits entirely, processing every scene-change frame while suppressing the duration warning.
• Documentation: Both the warning output and the project's SKILL.md and README.md files provide clear remediation guidance.

Frequently Asked Questions

At what exact duration does Claude-Video warn about sparse coverage?

The warning triggers when full_duration > 600 seconds (10 minutes). This check occurs in skills/watch/scripts/watch.py and only applies when the video is not in focused mode and the detail level is neither transcript nor token-burner.

Why does the token-burner mode suppress the long-video warning?

The token-burner mode suppresses the warning because it removes the frame cap entirely. Unlike efficient (50 frames) or balanced (100 frames), this mode preserves every scene-change frame regardless of video length, eliminating the sparse coverage problem that the warning is designed to address.

How does focused mode improve frame density?

Focused mode utilizes the auto_fps_focus() function in frames.py to calculate a higher effective frames-per-second rate for the specified time window. By limiting the scope to a --start and --end range, the fixed frame budget concentrates on a shorter duration, resulting in more frequent sampling and denser visual coverage.

Where is the warning logic documented in the repository?

The warning implementation is documented in the source code at skills/watch/scripts/watch.py lines 326-334. User-facing documentation appears in skills/watch/SKILL.md (lines 129-130) and the root README.md (lines 30-33), both explaining the sparse-scan behavior and recommended remediation strategies.

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