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

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. 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, 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 script serves as the primary entry point. It captures all command-line arguments and forwards them to the frames module. Within 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:

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

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. 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 using argparse.
• The entry point in 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 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. 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, 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 processes all inputs uniformly through the same FFmpeg pipeline.

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