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

> Learn how the --max-frames option overrides Claude Video's default frame cap. Discover how to set custom limits for your video processing needs and enhance control over your workflows.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-08-01

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`)

```python

# 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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)** (lines 30–33), `argparse` registers the optional flag with a default value of `None`:

```python

# 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):

```python

# 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`](https://github.com/bradautomates/claude-video/blob/main/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):

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

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

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.