# How Focus Mode Calculates FPS for Specific Time Ranges in Claude Video

> Discover how Claude Video's focus mode calculates FPS for specific time ranges. Learn about timestamp parsing, frame budgets, and the 2 FPS maximum for efficient video processing.

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

---

**Focus mode calculates FPS by parsing user-supplied `--start` and `--end` timestamps to determine duration, then applies duration-specific frame budgets via `auto_fps_focus` before clamping to the global 2 FPS maximum.**

When working with the `bradautomates/claude-video` repository, focus mode provides targeted frame extraction for specific video segments. This specialized calculation activates when users specify time boundaries, allocating denser frame budgets than standard full-video processing while respecting the global FPS ceiling.

## Activating Focus Mode with Time Ranges

Focus mode triggers when the watch script detects `--start` or `--end` arguments. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the parser converts timestamp strings to seconds using `parse_time`, then calculates the effective duration:

```python
start_sec = parse_time(args.start)
end_sec   = parse_time(args.end)

# ...

effective_duration = max(0.0, effective_end - effective_start)
focused = start_sec is not None or end_sec is not None

```

The boolean `focused` determines whether the script calls `auto_fps_focus` instead of the standard `auto_fps` function. According to the source code in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 155-158), the selection logic is:

```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 auto_fps_focus Algorithm

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 frame allocation strategy based on the effective duration. This algorithm prioritizes visual density for shorter clips while scaling efficiently for longer segments.

### Duration-Based Frame Budgets

The function applies specific target frame calculations depending on the time range length:

| Duration | Target Frame Calculation |
|----------|-------------------------|
| ≤ 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` (budget cap) |
| > 180 seconds | `max_frames` (budget cap) |

These thresholds ensure that a 12-second clip receives up to 48 target frames (`max(30, round(12 × 4))`), while a 30-second segment receives exactly 60 frames.

### FPS Clamping and Constraints

After determining the target frame count, the algorithm converts this to an FPS value and applies `_clamp_fps`. As implemented in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 49-53), this enforces the global `MAX_FPS` constant of 2 FPS:

```python

# Inside auto_fps_focus (lines 41-59)

fps = target / duration if duration > 0 else 0
return _clamp_fps(fps, target)

```

The `_clamp_fps` function ensures that even very short focus windows never exceed the 2 FPS ceiling, preserving the global rate limit while still allocating more frames than full-video mode would permit for the same duration.

## Practical Implementation Examples

### Direct API Usage

You can invoke the focus mode calculation directly in Python:

```python
from skills.watch.scripts.frames import auto_fps_focus

# Simulate a 12-second focus window with default 100-frame budget

duration = 12.0
fps, target = auto_fps_focus(duration, max_frames=100)

print(f"Focus FPS: {fps:.2f}  →  target frames: {target}")

# Output: Focus FPS: 2.00  →  target frames: 24

```

In this example, the function initially targets 48 frames (`max(30, 48)`), but `_clamp_fps` limits FPS to 2.0, resulting in `round(2.0 × 12) = 24` final frames.

### Command-Line Focus Mode

Invoke focus mode via CLI with timestamp arguments:

```bash
python -m skills.watch.scripts.watch \
    --source "https://youtu.be/abcd1234" \
    --start 1:15 \
    --end 1:45 \
    --detail balanced

```

This command processes the 30-second window between 01:15 and 01:45, triggering the message: `[watch] extracting scene-aware frames over 01:15-01:45 (30.0s) (target 60, cap 100)`. The target 60 derives directly from the ≤30s threshold in `auto_fps_focus`.

## Summary

- **Focus mode activates** when `--start` or `--end` arguments are present in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), setting `focused = True`.
- **Duration parsing** converts timestamps to seconds and calculates `effective_duration` for the specified range.
- **Tiered budgets** in `auto_fps_focus` allocate 10-6× frames for short clips, scaling up to the `max_frames` cap for segments over 3 minutes.
- **Global constraints** via `_clamp_fps` enforce the 2 FPS maximum regardless of duration, ensuring consistent extraction rates.
- **Higher density** focus mode yields more frames per second than standard `auto_fps` for equivalent durations, providing richer visual context for critical segments.

## Frequently Asked Questions

### How does focus mode differ from standard FPS calculation?

Standard mode uses `auto_fps` for full-video processing, while focus mode calls `auto_fps_focus` with higher frame density thresholds. According to the `bradautomates/claude-video` source, focus mode allocates up to 6× frames per second for clips under 5 seconds, whereas standard mode distributes the global frame budget across the entire video duration.

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

The 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). Even when `auto_fps_focus` calculates a higher theoretical rate for short durations, the `_clamp_fps` function enforces this ceiling to maintain consistent performance and API limits.

### Why does a 12-second clip return 24 frames instead of 48?

The `auto_fps_focus` function initially calculates a target of 48 frames for a 12-second duration (`max(30, round(12 × 4))`). However, `_clamp_fps` limits the FPS to 2.0, so the final frame count becomes `round(2.0 × 12) = 24`. This ensures the extraction rate never exceeds the global 2 FPS cap while still benefiting from focus mode's higher initial budget allocation.

### Can I use focus mode with scene-aware extraction?

Yes. The `fps` and `target` values calculated by `auto_fps_focus` feed directly into `extract_scene_or_uniform` or `extract_keyframes` functions. The FPS parameter guides both uniform frame sampling and scene-aware keyframe detection, ensuring the specified time range receives appropriate visual coverage regardless of extraction method.