# How Claude Video Handles Long Videos Exceeding the Frame Budget

> Discover how Claude Video expertly manages long videos by intelligently scaling frame sampling within your budget, ensuring efficient processing without frame loss.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: deep-dive
- Published: 2026-07-13

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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

```bash

# 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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.