How Claude Video Handles Long Videos Exceeding the Frame Budget

Claude Video automatically scales down the frame sampling rate and evenly samples frames to stay within a configurable budget, rather than extracting every possible frame from long videos.

When processing lengthy content with the bradautomates/claude-video tool, the system must balance comprehensive visual analysis against token limits and API constraints. Understanding how Claude Video handles long videos exceeding the frame budget helps users optimize their workflow and avoid sparse coverage on extended footage.

Determining the Frame Budget

The process begins in skills/watch/scripts/config.py, where the frame_cap() function (lines 65-73) establishes the maximum number of frames based on the selected detail mode.

• Balanced mode: Caps extraction at 100 frames
• Efficient mode: Limits output to 50 frames
• Token-burner mode: Removes the cap entirely (None), allowing unlimited frame extraction

Calculating Adaptive Frame Rates

Once the budget is established, the system calculates an appropriate sampling rate to fit the video duration within the frame limit. In skills/watch/scripts/frames.py, two functions handle this computation depending on whether you're processing the full video or a specific range.

Full Video Processing

The auto_fps() function (lines 22-38) calculates a frames-per-second value that satisfies the constraint fps × duration ≤ max_frames. It enforces an upper bound of 2 FPS (MAX_FPS) and returns both the calculated FPS and the target frame count.

Focused Range Processing

When users specify start and end timestamps, auto_fps_focus() performs the same calculation but applies it only to the selected duration, allowing higher density sampling within the constrained window while respecting any remaining budget after processing cue frames.

Enforcing the Frame Cap During Extraction

Even with careful FPS calculation, some extraction engines may identify more candidate frames than the budget allows. The _even_sample() function (lines 82-92 in skills/watch/scripts/frames.py) provides the final safeguard by evenly sampling across the candidate set and discarding excess frames to guarantee the final count never exceeds the budget.

The extraction engines—whether extract_keyframes, extract_scene_or_uniform, or simple uniform extraction—receive the computed FPS and max_frames arguments, ensuring all downstream processing respects the configured limits.

Warning Users About Coverage Gaps

For videos exceeding 10 minutes in duration, skills/watch/scripts/watch.py (lines 26-33) emits a warning when the detail mode is not set to "transcript" or "token-burner". This alert notifies users that the frame cap will result in sparse coverage and recommends narrowing the time range or switching to token-burner mode for denser sampling.

Practical Usage Examples

# Default "balanced" mode (max 100 frames) on a long video

watch https://www.youtube.com/watch?v=example

# Focused range on long video (respects remaining budget)

watch https://example.com/video.mp4 --start 00:10:00 --end 00:12:30

# Remove the cap entirely with token-burner mode

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

Summary

• Claude Video derives a configurable frame budget from the selected detail mode (50, 100, or unlimited frames).
• The system automatically reduces FPS via auto_fps() and auto_fps_focus() to ensure fps × duration stays within budget.
• The _even_sample() function in skills/watch/scripts/frames.py provides a final safeguard by evenly distributing frames when candidates exceed the cap.
• Users receive warnings for videos over 10 minutes to alert them to potential sparse coverage.

Frequently Asked Questions

What is the maximum number of frames Claude Video will extract?

By default, Claude Video extracts a maximum of 100 frames in "balanced" mode and 50 frames in "efficient" mode according to the frame_cap() implementation in skills/watch/scripts/config.py. The "token-burner" detail mode removes this cap entirely, allowing unlimited frame extraction depending on the video content.

How does Claude Video decide which frames to keep when exceeding the budget?

When extraction engines identify more candidate frames than the budget allows, the _even_sample() function in skills/watch/scripts/frames.py (lines 82-92) evenly distributes the frame selection across the video timeline. This ensures representative temporal coverage rather than clustering frames at the beginning of the video.

Can I disable the frame cap for long videos?

Yes. Specifying --detail token-burner removes the max_frames limit entirely, causing the engine to extract every scene-change frame without down-sampling. Be aware that this significantly increases token usage and API costs according to the implementation in skills/watch/scripts/config.py.

What happens if I specify a time range on a long video?

When using --start and --end parameters, the auto_fps_focus() function in skills/watch/scripts/frames.py calculates a higher FPS for the specific window while still respecting the overall frame budget. This allows denser sampling of relevant sections without exceeding the cap defined by the selected detail mode.

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