How to Set a Lower Frame Cap in Claude-Video Using `--max-frames`

To set a lower frame cap in claude-video, pass the --max-frames flag followed by a positive integer to override the default budget limit and control exactly how many frames are extracted from your video.

The bradautomates/claude-video repository automatically limits frame extraction based on your selected detail mode, but the --max-frames option gives you precise manual control over this behavior when you need stricter limits.

How --max-frames Overrides Default Frame Caps

Claude-Video calculates a frame cap automatically from your --detail mode selection. For example, efficient mode caps extraction at 50 frames, while balanced mode allows up to 100 frames. The --max-frames argument bypasses these defaults and establishes a hard upper bound.

In skills/watch/scripts/watch.py, the flag is defined at lines 31-33 and validated at lines 74-79 to ensure you provide a positive integer. Once validated, your custom value replaces the automatically computed budget_cap that governs the frame-selection logic.

Implementation Across the Codebase

The --max-frames value flows through three critical files:

• watch.py: Parses the CLI argument and integrates it into the overall budget logic before calling extraction routines.
• frames.py: At lines 1010-1012, the low-level extraction script accepts this flag directly for standalone usage.
• config.py: Provides the default caps used when --max-frames is omitted.

Your specified limit is passed to the core extraction functions—including auto_fps, auto_fps_focus, extract_keyframes, and extract_scene_or_uniform—ensuring the total output never exceeds your cap.

Practical Command-Line Examples

Use --max-frames with any positive integer greater than zero to enforce strict limits.

Override Detail Mode Defaults

Limit extraction to 30 frames regardless of whether you selected efficient or balanced mode:

watch "https://www.youtube.com/watch?v=example" --max-frames 30

Combine with Specific Detail Settings

Use efficient mode but cap output at 20 frames instead of the default 50:

watch "my_video.mp4" --detail efficient --max-frames 20

Direct Script Execution

Invoke the underlying frames.py module directly for the same control:

python -m skills.watch.scripts.frames my_video.mp4 ./frames \
    --max-frames 15 --resolution 640

Validation Constraints

According to the source code in watch.py (lines 74-79), the --max-frames value must be a positive integer greater than zero. The CLI enforces this validation before processing begins. If you omit the flag, the system falls back to the defaults defined in config.frame_cap().

Summary

• --max-frames overrides automatic detail-based caps in claude-video with a user-defined hard limit.
• The value must be a positive integer greater than zero, enforced at argument parsing time.
• Implementation spans watch.py (CLI entry point), frames.py (extraction logic), and config.py (default values).
• The flag functions identically in both the watch command and direct frames.py script usage.
• Your specified limit applies to all frame extraction methods, including cue-frame timestamps.

Frequently Asked Questions

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

If you do not specify --max-frames, claude-video uses the default caps from config.frame_cap() based on your detail mode: 50 frames for efficient, 100 frames for balanced, and unlimited frames for token-burner or transcript modes.

Can I use --max-frames to extract more frames than the default cap?

Yes. While commonly used to lower the limit, you can specify any positive integer higher than the default to allow more frames than the selected detail mode would normally permit.

Does the frame cap include manually specified cue frames?

Yes. The --max-frames value represents the absolute upper bound for total frame output, encompassing both automatically selected frames and any specific cue-frame timestamps you request in your command.

Where is the --max-frames validation enforced in the source code?

The argument validation occurs in skills/watch/scripts/watch.py at lines 74-79, which verify that the input is a positive integer before the value is passed to the extraction functions in frames.py.

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