How to Handle Videos Longer Than 10 Minutes with Claude Video

When processing videos longer than 10 minutes, Claude Video automatically reduces frame density to stay within token limits, but you can use focused mode with --start and --end flags for higher detail on specific segments or switch to token-burner mode to increase the frame budget.

Claude Video, part of the bradautomates/claude-video repository, can analyze videos of any length, but its default frame-budget strategy is optimized for shorter clips. When a video exceeds the approximate 10-minute threshold, the tool warns you and lowers the frame extraction rate to prevent excessive token consumption. Understanding how to adjust the frame budget or focus on specific time windows ensures you get dense visual analysis without hitting limits.

Understanding the Default Frame Budget Constraints

The default configuration in skills/watch/SKILL.md (lines 14-22) establishes recommended limits for "best accuracy" when processing videos under 10 minutes. When you process longer content, the orchestration script in skills/watch/scripts/watch.py detects the duration and automatically adjusts the sampling strategy. Specifically, lines 26-34 generate a warning that recommends using focused mode for long videos to maintain higher frame density where it matters.

Method 1: Focused Segment Analysis

How Focus Mode Works

Using the --start and --end flags puts the tool into focused mode, which treats your specified window as a standalone video. According to the skill contract in SKILL.md (lines 54-66), this mode allows the auto_fps_focus logic in skills/watch/scripts/frames.py to calculate frame rates using the shortened duration rather than the full video length. This yields a denser visual sample (up to 2 fps) for your target segment while staying within token budgets.

Command Examples

Zoom into a specific 2-minute segment of a longer video:

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

Combine focused scanning with a custom frame limit for precise control:

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/longvideo" \
  --start 10:00 --end 12:30 --max-frames 80

Method 2: Increase the Frame Budget

Using Token-Burner Mode

For comprehensive analysis of long videos where you need full scene coverage, set --detail to token-burner. This mode removes the frame cap and processes all scene-change frames, regardless of video length. Be aware that watch.py (lines 19-24) warns when outputs exceed 250 frames due to the high token cost.

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

Adjusting Maximum Frame Limits

Alternatively, stay in balanced mode but raise the ceiling with --max-frames. This gives you granular control over the trade-off between detail and token usage without entering full token-burner mode.

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/longvideo" \
  --max-frames 200

Technical Implementation Details

The frame extraction logic resides in skills/watch/scripts/frames.py, which implements auto_fps and auto_fps_focus functions to dynamically compute sampling rates based on duration and detail caps. The setup.py script handles pre-flight binary checks before processing begins. Together, these components ensure that long videos don't silently fail but instead apply predictable degradation strategies unless you explicitly override them with focused windows or increased budgets.

Summary

• Claude Video automatically reduces frame density for videos over 10 minutes to prevent token overflow, as documented in skills/watch/SKILL.md
• Use --start and --end flags to enter focused mode, which applies higher frame rates (≤2 fps) to specific segments instead of the full video
• Switch to token-burner detail mode or raise --max-frames to process all scene changes regardless of video length
• Watch for warnings in skills/watch/scripts/watch.py when exceeding 250 frames, as this indicates high token consumption
• The auto_fps_focus function in skills/watch/scripts/frames.py calculates optimal sampling when using time window constraints

Frequently Asked Questions

Why does Claude Video reduce frame density for long videos?

Claude Video implements automatic frame reduction to stay within token limits. When a video exceeds approximately 10 minutes, the script in skills/watch/scripts/watch.py (lines 26-34) warns you and lowers the extraction rate to prevent consuming excessive image tokens during analysis.

What is the maximum frame rate in focused mode?

In focused mode using --start and --end flags, the tool calculates frame rates based on the shortened duration, allowing densities up to 2 fps as implemented in skills/watch/scripts/frames.py. This gives you a denser visual sample for the specific segment you're analyzing rather than spreading the budget across the entire timeline.

How many frames trigger a token warning in Claude Video?

According to skills/watch/scripts/watch.py (lines 19-24), the script warns you when the output exceeds 250 frames. This typically occurs when using token-burner mode on long videos or when setting a very high --max-frames value that approaches or exceeds this threshold.

Can I process a 30-minute video at full detail?

Yes, but you must explicitly configure the frame budget. Either use the token-burner detail mode to capture all scene changes across the full duration, or break the video into focused segments using --start and --end timestamps to analyze specific portions at higher density. Without these adjustments, the default balanced mode will significantly reduce frame density to manage token costs.

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