How to Process Videos Longer Than 10 Minutes Using the Claude-Video Watch Skill

To effectively handle videos longer than 10 minutes in Claude-Video, use the --start and --end flags to limit analysis to specific segments, enable --detail token-burner mode to remove frame caps entirely, or switch to --detail transcript for text-only processing.

The bradautomates/claude-video repository provides a watch skill designed to analyze video content through frame extraction and transcription. When processing videos longer than 10 minutes, the tool implements specific architectural safeguards to prevent sparse frame sampling while managing API token costs.

Understanding the 10-Minute Warning System

The watch skill automatically detects when video duration exceeds the 600-second threshold. In skills/watch/scripts/watch.py at lines 26-33, the code compares full_duration against 600 seconds and emits a warning if the video exceeds 10 minutes while using detail levels other than transcript or token-burner. This warning alerts users that the default frame cap may result in overly sparse sampling across the timeline.

The warning system triggers because config.py defines default frame caps (often 100 frames) that automatically calculate a reduced frame-per-second rate for long durations. For a 15-minute video, this might result in one frame every 9 seconds, potentially missing important visual context.

Strategy 1: Zoom Into Specific Time Ranges

The most efficient method for handling long videos is limiting the effective duration using time-range selectors. The watch.py entry point accepts --start and --end arguments (defined at lines 49-50) that restrict analysis to a specific window, allowing the auto_fps_focus() function in skills/watch/scripts/frames.py to maintain higher frame density within that slice.

When you specify a range, the tool calls auto_fps_focus() rather than auto_fps(), calculating frame rates based only on the selected duration rather than the full video length. This produces more meaningful visual context for the specific segment of interest.

Process a 20-minute video, analyzing only the critical middle section:

watch \
  "https://www.youtube.com/watch?v=example" \
  --detail balanced \
  --start 00:08:00 \
  --end 00:12:00 \
  --resolution 640

Strategy 2: Remove Frame Caps with Token-Burner Mode

For comprehensive visual analysis of entire long videos, bypass the default frame caps using the token-burner detail level. In watch.py at lines 95-99, the code calculates detail_budget = max_frames - len(cue_frames), but when detail == "token-burner", this cap is removed entirely, allowing extraction of every scene-change frame regardless of duration.

Alternatively, manually raise the cap using --max-frames while keeping the balanced or efficient detail levels. This increases the budget available to the auto-fps algorithm without removing limits entirely.

Analyze a full 30-minute video with maximum frame extraction:

watch \
  "https://www.youtube.com/watch?v=example" \
  --detail token-burner \
  --resolution 512

Strategy 3: Transcript-Only Analysis

When visual frame extraction is unnecessary, use the transcript detail level to process videos longer than 10 minutes without triggering frame-related warnings. This mode utilizes skills/watch/scripts/transcribe.py to parse existing VTT subtitles, or falls back to skills/watch/scripts/whisper.py to invoke the Groq or OpenAI Whisper API (requires API key configuration via setup.py).

This approach consumes significantly fewer tokens than image-based analysis while providing complete textual context for long-form content.

Generate a full transcript for a 45-minute lecture:

watch \
  "https://www.youtube.com/watch?v=example" \
  --detail transcript \
  --whisper groq

How Frame Extraction Scales with Duration

The skills/watch/scripts/frames.py module implements two primary algorithms for frame rate calculation:

• auto_fps() – Calculates frame distribution across the full video duration to stay under max_frames defined in config.py
• auto_fps_focus() – Calculates frame distribution for a specific time range, enabling denser sampling when using --start and --end flags

Both functions attempt to distribute frames evenly while respecting the detail_budget constraints. For long videos, the default balanced detail level (typically capped at 100 frames) automatically reduces the sampling rate to cover the entire timeline, which is why the 10-minute warning recommends either zooming in or increasing the budget.

Summary

• The 10-minute threshold triggers at 600 seconds in watch.py, warning users about potential sparse frame sampling
• Time-range selection (--start and --end) limits effective duration, allowing auto_fps_focus() to maintain higher frame density within specific segments
• Token-burner mode removes frame caps entirely, extracting every scene-change frame regardless of video length
• Transcript mode bypasses frame extraction for long videos, using transcribe.py or whisper.py for text-only analysis
• Frame budgets are calculated as max_frames - len(cue_frames) unless overridden by detail level or --max-frames argument

Frequently Asked Questions

What happens if I process a 30-minute video without any special flags?

The tool will emit a warning at lines 26-33 of watch.py indicating that the video exceeds 600 seconds. It will then apply the default frame cap (typically 100 frames), resulting in approximately one frame every 18 seconds, which may miss fine-grained visual details. The warning suggests using --start/--end ranges or --detail token-burner to improve coverage.

How does the auto-fps calculation work for long videos?

The auto_fps() function in frames.py divides the target frame cap by the video duration to determine sampling intervals. For videos longer than 10 minutes using balanced detail, this often results in sub-1fps rates. When using --start and --end flags, auto_fps_focus() recalculates based on the shortened duration, effectively increasing the frame rate for that specific window.

Can I use Whisper transcription for videos longer than 10 minutes?

Yes, the whisper.py module handles long videos through API-based transcription. Configure your Groq or OpenAI API key using setup.py, then add the --whisper flag (e.g., --whisper groq). This functions independently of frame extraction and works efficiently regardless of video duration, though API costs scale with audio length.

What's the difference between balanced and token-burner detail levels?

Balanced applies a strict frame cap (around 100 frames) to manage token costs, forcing sparse sampling for long videos. Token-burner removes this cap entirely at lines 31-34 of watch.py, allowing the frame extractor to capture every scene-change frame. Use balanced for cost-efficient overviews and token-burner when visual completeness is critical, accepting higher token consumption.

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