# How Focused Mode in Claude-Video Calculates Denser Per-Second Budgets

> Discover how Claude-Video's focused mode calculates denser per-second budgets for sub-clips up to 6x higher frame rates for better detail in short video segments.

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

---

**When you specify a `--start` or `--end` timestamp in Claude-Video, the tool enters focused mode and allocates a higher frame-per-second budget to short sub-clips using a tiered calculation in `auto_fps_focus()` that yields up to 6× more target frames per second for sub-5-second windows compared to full-video scans.**

Claude-Video, an open-source video analysis tool from the `bradautomates/claude-video` repository, optimizes visual detail for specific time ranges through a specialized budgeting algorithm. When users narrow their analysis to a specific segment using time boundaries, the system switches from a sparse full-video scan to a denser, focused extraction strategy. This article explains exactly how the focused mode calculates these denser per-second budgets by examining the source code in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) and [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).

## What Triggers Focused Mode in Claude-Video

Focused mode activates immediately when you provide either a `--start` or `--end` argument to the CLI. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the code evaluates these parameters to set a boolean flag:

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

```

When `focused` evaluates to `True`, the engine treats the selected sub-clip as a "zoomed-in" region requiring finer temporal resolution. Instead of distributing frames across the entire video duration, the system calls `auto_fps_focus()` with the **effective duration** of the focus window and a `max_frames` cap (typically 100). This contrasts with full-video mode, which invokes the standard `auto_fps()` function designed for longer durations.

## The Tiered Budget Calculation in auto_fps_focus()

The core logic resides in `auto_fps_focus()` inside [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). According to the `bradautomates/claude-video` source code, this function implements a **tiered target-frame scheme** that grows faster for short windows, producing a higher effective frames-per-second (FPS) value than the linear approach used in full-video mode.

### Duration Tiers and Frame Targets

The function selects a target frame count based on the effective duration of the focus window, subject to the `max_frames` limit:

- **≤ 5 seconds**: `max(10, round(duration × 6))`
- **≤ 15 seconds**: `max(30, round(duration × 4))`
- **≤ 30 seconds**: `60` frames
- **≤ 60 seconds**: `80` frames
- **≤ 180 seconds**: `max_frames` (typically 100)
- **> 180 seconds**: `max_frames`

This tiered structure ensures that a 10-second clip receives approximately 40 target frames (4 FPS before clamping), while a 3-second clip receives 18 frames (6 FPS), creating a denser per-second budget precisely where visual detail matters most.

### FPS Clamping to MAX_FPS

After calculating the raw target frames, the system determines the FPS by dividing target frames by duration. This value is then passed to `_clamp_fps()`, which enforces a global maximum of **`MAX_FPS = 2.0`**. Consequently, while the tiered logic may calculate a theoretical 6 FPS for a 3-second window, the final extraction rate is clamped to 2 FPS, and the actual frame count is recalculated as `min(max_frames, round(2.0 × duration))`.

## How watch.py Selects the Budgeting Strategy

The orchestration between modes occurs at lines 55-58 in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py). After computing the `effective_duration`, the script branches based on the `focused` flag:

```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 short focus windows receive the aggressive budgeting of `auto_fps_focus()`, while full-video scans use the standard `auto_fps()` logic, which typically spreads the `max_frames` budget across the entire video length, resulting in a much lower per-second density.

## Practical Code Examples

Consider a 12-second focus window analyzed with a budget cap of 100 frames:

```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)

# → fps ≈ 5.0 (clamped to MAX_FPS = 2.0, so final fps = 2.0)

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

```

For comparison, a full 10-minute video (600 seconds) in standard mode receives significantly fewer frames per second despite the same cap:

```python

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

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

```

These examples demonstrate how focused mode achieves a **12× denser frame distribution** for the short clip (2.0 FPS vs. 0.17 FPS) while respecting the same global resource constraints.

## Summary

- **Focused mode** activates when `--start` or `--end` arguments are provided, 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) calculates frame budgets using a tiered system that allocates more frames per second for shorter durations.
- Duration tiers range from 6× multiplier for ≤5s clips to fixed caps for longer segments, all subject to `max_frames` (typically 100).
- The final FPS is clamped to **`MAX_FPS = 2.0`** by `_clamp_fps()`, ensuring consistent extraction rates across varying window sizes.
- Lines 55-58 in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) orchestrate the selection between focused and full-video budgeting strategies.

## Frequently Asked Questions

### What is the maximum FPS in focused mode?

The absolute maximum FPS is **2.0**, defined by the `MAX_FPS` 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 higher theoretical values (up to 6.0 for very short clips), the `_clamp_fps()` function enforces the 2.0 ceiling to prevent excessive API calls or processing overhead.

### How does focused mode differ from full-video mode?

Full-video mode uses `auto_fps()`, which linearly distributes the `max_frames` budget across the entire video duration, typically resulting in FPS values well below 1.0 for long videos. Focused mode uses `auto_fps_focus()`, which applies aggressive multipliers (up to 6×) for short windows, yielding higher per-second frame densities for the specified sub-clip while ignoring the rest of the video timeline.

### Why does the frame budget use tiers instead of linear scaling?

The tiered approach in `auto_fps_focus()` prioritizes **visual fidelity for brief events**. Short clips benefit from disproportionately higher frame counts because the user has explicitly signaled interest in that specific segment. Linear scaling would allocate the same sparse density used for full-video scans, defeating the purpose of "zooming in" on a particular moment. The tiers ensure minimum viable frame counts (10, 30, 60, 80) even as duration decreases.

### Where is the focused mode logic implemented?

The calculation logic resides in **[`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)** within the `auto_fps_focus()` and `_clamp_fps()` functions. The mode detection and function selection occur 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 script checks `if focused:` to determine whether to invoke the focused or standard budgeting path.