# How the MAX_FPS Cap of 2.0 Impacts Frame Selection in claude-video

> Understand how claude-video's MAX_FPS cap of 2.0 limits frame extraction and ensures token budget compliance. Discover its impact on frame selection regardless of video length or max frames.

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

---

**The `MAX_FPS = 2.0` hard ceiling in claude-video ensures frame extraction never exceeds 2 frames per second, enforcing token budget compliance by clamping calculated rates regardless of video length or the `--max-frames` parameter.**

The `MAX_FPS` constant sits at the heart of claude-video's frame selection algorithm in `bradautomates/claude-video`. This repository implements a Claude-powered video analysis tool that extracts visual frames for LLM consumption, balancing comprehensiveness against token limits. Understanding how this 2.0 FPS cap shapes frame selection helps users predict behavior across different video durations and optimize their `--max-frames` settings.

## Where MAX_FPS Is Defined and Enforced

In [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), the constant is declared at module level:

```python
MAX_FPS = 2.0

```

Source: [`skills/watch/scripts/frames.py#L19`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py#L19)

This value feeds into the `_clamp_fps` helper function, which applies the ceiling before any final frame calculations:

```python
def _clamp_fps(fps: float) -> float:
    return min(fps, MAX_FPS)

```

Source: [`skills/watch/scripts/frames.py#L49-L52`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py#L49-L52)

Both automatic FPS calculation paths—`auto_fps` for standard mode and `auto_fps_focus` for focused frame selection—route their computed target rates through `_clamp_fps`. This architectural choice guarantees the 2.0 FPS limit applies universally, regardless of which extraction strategy is active.

## How Frame Selection Works Under the Cap

Claude-video uses a **budget-driven extraction model**. Rather than extracting at a fixed rate, it calculates what FPS would hit the user-specified `--max-frames` limit (default 100) given the video's duration. The `MAX_FPS` cap then truncates this calculation.

The mathematical flow is:

1. Compute `target_fps = max_frames / duration_seconds`
2. Apply `actual_fps = min(target_fps, MAX_FPS)`
3. Derive final frame count: `total_frames = actual_fps × duration`

This creates two distinct behavioral regimes based on video length.

## Impact on Long vs. Short Videos

### Long Videos: Cap-Enforced Sparsity

For videos exceeding 50 seconds with default settings, the budget math would suggest FPS below 2.0 anyway (100 frames ÷ 50s = 2.0 fps). For longer content, the budget itself limits extraction before the cap engages.

However, with elevated `--max-frames` values (e.g., 300 or 500), the cap becomes the active constraint. A 5-minute video with `--max-frames 600` would mathematically support 2.0 fps exactly—but cannot exceed it. The cap thus **protects token budgets** from users who might otherwise request frame-dense analysis of lengthy content.

### Short Videos: Density at the Ceiling

For videos under 50 seconds, the budget math often produces target FPS above 2.0. Consider a 10-second clip with default `--max-frames 100`:

- Uncapped calculation: 100 ÷ 10 = **10.0 fps**
- After `_clamp_fps`: **2.0 fps**
- Actual frames extracted: 20 frames

The cap **preserves temporal density up to the limit** but prevents over-sampling that would waste tokens on near-duplicate frames. This is particularly relevant for `auto_fps_focus` mode, which attempts denser extraction around detected scene changes—the cap ensures even this aggressive mode respects the 2.0 ceiling.

## Practical Configuration Implications

Users cannot override `MAX_FPS` through CLI flags. The constant is hardcoded, making the 2.0 ceiling a **non-negotiable system constraint** according to the claude-video source code.

To maximize frame coverage:

- **Increase `--max-frames`** rather than expecting higher density—this extends the cap's reach across longer durations
- **Split long videos** into shorter segments if scene-level granularity is critical
- **Use `--focus` mode** (`auto_fps_focus`) to concentrate the 2.0 fps budget on high-information regions rather than uniform sampling

## Summary

- **`MAX_FPS = 2.0`** in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) enforces a hard extraction ceiling
- **`_clamp_fps`** applies this limit to both `auto_fps` and `auto_fps_focus` calculations
- **Short videos** hit the cap and extract at exactly 2.0 fps despite higher budget allowances
- **Long videos** may fall below the cap based on `--max-frames` ÷ duration math
- The cap is **immutable via configuration**—users must work within its constraints through frame budget allocation and video segmentation

## Frequently Asked Questions

### What is the exact value of MAX_FPS in claude-video?

The `MAX_FPS` constant is set to **2.0** at line 19 of [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). This value has remained fixed in the repository's main branch and cannot be modified through command-line arguments or configuration files.

### Can I extract more than 2 frames per second from a short video?

No. Even with `--max-frames` set higher than your video duration would require at 2.0 fps, the `_clamp_fps` function enforces the ceiling. A 5-second video with `--max-frames 100` still extracts only 10 frames (2.0 fps × 5s), not 100 frames. The cap takes precedence over the budget calculation when the budget would permit higher rates.

### Why does claude-video limit frame extraction to 2 FPS?

The 2.0 FPS cap serves as a **token economy mechanism**. Claude's vision capabilities consume significant context window per image; unconstrained frame rates from short videos could rapidly exhaust available tokens. The cap ensures predictable, bounded resource consumption across all video lengths while preserving sufficient visual information for analysis tasks.

### How does MAX_FPS interact with the --focus flag?

The `--focus` flag activates `auto_fps_focus`, which applies intelligent scene detection to concentrate frames on high-variance regions. However, both `auto_fps` and `auto_fps_focus` routes pass through `_clamp_fps`. Focused extraction redistributes the 2.0 fps budget temporally—it does not increase the rate. You get smarter frame placement, not more frames per second.