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

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, 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 lines 57-58 invoke auto_fps_focus from 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 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

# 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. 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 file houses default detail settings and frame caps, while 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 lines 41-55
• Higher FPS targets are computed by auto_fps_focus in 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 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 lines 44-48 raise a validation error. The check specifically catches when start_sec exceeds the detected video duration, preventing invalid range specifications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}