How Focused Mode (--start/--end) Affects Frame Budgets in Claude-Video

Focused mode increases the frame budget for short video segments by switching from auto_fps to auto_fps_focus, which multiplies the target frame count by up to 6× for clips ≤5 seconds while respecting the MAX_FPS cap of 2.0.

The claude-video repository provides a watch skill that extracts video frames using an auto-scaled frames-per-second (FPS) algorithm to maintain a frame budget—the maximum number of JPEGs written for any analysis. When users supply --start and/or --end arguments, the system enters focused mode and recalculates this budget to provide denser coverage of the selected interval. This article examines exactly how the focused mode frame budget mechanism works in the source code.

What is Focused Mode?

Focused mode activates when the user "zooms in" on a specific sub-segment of the video using time-based arguments. Instead of distributing the frame budget across the entire video duration, the skill concentrates computational resources on the specified window, adjusting the frame extraction density algorithmically.

How Focused Mode Changes the Frame Budget Calculation

The frame budget determines the maximum number of JPEG frames the watch skill will extract. According to skills/watch/scripts/frames.py, focused mode triggers a four-step process that reallocates the budget toward the selected interval while maintaining hard caps.

Step 1: Detecting Focus Mode

The script evaluates whether to enter focused mode by checking for the presence of start or end timestamps at lines 30-32:

focused = start_sec is not None or end_sec is not None

When either variable is populated, the boolean focused becomes True, signaling that the user has requested a targeted extraction rather than a full-video scan.

Step 2: Selecting the FPS Function

Based on the focused flag, the code selects between two budget calculation strategies at lines 33-35:

• Full-video scan: Uses auto_fps for modest, evenly distributed coverage across the entire duration
• Focused scan: Uses auto_fps_focus for dense, targeted coverage of the sub-segment

Step 3: Computing a Denser Budget

The auto_fps_focus function (lines 41-59) implements a tiered multiplier system that increases the target frame count based on the duration of the selected clip:

• ≤ 5 seconds: Up to 6× the base FPS multiplier
• ≤ 15 seconds: Up to 4× the base FPS multiplier
• Maximum cap: MAX_FPS = 2.0 prevents the extraction rate from exceeding 2 frames per second

This ensures that short, focused clips receive significantly more frames than they would in a full-video scan. For example, a 4-second window that might generate 8 frames in standard mode can yield up to 24 frames in focused mode.

Step 4: Applying the Budget to Extraction

The computed fps and target values are passed to the extract() function (lines 39-44), which respects the max_frames parameter—the definitive budget ceiling. Even with focused mode's increased multipliers, the extraction cannot exceed the absolute maximum frame count defined by the system configuration.

Practical Impact on Frame Density

The difference between modes is substantial when analyzing short segments. A 4-second clip extracted in full-video mode generates approximately 8 frames (at 2 FPS), while the same clip in focused mode receives up to 24 frames (6× multiplier applied to the base calculation). This density ensures that rapid changes within the focused window are captured without increasing the processing burden for the entire video file.

Code Examples

The following commands demonstrate the practical difference between extraction modes:

# Full-video extraction (no focus)

# Uses auto_fps → ~2 fps for a 30-second clip (≈60 frames)

python -m skills.watch.scripts.frames video.mp4 out_dir

# Focused extraction on a 4-second window

# Uses auto_fps_focus → ~6 fps (≈24 frames) for the same 4s interval

python -m skills.watch.scripts.frames video.mp4 out_dir \
    --start 00:01:12 --end 00:01:16

The second command produces more frames per second inside the 4-second window because auto_fps_focus multiplies the target by up to 6 when the duration is ≤5 seconds.

Key Implementation Files

The focused mode frame budget logic is distributed across these critical files:

• skills/watch/scripts/frames.py: Contains the core logic for frame extraction, FPS selection via auto_fps_focus, and the MAX_FPS constant.
• skills/watch/scripts/watch.py: Entry point that parses CLI arguments and delegates to the frames module.
• tests/test_frames.py: Unit tests verifying the focused-mode budget behavior and multiplier calculations.

Summary

• Focused mode activates when --start or --end arguments are provided, setting focused = True in skills/watch/scripts/frames.py (lines 30-32).
• The system switches from auto_fps to auto_fps_focus, which applies multipliers up to 6× for short segments (≤5 seconds) and 4× for medium segments (≤15 seconds).
• The frame budget increases for the selected interval while respecting the MAX_FPS = 2.0 cap and absolute max_frames limits enforced by the extract() function.
• Short clips receive denser frame coverage (e.g., ~24 frames for 4 seconds vs. ~8 frames in standard mode) without affecting the full-video processing pipeline.

Frequently Asked Questions

What is the maximum frame rate in focused mode?

The MAX_FPS constant in skills/watch/scripts/frames.py caps the extraction rate at 2.0 frames per second, regardless of the multipliers applied by auto_fps_focus. This ensures that even with the 6× budget multiplier for clips ≤5 seconds, the system never exceeds 2 FPS.

How does the frame budget differ between full-video and focused extraction?

In full-video mode, auto_fps distributes a modest frame budget across the entire duration (e.g., ≤100 frames for a 10-minute video). In focused mode, auto_fps_focus concentrates a larger budget specifically into the selected sub-segment, yielding up to 6× more frames per second for short clips while maintaining the same absolute max_frames ceiling.

Can I exceed the maximum frame count using --start and --end?

No. The extract() function respects the max_frames parameter as an absolute limit. While focused mode increases the target density for your selected interval, the extraction process will stop if the computed frames would exceed the total budget cap defined by max_frames.

Where is the focused mode detection logic implemented?

The detection occurs at lines 30-32 of skills/watch/scripts/frames.py, where the code evaluates focused = start_sec is not None or end_sec is not None. This boolean then determines whether to invoke auto_fps_focus or auto_fps at lines 33-35.

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