# How Focused Mode in Claude-Video Calculates Denser Per-Second Frame Budgets Up to 2 FPS

> Discover how Claude-Video's focused mode calculates denser per-second frame budgets up to 2 FPS for short clips using a tiered approach. Learn more about this innovative video processing technique.

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

---

**When users specify a time range with `--start` or `--end` arguments, Claude-Video's focused mode calls `auto_fps_focus()` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) to allocate a higher frame density per second using a tiered calculation that scales aggressively for short clips before clamping to the global maximum of 2 FPS.**

Claude-Video, an open-source video analysis tool in the bradautomates repository, provides a specialized **focused mode** that extracts frames at a higher density when analyzing specific time windows. Unlike standard full-video scanning which spreads frames evenly across the entire duration, this feature concentrates the visual budget on user-specified segments. Understanding how focused mode calculates these denser per-second frame budgets up to 2 FPS reveals the precision behind the tool's adaptive sampling strategy.

## How Focused Mode Triggers the Denser Budget

The system detects focused mode through a boolean check in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) that evaluates whether temporal boundaries have been specified:

```python
focused = start_sec is not None or end_sec is not None

```

When this condition evaluates to `True`, the engine treats the selected sub-clip as a "zoomed-in" region requiring finer visual detail. The code then routes the **effective duration** of this focus window to `auto_fps_focus()` rather than the standard `auto_fps()` function, initiating the denser allocation logic.

## The Tiered Calculation Logic in auto_fps_focus()

Located in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), the `auto_fps_focus()` function receives two critical parameters: the `effective_duration` of the focus window in seconds, and `max_frames` (typically set to 100). It applies a non-linear scaling algorithm that allocates more frames per second for shorter durations.

### Duration Thresholds and Target Frame Allocation

The function implements a tiered strategy that increases the target frame count faster than linear growth for brief segments:

- **≤ 5 seconds**: `max(10, round(duration × 6))` — up to 6 frames per second requested
- **≤ 15 seconds**: `max(30, round(duration × 4))` — up to 4 frames per second requested  
- **≤ 30 seconds**: Fixed allocation of `60` frames
- **≤ 60 seconds**: Fixed allocation of `80` frames
- **≤ 180 seconds**: Full `max_frames` budget (typically 100)
- **> 180 seconds**: Capped at `max_frames`

This tiered approach ensures that a 10-second clip might receive 40 frames (4 FPS before clamping), while a 10-minute clip in standard mode would receive only 100 frames total (0.17 FPS).

### The 2 FPS Ceiling and _clamp_fps()

Regardless of the tiered calculation, the final output passes through `_clamp_fps()`, which enforces the global constant `MAX_FPS = 2.0`. This hard ceiling ensures that even when the target frame count suggests a higher rate (e.g., 4 FPS for a 10-second clip), the actual extraction rate never exceeds 2 frames per second. The function returns both the clamped FPS value and the final target frame count.

## Integration with the Watch Pipeline

The selection between focused and standard budgeting occurs in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) at lines 55-58, where the engine branches based on the `focused` boolean:

```python

# watch.py – after determining effective_duration and whether we are focused

if focused:
    fps, target = auto_fps_focus(effective_duration, max_frames=budget_cap)   # ← focused mode

else:
    fps, target = auto_fps(effective_duration, max_frames=budget_cap)       # ← full‑video mode

```

This conditional ensures that users automatically receive the denser sampling strategy whenever they narrow the analysis window, without manual FPS configuration.

## Practical Examples: Focused vs. Full-Video Mode

Consider a 12-second focus window analyzed with the default 100-frame budget cap:

```python

# Example: Extract frames from a 12‑second focus window

effective_duration = 12.0                     # seconds

fps, target = auto_fps_focus(effective_duration, max_frames=100)

# Tier calculation: max(30, round(12 × 4)) = 48 frames requested

# Raw FPS: 48 / 12 = 4.0 FPS

# After clamping to MAX_FPS = 2.0:

# → final fps = 2.0

# → target = min(100, round(2.0 * 12)) = 24 frames

```

In contrast, standard full-video mode for a 600-second (10-minute) video applies linear scaling:

```python

# Example: Full‑video mode for a 10‑minute video (600 s)

effective_duration = 600.0
fps, target = auto_fps(effective_duration, max_frames=100)

# → fps = 2.0 (MAX_FPS)  

# → target = min(100, round(2.0 * 600)) = 100 frames

# Actual density: 100 frames / 600 seconds = 0.17 FPS

```

While both respect the 100-frame cap, the **focused mode** yields 24 frames for 12 seconds (2 FPS), whereas the full-video approach spreads 100 frames across 600 seconds, demonstrating the density advantage for targeted analysis.

## Summary

- Focused mode activates automatically when users provide `--start` or `--end` arguments, setting `focused = True` in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py).
- The `auto_fps_focus()` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) implements a tiered duration-based allocation that scales aggressively for short clips.
- Duration thresholds apply multipliers of 6× and 4× for clips under 5 and 15 seconds respectively, with fixed allocations for longer segments up to the `max_frames` cap.
- The global `MAX_FPS = 2.0` constant enforced by `_clamp_fps()` sets the hard ceiling for all extraction rates.
- This architecture allows Claude-Video to concentrate visual detail precisely where users indicate interest without exceeding system resource limits.

## Frequently Asked Questions

### What is the maximum FPS that Claude-Video focused mode can achieve?

The absolute maximum is **2 FPS**, defined by the `MAX_FPS = 2.0` constant in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). While the tiered calculation in `auto_fps_focus()` may compute a higher theoretical rate for very short clips (e.g., 4-6 FPS), the `_clamp_fps()` function enforces this ceiling before extraction begins.

### How does focused mode differ from standard frame extraction?

Standard mode uses `auto_fps()` to distribute the `max_frames` budget linearly across the entire video duration, often resulting in fractions of a FPS for long content. Focused mode invokes `auto_fps_focus()` which applies a tiered, non-linear scaling algorithm that allocates proportionally more frames per second to shorter time windows, yielding denser visual sampling for the selected segment.

### Where is the frame budget calculation defined in the source code?

The primary calculation logic resides in `auto_fps_focus()` within [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). The function contains the duration threshold logic (5s, 15s, 30s, 60s, 180s) and target frame allocation rules. The global FPS ceiling is also defined in this file, while the mode selection logic appears in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) at lines 55-58.

### Why does focused mode use tiered thresholds instead of linear scaling?

The tiered approach prioritizes **visual fidelity for short analytical windows** where fine-grained changes matter most. A linear allocation would provide the same frame density regardless of clip length, but the tiered system (6×, 4×, then fixed values) ensures that brief segments receive disproportionately higher sampling rates while longer segments progressively approach the `max_frames` cap, optimizing the trade-off between detail and processing overhead.