How the --max-frames Option Overrides the Default Frame Cap in claude-video

The --max-frames option overrides the default frame cap by intercepting the mode-specific budget returned by frame_cap() and substituting the user-provided value, which then governs both the automatic FPS calculation and the frame extraction ceiling.

The claude-video repository provides a watch skill that processes video content using configurable detail modes. Each mode carries a built-in frame budget defined in config.py, but the --max-frames flag allows you to supersede these defaults and impose a hard limit on the number of frames extracted.

Default Frame Caps by Detail Mode

The watch skill determines its default frame budget based on the detail mode specified via the --detail flag. In skills/watch/scripts/config.py, the frame_cap() function (lines 65-74) returns mode-specific limits:

• efficient: 50 frames
• balanced: 100 frames
• token-burner: Unlimited (None)
• transcript: Unlimited (None)

When you run the command without --max-frames, the skill uses these preset values to constrain the extraction pipeline.

How the Override Logic Works

The CLI parser captures the --max-frames value in args.max_frames at line 31 of skills/watch/scripts/watch.py. The implementation then evaluates whether to use the default or the override at lines 73-78:

configured_cap = frame_cap(detail)                     # default based on mode

if args.max_frames is not None:
    max_frames = args.max_frames                        # <-- user-provided override

else:
    max_frames = configured_cap

This conditional ensures that any integer passed via --max-frames takes precedence over the mode-specific default. A subsequent sanity check at lines 78-79 validates that the value is positive, preventing zero or negative frame requests.

Where the Cap Gets Enforced

Once determined, the max_frames value propagates through two critical stages of the processing pipeline.

1. Budget for Automatic FPS Calculation

The cap feeds into the automatic FPS logic as a budget ceiling. The code uses budget_cap = max_frames if max_frames is not None else 100 to ensure that the calculated frames-per-second does not generate more candidate frames than the allowed maximum (around line 80). This budget applies to both auto_fps() and auto_fps_focus().

2. Frame Extraction Limits

The final max_frames value passes directly into the extraction functions: extract_keyframes(), extract_scene_or_uniform(), and extract_at_timestamps() (lines 84-92). These functions truncate their candidate lists to respect the limit, ensuring the output never exceeds your specified cap.

Practical Usage Examples

Override the default behavior using standard CLI syntax:

# Use the default cap for balanced mode (100 frames)

watch https://example.com/video.mp4 --detail balanced

# Override the balanced default and request only 40 frames

watch https://example.com/video.mp4 --detail balanced --max-frames 40

# Force a tight budget regardless of mode

watch https://example.com/video.mp4 --max-frames 25

After execution, the generated markdown report displays the "Frames" line, confirming the applied cap (e.g., "Frames: 40 selected … cap 40").

Summary

• The frame_cap() function in skills/watch/scripts/config.py defines mode-specific defaults: 50 for efficient, 100 for balanced, and unlimited for token-burner and transcript.
• The --max-frames argument captured in watch.py overrides these defaults when provided, taking precedence over the mode-specific configuration.
• The override value undergoes a positive-integer validation check before being applied to the pipeline.
• The final max_frames value constrains both the automatic FPS budget calculation (auto_fps() and auto_fps_focus()) and the downstream extraction functions.

Frequently Asked Questions

What happens if I omit the --max-frames flag?

If you do not specify --max-frames, the skill falls back to the default cap associated with your chosen detail mode. For efficient mode this means 50 frames, balanced means 100 frames, and both token-burner and transcript modes operate without limits.

Can I use --max-frames with any detail mode?

Yes. The --max-frames flag works with all detail modes including token-burner and transcript. Even though these modes default to unlimited frames, you can still impose a hard cap by providing a specific integer value.

What validation occurs when I set --max-frames?

The implementation enforces a sanity check that requires the value to be a positive integer. If you attempt to pass zero or a negative number, the validation logic in watch.py (lines 78-79) will reject the input.

How does --max-frames affect performance?

Setting a lower frame cap reduces the computational load and token consumption by limiting how many images get extracted and processed. The cap affects both the FPS calculation logic and the final extraction phase, ensuring the pipeline respects your specified budget throughout execution.

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