How the --max-frames Option Overrides the Default Frame Cap in Claude Video

The --max-frames CLI argument in Claude Video supersedes the default detail-level limits by directly replacing the value returned from the frame_cap() configuration function when a positive integer is supplied.

The bradautomates/claude-video repository provides a Python-based video analysis pipeline that automatically limits frame extraction to manage token consumption. Understanding precisely how the --max-frames option overrides the default frame cap enables users to fine-tune processing costs and analysis depth beyond the standard presets.

Understanding the Default Frame Cap Configuration

Before the override takes effect, the system establishes a baseline limit based on the selected processing detail level.

The frame_cap() Function in config.py

The frame_cap() function in skills/watch/scripts/config.py (lines 65–73) maps each detail mode to a specific maximum frame count:

• efficient → 50 frames
• balanced → 100 frames
• token-burner → No cap (None)
• transcript → No cap (None)

# skills/watch/scripts/config.py

def frame_cap(detail: str) -> int | None:
    if detail == "efficient":
        return 50
    if detail == "balanced":
        return 100
    if detail == "token-burner":
        return None
    if detail == "transcript":
        return None
    return 100

This function returns None for unlimited extraction or an integer for hard limits. The default detail level is typically balanced, which imposes a 100-frame cap unless modified.

How --max-frames Overrides the Default

The override mechanism operates in two stages: parsing the CLI argument and conditionally replacing the configured cap during execution initialization.

CLI Argument Definition

In skills/watch/scripts/watch.py (lines 30–33), argparse registers the optional flag with a default value of None:

# skills/watch/scripts/watch.py

ap.add_argument("--max-frames", type=int, default=None,
                help="Override frame cap")

When the user omits the flag, args.max_frames remains None, allowing the system to fall back to the detail-level default.

Override Logic and Validation

Following configuration loading, the script resolves the final frame budget (lines 71–78):

# skills/watch/scripts/watch.py

configured_cap = frame_cap(detail)
if args.max_frames is not None:
    max_frames = args.max_frames          # User-supplied value wins

else:
    max_frames = configured_cap           # Default based on detail

if max_frames is not None and max_frames < 1:
    raise SystemExit("--max-frames must be greater than zero")

Key behavior: If args.max_frames is not None, it unconditionally replaces the configured_cap regardless of the detail level. The script then validates that the resolved value is at least 1, aborting with a SystemExit if the user provides zero or negative numbers.

Propagation to Frame Extraction

The resolved max_frames (whether numeric or None) is passed to the extraction helpers in skills/watch/scripts/frames.py, such as auto_fps() and auto_fps_focus(), serving as the hard budget for frame generation throughout the pipeline.

Practical Usage Examples

Use the default cap for balanced processing (100 frames):

python -m skills.watch.scripts.watch https://www.youtube.com/watch?v=xyz123

Force a specific cap of 30 frames, overriding the detail-level default:

python -m skills.watch.scripts.watch https://www.youtube.com/watch?v=xyz123 --max-frames 30

To effectively disable the frame cap, rely on detail levels that return None rather than setting --max-frames to zero (which triggers a validation error):

python -m skills.watch.scripts.watch https://www.youtube.com/watch?v=xyz123 --detail token-burner

Summary

• The frame_cap() function in skills/watch/scripts/config.py establishes default limits (50, 100, or None) based on the selected detail level.
• The --max-frames argument in skills/watch/scripts/watch.py takes precedence over these defaults when explicitly provided with a positive integer.
• Values less than 1 trigger an immediate SystemExit with a validation error.
• The final resolved value propagates to skills/watch/scripts/frames.py, controlling the extraction budget for the entire analysis pipeline.

Frequently Asked Questions

What happens if I set --max-frames to 0?

The CLI aborts with a SystemExit error stating "--max-frames must be greater than zero". The validation logic explicitly rejects zero and negative integers to prevent invalid extraction budgets.

Does --max-frames work with all detail levels?

Yes. When provided, the --max-frames value unconditionally overrides the default cap associated with any detail level (efficient, balanced, token-burner, or transcript), forcing the pipeline to use your specified numeric limit instead.

How do I extract an unlimited number of frames?

You cannot achieve unlimited frames (None) using --max-frames, since the argument requires a positive integer. Instead, select a detail level that returns None from frame_cap(), such as token-burner or transcript, and omit the --max-frames flag entirely.

Where does the final max_frames value get consumed?

The resolved max_frames variable is passed to the frame extraction utilities in skills/watch/scripts/frames.py, specifically functions like auto_fps() and auto_fps_focus(), which use this budget to determine sampling rates and extraction intervals.

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