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

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, the parser converts timestamp strings to seconds using parse_time, then calculates the effective duration:

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 (lines 155-158), the selection logic is:

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 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 (lines 49-53), this enforces the global MAX_FPS constant of 2 FPS:

# 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:

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:

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, 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. 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.

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