How Focused Mode in Claude-Video Calculates Denser Per-Second Frame Budgets Up to 2 FPS

When users specify a time range with --start or --end arguments, Claude-Video's focused mode calls auto_fps_focus() in skills/watch/scripts/frames.py to allocate a higher frame density per second using a tiered calculation that scales aggressively for short clips before clamping to the global maximum of 2 FPS.

Claude-Video, an open-source video analysis tool in the bradautomates repository, provides a specialized focused mode that extracts frames at a higher density when analyzing specific time windows. Unlike standard full-video scanning which spreads frames evenly across the entire duration, this feature concentrates the visual budget on user-specified segments. Understanding how focused mode calculates these denser per-second frame budgets up to 2 FPS reveals the precision behind the tool's adaptive sampling strategy.

How Focused Mode Triggers the Denser Budget

The system detects focused mode through a boolean check in skills/watch/scripts/watch.py that evaluates whether temporal boundaries have been specified:

focused = start_sec is not None or end_sec is not None

When this condition evaluates to True, the engine treats the selected sub-clip as a "zoomed-in" region requiring finer visual detail. The code then routes the effective duration of this focus window to auto_fps_focus() rather than the standard auto_fps() function, initiating the denser allocation logic.

The Tiered Calculation Logic in auto_fps_focus()

Located in skills/watch/scripts/frames.py, the auto_fps_focus() function receives two critical parameters: the effective_duration of the focus window in seconds, and max_frames (typically set to 100). It applies a non-linear scaling algorithm that allocates more frames per second for shorter durations.

Duration Thresholds and Target Frame Allocation

The function implements a tiered strategy that increases the target frame count faster than linear growth for brief segments:

• ≤ 5 seconds: max(10, round(duration × 6)) — up to 6 frames per second requested
• ≤ 15 seconds: max(30, round(duration × 4)) — up to 4 frames per second requested
• ≤ 30 seconds: Fixed allocation of 60 frames
• ≤ 60 seconds: Fixed allocation of 80 frames
• ≤ 180 seconds: Full max_frames budget (typically 100)
• > 180 seconds: Capped at max_frames

This tiered approach ensures that a 10-second clip might receive 40 frames (4 FPS before clamping), while a 10-minute clip in standard mode would receive only 100 frames total (0.17 FPS).

The 2 FPS Ceiling and _clamp_fps()

Regardless of the tiered calculation, the final output passes through _clamp_fps(), which enforces the global constant MAX_FPS = 2.0. This hard ceiling ensures that even when the target frame count suggests a higher rate (e.g., 4 FPS for a 10-second clip), the actual extraction rate never exceeds 2 frames per second. The function returns both the clamped FPS value and the final target frame count.

Integration with the Watch Pipeline

The selection between focused and standard budgeting occurs in skills/watch/scripts/watch.py at lines 55-58, where the engine branches based on the focused boolean:

# 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 users automatically receive the denser sampling strategy whenever they narrow the analysis window, without manual FPS configuration.

Practical Examples: Focused vs. Full-Video Mode

Consider a 12-second focus window analyzed with the default 100-frame budget cap:

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

effective_duration = 12.0                     # seconds

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

# Tier calculation: max(30, round(12 × 4)) = 48 frames requested

# Raw FPS: 48 / 12 = 4.0 FPS

# After clamping to MAX_FPS = 2.0:

# → final fps = 2.0

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

In contrast, standard full-video mode for a 600-second (10-minute) video applies linear scaling:

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

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

# Actual density: 100 frames / 600 seconds = 0.17 FPS

While both respect the 100-frame cap, the focused mode yields 24 frames for 12 seconds (2 FPS), whereas the full-video approach spreads 100 frames across 600 seconds, demonstrating the density advantage for targeted analysis.

Summary

• Focused mode activates automatically when users provide --start or --end arguments, setting focused = True in watch.py.
• The auto_fps_focus() function in skills/watch/scripts/frames.py implements a tiered duration-based allocation that scales aggressively for short clips.
• Duration thresholds apply multipliers of 6× and 4× for clips under 5 and 15 seconds respectively, with fixed allocations for longer segments up to the max_frames cap.
• The global MAX_FPS = 2.0 constant enforced by _clamp_fps() sets the hard ceiling for all extraction rates.
• This architecture allows Claude-Video to concentrate visual detail precisely where users indicate interest without exceeding system resource limits.

Frequently Asked Questions

What is the maximum FPS that Claude-Video focused mode can achieve?

The absolute maximum is 2 FPS, defined by the MAX_FPS = 2.0 constant in skills/watch/scripts/frames.py. While the tiered calculation in auto_fps_focus() may compute a higher theoretical rate for very short clips (e.g., 4-6 FPS), the _clamp_fps() function enforces this ceiling before extraction begins.

How does focused mode differ from standard frame extraction?

Standard mode uses auto_fps() to distribute the max_frames budget linearly across the entire video duration, often resulting in fractions of a FPS for long content. Focused mode invokes auto_fps_focus() which applies a tiered, non-linear scaling algorithm that allocates proportionally more frames per second to shorter time windows, yielding denser visual sampling for the selected segment.

Where is the frame budget calculation defined in the source code?

The primary calculation logic resides in auto_fps_focus() within skills/watch/scripts/frames.py. The function contains the duration threshold logic (5s, 15s, 30s, 60s, 180s) and target frame allocation rules. The global FPS ceiling is also defined in this file, while the mode selection logic appears in skills/watch/scripts/watch.py at lines 55-58.

Why does focused mode use tiered thresholds instead of linear scaling?

The tiered approach prioritizes visual fidelity for short analytical windows where fine-grained changes matter most. A linear allocation would provide the same frame density regardless of clip length, but the tiered system (6×, 4×, then fixed values) ensures that brief segments receive disproportionately higher sampling rates while longer segments progressively approach the max_frames cap, optimizing the trade-off between detail and processing overhead.

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