How Focus Mode in claude-video Delivers Denser Frame Budgets for Targeted Analysis

Focus mode in claude-video allocates a higher frames-per-second density to user-specified time windows by switching from the generic auto_fps routine to the specialized auto_fps_focus function, which applies tighter sampling multipliers based on the effective duration of the selected clip.

The focus mode in claude-video (available at bradautomates/claude-video) allows you to isolate specific segments of a video using --start and --end timestamps. When activated, this mode redirects the frame-budget calculation through a specialized algorithm that concentrates sampling density inside your defined window rather than spreading it across the entire video length.

How Focus Mode Is Triggered

Focus mode activates when you provide either a --start or --end timestamp (or both) to the watch CLI. In skills/watch/scripts/watch.py (lines 53–57), the code evaluates these inputs to set a boolean flag:

# watch.py (simplified)

focused = start_sec is not None or end_sec is not None
effective_duration = end_sec - start_sec if focused else full_duration

Once focused evaluates to True, the script calculates the effective duration of your requested window rather than using the full video length. This shorter duration becomes the input for the denser budget algorithm.

The Denser Budget Calculation

The core difference lies in which auto-FPS function the system invokes. According to skills/watch/scripts/watch.py (lines 55–58), the logic branches based on the focused flag:

# Inside watch.py frame budget selection

if focused:
    fps, target = auto_fps_focus(effective_duration, max_frames=budget_cap)
else:
    fps, target = auto_fps(effective_duration, max_frames=budget_cap)

While the generic auto_fps distributes frames across the entire video, auto_fps_focus (defined in skills/watch/scripts/frames.py, lines 141–156) applies aggressive multipliers to short durations:

• ≤ 5 seconds: Target ≈ 6 × duration (e.g., 30 frames for a 5-second clip)
• ≤ 15 seconds: Target ≈ 4 × duration
• Longer windows: Falls back to the generic cap logic

This yields a significantly higher fps-to-duration ratio than the standard algorithm, which bases its calculations on the full video length.

Frame Extraction and Cap Management

After computing the target frame count, watch.py (lines 95–100) passes this budget to the extraction engines (extract_keyframes or extract_scene_or_uniform). The system reduces the cap only by the number of cue-frames (if specified), preserving the dense allocation for the focus window. The final output reflects this concentration:

[watch] extracting scene-aware frames over 00:30-01:00 (target 45, cap 80)…

Notice the target value (45) represents a much denser sampling than the default budget would allocate for a 30-second segment in a full-video analysis.

Practical Usage Examples

To analyze an entire video with standard frame distribution:

watch https://youtu.be/abc123 --detail balanced

To trigger focus mode and extract denser frames between 00:30 and 01:00:

watch https://youtu.be/abc123 --start 00:30 --end 01:00 --detail balanced

The Python implementation detail from skills/watch/scripts/frames.py shows the threshold logic:

def auto_fps_focus(duration_seconds: float, max_frames: int = 100) -> tuple[float, int]:
    if duration_seconds <= 5:
        target = min(max_frames, max(10, int(round(duration_seconds * 6))))
    elif duration_seconds <= 15:
        target = min(max_frames, max(30, int(round(duration_seconds * 4))))
    # Longer durations use standard allocation logic

    return _clamp_fps(target / duration_seconds, duration_seconds, max_frames)

Summary

• Focus mode activates via --start and --end flags, setting focused = True in watch.py.
• The system switches from auto_fps to auto_fps_focus, which resides in skills/watch/scripts/frames.py.
• Shorter focus windows trigger higher multipliers (6× for ≤5s, 4× for ≤15s), creating a denser frame budget.
• The calculated target preserves this density through the extraction pipeline, providing richer visual detail exactly where specified.

Frequently Asked Questions

What command-line flags activate focus mode in claude-video?

Focus mode activates when you provide either --start or --end arguments (or both) to the watch command. These timestamps can be in HH:MM:SS format, and their presence triggers the focused frame-budget calculation in skills/watch/scripts/watch.py.

How does auto_fps_focus differ from the standard auto_fps function?

The standard auto_fps calculates frame distribution based on the full video duration, while auto_fps_focus (defined in skills/watch/scripts/frames.py, lines 141–156) applies higher sampling multipliers to short durations—specifically 6× the duration for clips under 5 seconds and 4× for clips under 15 seconds.

Why does focus mode provide more frames per second than analyzing the full video?

Because auto_fps_focus receives the effective duration (the span between --start and --end) rather than the full video length. By dividing the frame budget by this smaller denominator and applying aggressive minimum thresholds, the function allocates more frames per second to the focused region.

Where is the frame budget cap defined in the claude-video source code?

The default detail caps that interact with the focus budget are defined in skills/watch/scripts/config.py, while the specific application of the cap occurs in skills/watch/scripts/watch.py (lines 95–100), where the target frame count is reduced only by cue-frame offsets before extraction.

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