# 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. Understand how it controls FPS calculation and frame extraction for your video processing needs.

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

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py). The implementation then evaluates whether to use the default or the override at lines 73-78:

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

```bash

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