# How to Override the Default Frame Cap with `--max-frames` in Claude-Video

> Override Claude-Video's default frame cap by using the --max-frames flag. Learn how to set a custom extraction limit for your video processing needs with this simple command.

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

---

**Pass the `--max-frames <integer>` flag when invoking the watch skill to override the default extraction limit of 250 frames.**

The `bradautomates/claude-video` repository provides a video processing toolkit that caps frame extraction to keep processing efficient. By default, the system extracts a maximum of 250 frames per video, but you can override this limit directly from the command line to capture more or fewer frames as needed.

## Where the Frame Cap is Defined

The frame extraction logic resides in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). This script manages the conversion of video streams into discrete images using FFmpeg.

### The Default Limit in frames.py

Inside [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), the argument parser sets the default cap to **250** frames. This value is defined using Python’s `argparse` module to prevent excessive processing time when handling long video files. When no override is provided, the script automatically applies this limit to all extraction operations.

## How `--max-frames` Works

When you execute the watch command, your arguments flow through the entry point before reaching the extraction engine.

### Argument Parsing

The [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) script serves as the primary entry point. It captures all command-line arguments and forwards them to the frames module. Within [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py), `argparse` processes the `--max-frames` flag, replacing the default value of 250 with the user-specified integer.

### FFmpeg Integration

After parsing, the script injects the frame limit into the FFmpeg command sequence as the `-vframes` parameter (or equivalent frame-limiting argument). This instructs FFmpeg to halt extraction once the specified number of frames has been output, ensuring precise control over resource utilization.

## Usage Examples

Override the default frame cap directly from the terminal when processing videos:

```bash

# Use the default 250-frame limit

watch https://www.youtube.com/watch?v=example

# Extract up to 500 frames for detailed analysis

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

# Quick preview with only 50 frames

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

```

## Programmatic Usage

You can also invoke the functionality directly from Python when building automated workflows:

```python
from skills.watch.scripts.watch import main as watch_main

# Override the default frame cap programmatically

watch_main([
    "https://www.youtube.com/watch?v=example",
    "--max-frames", "400"
])

```

This method allows you to integrate frame extraction into larger applications while maintaining control over processing limits.

## Testing the Frame Cap Override

The repository includes validation for this functionality in [`tests/test_frames.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_frames.py). This test suite verifies that the `--max-frames` argument correctly overrides the default behavior and ensures the value is properly passed to the underlying FFmpeg command, preventing regression in future releases.

## Summary

- The default frame cap of **250** is hardcoded in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) using `argparse`.
- The entry point in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) forwards CLI flags to the frames module.
- Use `--max-frames <number>` to customize the extraction limit for specific use cases.
- The value is passed to FFmpeg as `-vframes` to control exactly how many frames are output.
- Functionality is validated in [`tests/test_frames.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_frames.py) to ensure reliable operation.

## Frequently Asked Questions

### What is the default frame cap in claude-video?

The default frame cap is **250 frames**, defined in the argument parser within [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). This limit ensures that processing long videos remains efficient and does not consume excessive computational resources.

### Can I extract all frames from a video by setting a high `--max-frames` value?

Yes, you can set `--max-frames` to a large number (such as 10000) to effectively extract every frame from shorter videos. Be cautious when processing high-FPS or long-duration content, as this will significantly increase processing time and storage requirements.

### Where is the `--max-frames` option documented?

The option is documented in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md), which defines the `/watch` slash command and lists all available CLI flags including their default values and usage examples.

### Does `--max-frames` work with local video files?

Yes, the `--max-frames` flag works with any video source supported by the watch skill, including local file paths, YouTube URLs, and other remote streams, because [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) processes all inputs uniformly through the same FFmpeg pipeline.