# How Claude Video Scales Frame Budget With Video Duration

> Discover how Claude Video scales its frame budget with video duration. Learn about tiered caps and automatic density adjustments to optimize visual detail and token usage.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: performance
- Published: 2026-07-29

---

**Claude Video calculates a target frame budget that grows with video duration using tiered caps defined in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), automatically adjusting extraction density to balance visual detail against token consumption.**

The `bradautomates/claude-video` repository implements an intelligent sampling strategy that adapts extraction rates based on content length. Understanding how the **Claude Video frame budget** scales with video duration helps developers optimize token usage while preserving critical visual information across different content types.

## Tiered Budget Logic in frames.py

The core algorithm resides in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), which provides two distinct budgeting strategies depending on whether you process a complete video or a specific time range.

### Full-Video Processing with auto_fps

For complete video scans, the `auto_fps` function (lines 22-36) implements a five-tier scaling system that calculates target frame counts based on duration:

- **Ultra-short clips (≤30 seconds)**: Targets approximately **1 fps**, using the formula `min(max_frames, max(12, int(round(duration_seconds))))` to ensure at least 12 frames even for brief content.
- **30 seconds to 1 minute**: Hard cap at **40 frames** regardless of exact duration.
- **1 minute to 3 minutes**: Fixed budget of **60 frames**.
- **3 minutes to 10 minutes**: Fixed budget of **80 frames**.
- **Long videos (>10 minutes)**: Uses the full `max_frames` allowance (default 100).

The function returns an FPS value by dividing the target frame count by the duration, then passing the result through `_clamp_fps` to enforce safety limits.

### Focused Range Processing with auto_fps_focus

When users specify `--start` and `--end` timestamps, the `auto_fps_focus` function (lines 41-55) applies a denser extraction strategy to preserve detail in narrow segments:

- **≤5 seconds**: Targets **~6 fps** for maximum granular detail.
- **5-15 seconds**: Reduces to **~4 fps** while maintaining high density.
- **15-30 seconds**: Fixed budget of **60 frames**.
- **30 seconds to 1 minute**: Fixed budget of **80 frames**.
- **≥3 minutes**: Falls back to the full `max_frames` cap.

This focused approach ensures that cropped segments receive proportionally more frames per second than full-video processing would allocate.

## Safety Limits and FPS Clamping

Both budgeting functions rely on `_clamp_fps` (lines 49-53) to enforce constraints that prevent runaway token usage. The implementation sets a **hard maximum of 2 fps** (`MAX_FPS = 2.0`) and guarantees at least one frame for any non-zero duration. This safety mechanism ensures that even high-frame-rate source material cannot exceed the budgetary limits, while ensuring every video yields extractable content.

## Integration with the Watch Pipeline

The [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) file (lines 55-58) orchestrates the selection between these strategies based on user input:

```python
if focused:
    fps, target = auto_fps_focus(effective_duration, max_frames=budget_cap)
else:
    fps, target = auto_fps(effective_duration, max_frames=budget_cap)

```

The `budget_cap` value defaults to the `frame_cap` defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), though users can override this via the `--max-frames` flag to raise or lower the extraction ceiling.

## Practical Usage Examples

These commands demonstrate how the automatic budgeting applies to real-world scenarios:

```bash

# 45-second clip (no range) → auto_fps yields ~45 frames (≈1 fps)

watch myshortclip.mp4

# 2-minute clip (no range) → capped at 60 frames

watch my2min.mp4

# 12-minute clip (no range) → uses default cap of 100 frames

watch my12min.mp4

# 10-second segment extraction → auto_fps_focus yields ~60 frames

watch my5min.mp4 --start 00:02:30 --end 00:02:40

```

To override automatic calculations, specify `--max-frames`, `--fps`, or `--detail` flags, which the `auto_fps*` functions respect when computing final budgets.

## Summary

- Claude Video uses tiered logic in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) to scale frame budgets with video duration, ensuring short clips receive dense coverage while long videos respect cost constraints.
- **Short videos** (≤30s) receive approximately **1 fps** extraction, while **medium videos** hit fixed caps (40-80 frames) to control token costs.
- **Long videos** (>10min) respect the user-defined `max_frames` limit (default 100) regardless of additional length.
- **Focused ranges** via `--start/--end` trigger denser sampling (up to 6 fps) to preserve detail in short segments without affecting the global budget.
- A hard cap of **2 fps** enforced by `_clamp_fps` prevents excessive token usage regardless of source material or duration.

## Frequently Asked Questions

### What is the maximum frame rate Claude Video will extract?

Claude Video enforces a hard limit of **2 fps** through the `_clamp_fps` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). Even if the budget calculation suggests higher density for short clips, this ceiling prevents excessive token consumption on high-frame-rate source material.

### How does the frame budget differ for short clips versus long videos?

For clips under 30 seconds, the system targets approximately **1 fps** to ensure adequate visual coverage. As duration increases, the budget switches to fixed caps (40, 60, or 80 frames) until hitting the 10-minute threshold, where it defaults to the maximum configured frames (typically 100). This tiered approach ensures short content retains detail while long content avoids prohibitive token costs.

### Can I override the automatic frame budget calculation?

Yes. Users can supply `--max-frames`, `--fps`, or `--detail` flags when invoking the watch command. These values pass into `auto_fps` and `auto_fps_focus` as the `max_frames` parameter, which the functions use to clamp their calculated targets according to the tiered logic while respecting your specified ceiling.

### Where is the default frame cap configured?

The default `frame_cap` resides in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), which feeds into the `budget_cap` variable used by [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py). When no user override is provided, this configuration supplies the 100-frame default that limits extraction for videos exceeding 10 minutes in duration.