# How Focused Mode (--start/--end) Affects Frame Budgets in Claude-Video

> Discover how Claude-Video's focused mode (--start/--end) boosts frame budgets for short clips. Learn how auto_fps_focus multiplies frames up to 6x for clips under 5 seconds, respecting MAX_FPS.

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

---

**Focused mode increases the frame budget for short video segments by switching from `auto_fps` to `auto_fps_focus`, which multiplies the target frame count by up to 6× for clips ≤5 seconds while respecting the `MAX_FPS` cap of 2.0.**

The `claude-video` repository provides a **watch skill** that extracts video frames using an auto-scaled frames-per-second (FPS) algorithm to maintain a **frame budget**—the maximum number of JPEGs written for any analysis. When users supply `--start` and/or `--end` arguments, the system enters focused mode and recalculates this budget to provide denser coverage of the selected interval. This article examines exactly how the focused mode frame budget mechanism works in the source code.

## What is Focused Mode?

Focused mode activates when the user "zooms in" on a specific sub-segment of the video using time-based arguments. Instead of distributing the frame budget across the entire video duration, the skill concentrates computational resources on the specified window, adjusting the frame extraction density algorithmically.

## How Focused Mode Changes the Frame Budget Calculation

The frame budget determines the maximum number of JPEG frames the watch skill will extract. According to [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), focused mode triggers a four-step process that reallocates the budget toward the selected interval while maintaining hard caps.

### Step 1: Detecting Focus Mode

The script evaluates whether to enter focused mode by checking for the presence of start or end timestamps at lines 30-32:

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

```

When either variable is populated, the boolean `focused` becomes `True`, signaling that the user has requested a targeted extraction rather than a full-video scan.

### Step 2: Selecting the FPS Function

Based on the `focused` flag, the code selects between two budget calculation strategies at lines 33-35:

- **Full-video scan**: Uses `auto_fps` for modest, evenly distributed coverage across the entire duration
- **Focused scan**: Uses `auto_fps_focus` for dense, targeted coverage of the sub-segment

### Step 3: Computing a Denser Budget

The `auto_fps_focus` function (lines 41-59) implements a tiered multiplier system that increases the target frame count based on the duration of the selected clip:

- **≤ 5 seconds**: Up to **6×** the base FPS multiplier
- **≤ 15 seconds**: Up to **4×** the base FPS multiplier
- **Maximum cap**: `MAX_FPS = 2.0` prevents the extraction rate from exceeding 2 frames per second

This ensures that short, focused clips receive significantly more frames than they would in a full-video scan. For example, a 4-second window that might generate 8 frames in standard mode can yield up to 24 frames in focused mode.

### Step 4: Applying the Budget to Extraction

The computed `fps` and `target` values are passed to the `extract()` function (lines 39-44), which respects the `max_frames` parameter—the definitive budget ceiling. Even with focused mode's increased multipliers, the extraction cannot exceed the absolute maximum frame count defined by the system configuration.

## Practical Impact on Frame Density

The difference between modes is substantial when analyzing short segments. A 4-second clip extracted in full-video mode generates approximately 8 frames (at 2 FPS), while the same clip in focused mode receives up to 24 frames (6× multiplier applied to the base calculation). This density ensures that rapid changes within the focused window are captured without increasing the processing burden for the entire video file.

## Code Examples

The following commands demonstrate the practical difference between extraction modes:

```bash

# Full-video extraction (no focus)

# Uses auto_fps → ~2 fps for a 30-second clip (≈60 frames)

python -m skills.watch.scripts.frames video.mp4 out_dir

# Focused extraction on a 4-second window

# Uses auto_fps_focus → ~6 fps (≈24 frames) for the same 4s interval

python -m skills.watch.scripts.frames video.mp4 out_dir \
    --start 00:01:12 --end 00:01:16

```

The second command produces **more frames per second** inside the 4-second window because `auto_fps_focus` multiplies the target by up to 6 when the duration is ≤5 seconds.

## Key Implementation Files

The focused mode frame budget logic is distributed across these critical files:

- **[`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)**: Contains the core logic for frame extraction, FPS selection via `auto_fps_focus`, and the `MAX_FPS` constant.
- **[`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)**: Entry point that parses CLI arguments and delegates to the frames module.
- **[`tests/test_frames.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_frames.py)**: Unit tests verifying the focused-mode budget behavior and multiplier calculations.

## Summary

- Focused mode activates when `--start` or `--end` arguments are provided, setting `focused = True` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 30-32).
- The system switches from `auto_fps` to `auto_fps_focus`, which applies multipliers up to 6× for short segments (≤5 seconds) and 4× for medium segments (≤15 seconds).
- The **frame budget** increases for the selected interval while respecting the `MAX_FPS = 2.0` cap and absolute `max_frames` limits enforced by the `extract()` function.
- Short clips receive denser frame coverage (e.g., ~24 frames for 4 seconds vs. ~8 frames in standard mode) without affecting the full-video processing pipeline.

## Frequently Asked Questions

### What is the maximum frame rate in focused mode?

The `MAX_FPS` constant in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) caps the extraction rate at **2.0 frames per second**, regardless of the multipliers applied by `auto_fps_focus`. This ensures that even with the 6× budget multiplier for clips ≤5 seconds, the system never exceeds 2 FPS.

### How does the frame budget differ between full-video and focused extraction?

In full-video mode, `auto_fps` distributes a modest frame budget across the entire duration (e.g., ≤100 frames for a 10-minute video). In focused mode, `auto_fps_focus` concentrates a larger budget specifically into the selected sub-segment, yielding up to 6× more frames per second for short clips while maintaining the same absolute `max_frames` ceiling.

### Can I exceed the maximum frame count using --start and --end?

No. The `extract()` function respects the `max_frames` parameter as an absolute limit. While focused mode increases the target density for your selected interval, the extraction process will stop if the computed frames would exceed the total budget cap defined by `max_frames`.

### Where is the focused mode detection logic implemented?

The detection occurs at lines 30-32 of [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), where the code evaluates `focused = start_sec is not None or end_sec is not None`. This boolean then determines whether to invoke `auto_fps_focus` or `auto_fps` at lines 33-35.