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

> Easily set a lower frame cap for claude-video using the --max-frames option. Control frame extraction by specifying your desired integer limit and override default budgets for precise control.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: performance
- Published: 2026-07-25

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/watch.py)**: Parses the CLI argument and integrates it into the overall budget logic before calling extraction routines.
- **[`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py)**: At lines 1010-1012, the low-level extraction script accepts this flag directly for standalone usage.
- **[`config.py`](https://github.com/bradautomates/claude-video/blob/main/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:

```bash
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:

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

```

### Direct Script Execution

Invoke the underlying [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) module directly for the same control:

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/watch.py) (CLI entry point), [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) (extraction logic), and [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) (default values).
- The flag functions identically in both the `watch` command and direct [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/frames.py).