# How Focus Mode with --start and --end Affects Frame Budgets for Targeted Video Analysis

> Discover how focus mode with --start and --end reallocates your frame budget for dense, targeted video analysis without increasing token costs. Optimize your video analysis today.

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

---

**Focus mode reallocates your existing frame budget to a smaller time window, increasing frame density without raising token costs.**

The `claude-video` repository provides a `watch` skill that analyzes video content through frame extraction and transcription. When you need granular analysis of a specific segment rather than the entire video, the `--start` and `--end` flags activate focus mode — a specialized algorithm that concentrates the frame budget where you need it most.

## What Is Focus Mode in claude-video?

Focus mode is triggered whenever you supply one or both temporal boundary flags. The tool interprets this as a signal to narrow its attention and redistribute computational resources accordingly.

In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the parsing logic at lines 41-44 converts timestamp strings to seconds using `parse_time`. The validation at lines 44-48 ensures logical constraints: start must be non-negative, end must exceed start, and start cannot exceed video duration. When validation passes, lines 50-55 establish `effective_start`, `effective_end`, `effective_duration`, and set `focused = True`.

This boolean flag cascades through the extraction pipeline, fundamentally altering how frames are selected.

## How Frame Budgets Get Reallocated

The critical difference lies in frame density calculation. Instead of spreading frames across the full video duration, focus mode concentrates them within your specified window.

### Step 1: Higher FPS Target Selection

When `focused = True`, [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) lines 57-58 invoke `auto_fps_focus` from [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) (lines 41-59) rather than the standard `auto_fps`. This function scales target frame counts upward for short durations.

For example, a 5-second clip receives a target of `min(max_frames, max(10, duration × 6))` — ensuring meaningful visual coverage even for brief segments.

### Step 2: Budget Cap Preservation

The absolute limit — whether from `--max-frames` or the detail engine's default — **remains unchanged**. The budget is simply reallocated, not expanded. This keeps token usage predictable for downstream LLM processing while improving resolution in critical regions.

### Step 3: Timestamp-Aware Budget Management

Lines 124-130 in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) handle cue frames from `--timestamps` first, decrementing them from the cap before applying the remaining `detail_budget` to the extraction engine. This ensures priority timestamps are preserved regardless of focus boundaries.

## Practical Examples of Focus Mode Frame Budgets

```bash

# Full video: ~80 fps selected for 10-minute video, ~800 target frames

watch https://example.com/video.mp4 --detail balanced

# 12-second focus: ~6 fps, ~72 target frames, all within the window

watch https://example.com/video.mp4 --start 00:01:30 --end 00:01:42 --detail balanced

# 60-second focus with hard cap: higher fps selected, but only 30 frames kept

watch https://example.com/video.mp4 --start 00:05:00 --end 00:06:00 \
     --max-frames 30 --detail efficient

```

In the third example, the 30-frame cap applies universally — focus mode simply ensures those 30 frames sample the targeted minute more densely than they would if scattered across a longer duration.

## Fallback Behavior for Short Intervals

When scene detection requires more frames than the focused interval allows, the system falls back to uniform sampling via `extract` in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py). The elevated fps from `auto_fps_focus` still applies, maintaining higher granularity than full-video uniform sampling would provide.

## Configuration and Boundary Handling

The [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) file houses default detail settings and frame caps, while [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py) synchronously filters transcript segments to match `--start`/`--end` boundaries when focus mode is active. This ensures multimodal outputs remain temporally aligned.

## Summary

- **Focus mode activates** when `--start` and/or `--end` are provided, validated in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) lines 41-55
- **Higher FPS targets** are computed by `auto_fps_focus` in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) for denser sampling
- **Absolute frame budget unchanged** — the same `--max-frames` cap applies, but frames concentrate in the target window
- **Cue frames prioritized** via timestamp-aware budget management in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) lines 124-130
- **Uniform fallback** preserves density benefits when scene detection is infeasible

## Frequently Asked Questions

### What happens if I only specify --start without --end?

The effective end becomes the video duration, creating a focused window from your start point to the end. The same density logic applies: `auto_fps_focus` calculates appropriate fps for the remaining duration.

### Does focus mode increase API costs or token usage?

No. The frame budget cap remains fixed by `--max-frames` or detail defaults. Focus mode improves granular inspection without expanding computational requirements, keeping token consumption predictable.

### Can I use --timestamps inside a focused range?

Yes. Timestamps specified via `--timestamps` are extracted first and counted against the budget cap, then the remaining `detail_budget` is applied to the focus interval. This ensures critical moments are preserved regardless of automatic selection.

### What error occurs if my --start exceeds video duration?

[`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) lines 44-48 raise a validation error. The check specifically catches when `start_sec` exceeds the detected video duration, preventing invalid range specifications.