How Focused Mode in Claude-Video Calculates Denser Per-Second Budgets

When you specify a --start or --end timestamp in Claude-Video, the tool enters focused mode and allocates a higher frame-per-second budget to short sub-clips using a tiered calculation in auto_fps_focus() that yields up to 6× more target frames per second for sub-5-second windows compared to full-video scans.

Claude-Video, an open-source video analysis tool from the bradautomates/claude-video repository, optimizes visual detail for specific time ranges through a specialized budgeting algorithm. When users narrow their analysis to a specific segment using time boundaries, the system switches from a sparse full-video scan to a denser, focused extraction strategy. This article explains exactly how the focused mode calculates these denser per-second budgets by examining the source code in skills/watch/scripts/frames.py and skills/watch/scripts/watch.py.

What Triggers Focused Mode in Claude-Video

Focused mode activates immediately when you provide either a --start or --end argument to the CLI. In skills/watch/scripts/watch.py, the code evaluates these parameters to set a boolean flag:

focused = start_sec is not None or end_sec is not None

When focused evaluates to True, the engine treats the selected sub-clip as a "zoomed-in" region requiring finer temporal resolution. Instead of distributing frames across the entire video duration, the system calls auto_fps_focus() with the effective duration of the focus window and a max_frames cap (typically 100). This contrasts with full-video mode, which invokes the standard auto_fps() function designed for longer durations.

The Tiered Budget Calculation in auto_fps_focus()

The core logic resides in auto_fps_focus() inside skills/watch/scripts/frames.py. According to the bradautomates/claude-video source code, this function implements a tiered target-frame scheme that grows faster for short windows, producing a higher effective frames-per-second (FPS) value than the linear approach used in full-video mode.

Duration Tiers and Frame Targets

The function selects a target frame count based on the effective duration of the focus window, subject to the max_frames limit:

• ≤ 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 (typically 100)
• > 180 seconds: max_frames

This tiered structure ensures that a 10-second clip receives approximately 40 target frames (4 FPS before clamping), while a 3-second clip receives 18 frames (6 FPS), creating a denser per-second budget precisely where visual detail matters most.

FPS Clamping to MAX_FPS

After calculating the raw target frames, the system determines the FPS by dividing target frames by duration. This value is then passed to _clamp_fps(), which enforces a global maximum of MAX_FPS = 2.0. Consequently, while the tiered logic may calculate a theoretical 6 FPS for a 3-second window, the final extraction rate is clamped to 2 FPS, and the actual frame count is recalculated as min(max_frames, round(2.0 × duration)).

How watch.py Selects the Budgeting Strategy

The orchestration between modes occurs at lines 55-58 in skills/watch/scripts/watch.py. After computing the effective_duration, the script branches based on the focused flag:

# watch.py – after determining effective_duration and whether we are focused

if focused:
    fps, target = auto_fps_focus(effective_duration, max_frames=budget_cap)   # ← focused mode

else:
    fps, target = auto_fps(effective_duration, max_frames=budget_cap)       # ← full-video mode

This conditional ensures that short focus windows receive the aggressive budgeting of auto_fps_focus(), while full-video scans use the standard auto_fps() logic, which typically spreads the max_frames budget across the entire video length, resulting in a much lower per-second density.

Practical Code Examples

Consider a 12-second focus window analyzed with a budget cap of 100 frames:

# Example: Extract frames from a 12-second focus window

effective_duration = 12.0                     # seconds

fps, target = auto_fps_focus(effective_duration, max_frames=100)

# → fps ≈ 5.0 (clamped to MAX_FPS = 2.0, so final fps = 2.0)

# → target = min(100, round(2.0 * 12)) = 24 frames

For comparison, a full 10-minute video (600 seconds) in standard mode receives significantly fewer frames per second despite the same cap:

# Example: Full-video mode for a 10-minute video (600s)

effective_duration = 600.0
fps, target = auto_fps(effective_duration, max_frames=100)

# → fps = 2.0 (MAX_FPS)  

# → target = min(100, round(2.0 * 600)) = 100 frames

These examples demonstrate how focused mode achieves a 12× denser frame distribution for the short clip (2.0 FPS vs. 0.17 FPS) while respecting the same global resource constraints.

Summary

• Focused mode activates when --start or --end arguments are provided, setting focused = True in watch.py.
• The auto_fps_focus() function in skills/watch/scripts/frames.py calculates frame budgets using a tiered system that allocates more frames per second for shorter durations.
• Duration tiers range from 6× multiplier for ≤5s clips to fixed caps for longer segments, all subject to max_frames (typically 100).
• The final FPS is clamped to MAX_FPS = 2.0 by _clamp_fps(), ensuring consistent extraction rates across varying window sizes.
• Lines 55-58 in skills/watch/scripts/watch.py orchestrate the selection between focused and full-video budgeting strategies.

Frequently Asked Questions

What is the maximum FPS in focused mode?

The absolute maximum FPS is 2.0, defined by the MAX_FPS constant in skills/watch/scripts/frames.py. While the tiered calculation in auto_fps_focus() may compute higher theoretical values (up to 6.0 for very short clips), the _clamp_fps() function enforces the 2.0 ceiling to prevent excessive API calls or processing overhead.

How does focused mode differ from full-video mode?

Full-video mode uses auto_fps(), which linearly distributes the max_frames budget across the entire video duration, typically resulting in FPS values well below 1.0 for long videos. Focused mode uses auto_fps_focus(), which applies aggressive multipliers (up to 6×) for short windows, yielding higher per-second frame densities for the specified sub-clip while ignoring the rest of the video timeline.

Why does the frame budget use tiers instead of linear scaling?

The tiered approach in auto_fps_focus() prioritizes visual fidelity for brief events. Short clips benefit from disproportionately higher frame counts because the user has explicitly signaled interest in that specific segment. Linear scaling would allocate the same sparse density used for full-video scans, defeating the purpose of "zooming in" on a particular moment. The tiers ensure minimum viable frame counts (10, 30, 60, 80) even as duration decreases.

Where is the focused mode logic implemented?

The calculation logic resides in skills/watch/scripts/frames.py within the auto_fps_focus() and _clamp_fps() functions. The mode detection and function selection occur in skills/watch/scripts/watch.py at lines 55-58, where the script checks if focused: to determine whether to invoke the focused or standard budgeting path.

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